feat(log): 全栈结构化日志治理

横切层
- middleware/request_logger.go 新增 HTTP 访问日志，抽取/生成 X-Request-ID
  注入响应头与 std ctx，按状态分级（健康检查降为 Debug）
- middleware/recovery.go 新增 panic 兜底，输出 panic_recovered + 完整
  stack，返 500 + request_id
- middleware/auth.go 鉴权失败带 reason 的 *_validation_failed Warn，
  成功后用 user_id/group_id/api_key_id 重派生 logger 注入下游
- server/router.go server.go 启动顺序：Recovery → RequestLogger → I18n

业务路径
- plugin/forwarder.go forward_request_start 降 Debug、单请求 1 行 INFO
  策略；空 attrs / nil error 不输出；429 + Retry-After 取代静默 503
- plugin/request.go body 读失败 / 平台插件未加载 / 路由缺失补错误日志
- plugin/manager_runtime.go plugin_load/start_timeout 等 + 字段名常量化
- plugin/host_service.go host_forward_* 系列结构化日志
- plugin/outcome.go 新增 openAIRateLimitError helper 服务于 forward 限流
- auth/{apikey,crypto}.go 缓存命中/解密失败补点
- billing/recorder.go 事件名规范化
- scheduler/{state,selection}.go 状态翻转保留 Info、降级 Warn
- routing/selector.go routing_match Debug / routing_no_match Warn

管理面 12 个 app 包审计日志
- {auth,user,apikey,dashboard,account,group,subscription,pluginadmin,
  settings,usage,openclaw,proxy}/service.go 关键操作（创建/删除/改密/
  改额度/状态翻转）补 Info 审计；失败/拒绝补 Warn/Error；密码/token/
  签名/key 一律不打印

基础设施
- infra/store/ent_logger.go 新增 ent 默认 logger 桥接到 slog.Debug
- infra/mailer/mailer.go SMTP 三层日志，邮箱用 hash 脱敏
- setup/upgrade/bootstrap 一次性事件 + 失败 Error
- cmd/server/main.go server_listening / config_loaded（DSN 脱敏）

config.yaml.example 增加 log: 块说明 level/format 取值

Author: DouDOU-start

backend/cmd/server/main.go

