zeaslity/ProjectAGiPrompt

Fork 0

Files

zeaslity 631cce9e1e RMDC系统设计文档整体转换为SKILL

2026-01-21 16:15:49 +08:00

8.6 KiB

Raw Blame History

rmdc-jenkins-branch-dac 详细设计说明书（DDS）

模块名称: rmdc-jenkins-branch-dac
版本: v1.0
编制日期: 2026-01-06

1. 模块概述

1.1 模块定位

rmdc-jenkins-branch-dac 是 RMDC 平台的Jenkins分支级权限控制与构建管理模块，负责：

分支级权限控制(DAC)：基于自主访问控制模型，实现Organization→Repository→Branch三级资源权限管理
Jenkins集成：封装Jenkins REST API，提供统一的构建触发、状态查询、日志获取等能力
构建产物管理：管理Docker镜像的下载、压缩、上传(DCU)流程，集成MinIO对象存储
构建状态追踪：实时追踪构建进度，提供状态同步和超时检测机制

1.2 核心用户角色

角色	权限说明
SuperAdmin	全量访问，可管理所有Organization/Repository/Branch
Admin	拥有分配的权限，可将自有权限分配给Normal/Third用户
Normal	拥有分配的权限，只能查看和触发被授权的分支构建
Third	第三方人员，权限最受限，仅能查看被授权内容

1.3 技术栈

后端: Go + Gin + GORM
数据库: PostgreSQL (主库) + SQLite (DCU模块独立库)
外部服务: Jenkins REST API, MinIO对象存储

2. 系统架构

2.1 模块架构图

graph TB
    subgraph "rmdc-core 网关层"
        Router[Gin Router]
        AuthMW[AuthMiddleware]
        PermMW[PermissionMiddleware]
    end
    
    subgraph "rmdc-jenkins-branch-dac 模块"
        subgraph "Handler层"
            OrgH[OrgHandler]
            RepoH[RepoHandler]
            BranchH[BranchHandler]
            BuildH[BuildHandler]
            DCUH[DCUHandler]
        end
        
        subgraph "Service层"
            JenkinsS[JenkinsService]
            BuildS[BuildService]
            SyncS[SyncService]
            DCUS[DCUService]
            TrackerS[BuildTracker]
        end
        
        subgraph "DAO层"
            OrgDAO[OrganizationDAO]
            RepoDAO[RepositoryDAO]
            BranchDAO[BranchDAO]
            BuildDAO[BuildDAO]
        end
        
        JenkinsC[JenkinsClient]
        MinioC[MinioClient]
    end
    
    subgraph "外部服务"
        Jenkins[(Jenkins Server)]
        MinIO[(MinIO Storage)]
    end
    
    Router --> AuthMW --> PermMW
    PermMW --> OrgH & RepoH & BranchH & BuildH & DCUH
    
    BuildH --> BuildS --> JenkinsS --> JenkinsC --> Jenkins
    DCUH --> DCUS --> MinioC --> MinIO
    
    JenkinsS --> OrgDAO & RepoDAO & BranchDAO & BuildDAO

2.2 Jenkins层级结构

Organization Folder（组织）
  └── Repository/Project（仓库）
        └── Branch（分支）
              └── Build（构建）

URL路径模式：

/job/{ORG}                               # 组织
/job/{ORG}/job/{REPO}                    # 仓库
/job/{ORG}/job/{REPO}/job/{BRANCH}       # 分支
/job/{ORG}/job/{REPO}/job/{BRANCH}/{NUM} # 构建

3. 数据模型设计

3.1 核心实体

