--- name: 29-process-module-architecture description: Process 流水线核心模块架构总览，涵盖流水线 CRUD、构建执行引擎、事件驱动机制、分层架构设计。当用户开发流水线核心功能、理解 Process 模块、修改构建逻辑或进行流水线相关开发时使用。 --- # Process 流水线核心模块架构指南 > **模块定位**: Process 是 BK-CI 的核心模块，负责流水线的编排、调度与执行。 ## 相关 Skill 索引 | Skill | 内容 | |-------|------| | `29-1-process-api-layer` | API 接口层详细分析 | | `29-2-process-service-layer` | Service 业务层详细分析 | | `29-3-process-engine-control` | 构建引擎 Control 层分析 | | `29-4-process-dao-database` | DAO 层与数据库表结构 | | `29-5-process-event-driven` | 事件驱动机制详解 | ## 一、模块整体结构 ### 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 调度服务