refactor(repo): consolidate openflare-server to root and move subprojects to internal/apps

- Merge all files inside openflare-server to the repository root directory.
- Relocate agent, relay, and flared subprojects from internal/ to internal/apps/.
- Combine docker-compose files and update build context paths to root.
- Update GitHub workflows and Dockerfiles to refer to new directories and package names.
- Rewrite Go package imports across all files.
- Resolve database renew test race condition and clean up docs.

internal/apps/admin/system_config/errs.go

@@ -0,0 +1,15 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package system_config 提供系统配置管理功能
+package system_config
+
+// 系统配置错误消息常量
+const (
+	SystemConfigNotFound                 = "系统配置不存在"
+	ConfigKeyRequired                    = "配置键不能为空"
+	ConfigValueRequired                  = "配置值不能为空"
+	ConfigKeyExists                      = "配置键已存在"
+	StorageDriverSwitchRequiresMigration = "存在存量文件，请通过存储迁移任务切换存储引擎"
+)

internal/apps/admin/system_config/logics.go

@@ -0,0 +1,128 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package system_config
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/storage"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	"gorm.io/gorm"
+)
+
+func createSystemConfig(ctx context.Context, req CreateSystemConfigRequest) error {
+	exists, err := repository.SystemConfigExists(ctx, req.Key)
+	if err != nil {
+		return err
+	}
+	if exists {
+		return errors.New(ConfigKeyExists)
+	}
+
+	config := model.SystemConfig{
+		Key:         req.Key,
+		Value:       req.Value,
+		Type:        req.Type,
+		Visibility:  req.Visibility,
+		Description: req.Description,
+	}
+	if err := repository.CreateSystemConfig(ctx, &config); err != nil {
+		return err
+	}
+
+	invalidateSystemConfigCaches(ctx, req.Key)
+	if err := repository.InvalidateVisibleSystemConfigsCache(ctx); err != nil {
+		logger.WarnF(ctx, "清理公共配置列表缓存失败: %v", err)
+	}
+	return nil
+}
+
+func listSystemConfigs(ctx context.Context, configType string) ([]model.SystemConfig, error) {
+	return repository.ListAdminSystemConfigs(ctx, configType)
+}
+
+func getSystemConfig(ctx context.Context, key string) (model.SystemConfig, error) {
+	return repository.GetAdminSystemConfigByKey(ctx, key)
+}
+
+func updateSystemConfig(ctx context.Context, key string, req UpdateSystemConfigRequest) error {
+	config, err := repository.GetAdminSystemConfigByKey(ctx, key)
+	if err != nil {
+		return err
+	}
+
+	var originalDriver storage.Driver
+	if key == model.ConfigKeyStorageConfig {
+		var currentCfg storage.Config
+		if err := json.Unmarshal([]byte(config.Value), &currentCfg); err == nil {
+			originalDriver = currentCfg.Driver
+		}
+
+		validatedVal, err := validateAndMergeStorageConfig(ctx, req.Value, config.Value)
+		if err != nil {
+			return err
+		}
+		req.Value = validatedVal
+	}
+
+	if err := db.DB(ctx).Transaction(func(tx *gorm.DB) error {
+		updates := map[string]any{
+			"description": req.Description,
+		}
+		if req.Visibility != nil {
+			updates["visibility"] = *req.Visibility
+			config.Visibility = *req.Visibility
+		}
+		if key != model.ConfigKeySMTPPassword || req.Value != maskedConfigValue {
+			updates["value"] = req.Value
+			config.Value = req.Value
+		}
+		if err := tx.Model(&config).Updates(updates).Error; err != nil {
+			return err
+		}
+		resolveStorageMigrationTasksOnDirectDriverUpdate(ctx, tx, key, originalDriver, req.Value)
+		return nil
+	}); err != nil {
+		return err
+	}
+
+	invalidateCachesAfterConfigUpdate(ctx, key)
+	return nil
+}
+
+func resolveStorageMigrationTasksOnDirectDriverUpdate(
+	ctx context.Context,
+	tx *gorm.DB,
+	key string,
+	originalDriver storage.Driver,
+	newValue string,
+) {
+	if key != model.ConfigKeyStorageConfig || originalDriver == "" {
+		return
+	}
+
+	var newCfg storage.Config
+	if err := json.Unmarshal([]byte(newValue), &newCfg); err != nil {
+		return
+	}
+	if newCfg.Driver != originalDriver {
+		return
+	}
+
+	if err := tx.Model(&model.TaskExecution{}).
+		Where("task_type = ? AND status = ?", "storage:migrate", model.TaskExecutionStatusFailed).
+		Updates(map[string]any{
+			"status":      model.TaskExecutionStatusSucceeded,
+			"result":      "存储配置直接更新，故障迁移任务自动标记为已解决",
+			"finished_at": time.Now(),
+		}).Error; err != nil {
+		logger.ErrorF(ctx, "自动更新迁移任务状态失败: %v", err)
+	}
+}

