SKILL.md
readonly只读
name
process-module-architecture
description
Process 流水线核心模块架构总览，涵盖流水线 CRUD、构建执行引擎、事件驱动机制、分层架构设计。当用户开发流水线核心功能、理解 Process 模块、修改构建逻辑或进行流水线相关开发时使用。
Process 流水线核心模块架构指南
模块定位: Process 是 BK-CI 的核心模块，负责流水线的编排、调度与执行。
详细文档导航
本 Skill 提供 Process 模块的架构总览。如需深入了解各层实现细节，请查阅以下参考文档：
| 文档 | 内容 |
|---|---|
| 1-api-layer.md | API 接口层详细分析（708 行） |
| 2-service-layer.md | Service 业务层详细分析（872 行） |
| 3-engine-control.md | 构建引擎 Control 层分析（790 行） |
| 4-dao-database.md | DAO 层与数据库表结构（901 行） |
| 5-event-driven.md | 事件驱动机制详解（759 行） |
使用建议: 先阅读本文档了解整体架构，再根据具体开发需求深入对应的参考文档。
一、模块整体结构
1.1 子模块划分
src/backend/ci/core/process/
├── api-process/ # API 接口定义层
│ └── src/main/kotlin/com/tencent/devops/process/api/
│ ├── user/ # 用户接口（20+文件）
│ ├── service/ # 服务间调用接口（25+文件）
│ ├── builds/ # 构建机接口（8文件）
│ ├── template/ # 模板接口（6文件）
│ └── op/ # 运维接口（12文件）
│
├── biz-base/ # 基础业务逻辑层（核心）
│ └── src/main/kotlin/com/tencent/devops/process/
│ ├── engine/
│ │ ├── dao/ # 数据访问层（20+文件）
│ │ ├── service/ # 核心服务（30+文件）
│ │ ├── pojo/ # 数据对象
│ │ │ └── event/# 事件定义（19文件）
│ │ └── control/ # 控制逻辑
│ └── service/ # 业务服务
│
├── biz-engine/ # 构建引擎层
│ └── src/main/kotlin/com/tencent/devops/process/engine/
│ ├── control/ # 调度控制器（9文件）
│ ├── atom/ # 插件执行
│ └── listener/ # 事件监听
│
├── biz-process/ # 业务处理层
│ └── src/main/kotlin/com/tencent/devops/process/
│ ├── api/ # API 实现（ResourceImpl）
│ ├── service/ # Facade 服务
│ ├── permission/ # 权限服务
│ └── trigger/ # 触发服务
│
├── boot-engine/ # 引擎启动模块
├── boot-process/ # 服务启动模块
└── model-process/ # 数据模型层（JOOQ 生成）
1.2 模块职责矩阵
| 模块 | 职责 | 核心类数量 | 依赖关系 |
|---|---|---|---|
| api-process | REST API 接口定义 | 91 | 被 biz-process 实现 |
| biz-process | 业务逻辑、API 实现 | 100+ | 依赖 biz-base |
| biz-base | 引擎核心服务、DAO | 185+ | 依赖 model-process |
| biz-engine | 构建调度引擎 | 25 | 依赖 biz-base |
| model-process | JOOQ 数据模型 | 自动生成 | 基础层 |
二、分层架构图
┌─────────────────────────────────────────────────────────────────────────┐
│ 请求入口 │
│ HTTP Request / 服务间调用 / MQ 消息 │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ API 层 (api-process) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │UserPipeline │ │ServiceBuild │ │BuildBuild │ │UserTemplate │ │
│ │Resource │ │Resource │ │Resource │ │Resource │ │
│ │(用户流水线) │ │(服务间构建) │ │(构建机调用) │ │(模板管理) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 业务层 (biz-process) │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ ResourceImpl 实现层 │ │
│ │ UserPipelineResourceImpl | ServiceBuildResourceImpl | ... │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Facade Service 层 │ │
│ │ PipelineInfoFacadeService - 流水线信息管理门面 │ │
│ │ PipelineListFacadeService - 流水线列表查询门面 │ │
│ │ PipelineVersionFacadeService - 版本管理门面 │ │
│ │ ParamFacadeService - 参数管理门面 │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 基础业务层 (biz-base) │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Engine Service 层 │ │
│ │ PipelineRepositoryService - 流水线存储服务（110KB，核心） │ │
│ │ PipelineRuntimeService - 运行时服务（101KB，核心） │ │
│ │ PipelineContainerService - 容器管理服务 │ │
│ │ PipelineStageService - 阶段管理服务 │ │
│ │ PipelineTaskService - 任务管理服务 │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ DAO 层 │ │
│ │ PipelineInfoDao | PipelineBuildDao | PipelineResourceDao │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 引擎层 (biz-engine) │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Control 层 (核心调度) │ │
│ │ BuildStartControl | StageControl | ContainerControl | TaskControl│ │
│ │ BuildEndControl | BuildCancelControl | MutexControl │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 数据层 (model-process + MySQL) │
│ 数据库：devops_process（共 92 张表） │
└─────────────────────────────────────────────────────────────────────────┘
三、核心数据流
3.1 流水线创建流程
用户请求
│
▼
UserPipelineResource.create() # API 层
│
▼
UserPipelineResourceImpl.create() # 实现层
│
▼
PipelineInfoFacadeService.createPipeline() # Facade 层
│
├─► 权限校验 (PipelinePermissionService)
├─► 模型校验 (ModelCheckPlugin)
│
▼
PipelineRepositoryService.deployPipeline() # Engine Service 层
│
├─► PipelineInfoDao.create() # 保存流水线信息
├─► PipelineResourceDao.create() # 保存流水线模型
└─► PipelineSettingDao.create() # 保存流水线配置
3.2 构建执行完整流程（对应流程图）
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 触发层 │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Quartz定时调度 │ │ API接口触发 │ │ Webhook触发 │ │
│ │ PipelineQuartz │ │ UserBuild │ │ PipelineBuild │ │
│ │ Service │ │ Resource │ │ WebhookService │ │
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │ │
│ └───────────────────────┼───────────────────────┘ │
│ ▼ │
│ ┌──────────────────────────────┐ │
│ │ PipelineTimerService │ ← 定时触发服务 │
│ │ PipelineBuildFacadeService │ ← 构建门面服务 │
│ └──────────────┬───────────────┘ │
└───────────────────────────────────┼───────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 拦截器链层 │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ PipelineInterceptorChain │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐ │ │
│ │ │ RunLock │→ │ Queue │→ │ TimerTriggerScmChange │ │ │
│ │ │ Interceptor │ │ Interceptor │ │ Interceptor │ │ │
│ │ │ (运行锁检查) │ │ (队列/并发控制) │ │ (定时触发源码变更检查) │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────┼───────────────────────────────────────────────────────────────┘
│ 拦截通过
▼
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 运行时服务层 │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ PipelineRuntimeService.startBuild() │
│ ├─► 生成 buildId │
│ ├─► 创建构建记录 (T_PIPELINE_BUILD_HISTORY) │
│ ├─► 创建 Stage/Container/Task 记录 │
│ └─► 保存构建变量 │
└───────────────────────────────────┼───────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 事件分发层 │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ PipelineEventDispatcher.dispatch(PipelineBuildStartEvent) ──────────► RabbitMQ │
└───────────────────────────────────┼───────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 监听器层 (Listener) │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │PipelineBuildStart │ │PipelineStageBuild │ │PipelineContainerBuild│ │
│ │Listener │ │Listener │ │Listener │ │
│ │ └► BuildStartControl│ │ └► StageControl │ │ └► ContainerControl│ │
│ └─────────────────────┘ └─────────────────────┘ └─────────────────────┘ │
│ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │PipelineAtomTaskBuild│ │PipelineBuildFinish │ │PipelineBuildCancel │ │
│ │Listener │ │Listener │ │Listener │ │
│ │ └► TaskControl │ │ └► BuildEndControl │ │ └► BuildCancelControl│ │
│ └─────────────────────┘ └─────────────────────┘ └─────────────────────┘ │
└───────────────────────────────────┼───────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 引擎控制层 (Control) │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ BuildStartControl ─► StageControl ─► ContainerControl ─► TaskControl ─► BuildEndControl │
│ │ │ │ │ │
│ │ │ │ ▼ │
│ │ │ │ ┌─────────────────────────┐ │
│ │ │ │ │ 发送 AgentStartupEvent │ │
│ │ │ │ │ 到 Dispatch 服务 │ │
│ │ │ │ └───────────┬─────────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ 命令链 (Command Chain) │ │
│ │ Stage: CheckSkip → CheckInterrupt → CheckPauseReview → StartContainer → UpdateState │ │
│ │ Container: CheckSkip → CheckDependOn → CheckMutex → CheckDispatch → StartTask → UpdateState│ │
│ └─────────────────────────────────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────┼───────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Dispatch 调度服务 │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ DispatcherService (构建机分配服务) │ │
│ │ ├─► ThirdPartyDispatchService (第三方构建机调度) │ │
│ │ │ ├─► ThirdPartyAgentIDDispatchType (指定Agent) │ │
│ │ │ └─► ThirdPartyAgentEnvDispatchType (环境调度) │ │
│ │ ├─► VMDispatcher (虚拟机调度) │ │
│ │ └─► DockerDispatcher (Docker调度) │ │
│ └─────────────────────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ 构建分发 REST API │ │
│ │ BuildAgentBuildResource.claimBuildTask() ← Agent 领取任务 │ │
│ └─────────────────────────────────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────┼───────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 构建机 Agent │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ BuildRunner (容器或虚运行) MasterRunner (裸运行) │ │
│ │ ├─► 领取任务 ├─► 领取任务 │ │
│ │ ├─► 执行插件 ├─► 执行插件 │ │
│ │ ├─► 心跳上报 ├─► 心跳上报 │ │
│ │ └─► 回调完成 └─► 回调完成 │ │
│ └─────────────────────────────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘
四、核心类速查
4.1 触发层
| 类名 | 模块 | 职责 |
|---|---|---|
PipelineQuartzService |
biz-process | Quartz 定时调度服务 |
PipelineQuartzJob |
biz-process | Quartz Job 实现 |
PipelineTimerService |
biz-process | 定时器管理服务 |
PipelineTimerBuildListener |
biz-process | 定时触发监听器 |
4.2 拦截器层
| 类名 | 模块 | 职责 |
|---|---|---|
PipelineInterceptorChain |
biz-base | 拦截器链 |
PipelineInterceptor |
biz-base | 拦截器接口 |
RunLockInterceptor |
biz-base | 运行锁拦截器 |
QueueInterceptor |
biz-base | 队列/并发控制拦截器 |
TimerTriggerScmChangeInterceptor |
biz-base | 定时触发源码变更检查 |
4.3 Service 层
| 类名 | 文件大小 | 职责 |
|---|---|---|
PipelineRepositoryService |
110KB | 流水线存储，最核心的服务 |
PipelineRuntimeService |
101KB | 构建运行时管理 |
PipelineBuildFacadeService |
137KB | 构建管理门面 |
PipelineInfoFacadeService |
80KB | 流水线信息管理门面 |
4.4 监听器层
| 类名 | 模块 | 消费事件 |
|---|---|---|
PipelineBuildStartListener |
biz-engine | PipelineBuildStartEvent |
PipelineStageBuildListener |
biz-engine | PipelineBuildStageEvent |
PipelineContainerBuildListener |
biz-engine | PipelineBuildContainerEvent |
PipelineAtomTaskBuildListener |
biz-engine | PipelineBuildAtomTaskEvent |
PipelineBuildFinishListener |
biz-engine | PipelineBuildFinishEvent |
PipelineBuildCancelListener |
biz-engine | PipelineBuildCancelEvent |
4.5 Control 层
| 类名 | 文件大小 | 职责 |
|---|---|---|
BuildStartControl |
41KB | 构建启动控制 |
StageControl |
10KB | 阶段调度控制 |
ContainerControl |
13KB | 容器调度控制 |
TaskControl |
12KB | 任务调度控制 |
BuildEndControl |
27KB | 构建结束控制 |
MutexControl |
26KB | 互斥锁控制 |
4.6 DAO 层
| 类名 | 文件大小 | 职责 |
|---|---|---|
PipelineBuildDao |
80KB+ | 构建历史数据访问 |
PipelineInfoDao |
30KB | 流水线信息数据访问 |
PipelineResourceDao |
15KB | 流水线模型数据访问 |
五、开发规范
5.1 新增功能检查清单
- [ ] API 接口定义在
api-process模块 - [ ] API 实现在
biz-process模块 - [ ] 核心服务在
biz-base模块 - [ ] DAO 使用 JOOQ，禁止手写 SQL
- [ ] 事件通过
PipelineEventDispatcher分发 - [ ] 遵循命名规范（见各子 Skill）
5.2 常见问题
Q: 流水线模型存储在哪里？
A: T_PIPELINE_RESOURCE 表的 MODEL 字段，JSON 格式。
Q: 如何扩展新的触发方式？
A: 在 StartType 枚举中添加，并在 PipelineTriggerEventService 处理。
Q: 事件如何分发？
A: 通过 PipelineEventDispatcher 发送到 RabbitMQ，由对应 Control 消费。
版本: 2.1.0 | 更新日期: 2025-12-10 | 补充: 根据流程图完善触发层、拦截器层、监听器层、Dispatch 调度服务
You Might Also Like
Related Skills
create-pr
170Kdev-devops
Creates GitHub pull requests with properly formatted titles that pass the check-pr-title CI validation. Use when creating PRs, submitting changes for review, or when the user says /pr or asks to create a pull request.
n8n-io
electron-chromium-upgrade
120Kdev-devops
Guide for performing Chromium version upgrades in the Electron project. Use when working on the roller/chromium/main branch to fix patch conflicts during `e sync --3`. Covers the patch application workflow, conflict resolution, analyzing upstream Chromium changes, and proper commit formatting for patch fixes.
electron
pr-creator
92Kdev-devops
Use this skill when asked to create a pull request (PR). It ensures all PRs follow the repository's established templates and standards.
google-gemini
clawdhub
87Kdev-devops
Use the ClawdHub CLI to search, install, update, and publish agent skills from clawdhub.com. Use when you need to fetch new skills on the fly, sync installed skills to latest or a specific version, or publish new/updated skill folders with the npm-installed clawdhub CLI.
moltbottmux
87Kdev-devops
Remote-control tmux sessions for interactive CLIs by sending keystrokes and scraping pane output.
moltbot
create-pull-request
57Kdev-devops
Create a GitHub pull request following project conventions. Use when the user asks to create a PR, submit changes for review, or open a pull request. Handles commit analysis, branch management, and PR creation using the gh CLI tool.
cline