feat(system_config): validate storage configuration connectivity on update

- Add a live test connectivity check in UpdateSystemConfig before saving the storage configuration.
- Merge masked placeholder secrets from current configuration prior to testing and database storage.
- Extract validation and test logic to validateAndMergeStorageConfig helper to satisfy cyclomatic complexity.
- Add TestUpdateStorageConfigValidation covering successful updates and failed checks.

internal/apps/admin/system_config/routers.go

@@ -5,8 +5,10 @@
 package system_config
 
 import (
+	"context"
 	"encoding/json"
 	"errors"
+	"fmt"
 	"net/http"
 	"time"
 
@@ -199,6 +201,13 @@ func UpdateSystemConfig(c *gin.Context) {
 		if err := json.Unmarshal([]byte(config.Value), &currentCfg); err == nil {
 			originalDriver = currentCfg.Driver
 		}
+
+		validatedVal, err := validateAndMergeStorageConfig(c.Request.Context(), req.Value, config.Value)
+		if err != nil {
+			c.JSON(http.StatusBadRequest, util.Err(err.Error()))
+			return
+		}
+		req.Value = validatedVal
 	}
 
 	if err := db.DB(c.Request.Context()).Transaction(func(tx *gorm.DB) error {
@@ -338,3 +347,42 @@ func maskSensitiveConfig(key, value string) string {
 	}
 	return value
 }
+
+// validateAndMergeStorageConfig parses, merges unmasked secrets, validates parameter values,
+// and tests connectivity of the new storage configuration.
+func validateAndMergeStorageConfig(ctx context.Context, value string, currentConfig string) (string, error) {
+	var currentCfg storage.Config
+	if err := json.Unmarshal([]byte(currentConfig), &currentCfg); err != nil {
+		return "", fmt.Errorf("解析当前存储配置失败: %w", err)
+	}
+
+	var newCfg storage.Config
+	if err := json.Unmarshal([]byte(value), &newCfg); err != nil {
+		return "", fmt.Errorf("解析目标存储配置失败: %w", err)
+	}
+
+	// 合并被掩码屏蔽的敏感信息，获取完整的真实配置
+	targetCfg := storage.MergeMaskedSecrets(newCfg, currentCfg)
+
+	// 校验配置参数是否合法
+	if err := storage.ValidateConfig(targetCfg); err != nil {
+		return "", fmt.Errorf("验证存储配置参数失败: %w", err)
+	}
+
+	// 进行连通性测试验证，如果测试失败则拒绝保存
+	testBackend, err := storage.NewBackend(ctx, targetCfg, targetCfg.Driver)
+	if err != nil {
+		return "", fmt.Errorf("初始化测试存储实例失败: %w", err)
+	}
+	if err := testBackend.Test(ctx); err != nil {
+		return "", fmt.Errorf("存储连通性测试失败: %w", err)
+	}
+
+	// 序列化为最终保存的真实明文配置，防止保存屏蔽的 ****** 字符
+	unmaskedVal, err := json.Marshal(targetCfg)
+	if err != nil {
+		return "", fmt.Errorf("序列化存储配置失败: %w", err)
+	}
+
+	return string(unmaskedVal), nil
+}

internal/apps/admin/system_config/routers_test.go

@@ -18,6 +18,7 @@ import (
 	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
 	"github.com/Rain-kl/Wavelet/internal/db"
 	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/storage"
 	"github.com/Rain-kl/Wavelet/internal/testhelper"
 	"github.com/Rain-kl/Wavelet/internal/util"
 	"github.com/gin-gonic/gin"
@@ -362,3 +363,61 @@ func TestTestSMTP(t *testing.T) {
 		t.Errorf("expected test success, got failed: %s. Log: %s", testResp.Error, testResp.Log)
 	}
 }
+
+func TestUpdateStorageConfigValidation(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("update storage config successfully", func(t *testing.T) {
+		tempDir := t.TempDir()
+		cfg := storage.DefaultConfig()
+		cfg.Local.Root = tempDir
+
+		cfgBytes, _ := json.Marshal(cfg)
+		payload := UpdateSystemConfigRequest{
+			Value: string(cfgBytes),
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/system-configs/storage_config", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		// Verify database
+		var dbCfg model.SystemConfig
+		dbConn.Where("key = ?", "storage_config").First(&dbCfg)
+		var savedCfg storage.Config
+		_ = json.Unmarshal([]byte(dbCfg.Value), &savedCfg)
+		if savedCfg.Local.Root != tempDir {
+			t.Errorf("expected local root to be updated to %s, got %s", tempDir, savedCfg.Local.Root)
+		}
+	})
+
+	t.Run("update storage config failed connectivity check", func(t *testing.T) {
+		cfg := storage.DefaultConfig()
+		cfg.Driver = storage.DriverS3
+		cfg.S3.Bucket = "non-existent-bucket"
+		cfg.S3.Endpoint = "http://127.0.0.1:9999" // Will fail connectivity check
+
+		cfgBytes, _ := json.Marshal(cfg)
+		payload := UpdateSystemConfigRequest{
+			Value: string(cfgBytes),
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/system-configs/storage_config", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("expected 400 Bad Request, got %d. Body: %s", w.Code, w.Body.String())
+		}
+	})
+}