第二章：总体架构与系统设计（System Architecture & Design）

2.1 系统架构总览（Architecture Overview）

平台采用 分层 + 模块化 架构设计，分为 4 个核心层级：

架构示意（逻辑层）

+------------------------------------------------------------+
|                        Web UI / API                        |
+----------------------------+-------------------------------+
|        Scheduler           |         Policy Engine          |
+----------------------------+-------------------------------+
|        Metadata Store      |         Secret Store           |
+----------------------------+-------------------------------+
|       Artifact & Cache     |        Database (PostgreSQL)   |
+------------------------------------------------------------+
|                      Runner Plane                           |
|  Runner Agent <-> Job Executor <-> Build Container/VM        |
+------------------------------------------------------------+
|              Observability: Logs / Metrics / Tracing        |
+------------------------------------------------------------+

2.2 模块划分（Module Overview）

2.3 数据流与工作流（Data Flow & Workflow）

流程：从 Commit 到 Deployment

1. 触发（Trigger）：Push / Tag / 手动执行 → API 接口。
2. 调度（Schedule）：Scheduler 分配任务 → 选取空闲 Runner。
3. 执行（Execute）：Runner 下载代码 → 运行构建步骤。
4. 打包（Package）：产出二进制或镜像 → 上传 Artifact Store。
5. 部署（Deploy）：根据 YAML 中环境配置执行发布。
6. 验证（Verify）：健康检查、回滚策略判定。
7. 记录（Record）：生成日志、指标与审计事件。

2.4 数据模型与实体（Data Model）

主要实体

2.5 Runner 执行架构（Runner Execution Engine）

• 采用 pull-based 模式：Runner 定期向控制平面请求任务（避免外网访问问题）。

• 每个 Runner 可定义：

  • capacity（最大并发任务数）；
  • tags（如 region、type）；
  • isolation_mode（docker/k8s/host）；

• 支持多租户隔离：每个租户可绑定专属 Runner 组。

执行流程

Runner Start
   ↓
Register -> Control Plane
   ↓
Poll Jobs (Redis Queue)
   ↓
Execute Job Steps
   ↓
Stream Logs to API
   ↓
Upload Artifacts
   ↓
Report Status (Success/Failed)

2.6 Pipeline Engine（流水线引擎）

• 设计模式：基于 DAG（有向无环图）的状态机。
• 每个 Stage：定义输入/输出 Artifact、依赖、执行条件（when）、环境变量。
• 支持条件执行与审批。

状态机示例

Stage: build → test → package → deploy
Transitions:
  build.success -> test.start
  test.success -> package.start
  package.success -> deploy.approval
  deploy.approval -> deploy.start

• 失败策略（Failure Policy）：

  • stop-on-failure（默认）
  • continue-on-failure（警告但不中断）
  • rollback-on-failure（触发自动回滚）

2.7 存储系统设计（Storage Design）

2.8 网络与安全设计（Network & Security）

• 通信加密：所有模块之间通过 HTTPS/gRPC TLS。

• 身份认证：

  • 平台登录：JWT + RefreshToken；
  • Runner 注册：基于 Token + Fingerprint；

• 访问控制（RBAC）：

  • 组织级：Owner / Maintainer / Developer / Viewer；
  • 环境级：可配置访问与部署权限；

• 安全策略：

  • 每次部署执行沙箱隔离（容器或用户空间）。
  • Secret 注入时只读，任务完成自动清理。
  • 日志中屏蔽敏感值（masking）。

2.9 可扩展性与高可用（Scalability & HA）

• 控制平面支持多副本部署（K8s StatefulSet）。
• Runner 可弹性水平扩容（HPA / Docker swarm）。
• Scheduler 采用 Redis Stream 队列 + 任务分片机制。
• API Server 提供幂等接口（防重复触发）。
• 支持集群化部署：控制平面与执行平面可分离运行。

2.10 可观测性与日志链路（Observability）

• Metrics（Prometheus）：

  • pipeline_run_duration_seconds
  • runner_job_queue_length
  • deployment_success_rate

• Tracing：

  • 每个 JobRun 带 traceId，可串联 build → deploy → verify 全链路。

