docs(ops): 生产侧核对与发布 runbook;新增最小迁移脚本 sync-cms-schema(默认 dry-run)

只读核对生产库(scp 副本、本地 node:sqlite 查询,未写生产):
- navigation 行仍是旧 7 项 IA(panels products,solutions,services)⇒ 新代码每请求退回代码真源;
- 三处 caseStudies 的 ContentModel.fields 缺 authorized/basis ⇒ 后台填不出门槛字段;
- 生产案例条目 **0 条** ⇒ 只发代码不会隐藏任何内容(dataProofs 按裁定不套硬闸)。

新增 scripts/ops/sync-cms-schema.ts:只补 3 个模型的两个子字段 + 把 navigation 行改写为
由 NAVIGATION_V2/MEGA_DROPDOWN_DATA 派生的形状;默认 dry-run,--apply 才写,
写前用真实 resolveNavigation 验收派生形状、写后强制复查(不通过即退出码 1)。
在生产库副本上预演通过:source=cms / issues=0;逐行 diff 证明只动了
3 个 ContentModel 行 + 1 个 ContentItem 行(navigation),其余 37 行内容与 13 个模型逐字节不变。

docs/development/deploy-runbook.md 写清:备份与停容器顺序、**服务器 Node v20 无 node:sqlite
⇒ 迁移必须本机跑再回传**、不推荐用 db:seed(会重写所有覆盖行且需 SEED_ALLOW_EXTERNAL_DB=1)、
发布后四项只读核对、三条回滚路径,以及"合 main = 无人值守线上发布,须决策人显式发起"。
This commit is contained in:
zhangxiang committed 2026-10-20 07:40:37 +08:00
1 parent 8799a9658e
commit cee21e178a
3 files changed
+265

No files matched your search

