chore: 并入 iotlcm-docs 历史到 docs/（原提交 947e22e）

docs/docs/deploy/configuration.md

@@ -0,0 +1,189 @@
+---
+title: 配置说明
+description: 部署配置的结构、默认值与修改方式
+outline: deep
+---
+
+# 配置说明
+
+平台配置分两层，**都随仓库分发、都带可用默认值**，无需复制或初始化即可启动：
+
+| 层 | 位置 | 管什么 |
+| --- | --- | --- |
+| 编排层 | `docker-compose.yml` | 镜像地址、端口、数据库/Redis/MQ 口令、容器编排 |
+| 应用层 | `config/<服务>/config.yaml` | 业务参数、连接串、功能开关 |
+
+::: warning 配置里是字面值，不是环境变量
+配置文件与编排文件里直接写的是具体值，**不使用 `${VAR}` 占位**。
+
+原因：GoFrame 不会展开配置文件中的 `${VAR}`（环境变量只用于覆盖配置键，不参与文件内文本替换），用占位符会导致连接串变成字面量 `${X}`，服务直接连不上库。
+
+代价是改口令要改多处，见下方「改口令的正确姿势」。
+:::
+
+## 编排层：`docker-compose.yml`
+
+### 镜像地址
+
+```yaml
+image: 'crpi-.../iotlcm/iotlcm:mysql-8.0'
+image: 'crpi-.../iotlcm/iotlcm:iotlcm-admin-svr-v1.0.4'
+```
+
+所有镜像（基础组件 + 业务服务）都在**同一个镜像仓库** `<Registry>/iotlcm/iotlcm` 下，靠 tag 区分：
+
+| tag 形式 | 示例 |
+| --- | --- |
+| 基础组件：`<组件>-<版本>` | `mysql-8.0`、`redis-7.2`、`nginx-1.30` |
+| 业务服务：`<服务>-<版本>` | `iotlcm-admin-svr-v1.0.4`、`iotlcm-app-server-v1.0.2` |
+
+改用自有仓库时，全局替换 Registry 前缀即可。
+
+### 默认口令
+
+| 变量 | 默认值 | 用途 |
+| --- | --- | --- |
+| `MYSQL_ROOT_PASSWORD` | 见文件 | MySQL root |
+| `MYSQL_DATABASE` | `db_iotlcm` | 库名 |
+| `RABBITMQ_DEFAULT_PASS` | 见文件 | RabbitMQ |
+| redis `--requirepass` | 见文件 | Redis |
+
+### 端口
+
+| 端口 | 服务 | 对外 |
+| --- | --- | --- |
+| 8008 | admin-svr | 经反向代理 |
+| 8009 | admin-ui | **浏览器直接访问这个** |
+| 8000 | openapi | 经反向代理 |
+| 8010 / 8018 | app-server / app-web | 经反向代理 |
+| 8019 | docs | 经反向代理 |
+| 8080 | onelink-mock | 仅联调 |
+| 3306 / 6379 / 5672 / 8500 | 基础组件 | 仅内网 |
+| 8110 / 8310 / 8510 | chan / proxy | 仅内网 |
+| 11190 / 11200 | sms | 仅内网 |
+
+改端口直接改 `docker-compose.yml` 中对应 `ports` 的冒号左侧。
+
+## 应用层：`config/`
+
+```
+config/
+├── admin-svr/config.yaml
+├── admin-ui/default.conf
+├── app-server/config.yaml
+├── bot/config.yaml
+├── nginx/iotlcm.conf
+├── openapi/config.yaml
+├── sms/config.yaml
+├── upstream-chan/config.yaml
+├── upstream-proxy/config.yaml
+└── worker-svr/config.yaml
+```
+
+### 各服务要点
+
+#### admin-svr（管理端后端）
+
+| 项 | 默认情况 |
+| --- | --- |
+| `database.default.link` | 指向 `mysql:3306`，口令与应用账号一致 |
+| `database.legacyCard.link` | 空，不使用旧平台库 |
+| `jwt.signingKey` | 已填固定密钥，需与 openapi、app-server 一致 |
+| `warning.sms.enabled` | `true`，未配短信服务商时建议改 `false` |
+| `warning.wechat.enabled` | `false` |
+| `register.email.*` | 空，不发邮件 |
+| `tsdb.tdengine.dsn` | 空，不启用时序库 |
+| `alipay.*` | 空，不启用支付 |
+| `upstream.appDiagnosisToken` | 已填，需与 upstream-proxy 一致 |
+
+#### openapi（对外 API）
+
+`jwt.signingKey` 与 admin-svr 一致；`database.default.link` 同库。建议另建只读账号用于生产。
+
+#### worker-svr（异步任务）
+
+| 项 | 说明 |
+| --- | --- |
+| `batch.inbound.upstreamConcurrency` | 默认 300，机器弱或上游配额小时调低 |
+| `batch.inbound.upstreamRateLimit` | 运营商限流，**必须按上游实际配额设置**，调大易被封禁 |
+| `tsdb.tdengine.dsn` | 空，不启用时序库 |
+
+#### upstream-chan（运营商对接）
+
+| 项 | 说明 |
+| --- | --- |
+| `registry.address` | `consul:8500` |
+| `dependencies.sim_yd_mock_v5.url` | 指向挡板 `http://onelink-mock:8080/v5/`，接真实运营商时删除本段 |
+
+运营商通道本身（AppKey、AppSecret、接口地址）在平台「通道管理」中录入，存数据库，不在本文件。
+
+#### upstream-proxy（通道缓存转发）
+
+| 项 | 说明 |
+| --- | --- |
+| `appDiagnosis.internalToken` | 与 admin-svr 的 `upstream.appDiagnosisToken` 一致 |
+| `gateway.batchTimeout` | 默认 20m，**worker 侧超时必须大于此值** |
+
+#### app-server（小程序后端）
+
+`jwt.signingKey` 同上；`payment.wechat.enabled` 默认 `false`；`appCardRecognition.enabled` 默认 `false`（拍照识别需自备视觉模型 API）。
+
+#### sms（短信服务）
+
+| 项 | 默认 |
+| --- | --- |
+| `serviceType` | `1`（阿里云） |
+| `accessKeyId` / `accessKeySecret` | 空，需自行填写 |
+| `signName` | `示例签名` |
+
+不填则无法发送验证码，其余功能正常。
+
+#### bot（飞书通知）
+
+`feishu.appId` / `appSecret` / `chatId` 均为空。不启动该容器即可。
+
+#### admin-ui / nginx
+
+`admin-ui/default.conf` 把 `/api/` 反代到 `admin-svr:8008`；`nginx/iotlcm.conf` 按域名分流，需把 `your-domain.example.com` 换成实际域名。
+
+## 改口令的正确姿势
+
+改数据库口令时，以下**三处必须同时改**，漏一处就起不来：
+
+| 位置 | 内容 |
+| --- | --- |
+| `docker-compose.yml` | `MYSQL_ROOT_PASSWORD`、redis `--requirepass`、`RABBITMQ_DEFAULT_PASS` |
+| `config/*/config.yaml` | 各服务的 `database.default.link`、`redis.default.pass`、`rabbitmq.dsn` |
+| `schema/04-users.sh`、`schema/05-reset-passwords.sh` | 脚本内的 `APP_PASSWORD` / `ADMIN_PASSWORD` / `ROOT_PASSWORD` |
+
+::: tip 一次性全局替换
+```bash
+OLD='原口令'
+NEW='新口令'
+
+# 编排 + 配置
+grep -rl "$OLD" docker-compose.yml config/ | xargs sed -i "s/$OLD/$NEW/g"
+# 初始化脚本
+grep -rl "$OLD" schema/ | xargs sed -i "s/$OLD/$NEW/g"
+```
+:::
+
+::: danger 口令不能含 @ : / 等字符
+连接串格式为 `mysql:用户:口令@tcp(主机:端口)/库`，口令里的 `@`、`:`、`/` 会被解析成分隔符，导致连接失败。用字母数字组合。
+:::
+
+## 配置自检
+
+```bash
+# 编排语法
+docker compose config --quiet
+
+# 看某个服务最终的配置展开
+docker compose config | sed -n '/admin-svr:/,/^  [a-z]/p'
+```
+
+配置语法错误会导致服务启动后立刻退出，看日志定位：
+
+```bash
+docker compose logs --tail=50 admin-svr
+```