From 3728a921d2647847316d2d68d081e480ef635c11 Mon Sep 17 00:00:00 2001
From: Rogee <rogee@ipao.vip>
Date: Sat, 17 Jan 2026 22:16:52 +0800
Subject: [PATCH] feat: add s3 boot check option

---
 backend/config.full.toml              |  2 ++
 backend/providers/storage/config.go   |  2 ++
 backend/providers/storage/provider.go | 13 ++++++++++++-
 docs/storage_provider.md              |  2 ++
 docs/storage_provider_plan.md         |  2 +-
 docs/todo_list.md                     |  1 +
 6 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/backend/config.full.toml b/backend/config.full.toml
index 27e8c4c..96b8a16 100644
--- a/backend/config.full.toml
+++ b/backend/config.full.toml
@@ -270,6 +270,8 @@ Bucket = "quyun-assets"
 Endpoint = "https://s3.amazonaws.com"
 # PathStyle（S3/MinIO，MinIO 通常为 true）
 PathStyle = false
+# 启动时检查 bucket 是否可用（仅 s3）
+CheckOnBoot = false
 # 本地存储路径（local 使用）
 LocalPath = "./storage"
 # 签名密钥（local 使用）
diff --git a/backend/providers/storage/config.go b/backend/providers/storage/config.go
index d628578..11916a4 100644
--- a/backend/providers/storage/config.go
+++ b/backend/providers/storage/config.go
@@ -12,4 +12,6 @@ type Config struct {
 	Bucket    string
 	Endpoint  string
 	PathStyle bool
+	// CheckOnBoot 启动时检查 bucket 可用性（仅 s3）。
+	CheckOnBoot bool
 }
diff --git a/backend/providers/storage/provider.go b/backend/providers/storage/provider.go
index abdfba5..94b1a49 100644
--- a/backend/providers/storage/provider.go
+++ b/backend/providers/storage/provider.go
@@ -39,9 +39,20 @@ func Provide(opts ...opt.Option) error {
 	return container.Container.Provide(func() (*Storage, error) {
 		store := &Storage{Config: &config}
 		if store.storageType() == "s3" {
-			if _, err := store.s3ClientForUse(); err != nil {
+			client, err := store.s3ClientForUse()
+			if err != nil {
 				return nil, err
 			}
+			if store.Config.CheckOnBoot {
+				// 启动时可选检查 bucket 是否可用，便于尽早暴露配置问题。
+				exists, err := client.BucketExists(context.Background(), store.Config.Bucket)
+				if err != nil {
+					return nil, fmt.Errorf("storage bucket check failed: %w", err)
+				}
+				if !exists {
+					return nil, fmt.Errorf("storage bucket not found: %s", store.Config.Bucket)
+				}
+			}
 		}
 		return store, nil
 	}, o.DiOptions()...)
diff --git a/docs/storage_provider.md b/docs/storage_provider.md
index 7aebe2c..ca93d9d 100644
--- a/docs/storage_provider.md
+++ b/docs/storage_provider.md
@@ -27,6 +27,8 @@ Region = "us-east-1"
 Bucket = "quyun-assets"
 Endpoint = "http://127.0.0.1:9000"
 PathStyle = true
+# Optional: check bucket connectivity on boot
+CheckOnBoot = false
 ```
 
 For AWS S3, set `Endpoint` with `https://` (e.g., `https://s3.amazonaws.com`) and keep `PathStyle` as `false` unless your provider requires path-style access.
diff --git a/docs/storage_provider_plan.md b/docs/storage_provider_plan.md
index 5402485..d128676 100644
--- a/docs/storage_provider_plan.md
+++ b/docs/storage_provider_plan.md
@@ -74,7 +74,7 @@ BaseURL = "http://localhost:8080/t/<tenantCode>/v1/storage"
 
 1) 确认生产 Provider 类型（已完成：S3 兼容）。
 2) 填好生产配置（已完成：补齐 `config.full.toml` 示例）。
-3) 若是 S3 兼容：无需改代码，只做连通性检查。
+3) 若是 S3 兼容：已增加 `CheckOnBoot` 开关，连通性检查可在具备凭证后执行。
 4) 若是非 S3：新增 Provider 类型并实现签名/上传/删除。
 5) 回归上传链路：上传 → 回调 → 访问 URL → 删除。
 
diff --git a/docs/todo_list.md b/docs/todo_list.md
index cb98109..b0f0e3e 100644
--- a/docs/todo_list.md
+++ b/docs/todo_list.md
@@ -255,6 +255,7 @@
 
 **技术方案（后端）**
 - 通过配置注入 Provider，保留本地 FS/MinIO 作为 dev fallback。
+- 进度：已补齐 S3 配置示例与 `CheckOnBoot` 可选自检开关。
 
 **测试方案**
 - 本地 FS + MinIO + 真实 Provider 三套配置可用性。