32-repository-module-architecture by TencentBlueKing

---
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 认证类型

```kotlin
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 代码库类型服务加载机制

```kotlin
// 服务注册器模式
@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 服务间调用示例

```kotlin
// 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 相关字段

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

### 8.3 PAC 服务

```kotlin
@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 代码库查询示例

```kotlin
// 根据 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` 关联：

```kotlin
// 获取凭证
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