auth-module-architecture

name	auth-module-architecture
description	Auth 权限认证模块架构指南，涵盖 IAM 集成、RBAC 权限模型、资源权限校验、权限迁移、OAuth 认证。当用户开发权限功能、配置 IAM 资源、实现权限校验或处理认证流程时使用。

Auth 权限认证模块架构指南

模块定位: Auth 是 BK-CI 的权限认证核心模块，负责用户认证、权限校验、用户组管理、OAuth2 认证等功能，采用 RBAC（基于角色的访问控制）模型。

一、模块整体结构

1.1 子模块划分

src/backend/ci/core/auth/
├── api-auth/             # API 接口定义层
│   └── src/main/kotlin/com/tencent/devops/auth/
│       ├── api/
│       │   ├── callback/     # 回调接口（IAM、ITSM）
│       │   ├── login/        # 登录接口
│       │   ├── manager/      # 管理员接口
│       │   ├── migrate/      # 迁移接口
│       │   ├── oauth2/       # OAuth2 接口
│       │   ├── op/           # 运维接口
│       │   ├── open/         # 开放接口
│       │   ├── service/      # 服务间调用接口
│       │   ├── sync/         # 同步接口
│       │   └── user/         # 用户接口
│       ├── constant/         # 常量定义
│       └── pojo/             # 数据对象
│
├── biz-auth/             # 业务逻辑层
│   └── src/main/kotlin/com/tencent/devops/auth/
│       ├── aspect/           # AOP 切面
│       ├── common/           # 通用配置
│       ├── cron/             # 定时任务
│       ├── dao/              # 数据访问层（40+ 文件）
│       ├── entity/           # 实体定义
│       ├── filter/           # 过滤器
│       ├── provider/
│       │   ├── rbac/         # RBAC 实现（核心）
│       │   └── sample/       # 示例实现
│       ├── refresh/          # 刷新机制
│       ├── resources/        # API 实现
│       ├── service/          # 业务服务（30+ 文件）
│       ├── sharding/         # 分片策略
│       └── utils/            # 工具类
│
├── boot-auth/            # Spring Boot 启动模块
└── model-auth/           # 数据模型层（JOOQ 生成）

1.2 模块职责矩阵

模块	职责	核心类数量
api-auth	REST API 接口定义	50+
biz-auth	业务逻辑、RBAC 实现	150+
model-auth	JOOQ 数据模型	自动生成

二、核心概念

2.1 RBAC 权限模型

┌─────────────────────────────────────────────────────────────────────────┐
│                           BK-CI RBAC 权限模型                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌──────────┐     ┌──────────────┐     ┌──────────────┐                 │
│  │   用户    │────►│   用户组      │────►│   权限策略    │                 │
│  │  (User)   │     │ (Group)      │     │ (Policy)     │                 │
│  └──────────┘     └──────────────┘     └──────────────┘                 │
│       │                  │                     │                         │
│       │                  │                     ▼                         │
│       │                  │           ┌──────────────────┐               │
│       │                  │           │      操作        │               │
│       │                  │           │   (Action)       │               │
│       │                  │           │ create/view/edit │               │
│       │                  │           │ delete/execute   │               │
│       │                  │           └────────┬─────────┘               │
│       │                  │                    │                         │
│       ▼                  ▼                    ▼                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                        资源 (Resource)                           │   │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐            │   │
│  │  │ project │  │pipeline │  │ repo    │  │ env     │  ...       │   │
│  │  └─────────┘  └─────────┘  └─────────┘  └─────────┘            │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

2.2 核心实体关系

实体	说明	对应表
用户 (User)	系统用户	T_AUTH_USER_INFO
用户组 (Group)	权限组，关联权限策略	T_AUTH_RESOURCE_GROUP
组成员 (Member)	用户组成员关系	T_AUTH_RESOURCE_GROUP_MEMBER
资源 (Resource)	被管理的资源	T_AUTH_RESOURCE
操作 (Action)	资源上的操作	T_AUTH_ACTION
权限 (Permission)	组对资源的权限	T_AUTH_RESOURCE_GROUP_PERMISSION

2.3 默认用户组类型

enum class DefaultGroupType {
    MANAGER,      // 管理员组
    DEVELOPER,    // 开发人员组
    MAINTAINER,   // 运维人员组
    TESTER,       // 测试人员组
    PM,           // 产品人员组
    QC,           // 质量管理员组
    VIEWER        // 查看者组
}

