From 8c2f2afaead431cb889af9d9037173acdb49be6e Mon Sep 17 00:00:00 2001 From: zijunchiang Date: Tue, 15 Sep 2026 21:28:12 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=B8=89=E5=BA=93=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E8=A7=84=E8=8C=83=E5=8C=96=EF=BC=88=E5=8E=BB=E6=B7=B7=E6=B7=86?= =?UTF-8?q?=E5=AD=97=E7=AC=A6=20+=20=E5=8D=A0=E4=BD=8D=E7=AC=A6=EF=BC=89+?= =?UTF-8?q?=20Web=20README=20=E5=88=9D=E6=AC=A1=E9=83=A8=E7=BD=B2=E6=B8=85?= =?UTF-8?q?=E5=8D=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 三库所有 .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 条路由一致。 --- contracts/rest-api.yaml | 22 +++++++++++----------- deploy/.env.example | 10 +++++----- deploy/proxy/nginx.conf.example | 6 +++--- deploy/proxy/web.config.example | 14 +++++++------- project.yaml | 4 ++-- web-server/.env.example | 2 +- 6 files changed, 29 insertions(+), 29 deletions(-) diff --git a/contracts/rest-api.yaml b/contracts/rest-api.yaml index 66dc71b..44e1609 100644 --- a/contracts/rest-api.yaml +++ b/contracts/rest-api.yaml @@ -262,7 +262,7 @@ paths: parameters: [{ $ref: '#/components/parameters/Id' }] post: tags: [motions] - summary: 触发 BVH/FBX → MediaPipe33 关键点序列预处理（同步执行） + summary: 触发 BVH/FBX -> MediaPipe33 关键点序列预处理（同步执行） description: | 同步执行并返回最终状态：成功时 preprocessState=done； 失败时返回 422，且 Motion.preprocessError 记录可读原因。 @@ -285,7 +285,7 @@ paths: '200': description: | application/x-ndjson，每行一个帧对象： - {"frame":0,"timeMs":0,"points":[[x,y,z,conf], …33],"angles":[9 个余弦]} + {"frame":0,"timeMs":0,"points":[[x,y,z,conf], ...33],"angles":[9 个余弦]} content: application/x-ndjson: schema: { type: string } @@ -323,11 +323,11 @@ paths: - `.glb` / `.vrm` / `.gltf`：**直接导入**，不重编码 - `.pmx` / `.fbx`：服务端转换，**优先 GLB、其次 VRM** - - `.zip`：**自动搜索包内可用模型** —— `.vrm` → `.glb` → `.gltf`（直接导入） - 优先，其次 `.pmx` → `.fbx`（转换）。压缩包原件作为 `model-archive` 资产留存。 + - `.zip`：**自动搜索包内可用模型** -- `.vrm` -> `.glb` -> `.gltf`（直接导入） + 优先，其次 `.pmx` -> `.fbx`（转换）。压缩包原件作为 `model-archive` 资产留存。 - 转换链路（`model-convert.ts`）：`assimp export → .glb` →（失败）`→ .gltf` 后 - 由服务端自行打包成 GLB →（`MODEL_CONVERT_FORMAT=vrm` 时）在 GLB 之上补 + 转换链路（`model-convert.ts`）：`assimp export -> .glb` ->（失败）`-> .gltf` 后 + 由服务端自行打包成 GLB ->（`MODEL_CONVERT_FORMAT=vrm` 时）在 GLB 之上补 `VRMC_vrm` 扩展产出 VRM 1.0。每一步都 `assimp info` **回读校验**， 并把过程写进 `conversionNote`；贴图会内嵌进 GLB，保证单文件可用。 @@ -488,7 +488,7 @@ paths: - $ref: '#/components/parameters/Id' post: tags: [reviews] - summary: 审核通过 → published + summary: 审核通过 -> published requestBody: content: application/json: @@ -510,7 +510,7 @@ paths: - $ref: '#/components/parameters/Id' post: tags: [reviews] - summary: 撤回审核 → draft + summary: 撤回审核 -> draft requestBody: content: application/json: @@ -552,7 +552,7 @@ paths: - $ref: '#/components/parameters/Id' post: tags: [reviews] - summary: 审核驳回 → rejected + summary: 审核驳回 -> rejected requestBody: required: true content: @@ -795,13 +795,13 @@ components: fileSha256: type: string nullable: true - description: 模型文件（转换产物）的 sha256 —— 每次转换都会变（Assimp 导出非字节级确定），仅作记录 + description: 模型文件（转换产物）的 sha256 -- 每次转换都会变（Assimp 导出非字节级确定），仅作记录 stats: type: object nullable: true description: >- 模型分析结果（面数 / 顶点数 / 贴图 / 骨骼树 / humanoid 覆盖 / 可驱动性）， - 审核界面据此判断"能不能驱动与评分"。结构见 contracts/model-formats.md §1.1 + 审核界面据此判断"能不能驱动与评分"。结构见 contracts/model-formats.md 1.1 sourceSha256: type: string nullable: true diff --git a/deploy/.env.example b/deploy/.env.example index 4d6fcf2..883d4cf 100644 --- a/deploy/.env.example +++ b/deploy/.env.example @@ -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 # ---- 契约目录 ---- diff --git a/deploy/proxy/nginx.conf.example b/deploy/proxy/nginx.conf.example index 9ad495c..4f47504 100644 --- a/deploy/proxy/nginx.conf.example +++ b/deploy/proxy/nginx.conf.example @@ -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 /` 全匹配转发即可。 diff --git a/deploy/proxy/web.config.example b/deploy/proxy/web.config.example index b4c3e13..c602196 100644 --- a/deploy/proxy/web.config.example +++ b/deploy/proxy/web.config.example @@ -1,7 +1,7 @@