# 配置说明

平台配置分两层：

| 层 | 位置 | 管什么 | 是否入库 |
| --- | --- | --- | --- |
| 部署层 | `.env` | 镜像仓库、口令、端口、外部服务地址 | 否 |
| 应用层 | `config/<服务>/config.yaml` | 业务参数、连接串、功能开关 | 否 |

两者都由 `config.example/` 与 `.env.example` 复制而来，`.gitignore` 已排除。**不要把自己的配置提交回仓库。**

## 一、`.env`

```bash
cp .env.example .env
```

### 必填项

| 变量 | 说明 |
| --- | --- |
| `REGISTRY` | 镜像仓库地址，不含协议与末尾斜杠 |
| `TAG` | 镜像标签。生产请用具体版本号，不要用 `latest` |
| `MYSQL_ROOT_PASSWORD` | MySQL root 口令 |
| `MYSQL_APP_PASSWORD` | 应用账号 `u_iotlcm` 的口令，各服务用它连库 |
| `MYSQL_ADMIN_PASSWORD` | 平台 admin 账号的初始登录口令 |
| `REDIS_PASSWORD` | Redis 口令 |
| `RABBITMQ_PASSWORD` | RabbitMQ 口令 |
| `JWT_SIGNING_KEY` | JWT 签名密钥 |

以上任意一项未设置时，`docker compose` 会直接报错退出，不会用空值或弱口令启动。

生成强口令：

```bash
openssl rand -base64 24      # 用于各类密码
openssl rand -hex 32         # 用于 JWT_SIGNING_KEY
```

::: warning JWT_SIGNING_KEY 必须三处一致
`admin-svr`、`openapi`、`app-server` 共用同一个 `JWT_SIGNING_KEY`（都从 `.env` 读取）。不一致的表现是：能登录管理端，但调用外部 API 或小程序端提示未授权。

**更换此值会使已签发的全部登录态与接口令牌立即失效**，请在维护窗口操作。
:::

### 可选项

| 变量 | 不填的影响 |
| --- | --- |
| `DIAGNOSIS_INTERNAL_TOKEN` | 控制台「智能诊断」不可用 |
| `SMS_ACCESS_KEY_ID` / `SMS_ACCESS_KEY_SECRET` | 无法发送短信验证码 |
| `FEISHU_APP_ID` / `SECRET` / `CHAT_ID` | 不启动 bot 服务即可 |
| `TDENGINE_*` | 历史流量查询不可用，主流程正常 |

### 端口

全部端口变量见 `.env.example`，均有默认值。改端口只改 `.env`，不要改 `docker-compose.yml`。

## 二、应用配置

```bash
cp -r config.example 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
```

### 通用：环境变量占位

所有配置都支持 `${VAR}` 与 `${VAR:default}` 语法，由 compose 从 `.env` 注入。因此**口令类字段不必写进 yaml**，保持 `${MYSQL_APP_PASSWORD}` 这样的引用即可。

### 逐份说明

#### admin-svr（管理端后端）

| 项 | 说明 |
| --- | --- |
| `database.default.link` | 库连接串，默认已用 `${MYSQL_APP_PASSWORD}` 拼好 |
| `database.legacyCard.link` | 旧平台库，没有就留空 |
| `jwt.signingKey` | 保持 `${JWT_SIGNING_KEY}`，不要手写 |
| `warning.sms.enabled` | 不用短信改 `false` |
| `warning.wechat.*` | 不用微信订阅消息改 `false` 并留空 |
| `register.email.*` | 邮件验证码的 SMTP，不用则留空 |
| `tsdb.tdengine.dsn` | 不用时序库则留空 |
| `alipay.*` | 不用支付宝整段删除 |
| `upstream.appDiagnosisToken` | 与 `upstream-proxy` 的 `appDiagnosis.internalToken` 一致 |

#### openapi（对外 API）

| 项 | 说明 |
| --- | --- |
| `jwt.signingKey` | 与 admin-svr 一致 |
| `database.default.link` | 建议单独建只读账号与之隔离 |

#### worker-svr（异步任务）

| 项 | 说明 |
| --- | --- |
| `batch.inbound.upstreamRateLimit` | **运营商接口限流，必须按上游实际配额设置**。调太大会被运营商限流甚至封禁 |
| `rabbitmq.batchExecute.maxRetries` | 批次执行失败重试次数 |
| `tsdb.tdengine.dsn` | 不用时序库则留空 |

#### upstream-chan（运营商对接）

| 项 | 说明 |
| --- | --- |
| `registry.address` | Consul 地址，默认 `consul:8500` |
| `dependencies.sim_yd_mock_v5.url` | 挡板地址。对接真实运营商时删除本段 |
| `dependencies.token_refresh.skew_seconds` | 运营商 Token 提前刷新窗口 |

运营商通道本身（AppKey、AppSecret、接口地址）不在本文件配置，而是在平台「通道管理」中录入，存数据库。

#### upstream-proxy（通道缓存转发）

| 项 | 说明 |
| --- | --- |
| `appDiagnosis.internalToken` | 与 admin-svr 的 `upstream.appDiagnosisToken` 一致 |
| `gateway.batchTimeout` | 批量转发总预算上限，**worker 侧超时必须大于此值** |

#### app-server（小程序后端）

| 项 | 说明 |
| --- | --- |
| `jwt.signingKey` | 与 admin-svr 一致 |
| `payment.wechat.*` | 不用支付把 `enabled` 改 `false`；启用需把支付证书放入 `data/certs/` |
| `appCardRecognition.*` | 拍照识别卡号，不用改 `false` |
| `upstream.onelinkMock.*` | 挡板联调配置，对接真实运营商时 `enabled: false` |

#### sms（短信服务）

| 项 | 说明 |
| --- | --- |
| `serviceType` | `1`=阿里云，`2`=腾讯云 |
| `accessKeyId` / `accessKeySecret` | 从 `.env` 注入 |
| `signName` | 短信签名，需服务商审核通过 |
| `sceneDbDsn` | 场景模板库连接，默认已拼好 |

#### bot（飞书通知，可选）

| 项 | 说明 |
| --- | --- |
| `feishu.appId` / `appSecret` / `chatId` | 全部从 `.env` 注入 |

#### admin-ui（管理端 nginx）

`default.conf` 里 `/api/` 反代到 `admin-svr:8008`，`/upload/` 指向共享上传目录。一般无需修改。

#### nginx（对外入口，可选）

`iotlcm.conf` 按域名分三组 server：`api.*` → openapi，`admin.*` → 管理端 + 文档站，`app.*` → 小程序端。**把 `your-domain.example.com` 替换为实际域名。**

不使用自带 nginx 时，把其中的 `location` 段落复制到宿主机 nginx 配置中即可。

## 三、配置自检

启动前先验证语法：

```bash
# 检查 compose 展开是否正确（不会启动容器）
docker compose config

# 只检查必填项是否齐全
docker compose config --quiet
```

配置文件语法错误（缩进、冒号）会导致服务启动后立刻退出，用日志定位：

```bash
docker compose logs --tail=50 admin-svr
```