Files
novalon-website/docs/development/deploy-runbook.md
T
zhangxiang cee21e178a docs(ops): 生产侧核对与发布 runbook;新增最小迁移脚本 sync-cms-schema(默认 dry-run)
只读核对生产库(scp 副本、本地 node:sqlite 查询,未写生产):
- navigation 行仍是旧 7 项 IA(panels products,solutions,services)⇒ 新代码每请求退回代码真源;
- 三处 caseStudies 的 ContentModel.fields 缺 authorized/basis ⇒ 后台填不出门槛字段;
- 生产案例条目 **0 条** ⇒ 只发代码不会隐藏任何内容(dataProofs 按裁定不套硬闸)。

新增 scripts/ops/sync-cms-schema.ts:只补 3 个模型的两个子字段 + 把 navigation 行改写为
由 NAVIGATION_V2/MEGA_DROPDOWN_DATA 派生的形状;默认 dry-run,--apply 才写,
写前用真实 resolveNavigation 验收派生形状、写后强制复查(不通过即退出码 1)。
在生产库副本上预演通过:source=cms / issues=0;逐行 diff 证明只动了
3 个 ContentModel 行 + 1 个 ContentItem 行(navigation),其余 37 行内容与 13 个模型逐字节不变。

docs/development/deploy-runbook.md 写清:备份与停容器顺序、**服务器 Node v20 无 node:sqlite
⇒ 迁移必须本机跑再回传**、不推荐用 db:seed(会重写所有覆盖行且需 SEED_ALLOW_EXTERNAL_DB=1)、
发布后四项只读核对、三条回滚路径,以及"合 main = 无人值守线上发布,须决策人显式发起"。
2026-10-20 07:40:37 +08:00

5.4 KiB
Raw Blame History

发布 runbook(对标语法批 dev → main,2026-10)

本文件是操作清单,不是建议书。 每一步都给出可复跑的判据;任何一步的读数不符预期就停在原地, 不要带着已知漂移往下走。生产侧的实测事实见 reference-production-server-deploy 记忆与 docs/acceptance/qa-tracker.md §12–§14。

0. 这次发布包含什么(dev tip 8799a965 起)

  • §11 对标语法批(首页 8 段、双轴 IA、信任层零编造、tracer-bullet 详情页)
  • §12 台账六项:DEC-N1/N2(证伪)/N3/N4/N5/N6 + AUTH-VISUAL + AUTH-NAV 核查 + GA4 首次真断言
  • §13/§14 治理与收口:全量功能 E2E 1068 passed / 0 failed、test:all 0、 check:axe 0、lighthouse 0、视觉 125/125;case-publish-gate 与 seed 沙盒守卫

1. 预检(已完成,发布前复核仍然成立即可)

项 读数 复跑
生产库 navigation 行 旧 7 项 IA(产品/解决方案/服务/案例/新闻动态/关于我们/联系我们 + panels products,solutions,services) 见 §3 的只读检查
生产库 ContentModel.fields(3 个案例模型) 缺 authorized 与 basis 同上
生产库里的案例条目 0 条(case-study 模型 0 行;product/service/standalone-product/solution 的 caseStudies 数组全空) 同上
⇒ 只发代码、不做数据修复的后果 站点可用(导航 fail-closed 退回代码真源),但每请求一条回退日志,且后台填不出案例门槛字段 —
⇒ 这批代码会隐藏内容吗 不会(案例 0 条;dataProofs 按 DEC-N4 的裁定不套 verified 硬闸) —

2. 数据修复(只动 2 处,先备份、先 dry-run)

工具:scripts/ops/sync-cms-schema.ts(默认 dry-run;--apply 才写;写后强制用真实 resolveNavigation 复查,不通过即退出码 1)。

关键约束:服务器 Node 是 v20,没有 node:sqlite ⇒ 迁移必须在本机对下载下来的库副本执行, 再把库回传。不要试图在服务器上跑这个脚本。

