Compare commits

...

4 Commits

Author SHA1 Message Date
姚章浩 4cb5110845 fix(version-history): 页面链接改走公网 origin(抓取仍走内网)+ tag 补链接
build / build (push) Successful in 1m1s
现象(主人反馈):点「查看提交」打开是空白页。原因:链接用的是**抓取用的内网地址**
(`http://192.168.50.223:3000/...`),内网外的浏览器到不了;而公网地址
`https://gitea.zheromiku.top/...` 实测 200。另外 tag 证据里**根本没有 url**,
页面渲染出空 `href`,点下去像"没反应"。

修复:

- 新增 `VERSION_HISTORY_LINK_ORIGIN`(页面链接 origin,公网;留空 = 与抓取 origin 相同):
  抓取仍匿名走内网白名单地址,**给人点的链接**用公网 origin 拼 —— 两者本就不该共用一个地址;
  校验必须是干净的 http(s) 绝对地址。
- tag 证据补 `url`(`<link origin>/<repo>/src/tag/<name>`),并在前端**没有链接就不渲染**该按钮。
- 测试:客户端(LinkOrigin 生效 / 未配时退回 / 非法拒绝)、规则(tag 链接写入证据 / 无基址不编链接)、
  前端(有链接才渲染「查看 tag」)。

验证:make verify 15/15;真实链路重同步后库里 commit_url = `https://gitea.zheromiku.top/...`(200)、
release_tags 带 url。
2026-10-14 11:06:13 +08:00
姚章浩 90db243a68 fix(web): 旧 index.html 的哈希资源回退到「上一版构建」,页面不再空白/裸奔
build / build (push) Successful in 56s
现象(主人反馈:页面**偶尔**变成"只有文字没样式"):旧入口 index.html 引用的是上一版的
`index-CddbQIqQ.js` / `index-DLg1Y9tN.css`,而新镜像里只剩当次构建的两个文件
⇒ JS 404 白屏、CSS 404 只有文字没样式。触发条件是"短时间内多次重建 web + CDN/浏览器还拿着旧入口"。

修复(三层,各管一段):

1. **入口不缓存**(上一笔已做):`index.html` → `no-cache, must-revalidate`,CDN/浏览器每次回源校验;
2. **旧哈希资源仍可取**(本笔):`/assets/` 未命中时先回退到只读挂载的
   `deploy/legacy-assets/assets`(**上一版构建**的资源),再 404 ⇒ 还持有旧入口的客户端
   不会因为一个文件 404 而白屏/裸奔;该目录由 `scripts/deploy-api-web.sh` 在**每次重建前**
   从"正在运行的那个镜像"里落盘(`LEGACY_ASSETS=` 会打在部署日志里),并加进 .gitignore;
3. **未命中不再回退成 HTML**:避免浏览器把 index.html 当 JS 执行报一堆语法错误。

验证:旧入口的两个引用 `assets/index-CddbQIqQ.js`、`assets/index-DLg1Y9tN.css` 现在都是 200
(旧客户端可用);当前入口的 `assets/index-Dbnd-DW-.js`、`assets/index-Bgkt4A1i.css` 也是 200;
不存在的文件名仍明确 404;`nginx -t` 通过;本机 8088 与公网入口 kg.zheromiku.top 一致;make verify 15/15。
2026-10-14 10:58:01 +08:00
姚章浩 062a3b3cb6 fix(web): index.html 不再被 CDN/浏览器缓存(否则页面停在旧构建上)
build / build (push) Successful in 55s
现象:p1 已上线新构建(容器内 bundle 是新的),但主人通过公网入口 kg.zheromiku.top 看到的
仍是旧界面(左侧菜单只有 4 项、没有「版本记录」)。实测:

- 公网入口 `/` 引用 `index-CddbQIqQ.js`(10-10 的旧包),而本机 8088 已引用 `index-Dbnd-DW-.js`;
- 带上缓存破坏参数再取同一个公网地址 ⇒ 立刻拿到新包;响应头有 `EO-Cache-Status`/`EO-LOG-UUID`
  ⇒ 中间是腾讯云 EdgeOne,把**旧 index.html** 缓存住了(浏览器同理:index.html 无缓存头时按启发式缓存)。
- 根因:`deploy/nginx.conf` 里对 `index.html` **完全没设缓存头**。

修复(只动静态入口的缓存语义,不改任何业务逻辑):

- `index.html`(含 SPA 深链回退):`Cache-Control: no-cache, must-revalidate` ⇒ 每次回源校验,
  CDN/浏览器不会再把入口钉在旧构建上;
- `/assets/`(带内容哈希):`public, max-age=31536000, immutable` 长缓存,换版本必然换文件名;
- `/assets/` 未命中明确 `404`,不再回退成 `index.html`(否则浏览器把 HTML 当 JS 执行,报一堆语法错误)。

验证:本机 8088 与公网入口 `kg.zheromiku.top` 的 index.html 都只发一条 `no-cache, must-revalidate`,
且公网入口已引用新包 `index-Dbnd-DW-.js`(其中含「版本记录」);`nginx -t` 通过;旧哈希资源 404、
SPA 深链仍 200。CHANGELOG 补 Fixed 条目。

