zijunchiang/opendance-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity
54 Commits 2 Branches 17 Tags
eebccd55b4da5da199e65e0632d5b402b98d93c0
Commit Graph
14 Commits
Author SHA1 Message Date
opendance da03777995 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、环境变量说明）。
 2026-09-16 02:55:32 +08:00
opendance ea58520fc2 fix(deploy): .env 中带空格的值未加引号导致 install.sh 以 127 失败 
现象：
  ./deploy/.env: line 53: Miku.pmx: command not found
  [install] 第 53 行执行失败（退出码 127）

根因：deploy/.env.example 的 MODEL_CONVERT_PMX=Hatsune Miku.pmx 值含空格
却没加引号，install.sh 用 `set -a; . deploy/.env` 载入时被切成
「赋值 + 命令」，Miku.pmx 被当成命令执行。

修复：
1. 模板改为 MODEL_CONVERT_PMX="Hatsune Miku.pmx"（占位符值同样加引号）；
2. 新增 deploy/env-lib.sh：.env 语法预检，install.sh / ctl.sh 在 source
   之前检查，报错给出「哪一行 / 原文 / 改法」， 与反引号建议单引号；
3. install.sh 的 ERR trap 补上出错文件名（lineno 属于被 source 的 .env，
   只报行号无法定位）；
4. 新增 test/env-file.spec.ts 12 项回归测试，锁住「模板可被 shell 原样载入」；
5. 版本升到 0.2.1，README(.md/.txt)/DSH.md 补 .env 写法约定、FAQ 与测试数量。
 2026-09-15 22:26:58 +08:00
zijunchiang e4351c5062 feat(models): 模型压缩包自动转换 + 默认模型写进源码；首次启动 .env 引导；HOST 默认 0.0.0.0 
需求 1：模型上传支持压缩包（MMD 模型包）
- common/zip-reader.ts：纯 TS 极简 ZIP 读取器（EOCD/中央目录、STORE+DEFLATE、
  ZIP64 大小字段、Shift-JIS/GBK 文件名回退、拒绝 zip-slip 与加密条目）
- models/model-convert.ts：解压 → 选主模型（指名字/最浅/最大）→ Assimp 导出 FBX
  → **assimp info 回读校验**（Assimp 对带蒙皮大骨架模型会写出损坏文件：
  实测 714 骨骼 PMX 导出退出码 11、产物回读报 FBX-DOM no Objects dictionary found）
  → 失败自动回退 GLB；两种都失败则 422
- models/glb-textures.ts：把 Assimp 写成外部 URI 的贴图内嵌进 GLB 的 BIN chunk，
  保证模型库里单文件即可加载（否则是白模）
- 溯源：压缩包原件存为 model-archive 资产；models 新增 source_asset_id /
  conversion_note（迁移 1789450000000-AddModelConversionFields，已在真实库上
  验证 up/down 可逆）
- 默认模型：转换成功且 autoDefault 不为 false → is_primary=1 + published，
  并把身份（名称/格式/产物 sha256）写进源码 src/config/default-model.ts；
  resolveDefaultModelId 增加 DEFAULT_MODEL_ID 与源码种子两步（按 sha256 匹配，
  换库仍有效），实测库中有 2 个 VRM 时默认模型仍解析为该 GLB
- scripts/import-default-model.mjs：运维 CLI（上传 zip 并写源码 / --write-source-only）
- 修复 multipart 中文文件名乱码（upload.util.decodeUploadName）
- DTO/契约新增 conversionNote、fileSha256；管理端 accept 增加 .zip 并展示转换来源

需求 2：首次启动 .env 引导
- deploy/init-env.sh：交互式逐项填写 8 个键（回车保留默认、口令不回显不加引号、
  端口校验、mysql2 连通性自检且口令只经环境变量传递、只改这 8 个键并保留模板注释、
  chmod 600、结尾打码摘要）；--force/--check/-y/-i/--skip-db-check 等开关；
  非交互（-y、OPENDANCE_NONINTERACTIVE、stdin 关闭）绝不提问、读取带超时
- install.sh 缺 .env 时改为调用引导，失败才 die

