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.

frontend/components/common/admin/storage-config-tab.tsx

@@ -247,66 +247,78 @@ export function StorageConfigTab() {
         </Card>
       )}
 
-      <Card>
-        <CardHeader>
-          <CardTitle className="flex items-center gap-2">
-            <Database />
-            文件存储
-          </CardTitle>
-          <CardDescription>
-            默认使用本地存储。切换存储类型且已有文件时，系统会自动进入维护模式并迁移文件。
-          </CardDescription>
+      <Card className="border border-dashed shadow-sm">
+        <CardHeader className="border-b border-dashed pb-4">
+          <div className="flex items-center gap-2">
+            <div className="rounded-lg bg-indigo-500/10 p-1.5 text-indigo-500">
+              <Database className="size-4" />
+            </div>
+            <div>
+              <CardTitle className="text-base font-semibold">文件存储</CardTitle>
+              <CardDescription className="text-xs">
+                默认使用本地存储。配置系统文件的存储媒介，切换存储类型且已有文件时，系统会自动进入维护模式并迁移文件。
+              </CardDescription>
+            </div>
+          </div>
         </CardHeader>
-        <CardContent>
-          <FieldGroup>
-            <Field>
-              <FieldLabel>存储类型</FieldLabel>
-              <Select
-                value={config.driver}
-                disabled={isFormDisabled}
-                onValueChange={(value) => setConfig({...config, driver: value as StorageDriver})}
-              >
-                <SelectTrigger className="w-full">
-                  <SelectValue />
-                </SelectTrigger>
-                <SelectContent>
-                  <SelectGroup>
-                    {(Object.keys(driverLabels) as StorageDriver[]).map((driver) => (
-                      <SelectItem key={driver} value={driver}>{driverLabels[driver]}</SelectItem>
-                    ))}
-                  </SelectGroup>
-                </SelectContent>
-              </Select>
-            </Field>
+        <CardContent className="pt-6">
+          <FieldGroup className="space-y-6">
+            <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
+              <Field className="flex flex-col gap-1.5 md:col-span-2">
+                <FieldLabel className="text-xs font-semibold">存储类型</FieldLabel>
+                <Select
+                  value={config.driver}
+                  disabled={isFormDisabled}
+                  onValueChange={(value) => setConfig({...config, driver: value as StorageDriver})}
+                >
+                  <SelectTrigger className="w-full border-dashed bg-card text-xs">
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectGroup>
+                      {(Object.keys(driverLabels) as StorageDriver[]).map((driver) => (
+                        <SelectItem key={driver} value={driver}>{driverLabels[driver]}</SelectItem>
+                      ))}
+                    </SelectGroup>
+                  </SelectContent>
+                </Select>
+              </Field>
 
-            {config.driver === "local" && (
-              <TextField
-                label="根目录"
-                value={config.local.root}
-                placeholder="."
-                onChange={(root) => setConfig({...config, local: {root}})}
-              />
-            )}
+              {config.driver === "local" && (
+                <div className="md:col-span-2">
+                  <TextField
+                    label="根目录"
+                    value={config.local.root}
+                    placeholder="."
+                    onChange={(root) => setConfig({...config, local: {root}})}
+                  />
+                </div>
+              )}
 
-            {(config.driver === "s3" || config.driver === "r2" || config.driver === "minio" || config.driver === "oss") && (
-              <ObjectFields
-                driver={config.driver as "s3" | "r2" | "minio" | "oss"}
-                value={config[config.driver as "s3" | "r2" | "minio" | "oss"]}
-                onChange={(patch) => updateObject(config.driver as "s3" | "r2" | "minio" | "oss", patch)}
-              />
-            )}
+              {(config.driver === "s3" || config.driver === "r2" || config.driver === "minio" || config.driver === "oss") && (
+                <ObjectFields
+                  driver={config.driver as "s3" | "r2" | "minio" | "oss"}
+                  value={config[config.driver as "s3" | "r2" | "minio" | "oss"]}
+                  onChange={(patch) => updateObject(config.driver as "s3" | "r2" | "minio" | "oss", patch)}
+                />
+              )}
 
-            {config.driver === "webdav" && (
-              <>
-                <TextField label="服务地址" value={config.webdav.endpoint} placeholder="https://dav.example.com" onChange={(endpoint) => setConfig({...config, webdav: {...config.webdav, endpoint}})} />
-                <TextField label="用户名" value={config.webdav.username} onChange={(username) => setConfig({...config, webdav: {...config.webdav, username}})} />
-                <TextField label="密码" type="password" value={config.webdav.password} onChange={(password) => setConfig({...config, webdav: {...config.webdav, password}})} />
-                <TextField label="基础路径" value={config.webdav.base_path} placeholder="wavelet" onChange={(base_path) => setConfig({...config, webdav: {...config.webdav, base_path}})} />
-              </>
-            )}
+              {config.driver === "webdav" && (
+                <>
+                  <div className="md:col-span-2">
+                    <TextField label="服务地址" value={config.webdav.endpoint} placeholder="https://dav.example.com" onChange={(endpoint) => setConfig({...config, webdav: {...config.webdav, endpoint}})} />
+                  </div>
+                  <TextField label="用户名" value={config.webdav.username} onChange={(username) => setConfig({...config, webdav: {...config.webdav, username}})} />
+                  <TextField label="密码" type="password" value={config.webdav.password} onChange={(password) => setConfig({...config, webdav: {...config.webdav, password}})} />
+                  <div className="md:col-span-2">
+                    <TextField label="基础路径" value={config.webdav.base_path} placeholder="wavelet" onChange={(base_path) => setConfig({...config, webdav: {...config.webdav, base_path}})} />
+                  </div>
+                </>
+              )}
+            </div>
           </FieldGroup>
         </CardContent>
