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:
1 parent
8799a9658e
commit
cee21e178a
3 files changed
+265
No files matched your search
@@ -1140,3 +1140,25 @@ webkit/mobile 的 Tab 引擎差异取证法、`pollBoundingBox` 的二次读取
|
||||
**视觉基线与"seed 内容"耦合** —— 重跑 `db:seed` 或改 CMS 文案后,内容型基线会失效,
|
||||
必须按"内容变更 ⇒ 重采 + 只读复验"处理,不能把它读成样式回归。反过来,
|
||||
将来若看到只有 `/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)仍由决策人显式发起**。
|
||||
@@ -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. 视觉基线虽已逐名清单化,但**逐张人工读图追认**仍需决策人分批完成。
|
||||
@@ -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('✓ 写后复查通过');
|
||||
Reference in new issue
Block a user