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` 走单端口模式，而不是让反代去猜 |
|
||||
|
||||
## 八、还没有反代时：直连后端怎么访问
|
||||
|
||||
|
||||
Reference in New Issue
Block a user