需求 3：默认监听 0.0.0.0
- 代码默认值、两份 .env 模板、install.sh、init-env.sh 五处一致，并新增测试守护
  （未设置 HOST 时为 0.0.0.0；两份模板都写着 HOST=0.0.0.0）

契约：rest-api / data-models / model-formats → 0.3.0，database → 0.2.0（另两库已同步）

验证：125 项单测通过（7 文件）；契约 6 项与 29 条路由一致；typecheck/build 通过；
真实包端到端 HTTP 201 / 0.89s / format=glb / isPrimary=true / published；
GLB 1,152,464 字节、1 mesh / 240 nodes / 1 skin(238 joints) / 2 张内嵌贴图；
迁移 revert→run 实测可逆且数据无损恢复
 2026-09-15 13:55:54 +08:00
zijunchiang bba5bcf59e feat(web): 端口分离 + VMD 动作支持；契约升至 0.2.0 
需求 1：管理端端口与软件 API 端口分离
- 软件 API 端口 PORT（默认 3000）只提供 /api、/health、/static、/contracts，
  不提供管理页面（未命中路径 404）；管理端端口 ADMIN_PORT（默认 3001）
  提供管理页面与全部接口；ADMIN_HOST 可单独限制管理端来源
- main.ts 同进程监听两个端口，用 req.socket.localPort 区分端口行为；
  ADMIN_PORT=PORT 为单端口兼容模式（只创建一个 server，无 EADDRINUSE）
- 端口非法在生产环境中止启动；ADMIN_PORT=PORT 只 warn
- 启动日志分别打印两个端口的访问地址

需求 2：动作数据支持 VMD（MikuMikuDance）
- vmd-parser.ts：二进制解析（30 字节头 + Shift-JIS 模型名 + 111 字节/条骨骼
  关键帧 + morph 段）、MMD 贝塞尔插值、GBK 模型名回退、固定 30fps
- mmd-skeleton.ts：标准 MMD 骨架；静止比例从参考 PMX 骨骼段实测得到
  （足首 1.43 / 膝 6.57 / 髋 11.50 / 首 16.21 / 頭 17.16，腿长 10.09）
- mmd-pose.ts：FK + 两骨骼解析腿部 IK（膝盖朝正面，不可达收敛为伸直）
  + 左手系→右手系 Z 镜像（由真实数据对照实验确定：94.1% vs 5.9%）
- retarget.ts：抽出 worldFramesToKeypointFrames()，BVH 与 VMD 共用重定向
- MotionFormat 增 vmd、扩展名映射增 .vmd；管理端上传支持 .vmd
- scripts/inspect-vmd.mjs：上传前自查工具

契约：rest-api / data-models / model-formats → 0.2.0（另两库已同步逐字节一致）

验证：85 项单测通过（VMD 31 项）；契约与 29 条路由一致；typecheck/build 通过；
真实样本经 HTTP 端到端：霜雪千年 2901 帧（IK 腿）、恋爱循环 4604 帧（FK 腿）
均 preprocessState=done、0 NaN、0 越界（测试数据已从数据库清理）。
 2026-09-15 08:47:37 +08:00
zijunchiang 44451028dd fix(deploy): 安装脚本按真实 HOST 报告监听地址，并主动提示外部不可达 
背景：旧版 .env.example 的 HOST=127.0.0.1 会让服务只监听回环，
本机 curl 一切正常、安装日志毫无异常，但外部永远连不上。

install.sh 修复：
- 不再写死 API_HOST=127.0.0.1：从 deploy/.env 读 HOST 得到 BIND_HOST，
  绑定具体网卡时用该地址做健康检查（原来用回环会误判启动失败）
- 汇总输出改为真实监听地址 + 按三种绑定模式给出正确 URL
  （回环写 127.0.0.1、具体网卡写该地址、通配写探测到的对外 IP）
- 新增安装期外部可达性自测：用对外 IP 请求 /health，
  只监听回环 → 打印改 HOST 与重启命令；
  监听正常但自测失败 → 打印防火墙 / 云安全组放行步骤
- 反代提示里回显当前 HOST 实际值，避免照抄"建议 127.0.0.1"改坏配置

