name	32-repository-module-architecture
description	Repository 代码库管理模块架构指南，涵盖 Git/SVN 代码库接入、Webhook 配置、代码库授权、触发器管理。当用户开发代码库功能、配置 Webhook、处理代码库授权或实现触发器逻辑时使用。

Repository 代码库管理模块架构指南

模块定位: Repository 是 BK-CI 的代码库管理模块，负责对接各种代码托管平台（Git、SVN、GitHub、GitLab、TGit、P4），管理代码库的认证、授权、Webhook 等功能。

一、模块整体结构

1.1 子模块划分

src/backend/ci/core/repository/
├── api-repository/          # API 接口定义层
│   └── src/main/kotlin/com/tencent/devops/repository/
│       ├── api/                 # REST API 接口（30+ 文件）
│       │   ├── github/          # GitHub 专用接口
│       │   └── scm/             # SCM 通用接口
│       ├── constant/            # 常量和消息码
│       ├── pojo/                # 数据对象（40+ 文件）
│       ├── sdk/                 # SDK 定义
│       └── utils/               # 工具类
│
├── biz-repository/          # 业务逻辑层
│   └── src/main/kotlin/com/tencent/devops/repository/
│       ├── dao/                 # 数据访问层（18 文件）
│       ├── resources/           # API 实现
│       │   ├── github/          # GitHub 实现
│       │   ├── scm/             # SCM 实现
│       │   └── tapd/            # TAPD 实现
│       ├── service/             # 业务服务
│       │   ├── code/            # 各代码库类型服务
│       │   ├── github/          # GitHub 服务
│       │   ├── hub/             # SCM Hub 服务
│       │   ├── loader/          # 服务加载器
│       │   └── oauth2/          # OAuth2 服务
│       ├── sdk/                 # SDK 实现
│       └── utils/               # 工具类
│
├── biz-base-scm/            # SCM 基础库（Git/SVN 操作封装）
├── model-repository/        # 数据模型层（JOOQ 生成）
├── boot-repository/         # Spring Boot 启动模块
├── plugin-github/           # GitHub 插件扩展
└── plugin-tapd/             # TAPD 插件扩展

1.2 支持的代码库类型

类型	枚举值	说明	认证方式
Git（工蜂）	`CODE_GIT`	腾讯工蜂 Git	OAuth / SSH / HTTP
TGit	`CODE_TGIT`	腾讯 TGit	OAuth / SSH / HTTP
GitHub	`GITHUB`	GitHub.com	OAuth / GitHub App
GitLab	`CODE_GITLAB`	GitLab 私有部署	HTTP / SSH
SVN	`CODE_SVN`	Subversion	HTTP / SSH
P4	`CODE_P4`	Perforce	凭证认证

二、核心概念

2.1 代码库实体模型

┌─────────────────────────────────────────────────────────────────────────┐
│                         代码库模型                                       │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                    T_REPOSITORY（主表）                           │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │   │
│  │  │REPOSITORY_ID│  │ PROJECT_ID  │  │ ALIAS_NAME  │              │   │
│  │  │ (代码库ID)   │  │ (项目ID)    │  │ (别名)       │              │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘              │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │   │
│  │  │    URL      │  │    TYPE     │  │  ENABLE_PAC │              │   │
│  │  │ (代码库地址) │  │ (代码库类型) │  │ (PAC开关)    │              │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘              │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                              │                                           │
│              ┌───────────────┼───────────────┬───────────────┐          │
│              ▼               ▼               ▼               ▼          │
│  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────┐   │
│  │T_REPOSITORY_  │ │T_REPOSITORY_  │ │T_REPOSITORY_  │ │T_REPOSITORY│   │
│  │  CODE_GIT     │ │ CODE_GITLAB   │ │  CODE_SVN     │ │  _GITHUB   │   │
│  │ (Git明细表)    │ │ (GitLab明细)  │ │ (SVN明细表)   │ │(GitHub明细)│   │
│  └───────────────┘ └───────────────┘ └───────────────┘ └───────────┘   │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

2.2 核心字段说明

⚠️ 重要: 这里的 PROJECT_ID 是 T_PROJECT.english_name，不是 T_PROJECT.PROJECT_ID

字段	类型	说明
`REPOSITORY_ID`	Long	代码库主键（自增）
`PROJECT_ID`	String	项目标识（= T_PROJECT.english_name）
`ALIAS_NAME`	String	代码库别名（用户自定义）
`URL`	String	代码库 URL
`TYPE`	String	代码库类型（CODE_GIT/GITHUB 等）
`REPOSITORY_HASH_ID`	String	代码库 HashId（对外暴露）
`ENABLE_PAC`	Boolean	是否开启 PAC（Pipeline as Code）
`SCM_CODE`	String	SCM 配置标识

