docs(V5.4): 固化MySQL双环境配置基线

docs/configuration.md

@@ -1,19 +1,65 @@
 # 配置总表
 
-> 当前总纲：V5.3.md
+> 当前总纲：V5.4.md
 > 最后更新：2026-06-18
-> 维护规则：任何配置路径、账号、密码、域名、端口或加载顺序变化，必须与 README.md、V5.3.md 和实际配置在同一提交中更新。
+> 维护规则：任何配置路径、账号、密码、域名、端口或加载顺序变化，必须与 `README.md`、`V5.4.md` 和实际配置在同一提交中更新。
 
 ## 当前已知凭据
 
 | 环境 | 服务 | 地址 | 账号 | 密码 | 状态 |
 |---|---|---|---|---|---|
-| WSL | EMQX Dashboard | http://127.0.0.1:18083 | admin | admin123 | 已安装并运行；仅按 Dashboard 账号认定 |
-| Windows | Gitea SSH | ssh://git@git.txyundm.cn:2222/panda/qipai.git | SSH Key | 免密 | 已配置 |
-| Ubuntu 生产 | MQTT | 101.42.38.246:1883 | 待配置 | 待配置 | 未登记正式凭据 |
-| Ubuntu 生产 | MySQL | 127.0.0.1:3306 | 待配置 | 待配置 | 未登记正式凭据 |
-| Ubuntu 生产 | JWT | 环境变量 `QIPAI_JWT_SECRET` | - | 待生成 | 必须至少 32 位，禁止使用开发默认值 |
-| Ubuntu 生产 | 微信小程序 | `QIPAI_WECHAT_APP_SECRETS` | AppID | 待配置 AppSecret | JSON 映射，仅放 `/etc/qipai/qipai.secrets` |
+| WSL | EMQX Dashboard | `http://127.0.0.1:18083` | `admin` | `admin123` | 已安装并运行；仅按 Dashboard 账号认定 |
+| WSL | MySQL | `127.0.0.1:3306` | `root` | `root123` | 已确认；开发、测试与迁移预演 |
+| Windows | Gitea SSH | `ssh://git@git.txyundm.cn:2222/panda/qipai.git` | SSH Key | 免密 | 已配置 |
+| Ubuntu 生产 | MQTT | `101.42.38.246:1883` | 待配置 | 待配置 | 未登记正式凭据 |
+| Ubuntu 生产 | MySQL | `127.0.0.1:3306` | `root` | `Da@Shuai!6y8c..XT` | 已确认；正式生产数据库 |
+
+## MySQL 固定配置
+
+### WSL 开发/测试
+
+```dotenv
+MYSQL_HOST=127.0.0.1
+MYSQL_PORT=3306
+MYSQL_USER=root
+MYSQL_PASSWORD=root123
+MYSQL_DATABASE=<以项目实际数据库名为准>
+```
+
+有效配置位置按实际仓库结构选择一处，并在 `docs/repository-map.md` 中确认：
+
+- `D:\qipai\backend\.env.development`
+- `D:\qipai\backend\.env.test`
+- `D:\qipai\config\dev\mysql.local.env`
+
+### Ubuntu 正式生产
+
+```dotenv
+MYSQL_HOST=127.0.0.1
+MYSQL_PORT=3306
+MYSQL_USER=root
+MYSQL_PASSWORD='Da@Shuai!6y8c..XT'
+MYSQL_DATABASE=<以项目实际数据库名为准>
+```
+
+- 主运行配置：`/etc/qipai/qipai.secrets`，权限 `600`。
+- 菜单脚本、健康检查、迁移和备份：`/etc/qipai/mysql-client.cnf`，权限 `600`。
+- 禁止使用 `mysql -uroot -p明文密码`，禁止在日志中输出密码。
+- 密码包含 `@`、`!` 和连续句点，脚本应使用分离变量或 `--defaults-extra-file`。
+- 确需 `DATABASE_URL` 时，密码应编码为 `Da%40Shuai%216y8c..XT`；数据库名仍以实际配置为准。
+- WSL 与生产必须隔离；Windows/WSL 不得直接对生产数据库执行迁移。
+
+## 环境检测要求
+
+`setup.sh`、Windows/WSL 环境检查和 Ubuntu 菜单式诊断必须分别输出：
+
+- `MYSQL_SERVICE`：服务与端口；
+- `MYSQL_AUTH`：使用登记账号密码执行 `SELECT 1`；
+- `MYSQL_SCHEMA`：目标数据库、字符集和时区；
+- `MYSQL_MIGRATION`：迁移表和当前版本；
+- `MYSQL_BACKUP`：备份目录可写、最近备份和校验结果。
+
+检测结果只能使用 `PASS/WARN/FAIL`，不得回显密码。只有五项全部通过，数据库环境才可标记 `DONE`。
 
 ## 配置加载优先级
 
@@ -26,12 +72,10 @@
 
 ## 文件位置
 
-完整位置表见根目录 README.md 的“配置文件位置”章节以及 V5.3.md 的“0.6 README、配置文件与明文凭据同步规则”。
+完整位置表见根目录 `README.md` 的“配置文件位置”章节，以及 `V5.4.md` 的“0.6 README、配置文件与明文凭据同步规则”。
 
 ## 变更记录
 
 - 2026-06-16：建立 V5.1 配置总表；登记 WSL EMQX Dashboard `admin/admin123`；固定 Windows、WSL 和 Ubuntu 配置路径。
-
-- 2026-06-18：总纲升级为 V5.3；配置值未变，新增持续开发执行游标与固定模块推进规则。
-
-- 2026-06-18：M02-B 新增 `QIPAI_JWT_SECRET`、`QIPAI_ACCESS_TOKEN_TTL_SECONDS`、`QIPAI_SESSION_TTL_SECONDS` 和 `QIPAI_WECHAT_APP_SECRETS`；真实值尚未提供，生产启动禁止使用开发 JWT 默认值。
+- 2026-06-18：总纲升级为 V5.3；增加持续开发执行游标与固定模块推进规则。
+- 2026-06-18：总纲升级为 V5.4；登记 WSL MySQL `root/root123` 与生产 MySQL `root/Da@Shuai!6y8c..XT`，增加 `/etc/qipai/mysql-client.cnf`、特殊字符处理和真实登录检测规则。