From bb62cf4280bf9aa7733a9cf2fb0ba02242dcc606 Mon Sep 17 00:00:00 2001
From: Rogee <rogee@ipao.vip>
Date: Sat, 17 Jan 2026 22:12:18 +0800
Subject: [PATCH] docs: add s3 storage plan and config example

---
 backend/config.full.toml      | 25 ++++++++++
 docs/storage_provider_plan.md | 91 +++++++++++++++++++++++++++++++++++
 2 files changed, 116 insertions(+)
 create mode 100644 docs/storage_provider_plan.md

diff --git a/backend/config.full.toml b/backend/config.full.toml
index 99c273e..27e8c4c 100644
--- a/backend/config.full.toml
+++ b/backend/config.full.toml
@@ -251,3 +251,28 @@ Env = "dev"
 # 指标（毫秒，可选）
 # MetricReaderIntervalMs = 10000       # 指标导出周期
 # RuntimeReadMemStatsIntervalMs = 5000 # 运行时指标采集最小周期
+
+# =========================
+# 存储配置 (providers/storage)
+# =========================
+[Storage]
+# 存储类型：local | s3
+Type = "s3"
+# AccessKey（S3/MinIO）
+AccessKey = "your-access-key"
+# SecretKey（S3/MinIO）
+SecretKey = "your-secret-key"
+# Region（S3/MinIO）
+Region = "ap-southeast-1"
+# Bucket（S3/MinIO）
+Bucket = "quyun-assets"
+# Endpoint（S3/MinIO，AWS 示例：https://s3.amazonaws.com）
+Endpoint = "https://s3.amazonaws.com"
+# PathStyle（S3/MinIO，MinIO 通常为 true）
+PathStyle = false
+# 本地存储路径（local 使用）
+LocalPath = "./storage"
+# 签名密钥（local 使用）
+Secret = "your-storage-secret"
+# 公共访问URL前缀（local 使用）
+BaseURL = "http://localhost:8080/t/<tenantCode>/v1/storage"
diff --git a/docs/storage_provider_plan.md b/docs/storage_provider_plan.md
new file mode 100644
index 0000000..5402485
--- /dev/null
+++ b/docs/storage_provider_plan.md
@@ -0,0 +1,91 @@
+# 真实存储 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 兼容：无需改代码，只做连通性检查。
+4) 若是非 S3：新增 Provider 类型并实现签名/上传/删除。
+5) 回归上传链路：上传 → 回调 → 访问 URL → 删除。
+
+## 8. 测试清单（按顺序）
+
+- `SignURL` 输出正确（含过期参数）。
+- 上传成功，访问 URL 正常（HTTP 200）。
+- 删除成功，访问返回 404 或拒绝。
+- URL 过期后访问失败。
+
+## 9. 风险与回滚
+
+- 风险：生产 Provider 非 S3 兼容，签名不一致导致上传失败。
+- 回滚：切换回 `local` 或 `s3`（MinIO）配置即可恢复服务。