Store 研发商店模块架构指南
模块定位: Store 是 BK-CI 的研发商店模块，负责管理流水线插件（Atom）、流水线模板（Template）、容器镜像（Image）等可复用组件的发布、审核、安装、统计等全生命周期管理。
一、模块整体结构
1.1 子模块划分
src/backend/ci/core/store/
├── api-store/ # API 接口定义层
│ └── src/main/kotlin/com/tencent/devops/store/
│ ├── api/
│ │ ├── atom/ # 插件相关接口（25+ 文件）
│ │ ├── common/ # 通用接口（40+ 文件）
│ │ ├── container/ # 容器相关接口
│ │ ├── image/ # 镜像相关接口
│ │ └── template/ # 模板相关接口
│ ├── constant/ # 常量和消息码
│ └── pojo/ # 数据对象（100+ 文件）
│ ├── app/ # 应用相关
│ ├── atom/ # 插件相关
│ ├── common/ # 通用对象
│ ├── image/ # 镜像相关
│ └── template/ # 模板相关
│
├── biz-store/ # 业务逻辑层
│ └── src/main/kotlin/com/tencent/devops/store/
│ ├── atom/ # 插件业务
│ │ ├── dao/ # 插件数据访问
│ │ ├── factory/ # 工厂类
│ │ ├── resources/ # API 实现
│ │ └── service/ # 插件服务
│ ├── common/ # 通用业务
│ │ ├── dao/ # 通用数据访问（60+ 文件）
│ │ ├── handler/ # 处理器链
│ │ ├── resources/ # API 实现
│ │ └── service/ # 通用服务
│ ├── image/ # 镜像业务
│ └── template/ # 模板业务
│
├── model-store/ # 数据模型层（JOOQ 生成）
└── boot-store/ # Spring Boot 启动模块
1.2 Store 组件类型
| 类型 | 枚举值 | 说明 | 核心表 |
|---|
| 插件（Atom） | ATOM | 流水线可执行插件 | T_ATOM |
| 模板（Template） | TEMPLATE | 流水线模板 | T_TEMPLATE |
| 镜像（Image） | IMAGE | 容器构建镜像 | T_IMAGE |
二、核心概念
2.1 插件（Atom）模型
┌─────────────────────────────────────────────────────────────────────────┐
│ 插件模型 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ T_ATOM（插件主表） │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ ATOM_CODE │ │ NAME │ │ VERSION │ │ │
│ │ │ (插件标识) │ │ (插件名称) │ │ (版本号) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ ATOM_STATUS │ │ CLASS_TYPE │ │ LATEST_FLAG │ │ │
│ │ │ (插件状态) │ │ (插件大类) │ │ (最新版本) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────┼────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
│ │ T_ATOM_ENV_ │ │ T_ATOM_ │ │ T_ATOM_ │ │
│ │ INFO │ │ FEATURE │ │ VERSION_LOG │ │
│ │ (执行环境信息) │ │ (特性配置) │ │ (版本日志) │ │
│ └───────────────┘ └───────────────┘ └───────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.2 插件核心字段
| 字段 | 类型 | 说明 |
|---|
ID | String | 插件版本 ID（UUID） |
ATOM_CODE | String | 插件唯一标识（不变） |
NAME | String | 插件名称 |
VERSION | String | 版本号（如 1.0.0） |
ATOM_STATUS | Int | 插件状态 |
CLASS_TYPE | String | 插件大类（marketBuild 等） |
JOB_TYPE | String | 适用 Job 类型（AGENT/AGENT_LESS） |
OS | String | 支持的操作系统 |
CLASSIFY_ID | String | 分类 ID |
LATEST_FLAG | Boolean | 是否最新版本 |
DEFAULT_FLAG | Boolean | 是否默认插件 |
PUBLISHER | String | 发布者 |
REPOSITORY_HASH_ID | String | 代码库 HashId |
2.3 插件状态流转
enum class AtomStatusEnum(val status: Int) {
INIT(0), // 初始化
COMMITTING(1), // 提交中
BUILDING(2), // 构建中
BUILD_FAIL(3), // 构建失败
TESTING(4), // 测试中
AUDITING(5), // 审核中
AUDIT_REJECT(6), // 审核驳回
RELEASED(7), // 已发布
GROUNDING_SUSPENSION(8), // 上架中止
UNDERCARRIAGING(9), // 下架中
UNDERCARRIAGED(10), // 已下架
}
┌─────────────────────────────────────────────────────────────────┐
│ 插件状态流转图 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ INIT ──► COMMITTING ──► BUILDING ──► TESTING ──► AUDITING │
│ │ │ │
│ ▼ ▼ │
│ BUILD_FAIL AUDIT_REJECT │
│ │ │
│ ▼ │
│ RELEASED │
│ │ │
│ ▼ │
│ UNDERCARRIAGING │
│ │ │
│ ▼ │
│ UNDERCARRIAGED │
│ │
└─────────────────────────────────────────────────────────────────┘
2.4 插件分类
// 插件大类
enum class AtomTypeEnum(val type: Int) {
SELF_DEVELOPED(0), // 自研
THIRD_PARTY(1), // 第三方
}
// Job 类型
enum class JobTypeEnum(val type: String) {
AGENT("AGENT"), // 有构建环境
AGENT_LESS("AGENT_LESS"), // 无构建环境
}
三、核心数据库表
3.1 插件相关表
| 表名 | 说明 | 核心字段 |
|---|
T_ATOM | 插件主表 | ATOM_CODE, NAME, VERSION, ATOM_STATUS, LATEST_FLAG |
T_ATOM_ENV_INFO | 插件执行环境 | ATOM_ID, PKG_PATH, LANGUAGE, TARGET |
T_ATOM_FEATURE | 插件特性 | ATOM_CODE, VISIBILITY_LEVEL, YAML_FLAG, QUALITY_FLAG |
T_ATOM_BUILD_INFO | 插件构建信息 | LANGUAGE, SCRIPT, SAMPLE_PROJECT_PATH |
T_ATOM_VERSION_LOG | 版本日志 | ATOM_ID, RELEASE_TYPE, CONTENT |
T_ATOM_LABEL_REL | 插件标签关联 | ATOM_ID, LABEL_ID |
T_ATOM_OFFLINE | 插件下架记录 | ATOM_CODE, EXPIRE_TIME, STATUS |
3.2 模板相关表
| 表名 | 说明 | 核心字段 |
|---|
T_TEMPLATE | 模板主表 | TEMPLATE_CODE, TEMPLATE_NAME, VERSION, TEMPLATE_STATUS |
T_TEMPLATE_CATEGORY_REL | 模板分类关联 | TEMPLATE_ID, CATEGORY_ID |
T_TEMPLATE_LABEL_REL | 模板标签关联 | TEMPLATE_ID, LABEL_ID |
3.3 镜像相关表
| 表名 | 说明 | 核心字段 |
|---|
T_IMAGE | 镜像主表 | IMAGE_CODE, IMAGE_NAME, VERSION, IMAGE_STATUS |
T_IMAGE_CATEGORY_REL | 镜像分类关联 | IMAGE_ID, CATEGORY_ID |
T_IMAGE_LABEL_REL | 镜像标签关联 | IMAGE_ID, LABEL_ID |
3.4 通用表
| 表名 | 说明 |
|---|
T_CLASSIFY | 分类表 |
T_CATEGORY | 范畴表 |
T_LABEL | 标签表 |
T_STORE_MEMBER | 组件成员表 |
T_STORE_PROJECT_REL | 组件项目关联表 |
T_STORE_COMMENT | 评论表 |
T_STORE_COMMENT_REPLY | 评论回复表 |
T_STORE_COMMENT_PRAISE | 评论点赞表 |
T_STORE_STATISTICS | 统计表 |
T_STORE_APPROVE | 审批表 |
T_STORE_SENSITIVE_API | 敏感 API 表 |
T_STORE_SENSITIVE_CONF | 敏感配置表 |
3.5 容器编译环境表
| 表名 | 说明 |
|---|
T_APPS | 编译环境信息表 |
T_APP_ENV | 编译环境变量表 |
T_APP_VERSION | 编译环境版本表 |
T_CONTAINER | 容器信息表 |
T_BUILD_RESOURCE | 构建资源表 |
四、分层架构
┌─────────────────────────────────────────────────────────────────────────┐
│ 请求入口 │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ API 层 (api-store) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │UserMarket │ │ServiceAtom │ │UserTemplate │ │UserImage │ │
│ │AtomResource │ │Resource │ │Resource │ │Resource │ │
│ │(用户插件管理) │ │(服务间调用) │ │(模板管理) │ │(镜像管理) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │UserAtom │ │OpAtom │ │UserStore │ │
│ │ReleaseRes │ │Resource │ │MemberRes │ │
│ │(插件发布) │ │(运维管理) │ │(成员管理) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 业务层 (biz-store) │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ 插件服务 (atom/service/) │ │
│ │ MarketAtomService - 插件市场服务 │ │
│ │ AtomReleaseService - 插件发布服务 │ │
│ │ AtomService - 插件基础服务 │ │
│ │ MarketAtomEnvService - 插件环境服务 │ │
│ │ MarketAtomArchiveService - 插件归档服务 │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ 通用服务 (common/service/) │ │
│ │ StoreCommentService - 评论服务 │ │
│ │ StoreMemberService - 成员管理服务 │ │
│ │ StoreProjectService - 项目关联服务 │ │
│ │ StoreStatisticService - 统计服务 │ │
│ │ StoreApproveService - 审批服务 │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ 处理器链 (common/handler/) │ │
│ │ StoreCreateHandlerChain - 创建处理器链 │ │
│ │ StoreUpdateHandlerChain - 更新处理器链 │ │
│ │ StoreDeleteHandlerChain - 删除处理器链 │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ DAO 层 (biz-store/dao) │
│ AtomDao (59KB) | MarketAtomDao (31KB) | StoreProjectRelDao (25KB) │
│ StoreBaseQueryDao (20KB) | MarketAtomEnvInfoDao | ... │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 数据层 (model-store + MySQL) │
│ 数据库：devops_ci_store（共 50+ 张表） │
└─────────────────────────────────────────────────────────────────────────┘
五、核心类速查
5.1 API 接口层
| 类名 | 路径前缀 | 职责 |
|---|
UserMarketAtomResource | /user/market/atom | 用户插件市场操作 |
UserAtomReleaseResource | /user/market/atom/release | 插件发布 |
ServiceAtomResource | /service/atoms | 服务间插件查询 |
ServiceMarketAtomResource | /service/market/atom | 服务间市场插件 |
OpAtomResource | /op/market/atom | 运维插件管理 |
UserTemplateResource | /user/market/template | 模板管理 |
UserMarketImageResource | /user/market/image | 镜像管理 |
UserStoreMemberResource | /user/store/member | 成员管理 |
5.2 Service 层
| 类名 | 职责 |
|---|
MarketAtomService | 插件市场核心服务 |
AtomReleaseService | 插件发布流程 |
AtomService | 插件基础操作 |
MarketAtomEnvService | 插件执行环境 |
MarketAtomArchiveService | 插件归档 |
AtomCooperationService | 插件协作 |
AtomNotifyService | 插件通知 |
5.3 DAO 层
| 类名 | 文件大小 | 职责 |
|---|
AtomDao | 59KB | 插件主表访问（最大） |
MarketAtomDao | 31KB | 市场插件访问 |
StoreProjectRelDao | 25KB | 项目关联访问 |
StoreBaseQueryDao | 20KB | 基础查询 |
MarketAtomEnvInfoDao | 13KB | 插件环境访问 |
六、核心流程
6.1 插件发布流程
开发者提交发布请求
│
▼
UserAtomReleaseResource.createAtom()
│
▼
AtomReleaseService.handleAtomRelease()
│
├─► 参数校验
│ ├─► 校验插件代码唯一性
│ ├─► 校验版本号格式
│ └─► 校验代码库权限
│
├─► 创建插件记录
│ ├─► atomDao.create()
│ └─► 状态设为 INIT
│
├─► 触发构建流水线
│ └─► 调用 Process 模块构建插件包
│
├─► 构建完成回调
│ ├─► 更新状态为 TESTING
│ └─► 上传插件包到制品库
│
├─► 提交审核
│ └─► 状态设为 AUDITING
│
└─► 审核通过
├─► 状态设为 RELEASED
└─► 更新 LATEST_FLAG
6.2 插件安装流程
用户安装插件到项目
│
▼
UserMarketAtomResource.installAtom()
│
▼
MarketAtomService.installAtom()
│
├─► 权限校验
│ └─► 检查用户是否有项目权限
│
├─► 检查插件可见性
│ └─► 检查项目是否在可见范围内
│
├─► 创建关联记录
│ └─► storeProjectRelDao.create()
│
└─► 更新统计数据
└─► 增加安装量
6.3 处理器链模式
Store 模块使用责任链模式处理组件的创建、更新、删除：
// 创建处理器链
class StoreCreateHandlerChain {
private val handlers = listOf(
StoreCreateParamCheckHandler, // 参数校验
StoreCreatePreBusHandler, // 前置业务处理
StoreCreateDataPersistHandler, // 数据持久化
StoreCreatePostBusHandler // 后置业务处理
)
fun handle(context: StoreContext) {
handlers.forEach { it.handle(context) }
}
}
七、与其他模块的关系
7.1 依赖关系
┌─────────────────────────────────────────────────────────────────┐
│ Store 模块依赖关系 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────┐ │
│ │ store │ │
│ └───────┬───────┘ │
│ │ │
│ ┌──────────────────┼──────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ project │ │repository │ │artifactory│ │
│ │ (项目信息) │ │ (代码库) │ │ (制品库) │ │
│ └───────────┘ └───────────┘ └───────────┘ │
│ │
│ 被依赖： │
│ - process（流水线使用插件） │
│ - worker（构建机执行插件） │
└─────────────────────────────────────────────────────────────────┘
7.2 服务间调用示例
// Process 模块获取插件信息
// 注意：projectCode 是 T_PROJECT.english_name
client.get(ServiceAtomResource::class).getAtomByCode(
atomCode = atomCode,
username = userId
)
// 获取插件执行环境
client.get(ServiceMarketAtomEnvResource::class).getAtomEnv(
projectCode = projectId, // english_name
atomCode = atomCode,
atomVersion = version
)
// 获取项目可用的插件列表
client.get(ServiceMarketAtomResource::class).getProjectElements(
projectCode = projectId
)
八、插件开发规范
8.1 插件目录结构
my-atom/
├── task.json # 插件配置文件
├── README.md # 插件说明
├── src/ # 源代码
│ └── main.py # 入口文件
├── requirements.txt # Python 依赖
└── logo.png # 插件图标
8.2 task.json 配置
{
"atomCode": "myAtom",
"execution": {
"language": "python",
"packagePath": "src/",
"target": "main.py"
},
"input": {
"param1": {
"label": "参数1",
"type": "vuex-input",
"required": true
}
},
"output": {
"output1": {
"type": "string",
"description": "输出参数"
}
}
}
8.3 插件开发语言支持
| 语言 | 说明 |
|---|
| Python | 推荐，有完善的 SDK |
| NodeJS | 支持 |
| Java | 支持 |
| Golang | 支持 |
九、开发规范
9.1 新增组件类型
- 在
StoreTypeEnum 添加新类型 - 创建对应的主表和关联表
- 创建 DAO、Service、Resource 层代码
- 在处理器链中注册新类型的处理器
9.2 插件查询示例
// 根据插件代码查询最新版本
val atom = atomDao.getLatestAtomByCode(
dslContext = dslContext,
atomCode = atomCode
)
// 查询项目可用的插件
val atoms = atomDao.getProjectAtoms(
dslContext = dslContext,
projectCode = projectId, // english_name
classifyCode = classifyCode
)
// 查询插件执行环境
val envInfo = marketAtomEnvInfoDao.getMarketAtomEnvInfo(
dslContext = dslContext,
atomId = atomId
)
十、常见问题
Q: atomCode 和 atomId 的区别？ A: atomCode 是插件唯一标识（不变），atomId 是具体版本的 ID（每个版本不同）。
Q: 如何判断插件是否可用？ A: 检查 ATOM_STATUS = 7（RELEASED）且 LATEST_FLAG = true。
Q: 插件如何关联到项目？ A: 通过 T_STORE_PROJECT_REL 表关联，STORE_CODE 存储 atomCode。
Q: 如何获取插件的执行环境？ A: 查询 T_ATOM_ENV_INFO 表，根据 ATOM_ID 获取 PKG_PATH、TARGET 等信息。
版本: 1.0.0 | 更新日期: 2025-12-11
