# 真实存储 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）配置即可恢复服务。