Files
novalon-website/docs/development/deploy-runbook.md
T
zhangxiang 54783f4068 fix(ops): 磁盘写满事故收口——备份预检按模式取阈值、残档即删
生产全站 502 约 5.5 小时、Gitea 500 约 13 小时,根因是 / 写到 100%(20G/20G)。
仓库侧落这四处;另三处守卫在服务器侧脚本(未入仓,已在 runbook §7.3 登记)。

- backup-cicd.sh:预检阈值必须与本轮实际开销绑定。原 .env 把 MIN_FREE_GB 从 3 降到 1,
  于是 2GB 可用时放行了一次要写 2.6GB 的全量导出,tar 写到 2.0GB 撞盘。改为含仓库导出时
  上调至 BACKUP_FULL_MIN_FREE_GB(默认 4GB),thin 仍按 1GB —— 一并抬高等于又关掉
  「唯一副本、不可重建」的那份 DB 备份,是同一个错法的两个方向。
- backup-cicd.sh:归档失败即删残档。半截归档把一次备份失败升级成了全站故障,
  且 set -e 让末尾的保留清理从未执行,形成「失败越多越容易满盘」的正反馈。
- backup-cicd.sh:Jenkins 容器缺失时只在预检记录并跳过第 [3/3] 步。原先的
  require_container 会让整轮备份(含 Gitea DB dump)在预检阶段就中止。
- nginx-static-production.conf:upstream jenkins_app 后端置 127.0.0.1:1 down。
  Jenkins 下线后 `server jenkins:8080` 让 nginx -t 报 host not found,
  而修 502 正需要 reload,形成死锁。保留结构以便一行还原。
- runbook §7:复发时的四步判据(盘满时 docker ps 读数不可信)、已落地守卫表、9 项未闭环。
- lessons §5.53:诊断仪器在故障态下自身会失真这一族。§5.52 空号是他人未落库的在途段。
2026-11-01 16:58:33 +08:00

