zijunchiang/opendance-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity

docs: 消除 Gitea 模棱两可 Unicode 告警（全角标点紧邻 ASCII 时改为半角）

Browse Source 
依据 Gitea v1.27.3 modules/charset/escape_stream.go 的判定规则
（analyzeDetectResults：仅当左右相邻字符都不是非 ASCII 时才标记，
且 _common 表恒定生效），把说明文档中会被标记的全角标点
（，：；？！（） 等）改为半角，并保证成对括号宽度一致。
中文语境中的全角标点（左右均为中文）保持原样，不动代码与契约语义。

同时删除临时探针目录 _probe/（仅用于确认 Gitea 判定规则）。
This commit is contained in:
opendance
2026-09-15 21:45:51 +08:00
parent a34cca007c
commit 60c182f1b2
28 changed files with 276 additions and 615 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tasks/010-deploy.md
+47 -47
View File
@@ -1,17 +1,17 @@
# T-WEB-010 部署（Linux 业务服务，不使用 Docker，不部署反代）
- **状态**：done（两次需求变更后重做）
- **依赖**：T-WEB-001 ~ 009
- **状态**: done（两次需求变更后重做）
- **依赖**: T-WEB-001 ~ 009
## 目标
Web 服务端以**一个 Linux 业务服务**的形式部署运行：Node 进程由系统服务
（systemd / OpenRC / SysVinit / 后台进程）托管，**同时提供 REST API 与管理端页面**。
**不使用 Docker**，**不部署 MySQL**（数据库为部署方提供的现有实例），
(systemd / OpenRC / SysVinit / 后台进程)托管，**同时提供 REST API 与管理端页面**。
**不使用 Docker**, **不部署 MySQL**（数据库为部署方提供的现有实例），
**也不部署反向代理**（由另外的服务/团队负责）。
> **需求变更记录**
> 1. 初版按文档 4.4 实现为 Docker Compose；用户要求改为"运行在 Linux 的网站"，
> 1. 初版按文档 4.4 实现为 Docker Compose；用户要求改为"运行在 Linux 的网站",
> 于是替换为 nginx + systemd 原生站点部署，并删除 `deploy/docker-compose.yml`、
> `web-server/Dockerfile`、`web-server/admin/Dockerfile`。
> 2. 随后用户明确："web 端仅需要业务需求，反代等工作交由另外的服务处理。
@@ -20,7 +20,7 @@ Web 服务端以**一个 Linux 业务服务**的形式部署运行：Node 进程
> 托管（`ADMIN_DIR` + SPA 深链接回退），并新增 `deploy/proxy/` 只交付说明文档。
> 3. 再随后用户要求**管理端口与软件 API 端口分离**：新增 `ADMIN_PORT`
> （默认 `PORT + 1`）与可选的 `ADMIN_HOST`（默认跟随 `HOST`）。软件 API 端口
> 只给客户端调接口（`/api`、`/health`、`/static`、`/contracts`，`/` 等返回 404），
> 只给客户端调接口（`/api`、`/health`、`/static`、`/contracts`, `/` 等返回 404），
> 管理端端口给浏览器（管理页面 + 全部接口）。`ADMIN_PORT === PORT` 保留为
> 单端口兼容模式，只 warn 不中止。install.sh 的汇总与反代说明改为两个端口。
> 4. 本次追加两项：
@@ -29,7 +29,7 @@ Web 服务端以**一个 Linux 业务服务**的形式部署运行：Node 进程
> `install.sh` 在缺 `deploy/.env` 时先调用它，失败才 die（安装目录已有上次
> 安装留下的.env 则直接复用，保持原语义）。
> b) **默认监听 0.0.0.0 固化**：确认 `configuration.ts` 的
> `bindHost = process.env.HOST?? '0.0.0.0'`、`adminHost` 默认跟随 HOST，
> `bindHost = process.env.HOST?? '0.0.0.0'`、`adminHost` 默认跟随 HOST,
> 两个 `.env.example` 与 `init-env.sh` 的 HOST 默认值均为 `0.0.0.0`。
## load
@@ -52,10 +52,10 @@ deploy/proxy/README.md
```
Windows/Godot 客户端、Android App ─▶ 软件 API 端口:3000（只提供接口，无管理页面）
├── /api/ REST API
├── /health 健康检查（数据库不可用返回 503）
├── /health 健康检查(数据库不可用返回 503)
├── /static/ 上传文件
└── /contracts/ 契约快照
（/、/songs 等返回 404，有意设计）
(/、/songs 等返回 404，有意设计)
浏览器 ─▶ 反向代理（外部提供，IIS / nginx / 网关...）──▶ 管理端端口:3001
│ 整端口转发，不需要托管静态文件 ├── / 管理端页面（含 SPA 深链接回退）
@@ -81,15 +81,15 @@ Windows/Godot 客户端、Android App ─▶ 软件 API 端口:3000（只提供
| `deploy/.env.example` | 部署环境变量样例（`PORT` / `ADMIN_PORT` / `ADMIN_HOST` / `HOST` 说明与上传上限告警） |
| `deploy/systemd/opendance-api.service` | systemd 单元，含 `ProtectSystem=strict` 等安全加固 |
| `deploy/openrc/opendance-api` | OpenRC 服务脚本 |
| `deploy/initd/opendance-api` | SysVinit / LSB 启动脚本（转调 ctl.sh） |
| `deploy/initd/opendance-api` | SysVinit / LSB 启动脚本(转调 ctl.sh) |
| `deploy/ctl.sh` | 无 init 系统时的进程控制（后台进程 + PID 文件），start/stop/restart/status/logs |
| `deploy/proxy/README.md` | **反代说明文档**：转发目标、绑定地址、自检清单、故障对照 |
| `deploy/proxy/nginx.conf.example` | nginx 配置样例（上传上限、超时、keepalive、可选 HTTPS） |
| `deploy/proxy/nginx.conf.example` | nginx 配置样例(上传上限、超时、keepalive、可选 HTTPS) |
| `deploy/proxy/web.config.example` | IIS 配置样例（需 ARR + URL Rewrite 模块） |
## deploy/.env 初始化引导（init-env.sh）
## deploy/.env 初始化引导(init-env.sh)
首次部署不再要求手工 `cp deploy/.env.example deploy/.env && vi deploy/.env`：
首次部署不再要求手工 `cp deploy/.env.example deploy/.env && vi deploy/.env`:
```
install.sh 检测到缺 deploy/.env
@@ -97,11 +97,11 @@ install.sh 检测到缺 deploy/.env
└── 否则调用 deploy/init-env.sh
├── 缺.env -> 从.env.example 复制，chmod 600
├── 交互（TTY / 管道）-> 逐项询问并写回
└── 非交互（CI、</dev/null、-y）-> 只校验，绝不阻塞；失败则 install.sh die
└── 非交互(CI、</dev/null、-y)-> 只校验，绝不阻塞；失败则 install.sh die
```
逐项询问 `DB_HOST / DB_PORT / DB_USER / DB_PASS / DB_NAME / PORT / ADMIN_PORT / HOST`
共 8 个键，回车保留默认；`DB_PASS` 用 `read -rs` 不回显、按约定写盘**不加引号**；
共 8 个键，回车保留默认；`DB_PASS` 用 `read -rs` 不回显、按约定写盘**不加引号**;
校验必填项与端口范围；可用 Node + mysql2 做连通性自检（口令只经环境变量传给子进程，
失败仅告警）；只替换/追加这 8 个键、保留模板注释，写完 `chmod 600` 并回读校验；
结尾打印摘要（口令 `***`）与本次变更列表。
@@ -116,21 +116,21 @@ install.sh 检测到缺 deploy/.env
| `--skip-db-check` | 跳过数据库连通性自检 |
| `--dir DIR` | 等价于 `--env-file DIR/.env --example DIR/.env.example` |
| `--env-file PATH` / `--example PATH` | 指定 `.env` / 模板路径 |
| `--timeout SECONDS` | 非 TTY 下每次读取超时秒数（默认 10） |
| `--timeout SECONDS` | 非 TTY 下每次读取超时秒数(默认 10) |
| `-h` / `--help` | 显示帮助 |
环境变量：`OPENDANCE_NONINTERACTIVE` / `OPENDANCE_INTERACTIVE` /
`OPENDANCE_SKIP_DB_CHECK` / `OPENDANCE_ENV_FILE` / `OPENDANCE_ENV_EXAMPLE` /
`OPENDANCE_PROMPT_TIMEOUT`。
**非交互绝不挂住**：stdin 非 TTY 且是 `</dev/null` 或已关闭，或带 `-y` 等开关 ->
**非交互绝不挂住**: stdin 非 TTY 且是 `</dev/null` 或已关闭，或带 `-y` 等开关 ->
只校验不提问；所有 read 带超时，EOF/超时立即 `exit 1`。
**默认监听 0.0.0.0**：`configuration.ts` 的
`bindHost = process.env.HOST?? '0.0.0.0'`，`adminHost` 默认跟随 `HOST`
（HOST 未设置时同样回落 `0.0.0.0`）；`deploy/.env.example` 与
`web-server/.env.example` 均写 `HOST=0.0.0.0`；`install.sh` 的
`BIND_HOST="${HOST:-0.0.0.0}"`；`init-env.sh` 的 HOST 默认值也是 `0.0.0.0`。
**默认监听 0.0.0.0**: `configuration.ts` 的
`bindHost = process.env.HOST?? '0.0.0.0'`, `adminHost` 默认跟随 `HOST`
(HOST 未设置时同样回落 `0.0.0.0`); `deploy/.env.example` 与
`web-server/.env.example` 均写 `HOST=0.0.0.0`; `install.sh` 的
`BIND_HOST="${HOST:-0.0.0.0}"`; `init-env.sh` 的 HOST 默认值也是 `0.0.0.0`。
注意 `install.sh` 里的 `HEALTH_HOST` / `API_HOST` 用的是**回环地址**做本机健康检查，
与对外监听的默认值无关。
@@ -142,7 +142,7 @@ install.sh 检测到缺 deploy/.env
1. systemd /run/systemd/system 存在且 systemctl 可用
2. OpenRC rc-service + rc-update 可用
3. SysVinit /etc/init.d 存在且 update-rc.d 或 chkconfig 可用
4. 都没有 nohup 后台进程 + PID 文件（deploy/ctl.sh）
4. 都没有 nohup 后台进程 + PID 文件(deploy/ctl.sh)
并写 crontab @reboot 实现开机自启
```
@@ -156,45 +156,45 @@ install.sh 检测到缺 deploy/.env
## 关键实现
- **双端口**：一个 Node 进程创建两个 HTTP server--软件 API 端口（`PORT`，默认 3000）
- **双端口**：一个 Node 进程创建两个 HTTP server--软件 API 端口(`PORT`，默认 3000)
与管理端端口（`ADMIN_PORT`，默认 3001），复用同一个 express 实例；用
`req.socket.localPort` 判断请求来自哪个端口，决定是否提供管理页面。
`ADMIN_PORT === PORT` 时只建一个 server（单端口兼容模式，避免 EADDRINUSE）
- **服务自身托管管理端**：`app.useStaticAssets(adminDir,...)` + SPA 回退中间件
`ADMIN_PORT === PORT` 时只建一个 server(单端口兼容模式，避免 EADDRINUSE)
- **服务自身托管管理端**: `app.useStaticAssets(adminDir,...)` + SPA 回退中间件
（仅管理端口生效）；回退会跳过 `/api/`、`/health`、`/static/`、`/contracts/`
以及带扩展名的路径，保证未知 API 仍返回 404 而不是 HTML
- **软件 API 端口不提供管理页面**：`/`、`/songs` 等在该端口一律 404（有意设计）
- **软件 API 端口不提供管理页面**: `/`、`/songs` 等在该端口一律 404（有意设计）
- **`HOST` / `ADMIN_HOST` 绑定地址**：同机反代建议 `127.0.0.1`，异机反代用
`0.0.0.0` + 防火墙；`ADMIN_HOST` 可选（默认跟随 `HOST`），可单独把管理端限制在
本机或内网；`HOST` 默认取 `0.0.0.0` 以保证开箱可用
- **首次部署的.env 由引导生成**：`install.sh` 缺 `deploy/.env` 时先调用
- **首次部署的.env 由引导生成**: `install.sh` 缺 `deploy/.env` 时先调用
`deploy/init-env.sh`（安装目录已有上次安装的 `.env` 则直接复用）；引导脚本在
非交互环境下只校验、绝不阻塞，校验失败时 install.sh 才 die
- **端口校验**：`PORT` / `ADMIN_PORT` 必须是 1..65535 的整数；非法值在生产环境
- **端口校验**: `PORT` / `ADMIN_PORT` 必须是 1..65535 的整数；非法值在生产环境
启动时快速失败（`validateEnv` 的 errors），`ADMIN_PORT === PORT` 只 warn
- **install.sh 汇总与反代说明**：结尾分别打印两个端口的访问地址、监听配置与
防火墙放行命令（`firewall-cmd` / `ufw` 同时放行两个端口）
- **systemd 加固**：`NoNewPrivileges`、`ProtectSystem=strict`、`ProtectHome`、
- **systemd 加固**: `NoNewPrivileges`、`ProtectSystem=strict`、`ProtectHome`、
`ReadWritePaths=/var/lib/opendance`，进程只能写自己的存储目录
- **上传上限两侧一致**：后端 `UPLOAD_MAX_BYTES=536870912`（512 MiB），
- **上传上限两侧一致**：后端 `UPLOAD_MAX_BYTES=536870912`(512 MiB),
反代侧 `client_max_body_size` / `maxAllowedContentLength` 必须不小于此值
- **模型转换配置**（`deploy/.env.example` 已写入）：
- **模型转换配置**(`deploy/.env.example` 已写入):
- `ASSIMP_BIN=assimp`：上传 `.zip` 模型包或 `.pmx`/`.fbx` 单文件时**必须**能调用到，
否则转换失败 **422**
- `MODEL_CONVERT_FORMAT=glb`（默认）|`vrm`：只影响需要转换的 PMX/FBX 的交付格式。
`glb` 通用，两个客户端都原生加载；`vrm` 在 GLB 之上补 `VRMC_vrm` 扩展
（humanoid 骨骼 / 表情语义），**humanoid 骨骼名映射不全时自动回退交付 GLB**
(humanoid 骨骼 / 表情语义), **humanoid 骨骼名映射不全时自动回退交付 GLB**
并写进 `models.conversion_note`。产物一律 `assimp info` 回读校验
- `MODEL_CONVERT_PMX` / `MODEL_CONVERT_TIMEOUT_MS` 语义见 README 四
- **迁移用编译产物**：`web-server/scripts/migrate.mjs` 检测到 `dist/` 时走
`typeorm -d dist/db/data-source.js`，无需在服务器上装 devDependencies；
- **迁移用编译产物**: `web-server/scripts/migrate.mjs` 检测到 `dist/` 时走
`typeorm -d dist/db/data-source.js`，无需在服务器上装 devDependencies;
本版本迁移共 3 个：`InitSchema1789382903060`、
`AddModelConversionFields1789450000000`、**`AddModelStats1789460000000`**
（新增 `models.stats TEXT`，存模型分析结果，已在真实库执行）
- **依赖安装显式带 dev**：安装脚本先 `set -a;. deploy/.env` 导出了
`NODE_ENV=production`，会让 npm 跳过 devDependencies 导致 `tsc: not found`；
`NODE_ENV=production`，会让 npm 跳过 devDependencies 导致 `tsc: not found`;
故用 `env -u NODE_ENV npm ci --include=dev`
- **复制文件时锚定排除**：`storage/` 这类模式会误伤 `src/storage/` 与 `dist/storage/`
- **复制文件时锚定排除**: `storage/` 这类模式会误伤 `src/storage/` 与 `dist/storage/`
（曾导致 `MODULE_NOT_FOUND...storage.module`），排除规则一律用 `/storage/` 锚定
- **`/contracts/` 静态暴露**：另两端可直接从站点取契约快照
@@ -202,7 +202,7 @@ install.sh 检测到缺 deploy/.env
```bash
bash deploy/init-env.sh # 或手工 cp deploy/.env.example deploy/.env 后填写 DB_*
bash deploy/install.sh # 需 root（不需要 sudo）
bash deploy/install.sh # 需 root(不需要 sudo)
curl -fsS http://localhost:3000/health
curl -fsS http://localhost:3001/health
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/ # 期望 404（软件 API 端口无管理页面）
@@ -212,12 +212,12 @@ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3001/ # 期望 200
| 验收项 | 状态 |
|--|--|
| `deploy/install.sh` 脚本语法与幂等性 | ✅ `bash -n` 通过；重复执行会覆盖程序文件、保留 `.env` |
| 连接现有 MySQL 成功 | ✅ 已用真实实例验证（`/health` 200，`database.connected=true`） |
| TypeORM migration 执行成功 | ✅ 5 张业务表已创建并验证；v0.2.0 的 `AddModelStats1789460000000`（`models.stats TEXT`）已在真实库执行 |
| 连接现有 MySQL 成功 | ✅ 已用真实实例验证(`/health` 200, `database.connected=true`) |
| TypeORM migration 执行成功 | ✅ 5 张业务表已创建并验证；v0.2.0 的 `AddModelStats1789460000000`(`models.stats TEXT`)已在真实库执行 |
| 模型转换配置 | ✅ `deploy/.env.example` 写入 `ASSIMP_BIN` / `MODEL_CONVERT_FORMAT=glb|vrm` / `MODEL_CONVERT_PMX` / `MODEL_CONVERT_TIMEOUT_MS`；不合规输入转换失败 422 |
| `curl http://<host>:3000/health` 通过 | ✅ 直连后端端口已验证 |
| 软件 API 端口 `/` 返回 404 | ✅ `PORT=3000` 上 `/`、`/songs` 均 404（有意设计，无管理页面） |
| 管理端端口 `/` 返回 200 | ✅ `ADMIN_PORT=3001` 上 `/`、`/songs`、`/models` 均返回同一份 HTML（200） |
| 管理端端口 `/` 返回 200 | ✅ `ADMIN_PORT=3001` 上 `/`、`/songs`、`/models` 均返回同一份 HTML(200) |
| 前端深链接回退 | ✅ 未知静态路径回退到 `index.html`，未知 API 仍 404 |
| `ADMIN_PORT === PORT` 单端口兼容模式 | ✅ 只建一个 server，管理页面回到 API 端口，日志提示「未分端口」 |
| 端口非法在生产环境中止启动 | ✅ `validateEnv` 对非 1..65535 整数端口报 error |
@@ -225,11 +225,11 @@ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3001/ # 期望 200
| 不使用 Docker | ✅ 仓库内已无 Dockerfile / docker-compose / Docker 引用 |
| 不部署反向代理 | ✅ 仅交付 `deploy/proxy/` 文档，install.sh 中无任何反代安装动作 |
| 缺 `deploy/.env` 时由 `init-env.sh` 引导 | ✅ 交互逐项询问 8 个键；只改这 8 个键、保留模板注释、`chmod 600`、回读校验；安装目录已有 `.env` 时直接复用 |
| `init-env.sh --check` / 非交互不阻塞 | ✅ `test/init-env.spec.ts`（16 项）覆盖 `--check`、`-y`、EOF/超时立即退出、口令不加引号写盘 |
| `init-env.sh --check` / 非交互不阻塞 | ✅ `test/init-env.spec.ts`(16 项)覆盖 `--check`、`-y`、EOF/超时立即退出、口令不加引号写盘 |
| `HOST` 默认 `0.0.0.0` | ✅ `configuration.ts`、`deploy/.env.example`、`web-server/.env.example`、`install.sh`、`init-env.sh` 五处一致 |
> **环境限制说明**：本次执行环境**无 root 权限**，且**未安装 nginx**（按需求也不应安装）。
> 因此 `deploy/install.sh` 的服务注册链路（systemd / OpenRC / SysVinit / crontab）
> 因此 `deploy/install.sh` 的服务注册链路(systemd / OpenRC / SysVinit / crontab)
> 未能在本机实机跑通。已完成的等价验证：
> - 后端以 `node dist/main.js` 直连真实数据库启动，两个端口 `/health` 均 200
> - 管理端托管与 SPA 回退逐路径实测（`/`、`/songs`、`/models`、`/api/*`、未知路径），
@@ -238,7 +238,7 @@ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3001/ # 期望 200
> - `npm run migration:run` 走编译产物成功
> - 端到端冒烟 57 项全通过
> - `install.sh` / `uninstall.sh` / `ctl.sh` 通过 `bash -n` 语法校验
> - `init-env.sh` 通过 `bash -n`，并由 `test/init-env.spec.ts`（16 项）覆盖
> - `init-env.sh` 通过 `bash -n`，并由 `test/init-env.spec.ts`(16 项)覆盖
> 交互写回 / `--check` / 非交互 / 超时 / 幂等 / 口令不加引号
> - 反代文档中的占位符与后端实际行为逐条对照（两个端口、路径、上传上限、健康检查）
>
@@ -253,13 +253,13 @@ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3001/ # 期望 200
内容：`web-server/`（源码 + dist）、`admin/`（构建产物）、`deploy/`
（含 `proxy/` 反代文档）、`contracts/` 快照、`THIRD_PARTY.md`、`README.txt`。
打包脚本会对产物做硬校验：`src/**/*.ts` 必须都有对应 `dist/*.js`，
打包脚本会对产物做硬校验：`src/**/*.ts` 必须都有对应 `dist/*.js`,
关键文件（`dist/main.js`、`dist/storage/storage.module.js`、`admin/index.html`、
`deploy/proxy/*`）必须齐全，且不得含真实 `.env` 与 Docker/nginx 安装配置。
v0.2.0 起校验清单追加模型新模块：`dist/models/model-inspector.js`、
`dist/models/model-thumbnail.js`、`dist/models/vrm-writer.js`、
`dist/models/gltf-packer.js`、`dist/migrations/1789460000000-AddModelStats.js`。
> **发布包名变更**：`opendance-web-v0.1.0.tar.gz` -> **`opendance-web-v0.2.0.tar.gz`**
> （`scripts/package-release.sh` 的 `VERSION` 默认值已改为 `0.2.0`，
> **发布包名变更**: `opendance-web-v0.1.0.tar.gz` -> **`opendance-web-v0.2.0.tar.gz`**
> (`scripts/package-release.sh` 的 `VERSION` 默认值已改为 `0.2.0`,
> 与 `project.yaml` 的 `version: 0.2.0`、`web-server/package.json` 一致）。