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