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