前言
企业智能知识库系统是一个微服务架构下的多用户知识管理平台。
不同用户角色对文档、分类、标签、文件、系统管理等资源的访问边界截然不同——管理员可以管理系统用户和权限,编辑者可以创建和修改文档,审核员可以批准或驳回文档,而普通用户仅能查看和搜索。
这些都需要一套严谨且灵活的权限控制体系来保障。
本系统的权限体系基于 RBAC(Role-Based Access Control,基于角色的访问控制)模型,包含四层能力:
- 数据建模:用户 → 角色 → 权限的三层关系,支持多角色继承和直接权限分配
- 权限加载:登录时将角色和权限写入 JWT Claims,每次请求在 Filter 层从数据库刷新权限并注入 Spring Security 上下文
- 接口守卫:Controller 层通过
@PreAuthorize+ SpEL 表达式对每个接口进行细粒度权限校验 - 管理能力:提供角色创建/分配、权限树管理、用户角色指派等完整的后台管理 API
1. 一次请求的权限校验发生了什么
以 admin 用户创建文档为例,请求 POST /documents 经过以下权限校验链路:
用户前端发起 POST /documents,携带 Authorization: Bearer <JWT>
→ JwtAuthenticationFilter(kb-document 服务)
├── 从 Header 提取 JWT Token
├── jwtTokenUtil.getUserIdFromToken(token) → userId=1000000000000000001
├── 设置基础 ROLE_USER authority(兜底)
├── userServiceClient.getUserPermissions(userId, token)
│ └── Feign 调用 kb-user-auth: UserController.getUserPermissions(userId)
│ └── UserServiceImpl.getUserPermissions(userId)
│ ├── 查询 kb_user_permission(直接分配权限) → [...]
│ ├── 查询 kb_user_role + kb_role_permission(角色继承权限)
│ └── 判断角色是否包含 SUPER_ADMIN/ADMIN
│ → 是 → 注入全部 ADMIN_OPERATION_PERMISSIONS
│ → 否 → 仅返回数据库分配的权限
└── 所有权限码转换为 SimpleGrantedAuthority 列表
→ [ROLE_SUPER_ADMIN, document:list, document:create, ..., system:settings]
→ setSecurityContext(userId, token, authorities)
└── SecurityContextHolder → UsernamePasswordAuthenticationToken(authorities)
→ Controller 层到达 DocumentController.createDocument()
└── @PreAuthorize("hasAuthority(T(...DocumentPermissionConstants).DOCUMENT_CREATE)")
→ Spring Security 判断 authorities 中是否包含 "document:create"
→ admin 拥有 document:create → 校验通过 ✅
→ 执行 createDocument() 方法如果是一个仅拥有 ROLE_USER 的用户访问 POST /documents:
authorities = [ROLE_USER, document:list, document:create, document:edit, document:delete]
→ hasAuthority("document:create") → ✅ 通过
但如果同一个用户访问 DELETE /documents/{id}/categories/{categoryId}
→ @PreAuthorize("hasAuthority(T(...).DOCUMENT_CATEGORY)")
→ authorities 中无 "document:category" → ❌ 403 Forbidden2. 数据建模:三张表的关系
2.1 ER 关系图

