生产全站 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 空号是他人未落库的在途段。
17 KiB
发布 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:all0、check:axe0、lighthouse0、视觉 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)
# ⚠ 构建失败必须中止:把 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-routes30 路由非 200 = 0;容器日志error|exception|fatal0、退回代码真源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-routes30 路由非 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. 发布后核对(全部只读)
# 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. 已知残留(发布不会消除)
check:motion与全站 axe 仍不在test:all(CI 在 Jenkinsfile 单独阶段跑)。- 本地
core.hooksPath指向主检出的.husky,那份仍是 644 ⇒ 本机提交不跑 lint-staged (索引里已 100755,克隆/检出即生效)。 - 视觉基线虽已逐名清单化,但逐张人工读图追认仍需决策人分批完成。
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 复发时先跑这四条判据(顺序即诊断顺序)
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 未闭环(需决策人输入,不是工程侧能自决的)
ALERT_WEBHOOK_URL三处全空(infra/cicd/.env、container-monitor.sh的ALERT_WEBHOOK="")。 告警函数都在,但空值使其成为 no-op ⇒ 磁盘阈值告警连续 13 小时无人收到。 需要一个企业微信/钉钉 webhook 地址才能闭环,代理侧不能编造。- 备份仍是同盘:
.env里RCLONE_REMOTE=空,脚本自己每次都在打 「未配置 RCLONE_REMOTE —— 同盘备份不抗主机故障」。周日全量单份 ~2.0–2.6GB,而整机盘只有 20GB, 这是本次事故的算术来源。需要决策:裸库全量 offload 到对象存储,或接受「周日不做含仓库全量」并另设异地副本。 docker-cleanup.sh/disk-monitor.sh/container-monitor.sh三个运维脚本未入仓 (只在服务器上),本轮改动无法评审、也无法回滚到仓库版本。建议纳入infra/cicd/或scripts/ops/。- 保留清理在
backup-cicd.sh末尾 ⇒ 峰值占用 = 旧全量 + 新全量。本轮用阈值兜住,未重构脚本分段。 container-monitor.sh的容器清单基本是虚构的:woodpecker-server、woodpecker-agent、novalon-nginx、forgejo、registry均不存在(真实名novalon-nginx-secure、gitea、novavis-authority)。本轮未改清单——它会对清单内容器执行docker restart,而novavis-authority属另一项目,不应由本仓擅自纳管。需领域主确认后再补。- nginx upstream 仍是加载期一次性解析(本轮靠 5 分钟巡检兜)。根治是
resolver 127.0.0.11 valid=10s- 变量形式
proxy_pass,但变量形式会改变 URI 传递语义,需逐个location复核后单独一轮做。
- 变量形式
docs/PRODUCTION_DEPLOYMENT_LIGHTWEIGHT.md:141记载的健康检查/api/health在当前代码里不存在 (src/app/api/只有admin auth cms contact)。本轮实测该路径 404 是既有状态、非事故造成;文档需修正口径。- §6.1 说「CI 在 Jenkinsfile 单独阶段跑」在 Jenkins 下线后已不成立(且 2026-10-20 实测该任务从未被触发)。
novavis-authority处于unhealthy(Java/reactor-netty 连接报错),属另一项目,本仓未代改。