「DeployLite」第七章:技术实现与接口设计(Technical Implementation & API Specification)
By Leeting Yan
第七章:技术实现与接口设计(Technical Implementation & API Specification)
7.1 技术栈总览(Technology Stack Overview)
核心语言与框架
| 层级 | 技术 | 说明 |
|---|---|---|
| 后端语言 | Go 1.24+ | 主体逻辑实现,单二进制分发 |
| Web 框架 | Fiber / Gin | 高性能 HTTP 框架 |
| ORM / 数据库访问 | GORM v2 + SQLC(生成查询) | 兼顾灵活性与性能 |
| 消息队列 | Redis Streams / NATS JetStream | 调度与事件总线 |
| 对象存储 | MinIO / AWS S3 / Aliyun OSS | 构建制品与日志归档 |
| 配置管理 | Viper + YAML + Env | 动态加载配置文件 |
| 日志框架 | Zerolog / Zap | 结构化日志输出(JSON) |
| 容器交互 | Docker SDK / Kubernetes Client-Go | 部署与 Runner 执行 |
| 缓存层 | Redis / Memcached | 任务状态、令牌缓存 |
| 前端技术栈 | Vue3 + TypeScript + Vite + TailwindCSS | 控制台与 Dashboard 实现 |
| API 文档 | Swagger (OpenAPI 3.1) + Redoc | 自动生成文档 |
| 监控指标 | Prometheus Exporter + Grafana | 系统指标采集 |
| 策略引擎 | OPA(Open Policy Agent) + Rego | 策略即代码执行 |
| 测试框架 | GoConvey + Testify + Mockery | 单元与集成测试 |
| CI/CD 流程 | 自托管 DeployLite + GitHub Actions | 自动构建与发布 |
7.2 系统分层设计(System Layering)
| 层级 | 模块 | 职责描述 |
|---|---|---|
| Presentation Layer | HTTP API、GraphQL、WebSocket | 提供统一外部接口 |
| Application Layer | Pipeline Service、Runner Service、Deploy Service | 业务逻辑层 |
| Domain Layer | Entities、Aggregates、Policies | 核心业务模型 |
| Infrastructure Layer | Repository、Storage、Queue、Logger | 外部依赖封装 |
| Integration Layer | Plugins、Hooks、Webhooks、SDK | 外部系统交互 |
| Security Layer | Auth、RBAC、Policy、Audit | 身份与安全控制 |
| Observation Layer | Metrics、Tracing、Events | 可观测性支持 |
模块依赖图
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 接口。
主要组件
| 组件 | 描述 | 技术实现 |
|---|---|---|
| API Server | 对外统一接口(REST/gRPC) | Go Fiber / gRPC Gateway |
| Scheduler | 任务分配与调度队列 | Redis Stream + Worker Pool |
| Artifact Service | 制品上传、版本控制 | MinIO SDK / S3 API |
| Policy Service | 策略验证引擎 | OPA Rego Eval |
| Secret Manager | 密钥存取 | AES-GCM + Vault 插件 |
| Audit Logger | 操作记录 | PostgreSQL + Async Batch |
| Metrics Collector | 指标采集与上报 | Prometheus Exporter |
7.4 Runner Plane(执行平面)
Runner 模型
每个 Runner 是一个独立的 Go 进程,可在不同环境(Docker/K8s/VM)中运行。
核心功能
- 向 Scheduler 轮询任务;
- 下载构建代码;
- 运行 Steps;
- 上传制品与日志;
- 汇报状态。
内部模块划分
| 模块 | 功能 |
|---|---|
| JobFetcher | 轮询任务队列 |
| Executor | 执行 Steps(Shell / Docker / SSH) |
| ArtifactUploader | 上传构建输出 |
| HealthReporter | 定时心跳 |
| Sandbox | 临时执行环境清理 |
| LogStreamer | 实时日志传输 |
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 执行模式
-
Host 模式
- 执行宿主机命令;
- 适用于内部环境。
-
Docker 模式
- 每 Job 创建容器;
- 提供最大隔离性;
- 支持资源限制(CPU/MEM)。
-
K8s 模式
- 每 Job 生成 Pod;
- 支持自动清理;
- 适合大规模分布式环境。
7.5 Scheduler(任务调度器)
调度算法
采用 Fair Weighted Queue(加权公平调度):
- 每租户分配初始权重;
- 超出配额时降低优先级;
- 任务分配采用拉模式(Runner 主动拉取)。
任务状态机
| 状态 | 说明 | 转移条件 |
|---|---|---|
| Pending | 等待调度 | 有 Runner 空闲 |
| Assigned | 分配中 | Runner 拉取任务 |
| Running | 执行中 | Runner 启动 |
| Succeeded | 成功 | Job 执行完成 |
| Failed | 失败 | 异常中止或错误 |
| Canceled | 取消 | 用户终止或系统超时 |
调度实现伪代码
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 设计
| 方法 | 路径 | 描述 |
|---|---|---|
POST |
/artifacts/upload |
上传构建产物 |
GET |
/artifacts/:id |
获取制品信息 |
GET |
/artifacts/:id/download |
下载文件 |
DELETE |
/artifacts/:id |
删除制品 |
GET |
/projects/:id/artifacts |
查询项目下制品 |
存储目录结构
/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
}
使用流程
- 构建时由控制平面加载;
- 传递给 Runner;
- Runner 注入环境变量;
- 构建完成后销毁。
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
| 方法 | 路径 | 描述 |
|---|---|---|
GET |
/projects/:id/pipelines |
列出所有流水线 |
POST |
/projects/:id/pipelines/run |
触发新构建 |
GET |
/pipelines/:run_id/logs |
获取实时日志 |
DELETE |
/pipelines/:run_id |
取消执行 |
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)
缓存策略
| 类型 | Key 结构 | TTL | 说明 |
|---|---|---|---|
| Runner 状态 | runner:{id}:status | 10s | 心跳缓存 |
| 项目配置 | project:{id}:config | 60s | 减少 DB 查询 |
| Policy 缓存 | policy:{id}:hash | 300s | 提升 OPA 性能 |
| 构建日志块 | log:{pipeline}:{chunk} | 永久 | 流式读取优化 |
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)
| 测试类型 | 工具 | 目标 |
|---|---|---|
| 单元测试 | Go test + Testify | 代码逻辑正确性 |
| 集成测试 | Docker Compose | 多组件兼容 |
| 压力测试 | k6 / vegeta | 性能瓶颈 |
| 安全测试 | ZAP / Trivy | 漏洞扫描 |
| 端到端测试 | Playwright | Web + API 全链路 |
| Mock 测试 | Mockery | 外部依赖隔离 |
单元测试覆盖率目标
| 模块 | 覆盖率 |
|---|---|
| Pipeline Engine | ≥ 90% |
| Runner | ≥ 85% |
| Scheduler | ≥ 85% |
| API 层 | ≥ 80% |
| Artifact | ≥ 75% |
| Policy | ≥ 70% |
7.15 性能优化策略(Performance Optimization)
| 层级 | 策略 |
|---|---|
| API 层 | Gzip 压缩、连接复用、HTTP/2 |
| 数据库 | 索引优化、读写分离、批量提交 |
| 任务调度 | Redis pipeline 批量取任务 |
| Runner | 局部缓存、并行步骤执行 |
| 日志系统 | 分块写入、异步 flush |
| 前端加载 | 代码分片(chunk)、延迟加载 |
7.16 插件执行生命周期(Plugin Lifecycle)
| 阶段 | Hook 名称 | 插件类型 |
|---|---|---|
| 构建前 | pre_build |
Step Plugin |
| 构建后 | post_build |
Step Plugin |
| 部署前 | pre_deploy |
Policy Plugin |
| 部署后 | post_deploy |
Notify Plugin |
| 任务失败 | on_failure |
Notify Plugin |
执行顺序:
pre_build → build → post_build → pre_deploy → deploy → post_deploy
7.17 外部集成(Integrations)
| 系统 | 集成方式 |
|---|---|
| GitHub / GitLab | OAuth + Webhook |
| Slack / 飞书 | Notification Plugin |
| Harbor / GHCR | Docker Registry API |
| HashiCorp Vault | Secret Backend Plugin |
| Terraform | Step Plugin |
| Prometheus / Grafana | Metrics Exporter |
7.18 部署与升级(Deployment & Upgrade)
发布流程
- 构建二进制(
make build); - 生成镜像;
- 推送至 registry;
- K8s 滚动更新;
- 校验健康探针;
- 触发自动回滚(若失败)。
版本号策略
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 安全机制验证与渗透测试
| 测试类型 | 工具 | 目标 |
|---|---|---|
| SQL 注入 | ZAP | 验证防御 |
| XSS / CSRF | OWASP Zap | 前端安全 |
| SSRF | 自定义测试 | 网络隔离 |
| 权限绕过 | Burp Suite | RBAC 检查 |
| 文件上传 | Go test mock | MIME 校验 |
✅ 第七章总结
本章定义了 DeployLite 的完整技术实现路径与接口契约:
- 分层清晰,便于分工开发;
- 接口与协议标准化;
- 高性能、高安全、高扩展;
- 支持二次开发与插件生态。
整体目标:
“保持像 GitHub Actions 一样灵活,但像 Render 一样可自托管。”
接下来进入:
第八章:验收标准与测试计划(Acceptance & QA Plan)
它将定义各模块验收条件、功能/性能/安全测试用例、回归策略与自动化覆盖体系。