# 2.1 备份(容器运行时 prod.db 是 WAL,先停容器再拷)
ssh root@139.155.109.62 'cd /home/novalon/docker-app/novalon-website \
  && docker stop novalon-website \
  && cp -av data/prod.db data/prod.db.bak.$(date +%Y%m%d_%H%M%S)'
# 2.2 下载副本、本机 dry-run(**先看计划**)
scp root@139.155.109.62:/home/novalon/docker-app/novalon-website/data/prod.db /tmp/prod.db
npx tsx scripts/ops/sync-cms-schema.ts --db /tmp/prod.db            # 期望:3 个模型各 +authorized,+basis;navigation 7 项 → 4 项
# 2.3 应用到副本并复查
npx tsx scripts/ops/sync-cms-schema.ts --db /tmp/prod.db --apply    # 期望:写后复查通过
# 2.4 回传(覆盖前再确认备份存在)
scp /tmp/prod.db root@139.155.109.62:/home/novalon/docker-app/novalon-website/data/prod.db
ssh root@139.155.109.62 'cd /home/novalon/docker-app/novalon-website && ls -l data/ && chown 1001:1001 data/prod.db'
docker start novalon-website

已在本机对生产库副本预演通过(2026-10-19):source=cms issues=0, 变更范围经逐行比对为 3 个 ContentModel 行 + 1 个 ContentItem 行(navigation), 其余 37 行内容与 13 个模型逐字节不变。

若不走 §2 而选择跑 npm run db:seed:它会把所有 seed 覆盖的内容行一并改回仓库版本, 且服务器上必须显式 SEED_ALLOW_EXTERNAL_DB=1(seed 沙盒守卫会拦住 file:/app/data/prod.db)。不推荐。

3. 发布代码

  • 合 dev → main 会触发 Jenkins 的「🚀 部署到生产环境」阶段(when { branch 'main' })—— 这是一次无人值守线上发布,必须由决策人显式发起。
  • 合并方式与 #29 一致:main 是 dev 的严格祖先时用 fast-forward-only,保住 sha 可引用。
  • 发布后产物要点:dist/_next/static 镜像必须存在(deploy.sh 步骤 1.5 会自动生成; 缺它 = 全站 CSS/JS 404 而 HTML 全 200)。

4. 发布后核对(全部只读)

# 4.1 页面健康 + 关键页面状态码
for u in / /products /products/erp /solutions /solutions/manufacturing /services /insights /news /contact; do
  curl -s -o /dev/null -w "%{http_code} $u\n" https://www.novalon.cn$u; done
# 4.2 服务端不再每请求回退(§2 做过就不该再有)
docker logs --since 10m novalon-website 2>&1 | grep -c '退回代码真源'   # 期望 0
# 4.3 后台能填案例门槛字段(super_admin 登录后看内容编辑表单)
#     期望:caseStudies 每条出现「客户授权展示」与「成果口径」两个字段
# 4.4 视觉抽查:首页/关于/联系/产品详情各截一张,与 local 基线对比只有内容差异

5. 回滚

  • 静态:dist_backup_<YYYYmmdd_HHMMSS>(保留最近 3 份)。
  • 服务端 + 静态:deploy.sh 的 cmd_rollback(722f08a 起会重建容器,避免"旧静态 + 新服务端")。
  • 数据库:data/prod.db.bak.<ts>;恢复时同样先停容器,再覆盖、再启。

6. 已知残留(发布不会消除)

  1. check:motion 与全站 axe 仍不在 test:all(CI 在 Jenkinsfile 单独阶段跑)。
  2. 本地 core.hooksPath 指向主检出的 .husky,那份仍是 644 ⇒ 本机提交不跑 lint-staged (索引里已 100755,克隆/检出即生效)。
  3. 视觉基线虽已逐名清单化,但逐张人工读图追认仍需决策人分批完成。