docs: 完善 README 文档

- 添加 docker-backup update 自动更新命令说明 - 添加详细的备份恢复指南，包含 SQL.gz 多种恢复方法 - 添加 keep_count 和 keep_days 清理策略详细说明 - 添加备份验证完整性方法 - 添加完整恢复到新服务器的示例 - 添加恢复注意事项和最佳实践 - 添加 3-2-1 备份策略说明 - 添加异地备份示例（rsync、rclone） - 添加更新日志 v1.2.0 - 添加贡献指南和相关链接
2025-12-25 17:26:16 +08:00
parent 0459136442
commit 8d1ad4a642
1 changed files with 313 additions and 11 deletions
--- 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    # 文件夹备份
+├── folders/
-└── mysql.sql.gz      # MySQL 数据库备份
+│   └── 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 容器备份
+感谢所有贡献者的支持和反馈！
 - 支持定时任务
 - 支持自动清理旧备份
 - 提供一键安装脚本