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 新增代码库类型

1. 在 ScmType 枚举中添加新类型
2. 创建明细表 T_REPOSITORY_CODE_XXX
3. 创建 DAO 类 RepositoryCodeXxxDao
4. 创建服务类 CodeXxxRepositoryService 实现 CodeRepositoryService
5. 在 CodeRepositoryServiceRegistrar 中注册
6. 添加对应的 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