zijunchiang
34c5040e6b
"服务已启动但外部访问不了"时一次性定位原因，只读诊断、不改配置： - 读出 .env 的 HOST/PORT，并对 127.0.0.1 这种只监听回环的配置直接报错 - 检查实际监听地址（ss/netstat），区分通配与仅回环 - 回环 + 对外 IP 两次 /health 自测（用 ip route get 取真实出口 IP） - 检查 80/443 上有没有反向代理，并说明本项目不部署反代 - 检查 firewalld / ufw / iptables 对端口的放行情况，给出修复命令 - 结尾按"直连后端"与"经反代"两条路径给出结论 同时更新 README.txt、deploy/proxy/README.md（新增第八节：还没有反代时 如何直连后端）与打包校验清单。
224 lines
10 KiB
Plaintext
224 lines
10 KiB
Plaintext
================================================================
|
||
OpenDance Studio —— Web 管理服务端 v0.1.0 使用说明
|
||
================================================================
|
||
|
||
本服务端是 OpenDance Studio 三端中的第一端，负责管理歌曲、VRM 模型与
|
||
动作来源，是 Windows 客户端与 Android 辅助 App 的唯一数据源与契约权威。
|
||
|
||
重要：本服务端 **不部署、不管理 MySQL**。数据库为部署方提供的现有实例，
|
||
连接信息通过 .env 注入。
|
||
|
||
----------------------------------------------------------------
|
||
一、部署到 Linux 服务器（业务服务，不含反向代理）
|
||
----------------------------------------------------------------
|
||
|
||
职责边界
|
||
本端**只提供业务服务**：NestJS API + 管理端页面。
|
||
**反向代理由另外的服务/团队负责**，本项目不安装、不配置任何反代软件，
|
||
只在 deploy/proxy/ 下提供 IIS 与 nginx 的配置说明文档。
|
||
|
||
部署形态
|
||
Node 业务服务由系统服务托管，同时提供：
|
||
/ 管理端页面（本服务自带，含 SPA 深链接回退）
|
||
/api/ REST API
|
||
/health 健康检查
|
||
/static/ 上传文件
|
||
/contracts/ 契约快照
|
||
因为静态页面也由本服务提供，反向代理**只需一条全匹配转发规则**。
|
||
|
||
前置要求
|
||
- Linux 服务器，有 root 权限（不需要 sudo，直接以 root 执行即可）
|
||
- Node.js 22 或更高版本
|
||
- 进程管理：systemd / OpenRC / SysVinit 均可；**三者都没有也能装**
|
||
（自动降级为 nohup 后台进程 + PID 文件 + crontab @reboot 开机自启）
|
||
- 反向代理：由另外的服务提供，本项目不要求、也不安装
|
||
- 一个可连通的现有 MySQL / MariaDB 实例，并已创建数据库与账号：
|
||
|
||
CREATE DATABASE IF NOT EXISTS dpendance
|
||
CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||
CREATE USER IF NOT EXISTS 'dpendance'@'%' IDENTIFIED BY '<密码>';
|
||
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP, REFERENCES
|
||
ON dpendance.* TO 'dpendance'@'%';
|
||
FLUSH PRIVILEGES;
|
||
|
||
（本项目不会创建数据库本身，也不需要 GRANT OPTION / FILE / SUPER 等管理权限）
|
||
|
||
部署步骤
|
||
tar -xzf opendance-web-v0.1.0.tar.gz
|
||
cd opendance-web-v0.1.0
|
||
cp deploy/.env.example deploy/.env
|
||
vi deploy/.env # 填写 DB_HOST / DB_PORT / DB_USER / DB_PASS / DB_NAME
|
||
sudo bash deploy/install.sh
|
||
|
||
脚本会依次：
|
||
校验环境与 .env → 创建服务用户与目录 → 复制程序文件 →
|
||
安装运行期依赖 → 执行 TypeORM 迁移 →
|
||
注册并启动系统服务（systemd / OpenRC / SysVinit / 后台进程）→ 等待健康检查
|
||
|
||
部署完成后（直接访问后端端口，<host> 为服务器 IP）
|
||
管理端首页： http://<host>:3000/
|
||
API 前缀： http://<host>:3000/api
|
||
健康检查： http://<host>:3000/health
|
||
契约快照： http://<host>:3000/contracts/
|
||
|
||
对外访问
|
||
由反向代理把请求转发到 http://<后端地址>:3000 即可。
|
||
配置样例与说明：
|
||
deploy/proxy/nginx.conf.example nginx 站点配置
|
||
deploy/proxy/web.config.example IIS（ARR + URL Rewrite）配置
|
||
deploy/proxy/README.md 完整说明、自检清单与常见故障
|
||
|
||
外部访问不了？先在服务器上跑一次自检脚本（只读，不改配置）：
|
||
bash deploy/check-access.sh # 或 bash deploy/check-access.sh /opt/opendance
|
||
它会打印 .env 里的 HOST/PORT、实际监听地址、回环与对外 IP 自测结果、
|
||
80/443 是否有反代、防火墙放行情况，并直接给出修复命令。
|
||
|
||
可覆盖的安装参数
|
||
APP_DIR=/opt/opendance 程序目录
|
||
SERVICE_USER=opendance 运行服务的系统用户
|
||
STORAGE_DIR=/var/lib/opendance/storage 上传文件目录
|
||
|
||
例：APP_DIR=/srv/opendance bash deploy/install.sh
|
||
|
||
升级
|
||
解压新版本后重新执行 sudo bash deploy/install.sh 即可（会覆盖程序文件，
|
||
保留 deploy/.env 与上传数据）。
|
||
|
||
卸载
|
||
sudo bash deploy/uninstall.sh # 停服务、禁用站点，保留数据
|
||
sudo bash deploy/uninstall.sh --purge # 一并删除程序目录与上传文件
|
||
|
||
数据库始终由部署方自行管理，卸载脚本不做任何改动。
|
||
|
||
常用命令（按安装时自动检测到的初始化系统而定）
|
||
systemd：
|
||
systemctl status opendance-api # 服务状态
|
||
journalctl -u opendance-api -f # 实时日志
|
||
systemctl restart opendance-api # 重启
|
||
|
||
OpenRC：
|
||
rc-service opendance-api status / restart
|
||
tail -f /var/log/opendance-api.log
|
||
|
||
SysVinit：
|
||
/etc/init.d/opendance-api status / restart
|
||
|
||
无 init 系统（降级模式）：
|
||
bash /opt/opendance/deploy/ctl.sh status | restart | logs
|
||
|
||
反代配置：不在本机，无需在此维护
|
||
|
||
----------------------------------------------------------------
|
||
二、本地开发
|
||
----------------------------------------------------------------
|
||
|
||
后端
|
||
cd web-server
|
||
cp .env.example .env # 填写 DB_*
|
||
npm install
|
||
npm run migration:run # 首次需要
|
||
npm run start:dev # http://localhost:3000
|
||
|
||
管理前端
|
||
cd web-server/admin
|
||
npm install
|
||
npm run dev # http://localhost:5173（/api 与 /health 代理到 3000）
|
||
|
||
----------------------------------------------------------------
|
||
三、验证
|
||
----------------------------------------------------------------
|
||
|
||
cd web-server
|
||
npm run contracts:check # 契约版本一致性
|
||
npm run typecheck # TypeScript 严格检查
|
||
npm run test # 31 项单元测试
|
||
npm run build # 生产构建
|
||
npm run start:prod & # 启动
|
||
npm run test:smoke # 57 项端到端冒烟（需要数据库可连通）
|
||
|
||
cd ../admin && npm run build # 管理端构建
|
||
|
||
----------------------------------------------------------------
|
||
四、环境变量
|
||
----------------------------------------------------------------
|
||
|
||
DB_HOST / DB_PORT / DB_USER / DB_PASS / DB_NAME
|
||
现有 MySQL 实例连接信息（必填）
|
||
|
||
DB_SYNCHRONIZE
|
||
必须为 false。生产环境启动时若检测到 true 会直接中止启动。
|
||
所有表结构变更通过 TypeORM migration 执行。
|
||
|
||
DB_LOGGING 是否打印 SQL（默认 false）
|
||
PORT API 监听端口（默认 3000）
|
||
HOST 监听地址。反代与后端同机用 127.0.0.1（推荐）；
|
||
反代在别的机器用 0.0.0.0，并用防火墙限制来源
|
||
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 动作预处理需要
|
||
CONTRACTS_DIR 可选：契约目录，设置后 /health 反映实时契约版本
|
||
（原生部署默认指向 /opt/opendance/contracts）
|
||
|
||
----------------------------------------------------------------
|
||
五、主要 API
|
||
----------------------------------------------------------------
|
||
|
||
GET /health 健康检查（含数据库连通性）
|
||
GET /api/songs 曲目列表（分页 / 检索）
|
||
POST /api/songs 新建曲目
|
||
GET /api/songs/:id 曲目详情
|
||
PATCH /api/songs/:id 更新曲目
|
||
DELETE /api/songs/:id 删除曲目（软删除）
|
||
POST /api/songs/:id/audio 上传音频
|
||
GET /api/motions 动作列表
|
||
POST /api/motions 上传动作 + 来源信息
|
||
POST /api/motions/:id/preprocess BVH/FBX → MediaPipe33 关键点
|
||
GET /api/motions/:id/keypoints 下载关键点序列（NDJSON）
|
||
GET /api/models 模型列表
|
||
POST /api/models 上传模型 + 来源信息（VRM 优先）
|
||
POST /api/models/:id/primary 设为全局默认模型
|
||
GET /api/reviews 审核流水 / 待审列表
|
||
POST /api/reviews/:type/:id/approve 审核通过
|
||
POST /api/reviews/:type/:id/reject 审核驳回（必须填意见）
|
||
GET /api/catalog/export 客户端一次性拉取已发布目录
|
||
GET /api/catalog/version 契约版本 + 目录指纹
|
||
|
||
完整契约（OpenAPI 3.0）见 contracts/rest-api.yaml。
|
||
|
||
上传文件通过 /static/<kind>/<yyyy>/<mm>/<sha256>.ext 访问，
|
||
相同内容只落盘一次（sha256 去重）。
|
||
|
||
----------------------------------------------------------------
|
||
六、目录结构
|
||
----------------------------------------------------------------
|
||
|
||
project.yaml 任务清单与状态
|
||
DSH.md 本项目 DSH 执行约束
|
||
tasks/ 单任务说明书（T-WEB-001 ~ 010）
|
||
contracts/ 跨端契约（权威，改接口先改这里）
|
||
web-server/ NestJS 服务端源码
|
||
web-server/admin/ React 管理端
|
||
deploy/ 业务服务部署（系统服务，不含 MySQL、不含反向代理）
|
||
deploy/proxy/ 反向代理配置说明（nginx / IIS，仅供参考不部署）
|
||
THIRD_PARTY.md 第三方开源项目声明
|
||
|
||
----------------------------------------------------------------
|
||
七、安全提示
|
||
----------------------------------------------------------------
|
||
|
||
1. .env 已被 .gitignore 忽略，禁止提交；仓库中只保留 .env.example。
|
||
2. 数据库账号使用最小权限，不授予 GRANT OPTION / FILE / SUPER。
|
||
3. 本版本未内置管理端登录认证，请部署在内网，或在反向代理层加 Basic Auth / SSO。
|
||
4. 上传的模型与动作必须填写来源五元组并通过审核后才对客户端可见。
|
||
5. 未使用 SMPL 拓扑，统一 MediaPipe 33 点，规避非商用许可限制。
|
||
|
||
----------------------------------------------------------------
|
||
八、第三方开源声明
|
||
----------------------------------------------------------------
|
||
|
||
见 THIRD_PARTY.md，或访问站点 http://<host>/ 的「关于」页面。
|