|
|
# 文件存储系统
|
|
|
|
|
|
## 概述
|
|
|
|
|
|
本存储系统采用策略模式设计，支持多种存储后端，包括本地存储和各大云服务商的对象存储服务。
|
|
|
|
|
|
## 支持的存储类型
|
|
|
|
|
|
- **本地存储 (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`
|
|
|
- 文件操作失败时会抛出相应异常
|
|
|
|