zijunchiang
9f08d316d0
需求：公开仓库的说明文档不应暴露开发/部署期信息，且 Gitea 会对 README.txt 报"含模棱两可的 Unicode 字符"。 敏感信息（全部替换为占位符或文档示例值）： - 真实数据库实例：DB_HOST=192.168.150.10 / DB_USER=dpendance / DB_NAME=dpendance → <数据库主机> / opendance_app / opendance（web-server/.env.example、 deploy/.env.example、contracts/database.md ×3 库、project.yaml、README.txt 的建库 SQL、tasks/001、tasks/002） - 内网网段 192.168.150.0/24 / 192.168.150.20 / 192.168.1.10 → RFC 5737 文档网段 192.0.2.0/24 等（含测试夹具，行为不变） - 真实 Gitea 域名 → https://<Gitea 地址>/<owner>/<repo>（systemd 单元、 Windows/Android README 的交叉链接） - 测试夹具里的真实口令字面量 → 虚构口令（仍覆盖特殊字符场景） - 保留 /opt/opendance、/var/lib/opendance 等产品默认安装路径（非敏感） README.txt 易混淆字符： - 全角拉丁字母（Ｉ/Ｋ 等）与全角 ASCII 标点（（），：；？）→ 半角 + 中文排版空格 - 正文里的乱码字节样例（模å…）→ 改为文字描述 - × → x，★ → * - 注意：代码/测试/契约里的全角「ＩＫ」是 MMD 真实骨骼名，**必须保留**， 已回滚误改（mmd-skeleton.ts、mmd-vmd.spec.ts、inspect-vmd.mjs、各契约） 验证：168 项单测通过（含 VMD 31 项，确认全角骨骼名未被破坏）。
64 lines
2.1 KiB
Markdown
64 lines
2.1 KiB
Markdown
# T-WEB-001 骨架 + 连接现有 MySQL
|
||
|
||
- **状态**：done
|
||
- **依赖**：无
|
||
|
||
## 目标
|
||
|
||
建立 NestJS 服务端骨架，并**连接部署方提供的现有 MySQL 实例**。本项目不部署、
|
||
不管理 MySQL。
|
||
|
||
## load
|
||
|
||
```
|
||
DSH.md
|
||
contracts/database.md
|
||
web-server/package.json
|
||
web-server/src/main.ts
|
||
web-server/src/app.module.ts
|
||
web-server/src/config/configuration.ts
|
||
web-server/src/db/data-source.ts
|
||
```
|
||
|
||
## 交付物
|
||
|
||
| 文件 | 说明 |
|
||
|---|---|
|
||
| `web-server/package.json` | NestJS 11 + TypeORM 0.3 + mysql2 依赖与脚本 |
|
||
| `web-server/src/main.ts` | 启动引导：环境校验、全局校验管道、CORS、静态资源、优雅关闭 |
|
||
| `web-server/src/app.module.ts` | 根模块，`TypeOrmModule.forRootAsync` 由 `AppConfig` 注入连接信息 |
|
||
| `web-server/src/config/configuration.ts` | 类型化配置层，唯一读取 `process.env` 的位置 |
|
||
| `web-server/src/config/config.module.ts` | 全局配置模块 |
|
||
| `web-server/src/db/data-source.ts` | TypeORM DataSource（CLI + 运行期共用），`synchronize: false` |
|
||
| `web-server/src/health/health.controller.ts` | `GET /health`，真实探测数据库连通性 |
|
||
| `web-server/.env.example` | 环境变量样例 |
|
||
|
||
## 关键实现
|
||
|
||
- `synchronize` 在代码中恒为 `false`，不读取环境变量覆盖，从结构上杜绝生产误开。
|
||
- `validateEnv()` 在启动时检查必填项，生产环境检测到 `DB_SYNCHRONIZE=true` 直接
|
||
以退出码 1 中止。
|
||
- `/health` 返回数据库版本、库名、待执行迁移数、存储目录、Assimp 可用性、契约版本；
|
||
数据库不可用时返回 **503**。
|
||
|
||
## 验收
|
||
|
||
```bash
|
||
cd web-server
|
||
cp .env.example .env # 填写 DB_* 后
|
||
npm install
|
||
npm run start:prod
|
||
curl -s http://localhost:3000/health
|
||
```
|
||
|
||
期望：`status=ok`、`database.connected=true`、`database.server` 形如
|
||
`10.11.19-MariaDB-...`。
|
||
|
||
> **环境差异记录**：文档假设 MySQL 8.x，实际部署实例为 **MariaDB 10.11.19**。
|
||
> 已确认 TypeORM `mysql` 驱动（mysql2）兼容，SQL 限制在两者共同子集内，
|
||
> 详见 `contracts/database.md`。
|
||
|
||
## 结果
|
||
|
||
- 已连通 `<数据库主机>:3306/opendance`，`/health` 返回 200 且 `connected=true`。
|