46-pipeline-template-module by TencentBlueKing
流水线模板模块架构指南，涵盖模板创建、版本管理、实例化、权限控制、研发商店集成。当用户需要开发模板功能、实现模板复用、管理模板版本或进行批量实例化时使用。
Coding
2.5K Stars
514 Forks
Updated Jan 9, 2026, 09:52 AM
Why Use This
This skill provides specialized capabilities for TencentBlueKing's codebase.
Use Cases
- Developing new features in the TencentBlueKing repository
- Refactoring existing code to follow TencentBlueKing standards
- Understanding and working with TencentBlueKing's codebase structure
Skill Snapshot
Auto scan of skill assets. Informational only.
Valid SKILL.md
Checks against SKILL.md specification
Source & Community
Skill Stats
SKILL.md 1621 Lines
Total Files 1
Total Size 0 B
License NOASSERTION
---
name: 46-pipeline-template-module
description: 流水线模板模块架构指南，涵盖模板创建、版本管理、实例化、权限控制、研发商店集成。当用户需要开发模板功能、实现模板复用、管理模板版本或进行批量实例化时使用。
---
# 流水线模板模块架构指南
## 概述
流水线模板（Pipeline Template）是 BK-CI 的核心功能模块之一，允许用户将流水线配置抽象为可复用的模板，支持模板的创建、版本管理、实例化、权限控制以及与研发商店的集成。
### 核心价值
- **配置复用**：将通用的流水线配置抽象为模板，避免重复配置
- **标准化管理**：通过模板统一管理流水线标准，确保一致性
- **版本控制**：支持模板版本管理，可追溯历史变更
- **批量操作**：支持批量实例化和更新，提高效率
- **商店集成**：支持模板发布到研发商店，实现跨项目共享
### 系统架构
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 流水线模板模块 │
├─────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ API 接口层 │ │ 业务服务层 │ │ 数据访问层 │ │
│ │ (V1 + V2) │ │ (Service) │ │ (DAO) │ │
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 数据库表 │ │
│ │ T_TEMPLATE | T_TEMPLATE_PIPELINE | T_PIPELINE_TEMPLATE_INFO │ │
│ │ T_PIPELINE_TEMPLATE_RESOURCE_VERSION | T_TEMPLATE_INSTANCE_* │ │
│ └─────────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 权限控制 │ │ 研发商店集成 │ │ 事件驱动 │ │
│ │ (RBAC) │ │ (Store) │ │ (MQ) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## 一、版本架构
系统存在两个版本的实现，V2 版本是新架构，功能更完善：
| 版本 | 特点 | 适用场景 |
|------|------|----------|
| **V1** | 原始实现，功能基础 | 兼容老版本，简单场景 |
| **V2** | 新架构，支持草稿、PAC、完善的版本管理 | 新功能开发，复杂场景 |
### 模板类型
```kotlin
// 文件: process/api-process/.../pojo/template/TemplateType.kt
enum class TemplateType(val value: String) {
CUSTOMIZE("customize"), // 自定义模板 - 项目内创建
CONSTRAINT("constraint"), // 约束模板 - 来自研发商店
PUBLIC("public") // 公共模板 - 系统级公共模板
}
```
---
## 二、目录结构
### 2.1 API 接口层
```
src/backend/ci/core/process/api-process/src/main/kotlin/com/tencent/devops/process/
├── api/template/ # V1 版本 API
│ ├── UserPTemplateResource.kt # 用户模板接口
│ ├── UserTemplateInstanceResource.kt # 模板实例化接口
│ ├── UserPipelineTemplateResource.kt # 流水线模板接口
│ ├── UserTemplateAtomResource.kt # 模板插件接口
│ ├── ServicePTemplateResource.kt # 服务间调用接口
│ ├── ServiceTemplateInstanceResource.kt # 服务间实例接口
│ └── v2/ # V2 版本 API
│ ├── UserPipelineTemplateV2Resource.kt # V2 用户模板接口
│ ├── UserPipelineTemplateInstanceV2Resource.kt # V2 实例化接口
│ ├── ServicePipelineTemplateV2Resource.kt # V2 服务间接口
│ ├── OpPipelineTemplateResource.kt # V2 运营管理接口
│ └── UserTemplateAtomV2Resource.kt # V2 插件检查接口
├── api/op/
│ └── OpPipelineTemplateResource.kt # 运营管理模板接口
├── api/builds/
│ └── BuildTemplateAcrossResource.kt # 跨项目模板访问
└── api/service/
└── ServiceTemplateAcrossResource.kt # 服务间跨项目模板
```
### 2.2 POJO 数据模型
```
src/backend/ci/core/process/api-process/src/main/kotlin/com/tencent/devops/process/pojo/template/
├── TemplateType.kt # 模板类型枚举
├── TemplateModel.kt # 模板模型
├── TemplateModelDetail.kt # 模板模型详情
├── TemplateVersion.kt # 模板版本信息
├── TemplateId.kt # 模板ID
├── TemplateInstanceCreate.kt # 实例创建请求
├── TemplateInstanceUpdate.kt # 实例更新请求
├── TemplateInstanceParams.kt # 实例参数
├── TemplatePipeline.kt # 模板流水线
├── TemplateWithPermission.kt # 带权限的模板
├── TemplateCompareModel.kt # 模板对比模型
├── CopyTemplateReq.kt # 复制模板请求
├── SaveAsTemplateReq.kt # 另存为模板请求
├── MarketTemplateRequest.kt # 商店模板请求
└── v2/ # V2 版本 POJO
├── PipelineTemplateInfoV2.kt # V2 模板基础信息
├── PipelineTemplateResource.kt # V2 模板资源(版本)
├── PipelineTemplateDetailsResponse.kt # V2 模板详情响应
├── PipelineTemplateVersionInfo.kt # V2 版本信息
├── PipelineTemplateCustomCreateReq.kt # V2 自定义创建请求
├── PipelineTemplateCopyCreateReq.kt # V2 复制创建请求
├── PipelineTemplateMarketCreateReq.kt # V2 商店导入请求
├── PipelineTemplateDraftSaveReq.kt # V2 草稿保存请求
├── PipelineTemplateDraftReleaseReq.kt # V2 草稿发布请求
├── PipelineTemplateInstancesRequest.kt # V2 批量实例化请求
├── PipelineTemplateCompareResponse.kt # V2 版本对比响应
└── TemplateInstanceType.kt # 实例类型枚举
```
### 2.3 业务服务层
```
src/backend/ci/core/process/biz-process/src/main/kotlin/com/tencent/devops/process/service/template/
├── TemplateFacadeService.kt # V1 核心门面服务 (120KB)
├── TemplateCommonService.kt # 模板通用服务
├── TemplateSettingService.kt # 模板设置服务
├── TemplateAtomService.kt # 模板插件服务
├── TemplatePACService.kt # 模板 PAC 服务
└── v2/ # V2 版本服务
├── PipelineTemplateFacadeService.kt # V2 核心门面服务 (71KB)
├── PipelineTemplateInstanceService.kt # V2 实例化服务 (41KB)
├── PipelineTemplatePersistenceService.kt # V2 持久化服务 (38KB)
├── PipelineTemplateMigrateService.kt # V2 迁移服务 (38KB)
├── PipelineTemplateGenerator.kt # 模板生成器
├── PipelineTemplateMarketFacadeService.kt # 商店模板服务
├── PipelineTemplateInfoService.kt # 模板信息服务
├── PipelineTemplateResourceService.kt # 模板资源服务
├── PipelineTemplateRelatedService.kt # 模板关联服务
├── PipelineTemplateSettingService.kt # V2 模板设置服务
├── PipelineTemplateCommonService.kt # V2 通用服务
├── PipelineTemplateAtomService.kt # V2 插件服务
├── PipelineTemplateVersionValidator.kt # 版本校验器
├── PipelineTemplateModelInitializer.kt # 模型初始化器
├── PipelineTemplateInstanceListener.kt # 实例化事件监听器
└── version/ # 版本管理
├── PipelineTemplateVersionManager.kt # 版本管理器
├── PipelineTemplateVersionCreateContext.kt # 版本创建上下文
├── PipelineTemplateVersionDeleteContext.kt # 版本删除上下文
├── convert/ # 请求转换器
│ ├── PipelineTemplateCustomCreateReqConverter.kt
│ ├── PipelineTemplateCopyCreateReqConverter.kt
│ ├── PipelineTemplateMarketCreateReqConverter.kt
│ ├── PipelineTemplateDraftSaveReqConverter.kt
│ ├── PipelineTemplateDraftReleaseReqConverter.kt
│ └── PipelineTemplateDraftRollbackReqConverter.kt
├── hander/ # 版本处理器
│ ├── PipelineTemplateVersionCreateHandler.kt
│ ├── PipelineTemplateDraftSaveHandler.kt
│ ├── PipelineTemplateDraftReleaseHandler.kt
│ ├── PipelineTemplateReleaseCreateHandler.kt
│ ├── PipelineTemplateBranchCreateHandler.kt
│ └── PipelineTemplateVersionDeleteHandler.kt
└── processor/ # 版本后处理器
├── PTemplateVersionCreatePostProcessor.kt
├── PTemplateVersionDeletePostProcessor.kt
├── PTemplateCompatibilityVersionPostProcessor.kt
├── PTemplateMarketInstallVersionPostProcessor.kt
└── PTemplateOperationLogVersionPostProcessor.kt
```
### 2.4 数据访问层
```
src/backend/ci/core/process/biz-base/src/main/kotlin/com/tencent/devops/process/
├── engine/dao/template/ # V1 版本 DAO
│ ├── TemplateDao.kt # 核心模板 DAO (25KB)
│ └── TemplatePipelineDao.kt # 模板流水线 DAO (16KB)
└── dao/template/ # V2 版本 DAO
├── PipelineTemplateInfoDao.kt # V2 模板信息 DAO (16KB)
├── PipelineTemplateResourceDao.kt # V2 模板资源 DAO (23KB)
├── PipelineTemplateSettingDao.kt # V2 模板设置 DAO (13KB)
├── PipelineTemplateRelatedDao.kt # V2 模板关联 DAO (15KB)
└── PipelineTemplateMigrationDao.kt # V2 迁移 DAO
```
### 2.5 权限控制
```
src/backend/ci/core/process/biz-process/src/main/kotlin/com/tencent/devops/process/permission/template/
├── PipelineTemplatePermissionService.kt # 权限服务接口
├── AbstractPipelineTemplatePermissionService.kt # 抽象实现
├── RbacPipelineTemplatePermissionService.kt # RBAC 权限实现
├── MockPipelineTemplatePermissionService.kt # Mock 实现
└── config/
└── PipelineTemplatePermConfiguration.kt # 权限配置
```
---
## 三、数据库表结构
### 3.1 V1 版本表
#### T_TEMPLATE - 模板信息表
```sql
CREATE TABLE IF NOT EXISTS `T_TEMPLATE` (
`VERSION` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '版本号',
`ID` varchar(32) NOT NULL COMMENT '模板ID',
`TEMPLATE_NAME` varchar(64) NOT NULL COMMENT '模板名称',
`PROJECT_ID` varchar(34) NOT NULL COMMENT '项目ID',
`VERSION_NAME` varchar(64) NOT NULL COMMENT '版本名称',
`CREATOR` varchar(64) NOT NULL COMMENT '创建者',
`CREATED_TIME` datetime(3) DEFAULT NULL COMMENT '创建时间',
`TEMPLATE` mediumtext COMMENT '模板内容(JSON)',
`TYPE` varchar(32) NOT NULL DEFAULT 'CUSTOMIZE' COMMENT '模板类型',
`CATEGORY` varchar(128) DEFAULT NULL COMMENT '分类',
`LOGO_URL` varchar(512) DEFAULT NULL COMMENT 'Logo地址',
`SRC_TEMPLATE_ID` varchar(32) DEFAULT NULL COMMENT '源模板ID',
`STORE_FLAG` bit(1) DEFAULT b'0' COMMENT '是否来自商店',
`WEIGHT` int(11) DEFAULT '0' COMMENT '权重',
`LATEST_FLAG` bit(1) DEFAULT b'0' COMMENT '是否最新版本',
`DRAFT_FLAG` bit(1) DEFAULT b'0' COMMENT '是否草稿',
PRIMARY KEY (`VERSION`),
KEY `IDX_PROJECT_ID` (`PROJECT_ID`),
KEY `IDX_ID` (`ID`),
KEY `IDX_SRC_TEMPLATE_ID` (`SRC_TEMPLATE_ID`)
);
```
#### T_TEMPLATE_PIPELINE - 模板流水线关联表
```sql
CREATE TABLE IF NOT EXISTS `T_TEMPLATE_PIPELINE` (
`PIPELINE_ID` varchar(34) NOT NULL COMMENT '流水线ID',
`INSTANCE_TYPE` varchar(32) NOT NULL DEFAULT 'CONSTRAINT' COMMENT '实例类型',
`ROOT_TEMPLATE_ID` varchar(32) DEFAULT NULL COMMENT '根模板ID',
`VERSION` bigint(20) NOT NULL COMMENT '模板版本',
`VERSION_NAME` varchar(64) NOT NULL COMMENT '版本名称',
`TEMPLATE_ID` varchar(32) NOT NULL COMMENT '模板ID',
`CREATOR` varchar(64) NOT NULL COMMENT '创建者',
`UPDATOR` varchar(64) NOT NULL COMMENT '更新者',
`CREATED_TIME` datetime NOT NULL COMMENT '创建时间',
`UPDATED_TIME` datetime NOT NULL COMMENT '更新时间',
`BUILD_NO` text COMMENT '构建号信息',
`PARAM` mediumtext COMMENT '参数',
`DELETED` bit(1) DEFAULT b'0' COMMENT '是否删除',
PRIMARY KEY (`PIPELINE_ID`),
KEY `IDX_TEMPLATE_ID` (`TEMPLATE_ID`),
KEY `IDX_ROOT_TEMPLATE_ID` (`ROOT_TEMPLATE_ID`)
);
```
### 3.2 V2 版本表
#### T_PIPELINE_TEMPLATE_INFO - 模板基础信息表
```sql
CREATE TABLE IF NOT EXISTS `T_PIPELINE_TEMPLATE_INFO` (
`TEMPLATE_ID` varchar(34) NOT NULL COMMENT '模板ID',
`PROJECT_ID` varchar(64) NOT NULL COMMENT '项目ID',
`TEMPLATE_NAME` varchar(255) NOT NULL COMMENT '模板名称',
`TEMPLATE_TYPE` varchar(32) NOT NULL DEFAULT 'CUSTOMIZE' COMMENT '模板类型',
`CREATOR` varchar(64) NOT NULL COMMENT '创建者',
`CREATE_TIME` datetime(3) NOT NULL COMMENT '创建时间',
`LATEST_VERSION` bigint(20) DEFAULT NULL COMMENT '最新版本号',
`RELEASE_VERSION` bigint(20) DEFAULT NULL COMMENT '发布版本号',
`DRAFT_VERSION` bigint(20) DEFAULT NULL COMMENT '草稿版本号',
`DELETE` bit(1) NOT NULL DEFAULT b'0' COMMENT '是否删除',
PRIMARY KEY (`TEMPLATE_ID`),
KEY `IDX_PROJECT_ID` (`PROJECT_ID`)
);
```
#### T_PIPELINE_TEMPLATE_RESOURCE_VERSION - 模板资源版本表
```sql
CREATE TABLE IF NOT EXISTS `T_PIPELINE_TEMPLATE_RESOURCE_VERSION` (
`TEMPLATE_ID` varchar(34) NOT NULL COMMENT '模板ID',
`VERSION` bigint(20) NOT NULL COMMENT '版本号',
`VERSION_NAME` varchar(64) NOT NULL COMMENT '版本名称',
`PROJECT_ID` varchar(64) NOT NULL COMMENT '项目ID',
`CREATOR` varchar(64) NOT NULL COMMENT '创建者',
`CREATE_TIME` datetime(3) NOT NULL COMMENT '创建时间',
`MODEL` mediumtext COMMENT '模型内容(JSON)',
`STATUS` varchar(32) DEFAULT NULL COMMENT '版本状态',
`BRANCH_ACTION` varchar(32) DEFAULT NULL COMMENT '分支操作',
`DESCRIPTION` varchar(1024) DEFAULT NULL COMMENT '版本描述',
`YAML` mediumtext COMMENT 'YAML内容',
`YAML_VERSION` varchar(34) DEFAULT NULL COMMENT 'YAML版本',
`BASE_VERSION` bigint(20) DEFAULT NULL COMMENT '基础版本',
`DEBUG_BUILD_ID` varchar(64) DEFAULT NULL COMMENT '调试构建ID',
`REFER_FLAG` bit(1) DEFAULT NULL COMMENT '引用标志',
`REFER_TEMPLATE_ID` varchar(34) DEFAULT NULL COMMENT '引用模板ID',
PRIMARY KEY (`TEMPLATE_ID`, `VERSION`),
KEY `IDX_PROJECT_ID` (`PROJECT_ID`)
);
```
#### T_TEMPLATE_INSTANCE_BASE - 实例化基础表
```sql
CREATE TABLE IF NOT EXISTS `T_TEMPLATE_INSTANCE_BASE` (
`ID` varchar(32) NOT NULL COMMENT '主键ID',
`TEMPLATE_ID` varchar(32) DEFAULT NULL COMMENT '模板ID',
`TEMPLATE_VERSION` bigint(20) DEFAULT NULL COMMENT '模板版本',
`USE_TEMPLATE_SETTINGS_FLAG` bit(1) DEFAULT b'1' COMMENT '使用模板设置',
`PROJECT_ID` varchar(64) NOT NULL COMMENT '项目ID',
`TOTAL_ITEM_NUM` int(11) NOT NULL COMMENT '总实例数',
`SUCCESS_ITEM_NUM` int(11) NOT NULL DEFAULT '0' COMMENT '成功实例数',
`FAIL_ITEM_NUM` int(11) NOT NULL DEFAULT '0' COMMENT '失败实例数',
`STATUS` varchar(32) NOT NULL COMMENT '状态',
`CREATOR` varchar(50) NOT NULL COMMENT '创建者',
`MODIFIER` varchar(50) NOT NULL COMMENT '修改者',
`UPDATE_TIME` datetime(3) NOT NULL COMMENT '更新时间',
`CREATE_TIME` datetime(3) NOT NULL COMMENT '创建时间',
PRIMARY KEY (`ID`),
KEY `IDX_TEMPLATE_ID` (`TEMPLATE_ID`),
KEY `IDX_PROJECT_ID` (`PROJECT_ID`)
);
```
#### T_TEMPLATE_INSTANCE_ITEM - 实例化项表
```sql
CREATE TABLE IF NOT EXISTS `T_TEMPLATE_INSTANCE_ITEM` (
`ID` varchar(32) NOT NULL COMMENT '主键ID',
`BASE_ID` varchar(32) NOT NULL COMMENT '基础ID',
`PIPELINE_ID` varchar(34) DEFAULT NULL COMMENT '流水线ID',
`PIPELINE_NAME` varchar(255) NOT NULL COMMENT '流水线名称',
`BUILD_NO_INFO` varchar(512) DEFAULT NULL COMMENT '构建号信息',
`STATUS` varchar(32) NOT NULL COMMENT '状态',
`PARAM` mediumtext COMMENT '参数',
`CREATE_TIME` datetime(3) NOT NULL COMMENT '创建时间',
`UPDATE_TIME` datetime(3) NOT NULL COMMENT '更新时间',
PRIMARY KEY (`ID`),
KEY `IDX_BASE_ID` (`BASE_ID`),
KEY `IDX_PIPELINE_ID` (`PIPELINE_ID`)
);
```
---
## 四、核心功能实现
### 4.1 模板创建
#### V1 版本创建流程
```kotlin
// 文件: process/biz-process/.../service/template/TemplateFacadeService.kt
@Service
class TemplateFacadeService {
fun createTemplate(
projectId: String,
userId: String,
template: Model,
templateType: TemplateType = TemplateType.CUSTOMIZE
): String {
// 1. 权限校验
pipelineTemplatePermissionService.checkPipelineTemplatePermission(
userId = userId,
projectId = projectId,
permission = AuthPermission.CREATE
)
// 2. 模板名称校验
if (templateDao.countByName(dslContext, projectId, template.name) > 0) {
throw ErrorCodeException(errorCode = ProcessMessageCode.ERROR_TEMPLATE_NAME_IS_EXISTS)
}
// 3. 生成模板ID
val templateId = UUIDUtil.generate()
// 4. 保存模板
templateDao.create(
dslContext = dslContext,
templateId = templateId,
projectId = projectId,
templateName = template.name,
versionName = INIT_TEMPLATE_VERSION_NAME,
userId = userId,
template = JsonUtil.toJson(template),
type = templateType.name
)
// 5. 注册权限资源
pipelineTemplatePermissionService.createResource(
userId = userId,
projectId = projectId,
templateId = templateId,
templateName = template.name
)
return templateId
}
}
```
#### V2 版本创建流程
```kotlin
// 文件: process/biz-process/.../service/template/v2/PipelineTemplateFacadeService.kt
@Service
class PipelineTemplateFacadeService {
fun create(
userId: String,
projectId: String,
request: PipelineTemplateCustomCreateReq
): PipelineTemplateCreateResp {
// 1. 权限校验
pipelineTemplatePermissionService.checkPipelineTemplatePermission(
userId = userId,
projectId = projectId,
permission = AuthPermission.CREATE
)
// 2. 调用版本管理器
val result = pipelineTemplateVersionManager.deployTemplate(
userId = userId,
projectId = projectId,
request = request
)
// 3. 注册权限资源
pipelineTemplatePermissionService.createResource(
userId = userId,
projectId = projectId,
templateId = result.templateId,
templateName = request.name
)
return PipelineTemplateCreateResp(
templateId = result.templateId,
version = result.version
)
}
}
```
### 4.2 模板实例化
模板实例化是将模板转换为具体流水线的过程：
```kotlin
// 文件: process/biz-process/.../service/template/v2/PipelineTemplateInstanceService.kt
@Service
class PipelineTemplateInstanceService {
/**
* 批量实例化模板
*/
fun createTemplateInstances(
userId: String,
projectId: String,
templateId: String,
version: Long,
request: PipelineTemplateInstancesRequest
): List<PipelineTemplateInstanceItem> {
// 1. 校验创建流水线权限
pipelinePermissionService.validPipelinePermission(
userId = userId,
projectId = projectId,
permission = AuthPermission.CREATE
)
// 2. 获取模板详情
val templateDetail = pipelineTemplateFacadeService.getTemplateDetail(
userId = userId,
projectId = projectId,
templateId = templateId,
version = version
)
// 3. 遍历创建流水线实例
return request.instances.map { instance ->
createInstance(
userId = userId,
projectId = projectId,
templateDetail = templateDetail,
instance = instance
)
}
}
private fun createInstance(
userId: String,
projectId: String,
templateDetail: PipelineTemplateDetailsResponse,
instance: PipelineTemplateInstanceItem
): PipelineTemplateInstanceItem {
// 1. 合并模板参数和实例参数
val model = mergeTemplateAndInstanceParams(
templateModel = templateDetail.model,
instanceParams = instance.params
)
// 2. 创建流水线
val pipelineId = pipelineInfoFacadeService.create(
userId = userId,
projectId = projectId,
model = model,
channelCode = ChannelCode.BS
)
// 3. 建立模板-流水线关联
templatePipelineDao.create(
dslContext = dslContext,
pipelineId = pipelineId,
templateId = templateDetail.templateId,
version = templateDetail.version,
versionName = templateDetail.versionName,
userId = userId
)
return instance.copy(pipelineId = pipelineId)
}
}
```
### 4.3 版本管理
V2 版本采用策略模式实现版本管理：
```kotlin
// 文件: process/biz-process/.../service/template/v2/version/PipelineTemplateVersionManager.kt
@Service
class PipelineTemplateVersionManager(
private val versionReqConverters: List<PipelineTemplateVersionReqConverter>,
private val versionCreateHandlers: List<PipelineTemplateVersionCreateHandler>,
private val pipelineTemplateVersionValidator: PipelineTemplateVersionValidator,
private val versionDeleteHandler: PipelineTemplateVersionDeleteHandler
) {
/**
* 部署模板（创建/更新版本）
*/
fun deployTemplate(
userId: String,
projectId: String,
templateId: String? = null,
version: Long? = null,
request: PipelineTemplateVersionReq
): DeployTemplateResult {
// 1. 转换请求为上下文
val context = getConverter(request).convert(
userId = userId,
projectId = projectId,
templateId = templateId,
version = version,
request = request
)
// 2. 校验版本
pipelineTemplateVersionValidator.validate(context = context)
// 3. 调用对应处理器
return getHandler(context).handle(context = context)
}
/**
* 删除版本
*/
fun deleteVersion(
userId: String,
projectId: String,
templateId: String,
version: Long?,
versionName: String? = null
) {
val context = PipelineTemplateVersionDeleteContext(
userId = userId,
projectId = projectId,
templateId = templateId,
version = version,
versionAction = PipelineVersionAction.DELETE_VERSION
)
versionDeleteHandler.handle(context = context)
}
private fun getHandler(context: PipelineTemplateVersionCreateContext): PipelineTemplateVersionCreateHandler {
return versionCreateHandlers.find { it.support(context) }
?: throw IllegalArgumentException("Unsupported version event")
}
private fun getConverter(request: PipelineTemplateVersionReq): PipelineTemplateVersionReqConverter {
return versionReqConverters.find { it.support(request) }
?: throw IllegalArgumentException("Unsupported version request")
}
}
```
#### 版本处理器类型
| 处理器 | 功能 | 触发场景 |
|--------|------|----------|
| `PipelineTemplateDraftSaveHandler` | 保存草稿 | 编辑模板后保存草稿 |
| `PipelineTemplateDraftReleaseHandler` | 发布草稿 | 将草稿发布为正式版本 |
| `PipelineTemplateReleaseCreateHandler` | 创建发布版本 | 直接创建正式版本 |
| `PipelineTemplateBranchCreateHandler` | 创建分支版本 | PAC 场景下的分支版本 |
| `PipelineTemplateVersionDeleteHandler` | 删除版本 | 删除指定版本 |
### 4.4 权限控制
```kotlin
// 文件: process/biz-process/.../permission/template/PipelineTemplatePermissionService.kt
interface PipelineTemplatePermissionService {
/**
* 校验模板权限
*/
fun checkPipelineTemplatePermission(
userId: String,
projectId: String,
templateId: String? = null,
permission: AuthPermission,
message: String? = null
)
/**
* 创建权限资源
*/
fun createResource(
userId: String,
projectId: String,
templateId: String,
templateName: String
)
/**
* 删除权限资源
*/
fun deleteResource(
projectId: String,
templateId: String
)
/**
* 获取有权限的模板列表
*/
fun filterTemplates(
userId: String,
projectId: String,
permission: AuthPermission,
templateIds: List<String>
): List<String>
/**
* 是否启用模板权限管理
*/
fun enableTemplatePermissionManage(projectId: String): Boolean
}
```
#### RBAC 权限实现
```kotlin
// 文件: process/biz-process/.../permission/template/RbacPipelineTemplatePermissionService.kt
@Service
class RbacPipelineTemplatePermissionService(
private val client: Client,
private val authPermissionApi: AuthPermissionApi,
private val authResourceApi: AuthResourceApi
) : AbstractPipelineTemplatePermissionService() {
override fun checkPipelineTemplatePermission(
userId: String,
projectId: String,
templateId: String?,
permission: AuthPermission,
message: String?
) {
// 调用权限中心校验
val hasPermission = authPermissionApi.validateUserResourcePermission(
userId = userId,
serviceCode = AuthServiceCode.PIPELINE,
resourceType = AuthResourceType.PIPELINE_TEMPLATE,
projectCode = projectId,
resourceCode = templateId ?: "*",
permission = permission
)
if (!hasPermission) {
throw PermissionForbiddenException(message ?: "无模板操作权限")
}
}
override fun createResource(
userId: String,
projectId: String,
templateId: String,
templateName: String
) {
authResourceApi.createResource(
userId = userId,
serviceCode = AuthServiceCode.PIPELINE,
resourceType = AuthResourceType.PIPELINE_TEMPLATE,
projectCode = projectId,
resourceCode = templateId,
resourceName = templateName
)
}
}
```
---
## 五、PAC (Pipeline as Code) 模板
### 5.1 PAC 概述
PAC（Pipeline as Code）是 BK-CI 的核心特性，允许用户通过 YAML 文件定义和管理流水线模板。模板 PAC 支持：
- **YAML 定义模板**：使用 YAML 格式定义模板配置
- **Git 仓库托管**：模板 YAML 文件存储在 Git 仓库中
- **Webhook 自动同步**：代码推送自动触发模板更新
- **分支版本管理**：支持基于 Git 分支的版本管理
- **双向转换**：Model ↔ YAML 双向转换
### 5.2 模板类型（PAC 视角）
```kotlin
// 文件: common/common-pipeline/.../template/PipelineTemplateType.kt
enum class PipelineTemplateType(val value: String) {
PIPELINE("pipeline"), // 完整流水线模板
STAGE("stage"), // Stage 级别模板
JOB("job"), // Job 级别模板
STEP("step"), // Step 级别模板
VARIABLE("variable") // 变量模板
}
```
### 5.3 PAC 核心服务
#### 5.3.1 TemplatePACService（V1 PAC 服务）
```kotlin
// 文件: process/biz-process/.../service/template/TemplatePACService.kt
@Service
class TemplatePACService(
private val templateDao: TemplateDao,
private val transferYamlService: PipelineTransferYamlService,
private val templateCommonService: TemplateCommonService
) {
/**
* 预览模板（返回 Model + YAML + 高亮标记）
*/
fun previewTemplate(
userId: String,
projectId: String,
templateId: String,
highlightType: HighlightType?
): TemplatePreviewDetail {
// 1. 获取模板
val template = templateDao.getLatestTemplate(dslContext, projectId, templateId)
val model: Model = objectMapper.readValue(template.template)
// 2. 获取设置
val setting = pipelineRepositoryService.getSetting(projectId, templateId)
// 3. Model 转 YAML
val yaml = transferYamlService.transfer(
userId = userId,
projectId = projectId,
actionType = TransferActionType.FULL_MODEL2YAML,
data = TransferBody(PipelineModelAndSetting(model, setting))
).yamlWithVersion?.yamlStr
// 4. 生成高亮标记（用于 UI 展示）
val highlightMarkList = buildHighlightMarks(yaml, highlightType)
return TemplatePreviewDetail(
template = model,
templateYaml = yaml,
setting = setting,
hasPermission = hasPermission,
highlightMarkList = highlightMarkList
)
}
}
```
#### 5.3.2 PTemplateYamlResourceService（YAML 资源服务）
```kotlin
// 文件: process/biz-process/.../yaml/resource/PTemplateYamlResourceService.kt
@Service
class PTemplateYamlResourceService(
private val pipelineTemplateFacadeService: PipelineTemplateFacadeService,
private val pipelineTemplateInfoService: PipelineTemplateInfoService
) : IPipelineYamlResourceService {
/**
* 通过 YAML 创建模板（Git Webhook 触发）
*/
override fun createYamlPipeline(
userId: String,
projectId: String,
yaml: String,
event: PipelineYamlFileEvent
): DeployPipelineResult {
with(event) {
val isDefaultBranch = ref == defaultBranch
val yamlFileName = GitActionCommon.getCiTemplateName(filePath)
// 调用 V2 服务创建 YAML 模板
val result = pipelineTemplateFacadeService.createYamlTemplate(
userId = userId,
projectId = projectId,
yaml = yaml,
yamlFileName = yamlFileName,
branchName = ref,
isDefaultBranch = isDefaultBranch,
description = commit!!.commitMsg,
yamlFileInfo = PipelineYamlFileInfo(repoHashId, filePath)
)
return DeployPipelineResult(
pipelineId = result.templateId,
pipelineName = result.templateName,
version = result.version.toInt(),
versionName = result.versionName
)
}
}
/**
* 通过 YAML 更新模板
*/
override fun updateYamlPipeline(
userId: String,
projectId: String,
pipelineId: String,
yaml: String,
event: PipelineYamlFileEvent
): DeployPipelineResult {
// 类似创建逻辑，调用 updateYamlTemplate
}
/**
* 分支失活（分支删除时调用）
*/
override fun updateBranchAction(
userId: String,
projectId: String,
pipelineId: String,
branchName: String,
branchVersionAction: BranchVersionAction
) {
pipelineTemplateFacadeService.inactiveBranch(
userId = userId,
projectId = projectId,
templateId = pipelineId,
branch = branchName
)
}
}
```
#### 5.3.3 PipelineYamlResourceManager（统一管理器）
```kotlin
// 文件: process/biz-process/.../yaml/resource/PipelineYamlResourceManager.kt
@Service
class PipelineYamlResourceManager(
private val pipelineYamlResourceService: PipelineYamlResourceService,
@Lazy private val pTemplateYamlResourceService: PTemplateYamlResourceService
) {
/**
* 根据 isTemplate 标志选择对应的服务
*/
fun getService(isTemplate: Boolean): IPipelineYamlResourceService {
return if (isTemplate) {
pTemplateYamlResourceService // 模板 YAML 服务
} else {
pipelineYamlResourceService // 流水线 YAML 服务
}
}
fun createYamlPipeline(userId: String, projectId: String, yaml: String, event: PipelineYamlFileEvent) =
getService(event.isTemplate).createYamlPipeline(userId, projectId, yaml, event)
fun updateYamlPipeline(userId: String, projectId: String, pipelineId: String, yaml: String, event: PipelineYamlFileEvent) =
getService(event.isTemplate).updateYamlPipeline(userId, projectId, pipelineId, yaml, event)
}
```
### 5.4 YAML Webhook 请求处理
#### 5.4.1 PipelineTemplateYamlWebhookReq（请求对象）
```kotlin
// 文件: process/api-process/.../pojo/template/v2/PipelineTemplateYamlWebhookReq.kt
@Schema(title = "模版yaml文件推送请求")
data class PipelineTemplateYamlWebhookReq(
@get:Schema(title = "模板YAML", required = true)
val yaml: String,
@get:Schema(title = "yaml文件名", required = true)
val yamlFileName: String,
@get:Schema(title = "分支名", required = true)
val branchName: String,
@get:Schema(title = "是否默认分支", required = true)
val isDefaultBranch: Boolean,
@get:Schema(title = "描述", required = true)
val description: String? = null,
@get:Schema(title = "yaml文件信息", required = true)
val yamlFileInfo: PipelineYamlFileInfo? = null
) : PipelineTemplateVersionReq // 继承版本请求接口
```
#### 5.4.2 PipelineTemplateYamlWebhookReqConverter（请求转换器）
```kotlin
// 文件: process/biz-process/.../version/convert/PipelineTemplateYamlWebhookReqConverter.kt
@Service
class PipelineTemplateYamlWebhookReqConverter(
private val pipelineTemplateGenerator: PipelineTemplateGenerator,
private val pipelineTemplateInfoService: PipelineTemplateInfoService
) : PipelineTemplateVersionReqConverter {
override fun support(request: PipelineTemplateVersionReq) =
request is PipelineTemplateYamlWebhookReq
override fun convert(
userId: String,
projectId: String,
templateId: String?,
version: Long?,
request: PipelineTemplateVersionReq
): PipelineTemplateVersionCreateContext {
request as PipelineTemplateYamlWebhookReq
// 1. YAML 转 Model
val transferResult = pipelineTemplateGenerator.transfer(
userId = userId,
projectId = projectId,
storageType = PipelineStorageType.YAML,
yaml = request.yaml
)
// 2. 根据是否默认分支决定版本状态
val (status, versionAction) = if (request.isDefaultBranch) {
Pair(VersionStatus.RELEASED, PipelineVersionAction.CREATE_RELEASE)
} else {
Pair(VersionStatus.BRANCH, PipelineVersionAction.CREATE_BRANCH)
}
// 3. 模板名称优先级：setting > model > fileName
val templateName = transferResult.templateSetting.pipelineName
.takeIf { it.isNotBlank() }
?: (transferResult.templateModel as? Model)?.name?.ifBlank { request.yamlFileName }
?: request.yamlFileName
// 4. 构建上下文
return PipelineTemplateVersionCreateContext(
userId = userId,
projectId = projectId,
templateId = templateId ?: pipelineTemplateGenerator.generateTemplateId(),
versionAction = versionAction,
newTemplate = templateId == null,
enablePac = true, // 标记为 PAC 模板
yamlFileInfo = request.yamlFileInfo,
branchName = request.branchName
)
}
}
```
### 5.5 Model ↔ YAML 转换
#### 5.5.1 PipelineTemplateGenerator（模板生成器）
```kotlin
// 文件: process/biz-process/.../service/template/v2/PipelineTemplateGenerator.kt
@Service
class PipelineTemplateGenerator(
private val transferService: PipelineTransferYamlService
) {
/**
* 双向转换：Model ↔ YAML
*/
fun transfer(
userId: String,
projectId: String,
storageType: PipelineStorageType,
templateType: PipelineTemplateType?,
templateModel: ITemplateModel?,
templateSetting: PipelineSetting?,
params: List<BuildFormProperty>?,
yaml: String?,
fallbackOnError: Boolean = false
): PTemplateModelTransferResult {
return if (storageType == PipelineStorageType.YAML) {
// YAML → Model
transferYamlToModel(userId, projectId, templateType, params, yaml)
} else {
// Model → YAML
transferModelToYamlWithFallback(
userId, projectId, templateType,
templateModel, templateSetting, params, fallbackOnError
)
}
}
/**
* YAML → Model 转换
*/
private fun transferYamlToModel(...): PTemplateModelTransferResult {
val transferResult = transferService.transfer(
userId = userId,
projectId = projectId,
actionType = TransferActionType.TEMPLATE_YAML2MODEL_PIPELINE,
data = TransferBody(oldYaml = yaml)
)
return PTemplateModelTransferResult(
templateType = templateType ?: PipelineTemplateType.PIPELINE,
templateModel = transferResult.templateModelAndSetting?.templateModel,
templateSetting = transferResult.templateModelAndSetting?.setting,
yamlWithVersion = transferResult.yamlWithVersion
)
}
/**
* Model → YAML 转换（带异常兜底）
*/
private fun transferModelToYamlWithFallback(...): PTemplateModelTransferResult {
val actionType = getTransferActionType(templateType)
// TransferActionType 根据模板类型选择：
// PIPELINE → TEMPLATE_MODEL2YAML_PIPELINE
// STAGE → TEMPLATE_MODEL2YAML_STAGE
// JOB → TEMPLATE_MODEL2YAML_JOB
// STEP → TEMPLATE_MODEL2YAML_STEP
return try {
val result = transferService.transfer(
actionType = actionType,
data = TransferBody(
templateModelAndSetting = TemplateModelAndSetting(templateModel, templateSetting)
)
)
PTemplateModelTransferResult(yamlWithVersion = result.yamlWithVersion, ...)
} catch (ex: Exception) {
if (fallbackOnError) {
// 兜底：返回原始 Model，YAML 为空
PTemplateModelTransferResult(yamlWithVersion = null, ...)
} else {
throw ex
}
}
}
}
```
#### 5.5.2 TransferActionType（转换动作类型）
```kotlin
// 转换动作类型枚举
enum class TransferActionType {
// 模板 YAML → Model
TEMPLATE_YAML2MODEL_PIPELINE,
// 模板 Model → YAML（按模板类型）
TEMPLATE_MODEL2YAML_PIPELINE,
TEMPLATE_MODEL2YAML_STAGE,
TEMPLATE_MODEL2YAML_JOB,
TEMPLATE_MODEL2YAML_STEP,
// 完整转换（包含设置）
FULL_MODEL2YAML,
FULL_YAML2MODEL
}
```
### 5.6 PAC 版本状态
```kotlin
// 版本状态枚举
enum class VersionStatus {
COMMITTING, // 草稿状态
RELEASED, // 已发布（默认分支）
BRANCH // 分支版本（非默认分支）
}
```
| 状态 | 触发场景 | 说明 |
|------|----------|------|
| `RELEASED` | 推送到默认分支 | 正式发布版本 |
| `BRANCH` | 推送到非默认分支 | 分支版本，可用于测试 |
| `COMMITTING` | UI 保存草稿 | 草稿状态，未发布 |
### 5.7 PAC 版本生成
```kotlin
// 文件: PipelineTemplateGenerator.kt
/**
* 生成分支版本
*/
fun generateBranchVersion(
projectId: String,
templateId: String,
branchName: String
): PTemplateResourceOnlyVersion {
val latestResource = pipelineTemplateResourceService.getLatestVersionResource(projectId, templateId)
// 如果已存在同名分支版本，基于分支版本创建
val branchResource = pipelineTemplateResourceService.getLatestBranchResource(
projectId, templateId, branchName
)
return PTemplateResourceOnlyVersion(
version = generateTemplateVersion(),
number = latestResource.number + 1,
versionName = branchName, // 分支版本名 = 分支名
baseVersion = branchResource?.version ?: latestResource.version
)
}
/**
* 草稿发布时的 PAC 版本生成
*/
fun generateDraftReleaseVersionWithPac(
projectId: String,
templateId: String,
draftResource: PipelineTemplateResource,
repoHashId: String,
targetAction: CodeTargetAction?,
targetBranch: String?
): Pair<VersionStatus, PTemplateResourceOnlyVersion> {
return when (targetAction) {
// 直接提交到主分支 → 发布版本
CodeTargetAction.COMMIT_TO_MASTER -> {
Pair(VersionStatus.RELEASED, generateReleaseVersion(...))
}
// 提交到源分支 → 分支版本
CodeTargetAction.COMMIT_TO_SOURCE_BRANCH -> {
Pair(VersionStatus.BRANCH, ...)
}
// 新建分支并提交 → 分支版本
CodeTargetAction.CHECKOUT_BRANCH_AND_REQUEST_MERGE -> {
val versionName = "bk-ci-template-$templateId-${draftResource.number}"
Pair(VersionStatus.BRANCH, ...)
}
// 提交到指定分支
CodeTargetAction.COMMIT_TO_BRANCH -> {
// 如果是默认分支 → 发布版本
// 否则 → 分支版本
}
}
}
```
### 5.8 PAC 目录结构
```
src/backend/ci/core/process/biz-process/src/main/kotlin/com/tencent/devops/process/
├── yaml/
│ ├── resource/
│ │ ├── IPipelineYamlResourceService.kt # YAML 资源服务接口
│ │ ├── PipelineYamlResourceService.kt # 流水线 YAML 服务
│ │ ├── PTemplateYamlResourceService.kt # 模板 YAML 服务
│ │ └── PipelineYamlResourceManager.kt # 统一管理器
│ ├── mq/
│ │ └── PipelineYamlFileEvent.kt # YAML 文件事件
│ ├── PipelineYamlFileManager.kt # YAML 文件管理
│ ├── PipelineYamlFacadeService.kt # YAML 门面服务
│ └── PipelineYamlSyncService.kt # YAML 同步服务
├── service/template/
│ ├── TemplatePACService.kt # V1 PAC 服务
│ └── v2/
│ ├── PipelineTemplateGenerator.kt # 模板生成器（含转换）
│ └── version/convert/
│ └── PipelineTemplateYamlWebhookReqConverter.kt # Webhook 转换器
└── common/common-pipeline-yaml/ # YAML 解析公共库
└── src/main/kotlin/.../yaml/
├── v2/parsers/template/
│ ├── TemplateYamlMapper.kt # YAML 映射
│ └── TemplateYamlUtil.kt # YAML 工具
└── v3/parsers/template/
├── TemplateYamlMapper.kt
└── TemplateYamlUtil.kt
```
### 5.9 PAC 完整流程
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ PAC 模板创建/更新流程 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌──────────────────┐ ┌─────────────────────────┐ │
│ │ Git Push │───▶│ Webhook Event │───▶│ PipelineYamlFileEvent │ │
│ │ (YAML文件) │ │ (代码仓库触发) │ │ (isTemplate=true) │ │
│ └─────────────┘ └──────────────────┘ └───────────┬─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ PipelineYamlResourceManager │ │
│ │ (根据 isTemplate 路由) │ │
│ └───────────────────────────────┬─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ PTemplateYamlResourceService │ │
│ │ (模板 YAML 资源服务) │ │
│ └───────────────────────────────┬─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ PipelineTemplateFacadeService.createYamlTemplate() │ │
│ │ 构建 PipelineTemplateYamlWebhookReq │ │
│ └───────────────────────────────┬─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ PipelineTemplateVersionManager │ │
│ │ deployTemplate() │ │
│ └───────────────────────────────┬─────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────────┼────────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌────────────────────┐ ┌───────────────────┐ │
│ │ Converter │───▶│ Validator │───▶│ Handler │ │
│ │ (YAML→Model)│ │ (校验模板) │ │ (创建/更新版本) │ │
│ └─────────────┘ └────────────────────┘ └─────────┬─────────┘ │
│ │ │
│ ┌───────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 默认分支？ │ │
│ │ ├── YES → VersionStatus.RELEASED → 正式版本 │ │
│ │ └── NO → VersionStatus.BRANCH → 分支版本 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
### 5.10 PAC 最佳实践
#### 5.10.1 模板 YAML 文件命名
- 文件路径：`.ci/templates/xxx.yml` 或 `.ci/templates/xxx.yaml`
- 模板名称默认从 YAML 中的 `name` 字段获取，若无则使用文件名
#### 5.10.2 分支策略
| 分支类型 | 版本状态 | 使用场景 |
|----------|----------|----------|
| 默认分支（main/master） | `RELEASED` | 正式发布，可被实例化 |
| 特性分支 | `BRANCH` | 开发测试，不影响正式版本 |
| PR 分支 | `BRANCH` | 代码审查，合并后自动发布 |
#### 5.10.3 enablePac 标志
```kotlin
// 模板信息中的 PAC 标志
data class PipelineTemplateInfoV2(
val id: String,
val projectId: String,
val name: String,
val enablePac: Boolean = false, // 是否启用 PAC
// ...
)
```
- `enablePac = true`：模板由 YAML 文件管理，UI 编辑会同步到代码仓库
- `enablePac = false`：传统模板，仅在 BK-CI 内管理
---
## 六、研发商店集成
### 6.1 Store 模块模板服务
```
src/backend/ci/core/store/biz-store/src/main/kotlin/com/tencent/devops/store/template/
├── service/
│ ├── MarketTemplateService.kt # 商店模板服务接口
│ ├── MarketTemplateServiceImpl.kt # 商店模板服务实现
│ ├── TemplateReleaseService.kt # 模板发布服务接口
│ ├── TemplateReleaseServiceImpl.kt # 模板发布服务实现
│ ├── OpTemplateService.kt # 运营模板服务接口
│ └── OpTemplateServiceImpl.kt # 运营模板服务实现
└── dao/
├── MarketTemplateDao.kt # 商店模板 DAO
├── TemplateCategoryRelDao.kt # 模板分类关联 DAO
└── TemplateLabelRelDao.kt # 模板标签关联 DAO
```
### 6.2 商店模板数据库表
```sql
-- Store 模块的模板表
CREATE TABLE IF NOT EXISTS `T_TEMPLATE` (
`ID` varchar(32) NOT NULL COMMENT '主键ID',
`TEMPLATE_NAME` varchar(200) NOT NULL COMMENT '模板名称',
`TEMPLATE_CODE` varchar(64) NOT NULL COMMENT '模板代码',
`CLASSIFY_ID` varchar(32) NOT NULL COMMENT '分类ID',
`VERSION` varchar(20) NOT NULL COMMENT '版本号',
`TEMPLATE_TYPE` tinyint(4) NOT NULL DEFAULT '1' COMMENT '模板类型',
`TEMPLATE_STATUS` tinyint(4) NOT NULL COMMENT '模板状态',
`TEMPLATE_STATUS_MSG` varchar(1024) DEFAULT NULL COMMENT '状态信息',
`LOGO_URL` varchar(256) DEFAULT NULL COMMENT 'Logo地址',
`SUMMARY` varchar(256) DEFAULT NULL COMMENT '简介',
`DESCRIPTION` text COMMENT '描述',
`PUBLISHER` varchar(50) NOT NULL COMMENT '发布者',
`PUB_DESCRIPTION` text COMMENT '发布描述',
`PUBLIC_FLAG` bit(1) NOT NULL DEFAULT b'0' COMMENT '是否公开',
`LATEST_FLAG` bit(1) NOT NULL COMMENT '是否最新',
`CREATOR` varchar(50) NOT NULL COMMENT '创建者',
`MODIFIER` varchar(50) NOT NULL COMMENT '修改者',
`CREATE_TIME` datetime NOT NULL COMMENT '创建时间',
`UPDATE_TIME` datetime NOT NULL COMMENT '更新时间',
PRIMARY KEY (`ID`),
UNIQUE KEY `UNI_TEMPLATE_CODE_VERSION` (`TEMPLATE_CODE`, `VERSION`)
);
```
### 6.3 模板安装流程
```kotlin
// 从商店安装模板到项目
fun installTemplateFromStore(
userId: String,
projectId: String,
templateCode: String,
version: String
): String {
// 1. 获取商店模板信息
val storeTemplate = marketTemplateService.getTemplateByCode(templateCode, version)
// 2. 获取模板模型
val templateModel = storeTemplate.templateModel
// 3. 创建项目模板（类型为 CONSTRAINT）
val templateId = templateFacadeService.createTemplate(
projectId = projectId,
userId = userId,
template = templateModel,
templateType = TemplateType.CONSTRAINT
)
// 4. 记录安装历史
templateVersionInstallHistoryDao.create(
projectId = projectId,
templateId = templateId,
templateCode = templateCode,
version = version,
userId = userId
)
return templateId
}
```
---
## 七、事件驱动机制
### 7.1 模板相关事件
```kotlin
// 文件: process/biz-base/.../engine/pojo/event/
// 模板实例化事件
data class PipelineTemplateInstanceEvent(
val source: String,
val projectId: String,
val templateId: String,
val version: Long,
val instanceBaseId: String,
val userId: String
) : IEvent
// 模板迁移事件
data class PipelineTemplateMigrateEvent(
val source: String,
val projectId: String,
val templateId: String,
val userId: String
) : IEvent
// 模板触发器升级事件
data class PipelineTemplateTriggerUpgradesEvent(
val source: String,
val projectId: String,
val templateId: String,
val version: Long,
val userId: String
) : IEvent
```
### 7.2 事件监听器
```kotlin
// 文件: process/biz-process/.../service/template/v2/PipelineTemplateInstanceListener.kt
@Service
class PipelineTemplateInstanceListener(
private val pipelineTemplateInstanceService: PipelineTemplateInstanceService
) {
@StreamListener(PipelineTemplateInstanceEvent.TOPIC)
fun onTemplateInstance(event: PipelineTemplateInstanceEvent) {
// 处理异步批量实例化
pipelineTemplateInstanceService.processAsyncInstance(
projectId = event.projectId,
templateId = event.templateId,
version = event.version,
instanceBaseId = event.instanceBaseId,
userId = event.userId
)
}
}
```
---
## 八、分布式锁
### 8.1 模板相关锁
```kotlin
// 文件: process/biz-base/.../engine/control/lock/
// 实例计数锁 - 防止并发实例化时计数错误
class PipelineTemplateInstanceCountLock(
private val redisOperation: RedisOperation,
private val templateId: String
) : BaseLock(redisOperation, "template:instance:count:$templateId")
// 触发器升级锁 - 防止并发升级触发器
class PipelineTemplateTriggerUpgradesLock(
private val redisOperation: RedisOperation,
private val templateId: String
) : BaseLock(redisOperation, "template:trigger:upgrade:$templateId")
```
```kotlin
// 文件: process/biz-process/.../service/template/v2/
// V2 实例化锁
class PipelineTemplateInstanceLock(
private val redisOperation: RedisOperation,
private val templateId: String,
private val pipelineId: String
) : BaseLock(redisOperation, "template:v2:instance:$templateId:$pipelineId")
// V2 模型锁
class PipelineTemplateModelLock(
private val redisOperation: RedisOperation,
private val templateId: String
) : BaseLock(redisOperation, "template:v2:model:$templateId")
```
---
## 九、OpenAPI 接口
### 9.1 API 网关接口
```
src/backend/ci/core/openapi/api-openapi/src/main/kotlin/com/tencent/devops/openapi/api/apigw/
├── v3/
│ ├── ApigwTemplateResourceV3.kt # V3 模板接口
│ ├── ApigwTemplateInstanceResourceV3.kt # V3 实例化接口
│ └── ApigwMarketTemplateResourceV3.kt # V3 商店模板接口
└── v4/
├── ApigwTemplateResourceV4.kt # V4 模板接口
├── ApigwTemplateInstanceResourceV4.kt # V4 实例化接口
└── ApigwMarketTemplateResourceV4.kt # V4 商店模板接口
```
### 9.2 主要 API 端点
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/v4/projects/{projectId}/templates` | 创建模板 |
| GET | `/v4/projects/{projectId}/templates` | 获取模板列表 |
| GET | `/v4/projects/{projectId}/templates/{templateId}` | 获取模板详情 |
| PUT | `/v4/projects/{projectId}/templates/{templateId}` | 更新模板 |
| DELETE | `/v4/projects/{projectId}/templates/{templateId}` | 删除模板 |
| POST | `/v4/projects/{projectId}/templates/{templateId}/instances` | 实例化模板 |
| GET | `/v4/projects/{projectId}/templates/{templateId}/instances` | 获取实例列表 |
| GET | `/v4/projects/{projectId}/templates/{templateId}/versions` | 获取版本列表 |
---
## 十、最佳实践
### 10.1 新增模板功能
1. **API 层**：在 `api/template/v2/` 下定义接口
2. **POJO 层**：在 `pojo/template/v2/` 下定义请求/响应对象
3. **Service 层**：在 `service/template/v2/` 下实现业务逻辑
4. **DAO 层**：在 `dao/template/` 下实现数据访问
5. **权限控制**：调用 `PipelineTemplatePermissionService` 进行权限校验
### 10.2 版本管理扩展
如需新增版本操作类型：
1. 在 `PipelineVersionAction` 枚举中添加新操作
2. 实现 `PipelineTemplateVersionReqConverter` 转换器
3. 实现 `PipelineTemplateVersionCreateHandler` 处理器
4. 可选：实现 `PTemplateVersionPostProcessor` 后处理器
### 10.3 商店集成扩展
1. 在 Store 模块的 `template/service/` 下实现服务
2. 调用 Process 模块的模板服务进行模板操作
3. 维护商店特有的元数据（分类、标签、评论等）
---
## 十一、常见问题
### Q1: V1 和 V2 版本如何选择？
- 新功能开发优先使用 V2 版本
- V1 版本用于兼容老数据和简单场景
- V2 版本支持草稿、PAC、完善的版本管理
### Q2: 模板实例化失败如何排查？
1. 检查模板是否存在且版本正确
2. 检查用户是否有创建流水线权限
3. 检查模板参数是否完整
4. 查看 `T_TEMPLATE_INSTANCE_ITEM` 表中的错误信息
### Q3: 如何实现模板的批量更新？
使用异步实例化接口：
1. 调用 `createAsyncTemplateInstances` 创建异步任务
2. 系统通过 MQ 事件异步处理每个实例
3. 通过 `getTemplateInstanceStatus` 查询进度
### Q4: 模板权限如何配置？
1. 项目级别开关：`enableTemplatePermissionManage`
2. 权限类型：CREATE、EDIT、DELETE、LIST
3. 与蓝鲸权限中心集成，支持 RBAC 模型
### Q5: PAC 模板和普通模板有什么区别？
| 特性 | PAC 模板 | 普通模板 |
|------|----------|----------|
| 存储方式 | Git 仓库 YAML 文件 | BK-CI 数据库 |
| 编辑方式 | 代码编辑器 / IDE | BK-CI UI |
| 版本管理 | Git 分支 | BK-CI 版本号 |
| 同步机制 | Webhook 自动同步 | 手动保存 |
| 协作方式 | Git 工作流（PR/MR） | BK-CI 权限控制 |
| 回滚方式 | Git revert | BK-CI 版本回滚 |
### Q6: PAC 模板的 YAML 转换失败怎么办？
1. 检查 YAML 语法是否正确
2. 确认使用的是支持的 YAML 版本（v2/v3）
3. 查看 `PipelineTemplateGenerator.transfer()` 的异常日志
4. 使用 `fallbackOnError=true` 可以在转换失败时返回原始 Model
### Q7: 如何启用模板的 PAC 功能？
1. 在代码仓库中创建 `.ci/templates/xxx.yml` 文件
2. 配置 Webhook 触发器
3. 推送代码后自动创建/更新模板
4. 模板的 `enablePac` 标志会自动设为 `true`
### Q8: 分支版本和正式版本的关系？
- 推送到**默认分支**（main/master）→ 创建 `RELEASED` 正式版本
- 推送到**其他分支** → 创建 `BRANCH` 分支版本
- 分支版本可用于测试，不影响正式版本
- 分支合并到默认分支后，自动发布为正式版本
---
## 十二、相关 Skill
| Skill | 说明 |
|-------|------|
| `22-yaml-pipeline-transfer` | YAML 流水线转换，理解 Model ↔ YAML 转换机制 |
| `28-pipeline-model-architecture` | 流水线模型架构，理解模板的模型结构 |
| `29-process-module-architecture` | Process 模块架构，理解模板所在模块 |
| `30-auth-module-architecture` | 权限模块架构，理解模板权限控制 |
| `33-store-module-architecture` | 研发商店架构，理解模板商店集成 |
| `08-event-driven-architecture` | 事件驱动架构，理解异步实例化机制 |
| `10-distributed-lock` | 分布式锁，理解模板并发控制 |
Name Size