2.3 认证类型

enum class RepoAuthType(val value: String) {
    HTTP("HTTP"),           // HTTP 用户名密码
    HTTPS("HTTPS"),         // HTTPS
    SSH("SSH"),             // SSH 密钥
    OAUTH("OAUTH"),         // OAuth 授权
    TOKEN("TOKEN"),         // 个人访问令牌
    GITHUB_APP("GITHUB_APP") // GitHub App
}

三、核心数据库表

3.1 主表

表名	说明	核心字段
`T_REPOSITORY`	代码库主表	`REPOSITORY_ID`, `PROJECT_ID`, `ALIAS_NAME`, `URL`, `TYPE`, `ENABLE_PAC`
`T_REPOSITORY_COMMIT`	代码提交记录	`BUILD_ID`, `PIPELINE_ID`, `REPO_ID`, `COMMIT`, `COMMITTER`

3.2 各类型明细表

表名	说明	特有字段
`T_REPOSITORY_CODE_GIT`	工蜂 Git 明细	`PROJECT_NAME`, `CREDENTIAL_ID`, `AUTH_TYPE`, `GIT_PROJECT_ID`
`T_REPOSITORY_CODE_GITLAB`	GitLab 明细	`PROJECT_NAME`, `CREDENTIAL_ID`, `AUTH_TYPE`
`T_REPOSITORY_CODE_SVN`	SVN 明细	`REGION`, `PROJECT_NAME`, `SVN_TYPE`, `CREDENTIAL_ID`
`T_REPOSITORY_GITHUB`	GitHub 明细	`PROJECT_NAME`, `CREDENTIAL_ID`, `GIT_PROJECT_ID`
`T_REPOSITORY_CODE_P4`	P4 明细	`PROJECT_NAME`, `CREDENTIAL_ID`

3.3 Token 表

表名	说明
`T_REPOSITORY_GIT_TOKEN`	工蜂 OAuth Token
`T_REPOSITORY_TGIT_TOKEN`	TGit OAuth Token
`T_REPOSITORY_GITHUB_TOKEN`	GitHub OAuth Token

3.4 其他表

表名	说明
`T_REPOSITORY_GIT_CHECK`	Git Commit Check 记录
`T_REPOSITORY_PIPELINE_REF`	代码库与流水线关联
`T_REPOSITORY_SCM_CONFIG`	SCM 配置
`T_REPOSITORY_SCM_PROVIDER`	SCM 提供商配置
`T_REPOSITORY_WEBHOOK_REQUEST`	Webhook 请求记录

四、分层架构

┌─────────────────────────────────────────────────────────────────────────┐
│                              请求入口                                    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         API 层 (api-repository)                          │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐    │
│  │UserRepository│ │ServiceRepo   │ │ServiceScm    │ │ServiceGithub │    │
│  │Resource      │ │Resource      │ │Resource      │ │Resource      │    │
│  │(用户代码库)   │ │(服务间调用)   │ │(SCM操作)     │ │(GitHub操作)  │    │
│  └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                       业务层 (biz-repository)                            │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      核心 Service                                 │   │
│  │  RepositoryService (70KB)    - 代码库 CRUD 核心服务               │   │
│  │  RepositoryOauthService      - OAuth 授权服务                    │   │
│  │  RepositoryPacService        - PAC 服务                          │   │
│  │  RepositoryScmConfigService  - SCM 配置服务                      │   │
│  │  CommitService               - 提交记录服务                       │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                    │                                     │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                    代码库类型服务 (service/code/)                  │   │
│  │  CodeGitRepositoryService    - 工蜂 Git 服务                     │   │
│  │  CodeTGitRepositoryService   - TGit 服务                         │   │
│  │  CodeGithubRepositoryService - GitHub 服务                       │   │
│  │  CodeGitlabRepositoryService - GitLab 服务                       │   │
│  │  CodeSvnRepositoryService    - SVN 服务                          │   │
│  │  CodeP4RepositoryService     - P4 服务                           │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                    │                                     │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                    SCM Hub 服务 (service/hub/)                    │   │
│  │  ScmApiComposer              - SCM API 组合器                    │   │
│  │  ScmRepositoryApiService     - 仓库 API 服务                     │   │
│  │  ScmFileApiService           - 文件 API 服务                     │   │
│  │  ScmWebhookApiService        - Webhook API 服务                  │   │
│  │  ScmProviderAuthFactory      - 认证工厂                          │   │
│  └──────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         DAO 层 (biz-repository/dao)                      │
│  RepositoryDao (25KB) | RepositoryCodeGitDao | RepositoryGithubDao      │
│  CommitDao | GitTokenDao | RepositoryScmConfigDao | ...                 │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                      数据层 (model-repository + MySQL)                   │
│  数据库：devops_ci_repository（共 15+ 张表）                             │
└─────────────────────────────────────────────────────────────────────────┘