README.txt 同步说明。验证：用真实脚本片段 + 打桩跑四种场景
（回环 / 通配可达 / 通配被防火墙拦 / 指定网卡），输出逐一核对。
 2026-09-15 01:48:04 +08:00
zijunchiang 8c76b0a599 feat(web): 移除 Docker 与反代部署，改为 Linux 业务服务并自带管理端托管 
需求变更：Web 端只保留业务需求，反向代理交由另外的服务处理，
本项目仅提供 IIS / nginx 反代说明文档，不部署反代。

主要改动：
- web-server: 新增管理端静态托管（ADMIN_DIR、SPA 深链接回退），
  反代因此只需一条全匹配转发规则；新增 adminDir 配置项
- deploy/install.sh: 删除 nginx 安装与站点配置逻辑，改为原生 Linux
  服务部署（systemd → OpenRC → SysVinit → 后台进程四级降级），
  打印反代交接指引
- deploy/ctl.sh: 启停/状态/日志脚本
- deploy/proxy/: 新增反代说明文档（README.md、nginx.conf.example、
  web.config.example），标注上传上限与超时必须同步调整
- 删除 deploy/nginx/、web-server/admin/nginx.conf、Dockerfile、
  docker-compose.yml、.dockerignore
- scripts/package-release.sh: 锚定排除规则 + 产物完整性校验
- 文档同步：README.txt、DSH.md、project.yaml、tasks/008、tasks/010
 2026-09-15 01:25:19 +08:00
zijunchiang 653d9d168c feat(deploy): 缺少 deploy/.env 时复用安装目录中的历史配置 
用户在重新解压发布包后再次执行 install.sh，因缺少 deploy/.env 被拦下。
按文档流程每次升级都要重新解压，若每次都要求重填数据库口令，既繁琐
又容易出错（口令含 * 等特殊字符）。

- 优先使用当前目录的 deploy/.env
- 其次复用 $APP_DIR/deploy/.env（上次安装留下的配置）
- 两处都没有才报错，且错误信息列出需要填写的五个字段及注意事项

实测三种情形：
  全新安装（两处都无）→ 报错并给出字段说明，退出码 1
  安装目录有历史配置   → 自动复用，退出码 0
  当前目录已有 .env    → 直接使用，不覆盖
 2026-09-15 01:03:20 +08:00
zijunchiang 87a1ded2d2 fix(deploy): install.sh 复制时同样误排除了 storage 目录 
用户重装后仍报同一错误，且日志显示「复制 web-server … 174 个文件」。
经复现：发布包内 web-server 有 180 个文件（含 src/storage 2 个、
dist/storage 4 个），但 install.sh 复制后只剩 174 个——storage 被剔除了。

根因：上一轮只修了 package-release.sh，install.sh 里**还有一份独立的
copy_tree() 排除规则**，其中 'storage' 同样未锚定。install.sh 的
COPY_EXCLUDES 与 tar 回退分支都把 'storage' 当作任意层级模式，
于是 src/storage 与 dist/storage 在复制进 /opt/opendance 时被剔除。

这是同一类错误在本项目的第三次（.gitignore → package-release.sh →
install.sh）。因此这次不再只改模式，而是把语义显式化并加硬校验：

- 排除规则拆成三类常量，语义明确：
    TOP_DIRS  仅顶层：storage data tmp dist-release   → 必须锚定
    ANY_DIRS  任意层级：node_modules .git coverage .gradle
    TOP_FILES 仅顶层文件：.env .env.local
- rsync 用前导 '/' 锚定；tar 对 TOP_* 只给 './x'（绝不给 '*/storage'），
  对 ANY_* 才给 './x' + '*/x'
- 复制后硬校验关键产物（dist/main.js、dist/storage/storage.module.js、
  dist/app.module.js、admin/index.html），缺失即 die 并指出是排除规则问题

实测：
- rsync 路径：180 文件，src/storage 与 dist/storage 均在，
  运行时 storage 与 .env 未带入，.env.example 保留
- tar 回退路径（隔离 PATH 屏蔽 rsync 后真跑）：同样 180 文件，存储目录完整
- git 检出布局：214 文件，嵌套 admin/node_modules 未带入，本地 .env 未带入
- 对照实验：把锚定改回未锚定 → 复制剩 174 文件 → 守卫立刻报
  「缺少关键文件 dist/storage/storage.module.js」并终止，不再拖到启动才炸
 2026-09-15 01:00:58 +08:00
