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 新增调度类型

1. 在 JobQuotaVmType 添加新类型
2. 创建对应的调度服务实现
3. 在配额表中添加新类型的配置
4. 实现任务分发和状态管理逻辑

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