# aliyun-oss-backup-tool

**Repository Path**: brightxiaohan/aliyun-oss-backup-tool

## Basic Information

- **Project Name**: aliyun-oss-backup-tool
- **Description**: 阿里云OSS自动备份工具 - 支持定时备份文件到阿里云对象存储，流水号：6/3-826336
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-04
- **Last Updated**: 2025-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 阿里云OSS自动备份工具

自动将文件或目录备份到阿里云对象存储服务(OSS)的Python工具，支持定时备份和自动清理旧备份。

## 功能特点

- 按照设定的时间每天自动备份文件/目录到阿里云OSS
- 支持多个文件/目录的备份
- 支持文件排除模式（使用glob模式匹配）
- 自动清理超过保留期限的旧备份
- 自动管理存储空间，当接近配置的存储限制时自动删除最旧的备份
- 智能跳过未更改的文件，避免重复备份
- 大文件传输时显示实时进度条
- 详细的日志记录

## 系统要求

- Python 3.6+
- Windows操作系统
- 有效的阿里云OSS账号和访问凭证

## 安装步骤

1. 确保已安装Python 3.6或更高版本
2. 安装所需依赖：

```bash
pip install oss2 schedule
```

3. 克隆或下载此仓库到本地

## 配置说明

首次运行脚本时，会自动创建`config.ini`配置文件，或者您可以手动复制`config.ini.example`为`config.ini`并进行编辑：

```ini
[oss]
; 阿里云OSS凭证
access_key_id = YOUR_ACCESS_KEY_ID
access_key_secret = YOUR_ACCESS_KEY_SECRET
endpoint = http://oss-cn-hangzhou.aliyuncs.com
bucket_name = your-bucket-name
; 存储限制设置（单位：GB和百分比）
storage_limit_gb = 450
storage_threshold_percent = 90

[schedule]
; 每日备份时间（24小时制）
backup_time = 02:00

[backup]
; 要备份的文件或目录列表（逗号分隔）
sources = C:\path\to\backup1, C:\path\to\backup2
; 排除模式（逗号分隔，使用glob模式）
exclude_patterns = *.tmp, *.log, .git/
; 备份保留天数（0表示永久保留）
retention_days = 30
; 跳过未更改的文件以避免重复备份
skip_unchanged = true
; 显示大文件传输进度条
show_progress = true
; 文件大于此阈值时显示进度（单位：MB）
large_file_threshold_mb = 10
```

### 存储空间管理

该工具会自动管理OSS中的存储空间：

1. `storage_limit_gb`: 设置OSS存储空间的限制（默认为450GB，对应500GB的90%）
2. `storage_threshold_percent`: 设置存储使用率阈值（默认为90%）

当存储使用率超过设定的阈值时，工具会自动删除最旧的备份文件夹，直到释放足够的空间。这确保了即使您的云存储接近满额时，新的备份也能顺利进行。

### 避免重复备份

工具使用文件哈希比较功能，避免重复备份未更改的文件：

1. `skip_unchanged`: 设置是否跳过未更改的文件（默认为true）
2. 系统会为每个文件计算MD5哈希值，并与上次备份时的哈希值进行比较
3. 如果文件未发生变化，则跳过备份该文件，节省存储空间和带宽
4. 哈希值信息保存在本地的`file_hash_cache.json`文件中

通过这种机制，即使运行多次备份，也只会上传实际更改过的文件，大大提高了备份效率。

### 大文件进度显示

为了更好地监控大文件的备份进度，系统增加了实时进度显示功能：

1. `show_progress`: 设置是否显示文件传输进度条（默认为true）
2. `large_file_threshold_mb`: 设置文件大小阈值（默认为10MB），超过此大小的文件会显示进度条
3. 进度条显示格式为：`Uploading filename.ext: 45% (4.50/10.00 MB)`

这一功能对于备份视频、数据库备份等大文件特别有用，让您能够直观地了解传输进度，避免长时间等待而不清楚状态。

## 使用方法

### 定时备份模式

直接运行脚本启动定时备份：

```bash
python oss_backup.py
```

脚本将在后台运行，并按照配置文件中指定的时间每天执行备份。

### 立即执行备份

如需立即执行一次备份，可使用以下命令：

```bash
python oss_backup.py --now
```

### 使用Windows任务计划程序

请参考 `windows_scheduler_setup.md` 文件，了解如何使用Windows任务计划程序设置自动备份。

## 日志

脚本运行日志保存在`oss_backup.log`文件中，同时也会在控制台输出。

## 注意事项

1. 请确保您的阿里云OSS访问凭证安全，不要将包含敏感信息的配置文件提交到公共代码仓库
2. 对于大文件备份，请确保网络连接稳定
3. 备份路径中的特殊字符可能会导致问题，尽量使用标准路径名
4. 请正确设置`storage_limit_gb`值，以免系统误判存储空间不足
5. 文件哈希缓存（`file_hash_cache.json`）会随着备份文件数量增加而变大，如果备份大量小文件，可能会占用一定磁盘空间

## 常见问题

**Q: 如何更改备份时间？**  
A: 在`config.ini`文件中修改`[schedule]`部分的`backup_time`值。

**Q: 如何添加更多备份目录？**  
A: 在`config.ini`文件中编辑`[backup]`部分的`sources`值，以逗号分隔添加更多路径。

**Q: 如何防止特定备份被自动删除？**  
A: 目前系统会基于日期自动删除最旧的备份。如需保留特定备份，建议手动将其复制到OSS的其他路径下。

**Q: 云存储空间满了会怎样？**  
A: 当云存储空间使用率接近设定的阈值时，系统会自动删除最旧的备份文件夹以释放空间，确保新的备份可以正常进行。

**Q: 如何强制备份所有文件，包括未更改的文件？**  
A: 在`config.ini`文件中将`[backup]`部分的`skip_unchanged`设置为`false`。

**Q: 如果更换计算机，如何保持文件更改检测功能？**  
A: 将`file_hash_cache.json`文件复制到新计算机上的相同位置即可。

**Q: 如何关闭大文件传输进度显示？**  
A: 在`config.ini`文件中将`[backup]`部分的`show_progress`设置为`false`。

**Q: 如何调整进度条显示的文件大小阈值？**  
A: 在`config.ini`文件中修改`[backup]`部分的`large_file_threshold_mb`值，如设置为`50`表示超过50MB的文件才会显示进度条。

## 贡献

欢迎提交问题和改进建议。如需贡献代码，请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支
3. 提交代码
4. 创建 Pull Request