internal/apps/admin/system_config/routers.go

@@ -0,0 +1,365 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package system_config
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/cap"
+	"github.com/Rain-kl/Wavelet/internal/apps/upload"
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/storage"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	mail "github.com/Rain-kl/Wavelet/pkg/mail"
+)
+
+const maskedConfigValue = "******"
+
+// CreateSystemConfigRequest 创建系统配置请求
+type CreateSystemConfigRequest struct {
+	Key         string `json:"key" binding:"required,max=64"`
+	Value       string `json:"value" binding:"required"`
+	Type        string `json:"type" binding:"required,oneof=system business"`
+	Visibility  int    `json:"visibility" binding:"oneof=0 1"`
+	Description string `json:"description" binding:"max=255"`
+}
+
+// UpdateSystemConfigRequest 更新系统配置请求
+type UpdateSystemConfigRequest struct {
+	Value       string `json:"value" binding:"required"`
+	Visibility  *int   `json:"visibility" binding:"omitempty,oneof=0 1"`
+	Description string `json:"description" binding:"max=255"`
+}
+
+// CreateSystemConfig 创建系统配置
+// @Summary 创建系统配置
+// @Description 创建一条新的系统配置项，配置键不可重复，同时将新配置同步到 Redis，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body system_config.CreateSystemConfigRequest true "创建请求参数"
+// @Success 200 {object} response.Any{data=string} "创建成功"
+// @Failure 400 {object} response.Any "参数错误或配置键已存在"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/system-configs [post]
+func CreateSystemConfig(c *gin.Context) {
+	var req CreateSystemConfigRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if err := createSystemConfig(c.Request.Context(), req); err != nil {
+		if err.Error() == ConfigKeyExists {
+			response.AbortBadRequest(c, ConfigKeyExists)
+			return
+		}
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// ListSystemConfigs 获取系统配置列表
+// @Summary 获取系统配置列表
+// @Description 返回所有系统配置列表，支持按配置类型（system/business）过滤，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param type query string false "配置类型（system/business）"
+// @Success 200 {object} response.Any{data=[]model.SystemConfig} "系统配置列表"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/system-configs [get]
+func ListSystemConfigs(c *gin.Context) {
+	configs, err := listSystemConfigs(c.Request.Context(), c.Query("type"))
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	for i := range configs {
+		configs[i].Value = maskSensitiveConfig(configs[i].Key, configs[i].Value)
+	}
+
+	c.JSON(http.StatusOK, response.OK(configs))
+}
+
+// GetSystemConfig 获取单个系统配置
+// @Summary 获取单个系统配置
+// @Description 根据配置键获取对应的系统配置详情，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param key path string true "配置键"
+// @Success 200 {object} response.Any{data=model.SystemConfig} "系统配置详情"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 404 {object} response.Any "配置不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/system-configs/{key} [get]
+func GetSystemConfig(c *gin.Context) {
+	config, err := getSystemConfig(c.Request.Context(), c.Param("key"))
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			response.AbortNotFound(c, SystemConfigNotFound)
+		} else {
+			response.AbortInternal(c, err.Error())
+		}
+		return
+	}
+
+	config.Value = maskSensitiveConfig(config.Key, config.Value)
+
+	c.JSON(http.StatusOK, response.OK(config))
+}
+
+// UpdateSystemConfig 更新系统配置
+// @Summary 更新系统配置
+// @Description 根据配置键更新对应的配置内容，同时将更新同步到 Redis，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param key path string true "配置键"
+// @Param request body system_config.UpdateSystemConfigRequest true "更新请求参数"
+// @Success 200 {object} response.Any{data=string} "更新成功"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 404 {object} response.Any "配置不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/system-configs/{key} [put]
+func UpdateSystemConfig(c *gin.Context) {
+	var req UpdateSystemConfigRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	key := c.Param("key")
+	if err := updateSystemConfig(c.Request.Context(), key, req); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			response.AbortNotFound(c, SystemConfigNotFound)
+			return
+		}
+		if isStorageConfigValidationError(err) {
+			response.AbortBadRequest(c, err.Error())
+			return
+		}
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+func invalidateSystemConfigCaches(ctx context.Context, key string) {
+	if err := repository.InvalidateSystemConfigCache(ctx, key); err != nil {
+		logger.WarnF(ctx, "清理系统配置缓存失败: %v", err)
+	}
+	if cap.IsRuntimeConfigKey(key) {
+		cap.InvalidateRuntimeSettings()
+	}
+}
+
+func invalidateCachesAfterConfigUpdate(ctx context.Context, key string) {
+	invalidateSystemConfigCaches(ctx, key)
+
+	if key == model.ConfigKeyStorageConfig {
+		upload.ResetAccessCaches()
+		upload.PublishAccessCacheInvalidation(ctx)
+		storage.ResetCache()
+		storage.PublishCacheInvalidation(ctx)
+	}
+	if key == model.ConfigKeyFileAccessWhitelist {
+		upload.ResetAccessCaches()
+		upload.PublishAccessCacheInvalidation(ctx)
+	}
+
+	if err := repository.InvalidateVisibleSystemConfigsCache(ctx); err != nil {
+		logger.WarnF(ctx, "清理公共配置列表缓存失败: %v", err)
+	}
+}
+
+// TestSMTPRequest 测试 SMTP 配置请求
+type TestSMTPRequest struct {
+	SMTPHost     string `json:"smtp_host" binding:"required,max=255"`
+	SMTPPort     int    `json:"smtp_port" binding:"required"`
+	SMTPUsername string `json:"smtp_username" binding:"required,max=255"`
+	SMTPPassword string `json:"smtp_password" binding:"required,max=255"`
+	To           string `json:"to" binding:"required,email"`
+}
+
+// TestSMTPResponse 测试 SMTP 配置响应
+type TestSMTPResponse struct {
+	Success bool   `json:"success"`
+	Log     string `json:"log"`
+	Error   string `json:"error"`
+}
+
+// TestSMTP 测试 SMTP 邮件发送
+// @Summary 测试 SMTP 邮件发送
+// @Description 使用传入的配置进行 SMTP 邮件发送测试，支持使用 ****** 占位符使用保存的数据库密码
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body system_config.TestSMTPRequest true "测试请求参数"
+// @Success 200 {object} response.Any{data=system_config.TestSMTPResponse} "测试执行完毕"
+// @Failure 400 {object} response.Any "参数错误"
+// @Router /api/v1/admin/system-configs/smtp/test [post]
+func TestSMTP(c *gin.Context) {
+	var req TestSMTPRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	password := req.SMTPPassword
+	if password == maskedConfigValue {
+		if sc, err := repository.GetSystemConfigByKey(c.Request.Context(), model.ConfigKeySMTPPassword); err == nil {
+			password = sc.Value
+		}
+	}
+
+	cfg := mail.Config{
+		Host:     req.SMTPHost,
+		Port:     req.SMTPPort,
+		Username: req.SMTPUsername,
+		Password: password,
+	}
+
+	subject := "OpenFlare SMTP Test Mail"
+	body := `<h3>SMTP Mail Connection Test</h3>
+<p>If you received this message, your SMTP configuration is correct and mail sending is working properly.</p>
+<p>Sent from OpenFlare.</p>`
+
+	logs, err := mail.SendMailWithLog(c.Request.Context(), cfg, req.To, subject, body)
+	resp := TestSMTPResponse{
+		Success: err == nil,
+		Log:     logs,
+	}
+	if err != nil {
+		resp.Error = err.Error()
+	}
+
+	c.JSON(http.StatusOK, response.OK(resp))
+}
+
+func isStorageConfigValidationError(err error) bool {
+	msg := err.Error()
+	return msg == StorageDriverSwitchRequiresMigration ||
+		strings.HasPrefix(msg, "解析") ||
+		strings.HasPrefix(msg, "验证") ||
+		strings.HasPrefix(msg, "初始化测试") ||
+		strings.HasPrefix(msg, "存储连通性") ||
+		strings.HasPrefix(msg, "序列化") ||
+		strings.HasPrefix(msg, "检查存量文件")
+}
+
+func maskSensitiveConfig(key, value string) string {
+	if value == "" {
+		return value
+	}
+	switch key {
+	case model.ConfigKeySMTPPassword:
+		return maskedConfigValue
+	case model.ConfigKeyStorageConfig:
+		var cfg storage.Config
+		if err := json.Unmarshal([]byte(value), &cfg); err == nil {
+			masked := storage.MaskSecrets(cfg)
+			if val, err := json.Marshal(masked); err == nil {
+				return string(val)
+			}
+		}
+	}
+	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 := validateMergedStorageConfig(ctx, currentCfg, newCfg, targetCfg); err != nil {
+		return "", err
+	}
+
+	// 序列化为最终保存的真实明文配置，防止保存屏蔽的 ****** 字符
+	unmaskedVal, err := json.Marshal(targetCfg)
+	if err != nil {
+		return "", fmt.Errorf("序列化存储配置失败: %w", err)
+	}
+
+	return string(unmaskedVal), nil
+}
+
+func validateMergedStorageConfig(ctx context.Context, currentCfg, newCfg, targetCfg storage.Config) error {
+	if newCfg.Driver != "" && newCfg.Driver != currentCfg.Driver {
+		var uploadCount int64
+		if err := db.DB(ctx).Model(&model.Upload{}).
+			Where("status != ?", model.UploadStatusDeleted).
+			Count(&uploadCount).Error; err != nil {
+			return fmt.Errorf("检查存量文件失败: %w", err)
+		}
+		if uploadCount > 0 {
+			return errors.New(StorageDriverSwitchRequiresMigration)
+		}
+		if err := validateDriverConfig(targetCfg, newCfg.Driver); err != nil {
+			return fmt.Errorf("验证目标存储配置参数失败: %w", err)
+		}
+		pendingCfg := targetCfg
+		pendingCfg.Driver = newCfg.Driver
+		return testStorageBackend(ctx, pendingCfg, newCfg.Driver)
+	}
+
+	if err := storage.ValidateConfig(targetCfg); err != nil {
+		return fmt.Errorf("验证存储配置参数失败: %w", err)
+	}
+	return testStorageBackend(ctx, targetCfg, targetCfg.Driver)
+}
+
+func validateDriverConfig(cfg storage.Config, driver storage.Driver) error {
+	cfg.Driver = driver
+	return storage.ValidateConfig(cfg)
+}
+
+func testStorageBackend(ctx context.Context, cfg storage.Config, driver storage.Driver) error {
+	testBackend, err := storage.NewBackend(ctx, cfg, driver)
+	if err != nil {
+		return fmt.Errorf("初始化测试存储实例失败: %w", err)
+	}
+	if err := testBackend.Test(ctx); err != nil {
+		return fmt.Errorf("存储连通性测试失败: %w", err)
+	}
+	return nil
+}

