Files
novalon-website/docs/development/deploy-runbook.md
T
zhangxiang 702c732d27 fix(contact): 去掉 useSearchParams 让 /contact 可完整预渲染;补发布后 ISR 预热脚本
冷首访白屏的第二个真因:/contact 用 useSearchParams() 读 ?success,客户端组件里
这会让整页在预渲染时退化成 Suspense fallback(首访只看到「加载中…」,限速下 ~6s 才出内容)。
该参数只用于一次性成功提示 ⇒ 改为挂载后从 window.location 读并 replaceState 清理。

- /contact 冷首访 h1 可见:6.0s → 1.5s;HTML 73KB 含正文(此前只有外壳)。
- 新增 scripts/ops/warm-routes.mjs:按 sitemap 预热并断言全 200、第二遍 <1500ms 或 HIT;
  本轮线上第二遍:非 200 = 0、>1500ms = 0。
- 全站冷首访复测:/ 827ms、/about 1652ms、/contact 1511ms、/products 917ms、
  /services/software 922ms、/insights 1532ms。
- runbook:加发布前磁盘检查(≥2G)与「构建失败必须中止」;加 §4.0 预热步骤。
- 事故记录:第三次重建时服务器磁盘 99%,COPY 报 ENOSPC 而 up -d 仍执行(旧镜像被当已发布);
  清理旧备份 1.8G + docker image prune 1.075G 后回到 81%,重建 015b6d75 成功。
2026-10-20 08:23:34 +08:00

8.5 KiB
Raw Blame History

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

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

0. 发布前硬件检查

ssh root@139.155.109.62 "df -h / | tail -1"
# 要求可用 ≥ 2G(2026-10-20 真实踩过:99% 满时 COPY 报 no space left on device,
# 而 up -d 仍会跑起来 → 旧镜像被当成"已发布")。备份保留最近 2 代即可。

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. 发布代码

2026-10-20 实测更正:合 main 不会触发任何部署。 Jenkins 任务 novalon-website-ci-cd 的 config.xml 里是 <triggers/>(空)、builds/ 只有 permalinks (从未构建)、匿名 POST /job/…/build 返回 403 Authentication required, Gitea 的 webhook 因此打不进去。⇒ 下面这条"合 main 自动部署"是设计意图,当前不成立。 本轮实际按 §3.2 的手动路径发布(详见 docs/acceptance/qa-tracker.md §15)。

3.1 设计路径(需 Jenkins 管理员先补齐)

  • Jenkins 任务需加 GenericTrigger(token 与 Gitea webhook 的 novalon-website-webhook-token-2024 一致,并用 refs/heads/main 过滤), 或改用 Jenkins 的 Git SCM 轮询;两者都需管理员权限,代理侧无凭据。
  • 合并方式与 #29 一致:main 是 dev 的严格祖先时用 fast-forward-only,保住 sha 可引用。
  • 发布后产物要点:dist/_next/static 镜像必须存在(见 §3.2 步骤 3); 缺它 = 全站 CSS/JS 404 而 HTML 全 200。 不要对 _next/static 用 --delete:回访者的 HTML 可能来自旧缓存,仍在引用上一代 chunk; 删掉会让这些人 hydration 失败(表现为白屏)。用 --ignore-existing 合并旧代,或保留 N-1 代。

3.2 手动路径(2026-10-20 实际执行并验证)

# 0) 本地按待发布 sha 重建
npm run build                      # 产物:dist/standalone + dist/static + dist/server
# 1) 备份(服务器侧)
ssh root@139.155.109.62 'cd /home/novalon/docker-app/novalon-website \
  && cp -a dist dist_backup_$(date +%Y%m%d_%H%M%S) \
  && cp -a public public_backup_$(date +%Y%m%d_%H%M%S)'
# 2) 增量上传(node_modules 基本不变 ⇒ rsync 只传差异,150MB 原始内容线上只走 3.4MB)
rsync -az dist/standalone/ root@…:/home/novalon/docker-app/novalon-website/dist/standalone/
rsync -az dist/static/     root@…:/home/novalon/docker-app/novalon-website/dist/static/
rsync -az dist/static/ root@…:/home/novalon/docker-app/novalon-website/dist/_next/static/  # nginx 站点根镜像(**不要 --delete**)
rsync -az public/          root@…:/home/novalon/docker-app/novalon-website/public/
rsync -az public/          root@…:/home/novalon/docker-app/novalon-website/dist/                  # 根级静态资产
# 3) 重建镜像并重启(compose 是 v1 ⇒ docker-compose)
ssh root@… 'cd /home/novalon/docker-app/novalon-website \
  && # ⚠ 构建失败必须中止:`build && up -d` 要串成一条,别让 up 在 build 失败后继续跑
# (2026-10-20 踩过:ENOSPC 导致 COPY 失败,up -d 仍执行 ⇒ 容器跑旧镜像、看起来像已发布)
docker-compose -f docker-compose.server.yml build novalon-website \
  && docker-compose -f docker-compose.server.yml up -d novalon-website'
# 4) 数据迁移按 §2(停容器 → 备份 → 本机迁移 → 回传 → 启容器)

关键前置:服务器没有 sqlite3、Node 是 v20 ⇒ 库的读与迁移都在本机做; 上传目录的属主不影响容器(文件世界可读),但 data/prod.db 回传后必须 chown 1001:1001。

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

# 4.0 预热 ISR(发布后立刻做;冷首访白屏的成因之一)
node scripts/ops/warm-routes.mjs --base https://www.novalon.cn
# 期望:第二遍全部 HIT 或 <1500ms;任何非 200 退出 1

# 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. 视觉基线虽已逐名清单化,但逐张人工读图追认仍需决策人分批完成。