五、核心类速查

5.1 API 接口层

类名	路径前缀	职责
`UserRepositoryResource`	`/user/repositories`	用户代码库管理（创建/更新/删除）
`ServiceRepositoryResource`	`/service/repositories`	服务间代码库查询
`ServiceScmResource`	`/service/scm`	SCM 通用操作
`ServiceGitResource`	`/service/git`	Git 操作（分支/Tag/文件）
`ServiceGithubResource`	`/service/github`	GitHub 操作
`ServiceOauthResource`	`/service/oauth`	OAuth 授权
`ServiceRepositoryPacResource`	`/service/pac`	PAC 相关

5.2 Service 层

类名	文件大小	职责
`RepositoryService`	70KB	代码库核心服务（最大）
`OPRepositoryService`	32KB	运维代码库服务
`RepositoryScmConfigService`	30KB	SCM 配置服务
`CodeGitRepositoryService`	25KB	工蜂 Git 服务
`ScmRepositoryApiService`	23KB	SCM 仓库 API
`RepoFileService`	21KB	文件服务
`GithubService`	21KB	GitHub 服务

5.3 DAO 层

类名	文件大小	职责
`RepositoryDao`	25KB	代码库主表访问
`RepositoryCodeGitDao`	13KB	Git 明细表访问
`RepoPipelineRefDao`	12KB	流水线关联访问
`RepositoryGithubDao`	11KB	GitHub 明细表访问
`RepositoryScmConfigDao`	10KB	SCM 配置访问

六、核心流程

6.1 代码库创建流程

用户请求
    │
    ▼
UserRepositoryResource.create()
    │
    ▼
RepositoryService.userCreate()
    │
    ├─► 权限校验
    │   └─► repositoryPermissionService.validatePermission()
    │
    ├─► 参数校验
    │   ├─► 校验 URL 格式
    │   ├─► 校验别名唯一性
    │   └─► 校验凭证有效性
    │
    ├─► 根据类型创建
    │   └─► CodeRepositoryServiceRegistrar.getService(type).create()
    │       ├─► CodeGitRepositoryService.create()
    │       ├─► CodeGithubRepositoryService.create()
    │       └─► ...
    │
    ├─► 写入数据库
    │   ├─► repositoryDao.create()        # 主表
    │   └─► repositoryCodeXxxDao.create() # 明细表
    │
    └─► 注册到权限中心
        └─► authPermissionApi.createResource()

6.2 OAuth 授权流程

┌─────────────────────────────────────────────────────────────────┐
│                     OAuth 授权流程                               │
├─────────────────────────────────────────────────────────────────┤
│  1. 用户发起授权                                                 │
│     UserRepositoryOauthResource.getOauthUrl()                   │
│                          │                                       │
│                          ▼                                       │
│  2. 重定向到代码托管平台                                          │
│     返回 OAuth 授权 URL                                          │
│                          │                                       │
│                          ▼                                       │
│  3. 用户在平台授权                                               │
│     用户登录并授权 BK-CI 访问                                     │
│                          │                                       │
│                          ▼                                       │
│  4. 回调处理                                                     │
│     ExternalGithubResource.callback() / ExternalRepoResource    │
│                          │                                       │
│                          ▼                                       │
│  5. 获取并存储 Token                                             │
│     RepositoryOauthService.saveToken()                          │
│     存入 T_REPOSITORY_XXX_TOKEN 表                              │
└─────────────────────────────────────────────────────────────────┘

6.3 代码库类型服务加载机制

// 服务注册器模式
@Service
class CodeRepositoryServiceRegistrar {
    
    private val serviceMap = mutableMapOf<ScmType, CodeRepositoryService>()
    
    fun register(type: ScmType, service: CodeRepositoryService) {
        serviceMap[type] = service
    }
    
    fun getService(type: ScmType): CodeRepositoryService {
        return serviceMap[type] ?: throw NotFoundException("...")
    }
}

