# 文件存储系统

## 概述

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

## 支持的存储类型

- **本地存储 (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：

```bash
# 阿里云OSS
pip install oss2

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

# 七牛云Kodo
pip install qiniu

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

或一次性安装所有依赖：

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

## 配置说明

### 环境变量配置

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

```bash
# 阿里云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` 中修改默认存储类型：

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

## 使用方式

### 1. 全局默认存储

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

### 2. 目录级存储

为特定目录设置 `default_storage_type`：

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

### 3. 请求级存储

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

```javascript
// 普通上传
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`
   - 文件操作失败时会抛出相应异常