docs: 消除 Gitea 模棱两可 Unicode 告警（全角标点紧邻 ASCII 时改为半角）
依据 Gitea v1.27.3 modules/charset/escape_stream.go 的判定规则 （analyzeDetectResults：仅当左右相邻字符都不是非 ASCII 时才标记， 且 _common 表恒定生效），把说明文档中会被标记的全角标点 （，：；？！（） 等）改为半角，并保证成对括号宽度一致。 中文语境中的全角标点（左右均为中文）保持原样，不动代码与契约语义。 同时删除临时探针目录 _probe/（仅用于确认 Gitea 判定规则）。
This commit is contained in:
opendance
+13
-13
@@ -1,6 +1,6 @@
|
||||
# 反向代理说明（nginx / IIS）
|
||||
# 反向代理说明(nginx / IIS)
|
||||
|
||||
> **职责边界**：本 Web 端**只提供业务服务**（NestJS API + 管理端页面），
|
||||
> **职责边界**：本 Web 端**只提供业务服务**(NestJS API + 管理端页面),
|
||||
> **不部署、不配置反向代理**。反向代理由另外的服务或团队负责，本文档只提供配置说明。
|
||||
>
|
||||
> 安装脚本 `deploy/install.sh` 不会安装或修改任何反代软件。
|
||||
@@ -11,16 +11,16 @@
|
||||
|
||||
| 端口 | 环境变量 | 默认 | 给谁用 | 提供什么 |
|
||||
|--|--|--|--|--|
|
||||
| 软件 API 端口 | `PORT` | `3000` | Windows/Godot 客户端、Android App | `/api`、`/health`、`/static`、`/contracts`；**不含管理页面**（未知路径 404） |
|
||||
| 软件 API 端口 | `PORT` | `3000` | Windows/Godot 客户端、Android App | `/api`、`/health`、`/static`、`/contracts`; **不含管理页面**(未知路径 404) |
|
||||
| 管理端端口 | `ADMIN_PORT` | `3001` | 浏览器（管理员） | 管理页面 + 上面全部接口 |
|
||||
|
||||
```
|
||||
软件 API： http://<后端地址>:3000
|
||||
软件 API: http://<后端地址>:3000
|
||||
管理端： http://<后端地址>:3001
|
||||
```
|
||||
|
||||
两者都不需要在代理层托管静态文件，也不需要配置 SPA 回退（服务端已处理）；
|
||||
各用一条 `location /`（nginx）或全匹配规则（IIS）即可。
|
||||
各用一条 `location /`(nginx)或全匹配规则（IIS）即可。
|
||||
|
||||
**推荐做法**：把两个端口挂在两个不同的站点/域名上，便于分别做访问控制，例如
|
||||
|
||||
@@ -33,12 +33,12 @@
|
||||
| 路径 | 内容 | 哪个端口提供 |
|
||||
|--|--|--|
|
||||
| `/`、`/assets/*` | 管理端页面与静态资源 | **仅管理端**；前端路由深链接（如 `/songs`）由服务端回退到 `index.html` |
|
||||
| `/api/*` | REST API | 两个端口都提供（契约见 `contracts/rest-api.yaml`） |
|
||||
| `/api/*` | REST API | 两个端口都提供(契约见 `contracts/rest-api.yaml`) |
|
||||
| `/health` | 健康检查 | 两个端口都提供；可用作反代的存活探测，数据库不可用时返回 **503** |
|
||||
| `/static/*` | 上传文件 | 两个端口都提供（模型 / 音频 / 关键点序列） |
|
||||
| `/contracts/*` | 契约快照 | 两个端口都提供，只读 |
|
||||
|
||||
> Windows 客户端与 Android 之间的**关键点 WebSocket 链路不经过本服务**，
|
||||
> Windows 客户端与 Android 之间的**关键点 WebSocket 链路不经过本服务**,
|
||||
> 反代无需配置 WebSocket 转发。
|
||||
>
|
||||
> `ADMIN_PORT` 设为与 `PORT` 相同时是**单端口兼容模式**：两个端口合一，
|
||||
@@ -58,7 +58,7 @@
|
||||
|
||||
## 三、必须同步调整的两项
|
||||
|
||||
1. **上传上限**：本服务默认允许 512 MiB（`UPLOAD_MAX_BYTES`）。
|
||||
1. **上传上限**：本服务默认允许 512 MiB(`UPLOAD_MAX_BYTES`)。
|
||||
代理层默认值通常远小于此（nginx 1 MB、IIS 约 28.6 MB），不改会导致大模型上传失败。
|
||||
2. **超时**：上传大文件与下载关键点序列可能较慢，代理的读写超时必须放大。
|
||||
|
||||
@@ -138,7 +138,7 @@ IIS 管理器 -> 选中服务器节点 -> Application Request Routing Cache
|
||||
</rewrite>
|
||||
<security>
|
||||
<requestFiltering>
|
||||
<!-- 512 MiB：IIS 默认约 28.6 MB，不改大文件上传必失败 -->
|
||||
<!-- 512 MiB:IIS 默认约 28.6 MB，不改大文件上传必失败 -->
|
||||
<requestLimits maxAllowedContentLength="536870912" />
|
||||
</requestFiltering>
|
||||
</security>
|
||||
@@ -181,10 +181,10 @@ curl -i http://127.0.0.1:3001/health
|
||||
# 2. 经反代可访问
|
||||
curl -i http://<反代地址>/health
|
||||
|
||||
# 3. 管理端页面可打开（应返回 HTML）
|
||||
# 3. 管理端页面可打开(应返回 HTML)
|
||||
curl -i http://<反代地址>/ | head -5
|
||||
|
||||
# 4. 前端深链接可用（应返回同一份 HTML，而不是 404）
|
||||
# 4. 前端深链接可用(应返回同一份 HTML，而不是 404)
|
||||
curl -i http://<反代地址>/songs | head -5
|
||||
|
||||
# 5. API 可用
|
||||
@@ -196,7 +196,7 @@ curl -i http://<反代地址>/api/catalog/version
|
||||
|
||||
| 现象 | 原因 |
|
||||
|--|--|
|
||||
| 反代 502 / 504 | 后端未启动，或 `HOST` 绑定地址不对（同机应为 `127.0.0.1`，异机应为 `0.0.0.0`） |
|
||||
| 反代 502 / 504 | 后端未启动，或 `HOST` 绑定地址不对(同机应为 `127.0.0.1`，异机应为 `0.0.0.0`) |
|
||||
| 页面能开、接口 404 | 只转发了 `/`，需要把 `/api/`、`/health`、`/static/` 一并转发（最简单是全匹配） |
|
||||
| 上传大文件 413 | 代理层上传上限没放开（见第三、四、五节） |
|
||||
| 上传中途断开 | 代理超时太短 |
|
||||
@@ -210,7 +210,7 @@ curl -i http://<反代地址>/api/catalog/version
|
||||
在运维侧配好反代之前，可以直接访问后端业务服务（本项目开箱即用，不依赖反代）：
|
||||
|
||||
1. `deploy/.env` 中 `HOST=0.0.0.0`（若只想让某个网段访问，也可填具体网卡地址）
|
||||
2. 防火墙放行后端端口（默认 `3000/tcp`）
|
||||
2. 防火墙放行后端端口(默认 `3000/tcp`)
|
||||
3. 浏览器访问 `http://<服务器IP>:3000`
|
||||
|
||||
> 注意：服务默认在 **3000** 端口，不在 80/443。直接访问 `http://<服务器IP>/`
|
||||
|
||||
Reference in New Issue
Block a user