第七章：技术实现与接口设计（Technical Implementation & API Specification）

7.1 技术栈总览（Technology Stack Overview）

核心语言与框架

7.2 系统分层设计（System Layering）

模块依赖图

graph TD
A[HTTP API] --> B[Application Layer]
B --> C[Domain Layer]
C --> D[Repository]
D --> E[Database / Storage]
B --> F[Queue / Scheduler]
F --> G[Runner Agents]
B --> H[Policy Engine]
H --> I[OPA Rego]
B --> J[Metrics Collector]
J --> K[Prometheus]

7.3 控制平面（Control Plane）

主要职责

• 管理项目与流水线配置；
• 调度任务；
• 分配 Runner；
• 处理制品、日志、策略与审计；
• 提供 REST/gRPC 接口。

主要组件

7.4 Runner Plane（执行平面）

Runner 模型

每个 Runner 是一个独立的 Go 进程，可在不同环境（Docker/K8s/VM）中运行。

核心功能

• 向 Scheduler 轮询任务；
• 下载构建代码；
• 运行 Steps；
• 上传制品与日志；
• 汇报状态。

内部模块划分

Runner 注册流程

sequenceDiagram
  participant Runner
  participant ControlPlane
  Runner->>ControlPlane: Register(token)
  ControlPlane-->>Runner: Acknowledge (runner_id)
  Runner->>ControlPlane: Heartbeat (metrics)
  ControlPlane-->>Runner: Job Assignment
  Runner->>ControlPlane: Job Result

Runner 执行模式

1. Host 模式

   • 执行宿主机命令；
   • 适用于内部环境。

2. Docker 模式

   • 每 Job 创建容器；
   • 提供最大隔离性；
   • 支持资源限制（CPU/MEM）。

3. K8s 模式

   • 每 Job 生成 Pod；
   • 支持自动清理；
   • 适合大规模分布式环境。

7.5 Scheduler（任务调度器）

调度算法

采用 Fair Weighted Queue（加权公平调度）：

• 每租户分配初始权重；
• 超出配额时降低优先级；
• 任务分配采用拉模式（Runner 主动拉取）。

任务状态机

调度实现伪代码

func AssignJob(job Job) {
  runner := findAvailableRunner(job.Tags)
  if runner == nil {
    enqueuePending(job)
    return
  }
  assign(runner, job)
}

调度重试逻辑

• 最大重试次数：3；
• 指数回退策略：1s, 3s, 6s；
• 异常自动标记 Runner 不健康。

7.6 Artifact Service（制品服务）

API 设计

存储目录结构

/artifacts/
  ├── project-101/
  │   ├── v1.0.0/
  │   │   ├── binary.zip
  │   │   └── sbom.json
  │   ├── v1.0.1/
  │   │   ├── app.tar.gz
  │   │   └── manifest.json

上传流程

sequenceDiagram
User->>API: POST /artifacts/upload
API->>MinIO: PUT Object
MinIO-->>API: OK
API->>DB: INSERT metadata
API-->>User: 201 Created (artifact_id)

7.7 Secret Service（密钥管理）

存储格式

• 加密算法：AES-256-GCM；
• 每个 Secret 独立随机 IV；
• 加密密钥通过 KMS 管理（如 Vault）。

type Secret struct {
  ID       int64
  Scope    string // project / environment
  Key      string
  ValueEnc string // base64(ciphertext)
  Version  int
}

使用流程

1. 构建时由控制平面加载；
2. 传递给 Runner；
3. Runner 注入环境变量；
4. 构建完成后销毁。

7.8 Policy Engine（策略引擎）

集成 OPA

• 使用 OPA SDK 嵌入；
• 策略缓存至 Redis；
• 每次执行前异步校验。

执行流程

flowchart LR
A[Pipeline Request] --> B[Load Policy]
B --> C[OPA Eval]
C --> D{Result}
D -->|allow| E[Proceed]
D -->|deny| F[Reject + Reason]

策略示例：镜像签名验证

package deploy.policy

deny["Image not signed"] {
  not input.image.signed
}

7.9 API 设计规范（RESTful + OpenAPI）

基本规则

• 路径：/api/v1/
• 响应统一格式：

{
  "code": 0,
  "message": "success",
  "data": {...},
  "trace_id": "abc123"
}

分页标准

• 参数：?page=1&limit=20
• 响应：

{
  "total": 152,
  "page": 1,
  "page_size": 20,
  "items": [...]
}

样例接口：Pipeline Runs

7.10 gRPC 接口定义

service RunnerService {
  rpc RegisterRunner(RegisterRequest) returns (RegisterResponse);
  rpc FetchJob(FetchRequest) returns (Job);
  rpc ReportResult(ResultRequest) returns (ResultResponse);
  rpc StreamLogs(stream LogChunk) returns (LogAck);
}

message RegisterRequest {
  string token = 1;
  string hostname = 2;
}

7.11 WebSocket 实时通信

用于日志与状态更新推送。
连接路径：/ws/pipeline/:id/logs

消息格式：

{
  "event": "log",
  "timestamp": "2025-10-22T10:12:33Z",
  "content": "[build] compiling..."
}

7.12 缓存与加速（Caching Layer）

缓存策略

7.13 日志与追踪（Logging & Tracing）

日志格式

{
  "time": "2025-10-22T10:05:31Z",
  "level": "info",
  "trace_id": "xyz",
  "module": "runner",
  "msg": "job completed"
}

Trace 标准

• 使用 OpenTelemetry；
• traceId 注入 HTTP Header；
• 可与 Jaeger / Tempo 集成；
• 追踪跨 Runner 与 Pipeline。

7.14 测试与验证（Testing & Validation）

单元测试覆盖率目标

7.15 性能优化策略（Performance Optimization）

7.16 插件执行生命周期（Plugin Lifecycle）

执行顺序：

pre_build → build → post_build → pre_deploy → deploy → post_deploy

7.17 外部集成（Integrations）

7.18 部署与升级（Deployment & Upgrade）

发布流程

1. 构建二进制（make build）；
2. 生成镜像；
3. 推送至 registry；
4. K8s 滚动更新；
5. 校验健康探针；
6. 触发自动回滚（若失败）。

版本号策略

v<major>.<minor>.<patch>-<build>
示例：v1.2.3-20251022

灰度升级

• 蓝绿切换；
• 新版本实例并行启动；
• 流量切换完成后销毁旧版本。

7.19 API 文档生成（OpenAPI Integration）

• 使用 swaggo/swag 生成 OpenAPI；
• 自动发布至 /docs；
• 版本控制（v1/v2）。

示例

// @Summary Get all projects
// @Router /api/v1/projects [get]
// @Produce json
// @Success 200 {array} Project
func GetProjects(c *fiber.Ctx) error {...}

7.20 安全机制验证与渗透测试

✅ 第七章总结
本章定义了 DeployLite 的完整技术实现路径与接口契约：

• 分层清晰，便于分工开发；
• 接口与协议标准化；
• 高性能、高安全、高扩展；
• 支持二次开发与插件生态。

整体目标：

“保持像 GitHub Actions 一样灵活，但像 Render 一样可自托管。”

接下来进入：

第八章：验收标准与测试计划（Acceptance & QA Plan）
它将定义各模块验收条件、功能/性能/安全测试用例、回归策略与自动化覆盖体系。