# 配置总表

> 当前总纲：V5.4.md
> 最后更新：2026-06-22
> 维护规则：任何配置路径、账号、密码、域名、端口或加载顺序变化，必须与 `README.md`、`V5.4.md` 和实际配置在同一提交中更新。

## 当前已知凭据

| 环境 | 服务 | 地址 | 账号 | 密码 | 状态 |
|---|---|---|---|---|---|
| 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`。

## MQTT 后端连接

- 生产变量：`QIPAI_MQTT_URL`、`QIPAI_MQTT_CLIENT_ID`、`QIPAI_MQTT_USERNAME`、`QIPAI_MQTT_PASSWORD`。
- 调优变量：`QIPAI_MQTT_RECONNECT_MS=3000`、`QIPAI_MQTT_CONNECT_TIMEOUT_MS=10000`、`QIPAI_MQTT_MAX_MESSAGE_BYTES=65536`。
- 生产账号固定建议为 `qipai_backend_prod`；真实密码只写 `/etc/qipai/qipai.secrets`，不得进入 Git、日志或错误响应。
- 用户名和密码必须同时配置；生产环境缺任一项时后端拒绝启动。
- 后端使用 MQTT 3.1（`protocolVersion: 3`）和 QoS 1，订阅 `/devicesend/+`、`/devicewill/+`，发布 `/deviceaccept/{DeviceID}`。
- `/app-api/ready`、`/admin-api/ready` 返回 `mqttConfigured`、`mqttConnected`、`mqttSubscriptionsReady`，只有真实连接并恢复订阅后后两项才为真。

## 微信支付 v3

- 运行变量：`QIPAI_WECHAT_PAY_CREDENTIALS`。
- 值为 JSON 对象，键与 `qipai_payment_configs.credential_ref` 对应；例如数据库保存 `env:WX_STORE` 时，JSON 可使用 `env:WX_STORE` 或 `WX_STORE` 作为键。
- 每项包含 `appId`、`merchantId`、`serialNo`、`privateKeyPem`、32 字节 `apiV3Key` 和按平台证书序列号索引的 `platformCertificates`。
- 真实值只写入 `/etc/qipai/qipai.secrets` 或本地 Git 忽略配置，权限 `600`；商户私钥、APIv3 Key 和平台证书正文不得进入 Git、日志或前端包。
- 支付配置 `settings` 可登记 `description`、`paymentNotifyUrl`、`refundNotifyUrl`；未登记时固定回调地址为 `https://api.txyundm.cn/app-api/pay/wechat/notify` 和 `https://api.txyundm.cn/app-api/pay/wechat/refund-notify`。
- 当前仓库未登记真实微信支付凭据；真实预支付、退款、通知和账单下载联调仍为外部阻塞。
- `profitShareReceivers` 可在每个微信凭据项中按 `receiver:*` 引用登记真实分账接收方账号；数据库仅保存该引用、SHA-256 和脱敏值。
- `QIPAI_PROFIT_SHARE_MOCK_ENABLED=true` 仅允许非生产测试环境启用；生产环境始终强制关闭。
- 收款账户只有 `authorizationStatus=AUTHORIZED` 时才能开启分账；接收方也必须单独标记授权。

## 团购与第三方平台

- 运行变量：`QIPAI_THIRD_PARTY_CREDENTIALS`。
- 值为 JSON 对象，键与 `qipai_third_party_configs.credential_ref` 对应；每项可包含 `webhookSecret` 和 `apiToken`。
- 数据库配置支持 `MANUAL`、`MOCK`、`API` 三种模式；生产接入真实平台时必须使用 `API`，测试环境可使用 `MOCK`。
- `credential_ref` 只允许 `env:` 引用；真实 Token 和回调密钥只写入 `/etc/qipai/qipai.secrets` 或 Git 忽略的本地配置。
- 直订回调当前统一使用 `X-Third-Party-Signature` HMAC-SHA256 入口；取得真实平台授权后由专用适配器按厂商协议替换，不得降低验签要求。
- 券码只保存 SHA-256 和脱敏显示值，不得写入日志、回调摘要或后台列表。

## 配置加载优先级

1. `/etc/qipai/qipai.secrets`
2. `/etc/qipai/qipai.conf`
3. 进程显式环境变量
4. Windows/WSL 本地 `.local.env` 或 `.env.*`
5. `.env.example`、部署模板与 README
6. 代码默认值

## 文件位置

完整位置表见根目录 `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：总纲升级为 V5.4；登记 WSL MySQL `root/root123` 与生产 MySQL `root/Da@Shuai!6y8c..XT`，增加 `/etc/qipai/mysql-client.cnf`、特殊字符处理和真实登录检测规则。
- 2026-06-22：M05-B 增加 `QIPAI_WECHAT_PAY_CREDENTIALS` 凭据映射、微信支付/退款回调地址和私钥证书隔离规则。
- 2026-06-22：M05-C 增加 `QIPAI_THIRD_PARTY_CREDENTIALS`、人工/Mock/API 模式、回调 HMAC 和券码哈希规则。
- 2026-06-22：M05-D 增加门店收款账户、`profitShareReceivers` 环境映射、分账授权状态和非生产 Mock 门禁。