zijunchiang f6fe9af0a2 fix(deploy): 修复 NODE_ENV 污染导致管理端构建失败（tsc: not found） 
用户实测：部署时构建管理端报 `sh: 1: tsc: not found`，且 npm 只装了 23 个包。

根因：脚本开头用 `set -a; . deploy/.env; set +a` 载入 .env，其中的
NODE_ENV=production 被导出到脚本自身环境；npm 见到它便会跳过
devDependencies，于是 typescript / vite / nest 等构建工具全部缺失。
本地实测完全复现：
  NODE_ENV=production npm ci          → added 23 package，无 tsc
  env -u NODE_ENV npm ci --include=dev → added 53 package，tsc/vite 齐备

修复：
- 新增 npm_install_with_dev()：统一用 `env -u NODE_ENV npm ... --include=dev`
- 管理端构建改用它；**API 构建回退路径存在同一隐患，一并修复**
- 管理端改为在 $APP_DIR/web-server/admin 内构建（不再污染源码树、
  也不要求源码目录可写），构建完删除该处 node_modules 释放磁盘
- 构建失败时给出可操作提示（改用发布包）

另修复一处静默的信息泄露：
- 复制源码树时未排除 .env，本地开发用的 web-server/.env（含真实数据库
  口令）会被复制进 /opt/opendance/web-server/.env；deploy/.env 才是权威配置，
  多一个 dotenv 配置源只会造成排障困惑。已把 .env / .env.local 加入排除，
  并验证 .env.example 不受影响（209 → 208 个文件）

实测：
  旧行为 tsc 缺失、构建报 tsc: not found（与用户报错一致）
  新行为 tsc/vite 齐备，vite build 成功产出 dist/index.html + 3 个 assets
  复制排除：.env 不复制、.env.example 保留、node_modules 无泄漏
 2026-09-15 00:44:54 +08:00
zijunchiang c092b833fb fix(deploy): 支持无 systemd 的环境，并修复降级路径的两个真实缺陷 
用户实测：服务器没有 systemctl，install.sh 直接报错退出。

原错误信息本身也是错的（建议 SKIP_NGINX=1，但那只跳过 nginx，仍走 systemctl）。

进程管理改为四层降级：
  systemd → OpenRC → SysVinit → nohup 后台进程（deploy/ctl.sh）
- 新增 deploy/ctl.sh：start/stop/restart/status/logs，PID 文件 + 进程名双重判定
- 新增 deploy/openrc/opendance-api、deploy/initd/opendance-api
- 无 init 系统时写 crontab @reboot 实现开机自启
- uninstall.sh 同步支持四种模式清理（原先只处理 systemd，会留下运行中的进程）
- 汇总输出按实际初始化系统给出对应运维命令

测试中发现并修复降级路径的两个真实缺陷：

1. nohup 无法调用 shell 函数
    实测退出码 127 且什么都不执行
   （nohup 是外部命令，只能执行可执行文件）。
   这会让无 systemd 的降级路径完全失效——服务根本起不来。
   改为按 runuser / setpriv / su 显式拼接成外部命令后再 nohup。
   另加启动后 1 秒存活检测，失败立即打印日志，不再白等 30 秒。

2. find_pids 在无进程时返回一个空格
    在空输入下仍会执行一次 echo，输出空行，
   最终得到 " "；调用方 [ -n ... ] 会判为「有进程」，
   导致 start 直接跳过、status 谎报运行中。改为纯 bash 拼接，空时返回空串。

实测（真实 API 进程，端口 3100）：
  start → 健康检查 200，PID 正确
  重复 start → 识别已在运行，进程数保持 1
  status → 运行中
  restart → 新 PID，健康检查 200
  stop → 无残留进程，端口释放
  无 process 时 find_pids 返回空串，is_running=false
 2026-09-15 00:34:52 +08:00
zijunchiang 1ffe3059af fix(deploy): install.sh 不再依赖 sudo 
用户实测报错：deploy/install.sh: line 173: sudo: command not found

