zijunchiang/opendance-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity

docs(readme): 新增初次部署清单与常见问题；统一 root 执行写法；清除 markdown 粗体标记与残留真实库名

Browse Source
This commit is contained in:
zijunchiang
2026-09-15 21:27:29 +08:00
parent 9c8379e5eb
commit ebd871018f
19 changed files with 345 additions and 296 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.txt
+86 -37
View File
@@ -5,27 +5,56 @@ OpenDance Studio -- Web 管理服务端 v0.2.0 使用说明
本服务端是 OpenDance Studio 三端中的第一端, 负责管理歌曲、VRM 模型与
动作来源, 是 Windows 客户端与 Android 辅助 App 的唯一数据源与契约权威。
重要: 本服务端 **不部署、不管理 MySQL**。数据库为部署方提供的现有实例,
重要: 本服务端 不部署、不管理 MySQL。数据库为部署方提供的现有实例,
连接信息通过 .env 注入。
--
一、部署到 Linux 服务器(业务服务, 不含反向代理)
--
初次部署(从零跑起来)
按顺序做, 每步都有验证方法:
1. 准备一台 Linux 服务器, 以 root 登录(不需要 sudo), 装好 Node.js 22+
node -v # 期望 v22 或更高
2. 准备一个现有的 MySQL / MariaDB 实例, 并建好库与账号(见下方"前置要求")
本项目不会创建数据库本身
3. 取得发布包并校验(地址用你们自己的制品库替换)
curl -LO https://<制品库地址>/opendance-web-v0.2.0.tar.gz
curl -LO https://<制品库地址>/SHA256SUMS
sha256sum -c SHA256SUMS # 期望输出 "OK"
4. 解压并生成配置(交互式引导, 逐项问答, 口令不回显)
tar -xzf opendance-web-v0.2.0.tar.gz && cd opendance-web-v0.2.0
bash deploy/init-env.sh
5. 安装(建用户与目录 -> 装依赖 -> 迁移 -> 注册系统服务 -> 等健康检查)
bash deploy/install.sh
6. 验证(把 <服务器地址> 换成实际地址)
curl -fsS http://<服务器地址>:3000/health # 期望 {"status":"ok",...}
curl -sI http://<服务器地址>:3001/ | head -1 # 期望 200, 管理端页面
curl -sI http://<服务器地址>:3000/ | head -1 # 期望 404, API 端口不提供管理页
7. 可选: 回填历史模型的分析与缩略图(新装可跳过)
cd /opt/opendance/web-server
node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000
8. 浏览器打开 http://<服务器地址>:3001/ 进入管理端, 上传曲目/动作/模型并审核
模型上传后状态为"待审核", 审核通过才会被客户端拉取
安全约定: deploy/.env 已被 .gitignore 忽略, 不要提交; 文档、截图、工单里
也不要贴真实的数据库口令、内网地址或域名, 需要时用 <占位符> 代替。
职责边界
本端**只提供业务服务**:NestJS API + 管理端页面。
**反向代理由另外的服务/团队负责**, 本项目不安装、不配置任何反代软件,
本端只提供业务服务:NestJS API + 管理端页面。
反向代理由另外的服务/团队负责, 本项目不安装、不配置任何反代软件,
只在 deploy/proxy/ 下提供 IIS 与 nginx 的配置说明文档。
部署形态
Node 业务服务由系统服务托管, 同时监听**两个端口**, 职责分开:
Node 业务服务由系统服务托管, 同时监听两个端口, 职责分开:
软件 API 端口(默认 3000, 给 Windows/Godot 客户端与 Android App)
/api/ REST API
/health 健康检查
/static/ 上传文件
/contracts/ 契约快照
该端口**不提供管理页面**,/ 与 /songs 等一律返回 404(有意设计)
该端口不提供管理页面,/ 与 /songs 等一律返回 404(有意设计)
管理端端口(默认 3001, 给浏览器)
管理页面(本服务自带, 含 SPA 深链接回退)+ 上面全部接口
@@ -35,16 +64,16 @@ OpenDance Studio -- Web 管理服务端 v0.2.0 使用说明
前置要求
- Linux 服务器, 有 root 权限(不需要 sudo, 直接以 root 执行即可)
- Node.js 22 或更高版本
- 进程管理: systemd / OpenRC / SysVinit 均可; **三者都没有也能装**
- 进程管理: systemd / OpenRC / SysVinit 均可; 三者都没有也能装
(自动降级为 nohup 后台进程 + PID 文件 + crontab @reboot 开机自启)
- 反向代理: 由另外的服务提供, 本项目不要求、也不安装
- 一个可连通的现有 MySQL / MariaDB 实例, 并已创建数据库与账号:
CREATE DATABASE IF NOT EXISTS dpendance
CREATE DATABASE IF NOT EXISTS opendance
CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER IF NOT EXISTS 'dpendance'@'%' IDENTIFIED BY '<密码>';
CREATE USER IF NOT EXISTS 'opendance_app'@'%' IDENTIFIED BY '<数据库口令>';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP, REFERENCES
ON dpendance.* TO 'dpendance'@'%';
ON opendance.* TO 'opendance_app'@'%';
FLUSH PRIVILEGES;
(本项目不会创建数据库本身, 也不需要 GRANT OPTION / FILE / SUPER 等管理权限)
@@ -53,7 +82,7 @@ OpenDance Studio -- Web 管理服务端 v0.2.0 使用说明
tar -xzf opendance-web-v0.2.0.tar.gz
cd opendance-web-v0.2.0
bash deploy/init-env.sh # 首次启动引导: 逐项问答生成 deploy/.env(见下)
sudo bash deploy/install.sh
bash deploy/install.sh # 已以 root 登录, 不需要 sudo
也可跳过引导手工填写:
cp deploy/.env.example deploy/.env
@@ -69,7 +98,7 @@ deploy/.env 初始化引导(deploy/init-env.sh)
(若安装目录里已有上次安装留下的 .env, 则直接复用, 不会重复提问)。
也可以单独运行: 逐项询问数据库与端口, 回车保留默认值, 写盘前做必填项与
端口范围校验, 并可用项目自带的 mysql2 做一次数据库连通性自检--口令只经
环境变量传给子进程, 出错信息与摘要一律显示 ***。
环境变量传给子进程, 出错信息与摘要一律显示 *。
bash deploy/init-env.sh # 交互引导(终端里逐项询问)
bash deploy/init-env.sh --force # 已有 .env 也重新逐项询问
@@ -77,10 +106,10 @@ deploy/.env 初始化引导(deploy/init-env.sh)
逐项询问的字段(共 8 个):
DB_HOST / DB_PORT / DB_USER / DB_PASS / DB_NAME / PORT / ADMIN_PORT / HOST
DB_PASS 用 read -s 不回显; 所有字段按约定写成 `键=值`(**不加引号**),
DB_PASS 用 read -s 不回显; 所有字段按约定写成 `键=值`(不加引号),
因此口令请勿含会破坏 shell 语法的字符(& $ ` \ 空格; | < > ()!),
脚本检测到会告警。写回只替换或追加这 8 个键、保留模板注释, 写完
chmod 600 并回读校验; 结尾打印摘要(口令 ***)与本次变更列表。
chmod 600 并回读校验; 结尾打印摘要(口令 *)与本次变更列表。
开关:
--force 已有 .env 也重新逐项询问
@@ -111,7 +140,7 @@ deploy/.env 初始化引导(deploy/init-env.sh)
(软件 API 端口上没有管理页面: http://<host>:3000/ 返回 404, 属正常)
对外访问
由反向代理**按用途分别转发两个端口**:
由反向代理按用途分别转发两个端口:
浏览器管理界面 -> http://<后端地址>:3001
Windows/Godot 客户端与 Android App -> http://<后端地址>:3000
配置样例与说明(含两个端口的转发写法):
@@ -137,7 +166,7 @@ deploy/.env 初始化引导(deploy/init-env.sh)
例: APP_DIR=/srv/opendance bash deploy/install.sh
升级
解压新版本后重新执行 sudo bash deploy/install.sh 即可(会覆盖程序文件,
解压新版本后重新执行 bash deploy/install.sh 即可(会覆盖程序文件,
保留 deploy/.env 与上传数据)。
卸载
@@ -164,6 +193,26 @@ deploy/.env 初始化引导(deploy/init-env.sh)
反代配置: 不在本机, 无需在此维护
常见问题(初次部署)
- 安装脚本报"未找到 node" 或 Node 版本过低
装 Node.js 22+ 后重跑; 脚本会打印检测到的版本号。
- 安装脚本报"deploy/.env 中 DB_* 未设置"
先跑 bash deploy/init-env.sh 生成配置, 或手工 cp deploy/.env.example deploy/.env 后填写。
- 健康检查返回 503
服务起来了但连不上数据库: 核对 deploy/.env 的 DB_HOST/DB_PORT/DB_USER/DB_PASS/DB_NAME,
以及数据库账号是否允许从本机 IP 连接(GRANT ... TO 'user'@'%' 或具体主机)。
- 服务本机 curl 通、外部访问不了
bash deploy/check-access.sh 一次定位: 它会打印 HOST/PORT、实际监听地址、
对外 IP 自测、80/443 有无反代、防火墙放行情况, 并给出修复命令。
- 管理页面打开是 404
说明访问的是软件 API 端口(默认 3000); 管理页面在管理端端口(默认 3001)。
- 上传 .zip 模型包报 422 且提示 Assimp 不可用
PMX/FBX 转换依赖 Assimp: apt-get install -y assimp-utils libassimp6;
只上传 .glb / .vrm 则不需要它。
- 模型审核界面显示"未分析 / 无预览图"
该模型是升级前入库的: 调 POST /api/models/<id>/reanalyze, 或批量跑
node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000。
--
二、本地开发
--
@@ -211,11 +260,11 @@ deploy/.env 初始化引导(deploy/init-env.sh)
DB_LOGGING 是否打印 SQL(默认 false)
PORT 软件 API 监听端口(默认 3000)。给 Windows/Godot 客户端
与 Android App 调用, 只提供 /api、/health、/static、
/contracts,**不提供管理页面**
/contracts,不提供管理页面
ADMIN_PORT 管理端端口(默认 PORT + 1, 即 3001)。浏览器访问管理界面
(管理页面 + 上面全部接口); 设为与 PORT 相同即为
单端口兼容模式, 日志会提示「未分端口」
HOST 监听地址(软件 API 端口),**默认 0.0.0.0**, 因此装好即可
HOST 监听地址(软件 API 端口),默认 0.0.0.0, 因此装好即可
被客户端访问(此时请用防火墙限制来源)。反代与后端同机时
建议改为 127.0.0.1, 让后端不直接对外暴露
ADMIN_HOST 管理端监听地址(可选, 默认跟随 HOST;HOST 未设置时同样
@@ -230,7 +279,7 @@ deploy/.env 初始化引导(deploy/init-env.sh)
会在代理层被拒(nginx client_max_body_size /
IIS requestLimits), 详见 deploy/proxy/README.md
ASSIMP_BIN 可选: Assimp 可执行文件, FBX/glTF 动作预处理需要;
上传 .zip 模型包、或 .pmx/.fbx 单文件模型时**必须**能调用到,
上传 .zip 模型包、或 .pmx/.fbx 单文件模型时必须能调用到,
否则转换失败(422)
MODEL_CONVERT_FORMAT 需要转换的模型(PMX/FBX)的交付格式:
glb(默认, 两个客户端都原生加载)| vrm
@@ -279,19 +328,19 @@ deploy/.env 初始化引导(deploy/init-env.sh)
相同内容只落盘一次(sha256 去重)。
支持的模型格式(POST /api/models 上传)
**系统以 GLB / VRM 为主力格式**: 服务端与客户端都把这两种格式作为一等公民
系统以 GLB / VRM 为主力格式: 服务端与客户端都把这两种格式作为一等公民
(Godot 客户端用内置 GLTFDocument 加载 glTF/GLB/VRM, 见
opendance-windows/src/model/vrm_loader.gd, 本次无需改动)。
glTF Binary .glb 主力(P0)-- **直接导入**, 不重编码
glTF Binary .glb 主力(P0)-- 直接导入, 不重编码
VRM .vrm 主力(P0)-- 直接导入; GLB + VRM 扩展
(humanoid / 表情 / springBone / meta)
glTF .gltf P1 -- 直接导入(分离的 .bin / 贴图需随 .zip 一起上传)
MMD 压缩包 .zip P1 -- **自动搜索包内可用模型**(见下)
MMD 压缩包 .zip P1 -- 自动搜索包内可用模型(见下)
MMD 模型 .pmx P2(输入)-- 服务端转换, 优先 GLB、其次 VRM
FBX .fbx P2(输入)-- 服务端转换, 优先 GLB、其次 VRM
入库后**一律 status=pending(待审核)**: 上传不再自动发布、不再自动设为默认,
入库后一律 status=pending(待审核): 上传不再自动发布、不再自动设为默认,
必须经审核通过(模型审核面板可勾选「同时设为全局默认模型」)才对客户端可见。
升级后回填已有模型(面数 / 骨骼 / 缩略图)
@@ -303,17 +352,17 @@ deploy/.env 初始化引导(deploy/init-env.sh)
若模型文件在存储中已丢失, 接口返回 409 并提示先恢复文件, 不会用空结果覆盖已有数据。
模型压缩包(.zip)自动搜索与转换
上传的 .zip 不再"只找 .pmx", 而是**自动搜索包内可用模型**, 走
上传的 .zip 不再"只找 .pmx", 而是自动搜索包内可用模型, 走
"解压 -> 选主模型 -> 直接导入或转换 -> 回读校验 -> 入库", 而不是把压缩包当模型存下来。
选主模型 优先级 .vrm -> .glb -> .gltf -> .pmx -> .fbx; 同一优先级内按
"MODEL_CONVERT_PMX 指名字 -> 目录最浅 -> 文件最大"。
命中 .vrm/.glb/.gltf 时**直接导入**(不重编码)。
命中 .vrm/.glb/.gltf 时直接导入(不重编码)。
转换 只有 .pmx/.fbx 需要转换。链路: assimp export -> .glb(首选);
失败则 assimp export -> .gltf, 再由 gltf-packer.ts 自行打包回 GLB;
MODEL_CONVERT_FORMAT=vrm 时在 GLB 之上补 VRMC_vrm 扩展封装成
VRM 1.0(humanoid 骨骼不全则回退交付 GLB, 缺失骨骼写进说明)。
校验 每一步产物**必须**用 `assimp info` 回读校验。Assimp 会"写出损坏文件"
校验 每一步产物必须用 `assimp info` 回读校验。Assimp 会"写出损坏文件"
(实测 PMX 导出 FBX 退出码 11、回读报 FBX-DOM 错误), 只看退出码
会把坏文件入库。
贴图 GLB 产物里 Assimp 会把贴图写成外部 URI(还带反斜杠), 服务端把
@@ -339,16 +388,16 @@ deploy/.env 初始化引导(deploy/init-env.sh)
maxBoneDepth=23;missingRequiredBones 为全部 16 根
(日文 MMD 骨名无法映射到 humanoid, 审核界面会直接标红)。
- 直接上传 .glb -> HTTP 201 / 0.36s、conversionNote=`直接导入(GLB, 未做重编码)`,
入库文件 sha256 与源文件**一致**(不重编码, 字节级保留)。
入库文件 sha256 与源文件一致(不重编码, 字节级保留)。
模型分析、缩略图与 3D 预览(入库后自动执行, 失败不影响入库)
分析 model-inspector.ts 解析 GLB/VRM: 面数 / 顶点 / 网格 / 材质 / 贴图 /
节点 / 形变目标 / 动画 / 蒙皮骨骼数 / **骨骼树** / humanoid 覆盖 /
节点 / 形变目标 / 动画 / 蒙皮骨骼数 / 骨骼树 / humanoid 覆盖 /
可驱动性(缺哪些必需骨骼)/ warnings, 写入 models.stats
(迁移 AddModelStats1789460000000, 新增 models.stats TEXT)。
缩略图 model-thumbnail.ts 用纯 TS 软件光栅化生成 PNG(读 GLB/glTF -> 应用节点
层级与蒙皮 -> 包围盒自动构图 -> 透视投影 -> z-buffer 逐三角形平面着色 ->
手写 PNG 编码),**零原生依赖**(不需要 canvas / headless-gl / puppeteer)。
手写 PNG 编码),零原生依赖(不需要 canvas / headless-gl / puppeteer)。
默认 512x512, 写入 models.thumbnail_asset_id / thumbnailUrl;
失败或非 glTF 容器时留空, 列表页退化为格式占位图。
实测: 512x512 PNG / 15,043 字节, 目视确认为居中的 T-pose 角色图;
@@ -357,11 +406,11 @@ deploy/.env 初始化引导(deploy/init-env.sh)
GLB/VRM」); 列表页显示 40px 小缩略图, 审核面板显示 116px 缩略图。
审核流程(模型)
模型上传后为 pending, 在管理端「审核」页的**模型审核面板**里查看并决定:
模型上传后为 pending, 在管理端「审核」页的模型审核面板里查看并决定:
面板内容 体积 / 格式 / 容器 / VRM 版本 / 面数 / 顶点 / 网格 / 材质 / 贴图 /
骨骼 / 节点 / 形变目标 / 动画 / humanoid 覆盖(已映射/总数 + 明细)/
**可驱动性结论**(缺哪些必需骨骼)/ warnings。
可驱动性结论(缺哪些必需骨骼)/ warnings。
骨骼预览 骨骼详细界面: 扁平骨骼树按 depth 缩进、显示骨骼名、是否参与蒙皮、
humanoid 映射徽章、子节点数; 支持按名搜索(保留祖先链)、
「仅显示蒙皮骨骼」开关、限高滚动 + 只渲染前 400 行(千根骨骼不卡)。
@@ -375,23 +424,23 @@ deploy/.env 初始化引导(deploy/init-env.sh)
GET /api/catalog/export 的 defaultModelId 按以下顺序解析:
0. 环境变量 DEFAULT_MODEL_ID(且模型存在且已发布)
1. 源码种子 src/config/default-model.ts 的 DEFAULT_MODEL_SEED--按**上传压缩包的
sha256** 匹配已发布模型(用户文件永远稳定; 不能用转换产物的 sha256 --
1. 源码种子 src/config/default-model.ts 的 DEFAULT_MODEL_SEED--按上传压缩包的
sha256 匹配已发布模型(用户文件永远稳定; 不能用转换产物的 sha256 --
Assimp 每次导出的字节都略有不同), 换库 / 重建库后仍有效
2. format='vrm' 且 published 且 is_primary=1
3. 任意 published 的 VRM(id 升序取第一个)
4. id 最小的已发布模型
5. 无可用模型 -> 客户端用内置占位模型
源码种子 src/config/default-model.ts 当前为**空种子**(占位: id=null、sha256 空串),
源码种子 src/config/default-model.ts 当前为空种子(占位: id=null、sha256 空串),
此时 defaultModelId 直接从第 2 步的 VRM 优先规则开始解析; 按下面的方式设定默认
模型后, 服务端会把种子写成真实内容。
实测(v0.2.0):`POST /api/reviews/model/22/approve` 带 `setPrimary:true` -> 200,
模型 status=published、isPrimary=true, 源码种子写入 sourceSha256=72eb6882...;
重建后 `GET /api/catalog/export` 的 defaultModelId 由 VRM 变为 **22**
重建后 `GET /api/catalog/export` 的 defaultModelId 由 VRM 变为 22
(库中另有 2 个已发布 VRM)。
也可手工指定: POST /api/models/:id/primary。
第 1 步的源码写入由服务端在**审核通过并勾选 setPrimary**(或调用 primary 接口)
第 1 步的源码写入由服务端在审核通过并勾选 setPrimary(或调用 primary 接口)
时完成; 生产 systemd 加固(ProtectSystem=strict)下服务进程写不了程序目录,
可改用下面的 CLI 补写。
@@ -416,7 +465,7 @@ deploy/.env 初始化引导(deploy/init-env.sh)
说明: --url 默认 http://127.0.0.1:3000,--source-type 默认 other。
v0.2.0 起上传一律 pending, 因此 CLI 上传路径只负责转换入库与写源码种子;
要让它在 `defaultModelId` 中生效, 仍需在管理端**审核通过**(勾选「同时设为全局
要让它在 `defaultModelId` 中生效, 仍需在管理端审核通过(勾选「同时设为全局
默认模型」)或调用 `POST /api/models/:id/primary`。
支持的动作格式(POST /api/motions 上传 -> POST /api/motions/:id/preprocess 预处理)
@@ -478,7 +527,7 @@ VMD 动作上传前后自查
2. 数据库账号使用最小权限, 不授予 GRANT OPTION / FILE / SUPER。
3. 本版本未内置管理端登录认证, 请部署在内网, 或在反向代理层加 Basic Auth / SSO。
4. 上传的模型与动作默认需填写来源五元组并通过审核后才对客户端可见。
**模型上传后一律 pending**: 不再自动发布、不再自动设为默认; 默认模型只在
模型上传后一律 pending: 不再自动发布、不再自动设为默认; 默认模型只在
审核通过时勾选「同时设为全局默认模型」(`setPrimary:true`)或调用
`POST /api/models/:id/primary`(仅 published)时才设置(见 五)。
5. 未使用 SMPL 拓扑, 统一 MediaPipe 33 点, 规避非商用许可限制。