fix(entities): 场景功能的真正根因 —— Scene 未注册进 ENTITIES(v0.7.4)

部署 v0.7.3 后,/health 的 scenes.error 给出决定性线索:

  No metadata for "Scene" was found.

src/entities/index.ts 的 ENTITIES 一直漏了 Scene:
  export const ENTITIES = [Asset, Song, Motion, CharacterModel, ReviewRecord];

TypeORM 只按 ENTITIES 注册 metadata,漏注册的后果极其隐蔽:
- 启动完全正常(DI 可解析、/health 正常、migrationsPending 0);
- 迁移也正常(AddScenes 已执行,表其实是建好的);
- 但第一次查 Scene 就抛 No metadata,于是 /api/scenes、/api/catalog/export、
  /api/catalog/version、/api/reviews?status=pending 全部 500
  → 客户端拉不到任何目录、管理端待审列表打不开。

即:此前"数据库缺 scenes 表"的判断也是错的(v0.7.3 的降级与诊断脚本因此仍然值得保留
—— 它们把"场景坏了"限制成"场景不可用",而不是整站不可用)。

修复:ENTITIES 加入 Scene 并导出。

新增静态防线 test/entities-registry.spec.ts(4 项):扫描 src/entities/*.entity.ts 里的
@Entity() 类并逐一与 ENTITIES 对账(漏一个即失败)、检查无重复/无多余、核对 AddScenes
迁移文件存在。已做反向验证:把 Scene 从 ENTITIES 移除后该测试立刻失败。
这类缺陷既过得了 tsc、也过得了启动冒烟(应用能启动),只能靠静态核对兜住。

文档:README.md/.txt 增加 v0.7.4 修订说明;tasks/015-scene-management.md 增
「缺陷修复记录四」;开发文档 §4.12 补「新增实体必须加入 ENTITIES」的硬性要求。

验证:npm run verify 通过(23 文件 / 285 项测试 + 契约/路由/版本一致 + 启动冒烟);
发布产物 opendance-web-v0.7.4.tar.gz
sha256 e680c23fc382b6c39498608ea0154f8f80e9e6b5c13518f0f88095644ce88fe1。
This commit is contained in:
2026-09-17 03:48:52 +08:00
parent 74332e20d8
commit 7a74f598be
8 changed files with 164 additions and 18 deletions
+16 -5
View File
@@ -1,5 +1,5 @@
================================================================
OpenDance Studio -- Web 管理服务端 v0.7.3 使用说明
OpenDance Studio -- Web 管理服务端 v0.7.4 使用说明
================================================================
本服务端是 OpenDance Studio 三端中的第一端, 负责管理歌曲、VRM 模型与
@@ -8,6 +8,17 @@ OpenDance Studio -- Web 管理服务端 v0.7.3 使用说明
重要: 本服务端 不部署、不管理 MySQL。数据库为部署方提供的现有实例,
连接信息通过 .env 注入。
v0.7.4 修订 - 场景功能的真正根因: Scene 没有注册进 ENTITIES
1. 生产实测 /health 的 scenes.error = 'No metadata for "Scene" was found.'
-- src/entities/index.ts 的 ENTITIES 漏了 Scene。TypeORM 只按 ENTITIES 注册
metadata, 于是启动完全正常、但第一次查 Scene 就抛错 => /api/scenes、
/api/catalog/export、/api/catalog/version、/api/reviews?status=pending 全 500。
此前"数据库缺 scenes 表"的判断也是错的: 表已由 AddScenes 迁移建好, 缺的是实体注册。
2. 修复: ENTITIES 加入 Scene 并导出。
3. 新增 test/entities-registry.spec.ts(4 项): 扫描 @Entity() 类与 ENTITIES 对账,
漏一个即失败; 已反向验证(移除 Scene 立刻失败)。
4. 部署后运行 node scripts/diagnose-scenes.mjs 可确认表与列的实际状态。
v0.7.3 修订 - 场景表不可用不再拖垮整站(生产事故修复)
另修一个更直接的缺陷: ScenesService.create() 按内存存储写(判断 file.buffer),
而上传中间件用的是 multer diskStorage(只有 path、没有 buffer) => 任何场景都传不上来,
@@ -206,11 +217,11 @@ v0.2.1 修订
本项目不会创建数据库本身
3. 取得发布包并校验(以下是本仓库的真实发布地址; 域名 gitea.kasugano.cn
与属主 zijunchiang 属部署必需信息, 不是隐私项)
curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.7.2/opendance-web-v0.7.3.tar.gz
curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.7.2/opendance-web-v0.7.4.tar.gz
curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.7.2/SHA256SUMS
sha256sum -c SHA256SUMS # 期望输出 "OK"
4. 解压并生成配置(交互式引导, 逐项问答, 口令不回显)
tar -xzf opendance-web-v0.7.3.tar.gz && cd opendance-web-v0.7.3
tar -xzf opendance-web-v0.7.4.tar.gz && cd opendance-web-v0.7.4
bash deploy/init-env.sh
5. 安装(建用户与目录 -> 装依赖 -> 迁移 -> 注册系统服务 -> 等健康检查)
bash deploy/install.sh
@@ -269,8 +280,8 @@ v0.2.1 修订
(本项目不会创建数据库本身, 也不需要 GRANT OPTION / FILE / SUPER 等管理权限)
部署步骤
tar -xzf opendance-web-v0.7.3.tar.gz
cd opendance-web-v0.7.3
tar -xzf opendance-web-v0.7.4.tar.gz
cd opendance-web-v0.7.4
bash deploy/init-env.sh # 首次启动引导: 逐项问答生成 deploy/.env(见下)
bash deploy/install.sh # 已以 root 登录, 不需要 sudo