wangdefa/docker-backup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 实现 Docker 备份系统，支持远程一键安装

Browse Source 
实现功能：
- 文件夹和 MySQL 容器数据库备份
- tar.gz 压缩和自动清理旧备份
- systemd 定时任务集成
- 远程一键安装脚本（通过 Gitea 仓库）
- 完整的 llmdoc 文档系统

安装方式：
bash <(curl -sL https://gitea.bcde.io/wangdefa/docker-backup/raw/branch/main/install.sh)

配置文件位置：/etc/docker-backup/config.yml
命令：docker-backup, docker-backup-cleanup
This commit is contained in:
Wang Defa
2025-12-25 15:02:07 +08:00
commit 4d00283654
19 changed files with 2553 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
llmdoc/architecture/backup-engine-architecture.md Normal file
View File

@@ -0,0 +1,67 @@
# 备份执行引擎架构
## 1. 身份识别
- **目的**：一个高度可配置的 Docker 备份解决方案，支持文件夹和 MySQL 数据库的备份
- **核心功能**：自动备份、日志记录、临时文件管理和备份保留策略
## 2. 核心组件
- `bin/backup.sh`（主备份脚本）:
- 负责协调整个备份流程
- 主要功能包括依赖检查、配置加载、文件备份、数据库备份和清理
## 3. 执行流程（LLM 检索图）
备份执行流程遵循以下关键步骤：
1. **依赖检查**：`check_dependencies()`
- 验证所需工具 (yq, tar, gzip, docker)
- 如缺少依赖，脚本将终止执行
2. **配置加载**：`load_config()`
- 读取 `/etc/docker-backup/config.yml`
- 配置备份输出目录、前缀和保留策略
3. **临时目录准备**
- 使用 `mktemp` 创建唯一临时目录
- 注册清理 `trap`，确保资源释放
4. **文件夹备份**：`backup_folders()`
- 支持多源目录备份
- 使用 `tar` 打包
- 可配置排除规则
5. **数据库备份**：`backup_mysql()`
- 通过 `docker exec` 调用 `mysqldump`
- 支持全库或指定库备份
- 使用 `gzip` 压缩
6. **备份合并**：`merge_backups()`
- 合并文件夹和数据库备份
- 生成时间戳文件名
- 输出单个 `.tar.gz` 文件
7. **备份清理**：`cleanup_old_backups()`
- 按配置的保留天数清理旧备份
## 4. 设计原理
- **模块化**：每个功能封装为独立函数
- **可配置性**：通过 YAML 文件灵活配置
- **错误处理**：严格的错误捕获和日志记录
- **安全性**：最小权限原则，临时文件自动清理
## 5. 关键配置点
- 备份源目录
- 数据库备份范围
- 输出目录和文件前缀
- 日志配置
- 备份保留策略
## 6. 局限性和注意事项
- 依赖外部工具（yq, docker, tar, gzip）
- 需要正确配置 MySQL 容器访问权限
- 备份过程中需要足够的临时存储空间

35
llmdoc/architecture/configuration-system.md Normal file
View File

@@ -0,0 +1,35 @@
# 配置系统架构
## 1. 身份识别
- **定义**：一个灵活、层次清晰的 YAML 配置系统，支持细粒度的备份策略定制
- **目的**：通过声明式配置，控制 Docker 备份的各个方面
## 2. 核心组件
- `/etc/docker-backup/config.yml`: 系统配置文件（安装时从 `config/backup.yml.example` 创建）
- `bin/backup.sh`: 读取并解析配置的主脚本
- `yq`: 用于 YAML 配置解析的关键工具
## 3. 执行流程（LLM 检索图）
1. **配置加载**：
- 读取 `/etc/docker-backup/config.yml`
- 使用 `yq` 解析配置项
2. **依赖性验证**：
- 检查必要工具（`yq`, `tar`, `docker`）
- 验证配置文件有效性
- 校验备份源和容器可用性
3. **配置解析**：
- 提取备份基础配置 (`backup`)
- 处理文件夹备份设置 (`folders`)
- 解析 MySQL 备份参数 (`mysql`)
- 配置日志和通知 (`logging`, `notification`)
## 4. 设计原理
- **灵活性**：通过 YAML 配置提供高度可定制的备份策略
- **最小侵入**：仅依赖常见的 Unix 工具链
- **安全性**：配置项有严格的验证机制

45
llmdoc/architecture/installation-architecture.md Normal file
View File

@@ -0,0 +1,45 @@
# Docker Backup 安装架构
## 1. 身份与目的
- **目标**：自动化 Docker 容器和卷的备份部署
- **关键功能**：依赖检测、文件部署、服务配置、定时任务管理
## 2. 核心组件
- `install.sh`（主安装脚本）：整个安装流程的协调者，支持远程下载和部署
- 动态生成的 systemd 服务文件（不再使用模板）
## 3. 执行流程图（LLM检索映射）
### 3.1 环境准备阶段
- **权限验证**：`check_root()`，确保以 root 权限运行
- **操作系统检测**：`detect_os()`，确定系统类型和版本
### 3.2 依赖安装阶段
- **工具检测**：`install_yq()`，安装 YAML 解析工具
- **依赖检查**：`install_dependencies()`
- 检测并安装：tar, gzip, docker, find
- 根据操作系统使用不同的包管理器 (apt/yum/dnf)
### 3.3 文件部署阶段
- **远程下载**：`deploy_files()`
- 从 Gitea 仓库下载 `backup.sh` 和 `cleanup.sh`
- 安装到 `/usr/local/bin/docker-backup` 和 `/usr/local/bin/docker-backup-cleanup`
- 设置可执行权限
- 下载配置文件模板到 `/etc/docker-backup/config.yml`
### 3.4 服务配置阶段
- **Systemd 服务生成**：`setup_systemd()`
- 动态生成 `.service` 文件到 `/etc/systemd/system/`
- 动态生成 `.timer` 文件，定义执行计划
- **服务启用**：`enable_service()`
- 重新加载 systemd 守护进程
- 启用并启动 systemd timer
## 4. 设计原则
- **模块化**：每个函数职责单一，便于维护
- **跨平台兼容**：支持主流 Linux 发行版
- **安全性**：要求 root 权限，预防权限问题
- **灵活性**：支持自定义安装目录、服务名称和执行计划

37
llmdoc/architecture/systemd-integration.md Normal file
View File

@@ -0,0 +1,37 @@
# Systemd 集成架构
## 1. 身份与目的
- **定义**：Docker 备份项目的 Systemd 集成层
- **目的**：通过 Systemd 单元提供可配置、高效的自动备份机制
## 2. 核心组件
- `systemd/docker-backup.service.template`: Service 单元模板
- `systemd/docker-backup.timer.template`: Timer 单元模板
## 3. 执行流程（LLM 检索路径）
### 定时触发
1. **Timer 激活**：`docker-backup.timer` 根据配置的 `OnCalendar` 触发
2. **服务启动**：触发 `docker-backup.service`
3. **备份脚本执行**：运行 `bin/backup.sh`
### 依赖关系
```
docker-backup.timer
└── Requires: docker-backup.service
└── Requires: docker.service
```
## 4. 资源管理策略
- **CPU 管理**：`Nice=19` - 最低优先级
- **IO 管理**：`IOSchedulingClass=idle` - 仅在系统空闲时执行
- **超时控制**：`TimeoutStartSec=1800` - 30分钟超时保护
## 5. 设计原理
- **模块化**：通过模板实现灵活配置
- **动态替换**：使用 `__INSTALL_DIR__` 和 `__SCHEDULE__` 变量
- **日志集成**：通过 systemd 日志系统（journald）收集日志

81
llmdoc/guides/how-to-configure-backups.md Normal file
View File

@@ -0,0 +1,81 @@
# 如何配置备份
## 准备工作
安装后，配置文件位于 `/etc/docker-backup/config.yml`。
1. **编辑配置文件**
```bash
sudo vi /etc/docker-backup/config.yml
```
2. **基础备份配置**
编辑 `backup` 区块：
```yaml
backup:
output_dir: "/path/to/backup/destination" # 指定备份存储位置
prefix: "mybackup" # 可选，自定义备份文件前缀
retention:
enabled: true # 启用自动清理
keep_days: 7 # 保留最近 7 天备份
```
3. **配置文件夹备份**
```yaml
folders:
enabled: true
sources:
- "/var/lib/docker/volumes"
- "/opt/important/data"
excludes:
- "*/logs" # 排除日志目录
- "*/.git" # 排除 Git 仓库
```
4. **配置 MySQL 备份**
```yaml
mysql:
enabled: true
container_name: "mysql_container"
username: "root"
password: "your_password"
databases:
- "database1" # 指定具体数据库
# 或使用 "all" 备份所有数据库
```
5. **日志和通知**
```yaml
logging:
enabled: true
log_file: "/var/log/docker-backup.log"
level: "INFO"
notification:
enabled: true
method: "webhook"
webhook_url: "https://example.com/webhook"
```
## 验证配置
运行以下命令测试备份功能：
```bash
docker-backup
```
查看配置是否生效：
```bash
# 查看备份日志
sudo journalctl -u docker-backup.service -f
# 查看生成的备份文件
docker-backup-cleanup --list
```
## 常见问题
- 确保所有路径正确
- 检查 MySQL 容器名称和凭据
- 权限问题：确保脚本有足够权限访问备份源
- 配置文件权限：`sudo chmod 600 /etc/docker-backup/config.yml`

101
llmdoc/guides/how-to-install.md Normal file
View File

@@ -0,0 +1,101 @@
# 如何安装 Docker Backup
## 1. 系统要求
- **操作系统**：Linux（推荐 Ubuntu, Debian, CentOS, RHEL, Fedora）
- **权限**：需要 root/sudo 权限
- **预安装依赖**：
- Docker
- Bash (4.0+)
- 网络工具（wget 或 curl）
## 2. 一键远程安装
### 2.1 执行安装命令
使用以下命令直接从远程仓库安装：
```bash
bash <(curl -sL https://gitea.bcde.io/wangdefa/docker-backup/raw/branch/main/install.sh)
```
安装脚本会自动完成：
- 检测操作系统类型
- 安装依赖工具（yq 等）
- 从远程仓库下载脚本文件
- 安装到系统目录（`/usr/local/bin`、`/etc/docker-backup`）
- 创建配置文件模板
- 配置并启动 systemd 服务
- 启动定时任务
### 2.2 配置备份
1. 编辑配置文件
```bash
sudo vi /etc/docker-backup/config.yml
```
2. 配置关键参数：
- `output_dir`：备份文件存储位置
- `folders.sources`：需要备份的文件夹列表
- `mysql.container_name`：MySQL 容器名称
- `retention.keep_days`：备份保留天数
## 3. 高级安装选项
### 3.1 自定义服务名称
```bash
# 为服务指定自定义名称
SERVICE_NAME=my-docker-backup bash <(curl -sL https://gitea.bcde.io/wangdefa/docker-backup/raw/branch/main/install.sh)
```
### 3.2 自定义执行计划
```bash
# 每天早上 6 点执行备份
SCHEDULE="*-*-* 06:00:00" bash <(curl -sL https://gitea.bcde.io/wangdefa/docker-backup/raw/branch/main/install.sh)
# 支持的计划格式：
# "daily" 每天
# "*-*-* 02:00:00" 每天凌晨 2 点
# "Mon *-*-* 02:00:00" 每周一凌晨 2 点
# "*-*-01 02:00:00" 每月 1 号
# "hourly" 每小时
```
## 4. 验证安装
1. 检查服务状态
```bash
systemctl status docker-backup.timer
```
2. 手动测试备份
```bash
docker-backup
```
3. 查看备份文件
```bash
docker-backup-cleanup --list
```
## 5. 卸载
```bash
# 卸载 Docker Backup
bash <(curl -sL https://gitea.bcde.io/wangdefa/docker-backup/raw/branch/main/install.sh) --uninstall
```
## 6. 常见问题
- **权限问题**：确保使用 `sudo` 运行脚本
- **依赖缺失**：脚本会自动尝试安装依赖
- **配置错误**：仔细检查 `backup.yml` 配置
## 7. 建议
- 首次安装后，建议立即测试备份功能
- 定期检查备份日志：`journalctl -u docker-backup.service`
- 根据实际需求调整备份策略

60
llmdoc/guides/how-to-manage-systemd-service.md Normal file
View File

@@ -0,0 +1,60 @@
# 如何管理 Docker 备份 Systemd 服务
## 1. 服务状态检查
1. **查看服务状态**
```bash
systemctl status docker-backup.service
```
2. **查看 Timer 状态**
```bash
systemctl status docker-backup.timer
```
## 2. 启动和停止服务
1. **启动服务**
```bash
systemctl start docker-backup.service
systemctl enable docker-backup.timer # 开机自启
```
2. **停止服务**
```bash
systemctl stop docker-backup.service
systemctl disable docker-backup.timer # 取消开机自启
```
## 3. 修改定时计划
1. **编辑 Timer 配置**
使用 `systemctl edit docker-backup.timer` 或直接编辑 `/etc/systemd/system/docker-backup.timer`
2. **常见调度示例**
- 每天凌晨 2 点：`OnCalendar=*-*-* 02:00:00`
- 每周一凌晨 2 点：`OnCalendar=Mon *-*-* 02:00:00`
- 每月 1 号凌晨 2 点：`OnCalendar=*-*-01 02:00:00`
3. **重载配置**
```bash
systemctl daemon-reload
systemctl restart docker-backup.timer
```
## 4. 查看服务日志
1. **查看最近日志**
```bash
journalctl -u docker-backup.service
```
2. **实时监控日志**
```bash
journalctl -f -u docker-backup.service
```
3. **查看指定时间范围日志**
```bash
journalctl -u docker-backup.service --since "1 hour ago"
```

114
llmdoc/guides/how-to-perform-backup.md Normal file
View File

@@ -0,0 +1,114 @@
# 如何执行备份
## 前提条件
1. 已安装必要的工具：
- Docker
- yq
- tar
- gzip
## 配置备份
1. **编辑配置文件**：`/etc/docker-backup/config.yml`
```yaml
# 备份基本设置
backup:
output_dir: /path/to/backup # 备份文件输出目录
prefix: docker-backup # 备份文件名前缀
retention:
enabled: true # 是否启用自动清理
keep_days: 30 # 保留最近 30 天的备份
# 文件夹备份配置
folders:
enabled: true # 是否启用文件夹备份
sources: # 要备份的文件夹列表
- /path/to/folder1
- /path/to/folder2
excludes: # 可选：排除的文件/目录模式
- '*.log'
- '.git/'
# MySQL 备份配置
mysql:
enabled: true # 是否启用 MySQL 备份
container_name: mysql_container
username: backup_user
password: backup_password
databases: # 要备份的数据库
- database1
- database2
# 或使用 'all' 备份所有数据库
# 日志配置
logging:
enabled: true
log_file: /path/to/backup.log
```
## 执行备份
1. **手动备份**：
```bash
docker-backup
```
2. **自动备份**（使用 systemd timer，安装时已配置）：
```bash
# 查看定时任务状态
systemctl status docker-backup.timer
# 查看下次执行时间
systemctl list-timers docker-backup.timer
# 立即触发一次备份
systemctl start docker-backup.service
```
3. **查看备份结果**：
```bash
# 列出所有备份文件
docker-backup-cleanup --list
# 查看备份日志
sudo journalctl -u docker-backup.service -n 50
```
## 故障排查
1. **常见错误**：
- 检查配置文件权限和路径
- 验证 Docker 容器状态
- 查看日志文件 `log_file`
2. **依赖检查**：
```bash
# 脚本会自动检查，但可手动验证
which yq tar gzip docker
```
## 备份恢复
1. 解压备份文件
```bash
tar -xzvf backup-YYYYMMDD-HHMMSS.tar.gz
```
2. 恢复文件夹
```bash
tar -xzvf folders.tar.gz -C /restore/path
```
3. 恢复 MySQL 数据库
```bash
# 假设使用 Docker MySQL 容器
zcat mysql.sql.gz | docker exec -i mysql_container mysql -u root -p
```
## 注意事项
- 备份前关闭正在写入的应用
- 定期测试备份和恢复流程
- 保护备份文件和配置文件的安全

62
llmdoc/index.md Normal file
View File

@@ -0,0 +1,62 @@
# Docker 备份工具文档中心
## 项目简介
Docker 备份工具是一个功能强大、易于使用的 Docker 数据备份解决方案，专为 Linux 系统设计。提供全面的备份和管理功能，帮助用户轻松备份 Docker 容器中的文件夹和数据库。
## 文档组织结构
我们的文档分为四个主要类别，旨在帮助用户和开发者快速找到所需信息：
### 1. 项目概述 (Overview)
- 了解项目背景、目标和核心功能
- 文档位置：`/llmdoc/overview/`
### 2. 指南 (Guides)
- 提供具体的操作步骤和实践指南
- 文档位置：`/llmdoc/guides/`
### 3. 架构 (Architecture)
- 深入探讨系统设计、组件交互和关键流程
- 文档位置：`/llmdoc/architecture/`
### 4. 参考 (Reference)
- 提供详细的技术规格、配置细节和编码约定
- 文档位置：`/llmdoc/reference/`
## 文档目录
### 项目概述
- [`project-overview.md`](/llmdoc/overview/project-overview.md): Docker 备份工具的核心目标、功能和技术栈概述
### 指南
1. 安装和配置
- [`how-to-install.md`](/llmdoc/guides/how-to-install.md): 安装 Docker 备份工具的详细步骤
- [`how-to-configure-backups.md`](/llmdoc/guides/how-to-configure-backups.md): 配置备份策略和参数
2. 服务管理
- [`how-to-manage-systemd-service.md`](/llmdoc/guides/how-to-manage-systemd-service.md): 管理和控制 systemd 服务
- [`how-to-perform-backup.md`](/llmdoc/guides/how-to-perform-backup.md): 执行手动备份和恢复操作
### 架构
1. 系统架构
- [`installation-architecture.md`](/llmdoc/architecture/installation-architecture.md): 安装过程和系统集成架构
- [`configuration-system.md`](/llmdoc/architecture/configuration-system.md): 配置系统的设计和实现
- [`systemd-integration.md`](/llmdoc/architecture/systemd-integration.md): systemd 服务集成细节
- [`backup-engine-architecture.md`](/llmdoc/architecture/backup-engine-architecture.md): 备份引擎的技术架构
### 参考
1. 约定和规范
- [`git-conventions.md`](/llmdoc/reference/git-conventions.md): 项目 Git 提交和协作约定
- [`coding-conventions.md`](/llmdoc/reference/coding-conventions.md): 代码编写和风格指南
2. 配置
- [`configuration-schema.md`](/llmdoc/reference/configuration-schema.md): 配置文件的详细架构和参数说明
## 开始使用
- 新用户请首先阅读[项目概述](/llmdoc/overview/project-overview.md)
- 安装指南请参考[如何安装](/llmdoc/guides/how-to-install.md)
- 遇到问题？查看具体的指南和架构文档
## 许可证
本项目采用 MIT License，欢迎在遵守许可条款的前提下自由使用和二次开发。

61
llmdoc/overview/project-overview.md Normal file
View File

@@ -0,0 +1,61 @@
# Docker 备份工具 - 项目概述
## 1. 项目简介
Docker 备份工具是一个功能强大、易于使用的 Docker 数据备份解决方案，专为 Linux 系统（支持 systemd）设计。该工具提供全面的备份和管理功能，帮助用户轻松备份 Docker 容器中的文件夹和数据库。
## 2. 主要功能
- 文件夹备份
- 打包指定文件夹为压缩文件
- 支持排除特定目录和文件模式
- MySQL 数据库备份
- 备份 Docker 容器中的 MySQL 数据库
- 支持备份指定或全部数据库
- 备份文件管理
- 合并文件夹和数据库备份
- 自动清理旧备份文件
- 按天数或数量保留备份
## 3. 技术栈
- **编程语言**: Bash Shell
- **核心工具**:
- tar: 文件打包
- gzip: 文件压缩
- docker: 容器交互
- yq: YAML 配置解析
- **系统集成**: systemd (定时任务和服务管理)
## 4. 项目结构
```
docker-backup/
├── bin/
│ ├── backup.sh # 主备份脚本
│ └── cleanup.sh # 备份清理脚本
├── config/ # 配置文件目录
├── systemd/ # systemd 服务模板
├── install.sh # 安装脚本
└── README.md # 项目文档
```
## 5. 使用场景
- 需要定期备份 Docker 容器数据的开发者和系统管理员
- 个人服务器和小型企业基础设施
- 需要自动化备份和管理备份文件的场景
- 对 MySQL 数据库和文件系统数据有备份需求的项目
## 6. 关键特性
- 一键安装和配置
- 灵活的备份策略
- 完善的日志记录
- 自动清理备份文件
- 支持自定义备份计划
- 安全性考虑（如权限控制）
## 7. 许可证
MIT License - 开源且自由使用

90
llmdoc/reference/coding-conventions.md Normal file
View File

@@ -0,0 +1,90 @@
# Bash 脚本编码约定
## 1. 脚本结构约定
### 1.1 基本骨架
- 必须以 `#!/bin/bash` 开头
- 使用 `set -e` 和 `set -o pipefail` 启用严格错误处理
- 按照以下顺序组织脚本：
1. Shebang
2. 文件描述注释
3. 变量和常量定义
4. 日志和颜色输出函数
5. 主要功能函数
6. 主函数（`main()`）
7. 主函数调用
### 1.2 错误处理
- 使用 `set -e` 在任何命令执行失败时立即退出脚本
- 使用 `set -o pipefail` 确保管道命令链任何一个失败都返回失败状态
- 对于可能失败的操作，编写明确的错误检查和日志记录机制
## 2. 命名约定
### 2.1 变量命名
- 全局变量使用大写，单词间使用下划线分隔
- 正确: `SCRIPT_DIR`, `DEFAULT_INSTALL_DIR`
- 局部变量使用小写，单词间使用下划线分隔
- 正确: `backup_type`, `temp_backup_dir`
### 2.2 函数命名
- 使用小写，单词间使用下划线分隔
- 动词 + 名词的形式
- 正确: `install_dependencies()`, `check_root()`
- 错误: `Dependencies()`, `rootCheck()`
## 3. 日志记录约定
### 3.1 日志级别
- 使用以下日志级别函数：
- `log_info()`: 普通信息
- `log_warn()`: 警告信息
- `log_error()`: 错误信息
### 3.2 日志输出
- 日志应包含时间戳
- 使用颜色区分不同日志级别
- 日志消息应简洁明了，描述当前操作或状态
## 4. 注释风格
### 4.1 文件头注释
- 使用 `###############################################################################`
- 包含脚本名称和简要功能描述
### 4.2 函数注释
- 在函数定义前使用块注释
- 描述函数的目的和关键行为
### 4.3 行内注释
- 仅在代码复杂或不明显时使用
- 解释 "为什么" 而非 "做什么"
## 5. 参数和配置处理
### 5.1 参数解析
- 使用 `case` 语句处理命令行参数
- 提供帮助选项（`-h`, `--help`）
- 对无效参数给出明确错误提示
### 5.2 配置加载
- 使用配置文件（如 YAML）管理可配置参数
- 提供合理的默认值
- 在加载配置时进行有效性检查
## 6. 性能和安全最佳实践
### 6.1 依赖检查
- 在脚本开始检查所有必需的外部工具
- 为缺失的依赖提供明确的安装指导
### 6.2 权限管理
- 对于需要特权的脚本，明确检查 root 权限
- 谨慎处理文件和目录权限
## 7. 示例项目特定约定
本项目脚本特有的一些约定：
- 使用 `BASH_SOURCE[0]` 获取脚本所在目录
- 支持通过环境变量覆盖默认配置
- 使用 `trap` 注册清理函数

62
llmdoc/reference/configuration-schema.md Normal file
View File

@@ -0,0 +1,62 @@
# 配置架构参考
## 配置项概览
### `backup` 区块
| 配置项 | 类型 | 必填 | 默认值 | 描述 |
|--------|------|------|--------|------|
| `output_dir` | 字符串 | 是 | `/var/backups/docker-backup` | 备份文件存储目录 |
| `prefix` | 字符串 | 否 | `backup` | 备份文件名前缀 |
| `retention.enabled` | 布尔 | 否 | `true` | 是否启用自动清理 |
| `retention.keep_days` | 整数 | 否 | `7` | 保留最近 N 天备份 |
| `retention.keep_count` | 整数 | 否 | `null` | 保留最近 N 个备份文件 |
### `folders` 区块
| 配置项 | 类型 | 必填 | 默认值 | 描述 |
|--------|------|------|--------|------|
| `enabled` | 布尔 | 否 | `true` | 是否启用文件夹备份 |
| `sources` | 字符串数组 | 是 | `[]` | 需备份的文件夹路径列表 |
| `excludes` | 字符串数组 | 否 | 预定义排除模式 | 排除的文件/文件夹模式 |
### `mysql` 区块
| 配置项 | 类型 | 必填 | 默认值 | 描述 |
|--------|------|------|--------|------|
| `enabled` | 布尔 | 否 | `true` | 是否启用 MySQL 备份 |
| `container_name` | 字符串 | 是 | 无 | MySQL 容器名称 |
| `username` | 字符串 | 是 | 无 | 数据库用户名 |
| `password` | 字符串 | 是 | 无 | 数据库密码 |
| `databases` | 字符串数组或字符串 | 是 | 无 | 要备份的数据库，可以是具体库名或 `"all"` |
### `logging` 区块
| 配置项 | 类型 | 必填 | 默认值 | 描述 |
|--------|------|------|--------|------|
| `enabled` | 布尔 | 否 | `true` | 是否启用日志 |
| `log_file` | 字符串 | 是 | `/var/log/docker-backup.log` | 日志文件路径 |
| `level` | 字符串 | 否 | `"INFO"` | 日志级别 (`DEBUG`, `INFO`, `WARN`, `ERROR`) |
### `notification` 区块
| 配置项 | 类型 | 必填 | 默认值 | 描述 |
|--------|------|------|--------|------|
| `enabled` | 布尔 | 否 | `false` | 是否启用通知 |
| `method` | 字符串 | 条件必填 | 无 | 通知方式 (`email`, `webhook`) |
| `webhook_url` | 字符串 | 条件必填 | 无 | Webhook 地址 |
| `on_failure_only` | 布尔 | 否 | `true` | 是否仅在备份失败时通知 |
## 配置依赖和约束
1. 互斥配置：
- `retention.keep_days` 和 `retention.keep_count` 互斥
2. 必要条件：
- MySQL 备份需要 `container_name`、`username`、`password`
- 通知需要 `method` 和相应的地址
3. 验证规则：
- 文件夹备份需要至少一个有效的 `sources`
- 检查路径有效性
- 验证工具依赖（`yq`, `tar`, `docker`）

88
llmdoc/reference/git-conventions.md Normal file
View File

@@ -0,0 +1,88 @@
# Git 约定
## 1. 分支策略
### 主分支
- **主分支名称**：`main`
- **主分支规则**：
- 始终保持稳定和可部署状态
- 直接对应生产环境
- 受保护分支，需要代码审查才能合并
### 开发分支类型
- `feature/[功能名称]`：新功能开发
- `bugfix/[问题描述]`：修复特定 bug
- `hotfix/[紧急问题]`：生产环境紧急修复
- `docs/[文档内容]`：文档更新
- `refactor/[模块名称]`：代码重构
## 2. 提交消息格式
提交消息应遵循语义化提交规范：
```
<type>(<scope>): <description>
[可选的详细描述]
- 可选的脚注信息
```
### 类型 (Type)
- `feat`: 新功能
- `fix`: 修复 bug
- `docs`: 文档变更
- `style`: 代码格式调整
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建过程或辅助工具变更
### 示例提交消息
```
feat(auth): 添加用户注册功能
- 实现基于电子邮件的用户注册流程
- 集成用户验证机制
```
## 3. 推荐工作流程
1. 从 `main` 创建功能分支
```bash
git checkout -b feature/new-feature main
```
2. 进行开发并频繁提交
```bash
git add .
git commit -m "feat(module): 描述具体变更"
```
3. 推送分支到远程仓库
```bash
git push -u origin feature/new-feature
```
4. 创建 Pull Request
- 目标分支：`main`
- 包含详细的变更说明
- 等待代码审查和批准
5. 合并后清理分支
```bash
git checkout main
git pull
git branch -d feature/new-feature
```
## 4. 其他最佳实践
- 保持提交原子化和有意义
- 编写清晰、简洁的提交消息
- 避免在一个提交中包含多个无关的变更
- 使用 `.gitignore` 排除不需要版本控制的文件
## 5. 推荐工具
- Git 提交检查：`pre-commit`
- 代码审查：GitHub/GitLab Pull Request