BK-CI 全局架构指南
<!-- ═══════════════════════════════════════════════════════════════════════════ 📚 Skill 导航索引（放在最前面 - 快速定位相关 Skill） ═══════════════════════════════════════════════════════════════════════════ -->📚 Skill 导航索引
说明: 本文档是全局架构总览，按需深入阅读具体模块的 Skill。
🗂️ 按类别查找 (31 个 Skill)
1️⃣ 全局架构 (1)
00-bkci-global-architecture(本文档) - 系统全局架构、模块协作、执行流程
2️⃣ 通用技术实践 (3)
common-technical-practices- 框架级实践：AOP、分布式锁、重试、监控、定时任务、审计日志microservice-infrastructure- 微服务基础：条件配置、事件驱动、服务调用、国际化、日志utility-components- 工具级组件：JWT、表达式解析、线程池、责任链
3️⃣ 后端开发 (3)
backend-microservice-development- 后端微服务开发规范、Controller/Service/Dao 模式api-interface-design- RESTful API 设计、接口规范unit-testing- 单元测试编写规范
4️⃣ 前端开发 (1)
frontend-vue-development- Vue 前端开发规范、组件设计
5️⃣ 数据库 (1)
database-design- 数据库表设计、字段规范、索引优化、DDL 脚本管理
6️⃣ Pipeline 流水线系列 (4)
pipeline-model-architecture- Pipeline 模型架构：Stage/Container/Element 结构pipeline-variable-management- 流水线变量管理：变量生命周期、字段扩展pipeline-template-module- 流水线模板模块：模板定义、实例化、版本管理pipeline-plugin-development- 流水线插件开发：插件规范、任务执行
7️⃣ 核心模块架构 (9)
process-module-architecture- Process 流水线模块（核心）：API/Service/Engine/Dao 四层架构auth-module-architecture- Auth 权限认证模块：RBAC、权限校验project-module-architecture- Project 项目管理模块：项目创建、配置、成员管理repository-module-architecture- Repository 代码库模块：Git/SVN 集成、Webhookstore-module-architecture- Store 研发商店模块：插件/模板上架、版本管理artifactory-module-architecture- Artifactory 制品库模块：制品存储、版本管理dispatch-module-architecture- Dispatch 构建调度模块：构建机分配、调度策略worker-module-architecture- Worker 任务执行器模块：任务领取、插件执行agent-module-architecture- Agent 构建机代理模块 (Go)：进程管理、日志上报
8️⃣ 支撑模块架构 (1)
supporting-modules-architecture- 支撑模块总览：- Ticket (凭证管理)
- Environment (构建机环境)
- Notify (通知服务)
- Log (构建日志)
- Quality (质量红线)
- OpenAPI (开放接口)
9️⃣ 设计模式 (1)
design-patterns- 设计模式实践：工厂、策略、观察者、责任链等
🔟 其他工具与规范 (7)
git-commit-specification- Git 提交规范：Commit Message 格式managing-devops-pipeline- 蓝盾流水线管理：MCP 工具使用指南business-knowledge-workflow- 业务知识获取流程：如何获取领域知识permission-model-change-guide- 权限模型变更指南：v3 → v4 迁移go-agent-development- Go Agent 开发规范：Go 编码规范、构建机开发yaml-pipeline-transfer- YAML 流水线转换：v2.0 → v3.0 迁移skill-writer- Skill 编写指南：如何编写高质量 Skill
🎯 按场景快速查找
| 场景 | 涉及 Skill (按优先级排序) |
|------|---------------------------|
| 新增流水线功能 | pipeline-model-architecture, process-module-architecture, pipeline-variable-management, microservice-infrastructure |
| 开发新插件 | store-module-architecture, worker-module-architecture, pipeline-plugin-development |
| 修改权限逻辑 | auth-module-architecture, common-technical-practices |
| 优化构建调度 | dispatch-module-architecture, agent-module-architecture, supporting-modules-architecture |
| 数据库表变更 | database-design |
| 添加 API 接口 | api-interface-design, backend-microservice-development |
| 前端页面开发 | frontend-vue-development |
| 流水线变量扩展 | pipeline-variable-management, utility-components (表达式解析) |
| 实现分布式锁 | common-technical-practices |
| 添加通知功能 | supporting-modules-architecture (Notify 模块) |
| 凭证管理 | supporting-modules-architecture (Ticket 模块) |
| 质量红线 | supporting-modules-architecture (Quality 模块) |
| 日志查询 | supporting-modules-architecture (Log 模块) |
| OAuth2 认证 | auth-module-architecture, utility-components (JWT) |
🧭 学习路径推荐
新手入门路径
1. 00-bkci-global-architecture (本文档) - 建立全局视图
↓
2. pipeline-model-architecture - 理解流水线模型
↓
3. process-module-architecture - 深入核心模块
↓
4. backend-microservice-development - 掌握开发规范
进阶开发路径
根据开发任务选择：
- 插件开发 → store + worker + pipeline-plugin-development
- 权限功能 → auth + common-technical-practices
- 调度优化 → dispatch + agent + supporting-modules-architecture
- 变量扩展 → pipeline-variable-management + utility-components
<!-- ═══════════════════════════════════════════════════════════════════════════ 🚀 快速参考区（放在最前面 - 解决 Lost-in-Middle 问题） ═══════════════════════════════════════════════════════════════════════════ -->
Quick Reference
系统分层（5 层）
用户层 → 网关层 → 微服务层 → 构建机层 → 资源层
核心模块速查
| 模块 | 职责 | 深入阅读 |
|------|------|----------|
| Process | 流水线编排与执行（核心） | process-module-architecture |
| Auth | 权限认证 RBAC | auth-module-architecture |
| Dispatch | 构建机分配调度 | dispatch-module-architecture |
| Store | 研发商店/插件管理 | store-module-architecture |
| Worker | 任务执行器 | worker-module-architecture |
| Agent | 构建机代理 (Go) | agent-module-architecture |
流水线执行核心流程
触发 → Process引擎 → Dispatch分配 → Agent领取 → Worker执行 → 状态回传
关键代码入口
| 功能 | 入口类 |
|------|--------|
| 手动构建 | PipelineBuildFacadeService.buildManualStartup() |
| 引擎调度 | StageControl / ContainerControl / TaskControl |
| Worker 主循环 | Runner.loopPickup() |
| 任务完成处理 | PipelineBuildTaskService.finishTask() |
When to Use ✅
- 首次接触 BK-CI 项目，需要建立全局视图
- 进行跨模块开发，需要理解模块间协作
- 调试复杂问题，需要追踪完整调用链路
- 规划架构设计或重构方案
- 不确定某个功能应该在哪个模块实现
When NOT to Use ❌
- 只修改单个模块内部逻辑（直接阅读对应模块 Skill）
- 简单的 Bug 修复（不涉及跨模块调用）
- 前端 UI 调整（阅读
frontend-vue-development） - 数据库表变更（阅读
database-design）
一、系统分层架构
┌─────────────────────────────────────────────────────────────────────────────┐
│ 用户层 (User Layer) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Web 前端 │ │ OpenAPI │ │ Webhook │ │ 第三方系统集成 │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │
└─────────┼────────────────┼────────────────┼────────────────────┼────────────┘
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 网关层 (Gateway Layer) │
│ OpenResty (Nginx + Lua) │
│ • 路由转发 • 身份认证 • 限流熔断 • 服务发现(Consul) │
└─────────────────────────────────────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 微服务层 (Microservice Layer) │
│ 核心: Project | Process | Auth | Store | Repository │
│ 调度: Dispatch | Environment | Ticket │
│ 支撑: Artifactory | Log | Notify | Quality | Metrics │
│ 开放: OpenAPI | WebSocket │
└─────────────────────────────────────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 构建机层 (Build Machine Layer) │
│ Agent (Go) ──▶ Worker (Kotlin) │
│ 进程守护 任务执行、插件运行、日志上报 │
└─────────────────────────────────────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 资源层 (Resource Layer) │
│ MySQL | Redis | RabbitMQ | ElasticSearch | 文件存储 │
└─────────────────────────────────────────────────────────────────────────────┘
模块职责速查表
| 模块 | 核心职责 | 关键能力 | |------|----------|----------| | Project | 项目管理 | 项目创建、成员管理、服务开通、路由分片 | | Process | 流水线编排与执行 | 模型定义、构建调度、事件驱动、状态管理 | | Auth | 权限认证 | RBAC、资源授权、用户组、OAuth2 | | Store | 研发商店 | 插件管理、模板市场、版本发布、统计分析 | | Repository | 代码库管理 | Git/SVN/P4 对接、Webhook、PAC | | Dispatch | 构建调度 | 构建机分配、Docker 调度、配额管理 | | Environment | 构建机环境 | 节点管理、Agent 安装、环境变量 | | Ticket | 凭证管理 | 密码/SSH/Token 存储、加密解密 | | Artifactory | 制品库 | 文件存储、版本管理、跨项目共享 | | Log | 日志服务 | 构建日志收集、存储、检索 | | Notify | 通知服务 | 邮件/企微/RTX 通知 | | Quality | 质量红线 | 指标定义、准入准出、拦截规则 | | Agent | 构建机代理 | 进程管理、任务调度、自动升级 | | Worker | 任务执行器 | 插件执行、脚本运行、日志上报 |
二、流水线执行全流程（核心）
这是 BK-CI 最核心的流程，涉及几乎所有模块的协作。
2.1 执行流程总览图
用户触发
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ PipelineBuild │────▶│ PipelineBuild │────▶│ PipelineRuntime │
│ FacadeService │ │ Service │ │ Service │
│ (权限校验) │ │ (拦截器链) │ │ (创建记录) │
└─────────────────┘ └─────────────────┘ └────────┬────────┘
│
▼
┌─────────────────────┐
│ PipelineBuildStart │
│ Event → RabbitMQ │
└──────────┬──────────┘
│
┌────────────────────────────────────────────────────┘
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ BuildStart │────▶│ StageControl │────▶│ Container │
│ Control │ │ (责任链) │ │ Control │
└─────────────────┘ └─────────────────┘ └────────┬────────┘
│
┌───────────────────────────┤
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Dispatch │ │ TaskControl │
│ (构建机分配) │ │ (引擎侧Task) │
└────────┬────────┘ └─────────────────┘
▼
┌─────────────────┐
│ Agent (Go) │
│ (领取任务) │
└────────┬────────┘
▼
┌─────────────────┐
│ Worker (Kotlin) │
│ (执行Task) │
└────────┬────────┘
│ completeTask API
▼
┌─────────────────┐
│ 状态逐层回传 │
│ Task→Job→Stage │
│ →Pipeline │
└────────┬────────┘
▼
┌─────────────────┐
│ BuildEndControl │
│ (完成处理) │
└────────┬────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Notify │ │ Metrics │ │ WebSocket │
└─────────────┘ └─────────────┘ └─────────────┘
2.2 四个阶段概要
| 阶段 | 核心动作 | 深入阅读 |
|---|---|---|
| 触发 | 手动/定时/Webhook/OpenAPI → PipelineBuildFacadeService.buildManualStartup() | process-module-architecture |
| 引擎调度 | Stage → Job → Task 责任链编排 | 3-engine-control.md 第三节 |
| 任务执行 | Agent(Go) 领取构建 → 拉起 Worker(Kotlin) → 循环 claimTask/completeTask | agent-module-architecture 3.2~3.3 节, worker-module-architecture Runner 节 |
| 状态回传 | completeTask → PipelineBuildContainerEvent → 逐层收敛到 BuildEnd | 3-engine-control.md 3.4.2 节 |
Task 的 5 种角色分类、引擎与 Worker 的事件驱动协作机制，详见
3-engine-control.md3.4 节。
三、引擎-调度-构建机 完整交互流程
本节将 Process 引擎、Dispatch 调度、Agent/Worker、BuildLess 容器池的完整交互串联起来， 覆盖从"用户触发构建"到"Job 完成"的全链路。
3.1 构建机环境（第三方/DevCloud/Docker）全链路时序
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ 用户/ │ │ Process │ │ RabbitMQ │ │ Dispatch │ │ Agent │ │ Worker │
│ 触发器 │ │ 引擎 │ │ │ │ 服务 │ │ (Go) │ │ (Kotlin) │
└────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │ │ │ │
① │─ 触发构建 ──>│ │ │ │ │
│ │ │ │ │ │
│ ┌────┴────────────────────────────────────────────────────────┐ │
│ │ ② 引擎编排阶段 │ │
│ │ BuildStartControl → StageControl → ContainerControl │ │
│ │ → StartActionTaskContainerCmd 选出 startVM-{seq} 任务 │ │
│ │ → TaskControl 执行 DispatchVMStartupTaskAtom │ │
│ └────┬────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
│ │── ③ dispatch(PipelineAgentStartupEvent) ──>│ │
│ │ │ │ │ │
│ │ │── ④ 消费 ──>│ │ │
│ │ │ 事件 │ │ │
│ │ │ │ │ │
│ │ │ │─ ⑤ 选择构建资源 ─> │
│ │ │ │ (IP/容器/VM)│ │
│ │ │ │ │ │
│ │ │ │── ⑥ 启动 ──>│ │
│ │ │ │ Worker 进程 │ │
│ │ │ │ │──── ⑦ ────>│
│ │ │ │ │ 拉起Worker │
│ │ │ │ │ │
│ ┌────────────────────────────────────────────────────────────────┤
│ │ ⑧ Worker 启动流程 │
│ │ EngineService.setStarted() → 上报启动，获取 BuildVariables │
│ │ 对应服务端：EngineVMBuildService.buildVMStarted() │
│ │ → 校验构建状态 │
│ │ → setStartUpVMStatus(SUCCEED) 改 startVM 任务为成功 │
│ │ → 发送 PipelineBuildContainerEvent 唤醒引擎 │
│ │ → 启动心跳监听 │
│ │ → 返回 BuildVariables（变量、超时、环境等） │
│ └────────────────────────────────────────────────────────────────┤
│ │ │ │ │ │
│ ┌────┴────────────────────────────────────────────────────────┐ │
│ │ ⑨ 引擎被唤醒，编排第一个用户插件任务 │ │
│ │ ContainerControl → StartActionTaskContainerCmd │ │
│ │ → 选出第一个插件任务 │ │
│ │ → updateTaskStatus(QUEUE_CACHE) │ │
│ │ → TaskControl 发现 taskAtom 为空，直接 return │ │
│ │ → 引擎停住，等待回调 │ │
│ └────┬────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
│ │ │ │ │ ┌────┤
│ │ │ │ │ │ ⑩ │
│ │ │ │ │ │循环│
│ │<─────────── claimTask（轮询）────────────────────────│领取│
│ │ │ │ │ │任务│
│ │──── 返回 BuildTask(DO) ────────────────────────────>│ │
│ │ │ │ │ │ │
│ │ │ │ │ │执行│
│ │ │ │ │ │插件│
│ │ │ │ │ │ │
│ │<─────────── completeTask(result) ──────────────────│ │
│ │ │ │ │ │ │
│ ┌────┴────────────────────────────────────────────────┐ │ │
│ │ ⑪ 引擎被唤醒 │ │ │
│ │ completeClaimBuildTask() │ │ │
│ │ → updateTaskStatus(SUCCEED/FAILED) │ │ │
│ │ → dispatch(PipelineBuildContainerEvent) │ │ │
│ │ → 引擎编排下一个任务 → QUEUE_CACHE → 再次停住 │ │ │
│ └────┬────────────────────────────────────────────────┘ │ │
│ │ │ │ │ │ │
│ │ ... 重复 ⑩⑪ 直到所有插件任务完成 ... │ │
│ │ │ │ │ └────┤
│ │ │ │ │ │
│ ┌────┴────────────────────────────────────────────────────────┐ │
│ │ ⑫ Job 结束阶段 │ │
│ │ Worker 领到 end-{seq} 任务 → 返回 BuildTaskStatus.END │ │
│ │ Worker 调用 EngineService.endBuild() → finishWorker() │ │
│ │ 引擎执行 stopVM-{seq} │ │
│ │ → DispatchVMShutdownTaskAtom │ │
│ │ → 发送 PipelineAgentShutdownEvent 给 Dispatch 回收资源 │ │
│ │ Job 完成 → Stage 完成检查 → 下一个 Stage 或 BuildEnd │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
3.2 无编译环境（BuildLess）全链路时序
BuildLess 与普通构建机的关键差异在于资源准备阶段： 不走 Agent，改走容器池 + Redis 任务队列认领。
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Process │ │ RabbitMQ │ │ Dispatch │ │ BuildLess│ │ Worker │
│ 引擎 │ │ │ │ (docker) │ │ 容器池 │ │ (容器内) │
└────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │ │ │
① │ startVM 任务执行 │ │ │
│ DispatchBuildLessDockerStartupTaskAtom │ │
│ 返回 CALL_WAITING（注意：不是 RUNNING） │ │
│ │ │ │ │
② │── dispatch(PipelineBuildLessStartupEvent) ─>│ │
│ │ │ │ │
│ │── ③ 消费 ──>│ │ │
│ │ │ │ │
│ │ │─ ④ 配额检查 ─> │
│ │ │ checkAndAddRunningJob │
│ │ │ │ │
│ │ │─ ⑤ HTTP ───>│ │
│ │ │ start() │ │
│ │ │ │ │
│ │ │ │─ ⑥ ────────>│
│ │ │ ContainerPoolExecutor │
│ │ │ .execute() │
│ │ │ │ │
│ │ │ ├── 拒绝策略检查 │
│ │ │ │ (ABORT/FOLLOW/JUMP) │
│ │ │ │ │
│ │ │ └── LPUSH 任务入队 │
│ │ │ Redis ready_task │
│ │ │ │ │
│ │ │ │ ⑦ 容器轮询 │
│ │ │ │<── RPOP ────│
│ │ │ │ claimTask │
│ │ │ │ │
│ │ │ │── 返回 ────>│
│ │ │ │ BuildLessTask│
│ │ │ │ │
│ │ │ │ ┌────┤
│ │ │ │ │ ⑧ │
│<──────────── setStarted / buildVMStarted ──────────│启动│
│ │ │ │ │ │
│── 返回 BuildVariables ────────────────────────────>│ │
│ │ │ │ │ │
│<──────────── claimTask ────────────────────────────│领取│
│── 返回 BuildTask(DO) ─────────────────────────────>│执行│
│ │ │ │ │ │
│<──────────── completeTask ─────────────────────────│ │
│ 唤醒引擎，编排下一个任务 │ │
│ │ │ │ │ │
│ ... 重复领取/完成直到所有插件任务结束 ... │ │
│ │ │ │ └────┤
│ │ │ │ │
⑨ │ stopVM 任务执行 │ │ │
│ DispatchBuildLessDockerShutdownTaskAtom │ │
│── dispatch(PipelineBuildLessShutdownEvent)─> │
│ │ │ │ │
│ │ │─ 回收配额 ──>│ │
│ │ │ removeRunningJob │
│ │ │ │─ 销毁容器 ──>│
│ │ │ │ │
3.3 两种环境的关键差异对比
| 对比项 | 构建机环境 | 无编译环境（BuildLess） |
|---|---|---|
| 启动原子 | DispatchVMStartupTaskAtom | DispatchBuildLessDockerStartupTaskAtom |
| 启动事件 | PipelineAgentStartupEvent | PipelineBuildLessStartupEvent |
| 容器参数 | VMBuildContainer | NormalContainer |
| 启动返回值 | BuildStatus.RUNNING | BuildStatus.CALL_WAITING |
| 资源准备 | Dispatch 选 Agent/VM → Agent 拉起 Worker | Dispatch → BuildLess 容器池 → Redis 队列认领 |
| Worker 来源 | Agent(Go) 拉起 Worker JAR 进程 | 容器内预装 Worker，从 Redis 认领任务后启动 |
| 任务认领 | Worker 直接 claimTask 轮询 Process | 容器先从 BuildLess Redis 队列 RPOP 认领构建，再 claimTask 领插件 |
| 关闭事件 | PipelineAgentShutdownEvent | PipelineBuildLessShutdownEvent |
| 资源回收 | Dispatch 通知 Agent 停止/销毁容器 | 容器即用即销 + removeRunningJob 回收配额 |
| 启动耗时 | 5~60 秒（取决于 VM/容器类型） | < 1 秒（容器池预热） |
Task 的 5 种角色分类和 TaskControl 分流全景，详见
3-engine-control.md3.4.1 节。 Worker 主循环（Runner.kt）的完整通信链路，详见worker-module-architectureRunner 节。
3.4 状态流转总览
一个 Job 内 task 的完整状态流转：
引擎编排 Worker 领取 Worker 完成
│ │ │
┌────────┐ ┌───────┴──────┐ ┌───────────┴─────────┐ ┌───────┴───────┐
│ QUEUE │───>│ QUEUE_CACHE │───>│ RUNNING │───>│SUCCEED/FAILED │
│(初始化)│ │(引擎选出待执行)│ │(Worker claimBuildTask)│ │(completeTask) │
└────────┘ └──────────────┘ └─────────────────────┘ └───────┬───────┘
│
▼
dispatch(ContainerEvent)
│
▼
引擎唤醒，选下一个任务
重复上述流程直到 end-{seq}
特殊状态:
| 状态 | 含义 | 触发场景 |
|---|---|---|
| QUEUE | 初始状态，任务还未被引擎选中 | 构建记录刚创建 |
| QUEUE_CACHE | 引擎已选出，等待 Worker 领取 | StartActionTaskContainerCmd |
| RUNNING | Worker 已领取，正在执行 | claimBuildTask() |
| SUCCEED | 执行成功 | Worker completeTask |
| FAILED | 执行失败 | Worker completeTask |
| CANCELED | 用户取消 | 心跳返回取消信号 |
| UNEXEC | 未执行（被跳过） | terminate 或条件不满足 |
| CALL_WAITING | 等待外部回调 | BuildLess startVM 返回 |
3.5 关键代码入口速查
| 阶段 | 代码入口 | 模块 |
|---|---|---|
| 触发构建 | PipelineBuildFacadeService.buildManualStartup() | process/biz-process |
| 引擎启动 | BuildStartControl.handle() | process/biz-engine |
| Stage 编排 | StageControl.handle() → 命令链 | process/biz-engine |
| Job 编排 | ContainerControl.handle() → 命令链 | process/biz-engine |
| 选出待执行 Task | StartActionTaskContainerCmd.findNeedToRunTask() | process/biz-engine |
| Task 分流 | TaskControl.handle() → runByVmTask() | process/biz-engine |
| 构建机调度（启动） | DispatchVMStartupTaskAtom.execute() | process/biz-engine |
| BuildLess 调度（启动） | DispatchBuildLessDockerStartupTaskAtom.startUpDocker() | process/biz-engine |
| Dispatch 监听 | DockerVMListener / ThirdPartyBuildListener / BuildLessListener | dispatch |
| BuildLess 任务入队 | ContainerPoolExecutor.execute() | buildless |
| BuildLess 任务认领 | BuildLessTaskService.claimBuildLessTask() | buildless |
| Worker 启动上报 | EngineVMBuildService.buildVMStarted() | process/biz-base |
| Worker 领取任务 | EngineVMBuildService.buildClaimTask() → claim() | process/biz-base |
| Worker 完成任务 | EngineVMBuildService.buildCompleteTask() | process/biz-base |
| 引擎被唤醒 | PipelineRuntimeService.completeClaimBuildTask() | process/biz-base |
| Worker 主循环 | Runner.loopPickup() | worker/worker-common |
| Agent 领取构建 | doAsk() → job.DoBuild() | agent (Go) |
| 构建结束 | BuildEndControl.handle() | process/biz-engine |
四、服务依赖关系
┌──────────┐
│ Project │ ◀──── 所有服务的基础依赖
└────┬─────┘
│
┌─────────────────────────┼─────────────────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Auth │◀────────────│ Process │────────────▶│ Store │
└────┬─────┘ └────┬─────┘ └──────────┘
│ ┌────────────┼────────────┐
│ ▼ ▼ ▼
│ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ │Repository│ │ Dispatch │ │ Ticket │
│ └──────────┘ └────┬─────┘ └──────────┘
│ │
│ ▼
│ ┌──────────┐
│ │Environment│
│ └────┬─────┘
│ ▼
│ ┌────────────┐
│ │Agent/Worker│
│ └─────┬──────┘
│ ▼
│ ┌──────────────────────────────────┐
│ │ Log | Artifactory | Notify │
│ └──────────────────────────────────┘
│ │
└───────────────────▶│
▼
┌──────────────┐
│ Metrics │
└──────────────┘
五、核心事件类型
| 事件类型 | 触发时机 | 处理器 |
|----------|----------|--------|
| PipelineBuildStartEvent | 构建启动 | StageControl |
| PipelineBuildStageEvent | Stage 状态变更 | StageControl |
| PipelineBuildContainerEvent | Job 状态变更 | ContainerControl |
| PipelineBuildTaskFinishEvent | 任务完成 | TaskControl |
| PipelineBuildFinishEvent | 构建完成 | BuildFinishListener |
| PipelineBuildCancelEvent | 构建取消 | CancelControl |
| PipelineAgentStartupEvent | 构建机启动 | DispatchListener |
六、技术栈
| 层次 | 技术 | |------|------| | 后端 | Kotlin/Java, Spring Boot 3, Gradle | | 数据库 | MySQL + JOOQ | | 缓存/锁 | Redis | | 消息队列 | RabbitMQ | | 日志检索 | ElasticSearch | | 服务发现 | Consul | | 前端 | Vue 2.7, Vuex, bk-magic-vue | | Agent | Go 1.19+ | | Worker | Kotlin (JVM) |
七、深入阅读导航
以下内容已在专属 Skill 中详细覆盖，不在本文档重复：
| 主题 | 去哪里看 |
|---|---|
| Task 的 5 种角色分类 + TaskControl 分流 | 3-engine-control.md 3.4.1 节 |
| Worker 执行插件的生命周期（事件驱动） | 3-engine-control.md 3.4.2 节 |
| Worker 主循环 + API 通信 | worker-module-architecture Runner 节 |
| Agent 领取构建 + Ask 模式 | agent-module-architecture 3.2~3.3 节 |
| 流水线模型结构（Model/Stage/Container/Element） | pipeline-model-architecture |
| 数据库核心表（92 张表详解） | process-module-architecture/reference/4-dao-database.md |
| BuildLess 容器池管理 | dispatch-module-architecture/reference/buildless.md |
Checklist
开始跨模块开发前，请确认：
- [ ] 已理解流水线执行流程：触发 → 调度 → 执行 → 回传
- [ ] 已确定涉及的模块：Process? Dispatch? Store?
- [ ] 已阅读相关模块 Skill：如
process-module-architecture - [ ] 已了解事件驱动机制：通过 RabbitMQ 异步通信
- [ ] 已确认数据流向：哪些表会被读写？
核心理解要点
- Process 是核心 - 流水线编排、构建调度、状态管理都在这里
- 事件驱动 - 通过 RabbitMQ 实现模块间解耦和异步处理
- 双层构建 - Agent(Go) 负责进程管理，Worker(Kotlin) 负责任务执行
- Worker Pull 模式 - Worker 主动
claimTask领取任务 - 非阻塞等待 - 引擎发出调度请求后不阻塞，通过事件回调继续