11 KiB
认证与授权
**本文档引用的文件** - [rbac_model.conf](file://configs/casbin/rbac_model.conf) - [jwt.go](file://pkg/auth/jwt.go) - [manager.go](file://pkg/auth/manager.go) - [auth.go](file://internal/middleware/auth.go) - [auth_handler.go](file://internal/handler/auth_handler.go) - [token.go](file://internal/model/token.go) - [token_service.go](file://internal/service/token_service.go) - [user_service.go](file://internal/service/user_service.go) - [user.go](file://internal/model/user.go) - [config.go](file://pkg/config/config.go) - [routes.go](file://internal/handler/routes.go) - [audit_log.go](file://internal/model/audit_log.go)目录
简介
CarrotSkin项目实现了一套完整的认证与授权安全机制，采用JWT（JSON Web Token）进行用户认证，并结合Casbin实现基于角色的访问控制（RBAC）。该系统为用户提供安全的注册、登录、密码重置功能，同时通过中间件对API请求进行权限验证。本文档详细说明了系统的安全架构、JWT认证流程、Casbin权限模型配置以及认证中间件的实现细节。
项目结构
CarrotSkin项目的认证与授权相关代码分布在多个目录中，形成了清晰的分层架构。核心安全功能主要集中在pkg/auth包中，而具体的业务逻辑则分布在internal目录下的各个模块。
graph TB
subgraph "配置"
config[configs/casbin/rbac_model.conf]
end
subgraph "内部处理"
handler[internal/handler]
middleware[internal/middleware]
model[internal/model]
service[internal/service]
repository[internal/repository]
end
subgraph "公共包"
auth[pkg/auth]
config_pkg[pkg/config]
database[pkg/database]
redis[pkg/redis]
end
config --> auth
auth --> middleware
middleware --> handler
handler --> service
service --> repository
repository --> database
service --> redis
Diagram sources
Section sources
核心组件
CarrotSkin项目的认证与授权系统由多个核心组件构成，包括JWT服务、认证中间件、Casbin权限管理器、用户服务和令牌服务。这些组件协同工作，确保系统的安全性。
Section sources
架构概述
CarrotSkin的认证与授权架构采用分层设计，从下到上的层次包括：配置层、认证服务层、中间件层、处理器层和路由层。这种设计实现了关注点分离，提高了代码的可维护性和可测试性。
graph TD
A[客户端] --> B[HTTP请求]
B --> C{路由}
C --> D[/认证路由\n无需JWT/]
C --> E[/受保护路由\n需要JWT/]
D --> F[auth_handler]
E --> G[AuthMiddleware]
G --> H{验证JWT}
H --> |有效| I[业务处理器]
H --> |无效| J[返回401]
I --> K[service]
K --> L[repository]
L --> M[(数据库)]
G --> N[Casbin权限检查]
N --> |允许| I
N --> |拒绝| O[返回403]
P[JWT配置] --> Q[jwt.go]
Q --> R[AuthMiddleware]
S[Casbin配置] --> T[CasbinRule]
T --> N
Diagram sources
详细组件分析
JWT认证服务分析
JWT认证服务是CarrotSkin安全机制的核心，负责生成和验证JWT令牌。该服务实现了标准的JWT功能，包括令牌的签发、验证和声明管理。
JWT服务类图
classDiagram
class JWTService {
+string secretKey
+int expireHours
+GenerateToken(userID int64, username string, role string) (string, error)
+ValidateToken(tokenString string) (*Claims, error)
}
class Claims {
+int64 UserID
+string Username
+string Role
+jwt.RegisteredClaims
}
class JWTManager {
-static *JWTService jwtServiceInstance
-static sync.Once once
+Init(cfg JWTConfig) error
+GetJWTService() (*JWTService, error)
+MustGetJWTService() *JWTService
}
JWTManager --> JWTService : "创建"
JWTService --> Claims : "包含"
Diagram sources
Section sources
认证中间件分析
认证中间件负责在请求处理流程中验证JWT令牌的有效性。它拦截所有受保护的API请求，确保只有携带有效令牌的请求才能访问受保护的资源。
认证中间件流程图
flowchart TD
Start([开始]) --> GetHeader["获取Authorization头"]
GetHeader --> HeaderEmpty{"头为空?"}
HeaderEmpty --> |是| Return401Unauthorized["返回401未授权"]
HeaderEmpty --> |否| ParseHeader["解析Bearer格式"]
ParseHeader --> FormatValid{"格式有效?"}
FormatValid --> |否| Return401InvalidFormat["返回401无效格式"]
FormatValid --> |是| ExtractToken["提取Token"]
ExtractToken --> ValidateToken["验证Token"]
ValidateToken --> TokenValid{"Token有效?"}
TokenValid --> |否| Return401InvalidToken["返回401无效Token"]
TokenValid --> |是| StoreUserInfo["将用户信息存入上下文"]
StoreUserInfo --> Next["调用下一个处理器"]
Next --> End([结束])
Return401Unauthorized --> End
Return401InvalidFormat --> End
Return401InvalidToken --> End
Diagram sources
Section sources
Casbin RBAC权限模型分析
CarrotSkin使用Casbin实现基于角色的访问控制（RBAC）模型，通过配置文件定义权限策略，实现灵活的权限管理。
Casbin RBAC模型配置
[request_definition]
r = sub, obj, act
[policy_definition]
p = sub, obj, act
[role_definition]
g = _, _
[policy_effect]
e = some(where (p.eft == allow))
[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act
Diagram sources
Section sources
用户认证流程分析
用户认证流程涵盖了从注册、登录到密码重置的完整生命周期，确保用户身份的安全管理。
用户认证流程序列图
sequenceDiagram
participant Client as "客户端"
participant Handler as "AuthHandler"
participant Service as "UserService"
participant JWT as "JWTService"
participant DB as "数据库"
Client->>Handler : POST /api/v1/auth/register
Handler->>Service : RegisterUser()
Service->>DB : 检查用户名/邮箱是否存在
DB-->>Service : 返回检查结果
Service->>JWT : HashPassword()
Service->>DB : 创建用户记录
DB-->>Service : 用户对象
Service->>JWT : GenerateToken()
JWT-->>Service : JWT Token
Service-->>Handler : 用户和Token
Handler-->>Client : 200 OK {token, userInfo}
Client->>Handler : POST /api/v1/auth/login
Handler->>Service : LoginUser()
Service->>DB : 查找用户(用户名/邮箱)
DB-->>Service : 用户对象
Service->>JWT : CheckPassword()
Service->>JWT : GenerateToken()
JWT-->>Service : JWT Token
Service-->>Handler : 用户和Token
Handler-->>Client : 200 OK {token, userInfo}
Diagram sources
Section sources
依赖分析
CarrotSkin的认证与授权系统依赖于多个外部包和内部组件，形成了复杂的依赖关系网络。
graph TD
A[pkg/auth] --> B[github.com/golang-jwt/jwt/v5]
A --> C[pkg/config]
D[internal/middleware] --> A
D --> E[github.com/gin-gonic/gin]
F[internal/handler] --> D
F --> G[internal/service]
G --> A
G --> H[pkg/database]
G --> I[pkg/redis]
J[pkg/config] --> K[github.com/spf13/viper]
J --> L[github.com/joho/godotenv]
H --> M[gorm.io/gorm]
I --> N[github.com/redis/go-redis]
Diagram sources
Section sources
性能考虑
CarrotSkin的认证与授权系统在设计时考虑了性能因素，通过多种机制确保系统的高效运行。
- JWT令牌验证：JWT令牌的验证是无状态的，不需要查询数据库，大大提高了验证速度。
- Redis缓存：系统使用Redis存储验证码等临时数据，减少了数据库的压力。
- 连接池：数据库和Redis都使用了连接池，避免了频繁创建和销毁连接的开销。
- 异步操作：某些非关键操作（如清理多余令牌）使用goroutine异步执行，不影响主流程性能。
- 批量操作：在清理多余令牌时，使用批量删除操作，减少了数据库交互次数。
Section sources
故障排除指南
当遇到认证与授权相关的问题时，可以参考以下常见问题的解决方案：
-
401 Unauthorized错误：
- 检查请求头中是否包含
Authorization头 - 确认
Authorization头的格式是否为Bearer <token> - 验证JWT令牌是否已过期
- 检查JWT密钥配置是否正确
- 检查请求头中是否包含
-
403 Forbidden错误：
- 检查用户角色是否有权限访问该资源
- 验证Casbin策略配置是否正确
- 确认请求的资源和操作是否匹配策略
-
登录失败：
- 检查用户名/邮箱和密码是否正确
- 确认用户账户状态是否正常（未被禁用）
- 检查数据库连接是否正常
-
令牌刷新失败：
- 确认旧令牌是否有效
- 检查客户端令牌是否匹配
- 验证用户是否有权限选择指定的角色
Section sources
结论
CarrotSkin项目实现了一套完整且安全的认证与授权机制，通过JWT和Casbin的结合，提供了灵活的用户身份验证和细粒度的权限控制。系统的分层架构使得各个组件职责清晰，易于维护和扩展。对于初学者，系统提供了清晰的API文档和错误处理机制；对于经验丰富的开发者，系统提供了扩展权限模型和集成其他认证方式的可能性。整体而言，CarrotSkin的安全机制设计合理，能够有效保护系统资源，为用户提供安全可靠的服务。