zeaslity/ProjectAGiPrompt

Fork 0

Files

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

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

12 KiB

Raw Permalink Blame History

DCU 模块设计文档

Docker镜像打包压缩服务模块，负责执行 Download-Compress-Upload (DCU) 工作流。

1. 模块概述

DCU模块是一个独立运行的服务，专门处理Docker镜像的下载、压缩和上传任务。该模块采用Gin+GORM+SQLite3技术栈，通过状态机管理任务流程，支持异步执行和定时清理。

1.1 核心特性

特性	说明
独立部署	完全独立运行，通过HTTP API接收请求
状态管理	基于状态机的任务状态管理，支持持久化
异步执行	DCU流程异步执行，不阻塞API响应
定时清理	支持定时清理本地gzip文件和MinIO对象
错误追踪	完整的错误信息记录和查询功能

2. 架构设计

2.1 系统架构图

graph TB
    subgraph "外部系统"
        JB[rmdc-jenkins-branch-dac] -->|HTTP Request| API
        DR[Docker Registry]
        MIO[(MinIO对象存储)]
    end
    
    subgraph "rmdc-dcu 模块"
        API[REST API Handler]
        
        subgraph "Service Layer"
            DCU[DCU Service]
            DS[Docker Service]
            CS[Compress Service]
            MS[MinIO Service]
            SCH[Scheduler]
        end
        
        subgraph "Core"
            SM[State Machine]
            DAO[DCU Task DAO]
        end
        
        DB[(SQLite3)]
    end
    
    API --> DCU
    DCU --> SM
    DCU --> DS
    DCU --> CS
    DCU --> MS
    SM --> DAO
    DAO --> DB
    DS -->|docker pull/save| DR
    MS -->|upload/delete| MIO
    SCH --> CS
    SCH --> MS

2.2 分层架构

┌─────────────────────────────────────────────────────┐
│                  Handler Layer                       │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────┐  │
│  │ StartTask   │  │ GetStatus    │  │ QueryTasks │  │
│  └─────────────┘  └──────────────┘  └────────────┘  │
├─────────────────────────────────────────────────────┤
│                  Service Layer                       │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────┐  │
│  │ DCUService  │  │ DockerSvc    │  │ CompressSvc│  │
│  ├─────────────┤  ├──────────────┤  ├────────────┤  │
│  │ MinIOSvc    │  │ Scheduler    │  │            │  │
│  └─────────────┘  └──────────────┘  └────────────┘  │
├─────────────────────────────────────────────────────┤
│                State Machine Layer                   │
│  ┌─────────────────────────────────────────────────┐│
│  │  StateMachine (状态转换 + 持久化回调)            ││
│  └─────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────┤
│                    DAO Layer                         │
│  ┌─────────────────────────────────────────────────┐│
│  │  DCUTaskDAO (CRUD + 分页查询 + 清理)             ││
│  └─────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────┤
│                  Entity Layer                        │
│  ┌─────────────────────────────────────────────────┐│
│  │  DCUTask (任务实体 + GORM映射)                   ││
│  └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘

3. 状态机设计

3.1 状态定义

状态	常量值	说明	进度
等待中	`idle`	任务已创建，等待开始	0%
下载中	`downloading`	正在执行docker pull	25%
压缩中	`compressing`	正在gzip压缩镜像	50%
上传中	`uploading`	正在上传到MinIO	75%
已完成	`completed`	任务成功完成	100%
失败	`failed`	任务执行失败	-1

3.2 状态转换图

stateDiagram-v2
    [*] --> idle: 创建任务

    idle --> downloading: StartTask()
    idle --> failed: 初始化失败

    downloading --> compressing: Pull成功
    downloading --> failed: Pull失败

    compressing --> uploading: 压缩成功
    compressing --> failed: 压缩失败

    uploading --> completed: 上传成功
    uploading --> failed: 上传失败

    completed --> [*]
    failed --> [*]

3.3 状态持久化

状态机通过回调函数实现状态持久化：

// 状态转换时自动调用
func (s *DCUService) onStateTransition(taskID, fromState, toState, errMsg string) error {
    return s.taskDAO.UpdateState(ctx, taskID, toState, errMsg)
}

4. DCU 工作流程

4.1 完整流程图

sequenceDiagram
    participant Client as 调用方
    participant API as REST API
    participant DCU as DCU Service
    participant SM as State Machine
    participant Docker as Docker CLI
    participant Compress as Compress Service
    participant MinIO as MinIO Service
    participant DB as SQLite

    Client->>API: POST /api/dcu/start
    API->>DCU: StartTask(username, imageName)
    DCU->>DB: Create task record
    DCU->>SM: RegisterTask(taskID)
    DCU-->>API: Return taskID
    API-->>Client: Response {task_id, state: "idle"}
    
    Note over DCU: 异步执行DCU流程
    
    DCU->>SM: Transition(downloading)
    SM->>DB: Update state
    DCU->>Docker: docker pull image
    Docker-->>DCU: Pull完成
    DCU->>Docker: docker save -o image.tar
    Docker-->>DCU: Save完成
    
    DCU->>SM: Transition(compressing)
    SM->>DB: Update state
    DCU->>Compress: CompressFile(tar → gzip)
    Compress-->>DCU: 压缩完成
    DCU->>DB: Update gzip_file_name
    
    DCU->>SM: Transition(uploading)
    SM->>DB: Update state
    DCU->>MinIO: Upload(objectName, gzipPath)
    MinIO-->>DCU: 上传完成
    DCU->>DB: Update minio_object_name
    
    DCU->>SM: Transition(completed)
    SM->>DB: Update state + end_time
    
    Client->>API: GET /api/dcu/status/{task_id}
    API->>DCU: GetTaskStatus(taskID)
    DCU->>DB: Query task
    DB-->>DCU: Task entity
    DCU-->>API: TaskStatusResponse
    API-->>Client: Response with progress

