# 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认证中间件进行身份验证。该设计提供了灵活、可扩展的权限控制机制，能够满足不同场景下的权限管理需求。通过合理配置权限策略，可以实现细粒度的访问控制，确保系统的安全性。