陌讯skills聚合平台

store-module-architecture

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

Agent 安装分布

claude-code 12
opencode 10
gemini-cli 10
antigravity 8
codex 8

Skill 文档

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 新增组件类型

  1. 在 StoreTypeEnum 添加新类型
  2. 创建对应的主表和关联表
  3. 创建 DAO、Service、Resource 层代码
  4. 在处理器链中注册新类型的处理器

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

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