From 2433cd22a5321b82ab242f33d509a40f57f0581a Mon Sep 17 00:00:00 2001 From: zijunchiang Date: Thu, 17 Sep 2026 01:49:52 +0800 Subject: [PATCH] =?UTF-8?q?fix(boot):=20CatalogModule=20=E6=BC=8F=20import?= =?UTF-8?q?=20ScenesModule=20=E5=AF=BC=E8=87=B4=E4=BA=A7=E7=89=A9=E8=B5=B7?= =?UTF-8?q?=E4=B8=8D=E6=9D=A5=20+=20/health=20=E7=89=88=E6=9C=AC=E5=8F=B7?= =?UTF-8?q?=E9=94=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 两个都是**只有真正启动服务才会暴露**的缺陷，v0.7.0 / v0.7.1 的产物受影响。 1. 【致命】CatalogModule 漏 import ScenesModule CatalogService 因为 catalog/export 要下发 scenes[] 而注入 ScenesService，但 CatalogModule 的 imports 只列了 SongsModule / MotionsModule / ModelsModule。 Nest 的 DI 按模块解析，于是 node dist/main.js 在 bootstrap 阶段直接抛 UnknownDependenciesException: Nest can't resolve dependencies of the CatalogService (... ? ...) —— 服务完全起不来（装得上、起不来）。 为什么三层检查全绿：nest build/tsc 看不出运行时 DI；258 项单元测试直接 new 服务或测纯函数，从不编译 AppModule；打包脚本只校验文件清单与压缩包完整性。 修复：CatalogModule.imports 补上 ScenesModule。 2. /health 的 version 在原生部署下永远是 0.1.0 原实现 process.env.npm_package_version ?? '0.1.0'，而该变量只在 npm 脚本下 存在；正式部署是原生服务（ExecStart=node dist/main.js），npm 不参与 -> 恒为 undefined -> 回退到硬编码 0.1.0，与管理端左下角展示的 vX.Y.Z 冲突， 违反文档 11.2 第 4 条「可核对：Web 端至少与 GET /health 的 version 一致」。 修复：新增 src/config/app-version.ts 作为运行时唯一解析点 （APP_VERSION -> 运行入口旁/工作目录的 package.json（带包名校验） -> npm_package_version -> 显式 0.0.0），/health 改用 resolveAppVersion()， main.ts 启动首行也打印版本号。新增 12 项测试，其中一项显式模拟无 npm 环境变量的原生部署。 防线（都挂进了 verify 与打包脚本） - scripts/check-bootstrap.mjs：以正式部署方式（node dist/main.js、无 npm 环境 变量、不需要数据库）拉起真实产物，断言①无依赖解析类错误②启动日志的应用版本 等于 package.json ③已推进到数据库连接阶段。已做反向验证：删掉 ScenesModule 后该检查立刻失败。 - scripts/check-version.mjs（并入 contracts:check）：校验 web-server/package.json = admin/package.json = project.yaml，正则禁止 health.controller.ts 再出现硬编码版本回退，管理端已构建时断言产物 JS 含 vX.Y.Z。 - npm run verify 现在包含 bootstrap:check；package-release.sh 在构建后、打包前 各跑一次（构建管理端后再跑 version:check，因为此时才需要校验产物内版本）。 文档：README.md / README.txt 增加 v0.7.2 修订说明； tasks/011-version-display.md 与 tasks/015-scene-management.md 补「缺陷修复记录」 （含为什么当时没被发现的三层检查对照表）。 验证：npm run verify 通过（契约六项一致、35 条路由、258 项测试、nest build、 启动冒烟）；产物 opendance-web-v0.7.2.tar.gz sha256 f04ecc85d17517ec00754238616eb1237cdb2fe17440af6dce731827c0922b26。 --- README.md | 20 ++- README.txt | 28 +++- project.yaml | 4 +- scripts/package-release.sh | 5 + tasks/011-version-display.md | 31 ++++ tasks/015-scene-management.md | 27 ++++ web-server/admin/package.json | 2 +- web-server/package-lock.json | 6 +- web-server/package.json | 10 +- web-server/scripts/check-bootstrap.mjs | 175 +++++++++++++++++++++ web-server/scripts/check-version.mjs | 128 +++++++++++++++ web-server/src/catalog/catalog.module.ts | 6 + web-server/src/config/app-version.ts | 129 +++++++++++++++ web-server/src/health/health.controller.ts | 6 +- web-server/src/main.ts | 7 + web-server/test/app-version.spec.ts | 111 +++++++++++++ 16 files changed, 673 insertions(+), 22 deletions(-) create mode 100644 web-server/scripts/check-bootstrap.mjs create mode 100644 web-server/scripts/check-version.mjs create mode 100644 web-server/src/config/app-version.ts create mode 100644 web-server/test/app-version.spec.ts diff --git a/README.md b/README.md index 8824fb4..4db3bbe 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,15 @@ OpenDance Studio **阶段一**: Web 管理服务端(NestJS + TypeORM + 现有 My ## 状态 -**阶段一已完成**: T-WEB-001 -> T-WEB-016 全部落地,当前版本 **v0.7.1**(契约 `rest-api 0.5.0`、`websocket-keypoints 0.2.0`、`data-models 0.7.0`、`model-formats 0.5.0`、`skeleton-topology 0.2.0`、`database 0.4.0`)。 +**阶段一已完成**: T-WEB-001 -> T-WEB-016 全部落地,当前版本 **v0.7.2**(契约 `rest-api 0.5.0`、`websocket-keypoints 0.2.0`、`data-models 0.7.0`、`model-formats 0.5.0`、`skeleton-topology 0.2.0`、`database 0.4.0`)。 + +v0.7.2 修订(**修复产物"装得上、起不来"+ `/health` 报错版本号**): + +1. **`CatalogModule` 漏 import `ScenesModule`(致命)**:`CatalogService` 注入了 `ScenesService`(因为 `catalog/export` 要下发 `scenes[]`),但 `CatalogModule` 只在 `imports` 里列了 `SongsModule / MotionsModule / ModelsModule`。Nest 的 DI 是**按模块**解析的,于是 `node dist/main.js` 在 bootstrap 阶段直接抛 `UnknownDependenciesException` —— **v0.7.0 / v0.7.1 的产物根本起不来**(装得上、起不来)。而当时 `nest build` 通过、258 项单元测试全绿、打包脚本的产物完整性校验也通过,因为它们都**从不编译 AppModule**; +2. **新增启动冒烟 `scripts/check-bootstrap.mjs`(并挂进 `verify` 与打包脚本)**:以正式部署方式(`ExecStart=node dist/main.js`,**不带任何 npm 环境变量**、不需要数据库)拉起真实产物,断言①日志里没有依赖解析类错误(模块图可解析)②日志里的「应用版本 vX.Y.Z」等于 `package.json` 的 version ③启动确实推进到了数据库连接阶段。已做**反向验证**:把 `ScenesModule` 删掉后该检查立刻失败; +3. **`/health` 的版本号在原生部署下永远是 0.1.0**:原来用 `process.env.npm_package_version ?? '0.1.0'`,而该变量只在 npm 脚本下存在,正式部署是原生服务 → 为 `undefined` → 与管理端左下角展示的 vX.Y.Z 不一致,违反文档 §11.2 第 4 条「可核对」。新增 `src/config/app-version.ts` 作为**运行时唯一解析点**(`APP_VERSION` → 运行入口旁/工作目录的 `package.json`(带包名校验) → `npm_package_version` → 显式 `0.0.0`),`main.ts` 启动首行也打印版本号,便于与 `/health`、管理端核对; +4. **新增 `scripts/check-version.mjs`**(并入 `contracts:check`):校验 `web-server/package.json` = `admin/package.json` = `project.yaml`,**禁止** `health.controller.ts` 再出现硬编码版本回退;管理端已构建时断言产物 JS 内含 `vX.Y.Z`;打包脚本在构建管理端后再次执行; +5. 新增 12 项测试(`test/app-version.spec.ts`),其中一项显式模拟「无 npm 环境变量」的原生部署。 v0.7.1 修订(**契约补齐 + 文档补齐**,契约 `websocket-keypoints` 0.1.0 -> 0.2.0): @@ -123,15 +131,15 @@ v0.2.0 主要变更: 3. 取得发布包并校验(地址用你们自己的制品库替换; 下面是本仓库的发布地址) ```bash - curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.7.1/opendance-web-v0.7.1.tar.gz - curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.7.1/SHA256SUMS + curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.7.2/opendance-web-v0.7.2.tar.gz + curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.7.2/SHA256SUMS sha256sum -c SHA256SUMS # 期望输出 "OK" ``` 4. 解压并生成配置(交互式引导,逐项问答,口令不回显) ```bash - tar -xzf opendance-web-v0.7.1.tar.gz && cd opendance-web-v0.7.1 + tar -xzf opendance-web-v0.7.2.tar.gz && cd opendance-web-v0.7.2 bash deploy/init-env.sh ``` @@ -201,8 +209,8 @@ FLUSH PRIVILEGES; ### 5. 部署步骤 ```bash -tar -xzf opendance-web-v0.7.1.tar.gz -cd opendance-web-v0.7.1 +tar -xzf opendance-web-v0.7.2.tar.gz +cd opendance-web-v0.7.2 bash deploy/init-env.sh # 首次启动引导: 逐项问答生成 deploy/.env(见下) bash deploy/install.sh # 已以 root 登录, 不需要 sudo ``` diff --git a/README.txt b/README.txt index 2f7d0dd..8715235 100644 --- a/README.txt +++ b/README.txt @@ -1,5 +1,5 @@ ================================================================ -OpenDance Studio -- Web 管理服务端 v0.7.1 使用说明 +OpenDance Studio -- Web 管理服务端 v0.7.2 使用说明 ================================================================ 本服务端是 OpenDance Studio 三端中的第一端, 负责管理歌曲、VRM 模型与 @@ -8,6 +8,24 @@ OpenDance Studio -- Web 管理服务端 v0.7.1 使用说明 重要: 本服务端 不部署、不管理 MySQL。数据库为部署方提供的现有实例, 连接信息通过 .env 注入。 +v0.7.2 修订 - 修复产物"装得上、起不来" + /health 报错版本号 + 1. CatalogModule 漏 import ScenesModule(致命): CatalogService 注入 + ScenesService, 但 CatalogModule 只列了 Songs/Motions/Models。Nest 的 DI + 按模块解析 -> node dist/main.js 在 bootstrap 直接抛 + UnknownDependenciesException -> v0.7.0/v0.7.1 的产物根本起不来。 + 当时 build 通过、258 项测试全绿、打包完整性校验通过, 因为它们都不编译 AppModule。 + 2. 新增启动冒烟 scripts/check-bootstrap.mjs(挂进 verify 与打包脚本): + 以正式部署方式(node dist/main.js, 无 npm 环境变量, 不需要数据库)拉起真实产物, + 断言无依赖解析错误 + 应用版本等于 package.json + 已推进到数据库连接阶段。 + 已反向验证: 删掉 ScenesModule 后该检查立刻失败。 + 3. /health 版本号在原生部署下永远是 0.1.0: 原来用 npm_package_version, + 该变量只在 npm 脚本下存在。新增 src/config/app-version.ts 作为运行时唯一 + 解析点(APP_VERSION -> package.json(带包名校验) -> npm_package_version -> 0.0.0), + main.ts 启动首行也打印版本号。 + 4. 新增 scripts/check-version.mjs(并入 contracts:check): 校验三处版本一致并 + 禁止 health.controller.ts 硬编码版本回退; 打包脚本构建管理端后再跑一次。 + 5. 新增 12 项测试(含"模拟无 npm 环境变量的原生部署")。 + v0.7.1 修订 - 契约补齐 + 文档补齐(契约 websocket-keypoints 0.1.0 -> 0.2.0) 1. 补齐 rest-api.yaml 里漏写的场景结构(CatalogBundle.scenes[] + Scene + SceneConfig): catalog/export 自 v0.7.0 起就返回 scenes[],规格漏写会导致 @@ -159,11 +177,11 @@ v0.2.1 修订 2. 准备一个现有的 MySQL / MariaDB 实例, 并建好库与账号(见下方"前置要求") 本项目不会创建数据库本身 3. 取得发布包并校验(地址用你们自己的制品库替换) - curl -LO https://<制品库地址>/opendance-web-v0.7.1.tar.gz + curl -LO https://<制品库地址>/opendance-web-v0.7.2.tar.gz curl -LO https://<制品库地址>/SHA256SUMS sha256sum -c SHA256SUMS # 期望输出 "OK" 4. 解压并生成配置(交互式引导, 逐项问答, 口令不回显) - tar -xzf opendance-web-v0.7.1.tar.gz && cd opendance-web-v0.7.1 + tar -xzf opendance-web-v0.7.2.tar.gz && cd opendance-web-v0.7.2 bash deploy/init-env.sh 5. 安装(建用户与目录 -> 装依赖 -> 迁移 -> 注册系统服务 -> 等健康检查) bash deploy/install.sh @@ -221,8 +239,8 @@ v0.2.1 修订 (本项目不会创建数据库本身, 也不需要 GRANT OPTION / FILE / SUPER 等管理权限) 部署步骤 - tar -xzf opendance-web-v0.7.1.tar.gz - cd opendance-web-v0.7.1 + tar -xzf opendance-web-v0.7.2.tar.gz + cd opendance-web-v0.7.2 bash deploy/init-env.sh # 首次启动引导: 逐项问答生成 deploy/.env(见下) bash deploy/install.sh # 已以 root 登录, 不需要 sudo diff --git a/project.yaml b/project.yaml index bb892e9..aadaa64 100644 --- a/project.yaml +++ b/project.yaml @@ -1,5 +1,5 @@ project: opendance-web-server -version: 0.7.1 +version: 0.7.2 repository: opendance-web default_branch: main contracts_version: @@ -90,7 +90,7 @@ tasks: status: done deliverable: - artifact: opendance-web-v0.7.1.tar.gz + artifact: opendance-web-v0.7.2.tar.gz packaging: Linux 业务服务（系统服务托管，双端口：软件 API + 管理端，不含 MySQL、不含反向代理、不使用 Docker） includes: - web-server/ # NestJS 源码 + 构建产物（含 BVH / VMD 内置解析、ZIP 读取与模型压缩包转换） diff --git a/scripts/package-release.sh b/scripts/package-release.sh index 76b1814..8c8bed6 100755 --- a/scripts/package-release.sh +++ b/scripts/package-release.sh @@ -49,11 +49,16 @@ log "校验契约版本一致性..." # ---------- 2. 后端构建 ---------- log "构建后端..." ( cd web-server && npm run build ) +# 构建后**启动冒烟**：产物能不能真正 boot 起来（模块 DI 图可解析 + 版本号正确）。 +# v0.7.0/v0.7.1 就是漏了这一步才把「装得上、起不来」的产物发了出去。 +( cd web-server && npm run bootstrap:check ) # ---------- 3. 管理端构建 ---------- if [ -d web-server/admin/node_modules ]; then log "构建管理端..." ( cd web-server/admin && npm run build ) + # 构建后再次校验版本一致性：此时管理端产物已存在，会额外断言产物 JS 内含 vX.Y.Z + ( cd web-server && npm run version:check ) else log "警告：web-server/admin/node_modules 不存在，跳过管理端构建（产物将缺少 admin/）" fi diff --git a/tasks/011-version-display.md b/tasks/011-version-display.md index 3f52f05..8142373 100644 --- a/tasks/011-version-display.md +++ b/tasks/011-version-display.md @@ -28,3 +28,34 @@ | 管理端任一页面左下角可见 `vX.Y.Z` | ✅ 侧边栏底部固定显示 | | 与 `GET /health` 的 `version` 相同 | ✅ 同源于 `web-server/package.json` | | 与产物文件名一致 | ✅ `opendance-web-vX.Y.Z.tar.gz`；打包脚本读取同一个 package.json | + +## 缺陷修复记录（v0.7.2） + +**缺陷**：`/health` 的 `version` 在正式部署里**永远是 `0.1.0`**。 + +原实现是 `process.env.npm_package_version ?? '0.1.0'`。这个环境变量 +**只在通过 npm 脚本启动时才存在**，而本项目的正式部署方式是原生服务 +（systemd / OpenRC / initd，`ExecStart=node dist/main.js`）—— npm 不参与， +于是它恒为 `undefined`，`/health` 就回退到硬编码的 `0.1.0`。 +这直接违反文档 §11.2 第 4 条「可核对：Web 端至少与 `GET /health` 的 `version` 一致」： +管理端左下角显示 v0.7.x，而 `/health` 说 0.1.0。 + +**修复**： + +* 新增 `src/config/app-version.ts` 作为**运行时唯一解析点**，按优先级尝试 + `APP_VERSION` 环境变量 → 运行入口旁的 `package.json` → 工作目录的 + `package.json` → `npm_package_version`，每一步都做**包名校验** + （必须是 `opendance-web-server`），避免读到上层仓库的 `package.json`； + 全都拿不到时返回显式的 `0.0.0`，而不是伪装成某个具体版本； +* `/health` 改为 `version: resolveAppVersion()`； +* `main.ts` 启动首行也打印 `应用版本 vX.Y.Z`，即使后面数据库连不上、进程退出， + 日志里也一定能看到本次运行的版本号。 + +**防线**： + +* `scripts/check-version.mjs`（并入 `npm run contracts:check`）校验 + `web-server/package.json` = `admin/package.json` = `project.yaml`，并 + **禁止** `health.controller.ts` 再出现硬编码版本回退（正则拦截 `?? 'x.y.z'`）； + 管理端已构建时还会断言产物 JS 内确实含 `vX.Y.Z`； +* `test/app-version.spec.ts` 12 项，其中一项**显式模拟无 npm 环境变量**的原生部署； +* `scripts/check-bootstrap.mjs` 用真实的 `node dist/main.js` 验证启动日志里的版本号。 diff --git a/tasks/015-scene-management.md b/tasks/015-scene-management.md index 0052fd2..8460605 100644 --- a/tasks/015-scene-management.md +++ b/tasks/015-scene-management.md @@ -46,3 +46,30 @@ | 非法参数不会入库 | ✅ 前后端同规则收敛；`test/scene-config.spec.ts` 9 项边界用例 | | 客户端能拿到场景 | ✅ `catalog/export.scenes[]`；目录指纹纳入场景变更 | | 路由与契约一致 | ✅ `check-routes` 共 **35** 条 | + +## 缺陷修复记录（v0.7.2） + +**缺陷**：`CatalogModule` 的 `imports` 里漏了 `ScenesModule`。 + +`CatalogService` 因为 `catalog/export` 要下发 `scenes[]` 而注入了 `ScenesService`， +但 Nest 的 DI 是**按模块**解析的 —— 不在同一个模块的 `imports` 里，就解析不到。 +后果是 `node dist/main.js` 在 bootstrap 阶段直接抛 +`UnknownDependenciesException: Nest can't resolve dependencies of the CatalogService (... ? ...)`， +**服务完全起不来**（v0.7.0 / v0.7.1 的产物都是这样）。 + +**为什么当时没被发现**：三层检查全都"绿"—— + +| 检查 | 为什么没抓到 | +|--|--| +| `nest build` / `tsc --noEmit` | 模块 import 缺失是**运行时** DI 问题，类型系统看不出来 | +| 258 项单元测试 | 它们直接 new 服务或测纯函数，**从不编译 `AppModule`** | +| 打包脚本的产物完整性校验 | 只校验文件清单、压缩包结构与 PE/魔数，不启动服务 | + +**修复**：在 `CatalogModule.imports` 中补上 `ScenesModule`。 + +**防线**：新增 `scripts/check-bootstrap.mjs`，以正式部署方式 +（`ExecStart=node dist/main.js`、**不带任何 npm 环境变量**、**不需要数据库**） +拉起真实产物，断言①无依赖解析类错误②启动日志里的应用版本等于 `package.json` +③启动确实推进到数据库连接阶段。已挂进 `npm run verify` 与 +`scripts/package-release.sh`（构建后、打包前），并做过**反向验证**： +把 `ScenesModule` 删除后该检查立刻失败。 diff --git a/web-server/admin/package.json b/web-server/admin/package.json index 19888a0..6c1d0f3 100644 --- a/web-server/admin/package.json +++ b/web-server/admin/package.json @@ -1,7 +1,7 @@ { "name": "opendance-admin", "private": true, - "version": "0.7.1", + "version": "0.7.2", "type": "module", "description": "OpenDance Studio 管理端（React + TypeScript + Vite）", "scripts": { diff --git a/web-server/package-lock.json b/web-server/package-lock.json index 37b25f1..ff0e08c 100644 --- a/web-server/package-lock.json +++ b/web-server/package-lock.json @@ -1,12 +1,12 @@ { "name": "opendance-web-server", - "version": "0.2.0", + "version": "0.7.2", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "opendance-web-server", - "version": "0.2.0", + "version": "0.7.2", "license": "MIT", "dependencies": { "@nestjs/common": "^11.0.12", @@ -35,7 +35,7 @@ "vitest": "^3.0.8" }, "engines": { - "node": ">=20.0.0" + "node": ">=22.0.0" } }, "node_modules/@angular-devkit/core": { diff --git a/web-server/package.json b/web-server/package.json index 3fd53a0..3a61b91 100644 --- a/web-server/package.json +++ b/web-server/package.json @@ -1,6 +1,6 @@ { "name": "opendance-web-server", - "version": "0.7.1", + "version": "0.7.2", "description": "OpenDance Studio Web 管理服务端（NestJS + TypeORM + 现有 MySQL 实例）", "license": "MIT", "private": true, @@ -16,13 +16,15 @@ "test": "vitest run", "test:watch": "vitest", "test:smoke": "node test/smoke.mjs", - "contracts:check": "node scripts/check-contracts.mjs && node scripts/check-routes.mjs", - "verify": "npm run contracts:check && npm run typecheck && npm run test && npm run build", + "contracts:check": "node scripts/check-contracts.mjs && node scripts/check-routes.mjs && node scripts/check-version.mjs", + "verify": "npm run contracts:check && npm run typecheck && npm run test && npm run build && npm run bootstrap:check", "typeorm": "node scripts/migrate.mjs", "migration:generate": "node scripts/migrate.mjs generate", "migration:run": "node scripts/migrate.mjs run", "migration:revert": "node scripts/migrate.mjs revert", - "migration:show": "node scripts/migrate.mjs show" + "migration:show": "node scripts/migrate.mjs show", + "version:check": "node scripts/check-version.mjs", + "bootstrap:check": "node scripts/check-bootstrap.mjs" }, "dependencies": { "@nestjs/common": "^11.0.12", diff --git a/web-server/scripts/check-bootstrap.mjs b/web-server/scripts/check-bootstrap.mjs new file mode 100644 index 0000000..9fd56c9 --- /dev/null +++ b/web-server/scripts/check-bootstrap.mjs @@ -0,0 +1,175 @@ +#!/usr/bin/env node +/** + * 启动冒烟检查：**编译产物能不能真正 boot 起来**（不需要数据库）。 + * + * 为什么必须有这一层：`src/catalog/catalog.module.ts` 曾经漏了 `ScenesModule`， + * 而 `CatalogService` 注入了 `ScenesService` —— Nest 的 DI 是**按模块**解析的， + * 于是 `node dist/main.js` 在 bootstrap 阶段直接抛 `UnknownDependenciesException`， + * **服务根本起不来**。但当时所有检查都是绿的： + * - `nest build` 通过（类型没问题）； + * - 258 项单元测试通过（它们直接 new 服务 / 测纯函数，从不编译 AppModule）； + * - 打包脚本只校验文件清单与压缩包完整性。 + * 结果就是 v0.7.0 / v0.7.1 的产物「装得上、起不来」。 + * + * 本脚本以**正式部署的方式**（systemd 的 `ExecStart=node dist/main.js`， + * 不带任何 npm 环境变量）拉起真实产物，然后： + * 1. 断言日志里**没有**依赖解析类错误（UnknownDependenciesException 等）→ 模块图可解析； + * 2. 断言日志里的「应用版本 vX.Y.Z」等于 `package.json` 的 version + * → 原生部署下版本号解析正确（原先会退化成硬编码的 0.1.0）； + * 3. 断言启动确实**推进到了数据库连接阶段** → 证明 Nest 已把整个 DI 图解析完， + * 而不是中途失败。 + * + * 不需要数据库：TypeORM 连不上时日志里会出现明确的连接错误，那就够了 —— + * 本脚本的职责是「启动能否走到连库这一步」，真连库的端到端验收由 + * `test/smoke.mjs`（部署好服务端后运行）负责。 + * + * 用法：node scripts/check-bootstrap.mjs + */ +import { spawn } from 'node:child_process'; +import { mkdtempSync, readFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { dirname, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const here = dirname(fileURLToPath(import.meta.url)); +const serverDir = join(here, '..'); +const entry = join(serverDir, 'dist', 'main.js'); + +const EXPECTED_VERSION = JSON.parse( + readFileSync(join(serverDir, 'package.json'), 'utf8'), +).version; + +/** 依赖解析失败的标志（任一出现即失败） */ +const DI_ERROR_PATTERNS = [ + /UnknownDependenciesException/, + /Nest can't resolve dependencies/i, + /cannot resolve dependencies/i, + /Nest can't resolve/i, +]; + +/** 走到数据库连接阶段的标志 */ +const DB_STAGE_PATTERNS = [ + /Unable to connect to the database/i, + /ECONNREFUSED/, + /getaddrinfo/i, + /Access denied for user/i, + /Unknown database/i, + /服务已?启动/, + /已启动，监听/, +]; + +const TIMEOUT_MS = Number(process.env.BOOTSTRAP_TIMEOUT_MS ?? 40_000); + +function freePort(base) { + // 用一个不常见的端口即可；连库失败是预期的，端口只要不撞上真实服务 + return base + Math.floor(Math.random() * 200); +} + +async function main() { + const scratch = mkdtempSync(join(tmpdir(), 'opendance-boot-')); + + // 模拟 systemd：删掉 npm_* 环境变量（ExecStart=node dist/main.js 时它们不存在） + const env = { ...process.env }; + for (const key of Object.keys(env)) { + if (key.startsWith('npm_')) delete env[key]; + } + delete env.APP_VERSION; // 也不允许用显式覆盖，必须走 package.json + Object.assign(env, { + NODE_ENV: 'development', // 免得 validateEnv 在生产模式直接 exit(1) + HOST: '127.0.0.1', + PORT: String(freePort(34000)), + ADMIN_PORT: String(freePort(35000)), + DB_HOST: '127.0.0.1', + DB_PORT: '3399', // 故意指向一个没有 MySQL 的端口 + DB_USER: 'opendance_probe', + DB_PASSWORD: 'opendance_probe', + DB_NAME: 'opendance_probe', + DB_LOGGING: 'false', + STORAGE_DIR: join(scratch, 'storage'), + ADMIN_DIR: join(scratch, 'admin'), + }); + + const child = spawn(process.execPath, [entry], { + cwd: serverDir, + env, + stdio: ['ignore', 'pipe', 'pipe'], + }); + + let output = ''; + let finished = false; + + const decide = () => { + if (finished) return null; + const diError = DI_ERROR_PATTERNS.find((re) => re.test(output)); + if (diError) { + finished = true; + return { ok: false, reason: 'di', pattern: String(diError) }; + } + const versionLine = output.match(/应用版本 v(\S+)/); + const dbStage = DB_STAGE_PATTERNS.some((re) => re.test(output)); + if (versionLine && dbStage) { + finished = true; + return { ok: true, version: versionLine[1] }; + } + return null; + }; + + const result = await new Promise((resolvePromise) => { + const timer = setTimeout(() => { + resolvePromise(decide() ?? { ok: false, reason: 'timeout' }); + }, TIMEOUT_MS); + + const onData = (chunk) => { + output += chunk.toString(); + const decided = decide(); + if (decided) { + clearTimeout(timer); + child.kill('SIGKILL'); + resolvePromise(decided); + } + }; + + child.stdout.on('data', onData); + child.stderr.on('data', onData); + child.on('exit', () => { + clearTimeout(timer); + resolvePromise(decide() ?? { ok: false, reason: 'exit' }); + }); + child.on('error', (error) => { + clearTimeout(timer); + resolvePromise({ ok: false, reason: 'spawn', error: error.message }); + }); + }); + + if (result.ok) { + if (result.version !== EXPECTED_VERSION) { + console.error( + `✗ 启动日志里的应用版本 v${result.version} 与 web-server/package.json 的 ${EXPECTED_VERSION} 不一致`, + ); + console.error(' （原生部署下版本号必须从 package.json 解析，不能依赖 npm 环境变量）'); + process.exit(1); + } + console.log( + `✓ 启动冒烟通过：模块依赖图可解析（无 UnknownDependenciesException）、` + + `应用版本 v${result.version} 与 package.json 一致、已推进到数据库连接阶段`, + ); + return; + } + + console.error('✗ 启动冒烟失败：'); + if (result.reason === 'di') { + console.error(` 依赖解析错误（匹配 ${result.pattern}）—— 有模块忘记 import 提供者了。`); + console.error(' 提示：检查各 @Module 的 imports 是否覆盖了构造函数里注入的服务。'); + } else if (result.reason === 'timeout') { + console.error(' 进程既没有报依赖错误，也没有推进到数据库连接阶段（超时）。'); + } else if (result.reason === 'exit') { + console.error(' 进程提前退出，且日志里既没有依赖错误也没有数据库阶段标志。'); + } else if (result.reason === 'spawn') { + console.error(` 无法启动 ${entry}：${result.error}`); + } + console.error('\n---- 进程输出（末尾 40 行）----'); + console.error(output.split('\n').slice(-40).join('\n')); + process.exit(1); +} + +await main(); diff --git a/web-server/scripts/check-version.mjs b/web-server/scripts/check-version.mjs new file mode 100644 index 0000000..cf3db19 --- /dev/null +++ b/web-server/scripts/check-version.mjs @@ -0,0 +1,128 @@ +#!/usr/bin/env node +/** + * 版本号一致性校验（文档 §11.2「单一来源 / 可核对」）。 + * + * 守护的缺陷：`/health` 曾经用 + * process.env.npm_package_version ?? '0.1.0' + * 而正式部署方式是原生服务（`ExecStart=node dist/main.js`），npm 不参与， + * 该环境变量为 undefined —— 于是真实部署里 `/health` 永远报 **0.1.0**， + * 与管理端左下角展示的 vX.Y.Z 不一致。 + * + * 校验项： + * 1. web-server/package.json 的 version === project.yaml 的 version + * 2. web-server/admin/package.json 的 version === web-server/package.json 的 version + * 3. src/config/app-version.ts 存在，且 health.controller 通过它取版本 + * 4. health.controller 里不得再出现硬编码的版本回退（如 `?? '0.1.0'`） + * 5. 若管理端已构建（web-server/admin/dist 存在），其 JS 包内必须含 `v` + * + * 用法：node scripts/check-version.mjs + */ +import { existsSync, readFileSync, readdirSync } from 'node:fs'; +import { dirname, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const here = dirname(fileURLToPath(import.meta.url)); +const serverDir = join(here, '..'); +const repoDir = join(serverDir, '..'); + +const problems = []; +const notes = []; + +function readJson(file) { + try { + return JSON.parse(readFileSync(file, 'utf8')); + } catch (error) { + problems.push(`无法解析 ${file}：${error.message}`); + return null; + } +} + +function readYamlVersion(file) { + if (!existsSync(file)) { + problems.push(`缺少 ${file}`); + return null; + } + const line = readFileSync(file, 'utf8') + .split(/\r?\n/) + .find((l) => l.trimStart().startsWith('version:')); + if (!line) { + problems.push(`无法在 ${file} 中定位 version:`); + return null; + } + return line.slice(line.indexOf(':') + 1).trim(); +} + +// ---- 1. package.json 与 project.yaml ---- +const serverPkg = readJson(join(serverDir, 'package.json')); +const yamlVersion = readYamlVersion(join(repoDir, 'project.yaml')); +if (serverPkg && yamlVersion && serverPkg.version !== yamlVersion) { + problems.push(`版本不一致：web-server/package.json=${serverPkg.version} vs project.yaml=${yamlVersion}`); +} + +// ---- 2. 管理端 package.json 与之同源 ---- +const adminPkgPath = join(serverDir, 'admin', 'package.json'); +if (existsSync(adminPkgPath)) { + const adminPkg = readJson(adminPkgPath); + if (serverPkg && adminPkg && adminPkg.version !== serverPkg.version) { + problems.push( + `版本不一致：web-server/admin/package.json=${adminPkg.version} vs web-server/package.json=${serverPkg.version}`, + ); + } +} + +// ---- 3 & 4. /health 的版本必须来自 package.json，不能再硬编码 ---- +const healthPath = join(serverDir, 'src', 'health', 'health.controller.ts'); +const versionModulePath = join(serverDir, 'src', 'config', 'app-version.ts'); +if (!existsSync(versionModulePath)) { + problems.push('缺少 src/config/app-version.ts（版本号运行时唯一解析点）'); +} +if (!existsSync(healthPath)) { + problems.push('缺少 src/health/health.controller.ts'); +} else { + const health = readFileSync(healthPath, 'utf8'); + if (!health.includes('resolveAppVersion')) { + problems.push('health.controller.ts 未使用 resolveAppVersion()，/health 的版本可能不是单一来源'); + } + // 硬编码版本回退：`?? 'x.y.z'` 或 `|| "x.y.z"` + const hardcoded = health.match(/\?\?\s*['"]\d+\.\d+\.\d+['"]|\|\|\s*['"]\d+\.\d+\.\d+['"]/); + if (hardcoded) { + problems.push( + `health.controller.ts 存在硬编码版本回退 ${hardcoded[0]}；应使用 resolveAppVersion()（否则原生部署下 /health 会报错版本）`, + ); + } +} + +// ---- 5. 管理端构建产物必须带上与 package.json 相同的版本 ---- +const adminDist = join(serverDir, 'admin', 'dist', 'assets'); +if (serverPkg && existsSync(adminDist)) { + const files = readdirSync(adminDist).filter((f) => f.endsWith('.js')); + const found = new Set(); + for (const file of files) { + const text = readFileSync(join(adminDist, file), 'utf8'); + for (const m of text.matchAll(/v\d+\.\d+\.\d+/g)) found.add(m[0]); + } + const expected = `v${serverPkg.version}`; + if (found.size === 0) { + problems.push(`管理端构建产物中找不到任何 vX.Y.Z（期望 ${expected}）`); + } else if (!found.has(expected)) { + problems.push(`管理端构建产物中的版本 ${[...found].join('/')} 与 package.json 的 ${expected} 不一致`); + } else { + notes.push(`管理端构建产物含 ${expected}`); + } +} else { + notes.push('管理端尚未构建，跳过产物内版本校验（打包脚本会在构建后再次执行本脚本）'); +} + +if (problems.length > 0) { + console.error('✗ 版本一致性校验失败：'); + for (const p of problems) console.error(` - ${p}`); + console.error('\n请同步 web-server/package.json、web-server/admin/package.json、project.yaml；'); + console.error('/health 的版本必须来自 src/config/app-version.ts（读 package.json），不得硬编码。'); + process.exit(1); +} + +for (const n of notes) console.log(` · ${n}`); +console.log( + `✓ 版本一致（${serverPkg?.version}）：web-server/package.json = admin/package.json = project.yaml，` + + `/health 由 resolveAppVersion() 读取 package.json`, +); diff --git a/web-server/src/catalog/catalog.module.ts b/web-server/src/catalog/catalog.module.ts index e0fcb0b..475d0a0 100644 --- a/web-server/src/catalog/catalog.module.ts +++ b/web-server/src/catalog/catalog.module.ts @@ -5,6 +5,7 @@ import { Motion } from '../entities/motion.entity'; import { Song } from '../entities/song.entity'; import { ModelsModule } from '../models/models.module'; import { MotionsModule } from '../motions/motions.module'; +import { ScenesModule } from '../scenes/scenes.module'; import { SongsModule } from '../songs/songs.module'; import { CatalogController } from './catalog.controller'; import { CatalogService } from './catalog.service'; @@ -15,6 +16,11 @@ import { CatalogService } from './catalog.service'; SongsModule, MotionsModule, ModelsModule, + // CatalogService 注入 ScenesService（catalog/export 要下发 scenes[]）。 + // Nest 的 DI 是**按模块**解析的：不在这里 import，bootstrap 时会直接 + // UnknownDependenciesException，服务根本起不来 —— 由 scripts/check-bootstrap.mjs + // 在构建后强制拦截（v0.7.0/v0.7.1 就是漏了这一步才把「装得上、起不来」的产物发了出去）。 + ScenesModule, ], controllers: [CatalogController], providers: [CatalogService], diff --git a/web-server/src/config/app-version.ts b/web-server/src/config/app-version.ts new file mode 100644 index 0000000..7583044 --- /dev/null +++ b/web-server/src/config/app-version.ts @@ -0,0 +1,129 @@ +import { existsSync, readFileSync } from 'node:fs'; +import { dirname, join, resolve } from 'node:path'; + +/** + * 应用版本号的**运行时唯一解析点**（文档 §11.1 / §11.2）。 + * + * 为什么不能只用 `process.env.npm_package_version`： + * 那个环境变量**只在通过 npm 脚本启动时**才存在（`npm start` / `npm run start:prod`）。 + * 而本项目的正式部署方式是**原生服务**（systemd / OpenRC / initd）， + * `ExecStart=node dist/main.js` —— npm 不参与，于是 `npm_package_version` 为 undefined， + * 原来那句 `?? '0.1.0'` 会让 `GET /health` 在真实部署里**永远报 0.1.0**， + * 与「管理端左下角展示 vX.Y.Z、且必须与 /health 一致」的硬性要求直接冲突。 + * + * 因此改为从 **`package.json` 实体文件**读取（构建期注入管理端的也是这同一份文件）， + * 依次尝试多个候选路径，取第一个「包名匹配」的结果： + * + * 1. `APP_VERSION` 环境变量（显式覆盖，给运维留一个不重新打包即可改的口子） + * 2. 运行入口所在目录的 `../package.json`（`dist/main.js` → `web-server/package.json`） + * 3. 进程工作目录下的 `package.json`（systemd 的 `WorkingDirectory=.../web-server`） + * 4. `npm_package_version`（npm 脚本启动时的兜底） + * 5. 都没有则 `'0.0.0'` —— 显式可见的“未知版本”，绝不伪装成某个具体版本 + * + * 候选路径都必须通过 [parsePackageVersion] 的**包名校验**， + * 避免把上层仓库或别的 Node 项目的 `package.json` 误当成自己。 + */ + +/** 本包的 `name`，用于校验读到的 package.json 确实是本项目 */ +export const PACKAGE_NAME = 'opendance-web-server'; + +/** 无法解析时的显式占位值（不是任何真实版本，便于一眼看出异常） */ +export const UNKNOWN_VERSION = '0.0.0'; + +/** + * 从 `package.json` 文本中解析版本号。 + * **纯函数**：只在「JSON 合法 + 包名匹配 + version 形如 x.y.z」时才返回版本， + * 否则返回 null（调用方继续尝试下一个候选路径）。 + */ +export function parsePackageVersion(content: string): string | null { + let parsed: unknown; + try { + parsed = JSON.parse(content); + } catch { + return null; + } + if (typeof parsed !== 'object' || parsed === null) return null; + const pkg = parsed as Record; + if (pkg.name !== PACKAGE_NAME) return null; + const version = pkg.version; + if (typeof version !== 'string') return null; + const trimmed = version.trim(); + // 形如 X.Y.Z（允许预发布后缀），防止读到 'workspace:*' 之类的非版本值 + if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(trimmed)) return null; + return trimmed; +} + +/** 收集候选 `package.json` 路径（顺序即优先级） */ +export function packageJsonCandidates(): string[] { + const out: string[] = []; + + // 2. 运行入口：CJS 下可用 require.main；ESM/测试环境下跳过 + try { + // eslint-disable-next-line @typescript-eslint/no-var-requires + const main = typeof require !== 'undefined' ? require.main : undefined; + const filename: unknown = main?.filename; + if (typeof filename === 'string' && filename.length > 0) { + out.push(resolve(dirname(filename), '..', 'package.json')); + } + } catch { + /* 非 CJS 环境，忽略 */ + } + + // 2b. 编译产物相对位置：dist/config/app-version.js → web-server/package.json + try { + // eslint-disable-next-line @typescript-eslint/no-undef + const here = typeof __dirname === 'string' ? __dirname : ''; + if (here) out.push(resolve(here, '..', '..', 'package.json')); + } catch { + /* ESM 下 __dirname 未定义，忽略 */ + } + + // 3. 工作目录（systemd 的 WorkingDirectory=.../web-server） + out.push(join(process.cwd(), 'package.json')); + + return [...new Set(out)]; +} + +function readVersion(file: string): string | null { + if (!existsSync(file)) return null; + try { + return parsePackageVersion(readFileSync(file, 'utf8')); + } catch { + return null; + } +} + +/** 解析当前运行版本；结果对同一进程稳定（缓存） */ +let cached: string | null = null; + +export function resolveAppVersion(): string { + if (cached !== null) return cached; + + const explicit = process.env.APP_VERSION?.trim(); + if (explicit) { + cached = explicit; + return cached; + } + + for (const file of packageJsonCandidates()) { + const version = readVersion(file); + if (version) { + cached = version; + return cached; + } + } + + const npmVersion = process.env.npm_package_version?.trim(); + if (npmVersion && /^\d+\.\d+\.\d+/.test(npmVersion)) { + cached = npmVersion; + return cached; + } + + cached = UNKNOWN_VERSION; + return cached; +} + +/** 测试用：清空缓存（生产代码不要调用） */ +export function resetAppVersionCache(): void { + cached = null; +} diff --git a/web-server/src/health/health.controller.ts b/web-server/src/health/health.controller.ts index 8c27375..6aa8dee 100644 --- a/web-server/src/health/health.controller.ts +++ b/web-server/src/health/health.controller.ts @@ -2,6 +2,7 @@ import { Controller, Get, Res, ServiceUnavailableException } from '@nestjs/commo import { InjectDataSource } from '@nestjs/typeorm'; import { Response } from 'express'; import { DataSource } from 'typeorm'; +import { resolveAppVersion } from '../config/app-version'; import { AppConfig } from '../config/configuration'; import { detectAssimp } from '../preprocess/assimp'; @@ -69,7 +70,10 @@ export class HealthController { const report: HealthReport = { status: database.connected ? 'ok' : 'degraded', uptimeSec: Math.round(process.uptime() * 1000) / 1000, - version: process.env.npm_package_version ?? '0.1.0', + // 版本号唯一解析点：读 package.json 实体文件，而不是只在 npm 脚本下才存在的 + // npm_package_version（原生部署 ExecStart=node dist/main.js 时它是 undefined， + // 会让 /health 永远报一个陈旧的硬编码版本，与管理端左下角的展示冲突）。 + version: resolveAppVersion(), contractVersion: this.config.contractVersions, database, storage: { diff --git a/web-server/src/main.ts b/web-server/src/main.ts index 79347ee..e8356c8 100644 --- a/web-server/src/main.ts +++ b/web-server/src/main.ts @@ -7,6 +7,7 @@ import { existsSync, mkdirSync } from 'node:fs'; import { extname, join, resolve } from 'node:path'; import { AppModule } from './app.module'; import { describeDualAccess, preferredUrl } from './config/access-hint'; +import { resolveAppVersion } from './config/app-version'; import { AppConfig, configuration, @@ -37,6 +38,12 @@ function listenServer(server: Server, port: number, host: string): Promise async function bootstrap(): Promise { const logger = new Logger('Bootstrap'); + // 先打版本号：这是「当前运行版本」的唯一来源（web-server/package.json， + // 由 resolveAppVersion() 解析，不依赖 npm 环境变量）。 + // 放在最前面还有一个作用：即使后面数据库连不上、进程退出， + // 日志里也一定能看到本次运行的版本号（便于与 /health、管理端左下角核对）。 + logger.log(`OpenDance Studio Web 服务端 应用版本 v${resolveAppVersion()}`); + // 启动前校验环境变量（生产环境禁止 DB_SYNCHRONIZE=true、端口必须合法等） const { errors, warnings } = validateEnv(configuration()); for (const warning of warnings) logger.warn(`环境变量提示：${warning}`); diff --git a/web-server/test/app-version.spec.ts b/web-server/test/app-version.spec.ts new file mode 100644 index 0000000..ab37a1a --- /dev/null +++ b/web-server/test/app-version.spec.ts @@ -0,0 +1,111 @@ +import { readFileSync } from 'node:fs'; +import { join, resolve } from 'node:path'; +import { afterEach, describe, expect, it } from 'vitest'; +import { + PACKAGE_NAME, + UNKNOWN_VERSION, + packageJsonCandidates, + parsePackageVersion, + resetAppVersionCache, + resolveAppVersion, +} from '../src/config/app-version'; + +/** + * 版本号展示的**运行时唯一来源**（文档 §11.1 / §11.2）。 + * + * 这里守护的是一个真实发生过的缺陷：原来 `/health` 用 + * `process.env.npm_package_version ?? '0.1.0'`，而正式部署方式是原生服务 + * （`ExecStart=node dist/main.js`），npm 不参与 → 该环境变量为 undefined → + * `/health` 在真实部署里永远报 **0.1.0**，与管理端左下角展示的 vX.Y.Z 不一致， + * 直接违反「可核对：Web 端至少与 GET /health 的 version 一致」。 + */ + +const serverPackageJson = JSON.parse( + readFileSync(resolve(__dirname, '..', 'package.json'), 'utf8'), +) as { name: string; version: string }; + +afterEach(() => { + delete process.env.APP_VERSION; + resetAppVersionCache(); +}); + +describe('parsePackageVersion（纯函数：只在包名与格式都对时才认）', () => { + it('接受本项目的 package.json', () => { + expect( + parsePackageVersion(JSON.stringify({ name: PACKAGE_NAME, version: '1.2.3' })), + ).toBe('1.2.3'); + }); + + it('接受带预发布后缀的版本', () => { + expect( + parsePackageVersion(JSON.stringify({ name: PACKAGE_NAME, version: '1.2.3-rc.1' })), + ).toBe('1.2.3-rc.1'); + }); + + it('拒绝包名不匹配的文件（避免读到上层仓库的 package.json）', () => { + expect(parsePackageVersion(JSON.stringify({ name: 'some-other-pkg', version: '9.9.9' }))).toBeNull(); + }); + + it('拒绝缺少 name / version 的文件', () => { + expect(parsePackageVersion(JSON.stringify({ version: '1.2.3' }))).toBeNull(); + expect(parsePackageVersion(JSON.stringify({ name: PACKAGE_NAME }))).toBeNull(); + expect(parsePackageVersion(JSON.stringify({ name: PACKAGE_NAME, version: 123 }))).toBeNull(); + }); + + it('拒绝非版本串（例如 workspace:*）', () => { + expect(parsePackageVersion(JSON.stringify({ name: PACKAGE_NAME, version: 'workspace:*' }))).toBeNull(); + expect(parsePackageVersion(JSON.stringify({ name: PACKAGE_NAME, version: '^1.0.0' }))).toBeNull(); + }); + + it('拒绝非法 JSON 与非对象', () => { + expect(parsePackageVersion('{ 不是 JSON')).toBeNull(); + expect(parsePackageVersion('"字符串"')).toBeNull(); + expect(parsePackageVersion('null')).toBeNull(); + }); +}); + +describe('resolveAppVersion（运行时解析）', () => { + it('解析结果等于 web-server/package.json 的 version（单一来源）', () => { + expect(resolveAppVersion()).toBe(serverPackageJson.version); + }); + + it('与 package.json 里声明的包名一致（校验逻辑没有把别的包读进来）', () => { + expect(serverPackageJson.name).toBe(PACKAGE_NAME); + }); + + it('未通过 npm 启动时也能拿到真实版本（不依赖 npm_package_version）', () => { + // 模拟原生部署：systemd 直接跑 node dist/main.js，没有 npm 环境变量 + const saved = process.env.npm_package_version; + delete process.env.npm_package_version; + delete process.env.APP_VERSION; + resetAppVersionCache(); + try { + const version = resolveAppVersion(); + expect(version).toBe(serverPackageJson.version); + expect(version).not.toBe('0.1.0'); + expect(version).not.toBe(UNKNOWN_VERSION); + } finally { + if (saved !== undefined) process.env.npm_package_version = saved; + resetAppVersionCache(); + } + }); + + it('APP_VERSION 环境变量可显式覆盖（运维不重新打包也能改）', () => { + process.env.APP_VERSION = '9.8.7'; + resetAppVersionCache(); + expect(resolveAppVersion()).toBe('9.8.7'); + }); + + it('候选路径包含工作目录（systemd WorkingDirectory=web-server）', () => { + const candidates = packageJsonCandidates(); + expect(candidates).toContain(join(process.cwd(), 'package.json')); + // 去重：同一路径不应出现两次 + expect(new Set(candidates).size).toBe(candidates.length); + }); + + it('结果稳定（同一进程内缓存，不会来回变）', () => { + const first = resolveAppVersion(); + const second = resolveAppVersion(); + expect(first).toBe(second); + }); +});