+22
View File
@@ -1140,3 +1140,25 @@ webkit/mobile 的 Tab 引擎差异取证法、`pollBoundingBox` 的二次读取
**视觉基线与"seed 内容"耦合** —— 重跑 `db:seed` 或改 CMS 文案后,内容型基线会失效, **视觉基线与"seed 内容"耦合** —— 重跑 `db:seed` 或改 CMS 文案后,内容型基线会失效,
必须按"内容变更 ⇒ 重采 + 只读复验"处理,不能把它读成样式回归。反过来, 必须按"内容变更 ⇒ 重采 + 只读复验"处理,不能把它读成样式回归。反过来,
将来若看到只有 `/contact`、`/news` 这类内容页整页红而组件裁图全绿,先查数据而不是查 CSS。 将来若看到只有 `/contact`、`/news` 这类内容页整页红而组件裁图全绿,先查数据而不是查 CSS。
### 14.7 生产侧只读核对 + 迁移预演(发布前的最后一块证据)
**只读核对(`scp` 生产 `data/prod.db` 到 /tmp,本地 `node:sqlite` 查询;未写生产任何东西)**
| 项 | 生产实测 |
|---|---|
| `navigation` 行 | **旧 7 项 IA**:产品/解决方案/服务/案例/新闻动态/关于我们/联系我们,面板 `products,solutions,services` ⇒ 新代码每请求退回代码真源 |
| `ContentModel.fields`(product / service / standalone-product) | **均缺** `authorized` 与 `basis` ⇒ 后台填不出案例门槛字段 |
| 生产内容里的案例条目 | **0 条**(`case-study` 0 行;四个含 `caseStudies` 字段的模型逐行解析,数组全空) |
| ⇒ 只发代码的影响 | 站点可用(fail-closed 回退),**不隐藏任何内容**(0 案例;`dataProofs` 按裁定不套硬闸);代价是每请求一条回退日志 + 后台填不出门槛字段 |
**迁移预演**:`scripts/ops/sync-cms-schema.ts`(默认 dry-run,`--apply` 才写,写后强制用真实
`resolveNavigation` 复查)。在**生产库副本**上跑通:
`source=cms issues=0`;逐行 diff 证明变更范围 **3 个 ContentModel 行 + 1 个 ContentItem 行**,
其余 37 行内容、其余 13 个模型逐字节未变。
关键约束写进 runbook:**服务器 Node v20 没有 `node:sqlite`** ⇒ 迁移必须本机对库副本执行再回传;
若改用 `npm run db:seed`,服务器上必须显式 `SEED_ALLOW_EXTERNAL_DB=1`(守卫会拦 `file:/app/data/prod.db`),
且 seed 会重写所有被覆盖的内容行 —— 因此**不推荐**。
发布步骤、发布后核对(页面状态码 / 回退日志计数 / 后台字段 / 视觉抽查)与三条回滚路径:
`docs/development/deploy-runbook.md`。**代码发布本身(合 main)仍由决策人显式发起**。
+87
View File
@@ -0,0 +1,87 @@
# 发布 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. 发布代码
- 合 `dev → main` 会触发 Jenkins 的「🚀 部署到生产环境」阶段(`when { branch 'main' }`)——
这是一次**无人值守线上发布**,必须由决策人显式发起。
- 合并方式与 `#29` 一致:`main` 是 `dev` 的严格祖先时用 **fast-forward-only**,保住 sha 可引用。
- 发布后产物要点:`dist/_next/static` 镜像必须存在(`deploy.sh` 步骤 1.5 会自动生成;
缺它 = 全站 CSS/JS 404 而 HTML 全 200)。
## 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. 视觉基线虽已逐名清单化,但**逐张人工读图追认**仍需决策人分批完成。
+156
View File
@@ -0,0 +1,156 @@
#!/usr/bin/env node
/**
* CMS 两处数据漂移的最小迁移(默认 dry-run,`--apply` 才写)。
*
* 为什么不用 `npm run db:seed` 在生产上修:
* seed 会把**所有**被 seed 覆盖的 ContentItem.data 重写回仓库版本,
* 生产里若有人在后台改过文案,会被一起覆盖。这里只动两处已确认的漂移:
*
* 1) `ContentModel.fields`:三处 caseStudies(product / service / standalone-product)
* 缺 `authorized` 与 `basis` 两个子字段 ⇒ 后台填不出来,case-publish-gate 会把所有案例闸住。
* 口径以 `src/lib/cms/content-types.ts` 为唯一真源(从那里取字段定义,不手抄)。
* 2) `ContentItem(modelCode='navigation').data`:仍是旧 7 项 IA(products/solutions/services 面板),
* 新代码会每请求「退回代码真源」并打日志。改写成由 `NAVIGATION_V2` + `MEGA_DROPDOWN_DATA`
* 派生出来的形状 —— 只动这一行,其它内容行不碰。
*
* 自证:写完后用 **真实的 `resolveNavigation`** 跑一遍,要求 `source === 'cms'` 且 `issues` 为空;
* 不成立就退出码 1(绝不"写完就算成功")。dry-run 只打印计划。
*
* 用法:
* npx tsx scripts/ops/sync-cms-schema.ts --db /path/to/prod.db # dry-run
* npx tsx scripts/ops/sync-cms-schema.ts --db /path/to/prod.db --apply
*/
import { DatabaseSync } from 'node:sqlite';
import { CONTENT_TYPE_CONFIGS } from '../../src/lib/cms/content-types';
import { NAVIGATION_V2, MEGA_DROPDOWN_DATA } from '../../src/lib/constants/navigation';
import { resolveNavigation } from '../../src/lib/navigation-resolution';
const args = process.argv.slice(2);
const dbArg = args[args.indexOf('--db') + 1];
const apply = args.includes('--apply');
if (!dbArg || dbArg.startsWith('--')) {
console.error('用法:sync-cms-schema.ts --db <sqlite 文件> [--apply]');
process.exit(2);
}
const db = new DatabaseSync(dbArg);
const say = (...a: unknown[]) => console.log(...a);
// ── 1) ContentModel.fields:补齐 caseStudies 的两个门槛子字段 ──────────────
type SubField = { name: string; [k: string]: unknown };
const modelRows = db
.prepare(`select code, fields from ContentModel where code in ('product','service','standalone-product')`)
.all() as { code: string; fields: string }[];
const modelUpdates: { code: string; next: string; before: string[] }[] = [];
for (const row of modelRows) {
let fields: { name: string; fields?: SubField[] }[];
try {
fields = JSON.parse(row.fields);
} catch {
console.error(`✗ ${row.code}: fields 不是合法 JSON,拒绝改写`);
process.exit(2);
}
const source = (CONTENT_TYPE_CONFIGS as unknown as Record<string, { model: { fields: { name: string; fields?: SubField[] }[] } }>)[row.code]
?.model.fields.find((f) => f.name === 'caseStudies');
if (!source?.fields) {
console.error(`✗ ${row.code}: 代码真源里找不到 caseStudies 定义,拒绝改写`);
process.exit(2);
}
const want = source.fields.filter((f) => f.name === 'authorized' || f.name === 'basis');
if (want.length !== 2) {
console.error(`✗ ${row.code}: 真源里 caseStudies 缺 authorized/basis,先修 content-types.ts`);
process.exit(2);
}
const beforeNames: string[] = [];
let changed = false;
for (const f of fields) {
if (f.name !== 'caseStudies' || !Array.isArray(f.fields)) continue;
for (const w of want) {
const had = f.fields.some((x) => x.name === w.name);
if (!had) {
f.fields.push(w);
beforeNames.push(`+${w.name}`);
changed = true;
}
}
}
if (changed) modelUpdates.push({ code: row.code, next: JSON.stringify(fields), before: beforeNames });
}
// ── 2) navigation 行:改写成由代码真源派生的形状 ────────────────────────────
const navRow = db
.prepare(`select id, data from ContentItem where modelCode = 'navigation' limit 1`)
.get() as { id: string; data: string } | undefined;
const derivedNav = {
slug: 'default',
title: '导航菜单',
mainNav: NAVIGATION_V2,
megaDropdown: MEGA_DROPDOWN_DATA,
};
let navUpdate: { id: string; next: string; beforeLabels: string[]; afterLabels: string[] } | null = null;
if (navRow) {
let before: { mainNav?: { label?: string }[] } = {};
try {
before = JSON.parse(navRow.data);
} catch {
before = {};
}
const beforeLabels = (before.mainNav ?? []).map((x) => String(x.label ?? '?'));
const afterLabels = NAVIGATION_V2.map((x) => x.label);
if (JSON.stringify(before) !== JSON.stringify(derivedNav)) {
navUpdate = { id: navRow.id, next: JSON.stringify(derivedNav), beforeLabels, afterLabels };
}
} else {
say('· navigation 行不存在 ⇒ 跳过(不新建;代码真源已能供数)');
}
// ── 3) 自证:用真实解析器验收派生出来的形状 ────────────────────────────────
const verdict = resolveNavigation(derivedNav);
say(`· 解析器验收:source=${verdict.source} issues=${verdict.issues.length}`);
if (verdict.source !== 'cms' || verdict.issues.length > 0) {
for (const i of verdict.issues) say(` ✗ ${i}`);
console.error('✗ 派生形状未通过 resolveNavigation ⇒ 本次中止(不写库)');
process.exit(1);
}
// ── 4) 计划 / 执行 ─────────────────────────────────────────────────────────
say(`· ContentModel 需补字段:${modelUpdates.length} 个(${modelUpdates.map((m) => m.code + ':' + m.before.join(',')).join(' | ') || '无'})`);
if (navUpdate) {
say(`· navigation 行需改写:${navUpdate.beforeLabels.join('/')} → ${navUpdate.afterLabels.join('/')}`);
} else {
say('· navigation 行已是目标形状');
}
if (!apply) {
say('\n[dry-run] 未写入。加 --apply 执行。');
process.exit(0);
}
const updateModel = db.prepare(`update ContentModel set fields = ?, updatedAt = CURRENT_TIMESTAMP where code = ?`);
const updateNav = db.prepare(`update ContentItem set data = ?, updatedAt = CURRENT_TIMESTAMP where id = ?`);
db.exec('begin');
try {
for (const m of modelUpdates) updateModel.run(m.next, m.code);
if (navUpdate) updateNav.run(navUpdate.next, navUpdate.id);
db.exec('commit');
} catch (e) {
db.exec('rollback');
console.error('✗ 写入失败已回滚:', (e as Error).message);
process.exit(1);
}
// 写后复查(不是"写完就算")
const checkNav = db.prepare(`select data from ContentItem where modelCode = 'navigation' limit 1`).get() as { data: string } | undefined;
const checkVerdict = checkNav ? resolveNavigation(JSON.parse(checkNav.data)) : verdict;
const checkModels = db
.prepare(`select code, fields from ContentModel where code in ('product','service','standalone-product')`)
.all() as { code: string; fields: string }[];
const bad = checkModels.filter((r) => !/authorized/.test(r.fields) || !/basis/.test(r.fields));
say(`\n[applied] models=${checkModels.length} 缺字段=${bad.length} · navigation source=${checkVerdict.source} issues=${checkVerdict.issues.length}`);
if (bad.length > 0 || checkVerdict.source !== 'cms' || checkVerdict.issues.length > 0) {
console.error('✗ 写后复查未通过');
process.exit(1);
}
say('✓ 写后复查通过');