# 权限策略管理

<cite>
**本文档引用文件**  
- [sys_auth_rule.go](file://internal/model/sys_auth_rule.go)
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go)
- [sys_auth_rule.go](file://api/sys_auth_rule/v1/sys_auth_rule.go)
- [rbac_model.conf](file://resource/casbin/rbac_model.conf)
- [sys_auth_rule_v1_rule_search.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_search.go)
- [sys_auth_rule_v1_rule_add.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_add.go)
- [sys_auth_rule_v1_rule_update.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_update.go)
- [sys_auth_rule_v1_rule_delete.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_delete.go)
- [v1_sys_auth_rule.go](file://internal/dao/v_1_sys_auth_rule.go)
</cite>

## 目录
1. [简介](#简介)
2. [权限策略数据模型](#权限策略数据模型)
3. [权限策略动态管理机制](#权限策略动态管理机制)
4. [权限策略查询接口实现](#权限策略查询接口实现)
5. [权限策略持久化与一致性保障](#权限策略持久化与一致性保障)
6. [权限策略备份恢复与迁移](#权限策略备份恢复与迁移)
7. [权限策略审计日志记录](#权限策略审计日志记录)
8. [性能监控与告警配置](#性能监控与告警配置)

## 简介
本文档详细阐述了kami_backend系统中权限策略的管理机制。系统采用基于Casbin的RBAC（基于角色的访问控制）模型，实现了权限策略的动态加载、更新和同步。权限策略以菜单、按钮等形式组织，支持分层树形结构，并通过角色进行权限分配。系统提供了完整的权限策略生命周期管理功能，包括创建、查询、更新、删除以及与角色的绑定操作。

## 权限策略数据模型

权限策略的核心数据结构定义在`internal/model/sys_auth_rule.go`中，主要包含以下字段：

- **Name**: 规则名称
- **Title**: 菜单标题
- **MenuType**: 类型（0目录，1菜单，2按钮）
- **Weigh**: 权重，用于排序
- **IsHide**: 显示状态
- **Path**: 路由地址
- **IdAdmin**: 是否管理员独享
- **Component**: 组件路径
- **Children**: 子节点列表，形成树形结构

权限策略与角色的关联通过Casbin的策略规则实现，存储在数据库的`sys_casbin_rule`表中。

```mermaid
classDiagram
class SysAuthRule {
+string Name
+string Title
+uint MenuType
+int Weigh
+uint IsHide
+string Path
+int IdAdmin
+string Component
+[]*SysAuthRule Children
}
class V1SysAuthRule {
+uint Id
+string CreatedAt
+string UpdatedAt
+string DeletedAt
}
class SysAuthRuleInfoOutput {
+uint Id
+string Name
+string Title
+uint MenuType
+int Weigh
+uint IsHide
+string Path
+int IdAdmin
+string Component
+[]*SysAuthRuleInfoOutput Children
}
class SysAuthRuleTreeOutput {
+uint Id
+string Name
+string Title
+uint MenuType
+int Weigh
+uint IsHide
+string Path
+int IdAdmin
+string Component
+[]*SysAuthRuleTreeOutput Children
}
SysAuthRule <|-- V1SysAuthRule : "继承"
SysAuthRule --> SysAuthRuleInfoOutput : "转换"
SysAuthRule --> SysAuthRuleTreeOutput : "转换"
```

**Diagram sources**
- [sys_auth_rule.go](file://internal/model/sys_auth_rule.go#L7-L10)

**Section sources**
- [sys_auth_rule.go](file://internal/model/sys_auth_rule.go#L7-L40)

## 权限策略动态管理机制

权限策略的动态管理通过控制器层（Controller）和服务层（Service）协同完成。控制器接收HTTP请求，调用服务层接口执行具体业务逻辑。

### 权限策略加载流程
系统启动时，权限策略从数据库`v1_sys_auth_rule`表中加载，并构建树形结构缓存。当用户登录时，系统根据用户角色动态生成其可访问的菜单列表。

### 权限策略更新与同步流程
权限策略的更新操作（添加、修改、删除）通过API接口触发，流程如下：

1. 前端发起HTTP请求（POST/PUT/DELETE）
2. 控制器接收请求并进行参数校验
3. 调用`ISysAuthRule`服务接口执行数据库操作
4. 操作成功后，更新Casbin策略引擎中的权限规则
5. 返回操作结果给前端

```mermaid
sequenceDiagram
participant 前端 as 前端
participant 控制器 as 控制器
participant 服务 as 服务
participant 数据库 as 数据库
participant Casbin as Casbin引擎
前端->>控制器 : 发起权限更新请求
控制器->>控制器 : 参数校验
控制器->>服务 : 调用服务方法
服务->>数据库 : 执行数据库操作
数据库-->>服务 : 返回结果
服务->>Casbin : 更新策略规则
Casbin-->>服务 : 确认更新
服务-->>控制器 : 返回结果
控制器-->>前端 : 返回响应
```

**Diagram sources**
- [sys_auth_rule_v1_rule_add.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_add.go#L1-L14)
- [sys_auth_rule_v1_rule_update.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_update.go#L1-L14)
- [sys_auth_rule_v1_rule_delete.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_delete.go#L1-L14)
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go#L14-L34)

**Section sources**
- [sys_auth_rule_v1_rule_add.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_add.go#L1-L14)
- [sys_auth_rule_v1_rule_update.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_update.go#L1-L14)
- [sys_auth_rule_v1_rule_delete.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_delete.go#L1-L14)
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go#L14-L34)

## 权限策略查询接口实现

权限策略的查询接口支持分页、条件过滤和结果排序功能，主要通过`RuleSearch`接口实现。

### 查询接口定义
查询接口定义在`api/sys_auth_rule/v1/sys_auth_rule.go`中，主要参数包括：
- **Title**: 菜单名称，用于模糊匹配
- **Component**: 组件路径，用于精确匹配

### 查询实现逻辑
查询逻辑在`internal/service/sys_auth_rule.go`中实现，流程如下：
1. 接收查询请求参数
2. 构建数据库查询条件
3. 从`v1_sys_auth_rule`表中查询数据
4. 将查询结果转换为树形结构
5. 返回结果给调用方

```mermaid
flowchart TD
Start([开始]) --> ValidateInput["校验输入参数"]
ValidateInput --> InputValid{"参数有效?"}
InputValid --> |否| ReturnError["返回错误"]
InputValid --> |是| BuildQuery["构建查询条件"]
BuildQuery --> ExecuteQuery["执行数据库查询"]
ExecuteQuery --> TransformResult["转换为树形结构"]
TransformResult --> ReturnResult["返回结果"]
ReturnError --> End([结束])
ReturnResult --> End
```

**Diagram sources**
- [sys_auth_rule_v1_rule_search.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_search.go#L1-L14)
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go#L14-L34)

**Section sources**
- [sys_auth_rule_v1_rule_search.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_search.go#L1-L14)
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go#L14-L34)

## 权限策略持久化与一致性保障

### 持久化存储方案
权限策略数据持久化存储在关系型数据库中，主要涉及以下表：
- **v1_sys_auth_rule**: 存储权限策略的基本信息
- **v1_sys_casbin_rule**: 存储Casbin策略规则，实现权限的细粒度控制

### 分布式环境下的策略一致性保障
在分布式环境下，系统通过以下机制保障权限策略的一致性：
1. **数据库事务**: 所有权限策略的变更操作都使用数据库事务，确保数据的原子性和一致性。
2. **Casbin适配器**: 使用数据库适配器，确保Casbin策略引擎与数据库中的策略规则保持同步。
3. **缓存一致性**: 当权限策略变更时，清除相关缓存，确保所有节点获取到最新的权限数据。

```mermaid
erDiagram
v1_sys_auth_rule {
uint id PK
string name
string title
uint menu_type
int weigh
uint is_hide
string path
int id_admin
string component
uint parent_id FK
timestamp created_at
timestamp updated_at
}
v1_sys_casbin_rule {
uint id PK
string p_type
string v0
string v1
string v2
string v3
string v4
string v5
timestamp created_at
timestamp updated_at
}
v1_sys_auth_rule ||--o{ v1_sys_casbin_rule : "权限规则"
```

**Diagram sources**
- [v1_sys_auth_rule.go](file://internal/dao/v_1_sys_auth_rule.go#L1-L20)
- [rbac_model.conf](file://resource/casbin/rbac_model.conf#L1-L14)

**Section sources**
- [v1_sys_auth_rule.go](file://internal/dao/v_1_sys_auth_rule.go#L1-L20)
- [rbac_model.conf](file://resource/casbin/rbac_model.conf#L1-L14)

## 权限策略备份恢复与迁移

### 备份方案
权限策略的备份应包含以下内容：
1. **数据库备份**: 定期备份`v1_sys_auth_rule`和`v1_sys_casbin_rule`表的数据。
2. **配置文件备份**: 备份Casbin模型配置文件`rbac_model.conf`。

### 恢复方案
权限策略的恢复流程：
1. 恢复数据库备份到目标环境。
2. 验证数据完整性。
3. 重启服务，确保Casbin引擎重新加载策略规则。

### 迁移指南
权限策略迁移时应注意：
1. 确保源环境和目标环境的Casbin模型配置一致。
2. 迁移过程中应停止服务，避免数据不一致。
3. 迁移完成后，进行全面的权限功能测试。

**Section sources**
- [v1_sys_auth_rule.go](file://internal/dao/v_1_sys_auth_rule.go#L1-L20)
- [rbac_model.conf](file://resource/casbin/rbac_model.conf#L1-L14)

## 权限策略审计日志记录

系统通过记录权限策略的变更日志，实现操作的可追溯性。审计日志应包含以下信息：
- **操作类型**: 添加、修改、删除等
- **操作人**: 执行操作的用户ID
- **操作时间**: 操作发生的时间戳
- **操作详情**: 变更前后的权限策略信息

审计日志的记录应在权限策略变更的事务中完成，确保日志与数据变更的一致性。

**Section sources**
- [sys_auth_rule_v1_rule_add.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_add.go#L1-L14)
- [sys_auth_rule_v1_rule_update.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_update.go#L1-L14)
- [sys_auth_rule_v1_rule_delete.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_delete.go#L1-L14)

## 性能监控与告警配置

### 性能监控指标
建议监控以下关键性能指标：
- **权限查询响应时间**: 监控`RuleSearch`等查询接口的平均响应时间。
- **权限更新成功率**: 监控权限策略更新操作的成功率。
- **Casbin策略加载时间**: 监控Casbin引擎加载策略规则的时间。

### 异常告警配置
建议配置以下告警规则：
- 当权限查询平均响应时间超过500ms时告警。
- 当权限更新操作失败率超过1%时告警。
- 当Casbin策略加载时间超过1秒时告警。

这些监控和告警配置有助于及时发现权限系统中的性能瓶颈和异常情况。

**Section sources**
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go#L14-L34)
- [sys_auth_rule_v1_rule_search.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_search.go#L1-L14)