iTi-Flask/iti/applications/common/storage

文件存储系统

概述

本存储系统采用策略模式设计，支持多种存储后端，包括本地存储和各大云服务商的对象存储服务。

支持的存储类型

• 本地存储 (local) - 默认，无需额外依赖
• 阿里云OSS (aliyun_oss) - 需要安装 oss2
• 腾讯云COS (tencent_cos) - 需要安装 cos-python-sdk-v5
• 七牛云Kodo (qiniu_kodo) - 需要安装 qiniu
• 华为云OBS (huawei_obs) - 需要安装 esdk-obs-python
• AWS S3 (aws_s3) - 待实现
• MinIO (minio) - 待实现

安装依赖

根据需要安装对应的SDK：

# 阿里云OSS
pip install oss2

# 腾讯云COS
pip install cos-python-sdk-v5

# 七牛云Kodo
pip install qiniu

# 华为云OBS
pip install esdk-obs-python

或一次性安装所有依赖：

pip install oss2 cos-python-sdk-v5 qiniu esdk-obs-python

配置说明

环境变量配置

在 .env 文件中配置对应的云存储凭证：

# 阿里云OSS
ALIYUN_OSS_ACCESS_KEY_ID=your_access_key_id
ALIYUN_OSS_ACCESS_KEY_SECRET=your_access_key_secret
ALIYUN_OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
ALIYUN_OSS_BUCKET=your_bucket_name

# 腾讯云COS
TENCENT_COS_SECRET_ID=your_secret_id
TENCENT_COS_SECRET_KEY=your_secret_key
TENCENT_COS_REGION=ap-guangzhou
TENCENT_COS_BUCKET=your_bucket_name

# 七牛云Kodo
QINIU_KODO_ACCESS_KEY=your_access_key
QINIU_KODO_SECRET_KEY=your_secret_key
QINIU_KODO_BUCKET=your_bucket_name
QINIU_KODO_DOMAIN=your_cdn_domain.com

# 华为云OBS
HUAWEI_OBS_ACCESS_KEY_ID=your_access_key_id
HUAWEI_OBS_SECRET_ACCESS_KEY=your_secret_access_key
HUAWEI_OBS_SERVER=obs.cn-north-4.myhuaweicloud.com
HUAWEI_OBS_BUCKET=your_bucket_name

应用配置

在 config.py 中修改默认存储类型：

FILE_STORAGE = {
    "DEFAULT_STORAGE_TYPE": "aliyun_oss",  # 修改为你想要的默认存储
    "LOCAL": {
        "base_path": "/path/to/uploads",
    },
    "ALIYUN_OSS": {
        # ...
    },
}

使用方式

1. 全局默认存储

在配置文件中设置 DEFAULT_STORAGE_TYPE，所有未指定存储类型的文件将使用此存储。

2. 目录级存储

为特定目录设置 default_storage_type：

directory = SysFileDirectory(
    name="用户头像",
    path="/avatars",
    default_storage_type="aliyun_oss"  # 该目录下的文件使用阿里云OSS
)

3. 请求级存储

上传文件时通过参数指定：

// 普通上传
formData.append('storageType', 'tencent_cos');

// TUS上传
uppy.setMeta({
  storageType: 'qiniu_kodo'
});

存储优先级

请求参数 > 目录默认 > 全局默认

接口说明

所有存储适配器实现了统一的 StorageInterface 接口：

• upload() - 上传文件
• append_chunk() - 追加数据块（用于TUS协议）
• download() - 下载文件
• delete() - 删除文件
• exists() - 检查文件是否存在
• get_url() - 获取访问URL（支持签名URL）

注意事项

1. TUS协议支持：

   • 阿里云OSS、华为云OBS 支持原生追加写入
   • 腾讯云COS、七牛云Kodo 使用读-改-写策略模拟追加（性能较低，不建议用于大文件）

2. URL签名：

   • 所有云存储都支持生成带签名的临时URL
   • 设置 expires=0 可生成永久URL（仅适用于公共读bucket）

3. 秒传机制：

   • 系统会检查文件哈希，相同存储类型下的重复文件自动复用
   • 不同存储类型的相同文件会分别存储

4. 错误处理：

   • SDK未安装时会抛出 ImportError
   • 配置不完整时会抛出 ValueError
   • 文件操作失败时会抛出相应异常