name	35-dispatch-module-architecture
description	Dispatch 构建调度模块架构指南，涵盖构建机调度策略、资源分配、队列管理、Docker/K8s 调度、Agent 选择。当用户开发调度功能、配置调度策略、处理资源分配或实现新调度类型时使用。

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

35-dispatch-module-architecture

Install Skill

SKILL.md