⚠️ 本次是"新功能看起来没上线"的真实原因,已记入 deploy/nginx.conf 注释,避免复发。
2026-10-14 10:38:44 +08:00
姚章浩 4d43a9386a fix(version-history): tag 之前的提交不再被编号 + 部署脚本注入构建身份
build / build (push) Successful in 1m5s
真实数据发现(本机 p1 实例第一次同步后核对):
- **缺陷**:tag `v0.1.0` 之前的 20 个提交,提交内 CHANGELOG 顶部**也已经**是 0.1.0(旧分支遗留条目),
  而它们的祖先集合被那个**更晚才打**的 tag 全覆盖 ⇒ 按提交数算得 0 ⇒ 被错标成「0.1.0 开发版」。
  它们的正确判定是「历史提交」:那个 tag 是后来才打的,当时还没有发布基线。
- **修复**:基线 tag 必须是该提交的**祖先(或就是该提交)**,否则不给号;新增原因码
  `release_tag_created_later`(页面文案:'该版本是在更晚的提交上发布的 —— 这个提交当时还没有 tag')。
  回归用例两条:`TestDeriveVersionsDoesNotNumberCommitsThatPredateTheTag`、
  `TestDeriveVersionsSideBranchWithoutTagStaysHistorical`(不含 tag 的侧分支同样不给号)。
- **部署脚本注入构建身份**:`scripts/deploy-api-web.sh` 原先不传 `-ldflags -X`,产物 `CommitSHA=unknown`
  ⇒ 页面只能显示"当前运行版本未知"(契约上诚实,但没用)。现在按 `scripts/version.py --identity`
  (唯一来源,与 Makefile/CI 同规则)注入 VERSION/RELEASE_VERSION/BUILD_KIND/COMMITS_SINCE_RELEASE/
  COMMIT_SHA/BUILD_TIME;取不到身份**拒绝继续**(宁可不上线,也不上线一个认不出自己的产物),
  并在收尾核对注入的 SHA 真的进了产物。
- compose.yaml:把 VERSION_HISTORY_* 五项接进应用环境(api/worker 共享锚点),留空即未接线。

