修复数据库波动导致后台掉线

backend/internal/middleware/auth.go

@@ -23,6 +23,7 @@ const (
 	ContextAuthTokenSource    = "auth_token_source"
 	ContextAuthTokenVersion   = "auth_token_version"
 	ContextAuthCurrentVersion = "auth_current_token_version"
+	ContextAuthFailureDetail  = "auth_failure_detail"
 	AdminAccessCookieName     = "hfb_admin_access"
 )
 
@@ -103,7 +104,12 @@ func AdminAuth(jwtManager *auth.JWTManager, validate AdminTokenValidatorFunc) gi
 			tokenContext, err := validate(c.Request.Context(), claims.UserID, claims.TokenVersion)
 			if err != nil {
 				reason, tokenVersion, currentVersion := AdminValidationFailure(err)
-				RecordAdminAuthFailure(c, reason, tokenSource, tokenVersion, currentVersion)
+				RecordAdminAuthFailure(c, reason, tokenSource, tokenVersion, currentVersion, AdminValidationFailureDetail(err))
+				if AdminValidationUnavailable(err) {
+					response.ServiceUnavailable(c, "后台认证服务暂时不可用")
+					c.Abort()
+					return
+				}
 				response.Unauthorized(c, "后台访问令牌无效或已过期")
 				c.Abort()
 				return
@@ -126,6 +132,14 @@ type authFailureVersionCarrier interface {
 	AuthFailureVersions() (int64, int64)
 }
 
+type authFailureDetailCarrier interface {
+	AuthFailureDetail() string
+}
+
+type authFailureUnavailableCarrier interface {
+	AuthFailureUnavailable() bool
+}
+
 // AdminValidationFailure 将认证包内部错误转换为安全、可观测的失败类别。
 func AdminValidationFailure(err error) (string, int64, int64) {
 	reason := "admin_validation_failed"
@@ -141,14 +155,32 @@ func AdminValidationFailure(err error) (string, int64, int64) {
 	return reason, 0, 0
 }
 
+// AdminValidationFailureDetail 返回仅供服务端日志记录的安全错误摘要。
+func AdminValidationFailureDetail(err error) string {
+	var detailCarrier authFailureDetailCarrier
+	if errors.As(err, &detailCarrier) {
+		return detailCarrier.AuthFailureDetail()
+	}
+	return ""
+}
+
+// AdminValidationUnavailable 判断失败是否由临时依赖故障引起。
+func AdminValidationUnavailable(err error) bool {
+	var unavailableCarrier authFailureUnavailableCarrier
+	return errors.As(err, &unavailableCarrier) && unavailableCarrier.AuthFailureUnavailable()
+}
+
 // RecordAdminAuthFailure 把认证失败诊断字段写入请求上下文，供访问日志统一输出。
-func RecordAdminAuthFailure(c *gin.Context, reason, source string, tokenVersion, currentVersion int64) {
+func RecordAdminAuthFailure(c *gin.Context, reason, source string, tokenVersion, currentVersion int64, detail ...string) {
 	c.Set(ContextAuthFailureReason, reason)
 	c.Set(ContextAuthTokenSource, source)
 	if tokenVersion != 0 || currentVersion != 0 {
 		c.Set(ContextAuthTokenVersion, tokenVersion)
 		c.Set(ContextAuthCurrentVersion, currentVersion)
 	}
+	if len(detail) > 0 && detail[0] != "" {
+		c.Set(ContextAuthFailureDetail, detail[0])
+	}
 }
 
 func RequireAdminPasswordChanged() gin.HandlerFunc {

backend/internal/middleware/request_logger.go

@@ -54,6 +54,9 @@ func RequestLogger(logger *zap.Logger) gin.HandlerFunc {
 		if source, ok := c.Get(ContextAuthTokenSource); ok {
 			fields = append(fields, zap.Any("auth_token_source", source))
 		}
+		if detail, ok := c.Get(ContextAuthFailureDetail); ok {
+			fields = append(fields, zap.Any("auth_failure_detail", detail))
+		}
 		if tokenVersion, ok := c.Get(ContextAuthTokenVersion); ok {
 			fields = append(fields, zap.Any("auth_token_version", tokenVersion))
 		}

backend/internal/modules/adminauth/handler.go

@@ -138,7 +138,7 @@ func (h *Handler) Refresh(c *gin.Context) {
 	tokens, err := h.service.Refresh(c.Request.Context(), refreshToken)
 	if err != nil {
 		reason, tokenVersion, currentVersion := middleware.AdminValidationFailure(err)
-		middleware.RecordAdminAuthFailure(c, reason, refreshTokenSource, tokenVersion, currentVersion)
+		middleware.RecordAdminAuthFailure(c, reason, refreshTokenSource, tokenVersion, currentVersion, middleware.AdminValidationFailureDetail(err))
 		writeAdminAuthError(c, err)
 		return
 	}

backend/internal/modules/adminauth/repository.go

@@ -92,12 +92,15 @@ func (r *Repository) Login(ctx context.Context, username string, password string
 }
 
 func (r *Repository) FindActiveForToken(ctx context.Context, id uint64, tokenVersion int64) (*model.AdminUser, error) {
+	if r.db == nil {
+		return nil, newTokenDependencyError(ErrDependencyUnavailable)
+	}
 	var admin model.AdminUser
 	if err := r.db.WithContext(ctx).First(&admin, id).Error; err != nil {
 		if errors.Is(err, gorm.ErrRecordNotFound) {
 			return nil, newTokenValidationError("admin_not_found", ErrAdminNotFound)
 		}
-		return nil, err
+		return nil, newTokenDependencyError(err)
 	}
 	if admin.Status != "active" {
 		return nil, newTokenValidationError("admin_disabled", ErrAdminDisabled)
@@ -160,10 +163,15 @@ func (r *Repository) FindByID(ctx context.Context, id uint64) (*AdminDTO, error)
 }
 
 func (r *Repository) FindActiveForPasswordGate(ctx context.Context, id uint64, tokenVersion int64) (*AdminDTO, error) {
-	if _, err := r.FindActiveForToken(ctx, id, tokenVersion); err != nil {
+	admin, err := r.FindActiveForToken(ctx, id, tokenVersion)
+	if err != nil {
 		return nil, err
 	}
-	return r.FindByID(ctx, id)
+	// 认证只需要用户名和强制改密标识；复用已校验的查询结果，避免每个后台请求再查询一次数据库。
+	return &AdminDTO{
+		Username:           admin.Username,
+		PasswordMustChange: admin.PasswordMustChange,
+	}, nil
 }
 
 func (r *Repository) UpdateSupportStatus(ctx context.Context, adminID uint64, status string) error {

backend/internal/modules/adminauth/service.go

@@ -3,6 +3,7 @@ package adminauth
 import (
 	"context"
 	"errors"
+	"strings"
 
 	"hfb_sys/backend/internal/modules/auth"
 )
@@ -23,6 +24,8 @@ type TokenValidationError struct {
 	Reason         string
 	TokenVersion   int64
 	CurrentVersion int64
+	Detail         string
+	Unavailable    bool
 	err            error
 }
 
@@ -44,10 +47,33 @@ func (e *TokenValidationError) AuthFailureVersions() (int64, int64) {
 	return e.TokenVersion, e.CurrentVersion
 }
 
+// AuthFailureDetail 返回仅供服务端日志使用的依赖错误摘要，不包含令牌内容。
+func (e *TokenValidationError) AuthFailureDetail() string {
+	return e.Detail
+}
+
+// AuthFailureUnavailable 标识当前失败是否由临时依赖故障引起。
+func (e *TokenValidationError) AuthFailureUnavailable() bool {
+	return e.Unavailable
+}
+
 func newTokenValidationError(reason string, err error) error {
 	return &TokenValidationError{Reason: reason, err: err}
 }
 
+func newTokenDependencyError(err error) error {
+	detail := strings.Join(strings.Fields(err.Error()), " ")
+	if len(detail) > 240 {
+		detail = detail[:240]
+	}
+	return &TokenValidationError{
+		Reason:      "admin_db_query_failed",
+		Detail:      detail,
+		Unavailable: true,
+		err:         errors.Join(ErrDependencyUnavailable, err),
+	}
+}
+
 func newTokenVersionMismatchError(tokenVersion, currentVersion int64) error {
 	return &TokenValidationError{
 		Reason:         "token_version_mismatch",
@@ -79,6 +105,9 @@ func (s *Service) Refresh(ctx context.Context, refreshToken string) (*auth.Token
 	}
 	admin, err := s.repo.FindActiveForToken(ctx, claims.UserID, claims.TokenVersion)
 	if err != nil {
+		if errors.Is(err, ErrDependencyUnavailable) {
+			return nil, err
+		}
 		if errors.Is(err, ErrAdminDisabled) {
 			return nil, ErrAdminDisabled
 		}