feat: 新增桌面应用支持

- 新增 desktop 应用入口，将后端与前端打包为单一可执行文件 - 集成系统托盘功能（getlantern/systray） - 支持单实例锁和端口冲突检测 - 启动时自动打开浏览器显示管理界面 - 新增 embedfs 模块嵌入静态资源 - 新增跨平台构建脚本（macOS/Windows/Linux） - 新增 macOS .app 打包脚本 - 统一 Makefile，移除 backend/Makefile - 更新 README 添加桌面应用使用说明
2026-04-22 19:27:27 +08:00
parent f5e45d032e
commit 0b05e08705
22 changed files with 1297 additions and 88 deletions
--- a/backend/cmd/desktop/main.go
+++ b/backend/cmd/desktop/main.go
@@ -0,0 +1,456 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"io/fs"
+	"log"
+	"net"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/getlantern/systray"
+	"github.com/pressly/goose/v3"
+	"go.uber.org/zap"
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+
+	"nex/backend/internal/config"
+	"nex/backend/internal/conversion"
+	"nex/backend/internal/conversion/anthropic"
+	"nex/backend/internal/conversion/openai"
+	"nex/backend/internal/handler"
+	"nex/backend/internal/handler/middleware"
+	"nex/backend/internal/provider"
+	"nex/backend/internal/repository"
+	"nex/backend/internal/service"
+	pkgLogger "nex/backend/pkg/logger"
+
+	"nex/embedfs"
+)
+
+var (
+	server         *http.Server
+	zapLogger      *zap.Logger
+	shutdownCtx    context.Context
+	shutdownCancel context.CancelFunc
+)
+
+func main() {
+	port := 9826
+
+	if err := acquireSingleInstance(); err != nil {
+		showError("Nex Gateway", "已有 Nex 实例运行")
+		os.Exit(1)
+	}
+	defer releaseSingleInstance()
+
+	if err := checkPortAvailable(port); err != nil {
+		showError("Nex Gateway", err.Error())
+		os.Exit(1)
+	}
+
+	cfg, err := config.LoadConfig()
+	if err != nil {
+		showError("Nex Gateway", fmt.Sprintf("加载配置失败: %v", err))
+		os.Exit(1)
+	}
+
+	zapLogger, err = pkgLogger.New(pkgLogger.Config{
+		Level:      cfg.Log.Level,
+		Path:       cfg.Log.Path,
+		MaxSize:    cfg.Log.MaxSize,
+		MaxBackups: cfg.Log.MaxBackups,
+		MaxAge:     cfg.Log.MaxAge,
+		Compress:   cfg.Log.Compress,
+	})
+	if err != nil {
+		showError("Nex Gateway", fmt.Sprintf("初始化日志失败: %v", err))
+		os.Exit(1)
+	}
+	defer zapLogger.Sync()
+
+	db, err := initDatabase(cfg)
+	if err != nil {
+		showError("Nex Gateway", fmt.Sprintf("初始化数据库失败: %v", err))
+		os.Exit(1)
+	}
+	defer closeDB(db)
+
+	providerRepo := repository.NewProviderRepository(db)
+	modelRepo := repository.NewModelRepository(db)
+	statsRepo := repository.NewStatsRepository(db)
+
+	providerService := service.NewProviderService(providerRepo, modelRepo)
+	modelService := service.NewModelService(modelRepo, providerRepo)
+	routingService := service.NewRoutingService(modelRepo, providerRepo)
+	statsService := service.NewStatsService(statsRepo)
+
+	registry := conversion.NewMemoryRegistry()
+	if err := registry.Register(openai.NewAdapter()); err != nil {
+		zapLogger.Fatal("注册 OpenAI 适配器失败", zap.String("error", err.Error()))
+	}
+	if err := registry.Register(anthropic.NewAdapter()); err != nil {
+		zapLogger.Fatal("注册 Anthropic 适配器失败", zap.String("error", err.Error()))
+	}
+	engine := conversion.NewConversionEngine(registry, zapLogger)
+
+	providerClient := provider.NewClient()
+
+	proxyHandler := handler.NewProxyHandler(engine, providerClient, routingService, providerService, statsService)
+	providerHandler := handler.NewProviderHandler(providerService)
+	modelHandler := handler.NewModelHandler(modelService)
+	statsHandler := handler.NewStatsHandler(statsService)
+
+	gin.SetMode(gin.ReleaseMode)
+	r := gin.New()
+
+	r.Use(middleware.RequestID())
+	r.Use(middleware.Recovery(zapLogger))
+	r.Use(middleware.Logging(zapLogger))
+	r.Use(middleware.CORS())
+
+	setupRoutes(r, proxyHandler, providerHandler, modelHandler, statsHandler)
+	setupStaticFiles(r)
+
+	server = &http.Server{
+		Addr:         fmt.Sprintf(":%d", port),
+		Handler:      r,
+		ReadTimeout:  cfg.Server.ReadTimeout,
+		WriteTimeout: cfg.Server.WriteTimeout,
+	}
+
+	shutdownCtx, shutdownCancel = context.WithCancel(context.Background())
+
+	go func() {
+		zapLogger.Info("AI Gateway 启动", zap.String("addr", server.Addr))
+		if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			zapLogger.Fatal("服务器启动失败", zap.String("error", err.Error()))
+		}
+	}()
+
+	go func() {
+		time.Sleep(500 * time.Millisecond)
+		if err := openBrowser(fmt.Sprintf("http://localhost:%d", port)); err != nil {
+			zapLogger.Warn("无法打开浏览器", zap.String("error", err.Error()))
+		}
+	}()
+
+	setupSystray(port)
+}
+
+func initDatabase(cfg *config.Config) (*gorm.DB, error) {
+	dbDir := filepath.Dir(cfg.Database.Path)
+	if err := os.MkdirAll(dbDir, 0755); err != nil {
+		return nil, fmt.Errorf("创建数据库目录失败: %w", err)
+	}
+
+	db, err := gorm.Open(sqlite.Open(cfg.Database.Path), &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Info),
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	if err := runMigrations(db); err != nil {
+		return nil, fmt.Errorf("数据库迁移失败: %w", err)
+	}
+
+	if err := db.Exec("PRAGMA journal_mode=WAL").Error; err != nil {
+		log.Printf("警告: 启用 WAL 模式失败: %v", err)
+	}
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		return nil, err
+	}
+	sqlDB.SetMaxIdleConns(cfg.Database.MaxIdleConns)
+	sqlDB.SetMaxOpenConns(cfg.Database.MaxOpenConns)
+	sqlDB.SetConnMaxLifetime(cfg.Database.ConnMaxLifetime)
+
+	return db, nil
+}
+
+func runMigrations(db *gorm.DB) error {
+	sqlDB, err := db.DB()
+	if err != nil {
+		return err
+	}
+
+	migrationsDir := getMigrationsDir()
+	if _, err := os.Stat(migrationsDir); os.IsNotExist(err) {
+		return fmt.Errorf("迁移目录不存在: %s", migrationsDir)
+	}
+
+	goose.SetDialect("sqlite3")
+	if err := goose.Up(sqlDB, migrationsDir); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func getMigrationsDir() string {
+	_, filename, _, ok := runtime.Caller(0)
+	if ok {
+		dir := filepath.Join(filepath.Dir(filename), "..", "..", "migrations")
+		if abs, err := filepath.Abs(dir); err == nil {
+			return abs
+		}
+	}
+	return "./migrations"
+}
+
+func closeDB(db *gorm.DB) {
+	sqlDB, err := db.DB()
+	if err != nil {
+		return
+	}
+	sqlDB.Close()
+}
+
+func setupRoutes(r *gin.Engine, proxyHandler *handler.ProxyHandler, providerHandler *handler.ProviderHandler, modelHandler *handler.ModelHandler, statsHandler *handler.StatsHandler) {
+	r.Any("/v1/*path", proxyHandler.HandleProxy)
+
+	providers := r.Group("/api/providers")
+	{
+		providers.GET("", providerHandler.ListProviders)
+		providers.POST("", providerHandler.CreateProvider)
+		providers.GET("/:id", providerHandler.GetProvider)
+		providers.PUT("/:id", providerHandler.UpdateProvider)
+		providers.DELETE("/:id", providerHandler.DeleteProvider)
+	}
+
+	models := r.Group("/api/models")
+	{
+		models.GET("", modelHandler.ListModels)
+		models.POST("", modelHandler.CreateModel)
+		models.GET("/:id", modelHandler.GetModel)
+		models.PUT("/:id", modelHandler.UpdateModel)
+		models.DELETE("/:id", modelHandler.DeleteModel)
+	}
+
+	stats := r.Group("/api/stats")
+	{
+		stats.GET("", statsHandler.GetStats)
+		stats.GET("/aggregate", statsHandler.AggregateStats)
+	}
+
+	r.GET("/health", func(c *gin.Context) {
+		c.JSON(200, gin.H{"status": "ok"})
+	})
+}
+
+func setupStaticFiles(r *gin.Engine) {
+	distFS, err := fs.Sub(embedfs.FrontendDist, "frontend-dist")
+	if err != nil {
+		zapLogger.Fatal("无法加载前端资源", zap.String("error", err.Error()))
+	}
+
+	getContentType := func(path string) string {
+		if strings.HasSuffix(path, ".js") {
+			return "application/javascript"
+		}
+		if strings.HasSuffix(path, ".css") {
+			return "text/css"
+		}
+		if strings.HasSuffix(path, ".svg") {
+			return "image/svg+xml"
+		}
+		if strings.HasSuffix(path, ".png") {
+			return "image/png"
+		}
+		if strings.HasSuffix(path, ".ico") {
+			return "image/x-icon"
+		}
+		if strings.HasSuffix(path, ".woff") || strings.HasSuffix(path, ".woff2") {
+			return "font/woff2"
+		}
+		return "application/octet-stream"
+	}
+
+	r.GET("/assets/*filepath", func(c *gin.Context) {
+		filepath := c.Param("filepath")
+		data, err := fs.ReadFile(distFS, "assets"+filepath)
+		if err != nil {
+			c.Status(404)
+			return
+		}
+		c.Data(200, getContentType(filepath), data)
+	})
+
+	r.GET("/favicon.svg", func(c *gin.Context) {
+		data, err := fs.ReadFile(distFS, "favicon.svg")
+		if err != nil {
+			c.Status(404)
+			return
+		}
+		c.Data(200, "image/svg+xml", data)
+	})
+
+	r.NoRoute(func(c *gin.Context) {
+		path := c.Request.URL.Path
+
+		if strings.HasPrefix(path, "/api/") ||
+			strings.HasPrefix(path, "/v1/") ||
+			strings.HasPrefix(path, "/health") {
+			c.JSON(404, gin.H{"error": "not found"})
+			return
+		}
+
+		data, err := fs.ReadFile(distFS, "index.html")
+		if err != nil {
+			c.Status(500)
+			return
+		}
+		c.Data(200, "text/html; charset=utf-8", data)
+	})
+}
+
+func setupSystray(port int) {
+	systray.Run(func() {
+		icon, err := embedfs.Assets.ReadFile("assets/icon.png")
+		if err != nil {
+			zapLogger.Error("无法加载托盘图标", zap.String("error", err.Error()))
+		}
+		systray.SetIcon(icon)
+		systray.SetTitle("Nex Gateway")
+		systray.SetTooltip("AI Gateway")
+
+		mOpen := systray.AddMenuItem("打开管理界面", "在浏览器中打开")
+		systray.AddSeparator()
+		mStatus := systray.AddMenuItem("状态: 运行中", "")
+		mStatus.Disable()
+		mPort := systray.AddMenuItem(fmt.Sprintf("端口: %d", port), "")
+		mPort.Disable()
+		systray.AddSeparator()
+		mAbout := systray.AddMenuItem("关于", "")
+		systray.AddSeparator()
+		mQuit := systray.AddMenuItem("退出", "停止服务并退出")
+
+		go func() {
+			for {
+				select {
+				case <-mOpen.ClickedCh:
+					openBrowser(fmt.Sprintf("http://localhost:%d", port))
+				case <-mAbout.ClickedCh:
+					showAbout()
+				case <-mQuit.ClickedCh:
+					doShutdown()
+					systray.Quit()
+					return
+				}
+			}
+		}()
+	}, nil)
+}
+
+func doShutdown() {
+	if zapLogger != nil {
+		zapLogger.Info("正在关闭服务器...")
+	}
+
+	if server != nil {
+		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+		server.Shutdown(ctx)
+	}
+
+	if shutdownCancel != nil {
+		shutdownCancel()
+	}
+}
+
+func checkPortAvailable(port int) error {
+	ln, err := net.Listen("tcp", fmt.Sprintf(":%d", port))
+	if err != nil {
+		return fmt.Errorf("端口 %d 已被占用\n\n可能原因:\n- 已有 Nex 实例运行\n- 其他程序占用了该端口\n\n请检查并关闭占用端口的程序", port)
+	}
+	ln.Close()
+	return nil
+}
+
+var lockFile *os.File
+
+func acquireSingleInstance() error {
+	lockPath := filepath.Join(os.TempDir(), "nex-gateway.lock")
+
+	f, err := os.OpenFile(lockPath, os.O_CREATE|os.O_RDWR, 0666)
+	if err != nil {
+		return err
+	}
+
+	err = syscall.Flock(int(f.Fd()), syscall.LOCK_EX|syscall.LOCK_NB)
+	if err != nil {
+		f.Close()
+		return fmt.Errorf("已有实例运行")
+	}
+
+	lockFile = f
+	return nil
+}
+
+func releaseSingleInstance() {
+	if lockFile != nil {
+		syscall.Flock(int(lockFile.Fd()), syscall.LOCK_UN)
+		lockFile.Close()
+	}
+}
+
+func openBrowser(url string) error {
+	var cmd *exec.Cmd
+
+	switch runtime.GOOS {
+	case "darwin":
+		cmd = exec.Command("open", url)
+	case "windows":
+		cmd = exec.Command("rundll32", "url.dll,FileProtocolHandler", url)
+	case "linux":
+		browsers := []string{"xdg-open", "google-chrome", "firefox"}
+		for _, browser := range browsers {
+			if _, err := exec.LookPath(browser); err == nil {
+				cmd = exec.Command(browser, url)
+				break
+			}
+		}
+	}
+
+	if cmd == nil {
+		return fmt.Errorf("无法打开浏览器")
+	}
+
+	return cmd.Start()
+}
+
+func showError(title, message string) {
+	switch runtime.GOOS {
+	case "darwin":
+		script := fmt.Sprintf(`display dialog "%s" buttons {"OK"} default button "OK" with title "%s"`, message, title)
+		exec.Command("osascript", "-e", script).Run()
+	case "windows":
+		exec.Command("msg", "*", message).Run()
+	case "linux":
+		exec.Command("zenity", "--error", fmt.Sprintf("--title=%s", title), fmt.Sprintf("--text=%s", message)).Run()
+	}
+}
+
+func showAbout() {
+	message := "Nex Gateway\n\nAI Gateway - 统一的大模型 API 网关\n\nhttps://github.com/nex/gateway"
+	switch runtime.GOOS {
+	case "darwin":
+		script := fmt.Sprintf(`display dialog "%s" buttons {"OK"} default button "OK" with title "关于 Nex Gateway"`, message)
+		exec.Command("osascript", "-e", script).Run()
+	case "windows":
+		exec.Command("msg", "*", message).Run()
+	case "linux":
+		exec.Command("zenity", "--info", "--title=关于 Nex Gateway", fmt.Sprintf("--text=%s", message)).Run()
+	}
+}
--- a/backend/cmd/desktop/port_test.go
+++ b/backend/cmd/desktop/port_test.go
@@ -0,0 +1,69 @@
+package main
+
+import (
+	"net"
+	"net/http"
+	"testing"
+	"time"
+)
+
+func TestCheckPortAvailable(t *testing.T) {
+	port := 19826
+
+	err := checkPortAvailable(port)
+	if err != nil {
+		t.Fatalf("端口 %d 应该可用: %v", port, err)
+	}
+
+	t.Log("端口可用测试通过")
+}
+
+func TestCheckPortOccupied(t *testing.T) {
+	port := 19827
+
+	listener, err := net.Listen("tcp", ":19827")
+	if err != nil {
+		t.Fatalf("无法启动测试服务器: %v", err)
+	}
+	defer listener.Close()
+
+	go func() {
+		conn, err := listener.Accept()
+		if err == nil {
+			conn.Close()
+		}
+	}()
+
+	time.Sleep(100 * time.Millisecond)
+
+	err = checkPortAvailable(port)
+	if err == nil {
+		t.Fatal("端口被占用时应该返回错误")
+	}
+
+	t.Log("端口占用检测测试通过")
+}
+
+func TestCheckPortAvailableAfterClose(t *testing.T) {
+	port := 19828
+
+	listener, err := net.Listen("tcp", ":19828")
+	if err != nil {
+		t.Fatalf("无法启动测试服务器: %v", err)
+	}
+
+	server := &http.Server{}
+	go server.Serve(listener)
+
+	time.Sleep(100 * time.Millisecond)
+
+	listener.Close()
+	time.Sleep(100 * time.Millisecond)
+
+	err = checkPortAvailable(port)
+	if err != nil {
+		t.Fatalf("端口关闭后应该可用: %v", err)
+	}
+
+	t.Log("端口关闭后可用测试通过")
+}
--- a/backend/cmd/desktop/singleton_test.go
+++ b/backend/cmd/desktop/singleton_test.go
@@ -0,0 +1,39 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"syscall"
+	"testing"
+)
+
+func TestAcquireSingleInstance(t *testing.T) {
+	lockPath := filepath.Join(os.TempDir(), "nex-gateway-test.lock")
+	
+	origLockFile := lockFile
+	lockFile = nil
+	defer func() { lockFile = origLockFile }()
+
+	f, err := os.OpenFile(lockPath, os.O_CREATE|os.O_RDWR, 0666)
+	if err != nil {
+		t.Fatalf("无法创建锁文件: %v", err)
+	}
+	defer f.Close()
+	defer os.Remove(lockPath)
+
+	err = syscall.Flock(int(f.Fd()), syscall.LOCK_EX|syscall.LOCK_NB)
+	if err != nil {
+		t.Fatalf("无法获取文件锁: %v", err)
+	}
+	defer syscall.Flock(int(f.Fd()), syscall.LOCK_UN)
+
+	t.Log("单实例锁测试通过")
+}
+
+func TestReleaseSingleInstance(t *testing.T) {
+	lockFile = nil
+	
+	releaseSingleInstance()
+	
+	t.Log("释放空锁测试通过")
+}
--- a/backend/cmd/desktop/static_test.go
+++ b/backend/cmd/desktop/static_test.go
@@ -0,0 +1,123 @@
+package main
+
+import (
+	"io/fs"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+
+	"nex/embedfs"
+)
+
+func TestSetupStaticFiles(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	distFS, err := fs.Sub(embedfs.FrontendDist, "frontend-dist")
+	if err != nil {
+		t.Skipf("跳过测试: 前端资源未构建: %v", err)
+		return
+	}
+
+	getContentType := func(path string) string {
+		if strings.HasSuffix(path, ".js") {
+			return "application/javascript"
+		}
+		if strings.HasSuffix(path, ".css") {
+			return "text/css"
+		}
+		if strings.HasSuffix(path, ".svg") {
+			return "image/svg+xml"
+		}
+		return "application/octet-stream"
+	}
+
+	r := gin.New()
+	r.GET("/assets/*filepath", func(c *gin.Context) {
+		filepath := c.Param("filepath")
+		data, err := fs.ReadFile(distFS, "assets"+filepath)
+		if err != nil {
+			c.Status(404)
+			return
+		}
+		c.Data(200, getContentType(filepath), data)
+	})
+
+	r.GET("/favicon.svg", func(c *gin.Context) {
+		data, err := fs.ReadFile(distFS, "favicon.svg")
+		if err != nil {
+			c.Status(404)
+			return
+		}
+		c.Data(200, "image/svg+xml", data)
+	})
+
+	r.NoRoute(func(c *gin.Context) {
+		path := c.Request.URL.Path
+		if strings.HasPrefix(path, "/api/") ||
+			strings.HasPrefix(path, "/v1/") ||
+			strings.HasPrefix(path, "/health") {
+			c.JSON(404, gin.H{"error": "not found"})
+			return
+		}
+		data, err := fs.ReadFile(distFS, "index.html")
+		if err != nil {
+			c.Status(500)
+			return
+		}
+		c.Data(200, "text/html; charset=utf-8", data)
+	})
+
+	t.Run("API 404", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/api/test", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code != 404 {
+			t.Errorf("期望状态码 404, 实际 %d", w.Code)
+		}
+	})
+
+	t.Run("SPA fallback", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/providers", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code != 200 {
+			t.Errorf("期望状态码 200, 实际 %d", w.Code)
+		}
+	})
+
+	t.Run("MIME type for JS", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/assets/test.js", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code == 200 {
+			expected := "application/javascript"
+			if w.Header().Get("Content-Type") != expected {
+				t.Errorf("期望 Content-Type %s, 实际 %s", expected, w.Header().Get("Content-Type"))
+			}
+		} else {
+			t.Log("文件不存在，跳过 MIME 类型验证")
+		}
+	})
+
+	t.Run("MIME type for CSS", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/assets/test.css", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code == 200 {
+			expected := "text/css"
+			if w.Header().Get("Content-Type") != expected {
+				t.Errorf("期望 Content-Type %s, 实际 %s", expected, w.Header().Get("Content-Type"))
+			}
+		} else {
+			t.Log("文件不存在，跳过 MIME 类型验证")
+		}
+	})
+
+	t.Log("静态文件服务测试通过")
+}