92 lines
2.9 KiB
Markdown
92 lines
2.9 KiB
Markdown
# 真实存储 Provider 接入（生产）（先规划，后执行）
|
||
|
||
## 1. 一句话说明
|
||
|
||
- 上线环境用真实对象存储（优先 S3 兼容），开发/测试仍可用本地 FS 或 MinIO。
|
||
|
||
## 2. 要做什么 / 不做什么
|
||
|
||
- 要做：
|
||
- 生产环境能正常上传、访问、删除文件。
|
||
- 不影响现有本地/MinIO 的开发体验。
|
||
- 不做：
|
||
- 不在本次做支付集成。
|
||
- 不改现有上传业务流程，仅替换存储后端。
|
||
|
||
## 3. 当前现状
|
||
|
||
- 已支持 `local` 与 `s3`（MinIO/AWS S3 兼容）两种类型：`backend/providers/storage`。
|
||
- 本地存储走自签名 URL；S3 走预签名 URL（MinIO SDK）。
|
||
- 文档已覆盖 MinIO 及本地配置：`docs/storage_provider.md`、`docs/storage_minio_smoke_test.md`。
|
||
|
||
## 4. 方案选择（最重要）
|
||
|
||
- **如果生产是 S3 兼容**（AWS S3 / MinIO / 兼容网关）：
|
||
- 直接用现有 `Type = "s3"`，只需要补齐配置。
|
||
- **如果生产是非 S3 兼容**（OSS/COS/OBS 专有签名）：
|
||
- 需要新增 Provider 类型（如 `oss`/`cos`），并实现：
|
||
- 生成签名 URL
|
||
- 上传/删除逻辑
|
||
- 保持现有 `Storage` 结构清晰，避免堆分支。
|
||
|
||
> 已确认：生产存储为 **S3 兼容**，无需新增 Provider 类型。
|
||
|
||
## 5. 必要配置（生产需要明确的信息）
|
||
|
||
- 需要确认的配置项：
|
||
- `Type`：`s3` 或新 Provider 类型。
|
||
- `Endpoint`：如 `https://s3.amazonaws.com` 或自建网关地址。
|
||
- `AccessKey` / `SecretKey`
|
||
- `Bucket`
|
||
- `Region`
|
||
- `PathStyle`：是否使用路径风格（MinIO 通常需要 `true`）。
|
||
- `BaseURL`：仅 `local` 使用。
|
||
- 约束：
|
||
- `Endpoint`、`Bucket` 不能为空。
|
||
- 签名 URL 需有过期时间（建议 15 分钟）。
|
||
|
||
## 6. 配置示例
|
||
|
||
### 6.1 S3 兼容
|
||
|
||
```toml
|
||
[Storage]
|
||
Type = "s3"
|
||
AccessKey = "xxx"
|
||
SecretKey = "yyy"
|
||
Region = "ap-southeast-1"
|
||
Bucket = "quyun-assets"
|
||
Endpoint = "https://s3.amazonaws.com"
|
||
PathStyle = false
|
||
```
|
||
|
||
### 6.2 本地（保持不变）
|
||
|
||
```toml
|
||
[Storage]
|
||
Type = "local"
|
||
LocalPath = "./storage"
|
||
Secret = "your-storage-secret"
|
||
BaseURL = "http://localhost:8080/t/<tenantCode>/v1/storage"
|
||
```
|
||
|
||
## 7. 实施步骤（更清晰）
|
||
|
||
1) 确认生产 Provider 类型（已完成：S3 兼容）。
|
||
2) 填好生产配置（已完成：补齐 `config.full.toml` 示例）。
|
||
3) 若是 S3 兼容：已增加 `CheckOnBoot` 开关，连通性检查可在具备凭证后执行。
|
||
4) 若是非 S3：新增 Provider 类型并实现签名/上传/删除。
|
||
5) 回归上传链路：上传 → 回调 → 访问 URL → 删除。
|
||
|
||
## 8. 测试清单（按顺序）
|
||
|
||
- `SignURL` 输出正确（含过期参数）。
|
||
- 上传成功，访问 URL 正常（HTTP 200）。
|
||
- 删除成功，访问返回 404 或拒绝。
|
||
- URL 过期后访问失败。
|
||
|
||
## 9. 风险与回滚
|
||
|
||
- 风险：生产 Provider 非 S3 兼容，签名不一致导致上传失败。
|
||
- 回滚：切换回 `local` 或 `s3`（MinIO）配置即可恢复服务。
|