artifactory-module-architecture

Artifactory 制品库模块架构指南

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "artifactory-module-architecture" with this command: npx skills add tencentblueking/bk-ci/tencentblueking-bk-ci-artifactory-module-architecture

Artifactory 制品库模块架构指南

模块定位: Artifactory 是 BK-CI 的制品库模块，负责构建产物的存储、下载、管理，支持对接本地磁盘存储或 BkRepo（蓝鲸制品库）等后端存储系统。

一、模块整体结构

1.1 子模块划分

src/backend/ci/core/artifactory/ ├── api-artifactory/ # API 接口定义层 │ └── src/main/kotlin/com/tencent/devops/artifactory/ │ ├── api/ │ │ ├── builds/ # 构建时接口 │ │ ├── service/ # 服务间接口 │ │ └── user/ # 用户接口 │ ├── constant/ # 常量和消息码 │ └── pojo/ # 数据对象 │ └── enums/ # 枚举定义 │ ├── biz-artifactory/ # 业务逻辑层 │ └── src/main/kotlin/com/tencent/devops/artifactory/ │ ├── config/ # 配置类 │ ├── dao/ # 数据访问层 │ ├── mq/ # 消息队列监听 │ ├── resources/ # API 实现 │ ├── service/ # 业务服务 │ │ └── impl/ # 服务实现 │ ├── store/ # 研发商店相关 │ │ ├── resources/ # 商店 API 实现 │ │ └── service/ # 商店归档服务 │ └── util/ # 工具类 │ ├── model-artifactory/ # 数据模型层（JOOQ 生成） └── boot-artifactory/ # Spring Boot 启动模块

1.2 存储后端类型

类型 说明 实现类

BkRepo 蓝鲸制品库（推荐） BkRepoArchiveFileServiceImpl

Disk 本地磁盘存储 DiskArchiveFileServiceImpl

二、核心概念

2.1 制品类型

