repository-module-architecture

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 接口层

类名	路径前缀	职责
`UserRep

---

Content truncated.