三、分层架构图

┌─────────────────────────────────────────────────────────────────────────┐
│                              请求入口                                    │
│           HTTP Request / 服务间调用 / IAM 回调 / OAuth2                  │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         API 层 (api-auth)                                │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐    │
│  │UserAuth      │ │ServicePerm   │ │OpenProject   │ │Oauth2Service │    │
│  │ApplyResource │ │AuthResource  │ │AuthResource  │ │EndpointRes   │    │
│  │(用户权限申请) │ │(服务间鉴权)   │ │(开放项目权限) │ │(OAuth2认证)  │    │
│  └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                       业务层 (biz-auth)                                  │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      ResourceImpl 实现层                          │   │
│  │  ServicePermissionAuthResourceImpl | OpenProjectAuthResourceImpl │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                    │                                     │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      RBAC Provider 层 (核心)                      │   │
│  │  RbacPermissionService           - 权限校验核心服务                 │   │
│  │  RbacPermissionResourceGroupService - 用户组管理服务               │   │
│  │  RbacPermissionResourceMemberService - 组成员管理服务              │   │
│  │  RbacPermissionResourceService   - 资源管理服务                    │   │
│  │  PermissionGradeManagerService   - 分级管理员服务                  │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                    │                                     │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      通用 Service 层                              │   │
│  │  PermissionAuthorizationService  - 授权服务                       │   │
│  │  AuthDeptServiceImpl             - 部门服务                       │   │
│  │  ManagerUserService              - 管理员用户服务                  │   │
│  │  StrategyService                 - 策略服务                       │   │
│  │  AuthMonitorSpaceService         - 监控空间服务                    │   │
│  └──────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         DAO 层 (biz-auth/dao)                            │
│  AuthResourceGroupDao | AuthResourceGroupMemberDao | AuthResourceDao    │
│  AuthAuthorizationDao | AuthOauth2ClientDetailsDao | ...                │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                      数据层 (model-auth + MySQL)                         │
│  数据库：devops_ci_auth（共 30+ 张表）                                   │
└─────────────────────────────────────────────────────────────────────────┘

四、核心数据库表

4.1 用户组相关表

表名	说明	核心字段
T_AUTH_RESOURCE_GROUP	资源用户组	ID, PROJECT_CODE, RESOURCE_TYPE, RESOURCE_CODE, GROUP_CODE, GROUP_NAME, IAM_GROUP_ID
T_AUTH_RESOURCE_GROUP_MEMBER	组成员关系	ID, PROJECT_CODE, IAM_GROUP_ID, MEMBER_ID, MEMBER_TYPE, EXPIRED_TIME
T_AUTH_RESOURCE_GROUP_PERMISSION	组权限	ID, PROJECT_CODE, RESOURCE_TYPE, IAM_GROUP_ID, ACTION, RESOURCE_CODE
T_AUTH_RESOURCE_GROUP_CONFIG	组配置	ID, RESOURCE_TYPE, GROUP_CODE, GROUP_NAME, ACTIONS

4.2 资源相关表

表名	说明	核心字段
T_AUTH_RESOURCE	资源信息	ID, PROJECT_CODE, RESOURCE_TYPE, RESOURCE_CODE, RESOURCE_NAME, IAM_RESOURCE_CODE
T_AUTH_RESOURCE_TYPE	资源类型	ID, RESOURCE_TYPE, NAME, PARENT, SYSTEM
T_AUTH_ACTION	操作定义	ACTION, RESOURCE_TYPE, ACTION_NAME, ACTION_TYPE

4.3 授权相关表

表名	说明	核心字段
T_AUTH_AUTHORIZATION	资源授权	ID, PROJECT_CODE, RESOURCE_TYPE, RESOURCE_CODE, HANDOVER_FROM, HANDOVER_TO
T_AUTH_IAM_CALLBACK	IAM 回调	ID, GATEWAY, PATH, RESOURCE, SYSTEM

4.4 OAuth2 相关表

表名	说明
T_AUTH_OAUTH2_CLIENT_DETAILS	OAuth2 客户端信息
T_AUTH_OAUTH2_ACCESS_TOKEN	访问令牌
T_AUTH_OAUTH2_REFRESH_TOKEN	刷新令牌
T_AUTH_OAUTH2_CODE	授权码
T_AUTH_OAUTH2_SCOPE	授权范围

