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

feat(web): 端口分离 + VMD 动作支持；契约升至 0.2.0

Browse Source 
需求 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 越界（测试数据已从数据库清理）。
This commit is contained in:
zijunchiang
2026-09-15 08:47:37 +08:00
parent 76725e5ce3
commit bba5bcf59e
35 changed files with 2658 additions and 192 deletions
Download Patch File Download Diff File Expand all files Collapse all files
deploy/proxy/nginx.conf.example
+85 -20
View File
@@ -1,44 +1,57 @@
# ============================================================
# OpenDance Studio Web 服务端 —— nginx 反向代理样例
# OpenDance Studio Web 服务端 —— nginx 反向代理样例（双端口）
#
# 说明：本 Web 端不自带反向代理。本文件是**给你的反代服务参考**的配置样例，
# 由部署 `deploy/install.sh` 之外的反代负责人使用。
#
# 特点：后端（NestJS）自带管理端页面与 SPA 回退，因此这里
# 只需一个全匹配 location 把请求整体转发过去即可，
# 不需要 root/try_files 托管静态文件。
# 后端同时监听两个端口，职责不同：
# 软件 API 端口（PORT，默认 3000）—— Windows/Godot 客户端、Android App
# 只提供 /api、/health、/static、/contracts
# 管理端端口（ADMIN_PORT，默认 3001）—— 浏览器，提供管理页面 + 上面全部接口
#
# 两个端口都不需要在代理层托管静态文件、也不需要 SPA 回退（服务端已处理），
# 因此每个站点只要一条 `location /` 全匹配转发即可。
#
# 安装：
# Debian/Ubuntu: /etc/nginx/sites-available/opendance.conf（再软链到 sites-enabled/）
# RHEL 系: /etc/nginx/conf.d/opendance.conf
# 校验并重载： nginx -t && systemctl reload nginx
#
# 想省事只挂一个域名？把两段 server 合并成一段，让另一侧的客户端直连端口即可；
# 也可以在后端设 `ADMIN_PORT=PORT` 走单端口兼容模式（此时管理页面回到 API 端口）。
# ============================================================
upstream opendance_api {
# 后端地址：同机用 127.0.0.1；异机改成实际 IP，并在后端放防火墙
# 软件 API 端口。同机用 127.0.0.1；异机改成实际 IP，并在后端放防火墙
server 127.0.0.1:3000;
keepalive 16;
}
upstream opendance_admin {
# 管理端端口
server 127.0.0.1:3001;
keepalive 16;
}
# ------------------------------------------------------------
# 站点一：软件 API（给客户端调用）
# ------------------------------------------------------------
server {
listen 80;
listen [::]:80;
server_name your.domain.com; # 改成实际域名或 _
server_name dance-api.example.com; # 改成实际域名或 _
# 字符集：管理端与 API 都是 UTF-8
charset utf-8;
# ★ 上传上限：后端默认允许 512 MiB，nginx 默认仅 1 MB，
# 不改会导致 VRM / FBX 等大文件上传直接 413。
# 不改会导致 VRM / FBX / VMD 等大文件上传直接 413。
client_max_body_size 512m;
client_body_timeout 300s;
access_log /var/log/nginx/opendance.access.log;
error_log /var/log/nginx/opendance.error.log;
access_log /var/log/nginx/opendance-api.access.log;
error_log /var/log/nginx/opendance-api.error.log;
# ---- 全部请求转发给后端 ----
# 管理端页面、前端路由深链接、/api、/health、/static、/contracts
# 全部由后端处理，所以这里只需一条规则。
# ---- 全部请求转发给后端（/api、/health、/static、/contracts）----
location / {
proxy_pass http://opendance_api;
proxy_http_version 1.1;
@@ -72,14 +85,54 @@ server {
gzip_types text/plain text/css application/json application/javascript
application/x-ndjson text/xml application/xml image/svg+xml;
gzip_min_length 1024;
}
# 若前端资源由后端返回，代理层不要缓存 HTML，避免升级后页面不更新
location ~* \.html$ {
proxy_pass http://opendance_api;
# ------------------------------------------------------------
# 站点二：管理端（给浏览器）
#
# 建议只在内网 / VPN 内暴露，或至少加一层认证（见文件末尾）。
# 也可以把 server_name 写成内网域名，并在防火墙只放行内网来源。
# ------------------------------------------------------------
server {
listen 80;
listen [::]:80;
server_name dance-admin.example.com; # 改成实际域名或 _
charset utf-8;
# 管理端同样会上传模型 / 动作，上限保持一致
client_max_body_size 512m;
client_body_timeout 300s;
access_log /var/log/nginx/opendance-admin.access.log;
error_log /var/log/nginx/opendance-admin.error.log;
# ---- 管理页面 + 全部接口 ----
location / {
proxy_pass http://opendance_admin;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Connection "";
proxy_connect_timeout 30s;
proxy_send_timeout 300s;
proxy_read_timeout 300s;
proxy_request_buffering off;
proxy_buffering off;
# 代理层不要缓存 HTML，避免升级后页面不更新
add_header Cache-Control "no-cache";
}
gzip on;
gzip_types text/plain text/css application/json application/javascript
application/x-ndjson image/svg+xml;
gzip_min_length 1024;
}
# ============================================================
@@ -88,7 +141,7 @@ server {
# server {
# listen 443 ssl;
# http2 on;
# server_name your.domain.com;
# server_name dance-admin.example.com;
#
# ssl_certificate /etc/nginx/ssl/opendance.crt;
# ssl_certificate_key /etc/nginx/ssl/opendance.key;
@@ -97,7 +150,7 @@ server {
# client_max_body_size 512m;
#
# location / {
# proxy_pass http://opendance_api;
# proxy_pass http://opendance_admin;
# proxy_http_version 1.1;
# proxy_set_header Host $host;
# proxy_set_header X-Real-IP $remote_addr;
@@ -111,11 +164,23 @@ server {
# ============================================================
# ============================================================
# 可选：本服务未内置登录认证，如需公网访问请在反代加一层防护
# 可选：本服务未内置登录认证
#
# 管理端建议至少加一层 Basic Auth；软件 API 若不便加认证，
# 请用 IP 白名单把来源限制为客户端所在网段。
#
# 管理端：
# location / {
# auth_basic "OpenDance Studio";
# auth_basic_user_file /etc/nginx/.htpasswd; # htpasswd -c 生成
# proxy_pass http://opendance_admin;
# ...
# }
#
# 软件 API：
# location / {
# allow 192.168.150.0/24; # 客户端所在网段
# deny all;
# proxy_pass http://opendance_api;
# ...
# }