# 发布 runbook(对标语法批 dev → main,2026-10) > **本文件是操作清单,不是建议书。** 每一步都给出可复跑的判据;任何一步的读数不符预期就停在原地, > 不要带着已知漂移往下走。生产侧的实测事实见 `reference-production-server-deploy` 记忆与 > `docs/acceptance/qa-tracker.md` §12–§14。 ## 0. 发布前硬件检查 ```bash 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`** ⇒ 迁移**必须在本机**对下载下来的库副本执行, 再把库回传。不要试图在服务器上跑这个脚本。 ```bash # 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` 里是 ``(空)、`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 实际执行并验证) ```bash # 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) # ⚠ 构建失败必须中止:把 build 与 up 串成一条 `&&` 链,别让 up 在 build 失败后继续跑。 # 2026-10-20 踩过:ENOSPC 导致 COPY 失败,而 up -d 仍执行 ⇒ 容器跑旧镜像、看起来像已发布。 # 判据:`BUILD_EXIT=0` 才允许 up;随后用 `docker inspect … {{.Image}}` 与 BUILD_ID 复核。 ssh root@… 'cd /home/novalon/docker-app/novalon-website \ && 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`。 ### 3.3 2026-10-20 11:12 首页改版发布(`acb6b673`) - 发布内容:首页咨询机构影像版式、导航/页脚/品牌页「名 + 号」字标、reduce 白屏修复、106 张视觉基线。 - 镜像:`sha256:33136c8e7a86fd59aa3520eb3b4a3ab1b5f1fd04ba4aa4fd28b4a7028a951ae5`;容器 healthy。 - 备份:`dist_backup_20261020_111121` / `public_backup_20261020_111121`。 - 上传:standalone 实际发送 2.5MB(speedup 47.5×)、static 0.27MB、`_next/static` 镜像 0.27MB、public 0.99MB。 - 核对:14 关键路由 200;`warm-routes` 30 路由非 200 = 0;容器日志 `error|exception|fatal` 0、 `退回代码真源` 0;线上多端探针 15/15、axe 8 次 0 violation。证据 `docs/acceptance/2026-10-20-home-multiplatform/README.md` §4.1。 ### 3.4 2026-10-20 14:05 站内跳转白屏修复(`2f86c441`) - 发布内容:移除路由级 `AnimatePresence mode="wait"` 退场链(`src/components/ui/page-transition.tsx`), 修复所有站内跳转白屏;reduce 模板变体连带修复;新增 `e2e/client-navigation-visibility.spec.ts`。 机理与判据见 `docs/lessons-learned.md` §5.50。 - 构建口径:**按提交树构建**。工作树中 3 个会话前未提交改动(`home-content-v16.tsx`、 `hero-architecture.webp`、`p2-functional-e2e.spec.ts`)未纳入发布;发布后服务器 `public/` 的 hero 图哈希与 HEAD 一致(`02cf8bca…`)。 - 镜像:`sha256:87ca390d44bbbaac614a7c6e7c56b6fb7073dd10fd5f7c7901ef999d7dc22175`; `BUILD_ID=KO7S41-qvKY89xp5Kczbl`(与本地产物逐字一致);容器 `healthy`。 - 备份:`dist_backup_20261020_140513` / `public_backup_20261020_140513`。 - 上传:standalone 实际发送 1.39MB;static 0.22MB ×2(含 `_next/static` 镜像,未 `--delete`);public 0.15MB ×2。 - 线上核对:关键 9 路由全 200;`warm-routes` 30 路由非 200=0、第二遍 >1500ms=0;容器日志 error 0; 三浏览器(chromium/firefox/webkit)站内跳转 15/15、iPhone 14 移动端 5/5,导航后有效 opacity 均回 1、 console 0 错误。 - 残留(独立于本次发布):发布当时页面响应仍带 nginx 追加的旧版 `X-Frame-Options: SAMEORIGIN` 与含 `'unsafe-eval'` 的第二份 CSP。**已于 14:26 处理**:线上 `/home/novalon/docker-app/novalon-nginx/nginx-static-production.conf` 是 9 月前旧版; 按仓库同名文件就地覆盖(备份 `nginx-static-production.conf.bak.20261020_142648`, 远端/容器内哈希一致),`nginx -t` 通过后 `nginx -s reload`。复核:页面仅 1 条 `X-Frame-Options: DENY`、1 条 CSP(无 `unsafe-eval`)、静态 chunk 200; `npm run test:security:headers` 线上 8/8 通过、0 警告。 - 磁盘:发布后 `docker image prune -f` 回收 1.27GB 悬空镜像,剩余 2.9G 可用(86%);dist 备份保留。 - PR:同分支 PR **#32**(`feat/brand-wordmark-landing → dev`)此前已存在,本轮已更新标题与描述 (补入白屏修复、线上发布与门禁读数);`origin/dev` 为 HEAD 祖先,无需 rebase。**尚未合并**,待评审。 - 本批门禁(2026-10-20 最终树):unit 149 套 / 1815 例、coverage 89.56/88.28/88.18/89.56、 functional 1088 passed / 44 skipped、visual 125/125、a11y 11/11、security headers 8/8、 integration 4 套 / 23 例、lighthouse 33 次运行全部断言通过。 ## 4. 发布后核对(全部只读) ```bash # 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_`(保留最近 3 份)。 - 服务端 + 静态:`deploy.sh` 的 `cmd_rollback`(`722f08a` 起会重建容器,避免"旧静态 + 新服务端")。 - 数据库:`data/prod.db.bak.`;恢复时同样先停容器,再覆盖、再启。 ## 6. 已知残留(发布不会消除) 1. `check:motion` 与全站 axe 仍不在 `test:all`(CI 在 Jenkinsfile 单独阶段跑)。 2. 本地 `core.hooksPath` 指向主检出的 `.husky`,那份仍是 644 ⇒ 本机提交不跑 lint-staged (索引里已 100755,克隆/检出即生效)。 3. 视觉基线虽已逐名清单化,但**逐张人工读图追认**仍需决策人分批完成。