dispatch-module-architecture
Installation
SKILL.md
Dispatch 构建调度模块架构指南
模块定位: Dispatch 是 BK-CI 的构建调度模块，负责接收流水线的构建任务，将任务分发到合适的构建机（第三方构建机、Docker 容器、Kubernetes Pod）上执行。
一、模块整体结构
1.1 子模块划分
src/backend/ci/core/dispatch/
├── api-dispatch/ # API 接口定义层
│ └── src/main/kotlin/com/tencent/devops/dispatch/
│ ├── api/ # REST API 接口
│ ├── constants/ # 常量定义
│ └── pojo/ # 数据对象
│ ├── enums/ # 枚举
│ ├── redis/ # Redis 数据结构
│ └── thirdpartyagent/ # 第三方构建机相关
│
├── api-dispatch-docker/ # Docker 调度 API
├── api-dispatch-kubernetes/ # Kubernetes 调度 API
│
├── biz-dispatch/ # 业务逻辑层
│ └── src/main/kotlin/com/tencent/devops/dispatch/
│ ├── configuration/ # 配置类
│ ├── controller/ # API 实现
│ ├── cron/ # 定时任务
│ ├── dao/ # 数据访问层
│ ├── exception/ # 异常定义
│ ├── listener/ # 消息监听
│ ├── service/ # 业务服务
│ │ ├── jobquota/ # 作业配额服务
│ │ └── tpaqueue/ # 第三方构建机队列
│ └── utils/ # 工具类
│
├── biz-dispatch-docker/ # Docker 调度业务
├── biz-dispatch-kubernetes/ # Kubernetes 调度业务
├── common-dispatch-kubernetes/ # Kubernetes 通用组件
├── model-dispatch/ # 数据模型层
└── boot-dispatch/ # Spring Boot 启动模块
1.2 调度类型
| 类型 | 说明 | 实现模块 |
|---|---|---|
| 第三方构建机 | 用户自有构建机 | biz-dispatch |
| Docker 构建机 | 公共 Docker 容器 | biz-dispatch-docker |
| Kubernetes | K8s Pod 构建 | biz-dispatch-kubernetes |
二、核心概念
2.1 构建任务状态
enum class PipelineTaskStatus(val status: Int) {
QUEUE(0), // 排队中
RUNNING(1), // 运行中
DONE(2), // 已完成
FAILURE(3), // 失败
CANCEL(4), // 取消
}
2.2 构建机类型
enum class JobQuotaVmType(val type: String) {
DOCKER("DOCKER"), // Docker 构建机
THIRD_PARTY_AGENT("THIRD_PARTY"), // 第三方构建机
KUBERNETES("KUBERNETES"), // K8s 构建机
AGENTLESS("AGENTLESS"), // 无编译环境
}
2.3 第三方构建机任务类型
enum class BuildJobType(val type: String) {
ALL("ALL"), // 所有类型
DOCKER("DOCKER"), // Docker 构建
BINARY("BINARY"), // 二进制构建
}
三、核心数据库表
3.1 调度记录表
| 表名 | 说明 | 核心字段 |
|---|---|---|
T_DISPATCH_PIPELINE_BUILD |
流水线构建调度记录 | PROJECT_ID, PIPELINE_ID, BUILD_ID, VM_SEQ_ID, STATUS |
T_DISPATCH_THIRDPARTY_AGENT_BUILD |
第三方构建机任务 | PROJECT_ID, AGENT_ID, BUILD_ID, STATUS, WORKSPACE |
T_DISPATCH_PIPELINE_DOCKER_BUILD |
Docker 构建任务 | BUILD_ID, VM_SEQ_ID, STATUS, DOCKER_IP, CONTAINER_ID |
T_DISPATCH_PIPELINE_DOCKER_TASK |
Docker 任务详情 | PROJECT_ID, AGENT_ID, IMAGE_NAME, STATUS |
3.2 配额管理表
| 表名 | 说明 | 核心字段 |
|---|---|---|
T_DISPATCH_QUOTA_PROJECT |
项目配额 | PROJECT_ID, VM_TYPE, RUNNING_JOBS_MAX, RUNNING_TIME_PROJECT_MAX |
T_DISPATCH_QUOTA_SYSTEM |
系统配额 | VM_TYPE, RUNNING_JOBS_MAX_SYSTEM, RUNNING_TIME_JOB_MAX |
T_DISPATCH_RUNNING_JOBS |
运行中的任务 | PROJECT_ID, VM_TYPE, BUILD_ID, AGENT_START_TIME |
3.3 队列管理表
| 表名 | 说明 |
|---|---|
T_DISPATCH_THIRDPARTY_AGENT_QUEUE |
第三方构建机任务队列 |
T_DISPATCH_PIPELINE_DOCKER_DEBUG |
Docker 调试会话 |
3.4 字段说明
⚠️ 重要:
PROJECT_ID是T_PROJECT.english_name
四、分层架构
┌─────────────────────────────────────────────────────────────────────────┐
│ Process 模块 │
│ (流水线引擎发起调度请求) │
└─────────────────────────────────────────────────────────────────────────┘
│
▼ (MQ 消息)
┌─────────────────────────────────────────────────────────────────────────┐
│ Dispatch 模块 │
├─────────────────────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ 消息监听层 (listener/) │ │
│ │ ThirdPartyBuildListener - 第三方构建机任务监听 │ │
│ │ TPAQueueListener - 第三方构建机队列监听 │ │
│ │ TPAMonitorListener - 第三方构建机监控监听 │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ 核心服务层 (service/) │ │
│ │ ThirdPartyDispatchService (45KB) - 第三方构建机调度核心 │ │
│ │ ThirdPartyAgentService (38KB) - 第三方构建机管理 │ │
│ │ TPAQueueService - 任务队列服务 │ │
│ │ TPAEnvQueueService - 环境队列服务 │ │
│ │ JobQuotaManagerService - 配额管理服务 │ │
│ │ AuthBuildService - 构建认证服务 │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ DAO 层 (dao/) │ │
│ │ ThirdPartyAgentBuildDao (17KB) - 第三方构建任务访问 │ │
│ │ RunningJobsDao - 运行任务访问 │ │
│ │ JobQuotaProjectDao - 项目配额访问 │ │
│ │ TPAQueueDao - 队列访问 │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 构建机 (Agent) │
│ (第三方构建机 / Docker / K8s) │
└─────────────────────────────────────────────────────────────────────────┘
五、核心类速查
5.1 API 接口层
| 类名 | 路径前缀 | 职责 |
|---|---|---|
BuildAgentBuildResource |
/build/agent |
构建机与调度服务交互 |
ServiceAgentResource |
/service/agent |
服务间构建机操作 |
ServiceDispatchJobResource |
/service/dispatch/job |
服务间任务调度 |
OpJobQuotaProjectResource |
/op/quota/project |
运维项目配额管理 |
OpJobQuotaSystemResource |
/op/quota/system |
运维系统配额管理 |
ExternalAuthBuildResource |
/external/auth |
外部构建认证 |
5.2 Service 层
| 类名 | 文件大小 | 职责 |
|---|---|---|
ThirdPartyDispatchService |
45KB | 第三方构建机调度核心（最大） |
ThirdPartyAgentService |
38KB | 第三方构建机管理 |
TPAEnvQueueService |
23KB | 环境队列服务 |
JobQuotaBusinessService |
14KB | 配额业务服务 |
TPAQueueService |
13KB | 任务队列服务 |
TPASingleQueueService |
13KB | 单队列服务 |
ThirdPartyAgentMonitorService |
13KB | 构建机监控 |
ThirdPartyAgentDockerService |
13KB | Docker 构建服务 |
5.3 DAO 层
| 类名 | 文件大小 | 职责 |
|---|---|---|
ThirdPartyAgentBuildDao |
17KB | 第三方构建任务访问 |
RunningJobsDao |
8KB | 运行任务访问 |
TPAQueueDao |
6KB | 队列访问 |
DispatchPipelineBuildDao |
5KB | 流水线构建访问 |
JobQuotaSystemDao |
5KB | 系统配额访问 |
JobQuotaProjectDao |
5KB | 项目配额访问 |
六、核心流程
6.1 第三方构建机调度流程
Process 模块发送调度消息
│
▼
ThirdPartyBuildListener.onBuildStart()
│
▼
ThirdPartyDispatchService.dispatch()
│
├─► 检查配额
│ └─► JobQuotaManagerService.checkJobQuota()
│
├─► 选择构建机
│ ├─► 根据环境 ID 筛选
│ ├─► 根据 Agent 状态筛选
│ └─► 负载均衡选择
│
├─► 创建调度记录
│ └─► ThirdPartyAgentBuildDao.create()
│
└─► 通知 Agent
└─► Redis 发布任务消息
6.2 Agent 领取任务流程
Agent 轮询请求任务
│
▼
BuildAgentBuildResource.claimTask()
│
▼
ThirdPartyAgentService.claimTask()
│
├─► 验证 Agent 身份
│ └─► 检查 Agent ID 和 Secret Key
│
├─► 查询待执行任务
│ └─► ThirdPartyAgentBuildDao.getQueueTask()
│
├─► 更新任务状态
│ └─► status = RUNNING
│
└─► 返回任务信息
└─► ThirdPartyBuildInfo
6.3 构建完成流程
Agent 报告构建完成
│
▼
BuildAgentBuildResource.finishTask()
│
▼
ThirdPartyAgentService.finishTask()
│
├─► 更新任务状态
│ └─► status = DONE / FAILURE
│
├─► 释放配额
│ └─► JobQuotaManagerService.releaseQuota()
│
└─► 通知 Process 模块
└─► 发送构建完成事件
七、配额管理
7.1 配额维度
| 维度 | 说明 |
|---|---|
| 系统级 | 全局最大并发数、单任务最大时长 |
| 项目级 | 项目最大并发数、项目最大运行时长 |
| 构建机类型 | 按 Docker/第三方/K8s 分别限制 |
7.2 配额检查
// 检查配额是否足够
fun checkJobQuota(
projectId: String,
vmType: JobQuotaVmType,
buildId: String
): Boolean {
// 1. 检查系统级配额
val systemQuota = jobQuotaSystemDao.get(vmType)
val systemRunning = runningJobsDao.countByVmType(vmType)
if (systemRunning >= systemQuota.runningJobsMax) {
return false
}
// 2. 检查项目级配额
val projectQuota = jobQuotaProjectDao.get(projectId, vmType)
val projectRunning = runningJobsDao.countByProject(projectId, vmType)
if (projectRunning >= projectQuota.runningJobsMax) {
return false
}
return true
}
八、与其他模块的关系
8.1 依赖关系
┌─────────────────────────────────────────────────────────────────┐
│ Dispatch 模块依赖关系 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────┐ │
│ │ process │ ──────► 发送调度消息 │
│ └───────────┘ │
│ │ │
│ ▼ │
│ ┌───────────┐ │
│ │ dispatch │ │
│ └─────┬─────┘ │
│ │ │
│ ├──────► project (项目信息) │
│ ├──────► environment (构建机信息) │
│ └──────► auth (权限校验) │
│ │
│ 被依赖： │
│ - agent（构建机领取任务） │
└─────────────────────────────────────────────────────────────────┘
8.2 服务间调用示例
// Process 模块查询调度状态
client.get(ServiceDispatchJobResource::class).getDispatchJob(
projectId = projectId, // english_name
pipelineId = pipelineId,
buildId = buildId,
vmSeqId = vmSeqId
)
// Environment 模块获取 Agent 信息
client.get(ServiceThirdPartyAgentResource::class).getAgentById(
projectId = projectId,
agentId = agentId
)
九、开发规范
9.1 新增调度类型
- 在
JobQuotaVmType添加新类型 - 创建对应的调度服务实现
- 在配额表中添加新类型的配置
- 实现任务分发和状态管理逻辑
9.2 调度记录查询示例
// 查询构建任务
val task = thirdPartyAgentBuildDao.get(
dslContext = dslContext,
buildId = buildId,
vmSeqId = vmSeqId
)
// 查询 Agent 的运行任务
val runningTasks = thirdPartyAgentBuildDao.listByAgentId(
dslContext = dslContext,
agentId = agentId,
status = PipelineTaskStatus.RUNNING.status
)
十、常见问题
Q: 如何选择构建机？ A: 根据环境 ID、Agent 状态、负载情况综合选择，优先选择空闲的 Agent。
Q: 配额不足时任务会怎样？ A: 任务会进入队列等待，直到有配额释放。
Q: Agent 离线后任务会怎样？ A: 任务会被标记为失败，或者重新调度到其他 Agent。
Q: 如何调整项目配额？
A: 通过运维接口 OpJobQuotaProjectResource 调整。
版本: 1.0.0 | 更新日期: 2025-12-11
Related skills
More from tencentblueking/bk-ci
frontend-vue-development
前端 Vue 开发规范，涵盖 Vue 2/3 组件开发、Vuex 状态管理、路由配置、组件通信、样式规范、国际化。当用户进行前端开发、编写 Vue 组件、处理状态管理或实现页面交互时使用。
146git-commit-specification
Git 提交规范，涵盖 commit message 格式（feat/fix/refactor）、Issue 关联、分支命名、PR 提交准备、rebase 使用。当用户提交代码、编写 commit message、创建分支或准备 PR 时使用。
63design-patterns
BK-CI 项目设计模式实践指南，涵盖工厂模式、策略模式、观察者模式、装饰器模式、模板方法等在项目中的实际应用。当用户学习设计模式、重构代码、设计可扩展架构或理解项目设计时使用。
62backend-microservice-development
后端微服务开发规范，涵盖目录结构、分层架构（API/Service/DAO）、依赖注入、配置管理、Spring Boot 最佳实践。当用户进行后端开发、创建新微服务、编写 Kotlin/Java 代码或设计服务架构时使用。
60database-design
BK-CI 数据库设计规范与表结构指南，涵盖命名规范、字段类型选择、索引设计、分表策略、数据归档。当用户设计数据库表、优化索引、规划分表策略或进行数据库架构设计时使用。
53unit-testing
单元测试编写指南，涵盖 JUnit5/MockK 使用、测试命名规范、Mock 技巧、测试覆盖率要求、TDD 实践。当用户编写单元测试、Mock 依赖、提高测试覆盖率或进行测试驱动开发时使用。
53