233 lines
17 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. 发布前硬件检查
```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` 里是 `<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)
# ⚠ 构建失败必须中止:把 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_<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. 视觉基线虽已逐名清单化,但**逐张人工读图追认**仍需决策人分批完成。
## 7. 2026-11-01 磁盘写满事故(记录 + 已落地守卫)
现象:`www.novalon.cn` 全站 502(含 `/api/health`)持续约 5.5 小时;`git.f.novalon.cn` 500、
开发者 `git fetch` 报 500 持续约 13 小时。根因 `/dev/vda1` 写到 100%(20G/20G,可用 0)。
机理、证据与教训见 `docs/lessons-learned.md` §5.53,本节只留**操作面**要记得的东西。
### 7.1 复发时先跑这四条判据(顺序即诊断顺序)
```bash
ssh root@139.155.109.62 'df -h / | tail -1' # 1) 盘满?
ssh root@… 'docker ps -a --format "{{.Names}}|{{.Status}}"' # 2) 盘满时此项不可信
ssh root@… 'docker inspect -f "{{.State.Status}} {{.NetworkSettings.IPAddress}}" novalon-website' # 3) 真实状态与当前 IP
ssh root@… 'docker exec novalon-nginx-secure sh -c "tail -5 /var/log/nginx/error.log"' # 4) 日志里的 upstream IP
```
**盘满时 `docker ps` 会报错误状态**(本轮同一容器同时出现 `Exited (0) 6 hours ago` 与
`Status=running`)。先腾空间,再相信任何 docker 读数。
若 `nginx error.log` 里的 upstream IP ≠ 第 3 步的当前 IP,则是 nginx 缓存旧地址,
`docker exec novalon-nginx-secure nginx -s reload` 即恢复(应用侧无需重启)。
### 7.2 已落地守卫
| 位置 | 守卫 | 验证读数 |
|---|---|---|
| `scripts/docker-cleanup.sh`(服务器侧,**未入仓**) | 容器/镜像/网络清理改为逐个判定 + 保护名单(`postgresql gitea novalon-website novalon-nginx-secure novavis-authority`);删掉 blanket `image prune -a` | 实跑后容器/镜像/网络三项 diff 全空;`alpine:latest` 在「引用容器 0 个」下仍保留 |
| `/usr/local/bin/container-monitor.sh`(每 5 分钟) | 新增 `check_nginx_upstream_drift`:容器 IP 变化时先 `nginx -t` 再 reload | 伪造 `172.20.0.99 → 172.20.0.3` 触发,日志 `WARN…准备 reload` + `OK nginx 已 reload`,站点仍 200 |
| `infra/cicd/backup/backup-cicd.sh` | ① Jenkins 容器缺失时**只在预检记一条并跳过第 [3/3] 步**,不再 `require_container` 拦掉整轮;② 归档失败即删残档;③ 预检阈值按 thin/full 分别取(含仓库导出时上调至 `BACKUP_FULL_MIN_FREE_GB`,默认 4GB) | `--skip-repos` 真实跑 EXIT=0、`gzip -t` 独立通过、保留清理正常执行;`--dry-run` 两模式分别显示阈值 1GB / 4GB |
| `nginx-static-production.conf` + 仓库同名文件 | `upstream jenkins_app` 后端置 `127.0.0.1:1 down`(保留结构,Jenkins 回归时一行还原) | 仓库与生产 md5 一致 `1bf99ea4…`;`ci.f.novalon.cn` 按预期不再可用 |
服务器侧改动均留了带时间戳的备份:`nginx-static-production.conf.bak.20261101_1635`、
`backup-cicd.sh.bak.20261101_1650`、`container-monitor.sh.bak.20261101_1650`。
### 7.3 未闭环(需决策人输入,不是工程侧能自决的)
1. **`ALERT_WEBHOOK_URL` 三处全空**(`infra/cicd/.env`、`container-monitor.sh` 的 `ALERT_WEBHOOK=""`)。
告警函数都在,但空值使其成为 no-op ⇒ 磁盘阈值告警连续 13 小时无人收到。
**需要一个企业微信/钉钉 webhook 地址**才能闭环,代理侧不能编造。
2. **备份仍是同盘**:`.env` 里 `RCLONE_REMOTE=` 空,脚本自己每次都在打
「未配置 RCLONE_REMOTE —— 同盘备份不抗主机故障」。周日全量单份 ~2.0–2.6GB,而整机盘只有 20GB,
这是本次事故的算术来源。需要决策:裸库全量 offload 到对象存储,或接受「周日不做含仓库全量」并另设异地副本。
3. **`docker-cleanup.sh` / `disk-monitor.sh` / `container-monitor.sh` 三个运维脚本未入仓**
(只在服务器上),本轮改动无法评审、也无法回滚到仓库版本。建议纳入 `infra/cicd/` 或 `scripts/ops/`。
4. **保留清理在 `backup-cicd.sh` 末尾** ⇒ 峰值占用 = 旧全量 + 新全量。本轮用阈值兜住,未重构脚本分段。
5. **`container-monitor.sh` 的容器清单基本是虚构的**:`woodpecker-server`、`woodpecker-agent`、
`novalon-nginx`、`forgejo`、`registry` 均不存在(真实名 `novalon-nginx-secure`、`gitea`、
`novavis-authority`)。本轮**未改清单**——它会对清单内容器执行 `docker restart`,而
`novavis-authority` 属另一项目,不应由本仓擅自纳管。需领域主确认后再补。
6. **nginx upstream 仍是加载期一次性解析**(本轮靠 5 分钟巡检兜)。根治是 `resolver 127.0.0.11 valid=10s`
+ 变量形式 `proxy_pass`,但变量形式会改变 URI 传递语义,需逐个 `location` 复核后单独一轮做。
7. `docs/PRODUCTION_DEPLOYMENT_LIGHTWEIGHT.md:141` 记载的健康检查 `/api/health` **在当前代码里不存在**
(`src/app/api/` 只有 `admin auth cms contact`)。本轮实测该路径 404 是既有状态、非事故造成;文档需修正口径。
8. §6.1 说「CI 在 Jenkinsfile 单独阶段跑」在 Jenkins 下线后已不成立(且 2026-10-20 实测该任务从未被触发)。
9. `novavis-authority` 处于 `unhealthy`(Java/reactor-netty 连接报错),属另一项目,本仓未代改。