enum class ArtifactoryType(val type: String) { PIPELINE("PIPELINE"), // 流水线产物 CUSTOM_DIR("CUSTOM_DIR"), // 自定义目录 REPORT("REPORT"), // 报告文件 }

2.2 文件类型

enum class FileTypeEnum(val type: String) { BK_ARCHIVE("BK_ARCHIVE"), // 构建归档 BK_CUSTOM("BK_CUSTOM"), // 自定义文件 BK_REPORT("BK_REPORT"), // 报告文件 BK_LOG("BK_LOG"), // 日志文件 BK_PLUGIN_FE("BK_PLUGIN_FE"), // 插件前端 BK_STATIC("BK_STATIC"), // 静态资源 }

2.3 文件路径规范

流水线产物路径

/{projectId}/{pipelineId}/{buildId}/{fileName}

自定义目录路径

/{projectId}/custom/{customPath}/{fileName}

报告文件路径

/{projectId}/report/{pipelineId}/{buildId}/{taskId}/{fileName}

三、核心数据库表

3.1 文件信息表

表名 说明 核心字段

T_FILE_INFO

文件信息主表 ID , PROJECT_CODE , FILE_TYPE , FILE_PATH , FILE_NAME , FILE_SIZE

T_FILE_PROPS_INFO

文件元数据表 FILE_ID , PROPS_KEY , PROPS_VALUE

T_TOKEN

下载令牌表 USER_ID , PROJECT_ID , PATH , TOKEN , EXPIRE_TIME

T_FILE_TASK

文件任务表 TASK_ID , FILE_TYPE , FILE_PATH , STATUS , BUILD_ID

3.2 字段说明

⚠️ 重要: PROJECT_CODE / PROJECT_ID 都是 T_PROJECT.english_name

字段 说明

PROJECT_CODE

项目标识（= T_PROJECT.english_name）

FILE_TYPE

文件类型（BK_ARCHIVE/BK_CUSTOM 等）

FILE_PATH

文件存储路径

ARTIFACTORY_TYPE

制品库类型（PIPELINE/CUSTOM_DIR）

四、分层架构

┌─────────────────────────────────────────────────────────────────────────┐ │ 请求入口 │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ API 层 (api-artifactory) │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │BuildFile │ │ServiceArti │ │UserFile │ │UserArtifact │ │ │ │Resource │ │factoryRes │ │Resource │ │oryResource │ │ │ │(构建时上传) │ │(服务间调用) │ │(用户文件) │ │(用户制品) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │BuildArtifact │ │ServiceBkRepo │ │UserReport │ │ │ │oryResource │ │Resource │ │StorageRes │ │ │ │(构建制品) │ │(BkRepo操作) │ │(报告存储) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ 业务层 (biz-artifactory) │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ 核心 Service │ │ │ │ ArchiveFileService - 文件归档服务（接口） │ │ │ │ BkRepoArchiveFileServiceImpl - BkRepo 实现 (29KB) │ │ │ │ DiskArchiveFileServiceImpl - 磁盘存储实现 (28KB) │ │ │ │ FileTaskService - 文件任务服务 │ │ │ │ PipelineBuildArtifactoryService - 流水线构建制品服务 │ │ │ └──────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ 商店归档服务 (store/service/) │ │ │ │ ArchiveAtomService - 插件归档服务 │ │ │ │ ArchiveStorePkgService - 商店包归档服务 │ │ │ │ ArchiveAtomToBkRepoServiceImpl - 插件归档到 BkRepo │ │ │ └──────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ 消息监听 (mq/) │ │ │ │ PipelineBuildArtifactoryListener - 构建完成后处理制品 │ │ │ └──────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ DAO 层 (biz-artifactory/dao) │ │ FileDao (7.5KB) | FileTaskDao (4.8KB) │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ 数据层 (model-artifactory + MySQL) │ │ 数据库：devops_ci_artifactory（共 4 张表） │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ 存储后端 (BkRepo / 本地磁盘) │ └─────────────────────────────────────────────────────────────────────────┘

五、核心类速查

5.1 API 接口层

类名 路径前缀 职责

BuildFileResource

/build/files

构建时文件上传下载

BuildArtifactoryResource

/build/artifactories

构建时制品操作

ServiceArtifactoryResource

/service/artifactories

服务间制品操作

ServiceFileResource

/service/files

服务间文件操作

UserFileResource

/user/files

用户文件操作

UserArtifactoryResource

/user/artifactories

用户制品操作

ServiceArchiveAtomResource

/service/archive/atom

插件归档

5.2 Service 层

类名 文件大小 职责

BkRepoArchiveFileServiceImpl

29KB BkRepo 文件归档实现

DiskArchiveFileServiceImpl

28KB 磁盘文件归档实现

ArchiveAtomServiceImpl

16KB 插件归档服务

ArchiveStorePkgServiceImpl

16KB 商店包归档服务

FileTaskServiceImpl

10KB 文件任务服务

ArchiveFileService

8KB 文件归档接口

5.3 DAO 层

类名 职责

FileDao

文件信息访问

FileTaskDao

文件任务访问

六、核心流程

6.1 构建产物上传流程

构建插件上传文件 │ ▼ BuildFileResource.uploadFile() │ ▼ ArchiveFileService.uploadFile() │ ├─► BkRepoArchiveFileServiceImpl.uploadFile() │ └─► 调用 BkRepo API 上传文件 │ └─► DiskArchiveFileServiceImpl.uploadFile() └─► 写入本地磁盘 │ ▼ FileDao.create() │ └─► 记录文件信息到数据库

6.2 构建产物下载流程

用户/插件请求下载 │ ▼ UserFileResource.downloadFile() / BuildFileResource.downloadFile() │ ▼ ArchiveFileService.downloadFile() │ ├─► 验证权限 │ └─► 检查用户是否有项目权限 │ ├─► 获取文件 │ ├─► BkRepo: 调用 BkRepo API 获取 │ └─► Disk: 从本地磁盘读取 │ └─► 返回文件流

6.3 插件包归档流程

插件发布时归档 │ ▼ ServiceArchiveAtomResource.archiveAtom() │ ▼ ArchiveAtomService.archiveAtom() │ ├─► 下载插件包 │ └─► 从代码库下载构建产物 │ ├─► 上传到制品库 │ └─► ArchiveAtomToBkRepoServiceImpl.archiveAtom() │ └─► 更新插件环境信息 └─► 记录 PKG_PATH

七、与其他模块的关系

7.1 依赖关系

┌─────────────────────────────────────────────────────────────────┐ │ Artifactory 模块依赖关系 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────┐ │ │ │ artifactory │ │ │ └───────┬───────┘ │ │ │ │ │ ┌────────────────┼────────────────┐ │ │ ▼ ▼ ▼ │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │ project │ │ auth │ │ BkRepo │ │ │ │ (项目信息) │ │ (权限校验) │ │ (存储后端) │ │ │ └───────────┘ └───────────┘ └───────────┘ │ │ │ │ 被依赖： │ │ - process（流水线归档产物） │ │ - store（插件包归档） │ │ - worker（构建机上传下载） │ └─────────────────────────────────────────────────────────────────┘

7.2 服务间调用示例

// Process 模块获取构建产物列表 // 注意：projectId 是 T_PROJECT.english_name client.get(ServiceArtifactoryResource::class).search( projectId = projectId, // english_name pipelineId = pipelineId, buildId = buildId )

// 获取文件下载 URL client.get(ServiceArtifactoryResource::class).getFileDownloadUrls( projectId = projectId, artifactoryType = ArtifactoryType.PIPELINE, filePath = filePath )

// Worker 上传文件 client.get(BuildFileResource::class).uploadFile( projectId = projectId, pipelineId = pipelineId, buildId = buildId, file = file )

八、BkRepo 集成

8.1 BkRepo 配置

application-artifactory.yml

bkrepo:

BkRepo 服务地址

gatewayUrl: http://bkrepo.example.com

是否启用 BkRepo

enabled: true

仓库名称

repoName: pipeline

8.2 BkRepo 工具类

// BkRepoUtils.kt object BkRepoUtils { // 构建 BkRepo 路径 fun buildPath(projectId: String, pipelineId: String, buildId: String, fileName: String): String

// 上传文件到 BkRepo
fun uploadFile(path: String, file: File): Boolean

// 从 BkRepo 下载文件
fun downloadFile(path: String): InputStream

}

九、开发规范

9.1 新增存储后端

