211 lines
9.2 KiB
Markdown
211 lines
9.2 KiB
Markdown
# RBAC权限控制
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [rbac_model.conf](file://configs/casbin/rbac_model.conf)
|
||
- [auth.go](file://internal/middleware/auth.go)
|
||
- [user_service.go](file://internal/service/user_service.go)
|
||
- [user_repository.go](file://internal/repository/user_repository.go)
|
||
- [audit_log.go](file://internal/model/audit_log.go)
|
||
- [config.go](file://pkg/config/config.go)
|
||
- [carrotskin_postgres.sql](file://scripts/carrotskin_postgres.sql)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [项目结构](#项目结构)
|
||
2. [核心组件](#核心组件)
|
||
3. [架构概述](#架构概述)
|
||
4. [详细组件分析](#详细组件分析)
|
||
5. [依赖分析](#依赖分析)
|
||
6. [性能考虑](#性能考虑)
|
||
7. [故障排除指南](#故障排除指南)
|
||
8. [结论](#结论)
|
||
|
||
## 项目结构
|
||
|
||
项目采用分层架构设计，权限控制相关文件主要分布在`configs/casbin/`和`internal/middleware/`目录下。`rbac_model.conf`文件定义了基于Casbin的RBAC权限模型，而`auth.go`文件实现了JWT认证中间件，为权限系统提供用户身份验证。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "配置"
|
||
rbac_model_conf[rbac_model.conf]
|
||
end
|
||
subgraph "中间件"
|
||
auth_go[auth.go]
|
||
end
|
||
subgraph "服务层"
|
||
user_service_go[user_service.go]
|
||
end
|
||
subgraph "数据模型"
|
||
audit_log_go[audit_log.go]
|
||
end
|
||
rbac_model_conf --> auth_go
|
||
auth_go --> user_service_go
|
||
user_service_go --> audit_log_go
|
||
```
|
||
|
||
**图示来源**
|
||
- [rbac_model.conf](file://configs/casbin/rbac_model.conf)
|
||
- [auth.go](file://internal/middleware/auth.go)
|
||
- [user_service.go](file://internal/service/user_service.go)
|
||
- [audit_log.go](file://internal/model/audit_log.go)
|
||
|
||
**本节来源**
|
||
- [rbac_model.conf](file://configs/casbin/rbac_model.conf)
|
||
- [auth.go](file://internal/middleware/auth.go)
|
||
|
||
## 核心组件
|
||
|
||
系统的核心权限控制组件包括Casbin权限模型配置、JWT认证中间件和用户服务。`rbac_model.conf`文件定义了请求定义、策略定义、角色定义、匹配器和策略效果等关键部分。`auth.go`文件中的`AuthMiddleware`函数实现了JWT认证逻辑，确保只有经过身份验证的用户才能访问受保护的资源。`user_service.go`文件中的用户服务函数处理用户注册、登录等操作，并在注册时为新用户分配默认角色。
|
||
|
||
**本节来源**
|
||
- [rbac_model.conf](file://configs/casbin/rbac_model.conf)
|
||
- [auth.go](file://internal/middleware/auth.go)
|
||
- [user_service.go](file://internal/service/user_service.go)
|
||
|
||
## 架构概述
|
||
|
||
系统采用基于Casbin的RBAC（基于角色的访问控制）权限模型。该模型通过`rbac_model.conf`文件定义，包含请求定义、策略定义、角色定义、匹配器和策略效果五个部分。JWT认证中间件负责用户身份验证，将用户信息存储在请求上下文中。用户服务处理用户相关的业务逻辑，并在注册时为用户分配角色。权限检查在中间件或服务层进行，通过将用户角色（role）与访问资源（obj）和操作（act）进行匹配来决定是否允许访问。
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[客户端] --> B[JWT认证中间件]
|
||
B --> C{身份验证}
|
||
C --> |成功| D[权限检查]
|
||
C --> |失败| E[返回401]
|
||
D --> F{权限允许?}
|
||
F --> |是| G[执行操作]
|
||
F --> |否| H[返回403]
|
||
G --> I[返回结果]
|
||
```
|
||
|
||
**图示来源**
|
||
- [auth.go](file://internal/middleware/auth.go)
|
||
|
||
## 详细组件分析
|
||
|
||
### RBAC模型配置分析
|
||
|
||
`rbac_model.conf`文件定义了系统的权限模型。请求定义`r = sub, obj, act`表示权限检查请求包含主体（用户或角色）、对象（资源）和动作（操作）三个部分。策略定义`p = sub, obj, act`定义了权限策略的结构。角色定义`g = _, _`用于建立角色继承关系。匹配器`m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act`是权限检查的核心逻辑，它首先通过`g(r.sub, p.sub)`检查请求主体是否具有策略主体的角色，然后检查请求的对象和动作是否与策略匹配。策略效果`e = some(where (p.eft == allow))`表示只要存在一条允许的策略，就允许访问。
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class RBACModel {
|
||
+request_definition : r = sub, obj, act
|
||
+policy_definition : p = sub, obj, act
|
||
+role_definition : g = _, _
|
||
+matchers : m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act
|
||
+policy_effect : e = some(where (p.eft == allow))
|
||
}
|
||
```
|
||
|
||
**图示来源**
|
||
- [rbac_model.conf](file://configs/casbin/rbac_model.conf)
|
||
|
||
**本节来源**
|
||
- [rbac_model.conf](file://configs/casbin/rbac_model.conf)
|
||
|
||
### JWT认证中间件分析
|
||
|
||
`auth.go`文件中的`AuthMiddleware`函数实现了JWT认证中间件。该中间件从请求头中提取JWT令牌，验证其有效性，并将用户信息存储在请求上下文中。`OptionalAuthMiddleware`函数提供了可选的JWT认证，允许未认证用户访问某些资源。这两个中间件为系统的权限控制提供了基础的身份验证功能。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as 客户端
|
||
participant Middleware as 认证中间件
|
||
participant JWTService as JWT服务
|
||
Client->>Middleware : 发送请求(Authorization头)
|
||
Middleware->>Middleware : 检查Authorization头
|
||
alt 头部不存在
|
||
Middleware-->>Client : 返回401(缺少Authorization头)
|
||
else 有效格式
|
||
Middleware->>JWTService : 验证令牌
|
||
alt 令牌有效
|
||
JWTService-->>Middleware : 返回用户声明
|
||
Middleware->>Middleware : 将用户信息存入上下文
|
||
Middleware->>Client : 继续处理请求
|
||
else 令牌无效
|
||
Middleware-->>Client : 返回401(无效的token)
|
||
end
|
||
end
|
||
```
|
||
|
||
**图示来源**
|
||
- [auth.go](file://internal/middleware/auth.go)
|
||
|
||
**本节来源**
|
||
- [auth.go](file://internal/middleware/auth.go)
|
||
|
||
### 用户服务分析
|
||
|
||
`user_service.go`文件中的`RegisterUser`函数处理用户注册逻辑。在创建用户时，该函数将用户的`Role`字段设置为"user"，为新用户分配默认角色。`LoginUser`函数处理用户登录，验证用户名/邮箱和密码的正确性，并在成功登录后生成JWT令牌。这些服务函数与权限系统紧密集成，确保用户在注册和登录时正确地获得和验证其角色。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start([注册用户]) --> CheckUsername["检查用户名是否已存在"]
|
||
CheckUsername --> UsernameExists{"用户名已存在?"}
|
||
UsernameExists --> |是| ReturnError1["返回错误: 用户名已存在"]
|
||
UsernameExists --> |否| CheckEmail["检查邮箱是否已存在"]
|
||
CheckEmail --> EmailExists{"邮箱已存在?"}
|
||
EmailExists --> |是| ReturnError2["返回错误: 邮箱已被注册"]
|
||
EmailExists --> |否| HashPassword["加密密码"]
|
||
HashPassword --> CreateAvatar["确定头像URL"]
|
||
CreateAvatar --> CreateUser["创建用户(角色=user)"]
|
||
CreateUser --> GenerateToken["生成JWT Token"]
|
||
GenerateToken --> ReturnSuccess["返回用户信息和Token"]
|
||
ReturnError1 --> End([结束])
|
||
ReturnError2 --> End
|
||
ReturnSuccess --> End
|
||
```
|
||
|
||
**图示来源**
|
||
- [user_service.go](file://internal/service/user_service.go)
|
||
|
||
**本节来源**
|
||
- [user_service.go](file://internal/service/user_service.go)
|
||
|
||
## 依赖分析
|
||
|
||
系统各组件之间存在明确的依赖关系。`auth.go`依赖于`pkg/auth/jwt.go`提供的JWT服务进行令牌验证。`user_service.go`依赖于`repository/user_repository.go`进行数据库操作，并依赖于`pkg/auth/password.go`进行密码加密。`rbac_model.conf`被Casbin引擎读取，用于定义权限模型。这些依赖关系确保了系统的模块化和可维护性。
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[auth.go] --> B[jwt.go]
|
||
C[user_service.go] --> D[user_repository.go]
|
||
C --> E[password.go]
|
||
F[rbac_model.conf] --> G[Casbin引擎]
|
||
```
|
||
|
||
**图示来源**
|
||
- [auth.go](file://internal/middleware/auth.go)
|
||
- [user_service.go](file://internal/service/user_service.go)
|
||
- [user_repository.go](file://internal/repository/user_repository.go)
|
||
- [rbac_model.conf](file://configs/casbin/rbac_model.conf)
|
||
|
||
**本节来源**
|
||
- [auth.go](file://internal/middleware/auth.go)
|
||
- [user_service.go](file://internal/service/user_service.go)
|
||
- [user_repository.go](file://internal/repository/user_repository.go)
|
||
- [rbac_model.conf](file://configs/casbin/rbac_model.conf)
|
||
|
||
## 性能考虑
|
||
|
||
系统的权限控制设计考虑了性能因素。JWT令牌在客户端存储，减少了服务器的认证开销。Casbin的权限检查算法经过优化，能够快速匹配权限策略。数据库查询使用了适当的索引，如`casbin_rule`表上的`ptype`、`v0`、`v1`索引，提高了权限检查的效率。对于高并发场景，可以考虑将权限策略缓存到Redis中，进一步提高性能。
|
||
|
||
## 故障排除指南
|
||
|
||
当遇到权限相关问题时，可以按照以下步骤进行排查：
|
||
1. 检查JWT令牌是否正确生成和传递。
|
||
2. 验证`rbac_model.conf`文件的语法是否正确。
|
||
3. 检查数据库中的`casbin_rule`表是否包含正确的权限策略。
|
||
4. 确认用户的角色是否正确分配。
|
||
5. 查看系统日志，寻找权限拒绝的记录。
|
||
|
||
**本节来源**
|
||
- [auth.go](file://internal/middleware/auth.go)
|
||
- [rbac_model.conf](file://configs/casbin/rbac_model.conf)
|
||
- [audit_log.go](file://internal/model/audit_log.go)
|
||
|
||
## 结论
|
||
|
||
本系统采用基于Casbin的RBAC权限模型，通过`rbac_model.conf`文件定义权限策略，使用JWT认证中间件进行身份验证。该设计提供了灵活、可扩展的权限控制机制，能够满足不同场景下的权限管理需求。通过合理配置权限策略，可以实现细粒度的访问控制，确保系统的安全性。 |