From 8d1ad4a642f2b2d55b61af80d4812c8866cbf43f Mon Sep 17 00:00:00 2001
From: Wang Defa <2-wangdefa@users.noreply.gitlab.bcde.io>
Date: Thu, 25 Dec 2025 17:26:16 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=20README=20=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 添加 docker-backup update 自动更新命令说明
- 添加详细的备份恢复指南，包含 SQL.gz 多种恢复方法
- 添加 keep_count 和 keep_days 清理策略详细说明
- 添加备份验证完整性方法
- 添加完整恢复到新服务器的示例
- 添加恢复注意事项和最佳实践
- 添加 3-2-1 备份策略说明
- 添加异地备份示例（rsync、rclone）
- 添加更新日志 v1.2.0
- 添加贡献指南和相关链接
---
 README.md | 324 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 313 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 92a2b30..aa8dc7e 100644
--- a/README.md
+++ b/README.md
@@ -76,6 +76,7 @@ backup:
   retention:
     enabled: true                           # 是否启用自动清理
     keep_days: 7                            # 保留最近 N 天的备份
+    # keep_count: 10                        # 或保留最近 N 个备份（与 keep_days 二选一）
 
 # 文件夹备份配置
 folders:
@@ -108,6 +109,22 @@ logging:
 
 ## 使用指南
 
+### 更新工具
+
+```bash
+# 更新到最新版本
+sudo docker-backup update
+
+# 显示帮助信息
+docker-backup help
+```
+
+更新功能会：
+- 自动从远程仓库下载最新版本
+- 备份当前版本（以防更新失败）
+- 同时更新 backup.sh 和 cleanup.sh
+- 更新失败时自动回滚
+
 ### 定时任务管理
 
 ```bash
@@ -140,6 +157,35 @@ docker-backup
 sudo journalctl -u docker-backup.service -f
 ```
 
+### 备份清理策略
+
+工具支持两种清理策略：
+
+#### 策略一：按天数清理（keep_days）
+
+保留最近 N 天的备份，删除更早的备份。
+
+```yaml
+backup:
+  retention:
+    enabled: true
+    keep_days: 7      # 保留最近 7 天的备份
+```
+
+#### 策略二：按数量清理（keep_count）
+
+保留最近 N 个备份文件，删除多余的旧备份。
+
+```yaml
+backup:
+  retention:
+    enabled: true
+    # keep_days: 7    # 注释掉 keep_days
+    keep_count: 10    # 只保留最近 10 个备份
+```
+
+**优先级**：如果同时配置了 `keep_days` 和 `keep_count`，将优先使用 `keep_days` 策略。
+
 ### 备份文件管理
 
 ```bash
@@ -204,8 +250,172 @@ backup-20250125-143022.tar.gz
 
 ```
 backup-20250125-143022.tar.gz