核心要点:
- N:N:一个用户可拥有多个角色,一个角色可被多个用户持有(
kb_user_role) - N:N:一个角色可包含多个权限,一个权限可归属于多个角色(
kb_role_permission) - 直分旁路:用户可以不经过角色,直接获得权限(
kb_user_permission)
用户的最终权限 = 所有角色权限的并集 ∪ 直接分配的权限 ∪ 管理员硬编码权限
2.2 建表 SQL
-- 角色表
CREATE TABLE `kb_role` (
`id` BIGINT NOT NULL COMMENT '角色ID(雪花算法)',
`role_name` VARCHAR(50) NOT NULL COMMENT '角色名称',
`role_code` VARCHAR(50) NOT NULL COMMENT '角色编码(ROLE_前缀)',
`description` VARCHAR(200),
`sort` INT NOT NULL DEFAULT 0,
`status` TINYINT NOT NULL DEFAULT 1 COMMENT '0-禁用, 1-启用',
`remark` VARCHAR(500),
`created_at` DATETIME DEFAULT CURRENT_TIMESTAMP,
`updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
`create_by` BIGINT,
`update_by` BIGINT,
`deleted` TINYINT DEFAULT 0 COMMENT '逻辑删除',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_role_code` (`role_code`, `deleted`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- 权限表(支持树形层级)
CREATE TABLE `kb_permission` (
`id` BIGINT NOT NULL,
`parent_id` BIGINT NOT NULL DEFAULT 0 COMMENT '父权限ID(0=根节点)',
`permission_name` VARCHAR(50) NOT NULL,
`permission_code` VARCHAR(100) NOT NULL COMMENT '权限编码(module:action格式)',
`permission_type` TINYINT NOT NULL COMMENT '1-菜单, 2-按钮, 3-接口',
`menu_url` VARCHAR(200) COMMENT '菜单路径',
`api_url` VARCHAR(500) COMMENT 'API路径',
`method` VARCHAR(10) COMMENT 'HTTP方法',
`icon` VARCHAR(50) COMMENT '菜单图标',
`sort` INT COMMENT '排序',
`status` TINYINT COMMENT '0-禁用, 1-启用',
`created_at` DATETIME DEFAULT CURRENT_TIMESTAMP,
`updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
`deleted` TINYINT DEFAULT 0,
PRIMARY KEY (`id`),
KEY `idx_parent_id` (`parent_id`),
KEY `idx_permission_type` (`permission_type`),
KEY `idx_permission_code` (`permission_code`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- 用户-角色关联表
CREATE TABLE `kb_user_role` (
`id` BIGINT NOT NULL,
`user_id` BIGINT NOT NULL,
`role_id` BIGINT NOT NULL,
`created_at` DATETIME,
`create_by` BIGINT,
PRIMARY KEY (`id`),
UNIQUE KEY `uk_user_role` (`user_id`, `role_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- 角色-权限关联表
CREATE TABLE `kb_role_permission` (
`id` BIGINT NOT NULL,
`role_id` BIGINT NOT NULL,
`permission_id` BIGINT NOT NULL,
`created_at` DATETIME,
PRIMARY KEY (`id`),
UNIQUE KEY `uk_role_permission` (`role_id`, `permission_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- 用户-直接权限关联表
CREATE TABLE `kb_user_permission` (
`id` BIGINT NOT NULL,
`user_id` BIGINT NOT NULL,
`permission_id` BIGINT NOT NULL,
`created_at` DATETIME,
PRIMARY KEY (`id`),
UNIQUE KEY `uk_user_permission` (`user_id`, `permission_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;2.3 实体类映射
Role 实体(kb-user-auth/.../entity/Role.java):
@Data
@EqualsAndHashCode(callSuper = true)
@TableName("kb_role")
public class Role extends BaseEntity {
private String roleName; // 角色名称
private String roleCode; // 角色编码(ROLE_SUPER_ADMIN, ROLE_ADMIN, ...)
private String description; // 描述
private Integer sort; // 排序
private Integer status; // 0-禁用, 1-启用
private String remark; // 备注
}Permission 实体(kb-user-auth/.../entity/Permission.java):
@Data
@EqualsAndHashCode(callSuper = true)
@TableName("kb_permission")
public class Permission extends BaseEntity {
private Long parentId; // 父权限ID(树形结构)
private String permissionName; // 权限名称
private String permissionCode; // 权限编码(document:create, system:user)
private Integer permissionType; // 1-菜单, 2-按钮, 3-接口
private String menuUrl; // 菜单前端路径
private String apiUrl; // API接口路径
private String method; // HTTP方法
private String icon; // 菜单图标
private Integer sort; // 排序
private Integer status; // 状态
}UserRole 关联实体(kb-user-auth/.../entity/UserRole.java):
@Data
@TableName("kb_user_role")
public class UserRole {
@TableId(type = IdType.ASSIGN_ID)
private Long id;
private Long userId;
private Long roleId;
private LocalDateTime createdAt;
private Long createBy;
}2.4 设计考量
| 维度 | 选择 | 理由 |
|---|---|---|
| ID 策略 | Snowflake 雪花算法 | 微服务多实例部署不冲突,全局唯一 |
| 逻辑删除 | deleted = 1 | 保留历史数据,支持审计追溯和误删恢复 |
| 角色编码 | ROLE_ 前缀 | Spring Security hasRole() 自动添加前缀的约定 |
| 权限编码 | module:action 冒号分隔 | 命名空间隔离,易读易扩展,支持 document:category:query 三级编码 |
| 直分旁路 | kb_user_permission 表 | 允许临时为特定用户赋予额外权限,无需修改角色定义 |
| unique key | 联合 (uk + deleted) | 逻辑删除后可重新创建同名角色/权限 |
3. 六种角色与权限矩阵
3.1 角色定义
系统内置 6 种角色,由 SQL 初始化脚本创建:
| ID | role\_code | role\_name | 说明 |
|---|---|---|---|
| 2000000000000000001 | ROLE_SUPER_ADMIN | 超级管理员 | 拥有全部权限,跳过所有权限检查 |
| 2000000000000000002 | ROLE_ADMIN | 管理员 | 文档管理 + 系统管理全部权限 |
| 2000000000000000003 | ROLE_EDITOR | 编辑 | 文档 CRUD,不可删除他人文档 |
| 2000000000000000004 | ROLE_REVIEWER | 审核员 | 文档审核(审批、驳回、批量审核) |
| 2000000000000000005 | ROLE_USER | 普通用户 | 知识成员:文档 CRUD,不可审核和管理 |
| 2000000000000000006 | ROLE_GUEST | 访客 | 只读访问,仅可查看文档列表和详情 |
3.2 权限矩阵
以下展示核心模块权限在各角色间的分布:
| 权限域 | 权限编码 | SUPER\_ADMIN | ADMIN | EDITOR | REVIEWER | USER | GUEST |
|---|---|---|---|---|---|---|---|
| 文档查看 | document:list | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 文档创建 | document:create | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ |
| 文档编辑 | document:edit | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ |
| 文档删除 | document:delete | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ |
| 文档审核 | document:review | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
| 分类管理 | document:category | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| 分类查询 | document:category:query | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 标签管理 | document:tag | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| 版本管理 | document:version | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| 用户管理 | system:user | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| 角色管理 | system:role | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| 权限查看 | system:permission | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| 权限增删改 | system:permission:create/edit/delete | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| 团队管理 | system:team | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| 统计分析 | system:statistics | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| 系统设置 | system:settings | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
注意:ROLE\_SUPER\_ADMIN 和 ROLE\_ADMIN 的权限来自UserServiceImpl中的ADMIN_OPERATION_PERMISSIONS硬编码列表,不依赖kb_role_permission表中的数据库配置。这意味着即使数据库中的角色权限关联被误删,管理员依然拥有所有操作权限。
3.3 角色编码与前端映射
登录时,后端将 Spring Security 风格的 ROLE_ 编码转换为前端简码:
// UserServiceImpl.java 第 810 行
private String mapRoleCodeToFrontendRole(String roleCode) {
return switch (roleCode) {
case "ROLE_SUPER_ADMIN" -> "SUPER_ADMIN";
case "ROLE_ADMIN" -> "KNOWLEDGE_ADMIN";
case "ROLE_EDITOR" -> "EDITOR";
case "ROLE_REVIEWER" -> "REVIEWER";
case "ROLE_USER", "ROLE_GUEST" -> "VIEWER";
default -> roleCode.startsWith("ROLE_") ? roleCode.substring(5) : roleCode;
};
}| 后端编码 | 前端编码 | 说明 |
|---|---|---|
ROLE_SUPER_ADMIN | SUPER_ADMIN | 超级管理员 |
ROLE_ADMIN | KNOWLEDGE_ADMIN | 知识库管理员 |
ROLE_EDITOR | EDITOR | 编辑者 |
ROLE_REVIEWER | REVIEWER | 审核员 |
ROLE_USER | VIEWER | 普通用户(知识成员) |
ROLE_GUEST | VIEWER | 访客用户 |
4. 权限树:菜单、按钮、接口三级分类
4.1 权限类型说明
kb_permission 表中的 permission_type 字段区分三种权限层级:
| 类型值 | 类型名 | 含义 | 示例 |
|---|---|---|---|
1 | menu | 菜单权限,控制前端侧边栏可见性 | document、file、system |
2 | button | 按钮权限,控制页面内操作按钮 | document:create、system:permission:create |
3 | api | 接口权限,控制后端 API 调用 | api:permission:list、document:category:query |
4.2 完整权限树
├── dashboard # 首页 (menu)
├── document # 文档中心 (menu)
│ ├── document:list # 文档列表 (menu)
│ ├── document:create # 创建文档 (button)
│ ├── document:edit # 编辑文档 (button)
│ ├── document:delete # 删除文档 (button)
│ ├── document:review # 文档审核 (button)
│ ├── document:category # 分类管理 (menu)
│ │ └── document:category:query # 分类查询 (api)
│ ├── document:tag # 标签管理 (menu)
│ └── document:version # 版本管理 (api)
├── file # 文件管理 (menu)
│ ├── file:list # 文件列表 (menu)
│ ├── file:upload # 上传文件 (button)
│ └── file:delete # 删除文件 (button)
├── graph # 知识图谱 (menu)
├── search # 搜索 (menu)
├── ai # AI助手 (menu)
├── ai-writing # AI写作 (menu)
├── notification # 通知中心 (menu)
├── profile # 个人中心 (menu)
└── system # 系统管理 (menu)
├── system:user # 用户管理 (menu)
├── system:role # 角色管理 (menu)
├── system:permission # 权限管理 (menu)
│ ├── system:permission:create # 新增权限 (button)
│ ├── system:permission:edit # 编辑权限 (button)
│ ├── system:permission:delete # 删除权限 (button)
│ ├── api:permission:list # 查询权限列表接口 (api)
│ └── api:permission:maintain # 维护权限接口 (api)
├── system:team # 团队管理 (menu)
├── system:statistics # 统计分析 (menu)
├── system:review # 审核管理 (menu)
├── system:settings # 系统设置 (menu)
├── system:config # 系统配置 (menu)
├── system:dictionary # 字典管理 (menu)
├── system:operation-log # 操作日志 (menu)
└── system:notification-template # 通知模板 (menu)4.3 创建权限——含父子关系校验
// PermissionServiceImpl.java 第 41 行
@Transactional(rollbackFor = Exception.class)
public Long createPermission(PermissionDTO permissionDTO) {
// 1. 检查权限编码是否已存在
if (StringUtils.hasText(permissionDTO.getCode())) {
Permission existPermission = permissionMapper.selectOne(
new LambdaQueryWrapper<Permission>()
.eq(Permission::getPermissionCode, permissionDTO.getCode())
);
if (existPermission != null) {
throw new BusinessException("权限编码已存在");
}
}
// 2. 检查父权限是否存在
if (permissionDTO.getParentId() != null && permissionDTO.getParentId() > 0) {
Permission parentPermission = permissionMapper.selectById(permissionDTO.getParentId());
if (parentPermission == null) {
throw new BusinessException("父权限不存在");
}
}
// 3. 构建权限实体并保存
Permission permission = new Permission();
permission.setId(SnowflakeIdGenerator.getInstance().nextId());
permission.setParentId(permissionDTO.getParentId() != null ? permissionDTO.getParentId() : 0L);
permission.setPermissionName(permissionDTO.getName());
permission.setPermissionCode(permissionDTO.getCode());
permission.setPermissionType(getPermissionTypeValue(permissionDTO.getType()));
// ... 其他字段
permissionMapper.insert(permission);
return permission.getId();
}权限编码采用 module:action 冒号分隔层级命名模式——document、system 为模块一级命名空间,create、edit、delete 为操作二级动作,system:permission:create 为三级细粒度控制。这种命名方式天然支持 hasAuthority 的精确匹配。
4.4 构建权限树
PermissionServiceImpl.getPermissionTree() 查询全量权限并递归构建树形结构,供前端渲染权限管理页面:
// PermissionServiceImpl.java 第 220 行
public List<PermissionVO> getPermissionTree() {
// 1. 查询所有权限,按 sort 升序
List<Permission> allPermissions = permissionMapper.selectList(
new LambdaQueryWrapper<Permission>().orderByAsc(Permission::getSort)
);
// 2. 转换为 VO
List<PermissionVO> permissionVOs = allPermissions.stream()
.map(this::convertToVO).collect(Collectors.toList());
// 3. 递归构建树(parentId == 0 为根节点)
return buildPermissionTree(permissionVOs, 0L);
}
private List<PermissionVO> buildPermissionTree(
List<PermissionVO> permissions, Long parentId) {
List<PermissionVO> tree = new ArrayList<>();
for (PermissionVO permission : permissions) {
if (parentId.equals(permission.getParentId())) {
permission.setChildren(buildPermissionTree(permissions, permission.getId()));
tree.add(permission);
}
}
return tree;
}5. 权限加载:从数据库到 Spring Security
5.1 权限加载流程

5.2 JwtAuthenticationFilter:权限加载的核心
kb-user-auth 服务中的权限加载(kb-user-auth/.../filter/JwtAuthenticationFilter.java 第 238 行):
private List<SimpleGrantedAuthority> getUserAuthorities(UserInfo userInfo) {
List<SimpleGrantedAuthority> authorities = new ArrayList<>();
try {
// 1. 从数据库加载用户角色编码
List<String> roleCodes = roleMapper.selectRoleCodesByUserId(userInfo.getUserId());
if (roleCodes != null) {
for (String roleCode : roleCodes) {
// 确保角色以 ROLE_ 前缀(Spring Security 约定)
String roleWithPrefix = roleCode.startsWith("ROLE_") ? roleCode : "ROLE_" + roleCode;
authorities.add(new SimpleGrantedAuthority(roleWithPrefix));
}
}
// 2. 从数据库加载用户权限编码(直接权限 + 角色继承权限)
List<String> permissions = userService.getUserPermissions(userInfo.getUserId());
if (permissions != null) {
for (String permission : permissions) {
authorities.add(new SimpleGrantedAuthority(permission));
}
}
} catch (Exception e) {
log.error("加载用户权限失败:userId={}", userInfo.getUserId(), e);
}
// 3. 兜底:确保至少有一个角色
if (authorities.isEmpty()) {
authorities.add(new SimpleGrantedAuthority("ROLE_USER"));
}
return authorities;
}权限加载完成后,构建 UsernamePasswordAuthenticationToken 并注入 Spring Security 上下文:
UsernamePasswordAuthenticationToken authentication =
new UsernamePasswordAuthenticationToken(
userInfo.getUserId(), // principal:用户ID
token, // credentials:JWT Token
authorities // authorities:角色 + 权限列表
);
// 三个参数的构造函数自动标记 authenticated = true
SecurityContextHolder.getContext().setAuthentication(authentication);5.3 管理员权限硬编码注入
管理员权限不依赖 kb_role_permission 表中的配置,而是在代码层面硬编码保证完整性:
// UserServiceImpl.java 第 728 行
private static final List<String> ADMIN_OPERATION_PERMISSIONS = List.of(
"document:list", "document:create", "document:edit", "document:delete",
"document:review", "document:category", "document:category:query",
"document:tag", "document:version",
"system:user", "system:role", "system:permission",
"system:permission:create", "system:permission:edit", "system:permission:delete",
"system:team", "system:statistics", "system:settings"
);
private static final List<String> ADMIN_ROLES = List.of("ROLE_SUPER_ADMIN", "ROLE_ADMIN");
public List<String> getUserPermissions(Long userId) {
// ... 查询直接权限 + 角色继承权限 ...
// 查询用户角色编码
List<String> userRoles = roleMapper.selectRoleCodesByUserId(userId);
// 管理员角色自动注入全部操作权限(不依赖数据库配置)
boolean isAdmin = userRoles.stream().anyMatch(ADMIN_ROLES::contains);
if (isAdmin) {
for (String perm : ADMIN_OPERATION_PERMISSIONS) {
if (!allPermissions.contains(perm)) {
allPermissions.add(perm);
}
}
}
return allPermissions;
}这是一个关键的安全设计——即使管理员误操作将自己的角色权限关联清空,系统仍然保证管理员能够正常工作。
5.4 权限查询 SQL
getUserPermissions() 通过 JdbcTemplate 执行两条 SQL,合并结果:
// 1. 查询用户直接分配的权限(kb_user_permission 表)
List<String> directPermissions = jdbcTemplate.queryForList(
"SELECT p.permission_code FROM kb_user_permission up " +
"JOIN kb_permission p ON up.permission_id = p.id " +
"WHERE up.user_id = ? AND p.status = 1",
String.class, userId
);
// 2. 查询用户通过角色获得的权限(kb_user_role + kb_role_permission 双表 JOIN)
List<String> rolePermissions = jdbcTemplate.queryForList(
"SELECT DISTINCT p.permission_code FROM kb_user_role ur " +
"JOIN kb_role_permission rp ON ur.role_id = rp.role_id " +
"JOIN kb_permission p ON rp.permission_id = p.id " +
"WHERE ur.user_id = ? AND p.status = 1",
String.class, userId
);
// 3. 合并去重(LinkedHashSet 保证顺序)
Set<String> allPermissions = new LinkedHashSet<>(directPermissions);
allPermissions.addAll(rolePermissions);5.5 RoleMapper XML 中的关键 SQL
RoleMapper.xml 包含 14 条自定义 SQL,以下为核心查询:
<!-- 根据用户ID查询角色编码列表 -->
<select id="selectRoleCodesByUserId" resultType="java.lang.String">
SELECT r.role_code
FROM kb_role r
INNER JOIN kb_user_role ur ON r.id = ur.role_id
WHERE ur.user_id = #{userId} AND r.deleted = 0
</select>
<!-- 根据用户ID查询权限ID列表(通过角色继承) -->
<select id="selectPermissionIdsByUserId" resultType="java.lang.Long">
SELECT DISTINCT rp.permission_id
FROM kb_role_permission rp
INNER JOIN kb_user_role ur ON rp.role_id = ur.role_id
WHERE ur.user_id = #{userId}
</select>
<!-- 根据角色编码查询用户ID列表 -->
<select id="selectUserIdsByRoleCode" resultType="java.lang.Long">
SELECT DISTINCT ur.user_id
FROM kb_user_role ur
INNER JOIN kb_role r ON ur.role_id = r.id
WHERE r.role_code = #{roleCode} AND r.deleted = 0
</select>6. 接口守卫:@PreAuthorize + SpEL 表达式
6.1 文档服务权限常量
kb-document 模块将权限编码集中维护在常量类中,避免字符串硬编码散布各处:
// kb-document/.../constants/DocumentPermissionConstants.java
public final class DocumentPermissionConstants {
public static final String DOCUMENT_LIST = "document:list";
public static final String DOCUMENT_CREATE = "document:create";
public static final String DOCUMENT_EDIT = "document:edit";
public static final String DOCUMENT_DELETE = "document:delete";
public static final String DOCUMENT_REVIEW = "document:review";
public static final String DOCUMENT_CATEGORY = "document:category";
public static final String DOCUMENT_CATEGORY_QUERY = "document:category:query";
public static final String DOCUMENT_TAG = "document:tag";
public static final String DOCUMENT_VERSION = "document:version";
}6.2 DocumentController 中的权限注解
// DocumentController.java
// 创建文档:需要 document:create 权限
@PostMapping
@PreAuthorize("hasAuthority(T(com.knowledge.base.document.constants.DocumentPermissionConstants).DOCUMENT_CREATE)")
public Result<Long> createDocument(@Valid @RequestBody DocumentDTO documentDTO) { ... }
// 更新文档:需要 document:edit 权限
@PutMapping("/{documentId}")
@PreAuthorize("hasAuthority(T(com.knowledge.base.document.constants.DocumentPermissionConstants).DOCUMENT_EDIT)")
public Result<Boolean> updateDocument(@PathVariable Long documentId, ...) { ... }
// 删除文档:需要 document:delete 权限
@DeleteMapping("/{documentId}")
@PreAuthorize("hasAuthority(T(com.knowledge.base.document.constants.DocumentPermissionConstants).DOCUMENT_DELETE)")
public Result<Boolean> deleteDocument(@PathVariable Long documentId) { ... }
// 查看文档:需要 document:list 权限
@GetMapping("/{documentId}")
@PreAuthorize("hasAuthority(T(com.knowledge.base.document.constants.DocumentPermissionConstants).DOCUMENT_LIST)")
public Result<DocumentVO> getDocumentById(@PathVariable Long documentId) { ... }
// 自动保存:需要 document:create 或 document:edit 权限(二选一)
@PostMapping("/autosave")
@PreAuthorize("hasAnyAuthority(T(...DocumentPermissionConstants).DOCUMENT_CREATE, " +
"T(...DocumentPermissionConstants).DOCUMENT_EDIT)")
public Result<Long> autoSaveDocument(@Valid @RequestBody AutoSaveDTO autoSaveDTO) { ... }6.3 其他 Controller 的权限注解
| Controller | 接口 | 所需权限 |
|---|---|---|
CategoryController | 创建/更新/删除/移动分类 | document:category |
TagController | 创建/更新/删除标签 | document:tag |
DocumentReviewController | 提交审核、获取审核任务 | document:edit 或 document:review |
DocumentReviewController | 审批/驳回、批量审核、统计 | document:review |
DocumentVersionController | 版本列表、回滚、比较 | document:version |
FileUploadController | 上传文件 | document:create 或 document:edit |
FileManagementController | 文件列表、详情、搜索 | document:list |
FileManagementController | 上传、重命名、删除 | document:create 或 document:edit |
6.4 SpEL 表达式的执行原理
@PreAuthorize("hasAuthority(T(...).DOCUMENT_CREATE)") 的执行流程:
- Spring Security 拦截器(
MethodSecurityInterceptor)在方法执行前读取注解 - SpEL 表达式引擎解析
T(...)→ 加载DocumentPermissionConstants类 → 获取静态字段DOCUMENT_CREATE的值 → 得到字符串"document:create" hasAuthority("document:create")调用SecurityContextHolder.getContext().getAuthentication().getAuthorities()遍历所有SimpleGrantedAuthority,检查是否存在authority.getAuthority().equals("document:create")- 找到 → 通过,未找到 → 抛出
AccessDeniedException→ 返回 HTTP 403
**为什么使用 **T(...)** 而不是直接写字符串**:保证权限编码与常量类保持一致。如果将来 document:create 改为 doc:write,只需修改常量类,IDE 会提示所有引用处。
6.5 SecurityConfig 启用方法级安全
// kb-document/.../config/SecurityConfig.java
@Configuration
@EnableWebSecurity
@EnableMethodSecurity // 核心:启用 @PreAuthorize 注解支持
public class SecurityConfig {
// 注入 JwtAuthenticationFilter,配置无状态会话
// 自定义 401/403 异常处理,返回 JSON 格式的错误响应
}7. 跨服务权限传递
7.1 kb-document 服务的权限加载
kb-document 独立运行,不直接访问 kb_user 数据库。它通过 **Feign 远程调用** kb-user-auth 获取用户权限:
// kb-document/.../filter/JwtAuthenticationFilter.java 第 183 行
private List<SimpleGrantedAuthority> getUserAuthorities(Long userId, String token) {
List<SimpleGrantedAuthority> authorities = new ArrayList<>();
// 默认兜底权限:确保至少拥有 ROLE_USER
authorities.add(new SimpleGrantedAuthority("ROLE_USER"));
// 通过 Feign 远程调用 kb-user-auth 获取权限列表
List<String> permissions = userServiceClient.getUserPermissions(userId, token);
if (permissions.isEmpty()) {
// 降级:kb-user-auth 服务不可达,仅授予基础读权限
log.warn("无法从用户服务获取权限,使用降级策略:仅授予基础读权限, userId={}", userId);
permissions = FALLBACK_BASIC_PERMISSIONS;
// FALLBACK_BASIC_PERMISSIONS = ["document:list", "document:category:query"]
} else if (!permissions.contains("document:list")) {
// 补充基础读权限(数据库权限映射不完整的保护)
log.warn("用户权限中缺少 document:list,自动补充基础权限, userId={}", userId);
List<String> augmented = new ArrayList<>(permissions);
augmented.add("document:list");
augmented.add("document:category:query");
permissions = augmented;
}
for (String permission : permissions) {
authorities.add(new SimpleGrantedAuthority(permission));
}
return authorities;
}7.2 权限加载对比

| 对比维度 | kb-user-auth | kb-document |
|---|---|---|
| 权限来源 | 直接查询 kb_user 数据库 | 通过 Feign 远程调用 kb-user-auth |
| 角色加载 | roleMapper.selectRoleCodesByUserId() | 不加载角色(仅加载权限码) |
| 管理员注入 | ✅ 硬编码注入 | ❌ 由 kb-user-auth 返回的权限已包含 |
| 降级策略 | 权限为空 → ROLE_USER | Feign 失败 → [document:list, document:category:query] |
| 兜底保护 | 角色为空 → ROLE_USER | 缺少 document:list → 自动补充 |
8. 角色与权限管理 API
8.1 角色管理 API
RoleController(kb-user-auth 服务)提供完整的角色 CRUD 和权限分配接口:
| 方法 | 路径 | 功能 | 说明 |
|---|---|---|---|
POST | /auth/roles | 创建角色 | 校验名称和编码唯一性 |
PUT | /auth/roles | 更新角色 | 校验名称/编码不被其他角色占用 |
DELETE | /auth/roles/{id} | 删除角色 | 校验角色未被分配给用户,清理关联数据 |
GET | /auth/roles/{id} | 获取角色详情 | 携带 permissions 和 userCount |
GET | /auth/roles/page | 分页查询角色 | 支持关键词搜索 |
GET | /auth/roles/all | 获取所有启用角色 | 含权限列表 |
POST | /auth/roles/{id}/permissions | 为角色分配权限 | 先清空再批量插入 |
分配权限实现(RoleServiceImpl.java 第 214 行):
@Transactional(rollbackFor = Exception.class)
public Boolean assignPermissions(Long roleId, List<Long> permissionIds) {
// 1. 检查角色存在
Role role = roleMapper.selectById(roleId);
if (role == null) throw new BusinessException("角色不存在");
// 2. 清空原有权限关联
jdbcTemplate.update("DELETE FROM kb_role_permission WHERE role_id = ?", roleId);
// 3. 批量插入新权限关联
if (permissionIds != null && !permissionIds.isEmpty()) {
String sql = "INSERT INTO kb_role_permission (id, role_id, permission_id, created_at) " +
"VALUES (?, ?, ?, NOW())";
for (Long permissionId : permissionIds) {
jdbcTemplate.update(sql, SnowflakeIdGenerator.getInstance().nextId(),
roleId, permissionId);
}
}
return true;
}8.2 用户-角色和用户-权限分配 API
UserController(kb-user-auth 服务)提供用户维度的角色和权限分配:
| 方法 | 路径 | 功能 |
|---|---|---|
POST | /auth/users/{userId}/roles | 为用户分配角色 |
POST | /auth/users/{userId}/permissions | 为用户分配直接权限 |
GET | /auth/users/{userId}/permissions | 查询用户的最终权限列表 |
用户角色分配(UserServiceImpl.java 第 650 行):
@Transactional(rollbackFor = Exception.class)
public Boolean assignRoles(Long userId, List<Long> roleIds) {
// 1. 删除现有角色关联
jdbcTemplate.update("DELETE FROM kb_user_role WHERE user_id = ?", userId);
// 2. 逐个插入新的角色关联
if (roleIds != null && !roleIds.isEmpty()) {
String sql = "INSERT INTO kb_user_role (id, user_id, role_id, created_at) " +
"VALUES (?, ?, ?, NOW())";
for (Long roleId : roleIds) {
Role role = roleMapper.selectById(roleId);
if (role == null) throw new BusinessException("角色不存在: " + roleId);
jdbcTemplate.update(sql, SnowflakeIdGenerator.getInstance().nextId(),
userId, roleId);
}
}
return true;
}8.3 权限管理 API
PermissionController(kb-user-auth 服务)提供权限树的 CRUD 和维护:
| 方法 | 路径 | 功能 |
|---|---|---|
POST | /auth/permissions | 创建权限(菜单/按钮/接口) |
PUT | /auth/permissions | 更新权限 |
DELETE | /auth/permissions/{id} | 删除权限(校验无子权限) |
GET | /auth/permissions/{id} | 获取权限详情 |
GET | /auth/permissions/tree | 获取权限树 |
GET | /auth/permissions/page | 分页查询权限 |
GET | /auth/permissions/all | 获取所有启用权限 |
9. 权限治理:四份 SQL 迁移脚本
系统在演化过程中产生了四份权限治理 SQL 脚本,记录了权限模型的演进历程:
9.1 脚本一览
| 文件 | 用途 | 说明 |
|---|---|---|
02_init_data.sql | 初始化种子数据 | 创建 6 角色、40+ 权限、10 用户、角色分配 |
12_init_permission_resource_data.sql | 补充菜单下级资源 | 为文档中心、系统管理补充子权限定义 |
13_init_menu_permission_data.sql | 补充一级菜单和子菜单 | 添加文件管理、AI写作一级菜单及系统管理子菜单 |
17_cleanup_role_user_permissions.sql | 清理 ROLE\_USER 越权 | 移除普通用户的审核/分类管理/系统管理权限 |
18_grant_role_user_document_permissions.sql | 授予 ROLE\_USER 文档权限 | 为知识成员添加 document:list/create/edit/delete |
9.2 种子数据:超级管理员获得全部权限
-- 02_init_data.sql:超级管理员获得全部权限
INSERT INTO `kb_role_permission` (`id`, `role_id`, `permission_id`)
SELECT 5000000000000000001 + (@row_num := @row_num + 1),
2000000000000000001, -- ROLE_SUPER_ADMIN
p.`id`
FROM `kb_permission` p, (SELECT @row_num := 0) r;9.3 清理 ROLE\_USER 越权权限
在系统演进中,ROLE\_USER 曾被授予过多的管理权限。17_cleanup_role_user_permissions.sql 进行了清理:
-- 移除文件管理权限
DELETE rp FROM `kb_role_permission` rp
INNER JOIN `kb_permission` p ON rp.`permission_id` = p.`id`
WHERE rp.`role_id` = 2000000000000000005 -- ROLE_USER
AND p.`permission_code` IN ('file', 'file:list', 'file:upload', 'file:delete');
-- 移除系统管理权限
DELETE rp FROM `kb_role_permission` rp
INNER JOIN `kb_permission` p ON rp.`permission_id` = p.`id`
WHERE rp.`role_id` = 2000000000000000005
AND p.`permission_code` IN (
'system', 'system:user', 'system:role', 'system:permission',
'system:permission:create', 'system:permission:edit', 'system:permission:delete',
'system:team', 'system:statistics', 'system:settings',
'system:config', 'system:dictionary', 'system:operation-log', 'system:notification-template',
'api:permission:list', 'api:permission:maintain'
);
-- 移除管理类文档权限(保留 CRUD 操作权限)
DELETE rp FROM `kb_role_permission` rp
INNER JOIN `kb_permission` p ON rp.`permission_id` = p.`id`
WHERE rp.`role_id` = 2000000000000000005
AND p.`permission_code` IN (
'document:review', 'document:category', 'document:category:query',
'document:tag', 'document:version'
);9.4 授予 ROLE\_USER 文档 CRUD 权限
18_grant_role_user_document_permissions.sql 为 ROLE\_USER 添加核心的文档增删改查权限:
-- 为 ROLE_USER 添加文档 CRUD 权限(如果尚未分配)
INSERT INTO `kb_role_permission` (`id`, `role_id`, `permission_id`)
SELECT COALESCE((SELECT MAX(`id`) FROM `kb_role_permission` rp2), 5000000000000000000)
+ (@row_num := @row_num + 1),
2000000000000000005, -- ROLE_USER
p.`id`
FROM `kb_permission` p, (SELECT @row_num := 0) r
WHERE p.`permission_code` IN (
'document:list', 'document:create', 'document:edit', 'document:delete'
)
AND NOT EXISTS (
SELECT 1 FROM `kb_role_permission` rp
WHERE rp.`role_id` = 2000000000000000005 AND rp.`permission_id` = p.`id`
);脚本使用 NOT EXISTS 保证幂等——重复执行不会重复插入。
总结
| 维度 | 评价 |
|---|---|
| 模型清晰 | 用户→角色→权限 → 三层 RBAC 标准模型,加上直分旁路(kb_user_permission),既规范又灵活 |
| 命名规范 | module:action 冒号分隔的权限编码体系,层次分明,document:create、system:permission:create 等命名自解释 |
| 常量管理 | DocumentPermissionConstants 集中维护权限码,避免字符串硬编码散落 |
| 硬编码兜底 | 管理员权限不依赖数据库配置,即使误操作清空 kb_role_permission 也不会导致管理员失权 |
| 降级策略 | kb-document 在 kb-user-auth 不可达时自动降级为基础读权限(document:list, document:category:query),确保服务可用 |
| 权限治理 | 四份 SQL 迁移脚本完整记录权限模型的演化过程,可审计可回滚 |
| 树形权限 | 支持菜单/按钮/接口三级权限分类和父子层级,可渲染为前端权限管理树 |
| 跨服务兼容 | kb-document 通过 Feign 远程获取权限 + X-User-Id Header 降级,不依赖共享数据库 |
技术栈总结
鉴权架构:JWT(HMAC-SHA256)无状态认证 + RBAC 权限模型
安全框架:Spring Security 6.x(@EnableMethodSecurity + @PreAuthorize)
数据层:MySQL 5 张 RBAC 表(kb_role、kb_permission、kb_user_role、kb_role_permission、kb_user_permission)
ORM:MyBatis-Plus 3.x(实体映射)+ 原生 JdbcTemplate(关联查询)
跨服务:Feign 远程调用 + X-User-Id Header 降级
ID 策略:Snowflake 雪花算法(全局唯一)