docs: 部署文档

- README：项目概览、快速开始、目录结构、重要提示
- 01 环境准备：硬件/系统/Docker 版本、镜像仓库、端口、防火墙、可选外部服务
- 02 配置说明：.env 必填与可选项、10 份应用配置逐项说明、启动前自检
- 03 启动与验证：首次初始化流程、状态检查、6 步验证清单、首次登录必做项
- 04 可选服务：挡板 onelink-mock、飞书 bot、自带 nginx（含 HTTPS）、组合启动
- 05 升级与备份：版本固定、升级回滚、备份脚本与恢复、日志清理、监控指标
- 06 故障排查：启动/功能/性能/网络四类共 20 个问题

docs/01-环境准备.md

@@ -0,0 +1,124 @@
+# 环境准备
+
+## 硬件要求
+
+按数据规模选择配置：
+
+| 场景 | CPU | 内存 | 磁盘 | 说明 |
+| --- | --- | --- | --- | --- |
+| 试用 / 演示 | 2 核 | 4 GB | 40 GB | 少量卡片，关闭定时任务 |
+| 生产（中小规模） | 4 核 | 8 GB | 200 GB | 万级卡片，开启全量同步 |
+| 生产（大规模） | 8 核+ | 16 GB+ | 500 GB+ | 十万级卡片，建议数据库独立部署 |
+
+磁盘估算：MySQL 数据约为卡片数的 1~2 KB/张；日志按每日同步任务量增长，建议单独挂载并配置轮转。
+
+内存分配参考（生产 8 GB 场景）：
+
+| 服务 | 大致占用 |
+| --- | --- |
+| MySQL | 1~2 GB |
+| Redis | 200~500 MB |
+| RabbitMQ | 300~500 MB |
+| worker-svr | 500 MB~1 GB（与并发同步的卡片数相关） |
+| 其余业务服务 | 每个 100~200 MB |
+
+## 系统要求
+
+| 项 | 要求 |
+| --- | --- |
+| 操作系统 | Linux x86_64（CentOS 7+ / Ubuntu 20.04+ / Debian 11+） |
+| 内核 | 3.10 以上 |
+| 文件系统 | ext4 / xfs |
+| 时区 | 建议设为 `Asia/Shanghai`，与 `.env` 中的 `TZ` 保持一致 |
+
+## Docker 要求
+
+| 组件 | 最低版本 | 说明 |
+| --- | --- | --- |
+| Docker Engine | 20.10 | 需要支持 `healthcheck` 与 `profiles` |
+| Docker Compose | v2.0（插件版） | `docker compose` 而非 `docker-compose` |
+
+验证：
+
+```bash
+docker version
+docker compose version
+```
+
+`docker compose version` 输出的版本号需 ≥ v2.0。若只有 `docker-compose`（v1），请升级到 Compose V2 插件。
+
+## 镜像仓库
+
+平台镜像由官方镜像仓库分发，需要：
+
+1. 能访问镜像仓库地址（内网仓库需先配置网络或代理）
+2. 具备拉取权限（私有仓库需先登录）
+
+```bash
+docker login <你的镜像仓库地址>
+```
+
+`.env` 中的 `REGISTRY` 填写仓库地址（不含 `https://` 与末尾斜杠）：
+
+```bash
+REGISTRY=registry.example.com
+```
+
+基础组件从 `<REGISTRY>/library/` 拉取（mysql、redis、rabbitmq、consul、nginx），业务镜像从 `<REGISTRY>/iotlcm/` 拉取。
+
+## 端口
+
+默认占用的宿主机端口：
+
+| 端口 | 服务 | 对外 |
+| --- | --- | --- |
+| 8000 | openapi | 需经反向代理 |
+| 8008 | admin-svr | 需经反向代理 |
+| 8009 | admin-ui | 需经反向代理 |
+| 8010 | app-server | 需经反向代理 |
+| 8018 | app-web | 需经反向代理 |
+| 8019 | docs | 需经反向代理 |
+| 8080 | onelink-mock | 仅联调时启用 |
+| 3306 | MySQL | 建议仅内网 |
+| 6379 | Redis | 建议仅内网 |
+| 5672 / 15672 | RabbitMQ | 建议仅内网 |
+| 8500 | Consul | 建议仅内网 |
+| 8110 / 8310 | upstream-chan | 建议仅内网 |
+| 8510 | upstream-proxy | 建议仅内网 |
+| 11190 / 11200 | sms | 建议仅内网 |
+| 80 | nginx | 启用 with-nginx 时 |
+
+端口冲突时在 `.env` 中修改对应变量即可，不要直接改 `docker-compose.yml`。
+
+## 防火墙
+
+仅需对外开放反向代理端口（默认 80/443）。其余服务端口应限制为内网访问：
+
+```bash
+# 示例：firewalld 仅放行 80/443
+firewall-cmd --permanent --add-service=http
+firewall-cmd --permanent --add-service=https
+firewall-cmd --reload
+```
+
+## 依赖外部服务（可选）
+
+| 服务 | 用途 | 是否必需 |
+| --- | --- | --- |
+| TDengine 3.x | 存流量历史数据 | 可选。不配置则历史流量查询不可用 |
+| 短信服务商 | 发送验证码 | 可选。不配置则无法发送短信 |
+| 微信支付 | 在线支付 | 可选。不配置则支付功能不可用 |
+| 飞书 | 运维通知 | 可选。不配置则不启动 bot |
+
+TDengine 需开启 WebSocket 接口（默认 6041 端口），在 `.env` 中配置：
+
+```bash
+TDENGINE_HOST=tdengine.example.com
+TDENGINE_PORT=6041
+TDENGINE_USER=root
+TDENGINE_PASSWORD=
+TDENGINE_DAILY_DB=iotlcm_daily
+TDENGINE_MONTHLY_DB=iotlcm_monthly
+```
+
+不使用时全部留空即可，主流程不受影响。