陌讯skills聚合平台

process-module-architecture

📁 tencentblueking/bk-ci 📅 Jan 23, 2026
25
总安装量
20
周安装量
#14959
全站排名
安装命令
npx skills add https://github.com/tencentblueking/bk-ci --skill process-module-architecture

Agent 安装分布

claude-code 12
opencode 10
cursor 10
trae 9
antigravity 8

Skill 文档

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 调度服务

GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台
本页面由 陌讯 Skills 聚合平台 收录整理，数据定期更新。