feat: 区分 server 与 desktop 配置加载入口，取消自动创建配置文件

- config.go 重构：抽取 loadConfig 共享逻辑，新增 LoadServerConfig/LoadDesktopConfig/LoadDesktopConfigAtPath，LoadConfig 保持向后兼容 - setupConfigFile 移除 SafeWriteConfigAs 自动创建逻辑，文件不存在时仅使用默认值 - cmd/desktop 切换为 LoadDesktopConfig，端口/HTTP/浏览器/托盘统一使用 cfg.Server.Port - cmd/server 显式使用 LoadServerConfig 明确入口语义 - 提取 desktop 可测 helper：desktopListenAddr/desktopURL/desktopPortMenuTitle/desktopConfigErrorMessage - 新增测试：desktop 忽略 CLI/env/未知参数、配置快照不变、无效配置文件不静默回退、端口 helper 一致性 - README 区分 server/desktop 配置源，移除首次启动自动创建配置文件描述 - 同步 delta specs 到 openspec/specs/ 主规范
2026-05-06 11:59:19 +08:00
parent 598e2acb7e
commit 5513f0c13d
10 changed files with 589 additions and 147 deletions
--- a/backend/README.md
+++ b/backend/README.md
@@ -72,7 +72,7 @@ GORM 日志自动桥接到 zap，SQL 查询映射到 Debug 级别。
 - **ORM**: GORM
 - **数据库**: SQLite / MySQL
 - **日志**: zap + lumberjack
- **配置**: Viper + pflag（多层配置：CLI > 环境变量 > 配置文件 > 默认值）
+- **配置**: Viper + pflag（Server 多层配置，Desktop 配置文件快照）
 - **验证**: go-playground/validator/v10
 - **迁移**: goose

@@ -334,15 +334,18 @@ go mod download
 go run cmd/server/main.go
 ```

-服务将在端口 9826 启动。首次启动会自动创建配置文件和运行数据库迁移。
+服务将在端口 9826 启动。首次启动会自动运行数据库迁移。

 ## 配置

-配置支持多种方式：配置文件、环境变量、命令行参数，优先级为：**CLI 参数 > 环境变量 > 配置文件 > 默认值**
+配置方式取决于启动入口：
+
+- **Server 入口**（`cmd/server`）：支持 CLI 参数 > 环境变量 > 配置文件 > 默认值
+- **Desktop 入口**（`cmd/desktop`）：仅支持 `~/.nex/config.yaml` > 默认值，不支持 CLI 参数和 `NEX_*` 环境变量覆盖，修改配置文件后需重启生效

 ### 配置文件

-配置文件位于 `~/.nex/config.yaml`，首次启动自动生成。
+配置文件位于 `~/.nex/config.yaml`。配置文件不存在时使用默认值，不会自动生成；需要自定义时手动创建该文件：

 ```yaml
 server:
@@ -372,9 +375,9 @@ log:
  compress: true
 ```

-### 环境变量
+### 环境变量（仅 Server 入口）

-所有配置项都支持环境变量，使用 `NEX_` 前缀：
+Server 入口下，所有配置项都支持环境变量，使用 `NEX_` 前缀：

 ```bash
 export NEX_SERVER_PORT=9000
@@ -392,7 +395,7 @@ export NEX_DATABASE_DBNAME=nex

 命名规则：配置路径转大写 + 下划线 + `NEX_` 前缀（如 `server.port` → `NEX_SERVER_PORT`）。