internal/apps/admin/system_config/routers_test.go

@@ -0,0 +1,543 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package system_config
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"net/textproto"
+	"strings"
+	"testing"
+
+	"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/repository"
+	"github.com/Rain-kl/Wavelet/internal/storage"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+const expectedDefaultConfigsCount = 30
+
+func setupTestRouter(authUser *model.User) *gin.Engine {
+	r := testhelper.NewTestGinEngine()
+	adminGroup := r.Group("/api/v1/admin")
+
+	// Mock authentication middleware
+	adminGroup.Use(func(c *gin.Context) {
+		if authUser != nil {
+			oauth.SetToContext(c, oauth.UserObjKey, authUser)
+		}
+		c.Next()
+	})
+
+	adminGroup.POST("/system-configs", CreateSystemConfig)
+	adminGroup.GET("/system-configs", ListSystemConfigs)
+
+	systemConfigRouter := adminGroup.Group("/system-configs/:key")
+	{
+		systemConfigRouter.GET("", GetSystemConfig)
+		systemConfigRouter.PUT("", UpdateSystemConfig)
+	}
+
+	return r
+}
+
+func TestCreateSystemConfig(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("create successfully", func(t *testing.T) {
+		payload := CreateSystemConfigRequest{
+			Key:         "custom_key",
+			Value:       "custom_value",
+			Type:        "system",
+			Visibility:  model.ConfigVisibilityVisible,
+			Description: "desc",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/system-configs", 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 cfg model.SystemConfig
+		err := dbConn.Where("key = ?", "custom_key").First(&cfg).Error
+		if err != nil {
+			t.Fatalf("failed to find system config in DB: %v", err)
+		}
+
+		// Verify caches are invalidated after create and repopulate on read
+		_, err = db.Redis.HGet(
+			context.Background(),
+			db.PrefixedKey(repository.SystemConfigRedisHashKey),
+			"custom_key",
+		).Result()
+		if err == nil {
+			t.Fatal("expected redis cache miss immediately after create")
+		}
+
+		loaded, err := repository.GetSystemConfigByKey(context.Background(), "custom_key")
+		if err != nil {
+			t.Fatalf("GetSystemConfigByKey(custom_key) error = %v", err)
+		}
+		if loaded.Value != "custom_value" {
+			t.Errorf("GetSystemConfigByKey(custom_key).Value = %q, want %q", loaded.Value, "custom_value")
+		}
+		if loaded.Visibility != model.ConfigVisibilityVisible {
+			t.Errorf("GetSystemConfigByKey(custom_key).Visibility = %d, want %d", loaded.Visibility, model.ConfigVisibilityVisible)
+		}
+	})
+
+	t.Run("create duplicate key error", func(t *testing.T) {
+		// Key "custom_key" already exists from previous test
+		payload := CreateSystemConfigRequest{
+			Key:         "custom_key",
+			Value:       "another_value",
+			Type:        "system",
+			Description: "desc",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/system-configs", 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 on duplicate key, got %d", w.Code)
+		}
+	})
+}
+
+func TestListSystemConfigs(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("list all seeded configurations", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/system-configs", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d", w.Code)
+		}
+
+		var resp response.Any
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var configs []model.SystemConfig
+		_ = json.Unmarshal(dataBytes, &configs)
+
+		// Defaults seed configurations
+		if len(configs) != expectedDefaultConfigsCount {
+			t.Errorf("expected %d default configs, got %d", expectedDefaultConfigsCount, len(configs))
+		}
+	})
+
+	t.Run("filter by type business", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/system-configs?type=business", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		var resp response.Any
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var configs []model.SystemConfig
+		_ = json.Unmarshal(dataBytes, &configs)
+
+		if len(configs) != 1 || configs[0].Key != model.ConfigKeyMaxAPIKeysPerUser {
+			t.Errorf("expected 1 business config (max_api_keys_per_user), got %d: %v", len(configs), configs)
+		}
+	})
+}
+
+func TestGetSystemConfig(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("get existing configuration", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/system-configs/"+model.ConfigKeySiteName, nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("expected 200 OK, got %d", w.Code)
+		}
+
+		var resp response.Any
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var cfg model.SystemConfig
+		_ = json.Unmarshal(dataBytes, &cfg)
+
+		if cfg.Value != "OpenFlare" {
+			t.Errorf("expected 'OpenFlare', got '%s'", cfg.Value)
+		}
+	})
+
+	t.Run("get non-existent config", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/system-configs/non_existent_key", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusNotFound {
+			t.Errorf("expected 404 Not Found, got %d", w.Code)
+		}
+	})
+}
+
+func TestUpdateSystemConfig(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 successfully", func(t *testing.T) {
+		hidden := model.ConfigVisibilityHidden
+		payload := UpdateSystemConfigRequest{
+			Value:       "Super Site Name",
+			Visibility:  &hidden,
+			Description: "Updated Description",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/system-configs/"+model.ConfigKeySiteName, 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 cfg model.SystemConfig
+		dbConn.Where("key = ?", model.ConfigKeySiteName).First(&cfg)
+		if cfg.Value != "Super Site Name" || cfg.Description != "Updated Description" || cfg.Visibility != model.ConfigVisibilityHidden {
+			t.Errorf("database values not updated: %+v", cfg)
+		}
+
+		// Verify caches are invalidated after update and repopulate on read
+		_, err := db.Redis.HGet(
+			context.Background(),
+			db.PrefixedKey(repository.SystemConfigRedisHashKey),
+			model.ConfigKeySiteName,
+		).Result()
+		if err == nil {
+			t.Fatal("expected redis cache miss immediately after update")
+		}
+
+		loaded, err := repository.GetSystemConfigByKey(context.Background(), model.ConfigKeySiteName)
+		if err != nil {
+			t.Fatalf("GetSystemConfigByKey(site_name) error = %v", err)
+		}
+		if loaded.Value != "Super Site Name" {
+			t.Errorf("GetSystemConfigByKey(site_name).Value = %q, want %q", loaded.Value, "Super Site Name")
+		}
+		if loaded.Visibility != model.ConfigVisibilityHidden {
+			t.Errorf("GetSystemConfigByKey(site_name).Visibility = %d, want %d", loaded.Visibility, model.ConfigVisibilityHidden)
+		}
+	})
+
+	t.Run("update non-existent config", func(t *testing.T) {
+		payload := UpdateSystemConfigRequest{
+			Value: "New Value",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/system-configs/invalid_key", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusNotFound {
+			t.Errorf("expected 404 Not Found, got %d", w.Code)
+		}
+	})
+}
+
+func TestTestSMTP(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	r := setupTestRouter(adminUser)
+	r.POST("/api/v1/admin/system-configs/smtp/test", TestSMTP)
+
+	// Start a mock SMTP server
+	l, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("failed to start mock smtp server: %v", err)
+	}
+	defer func() { _ = l.Close() }()
+
+	port := l.Addr().(*net.TCPAddr).Port
+
+	go func() {
+		conn, err := l.Accept()
+		if err != nil {
+			return
+		}
+		defer func() { _ = conn.Close() }()
+
+		writer := bufio.NewWriter(conn)
+		reader := bufio.NewReader(conn)
+		tp := textproto.NewReader(reader)
+
+		// 220 Ready
+		_, _ = writer.WriteString("220 mock.smtp.com SMTP Ready\r\n")
+		_ = writer.Flush()
+
+		// Read HELO/EHLO
+		_, _ = tp.ReadLine()
+		_, _ = writer.WriteString("250-mock.smtp.com\r\n250 AUTH PLAIN\r\n")
+		_ = writer.Flush()
+
+		// Read AUTH PLAIN
+		_, _ = tp.ReadLine()
+		_, _ = writer.WriteString("235 Authentication successful\r\n")
+		_ = writer.Flush()
+
+		// Read MAIL FROM
+		_, _ = tp.ReadLine()
+		_, _ = writer.WriteString("250 OK\r\n")
+		_ = writer.Flush()
+
+		// Read RCPT TO
+		_, _ = tp.ReadLine()
+		_, _ = writer.WriteString("250 OK\r\n")
+		_ = writer.Flush()
+
+		// Read DATA
+		_, _ = tp.ReadLine()
+		_, _ = writer.WriteString("354 Start mail input\r\n")
+		_ = writer.Flush()
+
+		// Read body lines until dot
+		for {
+			line, err := tp.ReadLine()
+			if err != nil || line == "." {
+				break
+			}
+		}
+		_, _ = writer.WriteString("250 OK\r\n")
+		_ = writer.Flush()
+
+		// Read QUIT
+		_, _ = tp.ReadLine()
+		_, _ = writer.WriteString("221 Bye\r\n")
+		_ = writer.Flush()
+	}()
+
+	payload := TestSMTPRequest{
+		SMTPHost:     "127.0.0.1",
+		SMTPPort:     port,
+		SMTPUsername: "sender@example.com",
+		SMTPPassword: "password",
+		To:           "recipient@example.com",
+	}
+
+	body, _ := json.Marshal(payload)
+	req, _ := http.NewRequest("POST", "/api/v1/admin/system-configs/smtp/test", bytes.NewBuffer(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+	}
+
+	var resp response.Any
+	json.Unmarshal(w.Body.Bytes(), &resp)
+
+	dataBytes, _ := json.Marshal(resp.Data)
+	var testResp TestSMTPResponse
+	json.Unmarshal(dataBytes, &testResp)
+
+	if !testResp.Success {
+		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())
+		}
+	})
+
+	t.Run("reject driver switch when uploads exist", func(t *testing.T) {
+		upload := model.Upload{
+			ID:        88001,
+			UserID:    1,
+			FileName:  "keep.txt",
+			FilePath:  "uploads/keep.txt",
+			FileSize:  4,
+			MimeType:  "text/plain",
+			Extension: "txt",
+			Type:      "attachment",
+			Status:    model.UploadStatusUsed,
+		}
+		if err := dbConn.Create(&upload).Error; err != nil {
+			t.Fatalf("seed upload failed: %v", err)
+		}
+
+		tempDir := t.TempDir()
+		cfg := storage.DefaultConfig()
+		cfg.Driver = storage.DriverS3
+		cfg.S3.Endpoint = "http://127.0.0.1:19998"
+		cfg.S3.Region = "us-east-1"
+		cfg.S3.Bucket = "wavelet"
+		cfg.S3.AccessKeyID = "test"
+		cfg.S3.SecretAccessKey = "test"
+		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.StatusBadRequest {
+			t.Fatalf("expected 400 Bad Request, got %d. Body: %s", w.Code, w.Body.String())
+		}
+		if !strings.Contains(w.Body.String(), StorageDriverSwitchRequiresMigration) {
+			t.Fatalf("expected migration-required error, got: %s", w.Body.String())
+		}
+	})
+
+	t.Run("switch to local while active s3 is unreachable", func(t *testing.T) {
+		if err := dbConn.Where("1 = 1").Delete(&model.Upload{}).Error; err != nil {
+			t.Fatalf("clear uploads failed: %v", err)
+		}
+
+		activeCfg := storage.DefaultConfig()
+		activeCfg.Driver = storage.DriverS3
+		activeCfg.S3.Endpoint = "http://127.0.0.1:9999"
+		activeCfg.S3.Region = "us-east-1"
+		activeCfg.S3.Bucket = "wavelet"
+		activeCfg.S3.AccessKeyID = "test"
+		activeCfg.S3.SecretAccessKey = "test"
+		activeBytes, _ := json.Marshal(activeCfg)
+		seedCfg := model.SystemConfig{
+			Key:   "storage_config",
+			Value: string(activeBytes),
+			Type:  "system",
+		}
+		if err := dbConn.Where("key = ?", "storage_config").
+			Assign(map[string]any{"value": seedCfg.Value, "type": seedCfg.Type}).
+			FirstOrCreate(&seedCfg).Error; err != nil {
+			t.Fatalf("seed active storage config failed: %v", err)
+		}
+
+		tempDir := t.TempDir()
+		stagedCfg := activeCfg
+		stagedCfg.Driver = storage.DriverLocal
+		stagedCfg.Local.Root = tempDir
+
+		cfgBytes, _ := json.Marshal(stagedCfg)
+		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())
+		}
+
+		var dbCfg model.SystemConfig
+		if err := dbConn.Where("key = ?", "storage_config").First(&dbCfg).Error; err != nil {
+			t.Fatalf("load saved storage config failed: %v", err)
+		}
+		var savedCfg storage.Config
+		if err := json.Unmarshal([]byte(dbCfg.Value), &savedCfg); err != nil {
+			t.Fatalf("parse saved storage config failed: %v", err)
+		}
+		if savedCfg.Driver != storage.DriverLocal {
+			t.Fatalf("active driver = %q, want %q after save", savedCfg.Driver, storage.DriverLocal)
+		}
+		if savedCfg.Local.Root != tempDir {
+			t.Fatalf("staged local root = %q, want %q", savedCfg.Local.Root, tempDir)
+		}
+	})
+}