BK-CI 全局架构指南
核心理念: 以流水线（Pipeline）为核心，理解 BK-CI 所有模块如何协同工作，完成从代码提交到制品交付的完整 CI/CD 流程。
一、全局架构概览
1.1 系统分层架构
┌─────────────────────────────────────────────────────────────────────────────┐
│ 用户层 (User Layer) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Web 前端 │ │ OpenAPI │ │ Webhook │ │ 第三方系统集成 │ │
│ │ (14个应用) │ │ (开放接口) │ │ (代码触发) │ │ (蓝鲸/企业微信等) │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │
└─────────┼────────────────┼────────────────┼────────────────────┼────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 网关层 (Gateway Layer) │
│ ┌─────────────────────────────────────────────────────────────────────────┐│
│ │ OpenResty (Nginx + Lua) ││
│ │ • 路由转发 • 身份认证 • 限流熔断 • 服务发现(Consul) ││
│ └─────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 微服务层 (Microservice Layer) │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐│
│ │ 核心服务 (Core Services) ││
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││
│ │ │ Project │ │ Process │ │ Auth │ │ Store │ │Repository│ ││
│ │ │ 项目管理 │ │ 流水线 │ │ 权限认证 │ │ 研发商店 │ │ 代码库 │ ││
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ ││
│ └─────────────────────────────────────────────────────────────────────────┘│
│ ┌─────────────────────────────────────────────────────────────────────────┐│
│ │ 调度服务 (Dispatch Services) ││
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││
│ │ │ Dispatch │ │Environment│ │ Ticket │ ││
│ │ │ 构建调度 │ │ 构建机 │ │ 凭证管理 │ ││
│ │ └──────────┘ └──────────┘ └──────────┘ ││
│ └─────────────────────────────────────────────────────────────────────────┘│
│ ┌─────────────────────────────────────────────────────────────────────────┐│
│ │ 支撑服务 (Support Services) ││
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││
│ │ │Artifactory│ │ Log │ │ Notify │ │ Quality │ │ Metrics │ ││
│ │ │ 制品库 │ │ 日志服务 │ │ 通知服务 │ │ 质量红线 │ │ 度量统计 │ ││
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ ││
│ └─────────────────────────────────────────────────────────────────────────┘│
│ ┌─────────────────────────────────────────────────────────────────────────┐│
│ │ 开放服务 (Open Services) ││
│ │ ┌──────────┐ ┌──────────┐ ││
│ │ │ OpenAPI │ │WebSocket │ ││
│ │ │ 开放接口 │ │ 实时推送 │ ││
│ │ └──────────┘ └──────────┘ ││
│ └─────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 构建机层 (Build Machine Layer) │
│ ┌─────────────────────────────────────────────────────────────────────────┐│
│ │ ┌──────────────────────┐ ┌──────────────────────┐ ││
│ │ │ Agent (Go) │ │ Worker (Kotlin) │ ││
│ │ │ • 进程守护 │ ───▶ │ • 任务执行 │ ││
│ │ │ • 任务调度 │ │ • 插件运行 │ ││
│ │ │ • 自动升级 │ │ • 日志上报 │ ││
│ │ └──────────────────────┘ └──────────────────────┘ ││
│ └─────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 资源层 (Resource Layer) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ MySQL │ │ Redis │ │ RabbitMQ │ │ ES │ │ 文件存储 │ │
│ │ 关系数据 │ │ 缓存/锁 │ │ 消息队列 │ │ 日志检索 │ │ 制品存储 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
1.2 模块职责速查表
| 模块 |
核心职责 |
关键能力 |
| Project |
项目管理 |
项目创建、成员管理、服务开通、路由分片 |
| Process |
流水线编排与执行 |
模型定义、构建调度、事件驱动、状态管理 |
| Auth |
权限认证 |
RBAC、资源授权、用户组、OAuth2 |
| Store |
研发商店 |
插件管理、模板市场、版本发布、统计分析 |
| Repository |
代码库管理 |
Git/SVN/P4 对接、Webhook、PAC |
| Dispatch |
构建调度 |
构建机分配、Docker 调度、配额管理 |
| Environment |
构建机环境 |
节点管理、Agent 安装、环境变量 |
| Ticket |
凭证管理 |
密码/SSH/Token 存储、加密解密 |
| Artifactory |
制品库 |
文件存储、版本管理、跨项目共享 |
| Log |
日志服务 |
构建日志收集、存储、检索 |
| Notify |
通知服务 |
邮件/企微/RTX 通知 |
| Quality |
质量红线 |
指标定义、准入准出、拦截规则 |
| Metrics |
度量统计 |
构建统计、趋势分析、报表 |
| OpenAPI |
开放接口 |
第三方集成、API 网关 |
| Agent |
构建机代理 |
进程管理、任务调度、自动升级 |
| Worker |
任务执行器 |
插件执行、脚本运行、日志上报 |
二、流水线生命周期全景
2.1 流水线创建流程
用户创建流水线
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 1. 前端 (devops-pipeline) │
│ • 流水线编辑器 (Pipeline Editor) │
│ • 可视化编排 Stage → Job → Task │
│ • 选择插件 (从 Store 获取) │
│ • 配置参数、触发器、通知 │
└─────────────────────────────────────────────────────────────────────────────┘
│ 提交 Model JSON
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 2. Process 服务 (API 层) │
│ • PipelineResource.create() 接收请求 │
│ • 参数校验、权限检查 (调用 Auth) │
│ • 项目校验 (调用 Project) │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 3. Process 服务 (Service 层) │
│ • PipelineRepositoryService.deployPipeline() │
│ • 解析 Model，校验插件 (调用 Store) │
│ • 校验代码库 (调用 Repository) │
│ • 校验凭证 (调用 Ticket) │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 4. Process 服务 (DAO 层) │
│ • 保存 T_PIPELINE_INFO (基本信息) │
│ • 保存 T_PIPELINE_RESOURCE (编排模型) │
│ • 保存 T_PIPELINE_SETTING (配置) │
│ • 初始化 T_PIPELINE_BUILD_SUMMARY (构建摘要) │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 5. Auth 服务 │
│ • 创建流水线资源权限 │
│ • 授予创建者管理员权限 │
│ • 同步到 IAM (蓝鲸权限中心) │
└─────────────────────────────────────────────────────────────────────────────┘
2.2 流水线执行全流程
这是 BK-CI 最核心的流程，涉及几乎所有模块的协作。下面从触发 → 调度 → 执行 → 完成四个阶段详细说明。
2.2.1 阶段一：触发构建
触发方式
| 触发类型 |
入口 |
说明 |
| 手动触发 |
Web/API |
用户点击"执行"按钮 |
| 定时触发 |
Cron |
TimerTriggerElement 定时调度 |
| 代码变更触发 |
Webhook |
Git Push/MR/Tag 事件 |
| 远程触发 |
OpenAPI |
第三方系统调用 |
| 子流水线调用 |
Sub-Pipeline |
父流水线调用子流水线 |
核心处理流程
用户/系统触发
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 1. API 层入口 │
│ PipelineBuildFacadeService.buildManualStartup() │
│ 源码: biz-process/.../service/builds/PipelineBuildFacadeService.kt:390 │
│ │
│ 主要职责: │
│ ├── 权限校验: pipelinePermissionService.validPipelinePermission() │
│ │ → 检查用户是否有 EXECUTE 权限 │
│ ├── 流水线校验: 检查是否锁定、版本是否最新 │
│ ├── 触发器校验: 检查 ManualTriggerElement 是否启用 │
│ ├── 参数解析: buildParamCompatibilityTransformer.parseTriggerParam() │
│ └── 调用: pipelineBuildService.startPipeline() │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 2. 构建服务层 │
│ PipelineBuildService.startPipeline() │
│ 源码: biz-base/.../service/pipeline/PipelineBuildService.kt:127 │
│ │
│ 主要职责: │
│ ├── 频率限制: simpleRateLimiter.acquire() 防止并发过高 │
│ ├── 拦截器链: pipelineInterceptorChain.filter() 执行前置检查 │
│ │ └── 包括: 排队检查、并发组检查、配额检查等 │
│ ├── 构建记录创建: pipelineRuntimeService.startBuild() │
│ │ ├── T_PIPELINE_BUILD_HISTORY (构建历史) │
│ │ ├── T_PIPELINE_BUILD_STAGE (Stage 状态) │
│ │ ├── T_PIPELINE_BUILD_CONTAINER (Job 状态) │
│ │ ├── T_PIPELINE_BUILD_TASK (Task 状态) │
│ │ └── T_PIPELINE_BUILD_VAR (构建变量) │
│ └── 发送启动事件: PipelineBuildStartEvent → RabbitMQ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
RabbitMQ 消息队列
关键源码位置
| 功能 |
类名 |
文件路径 |
| 手动构建入口 |
PipelineBuildFacadeService |
biz-process/.../service/builds/PipelineBuildFacadeService.kt |
| 构建启动核心 |
PipelineBuildService |
biz-base/.../service/pipeline/PipelineBuildService.kt |
| 运行时服务 |
PipelineRuntimeService |
biz-base/.../engine/service/PipelineRuntimeService.kt |
| Webhook 触发 |
WebhookTriggerBuildService |
biz-process/.../trigger/scm/WebhookTriggerBuildService.kt |
2.2.2 阶段二：引擎调度（核心）
构建启动后，引擎通过责任链模式和事件驱动机制，按 Stage → Job → Task 层级调度执行。
┌─────────────────────────────────────────────────────────────────────────────┐
│ 3. 构建启动控制器 │
│ BuildStartControl.handle(PipelineBuildStartEvent) │
│ 源码: biz-engine/.../control/BuildStartControl.kt:140 │
│ │
│ 主要职责: │
│ ├── 获取锁: BuildIdLock 防止重复处理 │
│ ├── 状态检查: 确认构建未结束、未取消 │
│ ├── 构建模型初始化: buildModel() 准备执行上下文 │
│ └── 发送 Stage 事件: PipelineBuildStageEvent → 第一个 Stage │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 4. Stage 控制器（责任链模式） │
│ StageControl.handle(PipelineBuildStageEvent) │
│ 源码: biz-engine/.../control/StageControl.kt:93 │
│ │
│ 责任链命令（按顺序执行）: │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 1. CheckInterruptStageCmd → 检查是否快速失败/中断 │ │
│ │ 2. CheckConditionalSkipStageCmd → 检查 Stage 条件跳过 │ │
│ │ 3. CheckPauseReviewStageCmd → 检查 Stage 暂停/审核 │ │
│ │ 4. StartContainerStageCmd → 下发 Container 事件（核心） │ │
│ │ 5. UpdateStateForStageCmdFinally → 更新 Stage 状态 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ StartContainerStageCmd 核心逻辑: │
│ 源码: biz-engine/.../command/stage/impl/StartContainerStageCmd.kt:68 │
│ ├── 遍历 Stage 下所有 Container（并行下发） │
│ ├── 发送 PipelineBuildContainerEvent 到每个 Job │
│ └── 同一 Stage 的多个 Job 并发执行 │
└─────────────────────────────────────────────────────────────────────────────┘
│
│ 并发下发多个 PipelineBuildContainerEvent
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 5. Container/Job 控制器（责任链模式） │
│ ContainerControl.handle(PipelineBuildContainerEvent) │
│ 源码: biz-engine/.../control/ContainerControl.kt:100 │
│ │
│ 责任链命令（按顺序执行）: │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 1. CheckDependOnContainerCmd → 检查 Job 依赖 │ │
│ │ 2. CheckConditionalSkipContainerCmd → 检查 Job 条件跳过 │ │
│ │ 3. CheckPauseContainerCmd → 检查 Job 暂停 │ │
│ │ 4. CheckMutexContainerCmd → 检查 Job 互斥组 │ │
│ │ 5. CheckDispatchQueueContainerCmd → 检查全局 Job 并发队列 │ │
│ │ 6. InitializeMatrixGroupStageCmd → 矩阵运算生成 Container │ │
│ │ 7. MatrixExecuteContainerCmd → 矩阵执行 │ │
│ │ 8. AgentReuseMutexCmd → Agent 复用互斥 │ │
│ │ 9. StartActionTaskContainerCmd → 启动 Task 执行（核心） │ │
│ │ 10. ContainerCmdLoop → 循环消息处理 │ │
│ │ 11. UpdateStateContainerCmdFinally → 更新 Job 状态 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ Job 类型判断: │
│ ├── VMBuildContainer: 需要构建机 → 执行 startVM Task → 调用 Dispatch │
│ ├── NormalContainer: 无编译环境 → 直接在引擎侧执行 │
│ └── TriggerContainer: 触发器 → 特殊处理 │
└─────────────────────────────────────────────────────────────────────────────┘
│
│ 需要构建机时，执行 startVM Task
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 6. Dispatch 服务 - 构建机分配 │
│ DispatchService.dispatch() │
│ 源码: biz-dispatch/.../service/DispatchService.kt │
│ │
│ 调度策略: │
│ ├── 公共构建机 (DevCloud): 云端容器 │
│ ├── 第三方构建机 (ThirdParty): 用户自有机器 │
│ └── Docker 构建 (Kubernetes): K8s Pod │
│ │
│ 调度流程: │
│ ├── 检查配额: T_DISPATCH_QUOTA_PROJECT │
│ ├── 查询可用构建机: Environment 服务 │
│ │ └── T_ENVIRONMENT_THIRDPARTY_AGENT │
│ ├── 创建调度记录: T_DISPATCH_THIRDPARTY_AGENT_BUILD │
│ └── 等待 Agent 领取任务 │
└─────────────────────────────────────────────────────────────────────────────┘
关键源码位置
| 功能 |
类名 |
文件路径 |
| 构建启动控制 |
BuildStartControl |
biz-engine/.../control/BuildStartControl.kt |
| Stage 控制 |
StageControl |
biz-engine/.../control/StageControl.kt |
| Container 控制 |
ContainerControl |
biz-engine/.../control/ContainerControl.kt |
| 下发 Container 事件 |
StartContainerStageCmd |
biz-engine/.../command/stage/impl/StartContainerStageCmd.kt |
| 启动 Task 执行 |
StartActionTaskContainerCmd |
biz-engine/.../command/container/impl/StartActionTaskContainerCmd.kt |
2.2.3 阶段三：任务执行
┌─────────────────────────────────────────────────────────────────────────────┐
│ 7. Agent (Go) - 构建机代理 │
│ 源码: src/agent/agent/src/pkg/job/build.go │
│ │
│ 主循环 (Ask Loop): │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ for { │ │
│ │ result := api.AskBuild() // 向 Dispatch 请求任务 │ │
│ │ if result.HasBuild { │ │
│ │ go runBuild(result.BuildInfo) // 异步执行 │ │
│ │ } │ │
│ │ time.Sleep(interval) // 轮询间隔 │ │
│ │ } │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ runBuild() 流程: │
│ ├── 1. 准备工作空间: 创建/清理工作目录 │
│ ├── 2. 设置环境变量: PROJECT_ID, PIPELINE_ID, BUILD_ID 等 │
│ ├── 3. 启动 Worker: java -jar worker.jar │
│ ├── 4. 监控 Worker: 等待进程结束 │
│ └── 5. 清理工作空间: 可选 │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 8. Worker (Kotlin) - 任务执行器 │
│ 源码: src/worker/worker-common/src/main/kotlin/.../Runner.kt │
│ │
│ 启动流程: │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 1. 初始化 │ │
│ │ ├── 启动心跳线程 (HeartbeatTask) │ │
│ │ ├── 初始化日志服务 (LoggerService) │ │
│ │ └── 调用 jobStarted API 通知服务端就绪 │ │
│ │ │ │
│ │ 2. 任务循环 (loopPickup) │ │
│ │ loop@ while (true) { │ │
│ │ val buildTask = EngineService.claimTask() // 领取任务 │ │
│ │ when (buildTask.status) { │ │
│ │ DO -> { │ │
│ │ val task = TaskFactory.create(buildTask.type) │ │
│ │ task.run(buildTask, buildVariables, workspace) │ │
│ │ EngineService.completeTask(result) // 上报结果 │ │
│ │ } │ │
│ │ WAIT -> Thread.sleep(sleepMills) // 暂无任务 │ │
│ │ END -> break@loop // Job 结束 │ │
│ │ } │ │
│ │ } │ │
│ │ │ │
│ │ 3. 完成构建 │ │
│ │ └── EngineService.endBuild() │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ Task 类型: │
│ ├── MarketAtomTask: 研发商店插件 │
│ ├── LinuxScriptTask: Shell 脚本 │
│ ├── WindowsScriptTask: Bat 脚本 │
│ ├── CodeGitPullTask: 代码拉取 │
│ └── ArchiveFileTask: 制品归档 │
└─────────────────────────────────────────────────────────────────────────────┘
│
│ 每个 Task 完成后调用 completeTask API
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 9. Task 控制器（引擎侧 Task 执行） │
│ TaskControl.handle(PipelineBuildAtomTaskEvent) │
│ 源码: biz-engine/.../control/TaskControl.kt:82 │
│ │
│ 说明: 此控制器处理引擎侧执行的 Task（如人工审核、质量红线等） │
│ 对于 Worker 侧执行的 Task，由 Worker 直接调用 completeTask API │
│ │
│ 主要职责: │
│ ├── 状态检查: 确认 Task 未完成 │
│ ├── 区分执行位置: runByVmTask() 判断是否在构建机执行 │
│ ├── 引擎侧执行: taskAtomService.start()/tryFinish() │
│ └── 结果处理: pipelineBuildTaskService.finishTask() │
└─────────────────────────────────────────────────────────────────────────────┘
关键源码位置
| 功能 |
类名 |
文件路径 |
| Agent 主程序 |
build.go |
src/agent/agent/src/pkg/job/build.go |
| Worker 主循环 |
Runner |
src/worker/worker-common/.../Runner.kt |
| Task 控制器 |
TaskControl |
biz-engine/.../control/TaskControl.kt |
| Task 完成处理 |
PipelineBuildTaskService |
biz-base/.../service/PipelineBuildTaskService.kt |
2.2.4 阶段四：结果处理与状态回传
┌─────────────────────────────────────────────────────────────────────────────┐
│ 10. Task 完成 → 触发 Container 事件 │
│ PipelineBuildTaskService.finishTask() │
│ 源码: biz-base/.../service/PipelineBuildTaskService.kt │
│ │
│ 处理流程: │
│ ├── 更新 Task 状态: T_PIPELINE_BUILD_TASK │
│ ├── 保存构建变量: 插件输出变量 │
│ └── 发送事件: PipelineBuildContainerEvent → 触发下一个 Task 调度 │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 11. Container/Job 完成 → 触发 Stage 事件 │
│ ContainerControl → UpdateStateContainerCmdFinally │
│ │
│ 处理流程: │
│ ├── 检查所有 Task 是否完成 │
│ ├── 更新 Container 状态: T_PIPELINE_BUILD_CONTAINER │
│ └── 发送事件: PipelineBuildStageEvent → 检查 Stage 是否完成 │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 12. Stage 完成 → 触发下一 Stage 或流水线完成 │
│ StageControl → UpdateStateForStageCmdFinally │
│ │
│ 处理流程: │
│ ├── 检查所有 Job 是否完成 │
│ ├── Quality: 检查准出红线 (Check-Out) │
│ ├── 更新 Stage 状态: T_PIPELINE_BUILD_STAGE │
│ └── 判断下一步: │
│ ├── 有下一个 Stage: 发送 PipelineBuildStageEvent │
│ └── 无下一个 Stage: 发送 PipelineBuildFinishEvent │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 13. 流水线完成处理 │
│ BuildEndControl.handle(PipelineBuildFinishEvent) │
│ 源码: biz-engine/.../control/BuildEndControl.kt │
│ │
│ 处理流程: │
│ ├── 更新构建状态: T_PIPELINE_BUILD_HISTORY │
│ ├── 释放资源: 构建机、互斥锁等 │
│ └── 触发后续处理: │
│ ├── Notify: 发送通知（邮件/企微/RTX） │
│ ├── Metrics: 更新统计数据 │
│ ├── Artifactory: 制品归档 │
│ └── WebSocket: 实时推送状态更新 │
└─────────────────────────────────────────────────────────────────────────────┘
2.2.5 执行流程总览图
┌─────────────────────────────────────────────────────────────────────────────┐
│ 流水线执行全流程总览 │
└─────────────────────────────────────────────────────────────────────────────┘
用户触发
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ PipelineBuild │────▶│ PipelineBuild │────▶│ PipelineRuntime │
│ FacadeService │ │ Service │ │ Service │
│ (权限校验) │ │ (拦截器链) │ │ (创建记录) │
└─────────────────┘ └─────────────────┘ └────────┬────────┘
│
▼
┌─────────────────────┐
│ PipelineBuildStart │
│ Event → RabbitMQ │
└──────────┬──────────┘
│
┌────────────────────────────────────────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ BuildStart │────▶│ StageControl │────▶│ Container │
│ Control │ │ (责任链) │ │ Control │
│ (启动控制) │ │ │ │ (责任链) │
└─────────────────┘ └─────────────────┘ └────────┬────────┘
│
┌───────────────────────────┤
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Dispatch │ │ TaskControl │
│ (构建机分配) │ │ (引擎侧Task) │
└────────┬────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ Agent (Go) │
│ (领取任务) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Worker (Kotlin) │
│ (执行Task) │
└────────┬────────┘
│
│ completeTask API
▼
┌─────────────────┐
│ PipelineBuild │
│ TaskService │
│ (状态回传) │
└────────┬────────┘
│
│ PipelineBuildContainerEvent
▼
┌─────────────────┐
│ 状态逐层回传 │
│ Task→Job→Stage │
│ →Pipeline │
└────────┬────────┘
│
▼
┌─────────────────┐
│ BuildEndControl │
│ (完成处理) │
└────────┬────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Notify │ │ Metrics │ │ WebSocket │
│ (通知) │ │ (统计) │ │ (推送) │
└─────────────┘ └─────────────┘ └─────────────┘
2.3 Job 执行机制详解（核心）
2.3.1 Job 中的系统 Task
重要概念：启动构建机本身就是一个 Task！每个 vmBuild 类型的 Job 会自动生成系统 Task：
┌─────────────────────────────────────────────────────────────────────────────┐
│ T_PIPELINE_BUILD_TASK 表数据示例 │
├─────────────────────────────────────────────────────────────────────────────┤
│ TASK_ID │ TASK_NAME │ TASK_ATOM │ TASK_SEQ │
├──────────────┼────────────────────┼──────────────────────────┼─────────────┤
│ startVM-1 │ Prepare_Job#1 │ dispatchVMStartupTaskAtom│ 1 ← 系统 │
│ e-xxx-1 │ Bash │ (空) │ 2 ← 用户 │
│ e-xxx-2 │ 代码拉取 │ (空) │ 3 ← 用户 │
│ e-xxx-3 │ 编译构建 │ (空) │ 4 ← 用户 │
│ end-1000 │ Wait_Finish_Job#1 │ (空) │ 1000 ← 系统 │
│ stopVM-1001 │ Clean_Job#1 │ dispatchVMShutdownTaskAtom│ 1001 ← 系统 │
└─────────────────────────────────────────────────────────────────────────────┘
说明：
• startVM-{containerId}：启动构建机 Task（TASK_SEQ=1），调用 Dispatch 拉起构建机
• 用户插件：TASK_SEQ 从 2 开始，TASK_ATOM 为空（由 Worker 执行）
• end-1000：等待所有用户插件完成的占位 Task
• stopVM-{containerId+1000}：关闭构建机 Task，释放资源
2.3.2 构建机启动与 Task 执行的协作流程
┌─────────────────────────────────────────────────────────────────────────────┐
│ 构建机启动流程（核心） │
└─────────────────────────────────────────────────────────────────────────────┘
Process 引擎 Dispatch 调度 Agent/Worker
│ │ │
│ 1. 执行 startVM Task │ │
│ (dispatchVMStartupTaskAtom) │
│─────────────────────────────▶│ │
│ │ │
│ (引擎不阻塞，继续处理 │ 2. 分配构建资源 │
│ 其他事件) │ (创建容器/分配构建机) │
│ │───────────────────────────────▶│
│ │ │
│ │ │ 3. Agent 启动 Worker
│ │ │
│ 4. Worker 调用 jobStarted API│ │
│◀────────────────────────────────────────────────────────────────│
│ (BuildJobResource.jobStarted) │
│ │ │
│ 5. 更新 startVM Task 状态 │ │
│ 为 SUCCEED │ │
│ │ │
│ 6. 发送 PipelineBuildContainerEvent │
│ (通知引擎继续执行) │ │
│ │ │
│ 7. 返回 BuildVariables │ │
│────────────────────────────────────────────────────────────────▶│
│ │ │
│ │ │ 8. Worker 开始执行插件
▼ ▼ ▼
关键点：
• Worker 采用 Pull 模式（主动报到），而非服务端 Push
• 构建机就绪后，Worker 调用 jobStarted API 通知服务端
• 服务端通过 PipelineBuildContainerEvent 事件驱动后续 Task
2.3.3 普通 Task 执行流程（Worker 侧）
┌─────────────────────────────────────────────────────────────────────────────┐
│ Worker 任务循环 │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ Runner.loopPickup() 主循环 │
│ │
│ loop@ while (true) { │
│ │ │
│ │ 1. 领取任务 │
│ ├──▶ val buildTask = EngineService.claimTask() │
│ │ │ │
│ │ │ HTTP API: GET /api/build/worker/claim │
│ │ ▼ │
│ │ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ 服务端 EngineVMBuildService.buildClaimTask() │ │
│ │ │ • 查询 QUEUE_CACHE/RUNNING 状态的 Task │ │
│ │ │ • 返回第一个待执行的 Task │ │
│ │ │ • 无任务时返回 WAIT 状态 │ │
│ │ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ 2. 根据状态处理 │
│ ├──▶ when (buildTask.status) { │
│ │ BuildTaskStatus.DO -> { │
│ │ │ │
│ │ │ 3. 创建执行器 │
│ │ ├──▶ val task = TaskFactory.create(buildTask.type) │
│ │ │ │ │
│ │ │ ├── linuxScript → LinuxScriptTask │
│ │ │ ├── windowsScript → WindowsScriptTask │
│ │ │ ├── marketBuild → MarketAtomTask │
│ │ │ └── marketBuildLess → MarketAtomTask │
│ │ │ │
│ │ │ 4. 执行任务 │
│ │ ├──▶ val taskDaemon = TaskDaemon(task, buildTask, ...) │
│ │ ├──▶ taskDaemon.runWithTimeout() │
│ │ │ │ │
│ │ │ └── task.run(buildTask, buildVariables, ws) │
│ │ │ │
│ │ │ 5. 上报结果 │
│ │ └──▶ EngineService.completeTask(buildTaskRst) │
│ │ │ │
│ │ │ HTTP API: POST /api/build/worker/complete │
│ │ ▼ │
│ │ ┌─────────────────────────────────────────────────┐ │
│ │ │ 服务端处理: │ │
│ │ │ • 保存构建变量 │ │
│ │ │ • 更新 Task 状态 │ │
│ │ │ • 发送 PipelineBuildContainerEvent │ │
│ │ │ • 引擎调度下一个 Task │ │
│ │ └─────────────────────────────────────────────────┘ │
│ │ } │
│ │ │
│ │ BuildTaskStatus.WAIT -> { │
│ │ Thread.sleep(sleepMills) // 暂无任务，等待 │
│ │ } │
│ │ │
│ │ BuildTaskStatus.END -> break@loop // Job 结束 │
│ │ } │
│ } │
└─────────────────────────────────────────────────────────────────────────────┘
2.3.4 Task 状态流转
┌─────────────────────────────────────────────────────────────────────────────┐
│ Task 状态流转图 │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────┐
│ QUEUE │ ← 初始状态（引擎创建）
│ 排队中 │
└──────┬──────┘
│ 引擎调度到该 Task
▼
┌─────────────┐
│ QUEUE_CACHE │ ← 待领取（Worker 可见）
│ 待执行 │
└──────┬──────┘
│ Worker claimTask 领取
▼
┌─────────────┐
│ RUNNING │ ← 执行中
│ 执行中 │
└──────┬──────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ SUCCEED │ │ FAILED │ │ CANCELED │
│ 成功 │ │ 失败 │ │ 取消 │
└─────────────┘ └─────────────┘ └─────────────┘
特殊状态：
• RETRY：失败重试中
• PAUSE：人工暂停
• SKIP：跳过执行
2.3.5 服务端与 Worker 的通信协议
┌─────────────────────────────────────────────────────────────────────────────┐
│ Worker ↔ Process 通信接口 │
└─────────────────────────────────────────────────────────────────────────────┘
┌──────────────────┬────────────────────────────────────────────────────────┐
│ 接口 │ 说明 │
├──────────────────┼────────────────────────────────────────────────────────┤
│ jobStarted │ Worker 启动后调用，通知服务端构建机已就绪 │
│ │ → 返回 BuildVariables（构建变量、上下文等） │
├──────────────────┼────────────────────────────────────────────────────────┤
│ claimTask │ 领取待执行的 Task │
│ │ → 返回 BuildTask（任务详情）或 WAIT/END 状态 │
├──────────────────┼────────────────────────────────────────────────────────┤
│ completeTask │ 上报 Task 执行结果 │
│ │ → 触发服务端调度下一个 Task │
├──────────────────┼────────────────────────────────────────────────────────┤
│ heartbeat │ 心跳上报，保持连接活跃 │
│ │ → 服务端检测构建机存活状态 │
├──────────────────┼────────────────────────────────────────────────────────┤
│ jobEnd │ Job 执行完毕，Worker 退出前调用 │
│ │ → 触发 stopVM Task 释放资源 │
└──────────────────┴────────────────────────────────────────────────────────┘
API 路径：/api/build/worker/{action}
实现类：BuildJobResource / BuildJobResourceImpl
服务类：EngineVMBuildService
2.4 流水线数据流图
┌─────────────────────────────────────────────────────────────────────────────┐
│ 数据流向 │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────┐
│ Model (JSON) │
│ 流水线编排模型 │
│ Pipeline → Stage → Job → Task │
└─────────────────┬───────────────────┘
│
┌─────────────────▼───────────────────┐
│ T_PIPELINE_RESOURCE │
│ 存储编排模型 │
└─────────────────┬───────────────────┘
│
┌───────────────────────────┼───────────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ T_PIPELINE_ │ │ T_PIPELINE_ │ │ T_PIPELINE_ │
│ BUILD_HISTORY │ │ BUILD_STAGE │ │ BUILD_CONTAINER │
│ 构建历史 │ │ 阶段状态 │ │ Job 状态 │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ T_PIPELINE_ │ │
│ │ BUILD_TASK │◀───────────────┘
│ │ 任务状态 │
│ └────────┬────────┘
│ │
│ ┌────────────────────┼────────────────────┐
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ T_PIPELINE_ │ │ T_PIPELINE_ │ │ T_REPORT │
│ BUILD_VAR │ │ BUILD_DETAIL │ │ 构建报告 │
│ 构建变量 │ │ 构建详情 │ │ (Artifactory) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
三、模块间调用关系
3.1 服务依赖图
┌─────────────────────────────────────────────────────────────────────────────┐
│ 服务依赖关系 │
└─────────────────────────────────────────────────────────────────────────────┘
┌──────────┐
│ Project │ ◀──── 所有服务的基础依赖
│ 项目管理 │
└────┬─────┘
│
┌─────────────────────────┼─────────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Auth │ │ Process │ │ Store │
│ 权限认证 │◀────────────│ 流水线 │────────────▶│ 研发商店 │
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
│ ┌────────────┼────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │Repository│ │ Dispatch │ │ Ticket │ │
│ │ 代码库 │ │ 构建调度 │ │ 凭证管理 │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌──────────┐ │ │
│ │ │Environment│ │ │
│ │ │ 构建机 │ │ │
│ │ └────┬─────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌────────────┐ │ │
│ │ │Agent/Worker│ │ │
│ │ │ 构建执行 │ │ │
│ │ └─────┬──────┘ │ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────┐ │
│ │ 支撑服务 │ │
│ │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐│ │
│ │ │ Log │ │Artif│ │Notif│ │Quali││ │
│ │ │日志 │ │制品 │ │通知 │ │红线 │◀───────┘
│ │ └─────┘ └─────┘ └─────┘ └─────┘│
│ └──────────────────────────────────┘
│ │
│ ▼
│ ┌──────────────┐
└───────────▶│ Metrics │
│ 度量统计 │
└──────────────┘
3.2 典型调用链路
链路1：手动触发构建
Frontend (devops-pipeline)
│
│ POST /api/process/user/builds/{projectId}/{pipelineId}/start
▼
Process (UserBuildResource)
│
├──▶ Auth (ServiceAuthResource)
│ └── 检查 pipeline_execute 权限
│
├──▶ Project (ServiceProjectResource)
│ └── 获取项目信息
│
├──▶ Repository (ServiceRepositoryResource)
│ └── 获取代码库信息
│
├──▶ Ticket (ServiceTicketResource)
│ └── 获取凭证信息
│
├──▶ Store (ServiceAtomResource)
│ └── 校验插件版本
│
└──▶ RabbitMQ
└── 发送 PipelineBuildStartEvent
│
▼
Process (BuildEventDispatcher)
│
└──▶ Dispatch (ServiceDispatchResource)
└── 分配构建机
│
▼
Environment (ServiceNodeResource)
└── 查询可用节点
│
▼
Agent (Ask API)
└── 获取构建任务
│
▼
Worker (Runner)
│
├──▶ Store: 下载插件
├──▶ Ticket: 获取凭证
├──▶ Repository: 拉取代码
├──▶ Artifactory: 上传制品
└──▶ Log: 上报日志
链路2：代码提交触发
Git Server (GitLab/GitHub/工蜂)
│
│ Webhook POST /api/repository/webhooks/{projectId}
▼
Repository (WebhookResource)
│
├──▶ 解析 Webhook 事件
│ └── Push/MR/Tag 等
│
└──▶ Process (ServiceBuildResource)
└── 触发流水线构建
│
└── (后续流程同链路1)
链路3：研发商店插件执行
Worker (MarketAtomTask)
│
├──▶ Store (ServiceMarketAtomResource)
│ └── 获取插件信息和下载地址
│
├──▶ Artifactory (BuildArchiveResource)
│ └── 下载插件安装包
│
├──▶ Ticket (BuildCredentialResource)
│ └── 获取插件所需凭证
│
├──▶ 执行插件脚本
│ └── Python/NodeJS/Go/Java
│
└──▶ Log (BuildLogResource)
└── 上报执行日志
四、核心数据模型关系
4.1 流水线模型 (Model) 结构
Model (流水线模型)
│
├── name: String # 流水线名称
├── desc: String # 描述
├── stages: List<Stage> # 阶段列表
│ │
│ └── Stage (阶段)
│ ├── id: String # 阶段ID (s-xxx)
│ ├── name: String # 阶段名称
│ ├── checkIn: StagePauseCheck # 准入检查
│ ├── checkOut: StagePauseCheck # 准出检查
│ └── containers: List<Container> # Job 列表
│ │
│ └── Container (Job)
│ ├── id: String # Job ID (c-xxx)
│ ├── name: String # Job 名称
│ ├── @type: String # 类型标识
│ │ ├── vmBuild # 需要构建机
│ │ ├── normal # 无编译环境
│ │ └── trigger # 触发器
│ ├── dispatchType: DispatchType # 调度类型
│ ├── mutexGroup: String # 互斥组
│ └── elements: List<Element> # 任务列表
│ │
│ └── Element (Task)
│ ├── id: String # 任务ID (t-xxx)
│ ├── name: String # 任务名称
│ ├── @type: String # 插件类型
│ │ ├── marketBuild # 研发商店插件
│ │ ├── linuxScript # Shell 脚本
│ │ ├── windowsScript # Bat 脚本
│ │ ├── manualReviewUserTask # 人工审核
│ │ └── ...
│ └── data: Map # 插件参数
│
├── triggers: List<Trigger> # 触发器配置
├── params: List<BuildFormProperty> # 启动参数
└── setting: PipelineSetting # 流水线设置
4.2 数据库表关联
┌─────────────────────────────────────────────────────────────────────────────┐
│ 核心表关联关系 │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────┐
│ T_PROJECT │
│ (devops_ci_project)│
└──────────┬──────────┘
│ PROJECT_ID
┌─────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ T_PIPELINE_INFO │ │ T_REPOSITORY │ │ T_AUTH_RESOURCE│
│ 流水线信息 │ │ 代码库 │ │ 权限资源 │
└────────┬────────┘ └─────────────────┘ └─────────────────┘
│ PIPELINE_ID
│
┌────┴────┬─────────────────┬─────────────────┐
│ │ │ │
▼ ▼ ▼ ▼
┌────────┐ ┌────────────┐ ┌────────────┐ ┌────────────────┐
│RESOURCE│ │ SETTING │ │ SUMMARY │ │ BUILD_HISTORY │
│编排模型│ │ 配置 │ │ 摘要 │ │ 构建历史 │
└────────┘ └────────────┘ └────────────┘ └───────┬────────┘
│ BUILD_ID
│
┌───────────────────────────────────────┼───────────────┐
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ ┌─────────────┐
│ BUILD_STAGE │ │ BUILD_CONTAINER │ │ BUILD_TASK │ │ BUILD_VAR │
│ 阶段状态 │ │ Job 状态 │ │ 任务状态 │ │ 构建变量 │
└─────────────────┘ └─────────────────┘ └─────────────┘ └─────────────┘
五、事件驱动机制
5.1 核心事件流
┌─────────────────────────────────────────────────────────────────────────────┐
│ 事件驱动流程 │
└─────────────────────────────────────────────────────────────────────────────┘
构建启动
│
▼
PipelineBuildStartEvent ──────────────────────────────────────────────────────┐
│ │
▼ │
┌───────────────────┐ │
│ StageControl │ │
│ 处理 Stage 事件 │ │
└─────────┬─────────┘ │
│ │
▼ │
PipelineBuildContainerEvent ──────────────────────────────────────────────────┤
│ │
▼ │
┌───────────────────┐ │
│ ContainerControl │ │
│ 处理 Job 事件 │ │
└─────────┬─────────┘ │
│ │
├──▶ 需要构建机: 发送 PipelineAgentStartupEvent │
│ │ │
│ ▼ │
│ Dispatch 分配构建机 │
│ │ │
│ ▼ │
│ Agent 执行 → Worker 执行任务 │
│ │ │
│ ▼ │
│ PipelineBuildTaskFinishEvent ◀──────────────────────────────────┤
│ │ │
│ ▼ │
│ ┌───────────────────┐ │
│ │ TaskControl │ │
│ │ 处理任务完成事件 │ │
│ └─────────┬─────────┘ │
│ │ │
│ ▼ │
│ 所有任务完成? ──▶ PipelineBuildContainerEvent (完成) │
│ │ │
│ ▼ │
│ 所有 Job 完成? │
│ │ │
│ ▼ │
│ PipelineBuildStageEvent (完成) │
│ │ │
│ ▼ │
│ ┌───────────────────┐ │
│ │ StageControl │ │
│ │ 检查下一个 Stage │ │
│ └─────────┬─────────┘ │
│ │ │
│ ├──▶ 有下一个 Stage: 循环处理 │
│ │ │
│ └──▶ 无: PipelineBuildFinishEvent │
│ │ │
│ ▼ │
│ ┌───────────────────┐ │
│ │ 构建完成处理 │ │
│ │ • 更新状态 │ │
│ │ • 发送通知 │ │
│ │ • 更新统计 │ │
│ └───────────────────┘ │
│ │
└──▶ 无编译环境: 直接执行任务 ───────────────────────────────────────┘
5.2 事件类型汇总
| 事件类型 |
触发时机 |
处理器 |
PipelineBuildStartEvent |
构建启动 |
StageControl |
PipelineBuildStageEvent |
Stage 状态变更 |
StageControl |
PipelineBuildContainerEvent |
Job 状态变更 |
ContainerControl |
PipelineBuildTaskFinishEvent |
任务完成 |
TaskControl |
PipelineBuildFinishEvent |
构建完成 |
BuildFinishListener |
PipelineBuildCancelEvent |
构建取消 |
CancelControl |
PipelineAgentStartupEvent |
构建机启动 |
DispatchListener |
PipelineAgentShutdownEvent |
构建机释放 |
DispatchListener |
5.3 事件驱动的非阻塞机制
核心设计：引擎发出事件后不阻塞等待，继续处理其他事件。
┌─────────────────────────────────────────────────────────────────────────────┐
│ 非阻塞事件处理机制 │
└─────────────────────────────────────────────────────────────────────────────┘
场景：Job 需要等待构建机就绪（可能需要几秒到几分钟）
传统阻塞方式（❌ 不采用）：
┌──────────────────────────────────────────────────────────────────────────┐
│ Process 引擎线程 │
│ │ │
│ ├── 发送调度请求 │
│ ├── 阻塞等待构建机就绪... ← 线程被占用，无法处理其他任务 │
│ ├── 构建机就绪 │
│ └── 继续执行 │
└──────────────────────────────────────────────────────────────────────────┘
BK-CI 事件驱动方式（✅ 采用）：
┌──────────────────────────────────────────────────────────────────────────┐
│ Process 引擎 │
│ │ │
│ ├── 发送调度请求（PipelineAgentStartupEvent） │
│ ├── 立即返回，处理其他事件（其他流水线、其他 Job） │
│ │ │
│ ... 时间流逝，构建机启动中 ... │
│ │ │
│ Worker 启动后 │
│ ├── 调用 jobStarted API │
│ ├── 服务端发送 PipelineBuildContainerEvent │
│ │ │
│ 引擎收到事件 │
│ └── 继续执行该 Job 的后续 Task │
└──────────────────────────────────────────────────────────────────────────┘
优势：
• 单个引擎实例可并发处理大量构建
• 不会因为某个构建机慢而阻塞其他构建
• 资源利用率高
5.4 关键事件触发点源码位置
| 事件 |
触发位置 |
说明 |
PipelineBuildStartEvent |
PipelineRuntimeService.sendBuildStartEvent() |
构建启动时发送 |
PipelineBuildContainerEvent |
EngineVMBuildService.setStartUpVMStatus() |
构建机就绪后发送 |
PipelineBuildContainerEvent |
PipelineBuildTaskService.finishTask() |
Task 完成后发送 |
PipelineBuildStageEvent |
ContainerControl |
所有 Job 完成后发送 |
PipelineBuildFinishEvent |
StageControl |
所有 Stage 完成后发送 |
六、跨模块协作场景
6.1 场景：创建并执行一条完整流水线
┌─────────────────────────────────────────────────────────────────────────────┐
│ 步骤 1: 创建项目 │
├─────────────────────────────────────────────────────────────────────────────┤
│ 模块: Project + Auth │
│ 操作: │
│ • Project: 创建项目记录 (T_PROJECT) │
│ • Auth: 创建项目权限组，授予创建者管理员权限 │
│ • Project: 初始化项目配额、路由规则 │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 步骤 2: 关联代码库 │
├─────────────────────────────────────────────────────────────────────────────┤
│ 模块: Repository + Ticket │
│ 操作: │
│ • Ticket: 创建 Git 凭证 (用户名密码/SSH/Token) │
│ • Repository: 关联代码库，配置 Webhook │
│ • Repository: 验证代码库连通性 │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 步骤 3: 安装构建机 │
├─────────────────────────────────────────────────────────────────────────────┤
│ 模块: Environment │
│ 操作: │
│ • 创建节点记录 (T_NODE) │
│ • 生成 Agent 安装脚本 │
│ • Agent 安装并上报状态 (T_ENVIRONMENT_THIRDPARTY_AGENT) │
│ • 配置节点环境变量、并行任务数 │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 步骤 4: 安装插件 │
├─────────────────────────────────────────────────────────────────────────────┤
│ 模块: Store │
│ 操作: │
│ • 浏览研发商店，选择插件 │
│ • 安装插件到项目 (T_STORE_PROJECT_REL) │
│ • 插件下载量统计更新 │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 步骤 5: 创建流水线 │
├─────────────────────────────────────────────────────────────────────────────┤
│ 模块: Process + Store + Repository + Auth │
│ 操作: │
│ • 前端编排流水线 Model │
│ • Process: 校验插件 (调用 Store) │
│ • Process: 校验代码库 (调用 Repository) │
│ • Process: 保存流水线 (T_PIPELINE_INFO, T_PIPELINE_RESOURCE) │
│ • Auth: 创建流水线权限资源 │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 步骤 6: 执行流水线 │
├─────────────────────────────────────────────────────────────────────────────┤
│ 模块: 全部模块协作 │
│ 操作: │
│ • Process: 创建构建记录，发送启动事件 │
│ • Quality: 检查准入红线 │
│ • Dispatch: 分配构建机 │
│ • Environment: 查询可用节点 │
│ • Agent: 接收任务，启动 Worker │
│ • Worker: 执行任务 │
│ - Store: 下载插件 │
│ - Ticket: 获取凭证 │
│ - Repository: 拉取代码 │
│ - Artifactory: 上传制品 │
│ - Log: 上报日志 │
│ • Quality: 检查准出红线 │
│ • Notify: 发送构建通知 │
│ • Metrics: 更新统计数据 │
│ • WebSocket: 实时推送状态 │
└─────────────────────────────────────────────────────────────────────────────┘
6.2 场景：插件开发与发布
┌─────────────────────────────────────────────────────────────────────────────┐
│ 阶段 1: 插件开发 │
├─────────────────────────────────────────────────────────────────────────────┤
│ 开发者本地: │
│ • 使用 SDK 开发插件 (Python/NodeJS/Go/Java) │
│ • 编写 task.json 定义输入输出 │
│ • 本地测试 │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 阶段 2: 插件上架 │
├─────────────────────────────────────────────────────────────────────────────┤
│ 模块: Store + Artifactory │
│ 操作: │
│ • Store: 创建插件记录 (T_ATOM) │
│ • Artifactory: 上传插件包 │
│ • Store: 提交审核 │
│ • Store: 审核通过，发布到商店 │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 阶段 3: 插件使用 │
├─────────────────────────────────────────────────────────────────────────────┤
│ 模块: Store + Process + Worker │
│ 操作: │
│ • Store: 用户安装插件到项目 │
│ • Process: 流水线中使用插件 │
│ • Worker (MarketAtomTask): │
│ - 从 Store 获取插件信息 │
│ - 从 Artifactory 下载插件包 │
│ - 准备输入参数 │
│ - 执行插件脚本 │
│ - 解析输出结果 │
│ • Store: 更新使用统计 │
└─────────────────────────────────────────────────────────────────────────────┘
6.3 场景：权限控制流程
┌─────────────────────────────────────────────────────────────────────────────┐
│ 权限检查链路 │
└─────────────────────────────────────────────────────────────────────────────┘
用户请求
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Gateway (OpenResty) │
│ • 验证 Token/Session │
│ • 获取用户信息 │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 业务服务 (如 Process) │
│ • 调用 Auth 服务检查权限 │
│ │ │
│ └──▶ Auth (RbacPermissionService) │
│ │ │
│ ├── 1. 检查用户是否为项目成员 │
│ │ └── T_AUTH_RESOURCE_GROUP_MEMBER │
│ │ │
│ ├── 2. 获取用户所属用户组 │
│ │ └── T_AUTH_RESOURCE_GROUP │
│ │ │
│ ├── 3. 获取用户组权限 │
│ │ └── T_AUTH_ACTION │
│ │ │
│ └── 4. 判断是否有目标操作权限 │
│ └── 返回 true/false │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 权限不足时的处理 │
│ • 返回 403 错误 │
│ • 前端展示权限申请入口 │
│ • 用户可申请加入用户组 │
└─────────────────────────────────────────────────────────────────────────────┘
七、技术栈与工具链
7.1 后端技术栈
| 层次 |
技术 |
说明 |
| 语言 |
Kotlin/Java |
主要业务代码 |
| 框架 |
Spring Boot 3 |
微服务基础框架 |
| 构建 |
Gradle Kotlin DSL |
依赖管理和构建 |
| 数据库 |
MySQL/MariaDB + JOOQ |
关系型数据存储 |
| 缓存 |
Redis |
缓存和分布式锁 |
| 消息 |
RabbitMQ |
事件驱动消息队列 |
| 搜索 |
ElasticSearch |
日志存储和检索 |
| 服务发现 |
Consul |
微服务注册发现 |
| 静态分析 |
Detekt |
Kotlin 代码检查 |
7.2 前端技术栈
| 层次 |
技术 |
说明 |
| 框架 |
Vue 2.7 |
前端框架 |
| 状态管理 |
Vuex 3.6 |
全局状态 |
| 路由 |
Vue Router 3.6 |
前端路由 |
| UI 组件 |
bk-magic-vue |
蓝鲸 MagicBox |
| 样式 |
Sass/SCSS |
CSS 预处理 |
| 打包 |
Webpack 5 |
模块打包 |
| 代码检查 |
ESLint |
代码规范检查 |
7.3 Agent 技术栈
| 层次 |
技术 |
说明 |
| 语言 |
Go 1.19+ |
Agent 主程序 |
| 进程管理 |
Daemon + Agent |
双进程架构 |
| 通信 |
HTTP/HTTPS |
与后端服务通信 |
| 数据采集 |
Telegraf |
构建机指标采集 |
7.4 Worker 技术栈
| 层次 |
技术 |
说明 |
| 语言 |
Kotlin |
Worker 主程序 |
| 运行时 |
JVM |
Java 虚拟机 |
| 插件执行 |
多语言 |
Python/NodeJS/Go/Java |
八、开发指南索引
8.1 按模块查找 Skill
| 模块 |
Skill 编号 |
描述 |
| 全局架构 |
00 |
本文档 |
| 后端开发 |
01 |
后端微服务开发规范 |
| API 设计 |
02 |
API 接口设计规范 |
| 单元测试 |
03 |
单元测试编写指南 |
| 前端开发 |
04 |
Vue 前端开发规范 |
| Agent 开发 |
05 |
Go Agent 开发指南 |
| 数据库 |
06, 44 |
数据库脚本管理、表设计规范 |
| Git 提交 |
07 |
提交规范 |
| 事件驱动 |
08 |
事件驱动架构 |
| 设计模式 |
09, 27 |
责任链模式、设计模式实践 |
| 分布式锁 |
10 |
分布式锁使用 |
| 服务调用 |
11 |
服务间调用规范 |
| 监控 |
12 |
性能监控 |
| 重试 |
13 |
重试机制 |
| 国际化 |
14 |
i18n 和日志 |
| 参数校验 |
15 |
参数验证 |
| 定时任务 |
16 |
定时任务开发 |
| AOP |
17 |
切面编程 |
| 条件配置 |
18 |
条件配置 |
| JWT |
19 |
JWT 安全认证 |
| 审计日志 |
20 |
审计日志 |
| 表达式 |
21 |
表达式解析器 |
| 分片 |
23 |
数据库分片 |
| OAuth2 |
24 |
OAuth2 认证 |
| 变量扩展 |
26 |
流水线变量扩展 |
| 流水线模型 |
28 |
Pipeline Model 架构 |
| Process |
29 系列 |
流水线核心模块 |
| Auth |
30 |
权限认证模块 |
| Project |
31 |
项目管理模块 |
| Repository |
32 |
代码库模块 |
| Store |
33 |
研发商店模块 |
| Artifactory |
34 |
制品库模块 |
| Dispatch |
35 |
构建调度模块 |
| Environment |
36 |
构建机环境模块 |
| Ticket |
37 |
凭证管理模块 |
| Notify |
39 |
通知服务模块 |
| OpenAPI |
41 |
开放接口模块 |
| Worker |
42 |
构建执行器模块 |
| Agent |
43 |
构建机代理模块 |
8.2 按场景查找
| 场景 |
涉及 Skill |
| 新增流水线功能 |
28, 29 系列, 08 |
| 开发新插件 |
33, 42 |
| 修改权限逻辑 |
30, 24 |
| 优化构建调度 |
35, 36, 43 |
| 添加新通知渠道 |
39 |
| 扩展 API 接口 |
02, 41 |
| 数据库表变更 |
06, 44 |
| 前端页面开发 |
04 |
| Agent 功能扩展 |
05, 43 |
九、总结
BK-CI 是一个以流水线为核心的 CI/CD 平台，通过 16 个后端微服务、14 个前端应用和 Go 构建代理的协作，实现了从代码提交到制品交付的完整自动化流程。
核心理解要点
- Process 是核心 - 流水线编排、构建调度、状态管理都在这里
- 事件驱动 - 通过 RabbitMQ 实现模块间解耦和异步处理
- 分层架构 - 每个服务都有 api/biz/model/boot 四层结构
- 双层构建 - Agent(Go) 负责进程管理，Worker(Kotlin) 负责任务执行
- 权限统一 - Auth 模块基于 RBAC 统一管理所有资源权限
Job/Task 执行机制要点
- 启动构建机是 Task - 每个 vmBuild 类型的 Job 会自动生成
startVM、end、stopVM 系统 Task
- Worker 采用 Pull 模式 - Worker 主动调用
claimTask 领取任务，而非服务端推送
- 非阻塞等待 - 引擎发出调度请求后不阻塞，通过事件回调继续执行
- Task 完成触发事件 - Worker 调用
completeTask 后，服务端发送 PipelineBuildContainerEvent 调度下一个 Task
关键代码入口
| 功能 |
代码位置 |
| Worker 主循环 |
Runner.loopPickup() |
| 领取任务 |
EngineVMBuildService.buildClaimTask() |
| 上报结果 |
EngineVMBuildService.buildCompleteTask() |
| 构建机就绪通知 |
EngineVMBuildService.setStartUpVMStatus() |
| Task 完成处理 |
PipelineBuildTaskService.finishTask() |
| 容器事件处理 |
ContainerControl.handle() |
掌握了这个全局视图，就能理解 BK-CI 任何功能的实现位置和模块协作方式。