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 越界（测试数据已从数据库清理）。
This commit is contained in:
+39
-15
@@ -5,37 +5,54 @@
|
||||
>
|
||||
> 安装脚本 `deploy/install.sh` 不会安装或修改任何反代软件。
|
||||
|
||||
## 一、需要转发的目标
|
||||
## 一、需要转发的目标（两个端口，按用途分开）
|
||||
|
||||
本服务**自带管理端页面**，因此反向代理**只需把请求整体转发**到一个地址：
|
||||
本服务**同时监听两个端口**，职责不同：
|
||||
|
||||
| 端口 | 环境变量 | 默认 | 给谁用 | 提供什么 |
|
||||
|---|---|---|---|---|
|
||||
| 软件 API 端口 | `PORT` | `3000` | Windows/Godot 客户端、Android App | `/api`、`/health`、`/static`、`/contracts`；**不含管理页面**（未知路径 404） |
|
||||
| 管理端端口 | `ADMIN_PORT` | `3001` | 浏览器（管理员） | 管理页面 + 上面全部接口 |
|
||||
|
||||
```
|
||||
http://<后端地址>:3000
|
||||
软件 API： http://<后端地址>:3000
|
||||
管理端： http://<后端地址>:3001
|
||||
```
|
||||
|
||||
不需要在代理层单独托管静态文件，也不需要配置 SPA 回退（服务端已处理）。
|
||||
一个 `location /`（nginx）或一条全匹配规则（IIS）即可。
|
||||
两者都不需要在代理层托管静态文件，也不需要配置 SPA 回退（服务端已处理）；
|
||||
各用一条 `location /`（nginx）或全匹配规则（IIS）即可。
|
||||
|
||||
| 路径 | 内容 | 说明 |
|
||||
**推荐做法**：把两个端口挂在两个不同的站点/域名上，便于分别做访问控制，例如
|
||||
|
||||
- `https://dance-api.example.com` → 转发到 `3000`（给客户端，可用 IP 白名单）
|
||||
- `https://dance-admin.example.com` → 转发到 `3001`（给管理员，建议加 Basic Auth / SSO 或只在内网放行）
|
||||
|
||||
如果客户端与管理端在同一个内网、也不想配域名，可以**让客户端直连 `3000`**（不经过反代），
|
||||
只把管理端 `3001` 挂到反代上；反之亦可。
|
||||
|
||||
| 路径 | 内容 | 哪个端口提供 |
|
||||
|---|---|---|
|
||||
| `/` | 管理端页面 | 由 Node 服务提供；前端路由深链接（如 `/songs`）由服务端回退到 `index.html` |
|
||||
| `/assets/*` | 前端静态资源 | 带内容哈希，可长缓存 |
|
||||
| `/api/*` | REST API | 契约见 `contracts/rest-api.yaml` |
|
||||
| `/health` | 健康检查 | 可用作反代的存活探测，数据库不可用时返回 **503** |
|
||||
| `/static/*` | 上传文件 | 模型 / 音频 / 关键点序列 |
|
||||
| `/contracts/*` | 契约快照 | 只读，便于另两端查阅 |
|
||||
| `/`、`/assets/*` | 管理端页面与静态资源 | **仅管理端**；前端路由深链接（如 `/songs`）由服务端回退到 `index.html` |
|
||||
| `/api/*` | REST API | 两个端口都提供（契约见 `contracts/rest-api.yaml`） |
|
||||
| `/health` | 健康检查 | 两个端口都提供；可用作反代的存活探测，数据库不可用时返回 **503** |
|
||||
| `/static/*` | 上传文件 | 两个端口都提供（模型 / 音频 / 关键点序列） |
|
||||
| `/contracts/*` | 契约快照 | 两个端口都提供，只读 |
|
||||
|
||||
> Windows 客户端与 Android 之间的**关键点 WebSocket 链路不经过本服务**，
|
||||
> 反代无需配置 WebSocket 转发。
|
||||
>
|
||||
> `ADMIN_PORT` 设为与 `PORT` 相同时是**单端口兼容模式**：两个端口合一，
|
||||
> 管理页面重新出现在 API 端口上（此时反代只需要一条规则）。
|
||||
|
||||
## 二、后端绑定地址怎么选
|
||||
|
||||
`deploy/.env` 中的 `HOST`：
|
||||
`deploy/.env` 中的 `HOST`（软件 API 端口）与可选的 `ADMIN_HOST`（管理端端口，缺省跟随 `HOST`）：
|
||||
|
||||
| 部署形态 | 建议值 | 说明 |
|
||||
|---|---|---|
|
||||
| 反代与后端**同机** | `127.0.0.1` | 后端不直接对外暴露，最安全 |
|
||||
| 反代与后端**不同机** | `0.0.0.0` | 必须用防火墙把 3000 端口限制为仅反代来源可访问 |
|
||||
| 反代与后端**同机** | `HOST=127.0.0.1` | 后端不直接对外暴露，最安全 |
|
||||
| 反代与后端**不同机** | `HOST=0.0.0.0` | 必须用防火墙把端口限制为仅反代来源可访问 |
|
||||
| 只想让管理端在内网可见 | `ADMIN_HOST=<内网网卡地址>` | 与 `HOST=0.0.0.0` 组合使用，把管理端限制在内网 |
|
||||
|
||||
改完执行 `systemctl restart opendance-api`（或对应的 `ctl.sh restart`）生效。
|
||||
|
||||
@@ -154,8 +171,12 @@ IIS 管理器 → 选中服务器节点 → Application Request Routing Cache
|
||||
配置完成后逐项确认：
|
||||
|
||||
```bash
|
||||
# 0. 两个端口都在监听（双端口部署）
|
||||
ss -tlnp | grep -E ':(3000|3001)'
|
||||
|
||||
# 1. 后端自身可用（绕过反代）
|
||||
curl -i http://127.0.0.1:3000/health
|
||||
curl -i http://127.0.0.1:3001/health
|
||||
|
||||
# 2. 经反代可访问
|
||||
curl -i http://<反代地址>/health
|
||||
@@ -180,6 +201,9 @@ curl -i http://<反代地址>/api/catalog/version
|
||||
| 上传大文件 413 | 代理层上传上限没放开（见第三、四、五节） |
|
||||
| 上传中途断开 | 代理超时太短 |
|
||||
| `/songs` 直接访问 404 | SPA 回退被代理拦截；本服务已处理，代理**不要**自己加 `try_files`，全匹配转发即可 |
|
||||
| 客户端接口全 404 | 把客户端的转发规则指到了管理端口之外，或误把 `/api` 前缀重写掉；客户端应转发到软件 API 端口 |
|
||||
| 管理页面 404 | 把浏览器的转发规则指到了**软件 API 端口**（该端口不提供管理页面，这是有意设计）；改指 `ADMIN_PORT` |
|
||||
| 两个端口都转发到同一条规则 | 若确实想合并两个端口，设置 `ADMIN_PORT=PORT` 走单端口模式，而不是让反代去猜 |
|
||||
|
||||
## 八、还没有反代时：直连后端怎么访问
|
||||
|
||||
|
||||
@@ -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;
|
||||
# ...
|
||||
# }
|
||||
|
||||
@@ -16,7 +16,18 @@
|
||||
|
||||
放置位置：IIS 站点根目录下的 web.config
|
||||
|
||||
后端（NestJS）自带管理端页面与 SPA 回退，所以这里只需一条全匹配重写规则，
|
||||
后端（NestJS）同时监听两个端口，职责不同：
|
||||
|
||||
软件 API 端口（PORT，默认 3000）—— 给 Windows/Godot 客户端与 Android App
|
||||
只有 /api、/health、/static、/contracts
|
||||
管理端端口（ADMIN_PORT，默认 3001）—— 给浏览器
|
||||
管理页面 + 上面全部接口
|
||||
|
||||
**在 IIS 里建两个站点**，把下面这份 web.config 各放一份，只改 <action> 里的端口：
|
||||
站点 A（如 dance-api.example.com） → http://127.0.0.1:3000/{R:1}
|
||||
站点 B（如 dance-admin.example.com）→ http://127.0.0.1:3001/{R:1}
|
||||
|
||||
后端自带管理端页面与 SPA 回退，所以每个站点只需一条全匹配重写规则，
|
||||
不需要在 IIS 上再配置默认文档或 URL Rewrite 的 SPA 回退。
|
||||
============================================================
|
||||
-->
|
||||
@@ -25,7 +36,12 @@
|
||||
|
||||
<rewrite>
|
||||
<rules>
|
||||
<!-- 全部请求转发给后端：管理端页面 / 前端深链接 / api / health / static / contracts -->
|
||||
<!--
|
||||
全部请求转发给后端。
|
||||
管理端站点把端口改成 3001；软件 API 站点保持 3000。
|
||||
注意：软件 API 端口**不提供管理页面**，用浏览器访问它会得到 404，
|
||||
这是有意设计（职责分离），不是配置错误。
|
||||
-->
|
||||
<rule name="OpenDanceReverseProxy" stopProcessing="true">
|
||||
<match url="(.*)" />
|
||||
<action type="Rewrite" url="http://127.0.0.1:3000/{R:1}" />
|
||||
@@ -70,8 +86,12 @@
|
||||
</configuration>
|
||||
<!--
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ 两个最常踩的坑 │
|
||||
│ 三个最常踩的坑 │
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ 0. 两个端口搞混。浏览器要访问的是**管理端端口 3001**； │
|
||||
│ 客户端调用的是**软件 API 端口 3000**。指错会出现 │
|
||||
│ "管理页面 404" 或 "接口全 404"。 │
|
||||
│ │
|
||||
│ 1. 代理超时是**服务器级**配置，不在 web.config 里。 │
|
||||
│ ARR 默认 120 秒，上传大模型会中途断开。改 │
|
||||
│ C:\Windows\System32\inetsrv\config\applicationHost.config │
|
||||
|
||||
Reference in New Issue
Block a user