4.2 错误处理流程

flowchart TD
    A[开始DCU] --> B{Docker Pull}
    B -->|成功| C{Docker Save}
    B -->|失败| F[记录错误信息]
    C -->|成功| D{Gzip压缩}
    C -->|失败| F
    D -->|成功| E{MinIO上传}
    D -->|失败| F
    E -->|成功| G[状态: completed]
    E -->|失败| F
    F --> H[状态: failed]
    G --> I[结束]
    H --> I

5. API 接口说明

5.1 启动DCU任务

POST /api/dcu/start

请求体：

{
    "username": "test_user",
    "docker_image_name": "nginx:latest"
}

响应：

{
    "code": 0,
    "status": 200,
    "message": "任务已启动",
    "data": {
        "task_id": "550e8400-e29b-41d4-a716-446655440000",
        "state": "idle"
    }
}

5.2 查询任务状态

GET /api/dcu/status/{task_id}

响应：

{
    "code": 0,
    "status": 200,
    "message": "success",
    "data": {
        "task_id": "550e8400-e29b-41d4-a716-446655440000",
        "state": "compressing",
        "state_display": "压缩镜像中",
        "docker_image_name": "nginx:latest",
        "gzip_file_name": "./data/gzip/nginx_latest.tar.gz",
        "progress": 50,
        "duration": 12345,
        "username": "test_user",
        "start_time": "2025-12-10 20:25:00"
    }
}

5.3 查询任务列表

GET /api/dcu/query?docker_image_name=nginx&page=1&page_size=10

查询参数：

参数	类型	说明
docker_image_name	string	镜像名称（模糊匹配）
username	string	用户名
state	string	状态筛选
page	int	页码
page_size	int	每页数量

响应：

{
    "code": 0,
    "status": 200,
    "message": "success",
    "data": {
        "total": 42,
        "items": [...]
    }
}

5.4 健康检查

GET /api/dcu/health

6. 数据库设计

6.1 DCU任务表 (dcu_tasks)

字段	类型	说明
id	INTEGER	主键，自增
task_id	VARCHAR(100)	任务UUID，唯一索引
username	VARCHAR(100)	用户名，索引
docker_image_name	VARCHAR(500)	Docker镜像名，索引
gzip_file_name	VARCHAR(500)	Gzip文件路径
minio_object_name	VARCHAR(500)	MinIO对象名
state	VARCHAR(50)	状态，索引
error_message	VARCHAR(2000)	错误信息
start_time	DATETIME	开始时间，索引
end_time	DATETIME	结束时间
duration	INTEGER	持续时间(毫秒)
created_at	DATETIME	创建时间
updated_at	DATETIME	更新时间

7. 定时任务

任务	默认Cron	说明
Gzip清理	`0 0 * * *`	每天凌晨清理过期gzip文件
MinIO清理	`0 0 * * 0`	每周日凌晨清理过期MinIO对象

8. 配置说明

配置文件位置：configs/config.yaml

server:
  host: 0.0.0.0
  port: 8090
  mode: debug

database:
  path: ./data/dcu.db

storage:
  gzip_path: ./data/gzip
  cleanup_gzip_cron: "0 0 * * *"
  cleanup_minio_cron: "0 0 * * 0"
  gzip_retention_days: 1
  minio_retention_days: 7

minio:
  endpoint: 192.168.40.50:9000
  access_key: your_access_key
  secret_key: your_secret_key
  bucket: dcu-artifacts
  use_ssl: false

9. 目录结构

rmdc-dcu/
├── cmd/
│   └── main.go                 # 应用入口
├── configs/
│   └── config.yaml             # 配置文件
├── internal/
│   ├── config/
│   │   └── config.go           # 配置结构
│   ├── dao/
│   │   ├── database.go         # 数据库初始化
│   │   └── dcu_task_dao.go     # 任务DAO
│   ├── handler/
│   │   ├── dcu_handler.go      # API处理器
│   │   └── router.go           # 路由注册
│   ├── model/
│   │   ├── dto/
│   │   │   └── dcu_dto.go      # 请求/响应DTO
│   │   └── entity/
│   │       └── dcu_task.go     # 任务实体
│   ├── service/
│   │   ├── compress_service.go # 压缩服务
│   │   ├── dcu_service.go      # DCU编排服务
│   │   ├── docker_service.go   # Docker服务
│   │   ├── minio_service.go    # MinIO服务
│   │   └── scheduler.go        # 定时调度器
│   └── statemachine/
│       ├── machine.go          # 状态机实现
│       └── state.go            # 状态定义
├── go.mod
└── go.sum

10. 运行要求

Go: 1.24+
Docker: 已安装并配置Docker CLI
MinIO: 可访问的MinIO服务器
SQLite3: 自动创建（通过GORM）

11. 启动命令

cd rmdc-dcu
go run ./cmd/main.go

服务将在 http://0.0.0.0:8090 启动。

12 KiB Raw Permalink Blame History Unescape Escape

DCU 模块设计文档

1. 模块概述

1.1 核心特性

2. 架构设计

2.1 系统架构图

2.2 分层架构

3. 状态机设计

3.1 状态定义

3.2 状态转换图

3.3 状态持久化

4. DCU 工作流程

4.1 完整流程图

4.2 错误处理流程

5. API 接口说明

5.1 启动DCU任务

5.2 查询任务状态

5.3 查询任务列表

5.4 健康检查

6. 数据库设计

6.1 DCU任务表 (dcu_tasks)

7. 定时任务

8. 配置说明

9. 目录结构

10. 运行要求

11. 启动命令

12 KiB

Raw Permalink Blame History