fix(models): Assimp 缺失时给出可操作报错，部署脚本自动安装
现象：服务器未安装 Assimp，上传 PMX 压缩包只得到 GLB 直出：导出失败（ENOENT）：spawn assimp ENOENT glTF 直出：导出失败（ENOENT）：spawn assimp ENOENT 用户看不出缺什么、怎么装，也不知道只传 glb/vrm 其实不需要它。 修复： 1. 新增 src/common/assimp.ts：按 ASSIMP_BIN -> PATH -> /usr/bin、/usr/local/bin 等常见目录定位可执行文件（只认文件，不认同名目录），转换前先预检； 找不到就一次性给出各发行版安装命令、查过的路径与替代办法， 不再打两条 ENOENT。动作预处理（FBX/glTF -> BVH）复用同一文案。 2. 新增 deploy/assimp-lib.sh：install.sh 按发行版自动安装 （apt-get / dnf / yum / zypper / apk / pacman），装在非常规目录时把绝对 路径写入 deploy/.env 的 ASSIMP_BIN；装不上只告警不中止，可用 SKIP_ASSIMP_INSTALL=1 跳过。check-access.sh 自检增加 Assimp 一行。 3. /health 增加 assimp.path；管理端「概览 -> 服务健康」显示 Assimp 状态， 不可用时给出安装提示。 4. 新增 test/assimp-locate.spec.ts 13 项；强化「assimp 不存在」用例断言安装命令。 测试规模 12 文件 / 193 项。 5. 版本 0.2.2，README(.md/.txt)/DSH.md 同步（前置要求、FAQ、环境变量说明）。
This commit is contained in:
opendance
+35
-13
@@ -1,5 +1,5 @@
|
||||
================================================================
|
||||
OpenDance Studio -- Web 管理服务端 v0.2.1 使用说明
|
||||
OpenDance Studio -- Web 管理服务端 v0.2.2 使用说明
|
||||
================================================================
|
||||
|
||||
本服务端是 OpenDance Studio 三端中的第一端, 负责管理歌曲、VRM 模型与
|
||||
@@ -8,6 +8,21 @@ OpenDance Studio -- Web 管理服务端 v0.2.1 使用说明
|
||||
重要: 本服务端 不部署、不管理 MySQL。数据库为部署方提供的现有实例,
|
||||
连接信息通过 .env 注入。
|
||||
|
||||
v0.2.2 修订
|
||||
1. 修复 Assimp 缺失时的报错与部署体验: 服务器没装 Assimp 时, 上传 .pmx/.fbx
|
||||
(或含它们的压缩包)只得到两条 导出失败(ENOENT): spawn assimp ENOENT,
|
||||
看不出缺什么、怎么装。
|
||||
2. 转换前先定位 Assimp(src/common/assimp.ts): 按 ASSIMP_BIN -> PATH ->
|
||||
/usr/bin、/usr/local/bin 等常见目录查找, 找不到就一次性给出各发行版安装
|
||||
命令、查过的路径与替代办法(只传 .glb/.vrm 不需要它), 不再打两条 ENOENT。
|
||||
3. install.sh 新增 Assimp 检查与自动安装(deploy/assimp-lib.sh): 按发行版调用
|
||||
apt-get / dnf / yum / zypper / apk / pacman; 装在非常规目录时自动把绝对
|
||||
路径写进 deploy/.env 的 ASSIMP_BIN; 装不上只告警不中止(可用
|
||||
SKIP_ASSIMP_INSTALL=1 跳过)。
|
||||
4. deploy/check-access.sh 自检增加 Assimp 一行; 管理端「概览 -> 服务健康」
|
||||
显示 Assimp 状态, 不可用时给出提示。
|
||||
5. 新增 13 项测试(test/assimp-locate.spec.ts)。
|
||||
|
||||
v0.2.1 修订
|
||||
1. 修复部署失败: 模板里的 MODEL_CONVERT_PMX=Hatsune Miku.pmx 值含空格却
|
||||
没加引号, install.sh 用 `set -a; . deploy/.env` 载入时把 Miku.pmx 当命令
|
||||
@@ -30,11 +45,11 @@ v0.2.1 修订
|
||||
2. 准备一个现有的 MySQL / MariaDB 实例, 并建好库与账号(见下方"前置要求")
|
||||
本项目不会创建数据库本身
|
||||
3. 取得发布包并校验(地址用你们自己的制品库替换)
|
||||
curl -LO https://<制品库地址>/opendance-web-v0.2.1.tar.gz
|
||||
curl -LO https://<制品库地址>/opendance-web-v0.2.2.tar.gz
|
||||
curl -LO https://<制品库地址>/SHA256SUMS
|
||||
sha256sum -c SHA256SUMS # 期望输出 "OK"
|
||||
4. 解压并生成配置(交互式引导, 逐项问答, 口令不回显)
|
||||
tar -xzf opendance-web-v0.2.1.tar.gz && cd opendance-web-v0.2.1
|
||||
tar -xzf opendance-web-v0.2.2.tar.gz && cd opendance-web-v0.2.2
|
||||
bash deploy/init-env.sh
|
||||
5. 安装(建用户与目录 -> 装依赖 -> 迁移 -> 注册系统服务 -> 等健康检查)
|
||||
bash deploy/install.sh
|
||||
@@ -76,6 +91,9 @@ v0.2.1 修订
|
||||
- Node.js 22 或更高版本
|
||||
- 进程管理: systemd / OpenRC / SysVinit 均可; 三者都没有也能装
|
||||
(自动降级为 nohup 后台进程 + PID 文件 + crontab @reboot 开机自启)
|
||||
- Assimp 命令行工具(可选但推荐): .pmx/.fbx 模型转换与 FBX/glTF 动作预处理
|
||||
需要它; install.sh 会自动尝试安装(apt-get / dnf / yum / zypper / apk /
|
||||
pacman), 装不上只告警不中止。只上传 .glb/.vrm 模型与 .bvh/.vmd 动作则不需要
|
||||
- 反向代理: 由另外的服务提供, 本项目不要求、也不安装
|
||||
- 一个可连通的现有 MySQL / MariaDB 实例, 并已创建数据库与账号:
|
||||
|
||||
@@ -89,8 +107,8 @@ v0.2.1 修订
|
||||
(本项目不会创建数据库本身, 也不需要 GRANT OPTION / FILE / SUPER 等管理权限)
|
||||
|
||||
部署步骤
|
||||
tar -xzf opendance-web-v0.2.1.tar.gz
|
||||
cd opendance-web-v0.2.1
|
||||
tar -xzf opendance-web-v0.2.2.tar.gz
|
||||
cd opendance-web-v0.2.2
|
||||
bash deploy/init-env.sh # 首次启动引导: 逐项问答生成 deploy/.env(见下)
|
||||
bash deploy/install.sh # 已以 root 登录, 不需要 sudo
|
||||
|
||||
@@ -216,9 +234,11 @@ deploy/.env 初始化引导(deploy/init-env.sh)
|
||||
对外 IP 自测、80/443 有无反代、防火墙放行情况, 并给出修复命令。
|
||||
- 管理页面打开是 404
|
||||
说明访问的是软件 API 端口(默认 3000); 管理页面在管理端端口(默认 3001)。
|
||||
- 上传 .zip 模型包报 422 且提示 Assimp 不可用
|
||||
PMX/FBX 转换依赖 Assimp: apt-get install -y assimp-utils libassimp6;
|
||||
只上传 .glb / .vrm 则不需要它。
|
||||
- 上传 .zip / .pmx / .fbx 报转换失败(ENOENT / Assimp 不可用)
|
||||
PMX/FBX 转换依赖外部 Assimp: apt-get install -y assimp-utils libassimp6
|
||||
(RHEL 系 dnf install -y assimp; install.sh 现在会尝试自动安装)。
|
||||
装好后不需要重启服务; 若不在服务 PATH 中, 在 deploy/.env 里把 ASSIMP_BIN
|
||||
设为绝对路径。只上传 .glb / .vrm 则不需要它。
|
||||
- 安装时报 command not found / 退出码 127, 且提示指向 deploy/.env 某一行
|
||||
该行的值含空格或 shell 元字符却没加引号, 被 shell 当成命令执行了。按预检
|
||||
提示给这个值加引号(如 MODEL_CONVERT_PMX="Hatsune Miku.pmx")后重跑。
|
||||
@@ -249,10 +269,11 @@ deploy/.env 初始化引导(deploy/init-env.sh)
|
||||
cd web-server
|
||||
npm run contracts:check # 契约版本一致性
|
||||
npm run typecheck # TypeScript 严格检查
|
||||
npm run test # 180 项单元测试 / 11 个文件(VMD 31、模型压缩包 24、
|
||||
npm run test # 193 项单元测试 / 12 个文件(VMD 31、模型压缩包 24、
|
||||
# 模型检查器 25、缩略图 8、骨骼过滤 8、
|
||||
# 预处理 25、init-env 16、admin-port 16、
|
||||
# access-log 9、VRM 检查器 6、.env 预检 12)
|
||||
# access-log 9、VRM 检查器 6、.env 预检 12、
|
||||
# Assimp 定位与安装 13)
|
||||
npm run build # 生产构建
|
||||
npm run start:prod & # 启动
|
||||
npm run test:smoke # 57 项端到端冒烟(需要数据库可连通)
|
||||
@@ -298,9 +319,10 @@ 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 单文件模型时必须能调用到,
|
||||
否则转换失败(422)
|
||||
ASSIMP_BIN Assimp 可执行文件(install.sh 会自动安装并把解析出的绝对
|
||||
路径写入此项)。.pmx/.fbx 模型转换与 FBX/glTF 动作预处理
|
||||
需要; 缺失时上传会失败并给出安装命令, 只上传 .glb/.vrm 与
|
||||
.bvh/.vmd 动作不受影响
|
||||
MODEL_CONVERT_FORMAT 需要转换的模型(PMX/FBX)的交付格式:
|
||||
glb(默认, 两个客户端都原生加载)| vrm
|
||||
vrm = 在 GLB 之上补 VRMC_vrm 扩展(humanoid 骨骼 / 表情语义),
|
||||
|
||||
Reference in New Issue
Block a user