  • 实现 ArchiveFileService 接口

  • 创建对应的 *ArchiveFileServiceImpl 类

  • 在配置中添加存储后端选择逻辑

  • 实现文件上传、下载、删除等方法

9.2 文件操作示例

// 上传文件 archiveFileService.uploadFile( userId = userId, projectId = projectId, // english_name pipelineId = pipelineId, buildId = buildId, file = file, fileType = FileTypeEnum.BK_ARCHIVE )

// 下载文件 val inputStream = archiveFileService.downloadFile( userId = userId, projectId = projectId, filePath = filePath )

// 查询文件列表 val files = fileDao.listByPath( dslContext = dslContext, projectCode = projectId, filePath = path )

十、常见问题

Q: 如何切换存储后端？ A: 通过配置 bkrepo.enabled 控制，true 使用 BkRepo，false 使用本地磁盘。

Q: 构建产物保留多久？ A: 根据项目配置的保留策略，默认跟随构建记录保留时间。

Q: 如何获取文件下载链接？ A: 调用 getFileDownloadUrls 接口获取带 Token 的临时下载链接。

Q: 大文件上传有限制吗？ A: 有，默认限制在配置文件中设置，可根据需要调整。

版本: 1.0.0 | 更新日期: 2025-12-11

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

General

git-commit-specification

No summary provided by upstream source.

Repository SourceNeeds Review
53-tencentblueking
General

design-patterns

No summary provided by upstream source.

Repository SourceNeeds Review
53-tencentblueking
General

database-design

No summary provided by upstream source.

Repository SourceNeeds Review
45-tencentblueking
General

api-interface-design

No summary provided by upstream source.

Repository SourceNeeds Review
41-tencentblueking