天翼云对象存储上传工具

一个功能强大的Python工具，用于将大文件和文件夹上传到天翼云对象存储（OOS）。

✨ 特性

• 🚀 大文件分片上传: 自动将大文件切分为多个分片并行上传
• 📁 文件夹递归上传: 支持上传整个文件夹，保留目录结构
• 🔄 断点续传: 网络中断后可从上次中断处继续上传
• ⚡ 并发上传: 使用线程池并发上传分片，提升速度
• 📊 进度跟踪: 实时显示上传进度和速度
• 🛡️ 错误重试: 自动重试失败的上传操作
• 🔧 灵活配置: 支持YAML配置文件和命令行参数

📋 系统要求

• Python 3.8+
• 天翼云对象存储账号和访问凭据

🚀 快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置认证信息

编辑 config/config.yaml 文件，填入你的天翼云OOS凭据：

tianyi_cloud:
  access_key: "YOUR_ACCESS_KEY"
  secret_key: "YOUR_SECRET_KEY"
  endpoint: "https://oos-cn.ctyunapi.cn"
  bucket: "your-bucket-name"

3. 上传文件

上传单个文件:

python main.py /path/to/file.txt

上传文件夹:

python main.py /path/to/folder

指定对象键名前缀:

python main.py /path/to/folder --prefix backup/2024/

📖 使用指南

命令行参数

python main.py [路径] [选项]

位置参数:
  path                  要上传的文件或文件夹路径

可选参数:
  -h, --help            显示帮助信息
  --config CONFIG       配置文件路径（默认: config/config.yaml）
  --prefix PREFIX       对象键名前缀
  --bucket BUCKET       存储桶名称（覆盖配置文件）
  --no-resume           禁用断点续传
  --cleanup             清理已完成的上传记录
  --cleanup-days DAYS   清理记录的保留天数（默认: 7天）
  --log-level LEVEL     日志级别（DEBUG, INFO, WARNING, ERROR, CRITICAL）
  --log-file FILE       日志文件路径

配置文件详解

config/config.yaml 支持以下配置项：

# 天翼云对象存储配置
tianyi_cloud:
  access_key: "YOUR_ACCESS_KEY"          # 访问密钥
  secret_key: "YOUR_SECRET_KEY"          # 密钥
  endpoint: "https://oos-cn.ctyunapi.cn" # OOS端点
  bucket: "your-bucket-name"             # 存储桶名称
  region: "cn"                           # 区域

# 上传设置
upload_settings:
  chunk_size: 10485760                   # 分片大小（10MB）
  multipart_threshold: 5242880           # 大文件阈值（5MB）
  max_workers: 5                         # 最大并发数
  retry_times: 3                         # 失败重试次数
  timeout: 300                           # 请求超时时间（秒）

# 断点续传设置
resume_settings:
  enabled: true                          # 是否启用断点续传
  database_path: ".upload_resume.db"     # 数据库路径
  cleanup_days: 7                        # 自动清理天数

# 日志设置
logging:
  level: "INFO"                          # 日志级别
  file: "upload.log"                     # 日志文件路径

🏗️ 项目结构

tianyiupload/
├── config/
│   └── config.yaml              # 配置文件
├── src/
│   ├── __init__.py
│   ├── client.py                # OOS客户端封装
│   ├── config.py                # 配置管理
│   ├── scanner.py               # 文件扫描器
│   ├── uploader.py              # 上传管理器
│   ├── progress.py              # 进度跟踪
│   └── database.py              # 断点续传数据库
├── tests/                       # 测试文件
├── main.py                      # 主程序入口
├── requirements.txt             # 依赖列表
└── README.md                    # 项目文档

🔧 高级用法

断点续传

工具默认启用断点续传功能。如果上传过程中断，再次运行相同命令即可继续上传：

# 首次上传（中断）
python main.py /large/folder

# 继续上传（自动从中断处恢复）
python main.py /large/folder

如需禁用断点续传：

python main.py /path/to/folder --no-resume

清理已完成记录

定期清理已完成的上传记录，释放数据库空间：

# 清理7天前的记录（默认）
python main.py --cleanup

# 清理30天前的记录
python main.py --cleanup --cleanup-days 30

自定义配置文件

使用不同的配置文件管理多个OOS账号：

python main.py /path/to/folder --config production.yaml

调试模式

启用DEBUG日志查看详细信息：

python main.py /path/to/folder --log-level DEBUG

📊 性能优化建议

1. 调整分片大小: 根据网络带宽调整 chunk_size（默认10MB）

   • 网络较慢：减小到 5MB
   • 网络较快：增大到 20MB

2. 调整并发数: 根据CPU和网络资源调整 max_workers（默认5）

   • CPU较弱：减小到 3
   • CPU较强：增大到 10

3. 调整重试次数: 根据网络稳定性调整 retry_times（默认3）

⚠️ 注意事项

1. 凭据安全: 请妥善保管配置文件，避免泄露访问密钥
2. 网络稳定性: 建议在稳定的网络环境下进行大文件上传
3. 存储桶权限: 确保访问密钥具有目标存储桶的写入权限
4. 磁盘空间: 断点续传数据库会占用少量磁盘空间
5. 并发限制: 过高的并发数可能触发API限流，请根据实际情况调整

🐛 故障排除

上传失败

1. 检查网络连接
2. 验证访问密钥是否正确
3. 确认存储桶名称是否存在
4. 查看日志文件获取详细错误信息

断点续传不生效

1. 确认 resume_settings.enabled 为 true
2. 检查数据库文件 .upload_resume.db 是否存在
3. 确保文件路径和对象键名未改变

性能问题

1. 调整 chunk_size 和 max_workers 参数
2. 检查网络带宽和延迟
3. 监控CPU和内存使用率

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📧 联系方式

如有问题或建议，请通过以下方式联系：

• GitHub Issues: [项目地址]
• Email: [联系邮箱]

---

⭐ 如果这个项目对你有帮助，请给个 Star！