opendance
60c182f1b2
依据 Gitea v1.27.3 modules/charset/escape_stream.go 的判定规则 （analyzeDetectResults：仅当左右相邻字符都不是非 ASCII 时才标记， 且 _common 表恒定生效），把说明文档中会被标记的全角标点 （，：；？！（） 等）改为半角，并保证成对括号宽度一致。 中文语境中的全角标点（左右均为中文）保持原样，不动代码与契约语义。 同时删除临时探针目录 _probe/（仅用于确认 Gitea 判定规则）。
65 lines
2.3 KiB
Markdown
65 lines
2.3 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` 形如
|
|
`<版本>-MariaDB-<发行版>`（版本字符串由实例返回）。
|
|
|
|
> **环境差异记录**：文档假设 MySQL 8.x；实际部署方提供的是 **MariaDB 10.5+** 兼容实例
|
|
> （具体版本由部署方确认，本项目不使用 MySQL 8 专有语法）。
|
|
> 已确认 TypeORM `mysql` 驱动（mysql2）兼容，SQL 限制在两者共同子集内，
|
|
> 详见 `contracts/database.md`。
|
|
|
|
## 结果
|
|
|
|
- 已连通 `<数据库主机>:3306/opendance`, `/health` 返回 200 且 `connected=true`。
|