• Logging：

  • 实时流式日志（WebSocket + Chunk 存储）。

• Audit Trail：

  • 用户操作、API 调用、部署事件、审批流全记录。

• Error Aggregation：

  • 构建失败原因聚合统计（依赖错误 / 超时 / 网络 / 配置）。

2.11 系统交互与外部集成（Integrations）

2.12 性能目标（Performance Goals）

2.13 模块依赖与接口关系（Dependencies）

graph LR
  A["Web UI"] --> B(API Server)
  B --> C[Scheduler]
  B --> D[Artifact Service]
  B --> E[Secret Service]
  C --> F[Runner Agent]
  F --> D
  F --> G[Cache Store]
  B --> H[Database]
  B --> I[Policy Engine]
  B --> J[Audit Logger]
  H --> J

2.14 关键技术选型（Tech Stack）

2.15 安全与合规设计（Security & Compliance Design）

安全模型

1. 数据隔离

   • 组织级命名空间（OrgID 作用域）。
   • 数据库层级 row-level filtering。

2. 最小权限原则（Least Privilege）

   • RBAC 角色限制 API 操作（读/写/执行/审批）。
   • 每个 Runner 仅能访问分配项目。

3. 传输安全

   • 所有流量 HTTPS/TLS 1.3。
   • gRPC 通信使用双向 TLS。

4. 存储加密

   • AES-256-GCM 加密 Secrets。
   • Artifact 哈希校验（SHA256）防篡改。

5. 执行沙箱

   • 每个任务在独立容器 / 用户空间执行。
   • 临时文件在任务结束后销毁。

6. 合规性

   • 数据保留策略（Retention Policy）符合 GDPR。
   • 审计日志 ≥ 180 天可追溯。

2.16 RBAC 权限模型（Role-Based Access Control）

权限设计采用 RBAC + Policy Hook 混合模式：

• RBAC 控制“谁能访问什么”；
• Policy 控制“在什么条件下允许”。

2.17 多租户架构（Multi-Tenancy Design）

租户资源配额：

• 最大并发任务数（Concurrency）
• 存储上限（GB）
• 每月构建分钟数（Build Minutes）
• 成员数量限制

超限触发通知或自动降级（如暂停 Runner 分配）。

2.18 Scheduler 调度算法（Task Scheduling Algorithm）

调度核心目标：快速分配 + 资源利用最大化 + 多租户公平性

算法要点

1. 任务队列

   • 使用 Redis Stream，每个 Runner 订阅自身标签对应任务。

2. 分配策略

   • 优先满足低延迟项目；
   • 租户配额加权轮询；
   • Runner 健康度评分影响优先级。

3. 任务重试

   • 最大重试 3 次，间隔递增。
   • 标记失败任务进入 dead-letter 队列。

4. 调度日志

   • 每次任务分配写入 scheduler_events 表；
   • 可用于性能分析与审计。

2.19 可扩展与插件架构（Plugin System）

平台提供标准插件机制，支持在构建、打包、部署各阶段挂钩。

插件注册文件：

plugin:
  name: "cache"
  type: "step"
  entry: "plugins/cache/main.go"
  hook: "pre_build"

2.20 数据库设计概要（Database Schema Overview）

示例核心表结构（简化版）：

表：projects

CREATE TABLE projects (
  id SERIAL PRIMARY KEY,
  org_id BIGINT NOT NULL,
  name VARCHAR(128) NOT NULL,
  repo_url TEXT,
  default_branch VARCHAR(64),
  created_at TIMESTAMP,
  updated_at TIMESTAMP
);

表：pipeline_runs

CREATE TABLE pipeline_runs (
  id SERIAL PRIMARY KEY,
  project_id BIGINT NOT NULL,
  status VARCHAR(16),
  triggered_by VARCHAR(128),
  duration_ms BIGINT,
  start_time TIMESTAMP,
  end_time TIMESTAMP
);

表：artifacts

CREATE TABLE artifacts (
  id SERIAL PRIMARY KEY,
  project_id BIGINT NOT NULL,
  version VARCHAR(64),
  type VARCHAR(32),
  storage_path TEXT,
  hash VARCHAR(128),
  size BIGINT,
  created_at TIMESTAMP
);