验证:真实仓库复验(114 条对账一致)⇒ 正式 1 / 开发 4 / 历史 109(原来错的 19 条现在都是
`release_tag_created_later`);p1 实例重新同步后当前快照分布一致,带号的记录只剩 1 正式 + 4 开发
(含真实存在的「同号不同 SHA」:950c1b4 与 3a1d32d 都是 0.1.1,各占一行);
make verify 15/15 success;前端 18 用例 + typecheck 通过。
2026-10-14 10:00:27 +08:00
18 changed files with 292 additions and 27 deletions
+3
View File
@@ -35,5 +35,8 @@ TEST_ACCEPTANCE_POLICY_VERSION=structural-v1
VERSION_HISTORY_GITEA_BASE_URL=
VERSION_HISTORY_REPO=Weknora/knowledge-governance
VERSION_HISTORY_ALLOWED_ORIGINS=
# 页面上的「查看提交 / 查看 tag」链接用哪个 origin —— 抓取可以走内网,但链接必须能被
# **点它的人**打开(否则点开是空白)。留空 = 与上面的抓取地址相同。
VERSION_HISTORY_LINK_ORIGIN=https://gitea.zheromiku.top
VERSION_HISTORY_HTTP_TIMEOUT=15s
VERSION_HISTORY_MAX_PAGES=200
+2
View File
@@ -43,3 +43,5 @@ backups/
.ci-remote-tags
.ci-commits-count
.ci-preview-url
# 上一版构建的静态资源(部署脚本落盘、只读挂载的运行时目录,不进 git)
deploy/legacy-assets/
+8
View File
@@ -9,6 +9,14 @@
- 新增迁移 `000046_version_history`(提交记录 + 同步状态):`commit_sha` 是唯一身份,**版本号不是唯一键** —— 两个提交算出同一个开发号时各占一行,用 SHA 区分。
- 「当前运行」只认运行产物注入的**完整 SHA 精确匹配**:匹配到就标该条;开发构建显式标注"开发构建";拿不到标识就显示"当前运行版本未知",**不拿最新 main 或最新 tag 顶替**;CI 成功不等于已部署。
### Fixed
- 前端入口与静态资源的缓存语义("新功能看起来没上线"与"页面偶尔裸奔/空白"的根因):
- `index.html` 此前**没有缓存头**,CDN/浏览器按启发式缓存它 ⇒ 页面会一直停在旧构建上(实测被腾讯云 EdgeOne 卡住:源站已是新包,公网入口仍发旧包)。现在 `index.html` 每次回源校验(`no-cache, must-revalidate`);
- 带内容哈希的 `/assets/` 长缓存(`immutable`),但**未命中时先回退到"上一版构建的资源"目录、再 404**(`deploy/legacy-assets` 由部署脚本在每次重建前落盘并只读挂载):CDN/浏览器仍持有旧 `index.html` 时,它引用的旧 JS/CSS 依旧能取到 ⇒ 不会出现"JS 404 白屏"或"CSS 404 只有文字没样式";
- 明确 404 时不再回退成 `index.html`(否则浏览器把 HTML 当 JS 执行,报一堆语法错误)。
- 「版本记录」页的链接改为**抓取与链接分离**:抓取仍走配置的(内网)地址,页面上的「查看提交 / 查看 tag」用 `VERSION_HISTORY_LINK_ORIGIN`(公网 origin)拼 —— 原先两者共用内网地址,内网外的浏览器点开是空白;另外 tag 记录原先不带链接(空 `href` 点下去没反应),现在补上链接、没有链接就不渲染该按钮。
### Security
- 版本记录同步**匿名只读**远端仓库(**不使用任何凭据**),来源限配置里批准的 origin 与固定仓库:拒绝任意 URL、拒绝跨主机重定向,单个响应设大小上限与超时、5xx/429 才有退避重试。
+1
View File
@@ -118,6 +118,7 @@ func workerHandlers(store *postgresstore.Store, config appconfig.Config) (map[st
client, err := versionhistory.NewGiteaClient(versionhistory.GiteaConfig{
BaseURL: config.VersionHistoryGiteaBaseURL,
AllowedBaseURLs: config.VersionHistoryAllowedOrigins,
LinkOrigin: config.VersionHistoryLinkOrigin,
Repo: config.VersionHistoryRepo,
Timeout: config.VersionHistoryHTTPTimeout,
})
+13
View File
@@ -40,6 +40,15 @@ services:
MINERU_BASE_URL: "${MINERU_BASE_URL:-}"
TEST_INTERNAL_WEKNORA_KB_ID: "${TEST_INTERNAL_WEKNORA_KB_ID:-1b52c140-2e18-4676-afc5-4c7d8d190a8c}"
TEST_EXTERNAL_WEKNORA_KB_ID: "${TEST_EXTERNAL_WEKNORA_KB_ID:-fd7db6aa-763a-46f1-84d2-ecc7c952a5ea}"
# 「版本记录」页:**匿名只读**远端仓库的提交与 tag(不使用任何凭据)。
# 留空 = 未接线(页面降级、同步入口不可用);来源只允许下面批准的 origin 与固定仓库。
VERSION_HISTORY_GITEA_BASE_URL: "${VERSION_HISTORY_GITEA_BASE_URL:-}"
VERSION_HISTORY_REPO: "${VERSION_HISTORY_REPO:-Weknora/knowledge-governance}"
VERSION_HISTORY_ALLOWED_ORIGINS: "${VERSION_HISTORY_ALLOWED_ORIGINS:-}"
# 页面链接用的 origin(给内网外的浏览器点开);留空 = 与抓取 origin 相同。
VERSION_HISTORY_LINK_ORIGIN: "${VERSION_HISTORY_LINK_ORIGIN:-}"
VERSION_HISTORY_HTTP_TIMEOUT: "${VERSION_HISTORY_HTTP_TIMEOUT:-15s}"
VERSION_HISTORY_MAX_PAGES: "${VERSION_HISTORY_MAX_PAGES:-200}"
# P10 readiness probe reads the routing KB with the same scoped key.
TEST_WEKNORA_API_KEY_FILE: /run/secrets/test_weknora_api_key
TEST_WEKNORA_ALLOW_DOCKER_HTTP: "${TEST_WEKNORA_ALLOW_DOCKER_HTTP:-false}"
@@ -204,6 +213,10 @@ services:
api:
condition: service_healthy
read_only: true
volumes:
# 上一版构建的静态资源(只读,由部署脚本落盘):CDN/浏览器可能还持有旧 index.html,
# 让它的旧哈希引用不至于 404 —— 否则页面会空白或"只有文字没样式"。
- ./deploy/legacy-assets:/usr/share/nginx/legacy:ro
tmpfs:
- /tmp
- /var/cache/nginx
+25
View File
@@ -25,7 +25,32 @@ server {
proxy_set_header Host $host;
}
# 带内容哈希的构建产物:可以长期缓存(换版本必然换文件名);旧哈希文件已被新构建替换
# ⇒ 明确 404,不要回退成 index.html(否则浏览器把 HTML 当 JS 执行,报一堆语法错误)。
location /assets/ {
expires 1y;
add_header Cache-Control "public, max-age=31536000, immutable";
# 当前构建里没有再找**上一版构建**的资源:CDN/浏览器可能还持有旧 index.html,
# 它引用的旧哈希文件若直接 404,页面就会空白或"裸奔"(只有文字没样式)。
# 旧目录由部署脚本在每次重建前落盘(deploy/legacy-assets,只读挂载)。
try_files $uri @legacy;
}
location @legacy {
root /usr/share/nginx/legacy;
try_files $uri =404;
}
# ⚠️ index.html(含 SPA 深链回退)**必须每次回源校验**:它引用的是带哈希的 JS 文件名,
# 一旦被 CDN/浏览器缓存住,页面就一直停在旧构建上(看着像"新功能没上线")。
# 2026-10-14 实测被腾讯云 EdgeOne 缓存卡住过一次:源站已是新包,公网入口仍发旧包。
location = /index.html {
# 只发一条 Cache-Control(`expires -1` 会再发一条,CDN 读到哪条说不准)。
add_header Cache-Control "no-cache, must-revalidate" always;
}
location / {
try_files $uri $uri/ /index.html;
add_header Cache-Control "no-cache, must-revalidate" always;
}
}
+11 -2
View File
@@ -67,8 +67,11 @@ type Config struct {
VersionHistoryGiteaBaseURL string
VersionHistoryRepo string
VersionHistoryAllowedOrigins []string
VersionHistoryHTTPTimeout time.Duration
VersionHistoryMaxPages int
// VersionHistoryLinkOrigin 是**页面链接**用的 origin(给内网外的浏览器点开),
// 留空即与抓取 origin 相同。只用于拼展示链接,不参与任何请求。
VersionHistoryLinkOrigin string
VersionHistoryHTTPTimeout time.Duration
VersionHistoryMaxPages int
}
func Load(getenv func(string) string) (Config, error) {
@@ -113,6 +116,7 @@ func Load(getenv func(string) string) (Config, error) {
VersionHistoryGiteaBaseURL: strings.TrimSpace(getenv("VERSION_HISTORY_GITEA_BASE_URL")),
VersionHistoryRepo: valueOrDefault(strings.TrimSpace(getenv("VERSION_HISTORY_REPO")), "Weknora/knowledge-governance"),
VersionHistoryAllowedOrigins: splitOrigins(getenv("VERSION_HISTORY_ALLOWED_ORIGINS")),
VersionHistoryLinkOrigin: strings.TrimSpace(getenv("VERSION_HISTORY_LINK_ORIGIN")),
VersionHistoryHTTPTimeout: 15 * time.Second,
VersionHistoryMaxPages: valueOrDefaultInt(getenv("VERSION_HISTORY_MAX_PAGES"), 200),
}
@@ -215,6 +219,11 @@ func Load(getenv func(string) string) (Config, error) {
if strings.Count(config.VersionHistoryRepo, "/") != 1 {
return Config{}, errors.New("VERSION_HISTORY_REPO 必须是 owner/name 形式")
}
if config.VersionHistoryLinkOrigin != "" {
if err := validateHTTPBaseURL(config.VersionHistoryLinkOrigin); err != nil {
return Config{}, fmt.Errorf("VERSION_HISTORY_LINK_ORIGIN: %w", err)
}
}
}
if config.TestWeKnoraHTTPTimeout, err = durationOrDefault(getenv("TEST_WEKNORA_HTTP_TIMEOUT"), config.TestWeKnoraHTTPTimeout); err != nil {
return Config{}, fmt.Errorf("TEST_WEKNORA_HTTP_TIMEOUT: %w", err)
+3
View File
@@ -34,6 +34,9 @@ const (
ReasonNoBaseline = "no_baseline"
// ReasonIncompleteGraph:提交图不完整(检出被截断)⇒ 提交数算不准 ⇒ 宁可不给号。
ReasonIncompleteGraph = "shallow_or_incomplete_graph"
// ReasonTagCreatedLater:该版本号对应的 tag 是在**更晚的提交**上打的(不在这个提交的历史里)
// ⇒ 这个提交当时还没有发布基线,不能拿"后来才有的 tag"给它编号。
ReasonTagCreatedLater = "release_tag_created_later"
)
// versionHistorySemver 只认三段十进制、无前导零(与 scripts/check_changelog.py 同口径)。
+24 -6
View File
@@ -15,8 +15,12 @@ import (
// GiteaConfig 是只读客户端的配置。**只用匿名请求**:本客户端不会携带任何凭据,
// 也不接受调用方传入任意 URL —— base 必须在白名单里,仓库只允许配置的那一个。
type GiteaConfig struct {
BaseURL string
AllowedBaseURLs []string
BaseURL string
AllowedBaseURLs []string
// LinkOrigin 是**给人看的链接**用的 origin(例如公网 https://gitea.example)。
// 抓取用内网地址、点链接的人在内网外 —— 两者必须能分开,否则页面上的链接打不开。
// 留空则与 BaseURL 相同。它只用于拼展示链接,不参与任何请求。
LinkOrigin string
Repo string
HTTPClient *http.Client
Timeout time.Duration
@@ -29,6 +33,7 @@ type GiteaConfig struct {
// GiteaClient 只读地访问 Gitea 的提交、tag 与仓库内文件。
type GiteaClient struct {
baseURL *url.URL
linkOrigin string
repo string
client *http.Client
maxBytes int64
@@ -98,16 +103,29 @@ func NewGiteaClient(config GiteaConfig) (*GiteaClient, error) {
if sleep == nil {
sleep = time.Sleep
}
return &GiteaClient{baseURL: base, repo: repo, client: &sameHost, maxBytes: maxBytes,
maxRetries: retries, sleep: sleep, pageSize: pageSize}, nil
linkOrigin := strings.TrimRight(strings.TrimSpace(config.LinkOrigin), "/")
if linkOrigin == "" {
linkOrigin = strings.TrimRight(base.String(), "/")
} else if parsed, perr := url.Parse(linkOrigin); perr != nil || parsed.Host == "" ||
(parsed.Scheme != "http" && parsed.Scheme != "https") {
return nil, fmt.Errorf("版本记录:链接 origin %q 非法(必须是 http(s) 绝对地址)", config.LinkOrigin)
}
return &GiteaClient{baseURL: base, linkOrigin: linkOrigin, repo: repo, client: &sameHost,
maxBytes: maxBytes, maxRetries: retries, sleep: sleep, pageSize: pageSize}, nil
}
// PageSize 是抓取页大小(外层据此做完整性对账)。
func (c *GiteaClient) PageSize() int { return c.pageSize }
// CommitURLBase 给记录页拼提交链接用(白名单 origin + 固定仓库,不接受外部传入)。
// CommitURLBase 给记录页拼提交链接用(**给人看的** origin + 固定仓库,不接受外部传入)。
// 抓取走内网、链接走公网 —— 两者分开,页面上的链接才点得开。
func (c *GiteaClient) CommitURLBase() string {
return strings.TrimRight(c.baseURL.String(), "/") + "/" + c.repo + giteaCommitURLSuffix
return c.linkOrigin + "/" + c.repo + giteaCommitURLSuffix
}
// TagURLBase 给记录页拼 tag 链接用(`<link origin>/<repo>/src/tag/`)。
func (c *GiteaClient) TagURLBase() string {
return c.linkOrigin + "/" + c.repo + "/src/tag/"
}
func (c *GiteaClient) apiURL(path string, query url.Values) string {
+29
View File
@@ -28,6 +28,35 @@ func validConfig(base string) GiteaConfig {
Sleep: func(time.Duration) {}, MaxRetries: 2, PageSize: 50}
}
func TestGiteaClientUsesSeparateLinkOriginForHumanLinks(t *testing.T) {
// 抓取走内网、链接走公网:页面上的链接必须用公网 origin,否则点开是空白。
config := validConfig("http://192.168.50.223:3000")
config.LinkOrigin = "https://gitea.zheromiku.top/"
client, err := NewGiteaClient(config)
if err != nil {
t.Fatalf("构造客户端失败:%v", err)
}
if got := client.CommitURLBase(); got != "https://gitea.zheromiku.top/Weknora/knowledge-governance/commit/" {
t.Fatalf("提交链接基址 = %q(必须用公网 origin)", got)
}
if got := client.TagURLBase(); got != "https://gitea.zheromiku.top/Weknora/knowledge-governance/src/tag/" {
t.Fatalf("tag 链接基址 = %q", got)
}
// 不配 LinkOrigin ⇒ 退回抓取 origin(内网场景仍然一致)
fallback, err := NewGiteaClient(validConfig("http://192.168.50.223:3000"))
if err != nil {
t.Fatalf("构造客户端失败:%v", err)
}
if !strings.HasPrefix(fallback.CommitURLBase(), "http://192.168.50.223:3000/") {
t.Fatalf("未配 LinkOrigin 时应退回抓取 origin:%q", fallback.CommitURLBase())
}
bad := validConfig("http://192.168.50.223:3000")
bad.LinkOrigin = "ftp://nope"
if _, err := NewGiteaClient(bad); err == nil {
t.Fatal("非 http(s) 的链接 origin 必须拒绝")
}
}
func TestGiteaClientRejectsNonWhitelistedOriginAndBadRepo(t *testing.T) {
if _, err := NewGiteaClient(GiteaConfig{BaseURL: "http://evil.example.com",
AllowedBaseURLs: []string{"http://192.168.50.223:3000"}, Repo: "a/b"}); err == nil {
+30 -12
View File
@@ -38,6 +38,7 @@ type ChangelogSource func(sha string) (string, error)
type DeriveInput struct {
RepoKey string
CommitURLBase string // 形如 "<origin>/<owner>/<repo>/commit/",由配置拼好,不接受外部传入
TagURLBase string // 形如 "<origin>/<owner>/<repo>/src/tag/";空则不下发 tag 链接
Commits []RawCommit
Tags []RawTag
Changelog ChangelogSource
@@ -124,37 +125,54 @@ func DeriveVersions(in DeriveInput) DeriveResult {
baseTagName := ""
var sinceBase *int
tagCreatedLater := false
if governance.SemverValid(top) {
candidate := "v" + top
if base, exists := tagByName[candidate]; exists {
if !graphComplete {
own, ownKnown := ancestors[commit.SHA]
_, tagIsAncestor := own[base.TargetSHA]
switch {
case !graphComplete:
// tag 存在但图不完整 ⇒ 不给号(宁可没号,也不报错号)
baseTagName = candidate
} else if baseSet, ok := ancestors[base.TargetSHA]; ok {
if own, ok2 := ancestors[commit.SHA]; ok2 {
count := 0
for item := range own {
if _, inBase := baseSet[item]; !inBase {
count++
}
case !ownKnown:
// 连自己的祖先都给不出 ⇒ 不给号
case !tagIsAncestor:
// **该 tag 是更晚才打在这个提交之后的**:这个提交当时还没有发布基线。
// (提交数在这里算会得到 0 —— 因为它的祖先全被那个更晚的 tag 覆盖 —— 拿它编号是错的。)
tagCreatedLater = true
default:
baseSet := ancestors[base.TargetSHA]
count := 0
for item := range own {
if _, inBase := baseSet[item]; !inBase {
count++
}
baseTagName = candidate
sinceBase = &count
}
baseTagName = candidate
sinceBase = &count
}
}
}
evidenceTags := make([]governance.VersionTagEvidence, 0, len(tagsByTarget[commit.SHA]))
for _, tag := range tagsByTarget[commit.SHA] {
url := ""
if in.TagURLBase != "" {
url = in.TagURLBase + tag.Name
}
evidenceTags = append(evidenceTags, governance.VersionTagEvidence{
Name: tag.Name, TagSHA: tag.TagSHA, Annotated: tag.Annotated})
Name: tag.Name, TagSHA: tag.TagSHA, Annotated: tag.Annotated, URL: url})
}
sort.Slice(evidenceTags, func(i, j int) bool { return evidenceTags[i].Name < evidenceTags[j].Name })
label, state, kind, evidence := governance.DecideVersion(top, evidenceTags, baseTagName, sinceBase)
if label == "" && !graphComplete {
switch {
case label != "":
case !graphComplete:
evidence.Reason = governance.ReasonIncompleteGraph
case tagCreatedLater:
evidence.Reason = governance.ReasonTagCreatedLater
}
record := governance.VersionHistoryCommit{
RepoKey: in.RepoKey,
+67
View File
@@ -177,6 +177,25 @@ func TestDeriveVersionsPicksUpTagAddedAfterwards(t *testing.T) {
}
}
func TestDeriveVersionsFillsTagLinksForHumans(t *testing.T) {
commits := []RawCommit{commit("A", nil, 1)}
tags := []RawTag{{Name: "v0.1.0", TargetSHA: "A", Annotated: true}}
derived := DeriveVersions(DeriveInput{RepoKey: "repo", Commits: commits, Tags: tags,
CommitURLBase: "https://gitea.example/o/r/commit/",
TagURLBase: "https://gitea.example/o/r/src/tag/",
Changelog: readerFor(map[string]string{"A": "0.1.0"})})
record := find(t, derived.Records, "A")
if len(record.ReleaseTags) != 1 || record.ReleaseTags[0].URL != "https://gitea.example/o/r/src/tag/v0.1.0" {
t.Fatalf("tag 必须带可点的链接:%+v", record.ReleaseTags)
}
// 不给 TagURLBase ⇒ 不下发链接(页面据此不渲染空的 tag 链接)
bare := DeriveVersions(DeriveInput{RepoKey: "repo", Commits: commits, Tags: tags,
Changelog: readerFor(map[string]string{"A": "0.1.0"})})
if url := find(t, bare.Records, "A").ReleaseTags[0].URL; url != "" {
t.Fatalf("没有基址时不该编链接:%q", url)
}
}
func TestDeriveVersionsSortsDeterministicallyForPaging(t *testing.T) {
sameTime := at(9)
commits := []RawCommit{
@@ -193,3 +212,51 @@ func TestDeriveVersionsSortsDeterministicallyForPaging(t *testing.T) {
}
}
}
// 回归用例(真实数据发现):tag **更晚**才在链尾打上时,tag 之前那些「提交内 CHANGELOG 顶部
// 已经写着 0.1.0」的提交**不能**被算成 0.1.0 开发版 —— 它们的祖先集合全被那个更晚的 tag 覆盖,
// 按提交数会得到 0。正确结果:历史提交 + 原因 release_tag_created_later。
func TestDeriveVersionsDoesNotNumberCommitsThatPredateTheTag(t *testing.T) {
commits := []RawCommit{
commit("A", nil, 1), commit("B", []string{"A"}, 2),
commit("C", []string{"B"}, 3), commit("D", []string{"C"}, 4),
}
// tag 打在 C 上;A、B 的 CHANGELOG 顶部**也已经**是 0.1.0(旧分支遗留的条目)
tags := []RawTag{{Name: "v0.1.0", TargetSHA: "C", Annotated: true}}
top := map[string]string{"A": "0.1.0", "B": "0.1.0", "C": "0.1.0", "D": "0.1.0"}
result := DeriveVersions(DeriveInput{RepoKey: "repo", Commits: commits, Tags: tags, Changelog: readerFor(top)})
for _, sha := range []string{"A", "B"} {
record := find(t, result.Records, sha)
if record.VersionLabel != "" || record.RecordKind != governance.RecordKindHistorical {
t.Fatalf("tag 之前的提交 %s 不许编号:%+v", sha, record)
}
if record.VersionEvidence.Reason != governance.ReasonTagCreatedLater {
t.Fatalf("提交 %s 的原因码 = %q,期望 %q", sha, record.VersionEvidence.Reason, governance.ReasonTagCreatedLater)
}
}
if release := find(t, result.Records, "C"); release.RecordKind != governance.RecordKindRelease || release.VersionLabel != "0.1.0" {
t.Fatalf("tag 指向的提交才是正式版本:%+v", release)
}
if after := find(t, result.Records, "D"); after.VersionLabel != "0.1.1" {
t.Fatalf("tag 之后的提交才是开发号:%+v", after)
}
}
// 侧分支(不含 tag 的那条线)同样不给号。
func TestDeriveVersionsSideBranchWithoutTagStaysHistorical(t *testing.T) {
commits := []RawCommit{
commit("A", nil, 1), commit("B", []string{"A"}, 2), commit("T", []string{"B"}, 3),
commit("S", []string{"A"}, 4), // 从 A 分出去、不含 tag 的侧分支
commit("M", []string{"T", "S"}, 5), // 合并回主干
}
tags := []RawTag{{Name: "v0.1.0", TargetSHA: "T", Annotated: true}}
top := map[string]string{"A": "0.1.0", "B": "0.1.0", "T": "0.1.0", "S": "0.1.0", "M": "0.1.0"}
result := DeriveVersions(DeriveInput{RepoKey: "repo", Commits: commits, Tags: tags, Changelog: readerFor(top)})
if side := find(t, result.Records, "S"); side.VersionLabel != "" {
t.Fatalf("不含 tag 的侧分支提交不许编号:%+v", side)
}
if merge := find(t, result.Records, "M"); merge.VersionLabel != "0.1.2" {
t.Fatalf("合并提交含 tag 祖先 ⇒ 按图算号:%+v", merge)
}
}
+4 -1
View File
@@ -104,6 +104,8 @@ type Source interface {
CommitURLBase() string
ListCommits(ctx context.Context, page, limit int) ([]RawCommit, int, error)
ListTags(ctx context.Context) ([]RawTag, error)
// TagURLBase 是 tag 链接的基址(给人看的 origin,可能与抓取 origin 不同)。
TagURLBase() string
ReadFile(ctx context.Context, sha, path string) (string, error)
// BranchHeadSHA 读分支 HEAD;读不到不算致命(退回"提交列表里最新的那条")。
BranchHeadSHA(ctx context.Context, branch string) (string, error)
@@ -203,7 +205,8 @@ func (s *Syncer) Sync(ctx context.Context, jobID, triggeredBy string) (governanc
}
derived := DeriveVersions(DeriveInput{RepoKey: s.repoKey, CommitURLBase: s.source.CommitURLBase(),
Commits: commits, Tags: tags, SnapshotID: runID,
TagURLBase: s.source.TagURLBase(),
Commits: commits, Tags: tags, SnapshotID: runID,
Changelog: func(sha string) (string, error) {
return s.source.ReadFile(ctx, sha, s.changelog)
}})
+4
View File
@@ -27,6 +27,10 @@ func (f *fakeSource) CommitURLBase() string {
return "http://gitea.test/Weknora/knowledge-governance/commit/"
}
func (f *fakeSource) TagURLBase() string {
return "http://gitea.test/Weknora/knowledge-governance/src/tag/"
}
func (f *fakeSource) ListCommits(_ context.Context, page, limit int) ([]RawCommit, int, error) {
f.listCalls++
if f.commitsErr != nil {
+46 -1
View File
@@ -9,8 +9,46 @@ echo "=== 1. 打回滚标签 ($TS)"
docker tag knowledge-governance-p1-api:latest "knowledge-governance-p1-api:rollback-$TS" || exit 1
docker tag knowledge-governance-p1-web:latest "knowledge-governance-p1-web:rollback-$TS" || exit 1
echo "=== 1b. 构建身份(构建期注入:页面「当前运行」只认产物里的完整 SHA 精确匹配)"
# 唯一来源是 scripts/version.py --identity(与 Makefile、CI 同一份规则):不注入 ⇒ 页面只能显示"未知"。
IDENTITY_ARGS=()
while IFS= read -r line; do IDENTITY_ARGS+=("$line"); done < <(python3 scripts/version.py --identity 2>/dev/null | python3 -c '
import json, sys
try:
d = json.load(sys.stdin)
except Exception:
sys.exit(0)
release = d.get("release_version") or ""
count = d.get("commits_since_release")
print("--build-arg=VERSION=" + (release or "dev"))
print("--build-arg=RELEASE_VERSION=" + release)
print("--build-arg=BUILD_KIND=" + (d.get("build_kind") or "development"))
print("--build-arg=COMMITS_SINCE_RELEASE=" + ("" if count is None else str(count)))
print("--build-arg=COMMIT_SHA=" + (d.get("commit_sha") or "unknown"))
print("--build-arg=BUILD_TIME=" + (d.get("built_at") or "unknown"))
')
if [ "${#IDENTITY_ARGS[@]}" -lt 6 ]; then
echo "IDENTITY_UNAVAILABLE"
echo " 取不到构建身份(scripts/version.py --identity 失败)⇒ 拒绝继续:"
echo " 否则构建出来的产物无法被「版本记录」页识别成「当前运行」,只会显示未知。"
exit 1
fi
printf ' %s\n' "${IDENTITY_ARGS[@]}"
echo "=== 1c. 保留上一版构建的静态资源(CDN/浏览器可能还持有旧 index.html)"
# 只保留**当前正在跑的那一版**:旧 index.html 的旧哈希引用仍能取到文件,
# 页面不会因为某个 JS/CSS 404 而空白或"裸奔"。目录只读挂载进 web 容器。
LEGACY_DIR="deploy/legacy-assets"
PREV_WEB_IMAGE=$(docker inspect -f '{{.Image}}' knowledge-governance-p1-web-1 2>/dev/null || true)
mkdir -p "$LEGACY_DIR/assets" && chmod 777 "$LEGACY_DIR" "$LEGACY_DIR/assets"
if [ -n "$PREV_WEB_IMAGE" ]; then
docker run --rm --user 0 --entrypoint sh -v "$PWD/$LEGACY_DIR:/out" "$PREV_WEB_IMAGE" \
-c 'cp -a /usr/share/nginx/html/assets/. /out/assets/ 2>/dev/null || true' >/dev/null 2>&1 || true
echo " LEGACY_ASSETS=$(ls -1 "$LEGACY_DIR/assets" 2>/dev/null | tr '\n' ' ')"
fi
echo "=== 2. 构建 api"
docker build --network host "${PROXY_ARGS[@]}" -f Dockerfile -t knowledge-governance-p1-api:latest . || { echo "API_BUILD_FAILED"; exit 1; }
docker build --network host "${PROXY_ARGS[@]}" "${IDENTITY_ARGS[@]}" -f Dockerfile -t knowledge-governance-p1-api:latest . || { echo "API_BUILD_FAILED"; exit 1; }
echo "=== 3. 构建 web"
docker build --network host "${PROXY_ARGS[@]}" -f Dockerfile.web -t knowledge-governance-p1-web:latest . || { echo "WEB_BUILD_FAILED"; exit 1; }
@@ -47,4 +85,11 @@ echo "=== 7b. 生产门禁状态(重建后必须与预期一致)"
docker exec knowledge-governance-p1-api-1 sh -lc 'for v in PRODUCTION_RELEASE_REQUESTS_ENABLED PRODUCTION_BACKUP_RESTORE_VERIFIED; do eval "val=\$$v"; echo "$v=${val:-<empty>}"; done'
echo "=== 8. 新包"
docker exec knowledge-governance-p1-web-1 sh -lc 'grep -o "index-[A-Za-z0-9_-]*\.js" /usr/share/nginx/html/index.html | head -1'
echo "=== 9. 构建身份是否真的进了产物(页面据此判「当前运行」)"
INJECTED=$(printf '%s\n' "${IDENTITY_ARGS[@]}" | sed -n 's/^--build-arg=COMMIT_SHA=//p')
if docker exec knowledge-governance-p1-api-1 sh -lc "strings /app/api | grep -q '$INJECTED'"; then
echo "INJECTED_COMMIT_SHA=$INJECTED(已进 api 产物)"
else
echo "INJECTION_MISSING(产物里没有 $INJECTED —— 页面会显示当前运行未知)"
fi
echo "DONE"
+13
View File
@@ -186,6 +186,19 @@ describe('VersionHistoryView', () => {
expect(html).not.toContain('同步记录</button>')
})
it('never renders a tag link without a URL (an empty href looks broken)', () => {
const withURL = render()
expect(withURL).toContain('查看 tag v0.1.0')
expect(withURL).toContain('https://gitea.example/Weknora/knowledge-governance/src/tag/v0.1.0')
const withoutURL = render({
page: {
...page,
items: [{ ...releaseItem, release_tags: [{ name: 'v0.1.0', url: '' }] }],
},
})
expect(withoutURL).not.toContain('查看 tag')
})
it('keeps mobile single-column rules so nothing overflows horizontally', () => {
const css = readFileSync(new URL('./versionHistory.css', import.meta.url), 'utf8')
expect(css).toMatch(/@media \(max-width: 760px\)[\s\S]*?\.version-history[\s\S]*?overflow-wrap:\s*anywhere/)
+8 -5
View File
@@ -197,11 +197,14 @@ function TimelineEntry({
查看提交
</a>
) : null}
{item.release_tags.map((tag) => (
<a key={tag.name} href={tag.url} target="_blank" rel="noreferrer noopener">
查看 tag {tag.name}
</a>
))}
{/* 没有链接就不渲染:空 href 点下去像"没反应/空白",比不显示更糟 */}
{item.release_tags
.filter((tag) => tag.url)
.map((tag) => (
<a key={tag.name} href={tag.url} target="_blank" rel="noreferrer noopener">
查看 tag {tag.name}
</a>
))}
</div>
</li>
)
+1
View File
@@ -85,6 +85,7 @@ export const reasonLabels: Record<string, string> = {
no_release_tag_for_commit: '没有指向该提交的正式 tag',
no_baseline: '找不到可核验的发布基线(该版本没有对应的 tag)',
shallow_or_incomplete_graph: '提交图不完整(检出被截断),提交数算不准',
release_tag_created_later: '该版本是在更晚的提交上发布的 —— 这个提交当时还没有 tag',
}
export const reasonLabel = (reason: string): string => reasonLabels[reason] ?? '版本号未能核验'