五、核心类速查

5.1 API 接口层

类名	路径前缀	职责
ServicePermissionAuthResource	/service/auth/permission	服务间权限校验
ServiceProjectAuthResource	/service/auth/project	服务间项目权限
ServiceResourceGroupResource	/service/auth/resource/group	用户组管理
ServiceResourceMemberResource	/service/auth/resource/member	组成员管理
UserAuthApplyResource	/user/auth/apply	用户权限申请
UserAuthAuthorizationResource	/user/auth/authorization	用户授权管理
OpenPermissionAuthResource	/open/auth/permission	开放权限接口
OpenProjectAuthResource	/open/auth/project	开放项目权限
Oauth2ServiceEndpointResource	/service/oauth2	OAuth2 服务端点

5.2 RBAC Provider 层（核心服务）

类名	文件大小	职责
RbacPermissionService	32KB	权限校验核心，对接 IAM SDK
RbacPermissionResourceGroupService	33KB	用户组 CRUD 管理
RbacPermissionResourceMemberService	29KB	组成员管理
RbacPermissionResourceService	21KB	资源注册与管理
RbacPermissionManageFacadeServiceImpl	117KB	权限管理门面（最大）
RbacPermissionResourceGroupPermissionService	39KB	组权限管理
RbacPermissionResourceGroupSyncService	37KB	组同步服务
PermissionGradeManagerService	27KB	分级管理员
RbacPermissionApplyService	30KB	权限申请服务

5.3 通用 Service 层

类名	职责
PermissionAuthorizationServiceImpl	资源授权（代持人）管理
AuthDeptServiceImpl	部门信息服务
ManagerUserService	超级管理员管理
StrategyService	权限策略管理
ThirdLoginService	第三方登录
AuthUserBlackListService	用户黑名单

5.4 DAO 层

类名	文件大小	职责
AuthResourceGroupMemberDao	34KB	组成员数据访问（最大）
AuthResourceGroupDao	19KB	用户组数据访问
AuthResourceDao	15KB	资源数据访问
AuthResourceGroupPermissionDao	11KB	组权限数据访问
AuthAuthorizationDao	10KB	授权数据访问

六、核心流程

6.1 权限校验流程

用户请求
    │
    ▼
ServicePermissionAuthResource.validateUserResourcePermission()
    │
    ▼
ServicePermissionAuthResourceImpl
    │
    ▼
RbacPermissionService.validateUserResourcePermission()
    │
    ├─► 检查是否超级管理员 (SuperManagerService)
    ├─► 检查项目成员缓存 (BkInternalPermissionCache)
    │
    ▼
AuthHelper.isAllowed()  ← IAM SDK
    │
    ├─► 构建 ActionDTO (操作)
    ├─► 构建 ResourceDTO (资源)
    └─► 调用 IAM 策略引擎

6.2 用户组创建流程

UserAuthApplyResource.createGroup()
    │
    ▼
RbacPermissionResourceGroupService.createGroup()
    │
    ├─► 校验组名长度 (5-32字符)
    ├─► 检查组名是否重复
    │
    ▼
iamV2ManagerService.createRoleGroup()  ← IAM SDK
    │
    ▼
authResourceGroupDao.create()  ← 保存到本地数据库
    │
    ▼
permissionResourceGroupPermissionService.grantGroupPermission()  ← 授予权限

6.3 OAuth2 认证流程

┌─────────────────────────────────────────────────────────────────┐
│                     OAuth2 授权码模式                            │
├─────────────────────────────────────────────────────────────────┤
│  1. 客户端请求授权                                               │
│     GET /oauth2/authorize?client_id=xxx&redirect_uri=xxx        │
│                          │                                       │
│                          ▼                                       │
│  2. 用户登录并授权                                               │
│     Oauth2DesktopEndpointResource.authorize()                   │
│                          │                                       │
│                          ▼                                       │
│  3. 返回授权码                                                   │
│     redirect_uri?code=xxx                                        │
│                          │                                       │
│                          ▼                                       │
│  4. 客户端用授权码换取 Token                                     │
│     POST /oauth2/token                                           │
│     Oauth2ServiceEndpointResource.getToken()                    │
│                          │                                       │
│                          ▼                                       │
│  5. 返回 Access Token + Refresh Token                           │
└─────────────────────────────────────────────────────────────────┘

