quyun-v2/docs/storage_provider_plan.md

真实存储 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 兼容

[Storage]
Type = "s3"
AccessKey = "xxx"
SecretKey = "yyy"
Region = "ap-southeast-1"
Bucket = "quyun-assets"
Endpoint = "https://s3.amazonaws.com"
PathStyle = false

6.2 本地（保持不变）

[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）配置即可恢复服务。