From 81bdeebc6403fb8b2c0455175239d862dde8ecce Mon Sep 17 00:00:00 2001 From: zhangxiang Date: Thu, 8 Oct 2026 17:41:36 +0800 Subject: [PATCH] =?UTF-8?q?docs(qa):=20=C2=A710=20=E7=94=9F=E4=BA=A7?= =?UTF-8?q?=E5=8F=91=E5=B8=83=E8=AE=B0=E5=BD=95=E4=B8=8E=E4=BA=8B=E6=95=85?= =?UTF-8?q?=E5=A4=8D=E7=9B=98=20+=20deployment=20=C2=A7=E4=B8=83=20web=20r?= =?UTF-8?q?oot=20=E5=A5=91=E7=BA=A6=20+=20lessons=20=C2=A75.34?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - §10:发布内容/序列(build EXIT=0 → 真 prod.db 副本预生产演练 14 路由全 200 → prod.db.bak.20261008_173048 快照 → dist_backup_20261008_173111 → DEPLOY_EXIT=0) - §10.2:本次部署引入的回归与恢复(≈4 分钟),并用 nginx access.log 现取 10-07 同一 URL 为 200 的证据把回归定性为自己引入而非既有状态 - §10.4:Playwright 三页线上健康证据(stylesheets=2、品牌红命中、4xx/5xx GET=0、 console error=0) - §10.5:发布后仍未闭合项,含 AUTH-D2 的真凭据——prod.db 里 Permission.modelCode 仍是旧码 team/legal(各 11 条授予)而 ContentModel 已是 team-page/legal-page/ contact-page 等 16 个模型;并列出三条 seed 执行候选与建议 - deployment.md §七:两种产物形态的契约、镜像生成命令、回滚须连容器一起、 compose/Dockerfile 从不同步导致的挂载漂移 - lessons §5.34:三条规则 + 两条取证法 + 管理归零(预生产演练、资源级门禁) --- docs/acceptance/qa-tracker.md | 50 +++++++++++++++++++++++++++++++++++ docs/deployment.md | 23 ++++++++++++++++ docs/lessons-learned.md | 19 +++++++++++++ 3 files changed, 92 insertions(+) diff --git a/docs/acceptance/qa-tracker.md b/docs/acceptance/qa-tracker.md index 7d91416..61877ba 100644 --- a/docs/acceptance/qa-tracker.md +++ b/docs/acceptance/qa-tracker.md @@ -387,3 +387,53 @@ S-3(about/contact/erp-upgrade 无 revalidate + revalidateTag no-op,涉渲染 | `AGENTS.md`(**被 `.gitignore:316` 排除,仅本机**) | 视觉回归行的 21 失败/104 通过/94-31 系列读数标注作废并指向 §9;lint 行补 2026-10-08 一手复测 104;`-u` 模式描述同 `quality-gates.md` 更正 | **PR 描述**:新建 `.pr-seal-2026-10-08.md`(覆盖 `a0328a6..HEAD` 全链,含 §8/§9 两轮),`bash scripts/check-pr-checklist.sh .pr-seal-2026-10-08.md` ⇒ **EXIT=0 通过**。按用户裁定与 `.pr-seal-2026-09-*.md` 同列**保持未跟踪**,需要时直接粘进 Gitea 表单;上一份 `.pr-seal-2026-09-30.md` 的叙述已停在 seal 轮,**不得再用于建 PR**。 + +--- + +## §10 2026-10-08 · 生产发布(用户指令「提交变更并发布到生产」) + +### 10.1 发布内容与序列 + +| 步 | 动作 | 读数 / 凭据 | +|---|---|---| +| 1 | `npm run build` | **BUILD_EXIT=0**,产物 BUILD_ID `uiV6QrbCH7jmurgLVp-nd`(树 `19079e1`,代码封版点仍是 `a0328a6`);`postbuild` 已装配 standalone 三件套(`dist/standalone/{server.js,dist/static,public}`) | +| 2 | 预生产演练(**部署前**) | 从服务器取 `prod.db` 副本(413,696 B)→ `PORT=3111 DATABASE_URL=file:/tmp/prod-copy.db node dist/standalone/server.js` → 14 条真实路由**全 200**(`/`、`/products/{,erp,erp-upgrade}`、`/solutions/{,manufacturing}`、`/about{,/brand}`、`/contact`、`/news`、`/cases`、`/services`、`/methodology`、`/admin/login`) | +| 3 | 生产库快照 | `data/prod.db.bak.20261008_173048`(AUTH-D2 的硬前置;此前仅有 `bak.20260820_093111`) | +| 4 | 远端 dist 快照 | 脚本自动产出 `dist_backup_20261008_173111` | +| 5 | `./scripts/deploy.sh deploy --skip-build` | **DEPLOY_EXIT=0**;步骤 3/5/6/6.5 全绿,容器重建后 `curl 127.0.0.1:3000` 就绪,`verify_remote` 五页 200 | + +上传前把 `dist/dev`(606M) 与 `dist/cache`(193M) 清掉,实际上传 205M(服务器出网带宽仅 ≈1Mbps,见 `docs/deployment.md` §6.5)。 + +### 10.2 本次部署引入的线上回归(已恢复,≈4 分钟) + +**症状**:部署后首页 HTML 200,但其引用的 `/_next/static/chunks/*.js|*.css`、`/favicon.ico` **全 404**(nginx 应答,`try_files $uri =404`)⇒ 真实用户看到的是无 CSS、无 JS 的破站。 + +**根因**:远端 nginx 的站点根 = 上传后的 `dist/`,要求磁盘上存在 `dist/_next/static/**`;而 `next build` 出的是 `dist/static/**`,`postbuild` 只补容器形态。**这份「web root 镜像」历史上由旧发布流程产出**(`dist_backup_20260905_113209/` 顶层确有 `_next/static` 与合并的 `fonts/ images/ *.svg`),本次 `rsync --delete` 把它抹掉了。`nginx access.log` 现取 **2026-10-07**(部署前)同一 URL 为 200 ⇒ 确证是本次部署引入,非既有状态。 + +**恢复**:在服务端补做镜像(`mkdir -p dist/_next && cp -R dist/static dist/_next/static && cp -R public/. dist/`,**纯新增、零删除**)+ `chown www-data` / `chmod 755`。恢复后:首页与 `/products/erp` 引用的 **19+ 件资源全 200**;`/images/logo-white.svg` 仍 404 属正确行为(该路径在 `public/` 里不存在,是我构造的探测 URL)。 + +**门禁盲区(管理归零)**:`verify_remote` 只 curl 五个 HTML 路径,所以它在破站状态下打印了「✅ 生产环境验证通过 / 🎉 部署成功」。**HTML 200 ≠ 站点可用**。 + +### 10.3 已落地的两处修复(`scripts/deploy.sh`,同笔提交) + +1. **步骤 1.5**:上传前本地生成 web root 镜像(`dist/static → dist/_next/static`、`public/. → dist/`),并在 `dist/static` 缺失时**终止部署**而非静默继续。 +2. **`verify_remote` 资源级断言**:部署后从首页 HTML **实际引用的 URL** 取前 5 个 `/_next/static/*.{js,css}` + `/favicon.ico`,逐个断言 200,任一非 200 即 `return 1`。**负对照已实测**:把取样 URL 换成不存在者 ⇒ `RED 404` 且 `failed=1`,证明该断言可失败。`bash -n` 通过,`deploy --dry-run` 复跑 ⇒ 六项取样全 200。 + +### 10.4 线上健康证据(Playwright 无头,`chromium`) + +| URL | stylesheets | h1 / 字号 | 品牌红 | 4xx·5xx GET | console error | +|---|---|---|---|---|---| +| `/` | 2 | 「让每一家企业都拥有数据驱动的决策能力」/ 81px `geistSans` | 命中 | **0** | **0** | +| `/products/erp` | 2 | 「睿新ERP管理系统」/ 81px | 命中 | **0** | **0** | +| `/contact` | 2 | 「随时欢迎聊一聊」/ 108px | 命中 | **0** | **0** | + +`TOTAL_FAILED_GETS=0`。安全头单次下发已核(`server: nginx` + CSP/HSTS/XP 等一组,无重复头报错);线上 nginx 的 `X-Frame-Options: SAMEORIGIN` 与仓内 `next.config.mjs` 的 `DENY` 叠加问题仍在(判定书 §5 已登记,修复须单独投递 nginx conf)。 + +### 10.5 发布后仍未闭合(须单独授权) + +| # | 项 | 现状与依据 | +|---|---|---| +| AUTH-D2 | **生产 `db:seed` 未执行**(快照已就绪) | 真凭据:`prod.db` 里 `Permission.modelCode` 仍是旧码 `team`/`legal`(各 11 条授予),而 `ContentModel.code` 已是 `team-page`/`legal-page`/`contact-page`/`navigation`/`methodology`/`page-copy`/`site-config`(共 16 个模型)⇒ `src/lib/permissions.ts:26` 精确匹配下,非 `super_admin` 四个角色对这些模型**无授予**。机制待定:服务器无 `src/`、`prisma/`(只有 `dist/`+`public/`+`data/`),`Dockerfile.prod` 是纯 COPY 镜像 ⇒ 无法在容器内直接跑 `npx tsx prisma/seed.ts`;宿主有 node v20.20.2 但无仓库源码。三条候选:① 宿主 `git clone` 后 `npm ci` 跑 seed(服务器出网 ≈1Mbps,248MB 全量 clone 约 35 分钟);② 本地对 `prod.db` 副本跑 seed 后整库换回(SQLite 换文件有并发写风险,需停容器);③ 把 seed 做成可 `docker cp` 进容器执行的产物。**建议 ①**,且需明文授权 | +| H | compose / Dockerfile 配置漂移 | 服务器 `docker-compose.server.yml` 仍是旧挂载 `./uploads:/app/uploads`(仓内已修成 `/app/public/uploads`),`deploy.sh` 从不同步 compose/Dockerfile ⇒ 上传落进容器可写层、重建即丢。详述见 `docs/deployment.md` §七 | +| I | `cmd_rollback` 不重建容器 | 回滚只恢复 `dist/` + 重载 nginx,会留下「旧静态 + 新服务端」的 Server Reference ID 不匹配。手工正确姿势已写进 `docs/deployment.md` §七 | +| J | PR / 合并 `main` | 生产已运行 `a0328a6` 代码,但 `origin/main` 落后 44 笔且**无 PR 记录**(本环境无 Gitea token)。治理缺口:产物与 main 不同源。人工入口 `https://git.f.novalon.cn/novalon/novalon-website/pulls/new/qa/seal-2026-09-28`,描述用 `.pr-seal-2026-10-08.md` | diff --git a/docs/deployment.md b/docs/deployment.md index f8c5076..213ef7f 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -578,3 +578,26 @@ echo " 3. 重载 Nginx: docker exec novalon-nginx-secure nginx -s reload" - **jenkins 容器**:以 root 运行且挂载 `/var/run/docker.sock` 与 `/root/.ssh`(CI 构建需要,但一旦被攻破即等于宿主机沦陷,建议评估最小权限方案) - **遗留 forgejo 引用**:`dist_backup_20260422_161751/` 与 `novalon-website/.woodpecker.yml` 等旧文件中仍含 forgejo/woodpecker 配置,属历史归档,无需处理 - **监控缺失**:本次攻击 2026-08-11 开始,3 天后才被发现;建议配置 fail2ban + 容器日志告警 + 定时恶意文件扫描 + +## 七、发布链的 web root 镜像(2026-10-08 线上事故后新增) + +**契约**:远端 nginx 的站点根就是 `deploy.sh` 上传后的 `dist/`——`novalon-nginx/nginx-static-production.conf:132` 写 `root /var/www/novalon;`,而该 mount 指向宿主 `/home/novalon/docker-app/novalon-website/dist`(`docker inspect novalon-nginx-secure` 现取)。同文件 `:136-142` 的 `location /_next/static/ { try_files $uri =404; }` 因此要求磁盘上存在 **`dist/_next/static/**`**,而不是 `dist/static/**`。 + +但 `next build` 的产物布局是 `dist/static/**`(无 `_next` 前缀)+ 独立的 `public/**`,而 `postbuild`(`package.json`)只为 **standalone 容器**装配 `dist/standalone/{dist/static,public}`——**两者不是同一份形态**。所以上传前必须另生成一份「nginx web root 镜像」: + +```bash +mkdir -p dist/_next && cp -R dist/static dist/_next/static && cp -R public/. dist/ +``` + +该步骤已固化进 `scripts/deploy.sh` 的 **步骤 1.5**(含 `dist/static` 缺失即终止部署的前置校验)。 + +**事故(2026-10-08 17:31)**:镜像步骤缺失时,`rsync -avz --delete dist/` 会**抹掉上一次部署留下的镜像**,于是新 `dist/` 只有 `static/` 与 `standalone/`。后果是 nginx 对 `/_next/static/chunks/*.{js,css}`、`/favicon.ico`、`/images/*` 全部返回 404,而**页面本身仍 200**——`deploy.sh` 的 `verify_remote` 只 curl 五个 HTML 路径,于是它打印「✅ 生产环境验证通过 / 🎉 部署成功」,实际线上是无 CSS、无 JS 的破站。恢复:在服务端补做镜像(纯新增,不删任何东西),约 4 分钟后资源全 200。 + +**为什么旧部署没红**:`dist_backup_20260905_113209/` 顶层确有 `_next/static` 与合并进根的 `fonts/ images/ *.svg`,即历史发布流程产出过这份镜像;`nginx access.log` 现取 2026-10-07(本次部署前)`/_next/static/chunks/*.js` 为 **200**,证明回归由本次部署引入而非既有状态。 + +**已加的门禁**(同文件 `verify_remote`):部署后从**首页 HTML 实际引用的 URL** 里取前 5 个 `/_next/static/*.{js,css}` + `/favicon.ico` 逐个断言 200,任一非 200 即 `return 1`。负对照已实测:把取样 URL 换成不存在者 ⇒ 输出 `RED 404` 且 `failed=1`,不是恒绿断言。 + +**仍未闭合的两条(须单独授权,勿夹带)**: + +1. `cmd_rollback` 只恢复 `dist/` 并重载 nginx,**不重建 Next.js 容器** ⇒ 若在新容器已起的情况下回滚,会出现「旧静态资源 + 新服务端代码」的 Server Reference ID 不匹配。正确手工回滚 = 恢复 `dist_backup_*` 后**再**跑一次 `docker-compose -f docker-compose.server.yml build && up -d`。 +2. 服务器侧 `docker-compose.server.yml` 仍是旧挂载 `./uploads:/app/uploads`,而仓内版本已改为 `./uploads:/app/public/uploads`(`src/lib/media/storage.ts:141` 的落盘根是 `cwd/public/uploads`)。`deploy.sh` **从不同步 compose 与 Dockerfile**,所以该修复从未生效——现取 `docker inspect novalon-website` 的 Mounts 仍是 `/app/uploads`。影响:后台上传写进容器可写层,重建即丢;宿主 `./uploads` 至今只有两个空目录(`image/`、`document/`),无数据可损。 diff --git a/docs/lessons-learned.md b/docs/lessons-learned.md index 1fbc544..5c60908 100644 --- a/docs/lessons-learned.md +++ b/docs/lessons-learned.md @@ -523,6 +523,24 @@ Object.defineProperty(window, 'requestAnimationFrame', { configurable: true, val **来源**:`docs/acceptance/2026-10-08-baselines/attribution.md` §5、`docs/acceptance/qa-tracker.md` §9.4(含本条的作废声明与更正)、`src/components/detail/detail-product-value.tsx:70-100`、`node_modules/playwright/lib/program.js:202`。 +### 5.34 「🎉 部署成功」之后线上是破站:HTML 全 200,而它引用的 CSS/JS 全 404 + +**事故(2026-10-08 17:31)**:`./scripts/deploy.sh deploy` 打完 `DEPLOY_EXIT=0`、五个页面全 200、脚本自己输出「✅ 生产环境验证通过 / 🎉 部署成功」。但用 `curl` 取首页 HTML 里**实际引用**的 `/_next/static/chunks/*.js|*.css` 与 `/favicon.ico`,全部 **404**(`server: nginx` 应答,`try_files $uri =404`)⇒ 真实用户打开的是无样式、无脚本的破站。恢复耗时约 4 分钟,且是**我在脚本判绿之后另做复核**才发现的——不是门禁抓到的,是人抓到的。 + +**根因是两种产物形态 + 一次 `--delete`**:远端 nginx 的站点根就是上传后的 `dist/`(`nginx-static-production.conf:132` `root /var/www/novalon;`,而该 mount 指向宿主 `.../novalon-website/dist`),`location /_next/static/` 因此要求磁盘上有 **`dist/_next/static/**`**;但 `next build` 出的是 `dist/static/**`(无 `_next` 前缀),`postbuild` 只补 **standalone 容器**形态。历史上那份「web root 镜像」是旧发布流程手工产出的(`dist_backup_20260905_113209/` 顶层确有 `_next/static` 与合并进来的 `fonts/ images/ *.svg`),本次 `rsync -avz --delete` 把它抹掉 ⇒ 第一次「干净部署」即红。 + +**三条规则**: + +1. **部署后验证必须从页面实际引用的 URL 取样,而不是只查页面路径**。已固化进 `verify_remote`:抓首页 HTML → 取前 5 个 `/_next/static/*.{js,css}` + `/favicon.ico` → 逐个断言 200,任一非 200 即 `return 1`。并做**负对照**:把取样 URL 换成不存在者,实测输出 `RED 404` 且 `failed=1`——不能失败的门禁不是门禁(同 §5.23、§5.30 的「空集合 `every` 为真」族)。 +2. **`rsync --delete` 的目标目录若被别的流程写入,本脚本必须自己重新生成那部分内容**。否则镜像/派生文件会在第一次部署时被静默删除,而删除动作在日志里完全不可见。修法是把生成步骤放进上传之前(`deploy.sh` 步骤 1.5),并对前置条件缺失(`dist/static` 不存在)**终止部署**而非继续。 +3. **改任何一侧产物形态前,先确认另一侧的契约**:`standalone`(容器内 `COPY dist/standalone`、`dist/static`、`public`)与 nginx web root(`_next/static` + 根级 public)不是同一棵树。`Dockerfile.prod` 两侧 md5 一致(`0ccd495490694a6bf71d4ff17270d2ed`)排除了镜像构建漂移,问题只出在上传目录。 + +**区分「我引入」与「既有」的取证法(值得复用)**:`nginx access.log` 里按 URL grep 历史状态码——本次现取 **2026-10-07**(部署前一日)`/_next/static/chunks/*.js` 为 **200**,一句话就把回归定性成自己引入的,不必猜。同理,`docker inspect <容器> --format '{{range .Mounts}}...'` 看**真实挂载**,比读仓内 compose 可靠:仓里 `docker-compose.server.yml` 已把 uploads 改成 `/app/public/uploads`,服务器跑的仍是旧的 `/app/uploads`,因为 `deploy.sh` 从不同步 compose/Dockerfile(登记为发布链漂移,见 `docs/deployment.md` §七)。 + +**管理归零**:① 发布类脚本的「成功」判据必须包含**资源级**断言,已写进 `verify_remote`;② 生产发布前新增一道**预生产演练**——取真 `prod.db` 副本、用同一份产物在本地端口起 `node dist/standalone/server.js` 打 14 条路由(本次全 200,才继续上线);③ 回滚路径要连容器一起回(`cmd_rollback` 只恢复 `dist/`,会留下「旧静态 + 新服务端」的 Server Reference ID 不匹配),正确手工步骤已写进 `docs/deployment.md` §七。 + +**来源**:`docs/acceptance/qa-tracker.md` §10(时间线、恢复命令、Playwright 三页 0 失败资源证据)、`scripts/deploy.sh`(步骤 1.5 与资源断言)、`/home/novalon/docker-app/novalon-nginx/nginx-static-production.conf:132,136-142`、`dist_backup_20260905_113209/` 目录形态、`nginx access.log` 2026-10-07 状态码。 + ## 6. 代码组织 ### 6.1 组件版本膨胀 @@ -577,3 +595,4 @@ Object.defineProperty(window, 'requestAnimationFrame', { configurable: true, val | 2026-09-23 | 增加 §5.30(覆盖率门禁 `collectCoverageFrom` 不含 `src/app/**` ⇒ route handler 全在棘轮外,专项审查找出 3 个 P1:`admin/stats` 只验会话即返回跨模型草稿标题、`checkUserPermission` 从不读 User 行使停用账号旧令牌 24h 内仍可用、B-6 的 `isInternalRedirect` 定义成私有函数致姊妹路由 `draft/disable` 开放重定向复活。管理归零:安全抽象必须可导入、修完要 grep 函数名看命中数是否等于应有数、每处修复做「临时移除 guard ⇒ 用例判红 ⇒ 恢复转绿」的 RED 实测、改共享鉴权函数打爆测试桩是信号不是障碍 | 2026-09-23 `src/app/**` 盲区专项审查(N-17..N-21)+ 三项修复与 RED 探针 | | 2026-09-30 | 增加 §5.32(「按文件名推断机制不存在」写出的假事实:DEC-N21b 记「无 middleware.ts ⇒ /admin 无服务端 gating」,实况是 Next 16 已改名 `src/proxy.ts` 且 `CLAUDE.md:108` 早已写明;同族第二例是「85 张基线未提交」而 `git ls-files` 实测 107 张全在库) | `src/proxy.ts:77-105`、`docs/acceptance/2026-09-30-seal/final-verdict.md` | | 2026-10-08 | 增加 §5.33(把「本轮零源码改动」误用成「参照与树同源」⇒ 将 `+30px` 判成运行期漂移;实际旧参照采集树是 `040951c`(09-22),当前树含 `a366bd1`(09-28 第五轮),根因是 Q-6 count-up 动画从 render 体迁入 `useEffect`,旧参照冻结了中间帧。附三条口径:归因须对「采集树 vs 当前树」、基线数量须标「例/张」、裸 `--update-snapshots` 实为 `changed` 模式不重写通过项) | `docs/acceptance/2026-10-08-baselines/{attribution.md,row-diff.cjs}`、`docs/acceptance/qa-tracker.md` §9.4 | +| 2026-10-08 | 增加 §5.34(`deploy.sh` 打印「🎉 部署成功」后线上实为破站:HTML 全 200 而首页引用的 CSS/JS/图标全 404。根因 = nginx web root 需要 `dist/_next/static/**`,而 `next build` 出 `dist/static/**`、`postbuild` 只补 standalone 形态,历史镜像被 `rsync --delete` 抹掉。三条规则:部署后验证须从页面实际引用的 URL 取样并做负对照;`--delete` 目标若被别的流程写入则本脚本须自行重新生成;改产物形态前先确认另一侧契约。附「用 nginx access.log 历史状态码区分我引入 vs 既有」与「`docker inspect` 看真实挂载而非读仓内 compose」两条取证法) | `docs/acceptance/qa-tracker.md` §10、`scripts/deploy.sh` 步骤 1.5 + 资源断言、`docs/deployment.md` §七 |