From 06b476c4e2573dd52e83632a749368ff2d2d7ae6 Mon Sep 17 00:00:00 2001 From: zijunchiang Date: Thu, 17 Sep 2026 04:44:30 +0800 Subject: [PATCH] =?UTF-8?q?test(accept):=20=E4=BA=A7=E7=89=A9=E7=BA=A7?= =?UTF-8?q?=E7=AB=AF=E5=88=B0=E7=AB=AF=E9=AA=8C=E6=94=B6=E8=87=AA=E5=8A=A8?= =?UTF-8?q?=E5=8C=96=20+=20=E5=AE=9E=E4=BD=93=E6=B3=A8=E5=86=8C=E6=A0=B8?= =?UTF-8?q?=E5=AF=B9=E8=90=BD=E5=88=B0=20dist=EF=BC=88v0.7.4=20=E5=AE=9E?= =?UTF-8?q?=E6=B5=8B=E5=85=A8=E9=80=9A=E8=BF=87=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 背景：`npm run verify` 跑的是源码与刚构建的 dist，而交付给部署方的是 `dist-release/*.tar.gz`；两者之间隔着「解包 → npm install --omit=dev → 迁移 → 起进程」四步。本项目三次生产事故（v0.7.0/v0.7.1 起不来、v0.7.3 场景上传 400、 v0.7.4 `No metadata for "Scene"`）全都只在产物真正跑起来时才暴露。 一、`scripts/check-bootstrap.mjs` 新增「产物级实体注册核对」 直接读包内 `dist/entities/`：逐个 import 每个 *.entity.js（@Entity() 装饰器 在模块加载时写 metadata），要求 * 每个实体文件里被 @Entity() 装饰的类都在 ENTITIES 里； * ENTITIES 里不允许有未装饰的成员；不允许重复； * Scene 必须注册（点名）。 为什么必须单独有这一条：漏注册实体**不影响启动**（TypeORM 只按 ENTITIES 注册， DI 图照样解析、/health 正常、migrationsPending 0），只在第一次查该实体时抛 `No metadata`，导致 /api/scenes、/api/catalog/export、/api/catalog/version、 /api/reviews?status=pending 全部 500 —— 客户端一个目录都拉不到。 原来的启动冒烟与 entities-registry.spec.ts（查 src/）都抓不到它。 反向验证（在真实 v0.7.4 发布包里复现生产缺陷）：把包内 dist/entities/index.js 的 ENTITIES 去掉 Scene 后，核对立即失败并给出 「scene.entity.js 里的 Scene 没有注册进 ENTITIES」与「ENTITIES 里没有 Scene」； 还原后通过。 二、`scripts/accept-release.sh`（新增）：一个 tar.gz 的产物级端到端验收 解包 → 装生产依赖 → 跑迁移 → 起服务 → 校验 /health 关键字段 （版本 / 数据库 / migrationsPending / scenes.available）→ 产物级实体注册核对 （用仓库当前的 checker 覆盖包内旧版本，验收标准以最新为准）→ 跑发布包自带的 test/smoke.mjs → 停服务。只需要一个现成的 MySQL/MariaDB，不装数据库 （与项目「不部署 MySQL」的边界一致）。 实测（opendance-web-v0.7.4.tar.gz + 真实 MySQL 9.7.2，全新库从零迁移）： ✓ /health version=0.7.4 与 package.json 一致 ✓ 数据库已连接（opendance_accept，pending=0） ✓ scenes.available=true（生产 v0.7.3 是 false + No metadata） ✓ 产物级实体注册核对通过：6 个实体文件全部注册进 ENTITIES（含 Scene） == 结果：80 通过 / 0 失败 == 冒烟 [7] 段即 ④ 验收：POST /api/scenes 201、一律 pending、GLB 直传不重编码、 glbUrl 生成、重力/风/摩擦/坡度/出生点/相机模式按配置原样入库、越界夹紧与非法 枚举回退、审核通过后 catalog/export 的 scenes[] 带完整物理参数与 GLB/缩略图字段、 目录指纹纳入场景变更、详情、状态过滤、DELETE 204。 `npm run verify` 全绿：契约 6 项 / 35 路由 / 版本一致 / 295 项测试 / build / 产物级注册核对 / 启动冒烟。 --- tasks/015-scene-management.md | 65 ++++++++ web-server/scripts/accept-release.sh | 198 +++++++++++++++++++++++++ web-server/scripts/check-bootstrap.mjs | 117 ++++++++++++++- 3 files changed, 379 insertions(+), 1 deletion(-) create mode 100755 web-server/scripts/accept-release.sh diff --git a/tasks/015-scene-management.md b/tasks/015-scene-management.md index cd63d28..cbd1aef 100644 --- a/tasks/015-scene-management.md +++ b/tasks/015-scene-management.md @@ -177,3 +177,68 @@ TypeORM 的 DataSource **只按 `ENTITIES` 注册 metadata**，漏注册的后 * 核对 `AddScenes` 迁移文件确实存在（迁移文件缺失时 `showMigrations()` 仍会显示 0 个待执行）。 这类"漏注册"既过得了 `tsc`，也过得了启动冒烟（应用能启动），因此**只能靠静态核对兜住**。 + +## 产物级端到端验收（v0.7.4 发布包实测） + +上面那条"只能靠静态核对兜住"其实**还不够**：静态核对查的是 `src/`， +而交付给部署方的是 `dist-release/*.tar.gz`。两者之间隔着 +「解包 → npm install --omit=dev → 迁移 → 起进程」四步， +`nest build` 没重编译、打包带了旧的 `dist/` 都会让校验全绿而产物仍是坏的。 + +因此补了两层，并把整条验收自动化： + +### 1. 产物级实体注册核对（`scripts/check-bootstrap.mjs` 新增一段） + +直接读**产物**里的 `dist/entities/`：逐个 `import` 每个 `*.entity.js` +（`@Entity()` 装饰器在模块加载时写 metadata），要求 + +- 每个实体文件里被 `@Entity()` 装饰的类都在 `ENTITIES` 里； +- `ENTITIES` 里不允许出现没有 `@Entity()` 装饰的成员； +- `ENTITIES` 不允许重复； +- `Scene` 必须注册（点名，便于一眼看出是不是又漏了场景）。 + +原先的启动冒烟只证明"DI 图可解析"，而**漏注册实体恰恰不影响启动** —— +所以这条必须单独存在。已接入 `npm run verify`。 + +**反向验证**（在真实 v0.7.4 发布包里复现生产缺陷）：把产物 +`dist/entities/index.js` 的 `ENTITIES` 去掉 `Scene` 后： + +``` +✗ 产物级实体注册核对失败（dist/entities 与 ENTITIES 不一致）： + - scene.entity.js 里的 Scene 没有注册进 ENTITIES —— 查询该实体会抛 + `No metadata for "..." was found.`（接口直接 500） + - ENTITIES 里没有 Scene —— 场景管理相关接口会全部 500（生产事故根因） +退出码=1 +``` + +### 2. 发布包级端到端验收（`scripts/accept-release.sh`，新增） + +对一个 tar.gz 一键跑完：解包 → 装生产依赖 → 迁移 → 起服务 → 检查 +`/health` 关键字段（版本 / 数据库 / `migrationsPending` / **`scenes.available`**） +→ 产物级实体注册核对 → 跑**发布包自带的** `test/smoke.mjs` → 停服务。 +需要一个可连的 MySQL/MariaDB（脚本不装数据库，与项目边界一致）。 + +```bash +DB_HOST=127.0.0.1 DB_PORT=3306 DB_USER=opendance DB_PASS=*** DB_NAME=opendance_accept \ + ASSIMP_BIN=/usr/bin/assimp bash scripts/accept-release.sh dist-release/opendance-web-v0.7.4.tar.gz +``` + +**实测（v0.7.4 发布包 + 真实 MySQL 9.7.2）**： + +``` +✓ /health 的 version=0.7.4 与 package.json 的 0.7.4 一致 +✓ 数据库已连接（opendance_accept，pending=0） +✓ 没有未执行的迁移 +✓ scenes.available=true（false 时 error=null） +✓ 产物级实体注册核对通过：dist/entities/ 下 6 个实体文件全部注册进 ENTITIES（含 Scene） +== 结果：80 通过 / 0 失败 +产物级验收全部通过 +``` + +其中冒烟的 `[7]` 段就是本任务的验收：`POST /api/scenes` 201、一律 `pending`、 +GLB 直传不重编码、`glbUrl` 生成、**重力/风/地面摩擦/坡度/出生点/相机模式按配置原样入库**、 +越界值夹紧与非法枚举回退、审核通过后 `catalog/export` 的 `scenes[]` 带完整物理参数与 +GLB/缩略图字段、**目录指纹纳入场景变更**、`GET /api/scenes/:id`、按状态过滤、`DELETE` 204。 + +> 这一步同时排除了「Linux 上导出/打包产物与源码不一致」的可能： +> 跑的是发布包里**自带的** `dist/`、`scripts/`、`test/`，不是仓库源码。 diff --git a/web-server/scripts/accept-release.sh b/web-server/scripts/accept-release.sh new file mode 100755 index 0000000..7a34b6f --- /dev/null +++ b/web-server/scripts/accept-release.sh @@ -0,0 +1,198 @@ +#!/usr/bin/env bash +# ============================================================ +# OpenDance Studio Web 服务端 —— **发布产物级端到端验收** +# +# 为什么需要它：仓库里的 `npm run verify`（单元测试 + `check-bootstrap`）跑的是 +# **源码与刚构建的 dist**；而真正交付给部署方的是 `dist-release/` 里的 tar.gz。 +# 两者之间还隔着「解包 → npm install → 迁移 → 起进程」四步，历史上三次生产 +# 事故（v0.7.0/v0.7.1 起不来、v0.7.3 场景上传 400、v0.7.4 `No metadata for "Scene"`） +# 全都只在**产物真正跑起来**时才暴露。 +# +# 本脚本把那次验收完整自动化：解包发布包 → 装生产依赖 → 跑迁移 → 起服务 → +# 跑发布包自带的 `test/smoke.mjs` → 停服务 → 汇报。跑完你就得到一份 +# 「这个 tarball 能不能用」的结论，而不是「源码测试是绿的」。 +# +# 前置：需要一个可连的 **MySQL / MariaDB**（脚本不会安装数据库，与项目 +# 「不部署 MySQL」的边界一致）。本机验证时可用纯用户态方案，例如： +# npm i mysql-memory-server # 或任何现成实例 +# +# 用法： +# DB_HOST=127.0.0.1 DB_PORT=3306 DB_USER=opendance DB_PASS=xxx DB_NAME=opendance_test \ +# bash scripts/accept-release.sh dist-release/opendance-web-v0.7.4.tar.gz +# +# 可选环境变量： +# PORT / ADMIN_PORT 服务端口（默认 34100 / 34101，避免撞上真实服务） +# WORK_DIR 解包与存储目录（默认 mktemp -d） +# ASSIMP_BIN Assimp 可执行文件；设为空则跳过需要它的用例 +# SKIP_MIGRATE=1 跳过迁移（复用已有库） +# KEEP_RUNNING=1 跑完不杀进程（便于手工继续查） +# +# 退出码：0 全通过 / 1 有失败 / 2 用法或前置问题。 +# ============================================================ +set -uo pipefail + +PROJECT_DIR="$(cd "$(dirname "$0")/.." && pwd)" +cd "$PROJECT_DIR" + +TARBALL="${1:-}" +if [ -z "$TARBALL" ]; then + echo "用法：DB_HOST=... DB_USER=... DB_NAME=... bash scripts/accept-release.sh <发布包 tar.gz>" >&2 + exit 2 +fi +if [ ! -f "$TARBALL" ]; then + echo "✗ 找不到发布包：$TARBALL" >&2 + exit 2 +fi + +for name in DB_HOST DB_USER DB_NAME; do + if [ -z "${!name:-}" ]; then + echo "✗ 缺少环境变量 $name（需要现有 MySQL/MariaDB 连接信息）" >&2 + exit 2 + fi +done + +PORT="${PORT:-34100}" +ADMIN_PORT="${ADMIN_PORT:-34101}" +WORK_DIR="${WORK_DIR:-$(mktemp -d)}" +SKIP_MIGRATE="${SKIP_MIGRATE:-0}" +KEEP_RUNNING="${KEEP_RUNNING:-0}" + +log() { printf '\033[1;34m[accept]\033[0m %s\n' "$*"; } +fail() { printf '\033[1;31m[accept] ✗ %s\033[0m\n' "$*" >&2; FAILED=1; } +FAILED=0 + +log "发布包：$TARBALL" +log "工作目录：$WORK_DIR" +mkdir -p "$WORK_DIR" + +# ---- 1. 解包 ---- +log "解包…" +tar -xzf "$TARBALL" -C "$WORK_DIR" || { echo "✗ 解包失败" >&2; exit 1; } +PACKAGE_ROOT="$(find "$WORK_DIR" -maxdepth 1 -mindepth 1 -type d | head -1)" +SERVER_DIR="$PACKAGE_ROOT/web-server" +[ -d "$SERVER_DIR" ] || { echo "✗ 包里没有 web-server/ 目录" >&2; exit 1; } + +# ---- 2. 装生产依赖 ---- +# 与部署脚本一致：只装 dependencies，不装 devDependencies。 +log "安装生产依赖（npm install --omit=dev）…" +( cd "$SERVER_DIR" && npm install --omit=dev --no-audit --no-fund >"$WORK_DIR/npm-install.log" 2>&1 ) \ + || { echo "✗ 依赖安装失败，日志：$WORK_DIR/npm-install.log" >&2; tail -20 "$WORK_DIR/npm-install.log"; exit 1; } + +# ---- 3. 环境变量 ---- +cat >"$WORK_DIR/accept.env" <"$WORK_DIR/migrate.log" 2>&1 ) \ + || { echo "✗ 迁移失败，日志：$WORK_DIR/migrate.log" >&2; tail -30 "$WORK_DIR/migrate.log"; exit 1; } + log "迁移完成" +fi + +# ---- 5. 起服务 ---- +log "启动产物（node dist/main.js）…" +( cd "$SERVER_DIR" && nohup node dist/main.js >"$WORK_DIR/server.log" 2>&1 & echo $! >"$WORK_DIR/server.pid" ) +SERVER_PID="$(cat "$WORK_DIR/server.pid")" + +cleanup() { + if [ "$KEEP_RUNNING" != "1" ] && [ -n "${SERVER_PID:-}" ] && kill -0 "$SERVER_PID" 2>/dev/null; then + kill "$SERVER_PID" 2>/dev/null || true + sleep 2 + kill -9 "$SERVER_PID" 2>/dev/null || true + log "已停止服务（pid $SERVER_PID）" + fi +} +trap cleanup EXIT + +API="http://127.0.0.1:$PORT" +READY=0 +for _ in $(seq 1 60); do + if curl -sf -m 5 "$API/health" >"$WORK_DIR/health.json" 2>/dev/null; then READY=1; break; fi + if ! kill -0 "$SERVER_PID" 2>/dev/null; then break; fi + sleep 1 +done +if [ "$READY" != "1" ]; then + fail "服务 60 秒内没有就绪；日志：$WORK_DIR/server.log" + tail -30 "$WORK_DIR/server.log" + exit 1 +fi + +# ---- 6. 健康检查关键字段（④ 的生产根因就在这几项上）---- +log "健康检查：" +node -e ' +const fs = require("node:fs"); +const j = JSON.parse(fs.readFileSync(process.argv[1], "utf8")); +const pkg = JSON.parse(fs.readFileSync(process.argv[2], "utf8")); +let bad = 0; +const say = (ok, text) => { console.log(` ${ok ? "✓" : "✗"} ${text}`); if (!ok) bad = 1; }; +say(j.version === pkg.version, `/health 的 version=${j.version} 与 package.json 的 ${pkg.version} 一致`); +say(j.database.connected === true, `数据库已连接（${j.database.database}，pending=${j.database.migrationsPending}）`); +say(j.database.migrationsPending === 0, "没有未执行的迁移"); +say(j.scenes.available === true, `scenes.available=${j.scenes.available}（false 时 error=${JSON.stringify(j.scenes.error)}）`); +process.exit(bad); +' "$WORK_DIR/health.json" "$SERVER_DIR/package.json" || fail "健康检查关键字段不符合预期" + +# ---- 7. 产物级实体注册核对 ---- +# 用**当前仓库**的检查脚本去核对包内产物：验收标准应当是最新的，而不是 +# 「这个包自带的那份检查」（包里那份可能比现在旧，旧规则查不出新增的检查项）。 +log "产物级实体注册核对：" +CHECKER="$PROJECT_DIR/scripts/check-bootstrap.mjs" +if [ -f "$CHECKER" ] && ! cmp -s "$CHECKER" "$SERVER_DIR/scripts/check-bootstrap.mjs"; then + cp "$CHECKER" "$SERVER_DIR/scripts/check-bootstrap.mjs" + log " 已用仓库当前的 check-bootstrap.mjs 覆盖包内版本（验收标准以最新为准）" +fi +if ( cd "$SERVER_DIR" && node scripts/check-bootstrap.mjs >"$WORK_DIR/bootstrap.log" 2>&1 ); then + grep -E "^✓" "$WORK_DIR/bootstrap.log" | sed 's/^/ /' +else + fail "实体注册核对失败" + sed 's/^/ /' "$WORK_DIR/bootstrap.log" | tail -20 +fi + +# ---- 8. 发布包自带的端到端冒烟 ---- +log "端到端冒烟（发布包自带的 test/smoke.mjs）…" +if ( cd "$SERVER_DIR" && API_BASE="$API" node test/smoke.mjs >"$WORK_DIR/smoke.log" 2>&1 ); then + grep -E "^== 结果" "$WORK_DIR/smoke.log" | sed 's/^/ /' + grep -c "^ ✓" "$WORK_DIR/smoke.log" | sed 's/^/ 通过项：/' +else + fail "冒烟未全通过" + grep -E "^ ✗|^== 结果" "$WORK_DIR/smoke.log" | sed 's/^/ /' +fi + +# ---- 9. 契约快照与三端一致 ---- +log "包内契约快照：" +if [ -f "$PACKAGE_ROOT/contracts/VERSION" ]; then + sed 's/^/ /' "$PACKAGE_ROOT/contracts/VERSION" +else + fail "包内缺少 contracts/VERSION" +fi + +echo "" +if [ "$FAILED" -ne 0 ]; then + echo "============================================================" + echo " 产物级验收失败（日志目录：$WORK_DIR）" + echo "============================================================" + exit 1 +fi +echo "============================================================" +echo " 产物级验收全部通过（日志目录：$WORK_DIR）" +echo "============================================================" diff --git a/web-server/scripts/check-bootstrap.mjs b/web-server/scripts/check-bootstrap.mjs index 9fd56c9..4da091a 100644 --- a/web-server/scripts/check-bootstrap.mjs +++ b/web-server/scripts/check-bootstrap.mjs @@ -26,7 +26,8 @@ * 用法：node scripts/check-bootstrap.mjs */ import { spawn } from 'node:child_process'; -import { mkdtempSync, readFileSync } from 'node:fs'; +import { mkdtempSync, readFileSync, readdirSync } from 'node:fs'; +import { createRequire } from 'node:module'; import { tmpdir } from 'node:os'; import { dirname, join } from 'node:path'; import { fileURLToPath } from 'node:url'; @@ -60,12 +61,126 @@ const DB_STAGE_PATTERNS = [ const TIMEOUT_MS = Number(process.env.BOOTSTRAP_TIMEOUT_MS ?? 40_000); +/* ---------------------------------------------- 产物级实体注册核对 */ + +/** + * 就地核对**编译产物**里的实体注册，而不是源码。 + * + * 为什么必须有这一层：生产事故「`/health` 报 `No metadata for "Scene" was found.`」 + * 的根因是 `src/entities/index.ts` 的 `ENTITIES` 漏了 `Scene`。这类缺陷有三个特点： + * 1. **启动完全正常** —— TypeORM 只按 `ENTITIES` 注册 metadata，漏注册不影响 DI 图； + * 2. **`tsc` 与单元测试全绿** —— 类型没问题，`entities-registry.spec.ts` 只查源码； + * 3. 只有**第一次查该实体**时才抛（`/api/scenes`、`/api/catalog/export`、 + * `/api/reviews?status=pending` 全部 500，客户端一个目录都拉不到）。 + * 也就是说：源码层的校验挡不住「产物里的 ENTITIES 与 dist 里的实体文件不一致」 + * （例如 `nest build` 没重新编译、打包时带了旧的 dist）。 + * + * 因此按「校验必须落在产物上」的规则，这里直接读 `dist/entities/`： + * * 每个 `*.entity.js` 里被 `@Entity()` 装饰的类都必须在 `ENTITIES` 里； + * * `ENTITIES` 里不允许出现没有 `@Entity()` 装饰的成员（防复制粘贴写错）； + * * `ENTITIES` 不允许重复； + * * `Scene` 必须注册（点名，一眼看出是不是又漏了场景）。 + */ +function checkEntityRegistry() { + const requireFromServer = createRequire(join(serverDir, 'package.json')); + const errors = []; + + let storage; + try { + requireFromServer('reflect-metadata'); + storage = requireFromServer('typeorm').getMetadataArgsStorage(); + } catch (error) { + return { + errors: [ + `无法加载 typeorm（${error instanceof Error ? error.message : String(error)}）——` + + '请先在 web-server 目录执行 npm install', + ], + }; + } + + const entitiesDir = join(serverDir, 'dist', 'entities'); + let files; + try { + files = readdirSync(entitiesDir).filter((name) => name.endsWith('.entity.js')); + } catch (error) { + return { errors: [`无法读取 ${entitiesDir}：${error.message}（是否忘了 npm run build？）`] }; + } + if (files.length === 0) { + return { errors: [`${entitiesDir} 下没有任何 *.entity.js`] }; + } + + // 逐个 import：@Entity() 装饰器在模块加载时写入 metadata storage + const fileOfClass = new Map(); + for (const file of files) { + const module_ = requireFromServer(join(entitiesDir, file)); + let decorated = null; + for (const value of Object.values(module_)) { + if (typeof value === 'function' && storage.tables.some((t) => t.target === value)) { + decorated = value; + break; + } + } + if (!decorated) { + errors.push(`${file} 里没有找到被 @Entity() 装饰的类`); + continue; + } + fileOfClass.set(decorated, file); + } + + let entities; + try { + entities = requireFromServer(join(entitiesDir, 'index.js')).ENTITIES; + } catch (error) { + return { errors: [`无法加载 dist/entities/index.js：${error.message}`] }; + } + if (!Array.isArray(entities)) { + return { errors: ['dist/entities/index.js 没有导出数组形式的 ENTITIES'] }; + } + + const registered = new Set(entities); + for (const [cls, file] of fileOfClass) { + if (!registered.has(cls)) { + errors.push( + `${file} 里的 ${cls.name} 没有注册进 ENTITIES —— ` + + '查询该实体会抛 `No metadata for "..." was found.`（接口直接 500）', + ); + } + } + for (const cls of entities) { + if (!fileOfClass.has(cls)) { + errors.push(`ENTITIES 里的 ${cls?.name ?? String(cls)} 不是 dist/entities/ 下任何 @Entity() 类`); + } + } + if (registered.size !== entities.length) { + errors.push(`ENTITIES 有重复项（${entities.length} 项，去重后 ${registered.size} 项）`); + } + if (!entities.some((cls) => cls?.name === 'Scene')) { + errors.push('ENTITIES 里没有 Scene —— 场景管理相关接口会全部 500（生产事故根因）'); + } + + return { errors, count: entities.length, fileCount: files.length }; +} + function freePort(base) { // 用一个不常见的端口即可；连库失败是预期的，端口只要不撞上真实服务 return base + Math.floor(Math.random() * 200); } async function main() { + // ---------- 第一步：产物级实体注册核对（不需要进程与数据库）---------- + const registry = checkEntityRegistry(); + if (registry.errors.length > 0) { + console.error('✗ 产物级实体注册核对失败（dist/entities 与 ENTITIES 不一致）：'); + for (const message of registry.errors) console.error(` - ${message}`); + console.error(' 说明：TypeORM 只按 ENTITIES 注册 metadata，漏注册不影响启动，'); + console.error(' 但第一次查该实体会抛 No metadata，相关接口全部 500。'); + process.exit(1); + } + console.log( + `✓ 产物级实体注册核对通过：dist/entities/ 下 ${registry.fileCount} 个实体文件` + + `全部注册进 ENTITIES（共 ${registry.count} 项，含 Scene）`, + ); + const scratch = mkdtempSync(join(tmpdir(), 'opendance-boot-')); // 模拟 systemd：删掉 npm_* 环境变量（ExecStart=node dist/main.js 时它们不存在）