-├── folders.tar.gz    # 文件夹备份
-└── mysql.sql.gz      # MySQL 数据库备份
+├── folders/
+│   └── folders.tar.gz    # 文件夹备份
+└── mysql/
+    └── mysql.sql.gz      # MySQL 数据库备份
+```
+
+## 备份恢复
+
+### 1. 解压备份文件
+
+```bash
+# 进入备份目录
+cd /var/backups/docker-backup
+
+# 解压主备份文件
+tar -xzf backup-20250125-143022.tar.gz
+
+# 查看解压内容
+ls -lh
+# folders/  mysql/
+```
+
+### 2. 恢复文件夹
+
+```bash
+# 解压文件夹备份
+cd folders
+tar -xzf folders.tar.gz
+
+# 查看解压的文件
+ls -lh
+# 将显示备份时的完整路径，如：opt/gitea/
+
+# 方法一：直接恢复到原位置（会覆盖现有文件）
+sudo cp -r opt/gitea/* /opt/gitea/
+
+# 方法二：恢复到临时目录检查
+mkdir -p /tmp/restore
+cp -r opt/gitea /tmp/restore/
+# 检查无误后再复制到目标位置
+```
+
+### 3. 恢复 MySQL 数据库
+
+#### 方法一：恢复到 Docker 容器
+
+```bash
+# 解压 SQL 文件
+cd ../mysql
+gunzip -c mysql.sql.gz > mysql.sql
+
+# 恢复到 MySQL 容器
+docker exec -i mysql mysql -uroot -p'your_password' < mysql.sql
+
+# 或者恢复单个数据库
+docker exec -i mysql mysql -uroot -p'your_password' database_name < mysql.sql
+
+# 清理临时文件
+rm mysql.sql
+```
+
+#### 方法二：恢复指定数据库
+
+```bash
+# 先解压查看备份内容
+gunzip -c mysql.sql.gz | less
+
+# 恢复特定数据库
+gunzip -c mysql.sql.gz | docker exec -i mysql mysql -uroot -p'your_password' database_name
+```
+
+#### 方法三：分步恢复（推荐用于生产环境）
+
+```bash
+# 1. 先测试 SQL 文件是否完整
+gunzip -t mysql.sql.gz
+echo "测试通过: SQL 文件完整"
+
+# 2. 解压到临时位置
+gunzip -c mysql.sql.gz > /tmp/restore_mysql.sql
+
+# 3. 检查 SQL 文件内容
+head -n 50 /tmp/restore_mysql.sql
+tail -n 50 /tmp/restore_mysql.sql
+
+# 4. 停止应用（避免数据写入）
+# docker-compose down  # 根据实际情况
+
+# 5. 备份当前数据库（以防恢复失败）
+docker exec mysql mysqldump -uroot -p'your_password' --all-databases | gzip > /tmp/current_backup.sql.gz
+
+# 6. 执行恢复
+docker exec -i mysql mysql -uroot -p'your_password' < /tmp/restore_mysql.sql
+
+# 7. 验证恢复结果
+docker exec mysql mysql -uroot -p'your_password' -e "SHOW DATABASES;"
+
+# 8. 重启应用
+# docker-compose up -d  # 根据实际情况
+
+# 9. 清理临时文件
+rm /tmp/restore_mysql.sql
+```
+
+### 4. 完整恢复示例
+
+假设需要完整恢复到新服务器：
+
+```bash
+# 1. 复制备份文件到新服务器
+scp backup-20250125-143022.tar.gz root@new-server:/tmp/
+
+# 2. 在新服务器上解压
+cd /tmp
+tar -xzf backup-20250125-143022.tar.gz
+
+# 3. 恢复文件夹
+cd folders
+tar -xzf folders.tar.gz
+sudo cp -r opt/gitea /opt/
+
+# 4. 启动 MySQL 容器（如果还没启动）
+docker-compose up -d mysql
+
+# 5. 等待 MySQL 启动完成
+sleep 10
+
+# 6. 恢复数据库
+cd ../mysql
+gunzip -c mysql.sql.gz | docker exec -i mysql mysql -uroot -p'your_password'
+
+# 7. 验证恢复
+docker exec mysql mysql -uroot -p'your_password' -e "SHOW DATABASES;"
+ls -lh /opt/gitea/
+
+# 8. 启动所有服务
+docker-compose up -d
+```
+
+### 5. 恢复注意事项
+
+⚠️ **重要提示**：
+
+1. **备份当前数据**：恢复前务必备份当前数据
+2. **停止应用**：恢复数据库时建议停止应用，避免数据冲突
+3. **测试恢复**：在生产环境恢复前，建议先在测试环境验证
+4. **权限问题**：恢复文件后检查文件所有者和权限
+5. **版本兼容**：确保 MySQL 版本兼容（备份和恢复的版本）
+6. **磁盘空间**：确保有足够的磁盘空间进行解压和恢复
+
+### 6. 验证备份完整性
+
+```bash
+# 测试 tar.gz 文件完整性
+tar -tzf backup-20250125-143022.tar.gz > /dev/null
+echo "主备份文件完整"
+
+# 测试 SQL 压缩文件完整性
+cd mysql
+gunzip -t mysql.sql.gz
+echo "SQL 备份文件完整"
+
+# 测试文件夹备份完整性
+cd ../folders
+tar -tzf folders.tar.gz > /dev/null
+echo "文件夹备份完整"
 ```
 
 ## 故障排查
@@ -306,25 +516,117 @@ docker-backup/
 
 4. **异地备份**: 建议将备份文件同步到远程服务器或云存储。
 
+5. **监控备份**: 配置通知功能，及时了解备份状态。
+
+## 最佳实践
+
+### 1. 3-2-1 备份策略
+
+推荐采用 3-2-1 备份策略：
+- **3** 份数据副本（1 份原始数据 + 2 份备份）
+- **2** 种不同的存储介质（如本地硬盘 + 云存储）
+- **1** 份异地备份
+
+### 2. 定期验证备份
+
+建议每月进行一次完整的恢复测试：
+
+```bash
+# 1. 创建测试环境
+mkdir -p /tmp/backup-test
+
+# 2. 解压最新备份
+cd /tmp/backup-test
+tar -xzf /var/backups/docker-backup/backup-latest.tar.gz
+
+# 3. 验证文件完整性
+cd folders && tar -tzf folders.tar.gz
+cd ../mysql && gunzip -t mysql.sql.gz
+
+# 4. 测试数据库恢复（可选）
+# 在测试容器中恢复并验证
+```
+
+### 3. 备份前的准备
+
+- 确保有足够的磁盘空间（至少是数据大小的 2 倍）
+- 在数据库负载较低时执行备份
+- 记录备份配置变更历史
+
+### 4. 异地备份示例
+
+使用 rsync 同步到远程服务器：
+
+```bash
+# 添加到定时任务或备份后钩子
+rsync -avz --delete \
+  /var/backups/docker-backup/ \
+  user@remote-server:/backups/
+```
+
+使用 rclone 同步到云存储：
+
+```bash
+# 安装 rclone
+# 配置云存储（如 S3、Google Drive 等）
+rclone config
+
+# 同步备份到云存储
+rclone sync /var/backups/docker-backup/ remote:backup/
+```
+
+## 更新日志
+
+### v1.2.0 (2025-12-25)
+
+- ✨ 新增：支持 `keep_count` 按数量保留备份策略
+- ✨ 新增：`docker-backup update` 自动更新功能
+- ✨ 新增：`docker-backup help` 帮助命令
+- 🐛 修复：清理策略未正确执行的问题
+- 📝 文档：添加详细的备份恢复指南
+
+### v1.1.0 (2025-01-25)
+
+- 📝 文档：完善使用说明和故障排查
+- 🔧 优化：改进日志输出格式
+
+### v1.0.0 (2025-01-25)
+
+- 🎉 初始版本发布
+- ✅ 支持文件夹备份
+- ✅ 支持 MySQL 容器备份
+- ✅ 支持定时任务
+- ✅ 支持自动清理旧备份
+- ✅ 提供一键安装脚本
+
 ## 贡献
 
 欢迎提交 Issue 和 Pull Request！
 
+### 贡献指南
+
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
+3. 提交更改 (`git commit -m 'feat: 添加某个功能'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 提交 Pull Request
+
+请遵循项目的代码规范和提交信息格式（参考 Conventional Commits）。
+
 ## 许可证
 
 MIT License
 
 ## 作者
 
-Your Name
+wangdefa
 
-## 更新日志
+## 相关链接
 
-### v1.0.0 (2025-01-25)
+- **项目主页**: https://gitea.bcde.io/wangdefa/docker-backup
+- **问题反馈**: https://gitea.bcde.io/wangdefa/docker-backup/issues
+- **文档**: https://gitea.bcde.io/wangdefa/docker-backup/wiki
 
-- 初始版本发布
-- 支持文件夹备份
-- 支持 MySQL 容器备份
-- 支持定时任务
-- 支持自动清理旧备份
-- 提供一键安装脚本
+## 致谢
+
+感谢所有贡献者的支持和反馈！
\ No newline at end of file