-### 命令行参数
+### 命令行参数（仅 Server 入口）

 ```bash
 ./server --server-port 9000 --log-level debug --database-path /tmp/test.db
--- a/backend/cmd/desktop/main.go
+++ b/backend/cmd/desktop/main.go
@@ -43,10 +43,23 @@ var (
 )

 func main() {
-	port := 9826
-
 	minimalLogger := pkgLogger.NewMinimal()

+	cfg, err := config.LoadDesktopConfig()
+	if err != nil {
+		minimalLogger.Error("加载配置失败", zap.Error(err))
+		showError(appName, desktopConfigErrorMessage(getDesktopConfigPath(), err))
+		os.Exit(1)
+	}
+
+	port := cfg.Server.Port
+
+	if err := checkPortAvailable(port); err != nil {
+		minimalLogger.Error("端口不可用", zap.Error(err))
+		showError(appName, err.Error())
+		os.Exit(1)
+	}
+
 	singleLock := NewSingletonLock(filepath.Join(os.TempDir(), "nex-gateway.lock"))
 	if err := singleLock.Lock(); err != nil {
 		minimalLogger.Error("已有 Nex 实例运行")
@@ -59,17 +72,6 @@ func main() {
 		}
 	}()

-	if err := checkPortAvailable(port); err != nil {
-		minimalLogger.Error("端口不可用", zap.Error(err))
-		showError(appName, err.Error())
-		return
-	}
-
-	cfg, err := config.LoadConfig()
-	if err != nil {
-		minimalLogger.Fatal("加载配置失败", zap.Error(err))
-	}
-
 	zapLogger, err = pkgLogger.Upgrade(minimalLogger, pkgLogger.Config{
 		Level:      cfg.Log.Level,
 		Path:       cfg.Log.Path,
@@ -144,7 +146,7 @@ func main() {
 	setupStaticFiles(r)

 	server = &http.Server{
-		Addr:         fmt.Sprintf(":%d", port),
+		Addr:         desktopListenAddr(port),
 		Handler:      r,
 		ReadTimeout:  cfg.Server.ReadTimeout,
 		WriteTimeout: cfg.Server.WriteTimeout,
@@ -165,7 +167,7 @@ func main() {

 	go func() {
 		time.Sleep(500 * time.Millisecond)
-		if err := openBrowser(fmt.Sprintf("http://localhost:%d", port)); err != nil {
+		if err := openBrowser(desktopURL(port)); err != nil {
 			zapLogger.Warn("无法打开浏览器", zap.Error(err))
 		}
 	}()
@@ -309,7 +311,7 @@ func setupSystray(port int) {
 		systray.AddSeparator()
 		mStatus := systray.AddMenuItem("状态: 运行中", "")
 		mStatus.Disable()
-		mPort := systray.AddMenuItem(fmt.Sprintf("端口: %d", port), "")
+		mPort := systray.AddMenuItem(desktopPortMenuTitle(port), "")
 		mPort.Disable()
 		systray.AddSeparator()
 		mQuit := systray.AddMenuItem("退出", "停止服务并退出")
@@ -318,7 +320,7 @@ func setupSystray(port int) {
 			for {
 				select {
 				case <-mOpen.ClickedCh:
-					if err := openBrowser(fmt.Sprintf("http://localhost:%d", port)); err != nil {
+					if err := openBrowser(desktopURL(port)); err != nil {
 						zapLogger.Warn("打开浏览器失败", zap.Error(err))
 					}
 				case <-mQuit.ClickedCh:
@@ -349,6 +351,30 @@ func doShutdown() {
 	}
 }

+func getDesktopConfigPath() string {
+	configDir, err := config.GetConfigDir()
+	if err != nil {
+		return "~/.nex/config.yaml"
+	}
+	return filepath.Join(configDir, "config.yaml")
+}
+
+func desktopConfigErrorMessage(configPath string, err error) string {
+	return fmt.Sprintf("加载配置失败\n\n配置文件: %s\n\n%v", configPath, err)
+}
+
+func desktopListenAddr(port int) string {
+	return fmt.Sprintf(":%d", port)
+}
+
+func desktopURL(port int) string {
+	return fmt.Sprintf("http://localhost:%d", port)
+}
+
+func desktopPortMenuTitle(port int) string {
+	return fmt.Sprintf("端口: %d", port)
+}
+
 func checkPortAvailable(port int) error {
 	ln, err := net.Listen("tcp", fmt.Sprintf(":%d", port))
 	if err != nil {
--- a/backend/cmd/desktop/port_test.go
+++ b/backend/cmd/desktop/port_test.go
@@ -4,6 +4,7 @@ import (
 	"errors"
 	"net"
 	"net/http"
+	"strings"
 	"testing"
 	"time"
 )
@@ -67,3 +68,62 @@ func TestCheckPortAvailableAfterClose(t *testing.T) {

 	t.Log("端口关闭后可用测试通过")
 }
+
+func TestCheckPortAvailableErrorContainsPort(t *testing.T) {
+	port := 19829
+
+	listener, err := net.Listen("tcp", ":19829") //nolint:gosec
+	if err != nil {
+		t.Fatalf("无法启动测试服务器: %v", err)
+	}
+	defer listener.Close()
+
+	time.Sleep(100 * time.Millisecond)
+
+	err = checkPortAvailable(port)
+	if err == nil {
+		t.Fatal("端口被占用时应该返回错误")
+	}
+
+	if !strings.Contains(err.Error(), "19829") {
+		t.Fatalf("错误信息应包含端口号 19829，实际: %v", err)
+	}
+
+	t.Log("端口错误信息包含端口号测试通过")
+}
+
+func TestGetDesktopConfigPath(t *testing.T) {
+	path := getDesktopConfigPath()
+	if path == "" {
+		t.Fatal("getDesktopConfigPath 应返回非空路径")
+	}
+	if !strings.Contains(path, "config.yaml") {
+		t.Fatalf("路径应包含 config.yaml，实际: %s", path)
+	}
+	t.Log("getDesktopConfigPath 测试通过")
+}
+
+func TestDesktopConfiguredPortHelpers(t *testing.T) {
+	port := 19830
+
+	if got := desktopListenAddr(port); got != ":19830" {
+		t.Fatalf("HTTP 监听地址应使用配置端口，实际: %s", got)
+	}
+	if got := desktopURL(port); got != "http://localhost:19830" {
+		t.Fatalf("浏览器 URL 应使用配置端口，实际: %s", got)
+	}
+	if got := desktopPortMenuTitle(port); got != "端口: 19830" {
+		t.Fatalf("托盘端口显示应使用配置端口，实际: %s", got)
+	}
+}
+
+func TestDesktopConfigErrorMessageContainsPathAndReason(t *testing.T) {
+	msg := desktopConfigErrorMessage("/tmp/nex/config.yaml", errors.New("yaml parse failed"))
+
+	if !strings.Contains(msg, "/tmp/nex/config.yaml") {
+		t.Fatalf("配置错误提示应包含配置路径，实际: %s", msg)
+	}
+	if !strings.Contains(msg, "yaml parse failed") {
+		t.Fatalf("配置错误提示应包含失败原因，实际: %s", msg)
+	}
+}
--- a/backend/cmd/server/main.go
+++ b/backend/cmd/server/main.go
@@ -29,7 +29,7 @@ import (
 func main() {
 	minimalLogger := pkgLogger.NewMinimal()

-	cfg, err := config.LoadConfig()
+	cfg, err := config.LoadServerConfig()
 	if err != nil {
 		minimalLogger.Fatal("加载配置失败", zap.Error(err))
 	}
--- a/backend/internal/config/config.go
+++ b/backend/internal/config/config.go
@@ -1,7 +1,6 @@
 package config

 import (
-	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -225,68 +224,71 @@ func setupConfigFile(v *viper.Viper, configPath string) error {
 	v.SetConfigFile(configPath)
 	v.SetConfigType("yaml")

-	// 尝试读取配置文件，如果不存在则忽略
 	if err := v.ReadInConfig(); err != nil {
-		if !os.IsNotExist(err) {
-			return appErrors.Wrap(appErrors.ErrInternal, err)
-		}
-		// 配置文件不存在，创建默认配置文件
-		writeErr := v.SafeWriteConfigAs(configPath)
-		if writeErr == nil {
+		if os.IsNotExist(err) {
 			return nil
 		}
-
-		var alreadyExistsErr viper.ConfigFileAlreadyExistsError
-		if errors.As(writeErr, &alreadyExistsErr) {
-			return nil
-		}
-
-		return appErrors.Wrap(appErrors.ErrInternal, writeErr)
+		return appErrors.Wrap(appErrors.ErrInternal, err)
 	}
 	return nil
 }

-// LoadConfig loads config from YAML file, creates default if not exists
-func LoadConfig() (*Config, error) {
-	configPath, err := GetConfigPath()
-	if err != nil {
-		return nil, appErrors.Wrap(appErrors.ErrInternal, err)
-	}
-	return LoadConfigFromPath(configPath)
+// loadOptions 控制配置加载器行为
+type loadOptions struct {
+	configPathOverride string
+	useCLI             bool
+	useEnv             bool
+	useConfigFlag      bool
 }

-// LoadConfigFromPath 从指定路径加载配置
-func LoadConfigFromPath(configPath string) (*Config, error) {
-	// 1. 创建 Viper 实例
+// resolveConfigPath 根据 loadOptions 解析 CLI 参数并返回最终配置文件路径
+func resolveConfigPath(v *viper.Viper, opts loadOptions) (string, error) {
+	configPath := opts.configPathOverride
+
+	if !opts.useCLI && !opts.useConfigFlag {
+		return configPath, nil
+	}
+
+	flagSet := pflag.NewFlagSet("config", pflag.ContinueOnError)
+	if opts.useConfigFlag {
+		flagSet.String("config", opts.configPathOverride, "配置文件路径")
+	}
+	if opts.useCLI {
+		setupFlags(v, flagSet)
+	}
+
+	if err := flagSet.Parse(os.Args[1:]); err != nil {
+		return "", appErrors.Wrap(appErrors.ErrInvalidRequest, err)
+	}
+
+	if opts.useConfigFlag {
+		if f, err := flagSet.GetString("config"); err == nil && f != "" {
+			configPath = f
+		}
+	}
+
+	return configPath, nil
+}
+
+// loadConfig 共享配置加载逻辑，通过 loadOptions 控制是否启用 CLI、环境变量和 --config 覆盖
+func loadConfig(opts loadOptions) (*Config, error) {
 	v := viper.New()

-	// 2. 定义 CLI 参数
-	flagSet := pflag.NewFlagSet("config", pflag.ContinueOnError)
-	flagSet.String("config", configPath, "配置文件路径")
-	setupFlags(v, flagSet)
-
-	// 3. 解析 CLI 参数（忽略错误，因为可能没有参数）
-	if err := flagSet.Parse(os.Args[1:]); err != nil {
-		return nil, appErrors.Wrap(appErrors.ErrInvalidRequest, err)
-	}
-
-	// 4. 获取配置文件路径（可能被 --config 参数覆盖）
-	if configPathFlag, err := flagSet.GetString("config"); err == nil && configPathFlag != "" {
-		configPath = configPathFlag
-	}
-
-	// 5. 设置默认值
 	setupDefaults(v)

-	// 6. 绑定环境变量
-	setupEnv(v)
+	configPath, err := resolveConfigPath(v, opts)
+	if err != nil {
+		return nil, err
+	}
+
+	if opts.useEnv {
+		setupEnv(v)
+	}

-	// 7. 读取配置文件
 	if err := setupConfigFile(v, configPath); err != nil {
 		return nil, err
 	}

-	// 8. 反序列化到结构体
 	cfg := &Config{}
 	if err := v.Unmarshal(cfg, viper.DecodeHook(mapstructure.ComposeDecodeHookFunc(
 		mapstructure.StringToTimeDurationHookFunc(),
@@ -295,7 +297,6 @@ func LoadConfigFromPath(configPath string) (*Config, error) {
 		return nil, appErrors.Wrap(appErrors.ErrInternal, err)
 	}

-	// 9. 验证配置
 	if err := cfg.Validate(); err != nil {
 		return nil, err
 	}
@@ -303,6 +304,61 @@ func LoadConfigFromPath(configPath string) (*Config, error) {
 	return cfg, nil
 }

+// LoadServerConfig 为 server 入口加载配置，支持 CLI 参数、环境变量和 --config
+func LoadServerConfig() (*Config, error) {
+	configPath, err := GetConfigPath()
+	if err != nil {
+		return nil, appErrors.Wrap(appErrors.ErrInternal, err)
+	}
+	return loadConfig(loadOptions{
+		configPathOverride: configPath,
+		useCLI:             true,
+		useEnv:             true,
+		useConfigFlag:      true,
+	})
+}
+
+// LoadDesktopConfig 为 desktop 入口加载配置，固定使用默认配置文件，不支持 CLI、环境变量和 --config
+func LoadDesktopConfig() (*Config, error) {
+	configPath, err := GetConfigPath()
+	if err != nil {
+		return nil, appErrors.Wrap(appErrors.ErrInternal, err)
+	}
+	return loadConfig(loadOptions{
+		configPathOverride: configPath,
+		useCLI:             false,
+		useEnv:             false,
+		useConfigFlag:      false,
+	})
+}
+
+// LoadConfig loads config from YAML file.
+// 向后兼容，等同于 LoadServerConfig。
+func LoadConfig() (*Config, error) {
+	return LoadServerConfig()
+}
+
+// LoadConfigFromPath 从指定路径加载配置。
+// 保留向后兼容，沿用 server 语义（支持 CLI、env 和 --config 覆盖）。
+func LoadConfigFromPath(configPath string) (*Config, error) {
+	return loadConfig(loadOptions{
+		configPathOverride: configPath,
+		useCLI:             true,
+		useEnv:             true,
+		useConfigFlag:      true,
+	})
+}
+
+// LoadDesktopConfigAtPath 从指定路径以 desktop 语义加载配置（仅配置文件和默认值），用于测试场景。
+func LoadDesktopConfigAtPath(configPath string) (*Config, error) {
+	return loadConfig(loadOptions{
+		configPathOverride: configPath,
+		useCLI:             false,
+		useEnv:             false,
+		useConfigFlag:      false,
+	})
+}
+
 // SaveConfig saves config to YAML file
 func SaveConfig(cfg *Config) error {
 	configPath, err := GetConfigPath()
--- a/backend/tests/config/config_test.go
+++ b/backend/tests/config/config_test.go
@@ -120,7 +120,7 @@ log:
 	assert.Equal(t, "warn", cfg.Log.Level, "YAML value should be used when no CLI/ENV override")
 }

-func TestLoadConfig_AutoCreate(t *testing.T) {
+func TestLoadConfig_NoAutoCreate(t *testing.T) {
 	tmpDir := t.TempDir()
 	configPath := filepath.Join(tmpDir, "config.yaml")

@@ -132,6 +132,9 @@ func TestLoadConfig_AutoCreate(t *testing.T) {
 	require.NotNil(t, cfg)

 	assert.Equal(t, 9826, cfg.Server.Port, "should load with default values")
+
+	_, err = os.Stat(configPath)
+	assert.True(t, os.IsNotExist(err), "config file should not be auto-created")
 }

 func TestSaveAndLoadConfig(t *testing.T) {
@@ -184,3 +187,124 @@ func TestSaveAndLoadConfig(t *testing.T) {
 	assert.Equal(t, cfg.Log.MaxAge, loaded.Log.MaxAge)
 	assert.Equal(t, cfg.Log.Compress, loaded.Log.Compress)
 }
+
+func TestLoadDesktopConfig_FileOnly(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.yaml")
+
+	yamlContent := `
+server:
+  port: 8080
+log:
+  level: debug
+`
+	err := os.WriteFile(configPath, []byte(yamlContent), 0o600)
+	require.NoError(t, err)
+
+	cfg, err := config.LoadDesktopConfigAtPath(configPath)
+	require.NoError(t, err)
+
+	assert.Equal(t, 8080, cfg.Server.Port)
+	assert.Equal(t, "debug", cfg.Log.Level)
+}
+
+func TestLoadDesktopConfig_IgnoresCLI(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.yaml")
+
+	err := os.WriteFile(configPath, []byte("server:\n  port: 8080\n"), 0o600)
+	require.NoError(t, err)
+
+	originalArgs := os.Args
+	defer func() { os.Args = originalArgs }()
+	os.Args = []string{"nex", "--server-port", "9999"}
+
+	cfg, err := config.LoadDesktopConfigAtPath(configPath)
+	require.NoError(t, err)
+
+	assert.Equal(t, 8080, cfg.Server.Port, "desktop should ignore CLI args and use config file")
+}
+
+func TestLoadDesktopConfig_IgnoresEnv(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.yaml")
+
+	err := os.WriteFile(configPath, []byte("server:\n  port: 8080\n"), 0o600)
+	require.NoError(t, err)
+
+	t.Setenv("NEX_SERVER_PORT", "9000")
+	t.Setenv("NEX_LOG_LEVEL", "debug")
+
+	cfg, err := config.LoadDesktopConfigAtPath(configPath)
+	require.NoError(t, err)
+
+	assert.Equal(t, 8080, cfg.Server.Port, "desktop should ignore env vars and use config file")
+	assert.Equal(t, "info", cfg.Log.Level, "desktop should ignore env vars and use default")
+}
+
+func TestLoadDesktopConfig_IgnoresUnknownArgs(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.yaml")
+
+	err := os.WriteFile(configPath, []byte("server:\n  port: 8080\n"), 0o600)
+	require.NoError(t, err)
+
+	originalArgs := os.Args
+	defer func() { os.Args = originalArgs }()
+	os.Args = []string{"nex", "--unknown-flag", "value", "--another-unknown"}
+
+	cfg, err := config.LoadDesktopConfigAtPath(configPath)
+	require.NoError(t, err, "desktop should not fail on unknown CLI args")
+
+	assert.Equal(t, 8080, cfg.Server.Port)
+}
+
+func TestLoadDesktopConfig_Snapshot(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.yaml")
+
+	err := os.WriteFile(configPath, []byte("server:\n  port: 8080\n"), 0o600)
+	require.NoError(t, err)
+
+	cfg, err := config.LoadDesktopConfigAtPath(configPath)
+	require.NoError(t, err)
+	assert.Equal(t, 8080, cfg.Server.Port)
+
+	err = os.WriteFile(configPath, []byte("server:\n  port: 9999\n"), 0o600)
+	require.NoError(t, err)
+
+	assert.Equal(t, 8080, cfg.Server.Port, "loaded config snapshot should not change when file changes")
+
+	cfg2, err := config.LoadDesktopConfigAtPath(configPath)
+	require.NoError(t, err)
+	assert.Equal(t, 9999, cfg2.Server.Port, "reload should pick up new config values")
+}
+
+func TestLoadDesktopConfig_InvalidFileFails(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+	}{
+		{
+			name:    "invalid yaml",
+			content: "server:\n  port: [\n",
+		},
+		{
+			name:    "validation failure",
+			content: "server:\n  port: 70000\n",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tmpDir := t.TempDir()
+			configPath := filepath.Join(tmpDir, "config.yaml")
+
+			err := os.WriteFile(configPath, []byte(tt.content), 0o600)
+			require.NoError(t, err)
+
+			_, err = config.LoadDesktopConfigAtPath(configPath)
+			require.Error(t, err, "desktop should not silently fall back to defaults for invalid config files")
+		})
+	}
+}