docs: 部署手册改为平台部署，替换原文档站自身部署说明
原 /deploy/ 内容是文档站自身（VitePress/Node/nginx）的部署说明， 与用户所需的「IotLCM 平台部署手册」不符。 改为基于 iotlcm-public/iotlcm-deploy 部署仓的平台部署手册： - 部署概览：部署构成、三步流程、端口规划、关键约束 - 环境准备：硬件分档、系统与 Docker 版本、镜像仓库、防火墙、可选外部依赖 - 配置说明：.env 必填 8 项与可选 4 项、10 份应用配置逐项说明 - 启动与验证：首次初始化流程、7 步验证清单、首次登录必做项 - 可选服务：运营商挡板 onelink-mock、飞书 bot、反向代理（含 HTTPS） - 升级与备份：版本固定、升级回滚、备份与恢复、日志清理、监控指标 - 故障排查：启动/功能/性能/网络四类共 20 个问题 删除原 6 页（docker-nginx / path-prefix / static-hosting / local-dev / offline / faq），侧边栏同步改为「部署手册 + 运维」两组。
This commit is contained in:
Dai0814
@@ -0,0 +1,178 @@
|
||||
---
|
||||
title: 配置说明
|
||||
description: 部署环境变量与应用配置文件的填写方式
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# 配置说明
|
||||
|
||||
平台配置分两层：
|
||||
|
||||
| 层 | 位置 | 管什么 | 是否入库 |
|
||||
| --- | --- | --- | --- |
|
||||
| 部署层 | `.env` | 镜像仓库、口令、端口、外部服务地址 | 否 |
|
||||
| 应用层 | `config/<服务>/config.yaml` | 业务参数、连接串、功能开关 | 否 |
|
||||
|
||||
两者分别由 `.env.example` 与 `config.example/` 复制而来，`.gitignore` 已排除。**不要把自己的配置提交回仓库。**
|
||||
|
||||
## 一、环境变量
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
### 必填项
|
||||
|
||||
| 变量 | 说明 |
|
||||
| --- | --- |
|
||||
| `REGISTRY` | 镜像仓库地址，不含协议与末尾斜杠 |
|
||||
| `TAG` | 镜像标签，生产用具体版本号 |
|
||||
| `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
|
||||
```
|
||||
|
||||
### 可选项
|
||||
|
||||
| 变量 | 不填的影响 |
|
||||
| --- | --- |
|
||||
| `DIAGNOSIS_INTERNAL_TOKEN` | 控制台「智能诊断」不可用 |
|
||||
| `SMS_ACCESS_KEY_ID` / `SMS_ACCESS_KEY_SECRET` | 无法发送短信验证码 |
|
||||
| `FEISHU_APP_ID` / `FEISHU_APP_SECRET` / `FEISHU_CHAT_ID` | 不启动 bot 即可 |
|
||||
| `TDENGINE_*` | 历史流量查询不可用，主流程正常 |
|
||||
|
||||
### 端口
|
||||
|
||||
全部端口变量见 `.env.example`，均有默认值。改端口只改 `.env`。
|
||||
|
||||
## 二、应用配置
|
||||
|
||||
```bash
|
||||
cp -r config.example config
|
||||
```
|
||||
|
||||
得到 10 份：
|
||||
|
||||
```
|
||||
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` 注入。**口令类字段保持占位引用即可，不要写死明文。**
|
||||
|
||||
### 各服务配置要点
|
||||
|
||||
#### 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` | 与 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` |
|
||||
| `appCardRecognition.*` | 拍照识别卡号，不用改 `false` |
|
||||
| `upstream.onelinkMock.*` | 挡板联调配置，切真实运营商时 `enabled: false` |
|
||||
|
||||
#### sms（短信服务）
|
||||
|
||||
| 项 | 说明 |
|
||||
| --- | --- |
|
||||
| `serviceType` | `1`=阿里云，`2`=腾讯云 |
|
||||
| `accessKeyId` / `accessKeySecret` | 从 `.env` 注入 |
|
||||
| `signName` | 短信签名，需服务商审核通过 |
|
||||
|
||||
#### bot（飞书通知，可选）
|
||||
|
||||
`feishu.appId`、`appSecret`、`chatId` 全部从 `.env` 注入。
|
||||
|
||||
#### admin-ui（管理端 nginx）
|
||||
|
||||
`default.conf` 中 `/api/` 反代到 `admin-svr:8008`，`/upload/` 指向共享上传目录。一般无需修改。
|
||||
|
||||
#### nginx（对外入口，可选）
|
||||
|
||||
`iotlcm.conf` 按域名分三组 server：`api.*` → openapi，`admin.*` → 管理端与文档站，`app.*` → 小程序端。**把示例域名替换为实际域名。**
|
||||
|
||||
不用自带 nginx 时，把其中 `location` 段落复制到宿主机 nginx 配置即可。
|
||||
|
||||
## 三、配置自检
|
||||
|
||||
启动前验证：
|
||||
|
||||
```bash
|
||||
# 检查展开结果（不启动容器）
|
||||
docker compose config
|
||||
|
||||
# 只检查必填项是否齐全
|
||||
docker compose config --quiet
|
||||
```
|
||||
|
||||
配置语法错误会导致服务启动后立即退出，用日志定位：
|
||||
|
||||
```bash
|
||||
docker compose logs --tail=50 admin-svr
|
||||
```
|
||||
Reference in New Issue
Block a user