-        <CardFooter className="justify-end gap-2 flex-col sm:flex-row items-end sm:items-center">
+        <CardFooter className="justify-end gap-2 flex-col sm:flex-row items-end sm:items-center border-t border-dashed pt-4 mt-6">
           {config.driver !== query.data?.config.driver && (
             <span className="text-xs text-amber-500 mr-auto text-left max-w-md">
               ⚠️ 您已切换存储类型。请先点击“保存配置”保存各存储端的配置凭据，然后点击“开始迁移”手动执行文件迁移。
@@ -317,6 +329,7 @@ export function StorageConfigTab() {
               variant="outline"
               disabled={isFormDisabled}
               onClick={() => saveMutation.mutate(config)}
+              className="border-dashed"
             >
               {saveMutation.isPending ? <Loader2 data-icon="inline-start" className="animate-spin" /> : <Save data-icon="inline-start" />}
               保存配置
@@ -348,8 +361,16 @@ function ObjectFields({
 }) {
   return (
     <>
-      {driver === "r2" && <TextField label="Account ID" value={value.account_id || ""} onChange={(account_id) => onChange({account_id})} />}
-      {driver !== "s3" && <TextField label="Endpoint" value={value.endpoint} placeholder="https://..." onChange={(endpoint) => onChange({endpoint})} />}
+      {driver === "r2" && (
+        <div className="md:col-span-2">
+          <TextField label="Account ID" value={value.account_id || ""} onChange={(account_id) => onChange({account_id})} />
+        </div>
+      )}
+      {driver !== "s3" && (
+        <div className="md:col-span-2">
+          <TextField label="Endpoint" value={value.endpoint} placeholder="https://..." onChange={(endpoint) => onChange({endpoint})} />
+        </div>
+      )}
       <TextField label="Region" value={value.region} onChange={(region) => onChange({region})} />
       <TextField label="Bucket" value={value.bucket} onChange={(bucket) => onChange({bucket})} />
       <TextField label="Access Key ID" value={value.access_key_id} onChange={(access_key_id) => onChange({access_key_id})} />
@@ -357,11 +378,15 @@ function ObjectFields({
       <TextField label="对象前缀" value={value.key_prefix} placeholder="uploads" onChange={(key_prefix) => onChange({key_prefix})} />
       <TextField label="CDN 地址" value={value.cdn_url} placeholder="https://cdn.example.com" onChange={(cdn_url) => onChange({cdn_url})} />
       {(driver === "s3" || driver === "minio") && (
-        <Field orientation="horizontal">
-          <FieldLabel>Path Style</FieldLabel>
-          <Switch checked={value.path_style} onCheckedChange={(path_style) => onChange({path_style})} />
-          <FieldDescription>MinIO 等自托管 S3 通常需要开启。</FieldDescription>
-        </Field>
+        <div className="md:col-span-2">
+          <Field orientation="horizontal" className="flex items-center justify-between border border-dashed rounded-lg p-4 bg-muted/30">
+            <div className="flex flex-col gap-0.5">
+              <FieldLabel className="text-xs font-semibold cursor-pointer">Path Style</FieldLabel>
+              <FieldDescription className="text-[11px] leading-relaxed text-muted-foreground">MinIO 等自托管 S3 通常需要开启。</FieldDescription>
+            </div>
+            <Switch checked={value.path_style} onCheckedChange={(path_style) => onChange({path_style})} />
+          </Field>
+        </div>
       )}
     </>
   )
@@ -381,9 +406,15 @@ function TextField({
   type?: React.HTMLInputTypeAttribute
 }) {
   return (
-    <Field>
-      <FieldLabel>{label}</FieldLabel>
-      <Input type={type} value={value} placeholder={placeholder} onChange={(event) => onChange(event.target.value)} />
+    <Field className="flex flex-col gap-1.5">
+      <FieldLabel className="text-xs font-semibold">{label}</FieldLabel>
+      <Input
+        type={type}
+        value={value}
+        placeholder={placeholder}
+        onChange={(event) => onChange(event.target.value)}
+        className="border-dashed bg-card text-xs"
+      />
     </Field>
   )
 }

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())
+		}
+	})
+}