前言

企业智能知识库系统是一个微服务架构下的多用户知识管理平台。

不同用户角色对文档、分类、标签、文件、系统管理等资源的访问边界截然不同——管理员可以管理系统用户和权限,编辑者可以创建和修改文档,审核员可以批准或驳回文档,而普通用户仅能查看和搜索。

这些都需要一套严谨且灵活的权限控制体系来保障。

本系统的权限体系基于 RBAC(Role-Based Access Control,基于角色的访问控制)模型,包含四层能力:

  1. 数据建模:用户 → 角色 → 权限的三层关系,支持多角色继承和直接权限分配
  2. 权限加载:登录时将角色和权限写入 JWT Claims,每次请求在 Filter 层从数据库刷新权限并注入 Spring Security 上下文
  3. 接口守卫:Controller 层通过 @PreAuthorize + SpEL 表达式对每个接口进行细粒度权限校验
  4. 管理能力:提供角色创建/分配、权限树管理、用户角色指派等完整的后台管理 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 Forbidden

2. 数据建模:三张表的关系

2.1 ER 关系图

图片.png

核心要点:

  • 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 初始化脚本创建:

IDrole\_coderole\_name说明
2000000000000000001ROLE_SUPER_ADMIN超级管理员拥有全部权限,跳过所有权限检查
2000000000000000002ROLE_ADMIN管理员文档管理 + 系统管理全部权限
2000000000000000003ROLE_EDITOR编辑文档 CRUD,不可删除他人文档
2000000000000000004ROLE_REVIEWER审核员文档审核(审批、驳回、批量审核)
2000000000000000005ROLE_USER普通用户知识成员:文档 CRUD,不可审核和管理
2000000000000000006ROLE_GUEST访客只读访问,仅可查看文档列表和详情

3.2 权限矩阵

以下展示核心模块权限在各角色间的分布:

权限域权限编码SUPER\_ADMINADMINEDITORREVIEWERUSERGUEST
文档查看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_ADMINSUPER_ADMIN超级管理员
ROLE_ADMINKNOWLEDGE_ADMIN知识库管理员
ROLE_EDITOREDITOR编辑者
ROLE_REVIEWERREVIEWER审核员
ROLE_USERVIEWER普通用户(知识成员)
ROLE_GUESTVIEWER访客用户

4. 权限树:菜单、按钮、接口三级分类

4.1 权限类型说明

kb_permission 表中的 permission_type 字段区分三种权限层级:

类型值类型名含义示例
1menu菜单权限,控制前端侧边栏可见性document、file、system
2button按钮权限,控制页面内操作按钮document:create、system:permission:create
3api接口权限,控制后端 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 权限加载流程

图片.png

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)") 的执行流程:

  1. Spring Security 拦截器(MethodSecurityInterceptor)在方法执行前读取注解
  2. SpEL 表达式引擎解析 T(...) → 加载 DocumentPermissionConstants 类 → 获取静态字段 DOCUMENT_CREATE 的值 → 得到字符串 "document:create"
  3. hasAuthority("document:create") 调用 SecurityContextHolder.getContext().getAuthentication().getAuthorities() 遍历所有 SimpleGrantedAuthority,检查是否存在 authority.getAuthority().equals("document:create")
  4. 找到 → 通过,未找到 → 抛出 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 权限加载对比

图片.png

对比维度kb-user-authkb-document
权限来源直接查询 kb_user 数据库通过 Feign 远程调用 kb-user-auth
角色加载roleMapper.selectRoleCodesByUserId()不加载角色(仅加载权限码)
管理员注入✅ 硬编码注入❌ 由 kb-user-auth 返回的权限已包含
降级策略权限为空 → ROLE_USERFeign 失败 → [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 雪花算法(全局唯一)
最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