docs: 部署文档

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

docs/05-升级与备份.md

@@ -0,0 +1,185 @@
+# 升级与备份
+
+## 版本固定
+
+生产环境**必须固定镜像标签**，不要用 `latest`。原因：
+
+- `latest` 会随仓库推送变化，同一份 compose 在不同时间拉到的镜像不同
+- 出问题无法确定运行的是哪个版本
+- 回滚时没有明确目标
+
+`.env` 中指定：
+
+```bash
+TAG=1.0.3
+```
+
+记录当前部署版本：
+
+```bash
+echo "$(date '+%Y-%m-%d %H:%M')  TAG=$(grep '^TAG=' .env | cut -d= -f2)" >> deploy-history.log
+```
+
+## 升级流程
+
+```bash
+# 1. 备份（见下节，不要跳过）
+./backup.sh
+
+# 2. 拉取新镜像
+vi .env                    # 修改 TAG
+docker compose pull
+
+# 3. 只更新发生变化的服务
+docker compose up -d
+
+# 4. 验证
+docker compose ps
+docker compose logs --tail=50 admin-svr
+```
+
+滚动更新单个服务，减少中断：
+
+```bash
+docker compose up -d --no-deps admin-svr
+```
+
+## 回滚
+
+```bash
+# 改回上一个版本
+vi .env                    # TAG 改回旧版本
+docker compose pull
+docker compose up -d
+```
+
+::: warning 数据库变更不可自动回滚
+若新版本包含数据库结构变更，回滚代码后数据库仍是新结构。升级前务必确认变更脚本可逆，或保留升级前的完整备份。
+:::
+
+## 什么情况下需要重新初始化数据库
+
+`schema/` 下的脚本**只在 `data/mysql` 为空时执行**。以下情况才需要清空重建：
+
+| 情况 | 是否需要 |
+| --- | --- |
+| 升级应用镜像 | 否 |
+| 修改 `config/` | 否，重启对应服务即可 |
+| 修改 `schema/` 脚本 | 是（会丢数据） |
+| 首次初始化失败 | 是 |
+
+清空重建：
+
+```bash
+docker compose down
+sudo rm -rf ./data/mysql
+docker compose up -d
+```
+
+::: danger 生产环境禁止清空 data/mysql
+生产数据必须通过数据库工具单独备份与迁移，不能依赖 schema 重建。上面这条命令仅用于首次部署阶段。
+:::
+
+## 备份
+
+### 全量备份脚本
+
+保存为 `backup.sh`（不要提交到仓库，`.gitignore` 已排除 `backup.sh` 外的脚本时请自行确认）：
+
+```bash
+#!/bin/bash
+set -euo pipefail
+cd "$(dirname "$0")"
+
+STAMP=$(date '+%Y%m%d-%H%M%S')
+DEST="./backups/${STAMP}"
+mkdir -p "$DEST"
+
+echo "[1/3] 导出数据库..."
+docker compose exec -T mysql sh -c \
+  'exec mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --single-transaction --routines --triggers --events db_iotlcm' \
+  | gzip > "${DEST}/db_iotlcm.sql.gz"
+
+echo "[2/3] 备份配置..."
+tar czf "${DEST}/config.tar.gz" config/ .env
+
+echo "[3/3] 备份上传文件（可选，量大可跳过）..."
+tar czf "${DEST}/upload.tar.gz" data/upload/ 2>/dev/null || echo "  上传目录为空，跳过"
+
+echo "完成：${DEST}"
+ls -lh "$DEST"
+```
+
+```bash
+chmod +x backup.sh
+./backup.sh
+```
+
+### 只备份数据库
+
+```bash
+docker compose exec -T mysql sh -c \
+  'exec mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --single-transaction db_iotlcm' \
+  | gzip > "db_iotlcm-$(date +%Y%m%d).sql.gz"
+```
+
+### 恢复数据库
+
+```bash
+gunzip -c db_iotlcm-20260101.sql.gz | \
+  docker compose exec -T mysql sh -c \
+  'exec mysql -uroot -p"$MYSQL_ROOT_PASSWORD" db_iotlcm'
+```
+
+### 备份内容清单
+
+| 内容 | 位置 | 重要性 |
+| --- | --- | --- |
+| 数据库 | MySQL 容器内 `db_iotlcm` | **最高**，业务数据全在这里 |
+| 配置 | `config/` + `.env` | 高，丢失需重新配置 |
+| 上传文件 | `data/upload/` | 中，附件与图片 |
+| Redis 数据 | `data/redis/` | 低，缓存可重建 |
+| RabbitMQ 队列 | `data/rabbitmq/` | 低，未消费消息会丢失 |
+| 日志 | `data/logs/` | 低，排障用 |
+
+### 备份策略建议
+
+| 场景 | 频率 | 保留 |
+| --- | --- | --- |
+| 生产 | 每日一次 + 升级前 | 30 天 |
+| 试用 | 有数据变更时 | 7 天 |
+
+备份文件应转存到异机或对象存储，不要与数据库放同一块盘。
+
+## 日志清理
+
+日志写在 `data/logs/` 下，按服务分目录，应用侧已配置按小时轮转（`{Y-m-d-H}.log`）。磁盘吃紧时清理旧日志：
+
+```bash
+# 删除 7 天前的日志
+find ./data/logs -name '*.log' -mtime +7 -delete
+```
+
+建议用系统 cron 定期执行：
+
+```bash
+# /etc/cron.d/iotlcm-logrotate
+0 3 * * * root find /path/to/iotlcm-deploy/data/logs -name '*.log' -mtime +7 -delete
+```
+
+## 监控
+
+基础组件自带的监控端点：
+
+| 服务 | 端点 |
+| --- | --- |
+| RabbitMQ | `http://<host>:15672`（管理界面） |
+| Consul | `http://<host>:8500/ui` |
+| MySQL | `docker compose exec mysql mysqladmin status` |
+
+建议对以下指标告警：
+
+- MySQL 连接数与磁盘使用率
+- Redis 内存使用率
+- RabbitMQ 队列积压数（`iotlcm.batch.execute`、`iotlcm.app.business`）
+- worker-svr 全量同步任务失败数