feat(swagger): support dynamic host via EZ_SWAGGER_HOST env var

- Add ServerConfig.SwaggerHost field
- Set docs.SwaggerInfo.Host dynamically at startup
- Update docker-compose, k8s manifests, and .env.example

.env.example

@@ -20,6 +20,10 @@ EZ_SYNC_OUTBOX_INTERVAL_SECONDS=5
 EZ_SYNC_OUTBOX_BATCH_SIZE=200
 EZ_SYNC_OUTBOX_MAX_RETRIES=10
 
+# Swagger UI Host (留空则使用相对路径，适合反向代理部署)
+# 示例: EZ_SWAGGER_HOST=api.example.com 或 EZ_SWAGGER_HOST=localhost:8080
+EZ_SWAGGER_HOST=
+
 # Log DB (docker-compose log-postgres，可选；默认不启用独立日志库)
 LOG_POSTGRES_USER=postgres
 LOG_POSTGRES_PASSWORD=postgres

cmd/server/main.go

@@ -14,7 +14,7 @@ import (
 	"syscall"
 	"time"
 
-	_ "github.com/ez-api/ez-api/docs"
+	"github.com/ez-api/ez-api/docs"
 	"github.com/ez-api/ez-api/internal/api"
 	"github.com/ez-api/ez-api/internal/config"
 	"github.com/ez-api/ez-api/internal/cron"
@@ -246,6 +246,13 @@ func main() {
 		c.Next()
 	})
 
+	// 动态设置 Swagger Host
+	if cfg.Server.SwaggerHost != "" {
+		docs.SwaggerInfo.Host = cfg.Server.SwaggerHost
+	} else {
+		docs.SwaggerInfo.Host = "" // 使用相对路径
+	}
+
 	// Health Check Endpoint
 	r.GET("/health", func(c *gin.Context) {
 		status := healthService.Check(c.Request.Context())

docker-compose.yml

@@ -79,6 +79,7 @@ services:
       EZ_LOG_RETENTION_DAYS: ${EZ_LOG_RETENTION_DAYS:-30}
       EZ_LOG_MAX_RECORDS: ${EZ_LOG_MAX_RECORDS:-1000000}
       EZ_LOG_PARTITIONING: ${EZ_LOG_PARTITIONING:-off}
+      EZ_SWAGGER_HOST: ${EZ_SWAGGER_HOST:-}
     depends_on:
       postgres:
         condition: service_healthy

internal/config/config.go

@@ -23,7 +23,8 @@ type Config struct {
 }
 
 type ServerConfig struct {
-	Port string
+	Port        string
+	SwaggerHost string // Swagger UI 显示的 Host (可选，留空则使用相对路径)
 }
 
 type CORSConfig struct {
@@ -83,6 +84,7 @@ func Load() (*Config, error) {
 	v := viper.New()
 
 	v.SetDefault("server.port", "8080")
+	v.SetDefault("server.swagger_host", "")
 	v.SetDefault("cors.allow_origins", "*")
 	v.SetDefault("postgres.dsn", "host=localhost user=postgres password=postgres dbname=ezapi port=5432 sslmode=disable")
 	v.SetDefault("redis.addr", "localhost:6379")
@@ -114,6 +116,7 @@ func Load() (*Config, error) {
 	v.AutomaticEnv()
 
 	_ = v.BindEnv("server.port", "EZ_API_PORT")
+	_ = v.BindEnv("server.swagger_host", "EZ_SWAGGER_HOST")
 	_ = v.BindEnv("cors.allow_origins", "EZ_CORS_ALLOW_ORIGINS")
 	_ = v.BindEnv("postgres.dsn", "EZ_PG_DSN")
 	_ = v.BindEnv("redis.addr", "EZ_REDIS_ADDR")
@@ -158,7 +161,8 @@ func Load() (*Config, error) {
 
 	cfg := &Config{
 		Server: ServerConfig{
-			Port: v.GetString("server.port"),
+			Port:        v.GetString("server.port"),
+			SwaggerHost: strings.TrimSpace(v.GetString("server.swagger_host")),
 		},
 		CORS: CORSConfig{
 			AllowOrigins: splitCommaList(v.GetString("cors.allow_origins")),

test/k8s/configmap.yaml

@@ -18,6 +18,8 @@ data:
   EZ_LOG_RETENTION_DAYS: "30"
   EZ_LOG_MAX_RECORDS: "1000000"
   EZ_LOG_PARTITIONING: "off"
+  # Swagger UI Host (留空则使用相对路径)
+  EZ_SWAGGER_HOST: ""
   
   # Balancer configuration
   EZ_BALANCER_PORT: "8081"

test/k8s/ez-api.yaml

@@ -153,6 +153,12 @@ spec:
                 configMapKeyRef:
                   name: ez-api-config
                   key: EZ_LOG_PARTITIONING
+            # Swagger Host
+            - name: EZ_SWAGGER_HOST
+              valueFrom:
+                configMapKeyRef:
+                  name: ez-api-config
+                  key: EZ_SWAGGER_HOST
           resources:
             requests:
               memory: "128Mi"