erDiagram
    jenkins_organizations ||--o{ jenkins_repositories : contains
    jenkins_repositories ||--o{ jenkins_branches : contains
    jenkins_branches ||--o{ jenkins_builds : contains
    
    jenkins_organizations {
        int64 id PK
        string name UK
        string display_name
        string url
        datetime last_sync_at
    }
    
    jenkins_repositories {
        int64 id PK
        int64 organization_id FK
        string name
        string url
    }
    
    jenkins_branches {
        int64 id PK
        int64 repository_id FK
        string name
        int last_build_number
        string last_build_result
    }
    
    jenkins_builds {
        int64 id PK
        int64 branch_id FK
        int build_number
        string result
        int64 timestamp
        int64 duration
        int64 estimated_duration
        bool is_building
        string artifact_docker_image
    }

4. API接口规范

设计原则: 使用RESTful风格，优先使用POST + RequestBody，避免PathVariables和RequestParams

4.1 组织管理接口

接口	方法	说明
`/api/jenkins/organizations/list`	POST	获取组织列表
`/api/jenkins/organizations/detail`	POST	获取组织详情
`/api/jenkins/organizations/sync`	POST	同步Jenkins组织数据

4.2 仓库管理接口

接口	方法	说明
`/api/jenkins/repositories/list`	POST	获取仓库列表
`/api/jenkins/repositories/detail`	POST	获取仓库详情
`/api/jenkins/repositories/sync`	POST	同步仓库数据
`/api/jenkins/repositories/scan`	POST	触发仓库扫描

4.3 分支管理接口

接口	方法	说明
`/api/jenkins/branches/list`	POST	获取分支列表
`/api/jenkins/branches/detail`	POST	获取分支详情
`/api/jenkins/branches/sync`	POST	同步分支数据

4.4 构建管理接口

接口	方法	说明
`/api/jenkins/builds/list`	POST	获取构建列表
`/api/jenkins/builds/detail`	POST	获取构建详情
`/api/jenkins/builds/trigger`	POST	触发构建
`/api/jenkins/builds/console`	POST	获取构建日志
`/api/jenkins/builds/sync`	POST	同步构建数据

4.5 DCU接口

接口	方法	说明
`/api/dcu/start`	POST	启动DCU任务
`/api/dcu/status`	POST	查询任务状态
`/api/dcu/list`	POST	查询任务列表

5. 分支权限(DAC)设计

5.1 权限模型

DAC采用资源-用户-权限三元组模型，支持三级权限继承：

授权层级	继承规则
Organization级	自动继承到该组织下所有Repository和Branch
Repository级	自动继承到该仓库下所有Branch
Branch级	最细粒度，不继承

5.2 权限类型

权限	说明
`can_view`	查看权限
`can_build`	构建权限

6. 构建状态追踪

6.1 BuildTracker设计

BuildTracker负责追踪正在进行中的构建，提供超时检测和状态同步：

sequenceDiagram
    participant User as 用户
    participant Handler as BuildHandler
    participant Service as BuildService
    participant Tracker as BuildTracker
    participant Jenkins as Jenkins API
    
    User->>Handler: POST /builds/trigger
    Handler->>Service: TriggerBuild()
    Service->>Jenkins: 触发构建
    Service->>Tracker: TrackBuild(buildId, timeout)
    Service-->>User: 返回构建号
    
    loop 后台超时检测(每10秒)
        Tracker->>Tracker: checkTimeouts()
        alt 超时
            Tracker->>Jenkins: 查询最新状态
            Tracker->>Tracker: 更新数据库
        end
    end

7. DCU(Download-Compress-Upload)流程

7.1 状态机

stateDiagram-v2
    [*] --> idle: 创建任务
    idle --> downloading: StartTask()
    downloading --> compressing: Pull成功
    compressing --> uploading: 压缩成功
    uploading --> completed: 上传成功
    
    downloading --> failed: Pull失败
    compressing --> failed: 压缩失败
    uploading --> failed: 上传失败

7.2 流程说明

Download: 从Docker Registry拉取镜像
Compress: 使用gzip压缩镜像tar包
Upload: 上传到MinIO对象存储

8. 错误码定义

错误码	说明
`JENKINS-001`	Jenkins服务不可用
`JENKINS-002`	Jenkins认证失败
`JENKINS-003`	Jenkins资源不存在
`JENKINS-004`	构建触发失败
`JENKINS-005`	构建超时
`DCU-001`	Docker Pull失败
`DCU-002`	压缩失败
`DCU-003`	MinIO上传失败
`PERM-001`	无权限访问该资源
`PERM-002`	无权限执行该操作

9. 相关文档

文档	内容
5-RMDC项目权限设计方案.md	权限设计
8-jenkins项目层级.md	Jenkins层级结构
9-JenkinsBuild-流程图.md	构建流程图
9-rmdc-dcu模块设计方案.md	DCU模块设计

8.6 KiB Raw Blame History Unescape Escape