feat: add s3 boot check option

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 使用）

backend/providers/storage/config.go

@@ -12,4 +12,6 @@ type Config struct {
 	Bucket    string
 	Endpoint  string
 	PathStyle bool
+	// CheckOnBoot 启动时检查 bucket 可用性（仅 s3）。
+	CheckOnBoot bool
 }

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()...)

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.

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 → 删除。
 

docs/todo_list.md

@@ -255,6 +255,7 @@
 
 **技术方案（后端）**
 - 通过配置注入 Provider，保留本地 FS/MinIO 作为 dev fallback。
+- 进度：已补齐 S3 配置示例与 `CheckOnBoot` 可选自检开关。
 
 **测试方案**
 - 本地 FS + MinIO + 真实 Provider 三套配置可用性。