auth-module-architecture

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

الانتقال إلى التثبيت

المستودع: aibot88/sec_skill_store
آخر نشاط في المصدر: ٢٧ مايو ٢٠٢٦ في ٠٣:٤٧
لغة SKILL.md المكتشفة: الصينية
النجوم: ٣
التفرعات: ٠

خيارات التثبيت

يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.

التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.

يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.

npx skills add https://github.com/aibot88/sec_skill_store --skill auth-module-architecture

يبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.

تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.

مراجعة ملفات المصدر

اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.

مستكشف الملفات

2 ملفات

SKILL.md

تعليمات المصدر · معاينة للقراءة فقط

العودة إلى البحث العودة إلى التثبيت

مستكشف الملفات

2 ملفات

SKILL.md

تعليمات المصدر · معاينة للقراءة فقط

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 新增权限操作

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

9.2 新增资源类型

在 AuthResourceType 枚举中添加类型
在 T_AUTH_RESOURCE_TYPE 表添加记录
实现 AuthResourceCallBackResource 回调接口
在 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

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 新增权限操作

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

9.2 新增资源类型

在 AuthResourceType 枚举中添加类型
在 T_AUTH_RESOURCE_TYPE 表添加记录
实现 AuthResourceCallBackResource 回调接口
在 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

auth-module-architecture

معلومات المصدر

خيارات التثبيت

مراجعة ملفات المصدر

المزيد من هذا المستودع

المزيد من هذا المستودع

Auth 权限认证模块架构指南

一、模块整体结构

1.1 子模块划分

1.2 模块职责矩阵

二、核心概念

2.1 RBAC 权限模型

2.2 核心实体关系

2.3 默认用户组类型

三、分层架构图

四、核心数据库表

4.1 用户组相关表

4.2 资源相关表

4.3 授权相关表

4.4 OAuth2 相关表

五、核心类速查

5.1 API 接口层

5.2 RBAC Provider 层（核心服务）

5.3 通用 Service 层

5.4 DAO 层

六、核心流程

6.1 权限校验流程

6.2 用户组创建流程

6.3 OAuth2 认证流程

七、与 IAM 集成

7.1 IAM SDK 依赖

7.2 IAM 回调接口

7.3 资源类型定义

八、配置说明

8.1 RBAC 配置类

8.2 MQ 配置

九、开发规范

9.1 新增权限操作

9.2 新增资源类型

9.3 权限校验示例

十、常见问题

Auth 权限认证模块架构指南

一、模块整体结构

1.1 子模块划分

1.2 模块职责矩阵

二、核心概念

2.1 RBAC 权限模型

2.2 核心实体关系

2.3 默认用户组类型

三、分层架构图

四、核心数据库表

4.1 用户组相关表

4.2 资源相关表

4.3 授权相关表

4.4 OAuth2 相关表

五、核心类速查

5.1 API 接口层

5.2 RBAC Provider 层（核心服务）

5.3 通用 Service 层

5.4 DAO 层

六、核心流程

6.1 权限校验流程

6.2 用户组创建流程

6.3 OAuth2 认证流程

七、与 IAM 集成

7.1 IAM SDK 依赖

7.2 IAM 回调接口

7.3 资源类型定义

八、配置说明

8.1 RBAC 配置类

8.2 MQ 配置

九、开发规范

9.1 新增权限操作

9.2 新增资源类型

9.3 权限校验示例

十、常见问题