docs: 三库文档规范化(去混淆字符 + 占位符)+ Web README 初次部署清单

- 三库所有 .md/.txt 与配置样例中的 — – … § → 一律换成 ASCII(Gitea 的
  「模棱两可的 Unicode 字符」告警即由这几个字符触发;中文全角标点不受影响,
  实测 README.txt 修正后告警消失)
- contracts/* 在三库保持逐字节一致(已校验 md5)
- 残留真实值清理:README.txt 建库 SQL 的 dpendance -> opendance/opendance_app,
  Android HostDiscovery.kt 注释示例 192.168.1.23 -> 192.0.2.23
- Web README.txt 新增「初次部署(从零跑起来)」8 步清单与「常见问题(初次部署)」
  7 条;去掉纯文本 README 里的 markdown 粗体标记;统一 '以 root 直接执行' 写法
- 重新打包 v0.2.0

验证:168 项单测通过;契约 6 项与 30 条路由一致。
This commit is contained in:
2026-09-15 21:28:12 +08:00
parent ebd871018f
commit 8c2f2afaea
6 changed files with 29 additions and 29 deletions
+5 -5
View File
@@ -1,5 +1,5 @@
# ============================================================
# OpenDance Studio Web 服务端 —— Linux 原生部署环境变量
# OpenDance Studio Web 服务端 -- Linux 原生部署环境变量
#
# 复制为 deploy/.env 后填写;.env 已被 .gitignore 忽略,禁止提交。
# 该文件由 systemd 通过 EnvironmentFile 注入 Node 进程。
@@ -14,8 +14,8 @@ PORT=3000
# 不设置时默认 = PORT + 1(即 3001);设为与 PORT 相同即为单端口兼容模式
ADMIN_PORT=3001
# 监听地址:
# 反代与后端同机 → 127.0.0.1(后端不直接对外暴露,推荐)
# 反代在别的机器 → 0.0.0.0,并用防火墙把该端口限制为仅反代来源可访问
# 反代与后端同机 -> 127.0.0.1(后端不直接对外暴露,推荐)
# 反代在别的机器 -> 0.0.0.0,并用防火墙把该端口限制为仅反代来源可访问
HOST=0.0.0.0
# 管理端单独绑定地址(可选)。只想让管理端暴露在内网时,例如 127.0.0.1 或内网网卡地址
# ADMIN_HOST=127.0.0.1
@@ -49,14 +49,14 @@ ASSIMP_BIN=assimp
# vrm:在 GLB 之上补 VRMC_vrm 扩展(humanoid 骨骼 / 表情语义);
# humanoid 骨骼名映射不全时会自动回退交付 GLB 并写进 conversion_note
MODEL_CONVERT_FORMAT=glb
# 压缩包里优先选用的 PMX 文件名(大小写不敏感);找不到时按"格式优先级 → 目录最浅 → 文件最大"挑
# 压缩包里优先选用的 PMX 文件名(大小写不敏感);找不到时按"格式优先级 -> 目录最浅 -> 文件最大"挑
MODEL_CONVERT_PMX=Hatsune Miku.pmx
# 单次转换超时(毫秒)
MODEL_CONVERT_TIMEOUT_MS=180000
# ---- 默认模型(可选)----
# 显式指定默认模型 id;不设置时按源码 src/config/default-model.ts 里的种子匹配,
# 再回落到契约 data-models.md §4.1 的 VRM 优先规则
# 再回落到契约 data-models.md 4.1 的 VRM 优先规则
# DEFAULT_MODEL_ID=1
# ---- 契约目录 ----
+3 -3
View File
@@ -1,13 +1,13 @@
# ============================================================
# OpenDance Studio Web 服务端 —— nginx 反向代理样例(双端口)
# OpenDance Studio Web 服务端 -- nginx 反向代理样例(双端口)
#
# 说明:本 Web 端不自带反向代理。本文件是**给你的反代服务参考**的配置样例,
# 由部署 `deploy/install.sh` 之外的反代负责人使用。
#
# 后端同时监听两个端口,职责不同:
# 软件 API 端口(PORT,默认 3000)—— Windows/Godot 客户端、Android App
# 软件 API 端口(PORT,默认 3000)-- Windows/Godot 客户端、Android App
# 只提供 /api、/health、/static、/contracts
# 管理端端口(ADMIN_PORT,默认 3001)—— 浏览器,提供管理页面 + 上面全部接口
# 管理端端口(ADMIN_PORT,默认 3001)-- 浏览器,提供管理页面 + 上面全部接口
#
# 两个端口都不需要在代理层托管静态文件、也不需要 SPA 回退(服务端已处理),
# 因此每个站点只要一条 `location /` 全匹配转发即可。
+7 -7
View File
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
============================================================
OpenDance Studio Web 服务端 —— IIS 反向代理样例
OpenDance Studio Web 服务端 -- IIS 反向代理样例
说明:本 Web 端不自带反向代理。本文件是**给你的反代服务参考**的配置样例。
@@ -11,21 +11,21 @@
2. Application Request Routing (ARR)
https://www.iis.net/downloads/microsoft/application-request-routing
3. 启用 ARR 代理(否则会 404.4):
IIS 管理器 → 服务器节点 → Application Request Routing Cache
→ Server Proxy Settings → 勾选 Enable proxy
IIS 管理器 -> 服务器节点 -> Application Request Routing Cache
-> Server Proxy Settings -> 勾选 Enable proxy
放置位置:IIS 站点根目录下的 web.config
后端(NestJS)同时监听两个端口,职责不同:
软件 API 端口(PORT,默认 3000)—— 给 Windows/Godot 客户端与 Android App
软件 API 端口(PORT,默认 3000)-- 给 Windows/Godot 客户端与 Android App
只有 /api、/health、/static、/contracts
管理端端口(ADMIN_PORT,默认 3001)—— 给浏览器
管理端端口(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}
站点 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 回退。