Files
novalon-website/docs/development/deploy-runbook.md
T
zhangxiang d0090cea56 fix(motion): reduce 偏好下 hydration 不匹配(React #418)且元素停在 opacity:0
线上 /about 白屏排查(§16):30 条路由 + 6 种环境里唯一可复现的缺陷是
webkit/chromium + prefers-reduced-motion:reduce ⇒ pageerror #418,main 内 14 个元素
opacity 恒 0(正常环境只有 3 个首屏以下的滚动入场项)。

根因:useReducedMotion 用 window.matchMedia 作 useState 初值 ⇒ SSR false、客户端首帧 true;
scroll-reveal / template / page-transition 又用它决定 initial/variants/甚至早返回不同树结构,
与 SSR HTML 不一致;且 reduce 时 whileInView 被清空 ⇒ 元素停在 initial 的 opacity:0。

修法(结构恒定,减少动效改用「时长 0」表达):
- hook 首帧恒 false,挂载后 effect 同步真实偏好;
- ScrollReveal/StaggerReveal 的 initial/whileInView/variants 不再按 reduce 清空;
- template.tsx 与 StaggerChildren 去掉早返回裸结构,改空 variants。

回归守卫 e2e/reduced-motion-hydration.spec.ts(/about 与 /):断言 reduce 自证生效、
无 hydration 错误、h1 与末段标题 opacity=1。变异验证:hook 改回 matchMedia 初值 ⇒ 2 红,恢复 ⇒ 2 绿。

另:runbook 明确禁止对 dist/_next/static 用 --delete(回访者旧 HTML 会引用上一代 chunk);
本轮已从备份 --ignore-existing 合并回旧代 101 个文件。复算:tsc/type-check:e2e 0、
jest 35 套件 462 例 0、check:visual 0、check:motion 0、视觉 chromium-desktop 25/25。
2026-10-20 08:00:20 +08:00

125 lines
7.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 发布 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`** ⇒ 迁移**必须在本机**对下载下来的库副本执行,
再把库回传。不要试图在服务器上跑这个脚本。
```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` 里是 `<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 实际执行并验证)
```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)
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`。
## 4. 发布后核对(全部只读)
```bash
# 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. 视觉基线虽已逐名清单化,但**逐张人工读图追认**仍需决策人分批完成。