MiFaZhan
503fe59fe7
- README：项目概览、快速开始、目录结构、重要提示 - 01 环境准备：硬件/系统/Docker 版本、镜像仓库、端口、防火墙、可选外部服务 - 02 配置说明：.env 必填与可选项、10 份应用配置逐项说明、启动前自检 - 03 启动与验证：首次初始化流程、状态检查、6 步验证清单、首次登录必做项 - 04 可选服务：挡板 onelink-mock、飞书 bot、自带 nginx（含 HTTPS）、组合启动 - 05 升级与备份：版本固定、升级回滚、备份脚本与恢复、日志清理、监控指标 - 06 故障排查：启动/功能/性能/网络四类共 20 个问题
6.1 KiB
配置说明
平台配置分两层：
| 层 | 位置 | 管什么 | 是否入库 |
|---|---|---|---|
| 部署层 | .env |
镜像仓库、口令、端口、外部服务地址 | 否 |
| 应用层 | config/<服务>/config.yaml |
业务参数、连接串、功能开关 | 否 |
两者都由 config.example/ 与 .env.example 复制而来，.gitignore 已排除。不要把自己的配置提交回仓库。
一、.env
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 会直接报错退出，不会用空值或弱口令启动。
生成强口令：
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。
二、应用配置
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 配置中即可。
三、配置自检
启动前先验证语法：
# 检查 compose 展开是否正确（不会启动容器）
docker compose config
# 只检查必填项是否齐全
docker compose config --quiet
配置文件语法错误（缩进、冒号）会导致服务启动后立刻退出，用日志定位：
docker compose logs --tail=50 admin-svr