diff --git a/DSH.md b/DSH.md index 069e0b9..7fac92e 100644 --- a/DSH.md +++ b/DSH.md @@ -101,7 +101,7 @@ opendance-web/ │ ├── admin/ # React 管理端 │ │ ├── src/components/ModelReviewPanel.tsx # 模型审核面板 + 骨骼详细界面 │ │ └── src/lib/bone-tree.ts # 骨骼树过滤（搜索保留祖先链） -│ ├── test/ # 单元测试 + 端到端冒烟（11 文件 / 180 项） +│ ├── test/ # 单元测试 + 端到端冒烟（12 文件 / 193 项） │ │ # mmd-vmd 31 / model-archive 24 / model-inspector 25 │ │ # / model-thumbnail 8 / admin-bone-filter 8 │ │ # / preprocess 25 / init-env 16 / admin-port 16 @@ -334,7 +334,7 @@ POST /api/models ─┬─.glb /.vrm /.gltf ─▶ importModelFile() 直接导 T-pose 角色图；真实 10MB VRM(83 关节、5307 顶点)单张耗时 60-121ms（中位 79ms）。 - 管理端 3D 预览放开到 `vrm/glb/gltf`(`fbx` 仍提示"仅归档，请先转换为 GLB/VRM"); 列表页显示 40px 缩略图。 -- 测试：`npx vitest run` -> **11 个文件 / 180 项通过** +- 测试：`npx vitest run` -> **12 个文件 / 193 项通过** (`model-inspector` 25、`model-thumbnail` 8、`admin-bone-filter` 8、 `model-archive` 24、`mmd-vmd` 31、`preprocess` 25、`init-env` 16、 `admin-port` 16、`access-log` 9、`vrm-inspector` 6）。 diff --git a/README.md b/README.md index 9a72d0b..ce82037 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,15 @@ OpenDance Studio **阶段一**: Web 管理服务端(NestJS + TypeORM + 现有 My ## 状态 -**阶段一已完成**: T-WEB-001 -> T-WEB-010 全部落地,当前版本 **v0.2.1**(契约 `rest-api / data-models / model-formats 0.4.0`、`database 0.3.0`)。 +**阶段一已完成**: T-WEB-001 -> T-WEB-010 全部落地,当前版本 **v0.2.2**(契约 `rest-api / data-models / model-formats 0.4.0`、`database 0.3.0`)。 + +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 修订: @@ -45,15 +53,15 @@ v0.2.0 主要变更: 3. 取得发布包并校验(地址用你们自己的制品库替换; 下面是本仓库的发布地址) ```bash - curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.1/opendance-web-v0.2.1.tar.gz - curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.1/SHA256SUMS + curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.2/opendance-web-v0.2.2.tar.gz + curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.2/SHA256SUMS sha256sum -c SHA256SUMS # 期望输出 "OK" ``` 4. 解压并生成配置(交互式引导,逐项问答,口令不回显) ```bash - 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 ``` @@ -103,6 +111,9 @@ Node 业务服务由系统服务托管,**同时监听两个端口**,职责分开 - Linux 服务器,有 **root** 权限(不需要 sudo,直接以 root 执行即可) - **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 实例,并已创建数据库与账号: @@ -120,8 +131,8 @@ FLUSH PRIVILEGES; ### 5. 部署步骤 ```bash -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 ``` @@ -261,7 +272,7 @@ bash /opt/opendance/deploy/ctl.sh status | restart | logs | 健康检查返回 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` 则不需要它 | +| 上传 `.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"`)后重跑;`deploy/env-lib.sh` 会提前拦住并给出行号 | | 模型审核界面显示"未分析 / 无预览图" | 该模型是升级前入库的:调 `POST /api/models//reanalyze`,或批量跑 `node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000` | @@ -291,10 +302,11 @@ npm run dev # http://localhost:5173(/api 与 /health 代理到 3000) 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 项端到端冒烟(需要数据库可连通) @@ -316,7 +328,7 @@ cd ../admin && npm run build # 管理端构建 | `ADMIN_DIR` | `../admin`(即 `/opt/opendance/admin`) | 管理端静态站点目录 | | `STORAGE_DIR` | `/var/lib/opendance/storage` | 上传文件存储目录(原生部署默认值) | | `UPLOAD_MAX_BYTES` | `536870912`(512 MiB) | 单文件上限。反向代理层的同名限制必须不小于此值,否则大模型上传会在代理层被拒(nginx `client_max_body_size` / IIS `requestLimits`),详见 `deploy/proxy/README.md` | -| `ASSIMP_BIN` | - | 可选:Assimp 可执行文件。FBX/glTF 动作预处理需要;上传 `.zip` 模型包、或 `.pmx/.fbx` 单文件模型时必须能调用到,否则转换失败(422) | +| `ASSIMP_BIN` | `assimp` | Assimp 可执行文件(`install.sh` 会自动安装并解析出绝对路径写入此项)。`.pmx/.fbx` 模型转换与 FBX/glTF 动作预处理需要;缺失时上传会失败并给出安装命令,只上传 `.glb/.vrm` 不受影响 | | `MODEL_CONVERT_FORMAT` | `glb` | 需要转换的模型(PMX/FBX)的交付格式:`glb`(两个客户端都原生加载)或 `vrm`。`vrm` = 在 GLB 之上补 `VRMC_vrm` 扩展(humanoid 骨骼 / 表情语义),humanoid 骨骼映射不全时自动回退交付 GLB 并写进 `conversion_note`。产物一律用 `assimp info` 回读校验 | | `MODEL_CONVERT_PMX` | `"Hatsune Miku.pmx"` | 压缩包内优先选用的 PMX 文件名(大小写不敏感);找不到时按「格式优先级 -> 目录最浅 -> 文件最大」挑选 | | `MODEL_CONVERT_TIMEOUT_MS` | `180000` | 单次转换超时(毫秒) | diff --git a/README.txt b/README.txt index 748bae8..3fe950b 100644 --- a/README.txt +++ b/README.txt @@ -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 骨骼 / 表情语义), diff --git a/deploy/assimp-lib.sh b/deploy/assimp-lib.sh new file mode 100644 index 0000000..97ebb1f --- /dev/null +++ b/deploy/assimp-lib.sh @@ -0,0 +1,68 @@ +#!/bin/bash +# ============================================================ +# OpenDance Studio Web API —— 外部依赖 Assimp 的定位与安装 +# +# 本文件被 install.sh 引用（不要单独执行）。 +# +# Assimp 是**外部**命令行工具（BSD-3-Clause），不在 Node 依赖里。 +# 它只影响两件事： +# * 上传 .pmx / .fbx（或含它们的压缩包）时的服务端转换； +# * FBX / glTF 动作的预处理。 +# 直接上传 .glb / .vrm 模型，或 .bvh / .vmd / 关键点 JSON 动作，都不需要它。 +# 因此这里「装不上」不叫失败，但必须给出结论与可复制的安装命令。 +# ============================================================ + +# 当前发行版对应的安装命令（用于提示） +opendance_assimp_install_cmd() { + if command -v apt-get >/dev/null 2>&1; then + printf 'apt-get update && apt-get install -y assimp-utils libassimp6' + elif command -v dnf >/dev/null 2>&1; then + printf 'dnf install -y assimp' + elif command -v yum >/dev/null 2>&1; then + printf 'yum install -y assimp' + elif command -v zypper >/dev/null 2>&1; then + printf 'zypper --non-interactive install assimp' + elif command -v apk >/dev/null 2>&1; then + printf 'apk add --no-cache assimp' + elif command -v pacman >/dev/null 2>&1; then + printf 'pacman -S --noconfirm assimp' + else + printf '用发行版包管理器安装 assimp 命令行工具' + fi +} + +# 真正执行安装（静默细节，成功返回 0） +opendance_assimp_install() { + if command -v apt-get >/dev/null 2>&1; then + DEBIAN_FRONTEND=noninteractive apt-get update -qq && + DEBIAN_FRONTEND=noninteractive apt-get install -y -qq assimp-utils libassimp6 + elif command -v dnf >/dev/null 2>&1; then dnf install -y -q assimp + elif command -v yum >/dev/null 2>&1; then yum install -y -q assimp + elif command -v zypper >/dev/null 2>&1; then zypper --non-interactive install assimp + elif command -v apk >/dev/null 2>&1; then apk add --no-cache assimp + elif command -v pacman >/dev/null 2>&1; then pacman -S --noconfirm assimp + else return 1 + fi +} + +# 解析 Assimp 的实际路径：ASSIMP_BIN -> PATH -> 常见系统目录 +# 找到时把绝对路径打印到 stdout 并返回 0；否则返回 1（stdout 为空） +opendance_assimp_resolve() { + local bin="${ASSIMP_BIN:-assimp}" dir candidate + # 必须同时是**文件**且可执行：只判 -x 会把目录（例如 ASSIMP_BIN=/usr/bin/）当成可执行文件 + if [ -f "$bin" ] && [ -x "$bin" ]; then printf '%s' "$bin"; return 0; fi + if command -v "$bin" >/dev/null 2>&1; then command -v "$bin"; return 0; fi + for dir in /usr/bin /usr/local/bin /usr/sbin /usr/local/sbin /snap/bin; do + candidate="$dir/${bin##*/}" # 用参数展开代替 basename: PATH 极窄时 basename 可能不可用 + if [ -f "$candidate" ] && [ -x "$candidate" ]; then printf '%s' "$candidate"; return 0; fi + done + return 1 +} + +# 该目录是否已在服务的默认 PATH 中（否 -> 需要把绝对路径写进 .env） +opendance_assimp_needs_env_path() { + case "$(dirname "${1:-}")" in + /bin|/usr/bin|/usr/local/bin|/sbin|/usr/sbin) return 1 ;; + *) return 0 ;; + esac +} diff --git a/deploy/check-access.sh b/deploy/check-access.sh index 186925b..0fce671 100755 --- a/deploy/check-access.sh +++ b/deploy/check-access.sh @@ -16,6 +16,7 @@ APP_DIR="${1:-/opt/opendance}" PORT="" HOST_CFG="" PROBLEMS=0 +ASSIMP_MISSING=0 c_red() { printf '\033[31m%s\033[0m\n' "$*"; } c_grn() { printf '\033[32m%s\033[0m\n' "$*"; } @@ -216,9 +217,33 @@ if [ "$FW_FOUND" -eq 0 ]; then info "注意：云服务器还需检查控制台的「安全组 / 网络 ACL」是否放行 $PORT" fi +# ---------- 6.5 可选依赖 Assimp ---------- +title "可选依赖 Assimp（.pmx/.fbx 模型转换、FBX/glTF 动作预处理）" +if [ -f "$(dirname "$0")/assimp-lib.sh" ]; then + # shellcheck source=deploy/assimp-lib.sh + . "$(dirname "$0")/assimp-lib.sh" + ASSIMP_PATH="$(opendance_assimp_resolve || true)" + if [ -n "$ASSIMP_PATH" ]; then + ok "Assimp 可用：$ASSIMP_PATH（$("$ASSIMP_PATH" version 2>/dev/null | head -1)）" + else + warn "未安装 Assimp：上传 .pmx / .fbx（或含它们的压缩包）会报转换失败" + info "安装：$(opendance_assimp_install_cmd)" + info "只上传 .glb / .vrm 模型与 .bvh / .vmd 动作则不受影响" + ASSIMP_MISSING=1 + fi +else + warn "未找到 deploy/assimp-lib.sh，跳过 Assimp 检查" +fi + # ---------- 7. 结论 ---------- title "结论" +if [ "${ASSIMP_MISSING:-0}" = "1" ]; then + c_yel " 提示：未安装 Assimp，.pmx / .fbx 模型转换与 FBX / glTF 动作预处理不可用（与访问无关）。" + echo " 安装：$(opendance_assimp_install_cmd 2>/dev/null || echo '用发行版包管理器安装 assimp')" + echo +fi + if [ "$PROBLEMS" -eq 0 ]; then c_grn " 未发现本机侧问题。" echo " 若仍访问不了，按顺序排查：" diff --git a/deploy/install.sh b/deploy/install.sh index 77bc9bd..0b64992 100755 --- a/deploy/install.sh +++ b/deploy/install.sh @@ -32,6 +32,8 @@ cd "$SRC_DIR" # 载入前先查一遍，给出带行号与改法的中文提示。 # shellcheck source=deploy/env-lib.sh . "$SRC_DIR/deploy/env-lib.sh" +# shellcheck source=deploy/assimp-lib.sh +. "$SRC_DIR/deploy/assimp-lib.sh" APP_DIR="${APP_DIR:-/opt/opendance}" SERVICE_USER="${SERVICE_USER:-opendance}" @@ -174,6 +176,38 @@ log "运行用户：$SERVICE_USER" log "上传目录：$STORAGE_DIR" log "目标数据库：${DB_HOST}:${DB_PORT:-3306}/${DB_NAME}（现有实例，本脚本不会创建或管理数据库）" +# ---------- 0.5 可选外部依赖：Assimp ---------- +# 逻辑与文案在 deploy/assimp-lib.sh（可单独测试）：Assimp 是外部命令行工具 +# （BSD-3-Clause），不在 Node 依赖里，只影响 .pmx/.fbx 模型转换与 FBX/glTF +# 动作预处理；装不上不中止安装，但必须当场给出结论与可复制的安装命令。 +log "检查 Assimp（可选依赖：.pmx/.fbx 模型转换、FBX/glTF 动作预处理需要）" +ASSIMP_PATH="$(opendance_assimp_resolve || true)" +if [ -z "$ASSIMP_PATH" ] && [ "${SKIP_ASSIMP_INSTALL:-0}" != "1" ]; then + log "未找到 Assimp，尝试用系统包管理器安装：$(opendance_assimp_install_cmd)" + if opendance_assimp_install >/dev/null 2>&1; then + ASSIMP_PATH="$(opendance_assimp_resolve || true)" + else + warn "自动安装 Assimp 失败（离线环境或该发行版没有对应软件包）" + fi +fi +if [ -n "$ASSIMP_PATH" ]; then + log "Assimp：$ASSIMP_PATH（$("$ASSIMP_PATH" version 2>/dev/null | head -1)）" + if opendance_assimp_needs_env_path "$ASSIMP_PATH"; then + log "该目录不在服务默认 PATH 中，把 ASSIMP_BIN=\"$ASSIMP_PATH\" 写入 deploy/.env" + if grep -qE '^[[:space:]]*#?[[:space:]]*ASSIMP_BIN=' deploy/.env; then + sed -i "0,/^[[:space:]]*#\?[[:space:]]*ASSIMP_BIN=.*/s||ASSIMP_BIN=\"$ASSIMP_PATH\"|" deploy/.env + else + printf '\nASSIMP_BIN="%s"\n' "$ASSIMP_PATH" >> deploy/.env + fi + fi +else + warn "未找到 Assimp：上传 .pmx / .fbx（或含它们的压缩包）会转换失败，FBX / glTF 动作也无法预处理。" + warn " 手动安装：$(opendance_assimp_install_cmd)" + warn " 只上传 .glb / .vrm 模型与 .bvh / .vmd / 关键点 JSON 动作则不受影响。" + warn " 已装好但不在 PATH？在 deploy/.env 里设置 ASSIMP_BIN 为绝对路径后重跑本脚本。" + warn " 也可用 SKIP_ASSIMP_INSTALL=1 跳过自动安装。" +fi + # ---------- 1. 系统用户与目录 ---------- if ! id -u "$SERVICE_USER" >/dev/null 2>&1; then log "创建系统用户 $SERVICE_USER" diff --git a/project.yaml b/project.yaml index b6e27fd..4142a26 100644 --- a/project.yaml +++ b/project.yaml @@ -1,5 +1,5 @@ project: opendance-web-server -version: 0.2.1 +version: 0.2.2 repository: opendance-web default_branch: main contracts_version: 0.4.0 @@ -60,7 +60,7 @@ tasks: status: done deliverable: - artifact: opendance-web-v0.2.1.tar.gz + artifact: opendance-web-v0.2.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 9b312fc..b46a727 100755 --- a/scripts/package-release.sh +++ b/scripts/package-release.sh @@ -1,12 +1,13 @@ #!/bin/bash # ============================================================ -# 打包发布产物：opendance-web-v0.2.1.tar.gz +# 打包发布产物：opendance-web-v0.2.2.tar.gz # # 产物结构（Linux 业务服务部署，不使用 Docker、不部署反向代理）： # web-server/ NestJS 源码 + 构建产物 # admin/ React 管理端构建产物 # deploy/ install.sh / ctl.sh / uninstall.sh / .env.example -# env-lib.sh (.env 语法预检) / init-env.sh (.env 引导) +# env-lib.sh (.env 语法预检) / assimp-lib.sh (Assimp 定位安装) +# init-env.sh (.env 引导) # systemd|openrc|initd / proxy（反代说明文档，仅文档不部署） # contracts/ 当前版本契约快照 # THIRD_PARTY.md 开源项目声明 @@ -20,7 +21,7 @@ set -euo pipefail REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)" cd "$REPO_ROOT" -VERSION="${1:-0.2.1}" +VERSION="${1:-0.2.2}" NAME="opendance-web-v${VERSION}" OUT_DIR="$REPO_ROOT/dist-release" STAGE="$OUT_DIR/$NAME" @@ -132,6 +133,7 @@ for required in \ "opendance-web-v${VERSION}/web-server/dist/models/gltf-packer.js" \ "opendance-web-v${VERSION}/deploy/init-env.sh" \ "opendance-web-v${VERSION}/deploy/env-lib.sh" \ + "opendance-web-v${VERSION}/deploy/assimp-lib.sh" \ "opendance-web-v${VERSION}/deploy/proxy/README.md" \ "opendance-web-v${VERSION}/deploy/proxy/nginx.conf.example" \ "opendance-web-v${VERSION}/deploy/proxy/web.config.example" \ diff --git a/tasks/005-model-upload.md b/tasks/005-model-upload.md index ff54c30..7f0cdbe 100644 --- a/tasks/005-model-upload.md +++ b/tasks/005-model-upload.md @@ -160,7 +160,7 @@ node scripts/import-default-model.mjs --write-source-only --model-id 22 --dry-ru ```bash cd web-server -npx vitest run # 11 个文件 / 180 项通过 +npx vitest run # 12 个文件 / 193 项通过 npm run test:smoke # 冒烟 [4] 段落 ``` diff --git a/tasks/007-upload-review.md b/tasks/007-upload-review.md index 9473473..3c1fdc5 100644 --- a/tasks/007-upload-review.md +++ b/tasks/007-upload-review.md @@ -86,7 +86,7 @@ draft ──submit──▶ pending ──approve──▶ published ```bash cd web-server -npx vitest run # 11 个文件 / 180 项通过（含 admin-bone-filter 8 项、.env 预检 12 项） +npx vitest run # 12 个文件 / 193 项通过（含 admin-bone-filter 8 项、.env 预检 12 项、Assimp 13 项） npm run test:smoke ``` diff --git a/web-server/admin/package.json b/web-server/admin/package.json index ca7faf9..fa8d0ee 100644 --- a/web-server/admin/package.json +++ b/web-server/admin/package.json @@ -1,7 +1,7 @@ { "name": "opendance-admin", "private": true, - "version": "0.2.1", + "version": "0.2.2", "type": "module", "description": "OpenDance Studio 管理端（React + TypeScript + Vite）", "scripts": { diff --git a/web-server/admin/src/api/types.ts b/web-server/admin/src/api/types.ts index 62de3e1..23583e5 100644 --- a/web-server/admin/src/api/types.ts +++ b/web-server/admin/src/api/types.ts @@ -273,12 +273,21 @@ export interface HealthDatabase { migrationsPending?: number; } +export interface HealthAssimp { + available: boolean; + /** 解析到的 Assimp 可执行文件路径 */ + path?: string; + version?: string; + error?: string; +} + export interface Health { status: 'ok' | 'degraded'; uptimeSec: number; version: string; contractVersion: Record; database: HealthDatabase; + assimp?: HealthAssimp; } /* ------------------------------------------------------------ 错误响应 */ diff --git a/web-server/admin/src/pages/Dashboard.tsx b/web-server/admin/src/pages/Dashboard.tsx index 825fc5d..3bcd11b 100644 --- a/web-server/admin/src/pages/Dashboard.tsx +++ b/web-server/admin/src/pages/Dashboard.tsx @@ -196,10 +196,28 @@ export function DashboardPage() { 迁移待执行 {healthValue.database?.migrationsPending ?? 0} +
+ assimp + + {healthValue.assimp?.available + ? (healthValue.assimp.version ?? 'available') + : '未安装'} + +
) : ( )} + {health.ok && healthValue && !healthValue.assimp?.available ? ( +
+ Assimp 不可用 + + 上传 .pmx / .fbx 模型（或含 PMX/FBX 的压缩包）会转换失败；FBX / glTF 动作预处理同样 + 需要它。在服务器上安装后无需重启服务：apt-get install -y assimp-utils + （RHEL 系为 dnf install -y assimp）。只上传 .glb / .vrm 则不受影响。 + +
+ ) : null} diff --git a/web-server/package.json b/web-server/package.json index d493765..e42b76a 100644 --- a/web-server/package.json +++ b/web-server/package.json @@ -1,6 +1,6 @@ { "name": "opendance-web-server", - "version": "0.2.1", + "version": "0.2.2", "description": "OpenDance Studio Web 管理服务端（NestJS + TypeORM + 现有 MySQL 实例）", "license": "MIT", "private": true, diff --git a/web-server/src/common/assimp.ts b/web-server/src/common/assimp.ts new file mode 100644 index 0000000..761569a --- /dev/null +++ b/web-server/src/common/assimp.ts @@ -0,0 +1,133 @@ +/** + * Assimp 可执行文件的定位、安装提示与可用性探测。 + * + * 背景：PMX / FBX 模型转换与 FBX / glTF 动作预处理都依赖**外部** Assimp + * 命令行工具（BSD-3-Clause，不在 Node 依赖里）。装漏了只有在用户上传完 + * 一整个压缩包之后才会暴露，而且原始报错只有 `spawn assimp ENOENT`。 + * 这里把「找二进制」与「怎么装」集中到一处，供转换管线、动作预处理、 + * /health 与部署自检共用。 + */ +import { execFile } from 'node:child_process'; +import { existsSync, statSync } from 'node:fs'; +import { delimiter, join } from 'node:path'; +import { promisify } from 'node:util'; + +const execFileAsync = promisify(execFile); + +/** + * 除 PATH 之外再查找的常见目录。 + * 生产上服务由系统服务托管，PATH 可能很窄（甚至只有 /usr/bin）， + * 而用户把 Assimp 装在 /usr/local/bin 也很常见。 + */ +export const ASSIMP_FALLBACK_DIRS = [ + '/usr/bin', + '/usr/local/bin', + '/usr/sbin', + '/usr/local/sbin', + '/snap/bin', +]; + +export interface AssimpLocation { + /** 解析到的可执行文件路径（未找到时原样返回传入的 bin） */ + path: string; + found: boolean; + /** 依次查找过的候选路径（用于错误信息） */ + searched: string[]; +} + +/** + * 定位 Assimp 可执行文件：显式路径 -> PATH -> 常见系统目录。 + * 只做文件系统检查，不执行它（探测可用性见 detectAssimpBin）。 + */ +export function resolveAssimpBinary(bin: string): AssimpLocation { + const candidates: string[] = []; + if (bin.includes('/') || bin.includes('\\')) { + candidates.push(bin); + } else { + for (const dir of (process.env.PATH ?? '').split(delimiter)) { + if (dir) candidates.push(join(dir, bin)); + } + for (const dir of ASSIMP_FALLBACK_DIRS) candidates.push(join(dir, bin)); + } + const searched = [...new Set(candidates)]; + for (const candidate of searched) { + try { + // 必须是文件：只判 existsSync 会把同名目录（例如 ASSIMP_BIN=/usr/bin）当成二进制 + if (existsSync(candidate) && statSync(candidate).isFile()) { + return { path: candidate, found: true, searched }; + } + } catch { + /* 权限等问题一律视为该候选不可用，继续找下一个 */ + } + } + return { path: bin, found: false, searched }; +} + +/** 各发行版的安装命令（部署脚本与错误信息共用同一份文案） */ +export const ASSIMP_INSTALL_COMMANDS: ReadonlyArray<{ distro: string; command: string }> = [ + { distro: 'Debian / Ubuntu', command: 'apt-get update && apt-get install -y assimp-utils libassimp6' }, + { distro: 'RHEL / CentOS / Rocky / Fedora', command: 'dnf install -y assimp' }, + { distro: 'Alpine', command: 'apk add --no-cache assimp' }, + { distro: 'Arch', command: 'pacman -S --noconfirm assimp' }, +]; + +export function assimpInstallHint(indent = ' '): string { + return ASSIMP_INSTALL_COMMANDS.map((item) => `${indent}${item.distro}: ${item.command}`).join('\n'); +} + +/** 找不到 Assimp 时的完整可读错误（含查过的路径、安装命令与替代办法） */ +export function assimpMissingMessage(bin: string, searched: string[] = []): string { + const tried = + searched.length > 0 + ? `\n已查找 ${searched.length} 处: ${searched.slice(0, 5).join(', ')}${searched.length > 5 ? ' ...' : ''}` + : ''; + return ( + `未找到 Assimp 可执行文件 "${bin}"。PMX / FBX 模型转换与 FBX / glTF 动作预处理都需要它` + + '(外部命令行工具, 不在 Node 依赖内)。' + + tried + + '\n安装方式:\n' + + assimpInstallHint() + + '\n装好后可用 `assimp version` 验证; 若它不在服务进程的 PATH 里, ' + + '请在 deploy/.env 中把 ASSIMP_BIN 设为绝对路径并重启服务。' + + '\n只上传 .glb / .vrm 模型(或 .bvh / .vmd / 关键点 JSON 动作)则不需要 Assimp。' + ); +} + +export interface AssimpProbe { + available: boolean; + /** 解析到的路径（未找到时为原值） */ + path: string; + version?: string; + error?: string; + searched: string[]; +} + +/** + * 探测 Assimp 是否真的可用（执行 `assimp version`）。 + * 用于 /health、部署自检，以及转换前的预检。 + */ +export async function detectAssimpBin(bin: string): Promise { + const location = resolveAssimpBinary(bin); + if (!location.found) { + return { + available: false, + path: location.path, + error: `未安装 (${bin})`, + searched: location.searched, + }; + } + try { + const { stdout } = await execFileAsync(location.path, ['version'], { timeout: 10_000 }); + const version = + stdout.split(/\r?\n/).find((line) => line.toLowerCase().includes('assimp')) ?? stdout.trim(); + return { available: true, path: location.path, version: version.trim(), searched: location.searched }; + } catch (error) { + const err = error as NodeJS.ErrnoException; + return { + available: false, + path: location.path, + error: err.code === 'ENOENT' ? `未安装 (${bin})` : (err.message ?? '未知错误'), + searched: location.searched, + }; + } +} diff --git a/web-server/src/health/health.controller.ts b/web-server/src/health/health.controller.ts index 892da0b..8c27375 100644 --- a/web-server/src/health/health.controller.ts +++ b/web-server/src/health/health.controller.ts @@ -24,6 +24,8 @@ export interface HealthReport { }; assimp: { available: boolean; + /** 解析到的 Assimp 可执行文件路径（未找到时为配置值） */ + path?: string; version?: string; error?: string; }; diff --git a/web-server/src/models/model-convert.ts b/web-server/src/models/model-convert.ts index 20af7f0..45fcb87 100644 --- a/web-server/src/models/model-convert.ts +++ b/web-server/src/models/model-convert.ts @@ -7,6 +7,7 @@ import { promisify } from 'node:util'; import { ModelFormat } from '../common/enums'; import { ZipEntry, readZipEntries } from '../common/zip-reader'; import { embedGlbImages } from './glb-textures'; +import { assimpMissingMessage, resolveAssimpBinary } from '../common/assimp'; import { packGltfToGlb } from './gltf-packer'; import { VrmWrapMeta, detectGlbKind, wrapGlbAsVrm } from './vrm-writer'; @@ -250,6 +251,13 @@ async function runAssimpPipeline( ): Promise<{ buffer: Buffer; format: ModelFormat; note: string; attempts: string[] }> { const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS; const prefer = options.preferFormat ?? 'glb'; + + // 预检：Assimp 缺失时直接给出「怎么装 + 查过哪些路径」，而不是两条 spawn ENOENT。 + // 只做文件系统检查（不执行），避免给假二进制（测试桩）增加额外要求。 + const location = resolveAssimpBinary(options.assimpBin); + if (!location.found) { + throw new Error(`模型转换失败：${assimpMissingMessage(options.assimpBin, location.searched)}`); + } { const workDir = dirname(modelPath); const attempts: string[] = []; diff --git a/web-server/src/preprocess/assimp.ts b/web-server/src/preprocess/assimp.ts index dbef9f5..54b672c 100644 --- a/web-server/src/preprocess/assimp.ts +++ b/web-server/src/preprocess/assimp.ts @@ -4,6 +4,8 @@ import { existsSync } from 'node:fs'; import { basename, extname, join } from 'node:path'; import { promisify } from 'node:util'; +import { assimpMissingMessage, resolveAssimpBinary } from '../common/assimp'; + const execFileAsync = promisify(execFile); export const ASSIMP_CONVERT_TIMEOUT_MS = 120_000; @@ -31,10 +33,8 @@ export async function convertToBvhWithAssimp( } catch (error) { const err = error as NodeJS.ErrnoException & { stderr?: string }; if (err.code === 'ENOENT') { - throw new BadRequestException( - `未找到 Assimp 可执行文件「${assimpBin}」。FBX / glTF 动作预处理需要 Assimp（BSD-3-Clause），` + - '请安装后设置 ASSIMP_BIN 环境变量；BVH 动作无需 Assimp。', - ); + const location = resolveAssimpBinary(assimpBin); + throw new BadRequestException(assimpMissingMessage(assimpBin, location.searched)); } const detail = (err.stderr ?? err.message ?? '').toString().trim().slice(0, 500); throw new BadRequestException(`Assimp 转换失败：${detail || '未知错误'}`); @@ -47,16 +47,4 @@ export async function convertToBvhWithAssimp( } /** 探测 Assimp 是否可用（用于 /health 与部署自检） */ -export async function detectAssimp(assimpBin: string): Promise<{ available: boolean; version?: string; error?: string }> { - try { - const { stdout } = await execFileAsync(assimpBin, ['version'], { timeout: 10_000 }); - const version = stdout.split(/\r?\n/).find((line) => line.toLowerCase().includes('assimp')) ?? stdout.trim(); - return { available: true, version: version.trim() }; - } catch (error) { - const err = error as NodeJS.ErrnoException; - return { - available: false, - error: err.code === 'ENOENT' ? `未安装（${assimpBin}）` : (err.message ?? '未知错误'), - }; - } -} +export { detectAssimpBin as detectAssimp } from '../common/assimp'; diff --git a/web-server/test/assimp-locate.spec.ts b/web-server/test/assimp-locate.spec.ts new file mode 100644 index 0000000..21db78f --- /dev/null +++ b/web-server/test/assimp-locate.spec.ts @@ -0,0 +1,200 @@ +import { spawnSync } from 'node:child_process'; +import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join, resolve } from 'node:path'; +import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest'; + +import { + ASSIMP_FALLBACK_DIRS, + assimpInstallHint, + assimpMissingMessage, + detectAssimpBin, + resolveAssimpBinary, +} from '../src/common/assimp'; +import { convertModelFile } from '../src/models/model-convert'; + +/** + * Assimp 缺失时的可诊断性。 + * + * 背景（真实故障）：服务器没装 Assimp，上传 PMX 压缩包只得到 + * GLB 直出：导出失败（ENOENT）：spawn assimp ENOENT + * glTF 直出：导出失败（ENOENT）：spawn assimp ENOENT + * 用户看不出「缺什么、怎么装」。现在： + * * 转换前先定位二进制，找不到就一次性给出安装命令与查过的路径； + * * 定位逻辑覆盖 PATH 之外的常见目录（服务由 systemd 托管时 PATH 可能很窄）。 + */ + +let workRoot = ''; +let fakeBin = ''; + +function findDeployLib(): string { + const candidates = [ + resolve(process.cwd(), '..', 'deploy', 'assimp-lib.sh'), + resolve(process.cwd(), 'deploy', 'assimp-lib.sh'), + resolve(process.cwd(), '..', '..', 'deploy', 'assimp-lib.sh'), + ]; + for (const candidate of candidates) { + if (existsSync(candidate)) return candidate; + } + throw new Error(`找不到 deploy/assimp-lib.sh，候选路径：\n${candidates.join('\n')}`); +} + +const ASSIMP_LIB = findDeployLib(); + +/** 写一个最小的假 assimp：只实现 `version` */ +function writeFakeAssimp(path: string, versionLine = 'Assimp version 6.0.4'): string { + mkdirSync(join(path, '..'), { recursive: true }); + writeFileSync(path, `#!/bin/bash\n[ "\${1:-}" = "version" ] && echo "${versionLine}"\nexit 0\n`); + chmodSync(path, 0o755); + return path; +} + +beforeAll(() => { + workRoot = mkdtempSync(join(tmpdir(), 'opendance-assimp-test-')); + fakeBin = writeFakeAssimp(join(workRoot, 'bin', 'assimp')); +}); + +afterAll(() => { + rmSync(workRoot, { recursive: true, force: true }); +}); + +const savedPath = process.env.PATH; +afterEach(() => { + process.env.PATH = savedPath; +}); + +describe('Assimp 定位（resolveAssimpBinary）', () => { + it('能在 PATH 中找到可执行文件', () => { + process.env.PATH = `${join(workRoot, 'bin')}:/usr/bin:/bin`; + const result = resolveAssimpBinary('assimp'); + expect(result.found).toBe(true); + expect(result.path).toBe(fakeBin); + }); + + it('显式绝对路径优先，不存在时 found=false 并给出查找记录', () => { + const missing = join(workRoot, 'no-such-assimp'); + const result = resolveAssimpBinary(missing); + expect(result.found).toBe(false); + expect(result.searched).toContain(missing); + + const present = resolveAssimpBinary(fakeBin); + expect(present.found).toBe(true); + expect(present.path).toBe(fakeBin); + }); + + it('PATH 里没有时仍会查常见系统目录（systemd 服务 PATH 可能很窄）', () => { + process.env.PATH = '/nonexistent-dir-only'; + const result = resolveAssimpBinary('assimp'); + // 结果取决于本机是否装了真实 assimp：两种都必须把常见目录查过 + for (const dir of ASSIMP_FALLBACK_DIRS) { + expect(result.searched).toContain(join(dir, 'assimp')); + } + if (!result.found) expect(result.path).toBe('assimp'); + }); +}); + +describe('Assimp 缺失时的错误信息', () => { + it('包含二进制名、各发行版安装命令、替代办法与查过的路径', () => { + const message = assimpMissingMessage('assimp', ['/usr/bin/assimp', '/usr/local/bin/assimp']); + expect(message).toContain('assimp'); + expect(message).toContain('apt-get install -y assimp-utils'); + expect(message).toContain('dnf install -y assimp'); + expect(message).toContain('/usr/bin/assimp'); + expect(message).toContain('ASSIMP_BIN'); + expect(message).toContain('.glb / .vrm'); + }); + + it('安装提示各发行版一条命令', () => { + const hint = assimpInstallHint(); + for (const distro of ['Debian / Ubuntu', 'Alpine', 'Arch']) { + expect(hint).toContain(distro); + } + }); +}); + +describe('Assimp 可用性探测（detectAssimpBin）', () => { + it('能执行时返回版本与路径', async () => { + const probe = await detectAssimpBin(fakeBin); + expect(probe.available).toBe(true); + expect(probe.path).toBe(fakeBin); + expect(probe.version).toContain('6.0.4'); + }); + + it('找不到时 available=false 且 error 说明未安装', async () => { + const probe = await detectAssimpBin(join(workRoot, 'no-such-assimp')); + expect(probe.available).toBe(false); + expect(probe.error).toContain('未安装'); + expect(probe.searched.length).toBeGreaterThan(0); + }); +}); + +describe('转换管线：Assimp 缺失时快速失败并给出可操作信息', () => { + it('convertModelFile 抛出的错误包含安装命令，且不再出现两次 spawn ENOENT', async () => { + let message = ''; + try { + await convertModelFile(Buffer.from('PMX dummy'), 'Hatsune Miku.pmx', { + assimpBin: join(workRoot, 'no-such-assimp'), + timeoutMs: 5_000, + }); + throw new Error('应当抛出异常'); + } catch (error) { + message = error instanceof Error ? error.message : String(error); + } + expect(message).toContain('模型转换失败'); + expect(message).toContain('apt-get install -y assimp-utils'); + expect(message).toContain('ASSIMP_BIN'); + expect(message).not.toContain('ENOENT'); + }); +}); + +describe('deploy/assimp-lib.sh：部署脚本共用的安装逻辑', () => { + function runLib(script: string, path?: string) { + // 覆盖 PATH 的用例里必须用绝对路径调 bash，否则连 bash 都找不到 + return spawnSync('/bin/bash', ['-c', `. "$1"; ${script}`, '_', ASSIMP_LIB], { + encoding: 'utf8', + timeout: 15000, + env: { ...process.env, ...(path ? { PATH: path } : {}) }, + }); + } + + it('opendance_assimp_resolve 能在 PATH 中找到二进制', () => { + const result = runLib('opendance_assimp_resolve', `${join(workRoot, 'bin')}:/usr/bin:/bin`); + expect(result.stdout.trim()).toBe(fakeBin); + expect(result.status).toBe(0); + }); + + it('opendance_assimp_resolve 在找不到时返回非 0 且无输出', () => { + const result = runLib('opendance_assimp_resolve || echo MISSING', '/nonexistent-dir-only'); + // 本机若真的装了 assimp（/usr/bin），则跳过这条断言的严格性 + if (!existsSync('/usr/bin/assimp') && !existsSync('/usr/local/bin/assimp')) { + expect(result.stdout.trim()).toBe('MISSING'); + } + expect(result.status).toBe(0); + }); + + it('opendance_assimp_install_cmd 按包管理器给出对应命令', () => { + const aptDir = join(workRoot, 'apt'); + mkdirSync(aptDir, { recursive: true }); + writeFileSync(join(aptDir, 'apt-get'), '#!/bin/bash\nexit 0\n'); + chmodSync(join(aptDir, 'apt-get'), 0o755); + const result = runLib('opendance_assimp_install_cmd', `${aptDir}:/usr/bin:/bin`); + expect(result.stdout).toContain('apt-get install -y assimp-utils libassimp6'); + }); + + it('opendance_assimp_install 调用包管理器安装 assimp-utils（离线失败也不抛）', () => { + const aptDir = join(workRoot, 'apt'); + const log = join(aptDir, 'calls.log'); + rmSync(log, { force: true }); + writeFileSync(join(aptDir, 'apt-get'), `#!/bin/bash\necho "apt-get $*" >> "${log}"\nexit 0\n`); + chmodSync(join(aptDir, 'apt-get'), 0o755); + const result = runLib('opendance_assimp_install', `${aptDir}:/usr/bin:/bin`); + expect(result.status).toBe(0); + const calls = existsSync(log) ? readFileSync(log, 'utf8') : ''; + expect(calls).toContain('apt-get install -y -qq assimp-utils libassimp6'); + }); + + it('非常规目录需要写 ASSIMP_BIN，标准目录不需要', () => { + expect(runLib(`opendance_assimp_needs_env_path ${join(workRoot, 'bin', 'assimp')} && echo YES`).stdout).toContain('YES'); + expect(runLib('opendance_assimp_needs_env_path /usr/bin/assimp || echo NO').stdout).toContain('NO'); + }); +}); diff --git a/web-server/test/model-archive.spec.ts b/web-server/test/model-archive.spec.ts index 279157b..713122f 100644 --- a/web-server/test/model-archive.spec.ts +++ b/web-server/test/model-archive.spec.ts @@ -423,13 +423,18 @@ describe('压缩包导入与转换（用假 Assimp 做对照）', () => { ); }); - it('assimp 不存在时给出可读错误', async () => { + it('assimp 不存在时给出可读错误（含安装命令与替代办法，而不是 spawn ENOENT）', async () => { + const promise = convertModelArchive(pmxArchive(), { + assimpBin: join(workRoot, 'no-such-assimp'), + timeoutMs: 5_000, + }); + await expect(promise).rejects.toThrow(/模型转换失败/); await expect( convertModelArchive(pmxArchive(), { assimpBin: join(workRoot, 'no-such-assimp'), timeoutMs: 5_000, }), - ).rejects.toThrow(/模型转换失败/); + ).rejects.toThrow(/apt-get install -y assimp-utils[\s\S]*\.glb \/ \.vrm/); }); });