Files
knowledge-governance/CHANGELOG.md
T
姚章浩 062a3b3cb6
build / build (push) Successful in 55s
fix(web): index.html 不再被 CDN/浏览器缓存(否则页面停在旧构建上)
现象: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

5.8 KiB
Raw Blame History

Changelog

[Unreleased]

Added

  • 「版本记录」页(一级菜单第 5 项):只读时间线追踪远端 main 可达的全部提交(含合并提交与已并入 main 的侧分支提交),按提交时间倒序显示标题/正文、[正式版本] / [开发版本] / [历史提交] 徽标、短 SHA、提交内变更记录与 [查看提交]/[查看 tag];支持「全部 / 正式 / 开发 / 历史」筛选与游标翻页,窄屏单列。
  • 新增只读接口 GET /api/v1/build-info(当前运行产物的构建身份)、GET /api/v1/version-history(快照游标分页,不返回伪造的 total)、POST /api/v1/version-history/sync(仅管理员手动同步,并发同步复用同一作业)。
  • 新增迁移 000046_version_history(提交记录 + 同步状态):commit_sha 是唯一身份,版本号不是唯一键 —— 两个提交算出同一个开发号时各占一行,用 SHA 区分。
  • 「当前运行」只认运行产物注入的完整 SHA 精确匹配:匹配到就标该条;开发构建显式标注"开发构建";拿不到标识就显示"当前运行版本未知",不拿最新 main 或最新 tag 顶替;CI 成功不等于已部署。

Fixed

  • 前端入口的缓存策略:index.html 此前没有缓存头,CDN/浏览器会启发式缓存它,于是页面会一直停在旧构建上(实测被腾讯云 EdgeOne 卡住:源站已是新包,公网入口仍发旧包,看起来像"新菜单/新页面没上线")。现在 index.html 每次回源校验(no-cache, must-revalidate)、带内容哈希的 /assets/ 长缓存(immutable),旧哈希资源明确 404 而不是回退成 HTML。

Security

  • 版本记录同步匿名只读远端仓库(不使用任何凭据),来源限配置里批准的 origin 与固定仓库:拒绝任意 URL、拒绝跨主机重定向,单个响应设大小上限与超时、5xx/429 才有退避重试。
  • 提交正文与变更记录一律按纯文本渲染(不产生 HTML/脚本注入面);页面不含打 tag / 发布 / 部署入口;同步动作仅管理员可用,服务端再次判角色。

版本号的唯一来源就是本文件顶部那条已发布版本。 不放 VERSION 文件、不把版本写进源码常量。

正式版本用注释 tag vX.Y.Z(由人批准后创建):CI 只核验「tag 的版本 == 它指到那个提交里的 版本记录」,不自动升版本、不打 tag、不发 Release。日常改动写进 [Unreleased]; 不要求每个提交都改本文件 —— 有使用者可见的变化才记,其余走提交信息与档案。

python3 scripts/version.py --identity      # 构建身份:release_version / build_kind / commit_sha / display_version / built_at
python3 scripts/check_changelog.py --tags  # 结构 + tag 一致性(无正式 tag 不判红)

小节只认四类(分类可省略,但不要空栏目):### Added / ### Changed / ### Fixed / ### Security。 破坏性变化写在 ### Changed 里、以 **破坏性** 开头,并链接发布文档(见 docs/RELEASE_RUNBOOK.md)。

过程记录(审查轮次、命令输出、逐条修正明细)不入本文件:归档在 docs/archive/, 未合并事项在 docs/BACKLOG.md。

版本怎么走(两行就够): · 正式版本 = 下面那条 ## [x.y.z] - 日期,是发版事实,由人批准后打注释 tag vX.Y.Z; · 开发版本自动递增 = <正式版本的主.次>.<自那个 tag 以来的提交数>(正式 0.1.0 之后第 12 个提交 = 0.1.12),由 scripts/version.py 从 git 算出来,不写进本文件 ⇒ 每个提交都有自己的版本号, 但"发布版本"仍然只能由人定(CI 不会自动升版本、不会打 tag)。

[0.1.0] - 2026-10-13

Added

  • 唯一权威门禁 make verify:一条命令跑完必需检查并产出结构化报告,本地与 CI 跑同一条命令。
  • 静态预览发布前先做同一份完整核对:报告有任何缺项就一个 publish 请求都不发。

Changed

  • 依赖升级:vite 7.1.3 → 7.3.7、vitest 3.2.4 → 5.0.3(npm audit 全量 0 命中)。
  • 前端存量格式债记入基线 web/.prettier-baseline.json(79 个文件,只能减,2026-12-31 到期)。

Fixed

  • 新分支推送时提交范围恒为空(基准改为远端默认分支)。
  • 空工作区下 CI 起不来(工作流首步改为最小 bootstrap)。
  • 事件负载缺 total_commits 时提交范围解析抛未收敛异常。

Security

  • 依赖漏洞例外登记 security/dependency-exceptions.json:缺字段 / 过期 / 批准人是占位值 ⇒ 例外无效。

能力基线(未发布):2026-10-10 的上线能力

这一条不是正式发布版本:当时本仓既没有版本号、也没有变更记录,没有 tag、没有 Release。 它只是把已上线能力补记在此,供此后发版对照;版本号体系从下一个正式版本开始(首个正式版本号由人指定)。

  • 来源与目录:列出可选的钉钉知识库 → 勾选 → 变成来源;快照与变更集。
  • 发布管理:计划 → 建批 → 锁定 → 授权发布(落 WeKnora 生产)。
  • 监控 + 需下架车道:测试库知识逐条下架。
  • 钉钉侧:知识库发现 / 注册、取件走 dws;登录与系统设置。
  • 运行形态:knowledge-governance-p1-* —— api / web / worker / release-worker / dingtalk-login / postgres 共 6 个容器;web 发布在 :8088。
  • 验收口径:docs/USER_FLOWS_ACCEPTANCE.md(C1~C9)与 docs/OPERATIONS_RUNBOOK.md。

⚠️ 上面的端口与容器名前缀是本机运行栈的实测值;换环境要按那边的运行栈改,别无脑照抄。