From 42475e687a24b2b054c3212bf29cf205fd11eea5 Mon Sep 17 00:00:00 2001 From: yml2213 Date: Tue, 14 Jul 2026 16:33:42 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E6=95=B0=E6=8D=AE=E5=BA=93?= =?UTF-8?q?=E6=B3=A2=E5=8A=A8=E5=AF=BC=E8=87=B4=E5=90=8E=E5=8F=B0=E6=8E=89?= =?UTF-8?q?=E7=BA=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- backend/internal/middleware/auth.go | 36 +++++++++++++++++-- backend/internal/middleware/request_logger.go | 3 ++ backend/internal/modules/adminauth/handler.go | 2 +- .../internal/modules/adminauth/repository.go | 14 ++++++-- backend/internal/modules/adminauth/service.go | 29 +++++++++++++++ 5 files changed, 78 insertions(+), 6 deletions(-) diff --git a/backend/internal/middleware/auth.go b/backend/internal/middleware/auth.go index ee794dc..1ffa72f 100644 --- a/backend/internal/middleware/auth.go +++ b/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 { diff --git a/backend/internal/middleware/request_logger.go b/backend/internal/middleware/request_logger.go index c06583e..64b4678 100644 --- a/backend/internal/middleware/request_logger.go +++ b/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)) } diff --git a/backend/internal/modules/adminauth/handler.go b/backend/internal/modules/adminauth/handler.go index e92da17..87597ee 100644 --- a/backend/internal/modules/adminauth/handler.go +++ b/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 } diff --git a/backend/internal/modules/adminauth/repository.go b/backend/internal/modules/adminauth/repository.go index a350abb..3dcae3f 100644 --- a/backend/internal/modules/adminauth/repository.go +++ b/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 { diff --git a/backend/internal/modules/adminauth/service.go b/backend/internal/modules/adminauth/service.go index 49aa2d4..6f4c7db 100644 --- a/backend/internal/modules/adminauth/service.go +++ b/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 }