七、与 IAM 集成

7.1 IAM SDK 依赖

Auth 模块深度集成腾讯蓝鲸 IAM（权限中心），核心依赖：

// IAM SDK 核心类
import com.tencent.bk.sdk.iam.config.IamConfiguration
import com.tencent.bk.sdk.iam.helper.AuthHelper
import com.tencent.bk.sdk.iam.service.PolicyService
import com.tencent.bk.sdk.iam.service.v2.V2ManagerService

7.2 IAM 回调接口

// 资源回调接口 - IAM 拉取资源信息
@Path("/open/auth/resource/callback")
interface OpenAuthResourceCallBackResource {
    fun getResource(...)      // 获取资源详情
    fun listResource(...)     // 列出资源
    fun searchResource(...)   // 搜索资源
}

7.3 资源类型定义

enum class AuthResourceType(val value: String) {
    PROJECT("project"),                    // 项目
    PIPELINE_DEFAULT("pipeline"),          // 流水线
    PIPELINE_GROUP("pipeline_group"),      // 流水线组
    PIPELINE_TEMPLATE("pipeline_template"),// 流水线模板
    CREDENTIAL("credential"),              // 凭证
    CERT("cert"),                          // 证书
    CGS("cgs"),                            // 代码扫描
    ENVIRONMENT_ENVIRONMENT("environment"),// 环境
    ENVIRONMENT_ENV_NODE("env_node"),      // 环境节点
    CODE_REPERTORY("repertory"),           // 代码库
    EXPERIENCE_TASK("experience_task"),    // 体验任务
    EXPERIENCE_GROUP("experience_group"),  // 体验组
    QUALITY_RULE("rule"),                  // 质量规则
    QUALITY_GROUP("quality_group"),        // 质量红线组
}

八、配置说明

8.1 RBAC 配置类

// 位置：biz-auth/provider/rbac/config/RbacAuthConfiguration.kt (37KB)
@Configuration
class RbacAuthConfiguration {
    // IAM 客户端配置
    // 权限服务 Bean 定义
    // 缓存配置
}

8.2 MQ 配置

// 位置：biz-auth/provider/rbac/config/RbacMQConfiguration.kt
// 定义权限相关的消息队列
// - 组创建事件
// - 组修改事件
// - ITSM 回调事件
// - 权限同步事件

九、开发规范

9.1 新增权限操作

1. 在 T_AUTH_ACTION 表添加操作定义
2. 在 AuthPermission 枚举中添加对应值
3. 在 IAM 系统注册操作
4. 更新 RbacAuthUtils.buildAction() 映射

9.2 新增资源类型

1. 在 AuthResourceType 枚举中添加类型
2. 在 T_AUTH_RESOURCE_TYPE 表添加记录
3. 实现 AuthResourceCallBackResource 回调接口
4. 在 IAM 系统注册资源类型

9.3 权限校验示例

// 服务间调用校验权限
client.get(ServicePermissionAuthResource::class).validateUserResourcePermission(
    userId = userId,
    token = token,
    action = AuthPermission.EXECUTE.value,
    projectCode = projectCode,
    resourceCode = AuthResourceType.PIPELINE_DEFAULT.value
)

// 使用 AuthPermissionApi
authPermissionApi.validateUserResourcePermission(
    user = userId,
    serviceCode = authServiceCode,
    resourceType = AuthResourceType.PIPELINE_DEFAULT,
    projectCode = projectCode,
    resourceCode = pipelineId,
    permission = AuthPermission.EXECUTE
)

十、常见问题

Q: 如何判断用户是否是项目成员？ A: 调用 RbacPermissionService.validateUserProjectPermission() 或检查用户是否在任意项目用户组中。

Q: 如何给用户授权？ A: 将用户添加到对应的用户组 RbacPermissionResourceMemberService.addGroupMember()。

Q: OAuth2 支持哪些授权模式？ A: 支持授权码模式（Authorization Code）和密码模式（Password）。

Q: 如何处理权限缓存？ A: 使用 BkInternalPermissionCache 进行缓存，通过 Redis 存储，支持主动刷新。

---

版本: 1.0.0 | 更新日期: 2025-12-10