33-store-module-architecture by TencentBlueKing

---
name: 33-store-module-architecture
description: Store 研发商店模块架构指南，涵盖插件/模板/镜像管理、版本发布、审核流程、商店市场、扩展点机制。当用户开发研发商店功能、发布插件、管理模板或实现扩展点时使用。
---

# 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 插件状态流转

```kotlin
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 插件分类

```kotlin
// 插件大类
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 模块使用责任链模式处理组件的创建、更新、删除：

```kotlin
// 创建处理器链
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 服务间调用示例

```kotlin
// 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 配置

```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 插件查询示例

```kotlin
// 根据插件代码查询最新版本
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