@@ -26,6 +26,7 @@ import (
 	"github.com/DouDOU-start/airgate-core/internal/bootstrap"
 	"github.com/DouDOU-start/airgate-core/internal/config"
 	"github.com/DouDOU-start/airgate-core/internal/i18n"
+	"github.com/DouDOU-start/airgate-core/internal/infra/store"
 	"github.com/DouDOU-start/airgate-core/internal/server"
 	"github.com/DouDOU-start/airgate-core/internal/setup"
 	"github.com/DouDOU-start/airgate-core/internal/version"
@@ -70,14 +71,16 @@ func main() {
 	}
 
 	// 加载配置
-	cfg, err := config.Load(config.ConfigPath())
+	cfgPath := config.ConfigPath()
+	cfg, err := config.Load(cfgPath)
 	if err != nil {
-		slog.Error("加载配置失败", "error", err)
+		slog.Error("config_load_failed", "path", cfgPath, "error", err)
 		os.Exit(1)
 	}
 
 	// 用配置值重新初始化日志（应用配置文件中的 level/format）
 	sdk.InitLogger("core", cfg.Log.Level, cfg.Log.Format)
+	slog.Info("config_loaded", "path", cfgPath, "log_level", cfg.Log.Level, "log_format", cfg.Log.Format)
 
 	// 启动正常服务
 	startMainServer(cfg)
@@ -135,12 +138,22 @@ func startSetupServer() {
 
 // startMainServer 启动主服务器
 func startMainServer(cfg *config.Config) {
+	bootStart := time.Now()
+
 	// 初始化数据库连接（Ent Client）
-	drv, err := sql.Open(dialect.Postgres, cfg.Database.DSN())
+	dsn := cfg.Database.DSN()
+	drv, err := sql.Open(dialect.Postgres, dsn)
 	if err != nil {
-		slog.Error("打开数据库失败", "error", err)
+		slog.Error("db_open_failed", "dsn", store.RedactDSN(dsn), sdk.LogFieldError, err)
 		os.Exit(1)
 	}
+	slog.Info("db_connected",
+		"driver", "postgres",
+		"host", cfg.Database.Host,
+		"port", cfg.Database.Port,
+		"db", cfg.Database.DBName,
+		"dsn", store.RedactDSN(dsn))
+
 	// 配置连接池：不限制时 Go 会无限开连接，高并发下 Postgres "too many clients already"
 	maxOpen := cfg.Database.MaxOpenConns
 	if maxOpen <= 0 {
@@ -157,19 +170,33 @@ func startMainServer(cfg *config.Config) {
 	drv.DB().SetMaxOpenConns(maxOpen)
 	drv.DB().SetMaxIdleConns(maxIdle)
 	drv.DB().SetConnMaxLifetime(time.Duration(lifeMin) * time.Minute)
-	slog.Info("数据库连接池已配置",
+	slog.Info("db_pool_configured",
 		"max_open", maxOpen, "max_idle", maxIdle, "lifetime_min", lifeMin)
 
-	db := ent.NewClient(ent.Driver(drv))
+	pingCtx, pingCancel := context.WithTimeout(context.Background(), 5*time.Second)
+	if err := drv.DB().PingContext(pingCtx); err != nil {
+		pingCancel()
+		slog.Error("db_ping_failed", sdk.LogFieldError, err)
+		os.Exit(1)
+	}
+	pingCancel()
+
+	// 注入 slog 桥接，让 ent 内部 debug/error 日志走结构化通道
+	db := ent.NewClient(ent.Driver(drv), store.EntSlogLogger())
+	slog.Info("ent_client_initialized",
+		"driver", "postgres",
+		"max_open_conns", maxOpen,
+		"max_idle_conns", maxIdle,
+		"lifetime_min", lifeMin)
 	defer func() {
 		if err := db.Close(); err != nil {
-			slog.Warn("关闭数据库连接失败", "error", err)
+			slog.Warn("db_close_failed", sdk.LogFieldError, err)
 		}
 	}()
 
 	// 启动时执行非破坏性迁移，补齐缺失表和字段，避免升级后因 schema 落后导致接口报错。
 	if err := db.Schema.Create(context.Background(), migrate.WithDropIndex(false), migrate.WithDropColumn(false)); err != nil {
-		slog.Error("执行数据库迁移失败", "error", err)
+		slog.Error("db_migration_failed", sdk.LogFieldError, err)
 		os.Exit(1)
 	}
 
@@ -182,12 +209,28 @@ func startMainServer(cfg *config.Config) {
 		Password: cfg.Redis.Password,
 		DB:       cfg.Redis.DB,
 	})
+	redisCtx, redisCancel := context.WithTimeout(context.Background(), 5*time.Second)
+	if err := rdb.Ping(redisCtx).Err(); err != nil {
+		redisCancel()
+		slog.Error("redis_ping_failed",
+			"host", cfg.Redis.Host,
+			"port", cfg.Redis.Port,
+			sdk.LogFieldError, err)
+		os.Exit(1)
+	}
+	redisCancel()
+	slog.Info("redis_connected",
+		"host", cfg.Redis.Host,
+		"port", cfg.Redis.Port,
+		"db", cfg.Redis.DB)
 	defer func() {
 		if err := rdb.Close(); err != nil {
-			slog.Warn("关闭 Redis 连接失败", "error", err)
+			slog.Warn("redis_close_failed", sdk.LogFieldError, err)
 		}
 	}()
 
+	slog.Info("bootstrap_completed", "duration_ms", time.Since(bootStart).Milliseconds())
+
 	// 创建并启动 HTTP 服务器
 	srv := server.NewServer(cfg, db, rdb)
 

backend/config.yaml.example

@@ -25,6 +25,12 @@ security:
   api_key_secret: ""             # 可选，API Key 加密密钥（hex 编码，≥64 字符）
                                  # 未配置时使用内置默认值；或设置环境变量 API_KEY_SECRET
 
+log:
+  level: "info"                  # debug / info / warn / error；core 设置会自动透传给所有插件
+                                 # 或设置环境变量 LOG_LEVEL
+  format: "text"                 # text（人看）/ json（对接 Loki / ELK / Datadog）
+                                 # 或设置环境变量 LOG_FORMAT
+
 plugins:
   dir: data/plugins
   dev: []

backend/internal/app/account/service.go

@@ -92,14 +92,38 @@ func (s *Service) List(ctx context.Context, filter ListFilter) (ListResult, erro
 	}
 
 	ids := make([]int, 0, len(accounts))
+	openaiIDs := make([]int, 0, len(accounts))
 	for _, item := range accounts {
 		ids = append(ids, item.ID)
+		// 生图统计仅 OpenAI 平台账号需要：其它平台没有 image endpoint，跑 SQL 也是 0 行白浪费。
+		if item.Platform == "openai" {
+			openaiIDs = append(openaiIDs, item.ID)
+		}
 	}
 	counts := s.concurrency.GetCurrentCounts(ctx, ids)
 	for index := range accounts {
 		accounts[index].CurrentConcurrency = counts[accounts[index].ID]
 	}
 
+	// 生图请求计数：今日 + 累计。BatchImageStats 失败不阻断主响应（运维路径优先稳定）。
+	if len(openaiIDs) > 0 {
+		todayStart := timezone.StartOfDay(s.now().In(time.Local))
+		if imageStats, err := s.repo.BatchImageStats(ctx, openaiIDs, todayStart); err == nil {
+			for index := range accounts {
+				if accounts[index].Platform != "openai" {
+					continue
+				}
+				if entry, ok := imageStats[accounts[index].ID]; ok {
+					stats := entry
+					accounts[index].ImageStats = &stats
+				} else {
+					// 没记录：显式给个零值结构，让前端拿到 today=0/total=0 而不是 nil（区分"没数据"和"非 openai"）
+					accounts[index].ImageStats = &AccountImageStats{}
+				}
+			}
+		}
+	}
+
 	return ListResult{
 		List:     accounts,
 		Total:    total,
@@ -110,10 +134,22 @@ func (s *Service) List(ctx context.Context, filter ListFilter) (ListResult, erro
 
 // Create 创建账号。
 func (s *Service) Create(ctx context.Context, input CreateInput) (Account, error) {
+	logger := sdk.LoggerFromContext(ctx)
 	account, err := s.repo.Create(ctx, input)
-	if err == nil {
-		s.InvalidateUsageCache("") // 新账号创建后清除用量缓存
-	}
+	if err != nil {
+		logger.Error("account_credential_persist_failed",
+			sdk.LogFieldPlatform, input.Platform,
+			"type", input.Type,
+			"name", input.Name,
+			sdk.LogFieldError, err)
+		return account, err
+	}
+	logger.Info("account_created",
+		sdk.LogFieldAccountID, account.ID,
+		sdk.LogFieldPlatform, account.Platform,
+		"type", account.Type,
+		"name", account.Name)
+	s.InvalidateUsageCache("") // 新账号创建后清除用量缓存
 	return account, err
 }
 
@@ -144,15 +180,39 @@ func (s *Service) Import(ctx context.Context, items []CreateInput) ImportSummary
 
 // Update 更新账号。
 func (s *Service) Update(ctx context.Context, id int, input UpdateInput) (Account, error) {
-	return s.repo.Update(ctx, id, input)
+	logger := sdk.LoggerFromContext(ctx)
+	updated, err := s.repo.Update(ctx, id, input)
+	if err != nil {
+		logger.Error("account_credential_persist_failed",
+			sdk.LogFieldAccountID, id,
+			sdk.LogFieldError, err)
+		return updated, err
+	}
+	switch {
+	case input.State != nil:
+		logger.Info("account_status_changed",
+			sdk.LogFieldAccountID, id,
+			"state", *input.State)
+	case input.MaxConcurrency != nil || input.RateMultiplier != nil:
+		logger.Info("account_quota_updated",
+			sdk.LogFieldAccountID, id)
+	}
+	return updated, err
 }
 
 // Delete 删除账号。
 func (s *Service) Delete(ctx context.Context, id int) error {
+	logger := sdk.LoggerFromContext(ctx)
 	err := s.repo.Delete(ctx, id)
-	if err == nil {
-		s.InvalidateUsageCache("")
+	if err != nil {
+		logger.Error("account_credential_persist_failed",
+			sdk.LogFieldAccountID, id,
+			"op", "delete",
+			sdk.LogFieldError, err)
+		return err
 	}
+	logger.Info("account_deleted", sdk.LogFieldAccountID, id)
+	s.InvalidateUsageCache("")
 	return err
 }
 
@@ -212,8 +272,12 @@ func (r *BulkResult) appendFailure(id int, err error) {
 // ToggleScheduling 快速切换账号调度状态。active ↔ disabled。
 // 其它中间态（rate_limited / degraded）一律视为"非 disabled"，切换后目标 = disabled。
 func (s *Service) ToggleScheduling(ctx context.Context, id int) (ToggleResult, error) {
+	logger := sdk.LoggerFromContext(ctx)
 	item, err := s.repo.FindByID(ctx, id, LoadOptions{})
 	if err != nil {
+		logger.Error("account_lookup_failed",
+			sdk.LogFieldAccountID, id,
+			sdk.LogFieldError, err)
 		return ToggleResult{}, err
 	}
 
@@ -224,20 +288,35 @@ func (s *Service) ToggleScheduling(ctx context.Context, id int) (ToggleResult, e
 
 	updated, err := s.repo.Update(ctx, id, UpdateInput{State: &newState})
 	if err != nil {
+		logger.Error("account_credential_persist_failed",
+			sdk.LogFieldAccountID, id,
+			"op", "toggle_scheduling",
+			sdk.LogFieldError, err)
 		return ToggleResult{}, err
 	}
+	logger.Info("account_status_changed",
+		sdk.LogFieldAccountID, id,
+		"state", updated.State)
 	return ToggleResult{ID: updated.ID, State: updated.State}, nil
 }
 
 // PrepareConnectivityTest 准备账号连通性测试。
 func (s *Service) PrepareConnectivityTest(ctx context.Context, id int, modelID string) (*ConnectivityTest, error) {
+	logger := sdk.LoggerFromContext(ctx)
 	item, err := s.repo.FindByID(ctx, id, LoadOptions{WithProxy: true})
 	if err != nil {
+		logger.Error("account_lookup_failed",
+			sdk.LogFieldAccountID, id,
+			sdk.LogFieldError, err)
 		return nil, err
 	}
 
 	inst := s.plugins.GetPluginByPlatform(item.Platform)
 	if inst == nil || inst.Gateway == nil {
+		logger.Warn("account_credential_validation_failed",
+			sdk.LogFieldAccountID, id,
+			sdk.LogFieldPlatform, item.Platform,
+			sdk.LogFieldReason, "plugin_not_found")
 		return nil, ErrPluginNotFound
 	}
 
@@ -808,13 +887,21 @@ func (s *Service) GetCredentialsSchema(platform string) CredentialSchema {
 
 // RefreshQuota 刷新账号额度。
 func (s *Service) RefreshQuota(ctx context.Context, id int) (QuotaRefreshResult, error) {
+	logger := sdk.LoggerFromContext(ctx)
 	item, err := s.repo.FindByID(ctx, id, LoadOptions{})
 	if err != nil {
+		logger.Error("account_lookup_failed",
+			sdk.LogFieldAccountID, id,
+			sdk.LogFieldError, err)
 		return QuotaRefreshResult{}, err
 	}
 
 	inst := s.plugins.GetPluginByPlatform(item.Platform)
 	if inst == nil || inst.Gateway == nil {
+		logger.Warn("account_credential_validation_failed",
+			sdk.LogFieldAccountID, id,
+			sdk.LogFieldPlatform, item.Platform,
+			sdk.LogFieldReason, "quota_refresh_unsupported")
 		return QuotaRefreshResult{}, ErrQuotaRefreshUnsupported
 	}
 
@@ -825,8 +912,16 @@ func (s *Service) RefreshQuota(ctx context.Context, id int) (QuotaRefreshResult,
 	if err != nil {
 		// 识别插件返回的 reauth_required 前缀（字符串识别，gRPC 不透传 sentinel error）。
 		if strings.Contains(err.Error(), reauthRequiredPrefix) {
+			logger.Warn("account_credential_validation_failed",
+				sdk.LogFieldAccountID, id,
+				sdk.LogFieldPlatform, item.Platform,
+				sdk.LogFieldReason, "reauth_required")
 			return QuotaRefreshResult{}, ErrReauthRequired
 		}
+		logger.Error("account_credential_validation_failed",
+			sdk.LogFieldAccountID, id,
+			sdk.LogFieldPlatform, item.Platform,
+			sdk.LogFieldError, err)
 		return QuotaRefreshResult{}, fmt.Errorf("刷新额度失败: %w", err)
 	}
 
@@ -853,6 +948,10 @@ func (s *Service) RefreshQuota(ctx context.Context, id int) (QuotaRefreshResult,
 	}
 	if updated {
 		if err := s.repo.SaveCredentials(ctx, id, credentials); err != nil {
+			logger.Error("account_credential_persist_failed",
+				sdk.LogFieldAccountID, id,
+				"op", "save_credentials",
+				sdk.LogFieldError, err)
 			return QuotaRefreshResult{}, err
 		}
 	}
@@ -885,17 +984,23 @@ func (s *Service) triggerUsageProbe(ctx context.Context, inst *plugin.PluginInst
 	defer cancel()
 	status, _, _, err := inst.Gateway.HandleHTTPRequest(probeCtx, "POST", "usage/probe", "", nil, reqBody)
 	if err != nil || status != http.StatusOK {
-		slog.Debug("usage/probe 探测失败（降级：等下一轮 5 分钟缓存过期重试）",
-			"account_id", id, "status", status, "error", err)
+		slog.Debug("account_usage_probe_failed",
+			sdk.LogFieldAccountID, id,
+			sdk.LogFieldStatus, status,
+			sdk.LogFieldError, err)
 	}
 	// 清掉本进程的 usage 5 分钟缓存，让下一次 GetAccountUsage 重新从插件拉窗口数据。
 	s.InvalidateUsageCache("")
 }
 
 // GetStats 获取单个账号统计。
 func (s *Service) GetStats(ctx context.Context, id int, query StatsQuery) (StatsResult, error) {
+	logger := sdk.LoggerFromContext(ctx)
 	item, err := s.repo.FindByID(ctx, id, LoadOptions{})
 	if err != nil {
+		logger.Error("account_lookup_failed",
+			sdk.LogFieldAccountID, id,
+			sdk.LogFieldError, err)
 		return StatsResult{}, err
 	}
 
@@ -908,6 +1013,10 @@ func (s *Service) GetStats(ctx context.Context, id int, query StatsQuery) (Stats
 
 	logs, err := s.repo.FindUsageLogs(ctx, id, startDate, endDate)
 	if err != nil {
+		logger.Error("account_lookup_failed",
+			sdk.LogFieldAccountID, id,
+			"op", "find_usage_logs",
+			sdk.LogFieldError, err)
 		return StatsResult{}, err
 	}