// 各类型服务自动注册
@Service
class CodeGitRepositoryService : CodeRepositoryService {
    @PostConstruct
    fun init() {
        registrar.register(ScmType.CODE_GIT, this)
    }
}

七、与其他模块的关系

7.1 依赖关系

┌─────────────────────────────────────────────────────────────────┐
│                    Repository 模块依赖关系                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│                  ┌───────────────┐                               │
│                  │  repository   │                               │
│                  └───────┬───────┘                               │
│                          │                                       │
│         ┌────────────────┼────────────────┐                     │
│         ▼                ▼                ▼                     │
│  ┌───────────┐    ┌───────────┐    ┌───────────┐               │
│  │  project  │    │  ticket   │    │   auth    │               │
│  │ (项目信息) │    │ (凭证管理) │    │ (权限校验) │               │
│  └───────────┘    └───────────┘    └───────────┘               │
│                                                                  │
│  被依赖：                                                        │
│  - process（流水线拉取代码）                                      │
│  - store（插件代码库）                                           │
│  - openapi（开放接口）                                           │
└─────────────────────────────────────────────────────────────────┘

7.2 服务间调用示例

// Process 模块调用 Repository 获取代码库信息
// 注意：projectId 是 T_PROJECT.english_name
client.get(ServiceRepositoryResource::class).get(
    projectId = projectId,  // english_name
    repositoryId = repositoryHashId,
    repositoryType = RepositoryType.ID
)

// 获取代码库列表
client.get(ServiceRepositoryResource::class).list(
    projectId = projectId,
    repositoryType = ScmType.CODE_GIT.name
)

// 获取文件内容
client.get(ServiceScmResource::class).getFileContent(
    projectName = repoProjectName,
    ref = branch,
    filePath = filePath,
    token = token,
    authType = RepoAuthType.OAUTH,
    scmType = ScmType.CODE_GIT
)

八、PAC（Pipeline as Code）支持

8.1 PAC 概念

PAC 允许用户在代码库中通过 YAML 文件定义流水线，代码库变更时自动同步流水线配置。

8.2 PAC 相关字段

// T_REPOSITORY 表
ENABLE_PAC: Boolean      // 是否开启 PAC
YAML_SYNC_STATUS: String // PAC 同步状态（SYNC/SYNCING/FAILED）

8.3 PAC 服务

@Service
class RepositoryPacService {
    // 开启 PAC
    fun enablePac(projectId: String, repositoryHashId: String)
    
    // 关闭 PAC
    fun disablePac(projectId: String, repositoryHashId: String)
    
    // 同步 YAML 流水线
    fun syncYamlPipeline(projectId: String, repositoryHashId: String)
}

九、开发规范

9.1 新增代码库类型

在 ScmType 枚举中添加新类型
创建明细表 T_REPOSITORY_CODE_XXX
创建 DAO 类 RepositoryCodeXxxDao
创建服务类 CodeXxxRepositoryService 实现 CodeRepositoryService
在 CodeRepositoryServiceRegistrar 中注册
添加对应的 POJO 类（如 CodeXxxRepository）

9.2 代码库查询示例

// 根据 HashId 查询
val repository = repositoryDao.getByHashId(
    dslContext = dslContext,
    projectId = projectId,  // english_name
    repositoryHashId = hashId
)

// 根据 ID 查询
val repository = repositoryDao.get(
    dslContext = dslContext,
    projectId = projectId,
    repositoryId = repositoryId
)

// 列表查询
val list = repositoryDao.listByProject(
    dslContext = dslContext,
    projectId = projectId,
    repositoryType = ScmType.CODE_GIT.name,
    offset = offset,
    limit = limit
)

9.3 凭证使用

代码库的凭证存储在 Ticket 模块，通过 CREDENTIAL_ID 关联：

// 获取凭证
val credential = client.get(ServiceCredentialResource::class).get(
    projectId = projectId,
    credentialId = credentialId
)

十、常见问题

Q: 如何判断代码库类型？ A: 查看 T_REPOSITORY.TYPE 字段，值为 CODE_GIT、GITHUB、CODE_GITLAB 等。

Q: repositoryId 和 repositoryHashId 的区别？ A: repositoryId 是数据库自增 ID，repositoryHashId 是对外暴露的 Hash 编码 ID。

Q: 如何获取代码库的认证信息？ A: 通过 CREDENTIAL_ID 从 Ticket 模块获取凭证，或通过 OAuth Token 表获取授权信息。

Q: PAC 开启后代码库能否删除？ A: 不能，需要先关闭 PAC 才能删除代码库。

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

32-repository-module-architecture

Install Skill

SKILL.md