本脚本已经强制要求 root 权限，用 sudo 降权到服务用户本就多余，
且部分服务器（尤其精简系统/容器）根本没有安装 sudo。

- 新增 as_service_user()：runuser → setpriv → su 依次回退，
  并在三者都不可用时给出明确错误
- 替换全部 sudo -u 调用（npm ci / npm install / npm run build / 迁移）
- 新增 http_get() / http_ok()：curl → wget → node fetch 依次回退，
  健康检查不再强依赖 curl
- 启动前检查 systemctl（本部署依赖 systemd），缺失时给出可操作提示
- 修正 install.sh / uninstall.sh 中所有「用 sudo 执行」的提示文案

实测（桩替换 runuser 验证分派与参数传递）：
  有 runuser：runuser -u opendance -- npm ci --omit=dev --loglevel=error
  仅 su：正确回退到 su
  HTTP：curl 路径与 node fetch 回退路径返回一致
 2026-09-15 00:27:27 +08:00
zijunchiang 7cd607ecde fix(deploy): 修复 install.sh 同步文件时的长时间卡死 
用户实测：执行到「同步程序文件到 /opt/opendance」后卡死。

根因：在源码检出目录执行时，web-server/ 下有 node_modules（236MB /
27359 个文件，admin 下还有 122MB），原实现用 cp -r 全量复制，
随后又对整个目录 chown -R，处理三万个文件表现为卡死。

修复：
- 复制改用 copy_tree()，排除 node_modules/.git/storage/dist-release 等
  运行期可再生目录；有 rsync 用 rsync -a --delete，否则用 tar 管道回退
- tar 回退的排除模式同时给出 './x' 与 '*/x'：只写 './x' 无法匹配嵌套的
  './admin/node_modules'（实测会漏掉 122MB，等于没修）
- 增加目录安全检查：安装目录与源目录相同、或二者互相包含时直接报错退出，
  避免 rm -rf 删掉源文件 / cp 无限递归
- 支持两种目录布局：发布包 admin/ 在根目录，源码检出在
  web-server/admin/dist（缺失则现场构建），此前从源码目录执行必然在
  「缺少 admin/ 目录」处失败
- 每个目录打印复制结果与文件数，npm 安装前给出预计耗时提示，
  不再有长时间无输出的「假卡死」
- 失败时 trap 打印行号

实测（用脚本中真实代码块驱动的用例）：
  源码检出目录 → /tmp：rsync 路径 1 秒 / 209 文件；tar 回退路径同样 209 文件
  发布包解压目录 → /tmp：0 秒，admin 与 dist/main.js 均正确
  同目录 / 嵌套目录两种危险布局：均被拒绝并给出可操作提示
  两条路径均无 node_modules 泄漏
 2026-09-15 00:14:06 +08:00
zijunchiang 75498db1c0 feat(web): 部署方式由 Docker 改为 Linux 原生站点（nginx + systemd） 
需求变更：Web 服务端不再使用 Docker，改为直接运行在 Linux 上的网站。

- 移除 deploy/docker-compose.yml、web-server/Dockerfile、
  web-server/admin/Dockerfile、web-server/.dockerignore
- 新增 deploy/install.sh：建服务用户与目录 → 装运行期依赖 → 迁移
  → 注册 systemd 服务 → 配置 nginx 站点 → 健康检查，一键完成
- 新增 deploy/systemd/opendance-api.service：ProtectSystem=strict 等
  安全加固，ReadWritePaths 限定为上传目录
- 新增 deploy/nginx/opendance.conf：同站点托管管理端静态资源 +
  反代 /api /health /static，client_max_body_size 512m，SPA 回退
- 新增 deploy/uninstall.sh：默认保留数据，--purge 才删除
- 新增配置项 HOST（AppConfig.bindHost）：原生部署下 Node 只监听
  127.0.0.1，不直接对外暴露，实测外部 IP 不可达
- 同步更新 contracts/rest-api.yaml、DSH.md、project.yaml、README.txt、
  tasks/008、tasks/010 与发布打包脚本
 2026-09-14 22:42:56 +08:00
zijunchiang 5a8b77b0a4 feat(web): T-WEB-010 部署脚本（Docker Compose，不含 MySQL） 2026-09-14 19:00:55 +08:00