Module Document

基础架构 · GitLab / CI/CD / 制品仓详细设计文档

基础架构 · GitLab / CI/CD / 制品仓详细设计文档

版本: v0.1
日期: 2026-07-06
归属: 基础架构 / GitLab / CI/CD / 制品仓

1. 模块定位与目标

提供代码版本管理、自动化构建/测试/部署流水线和制品仓库。国内部署自建 GitLab（阿里云服务器），制品仓国内走阿里云 ACR，海外走 AWS ECR。所有发布包必须经由 CI 流水线产出，禁止手工构建上线。

目标 说明
统一代码事实源 所有代码（固件/App/云端/工具）统一进 GitLab 管理。
流水线门禁 main/release 分支合并须通过 CI 检查，禁止 force push。
制品可追溯 每个制品有 Git commit、构建时间、构建人、测试报告关联。
多端制品分发 Docker 镜像/固件包/App 包/SDK 制品分类存储，按权限分发。

2. 执行计划

阶段 时间 交付物 Owner 工作量
P0 GitLab 部署 0–14 天 自建 GitLab、代码迁移、分支保护、权限配置 平台运维 1人×2周
P1 基础 CI 15–35 天 各项目接入 GitLab CI、lint/test/build 流水线 各研发团队 分端并行
P2 制品仓 36–50 天 阿里云 ACR + AWS ECR 接入，制品命名规范，tag 策略 平台运维 1人×2周
P3 CD 流水线 51–80 天 测试环境自动部署、生产环境审批部署、ArgoCD 集成 平台运维+研发 2人×4周
P4 固件/OTA 集成 81–110 天 固件构建流水线、签名、上传 OTA 服务，协议 SDK 集成 固件+平台 2人×4周
P5 审计优化 111–150 天 构建缓存、制品清理策略、安全扫描接入、合规报告 平台运维 1人×3周

3. 困难点与复杂度分析

困难点 复杂度 应对
多端构建环境差异大（C/Go/Flutter/Node） 高 每类制品维护独立 Docker 构建镜像，GitLab CI 按项目类型选择 runner 镜像。
固件构建工具链依赖复杂（交叉编译） 高 固件专用 runner，工具链镜像版本固定，构建环境与开发环境隔离。
国内 GitLab + 海外 AWS ECR 制品同步 中 国内构建推 ACR，海外部署从 ECR 拉取；镜像跨区同步走专用 Sync Job，不实时双推。
生产部署审批流程设计 中 GitLab Environment + Protected Branches，生产部署需 2 人 approve，审批记录在 MR。
制品存储成本控制 中 制品设 TTL 策略：feature 分支制品 7 天清理，release 制品永久保留最近 10 版。

4. 核心流程

flowchart LR
  A["开发者 Push 代码"] --> B["GitLab CI 触发"]
  B --> C["Lint + 单元测试"]
  C --> D{通过?}
  D -->|否| E["通知开发者修复"]
  D -->|是| F["构建制品"]
  F --> G["推送到制品仓(ACR/ECR)"]
  G --> H["自动部署到测试环境"]
  H --> I["集成测试 + 协议回归"]
  I --> J{生产发布?}
  J -->|是| K["2 人审批 Approve"]
  K --> L["部署生产"]
  J -->|否| M["等待下次发布窗口"]

5. 系统架构

flowchart LR
  subgraph GitLab["GitLab (阿里云自建)"]
    REPO["代码仓库"] --> CI["CI Runner"]
    CI --> PIPELINE["Pipeline"]
  end
  subgraph Artifacts["制品仓"]
    ACR["阿里云 ACR (国内)"]
    ECR["AWS ECR (海外)"]
    OTA_STORE["OTA 固件包存储"]
  end
  subgraph Deploy["部署层"]
    ARGO["ArgoCD"] --> ACK["阿里云 ACK"]
    ARGO --> EKS["AWS EKS"]
    OTA_SVC["OTA 服务"] --> OTA_STORE
  end
  PIPELINE --> ACR
  PIPELINE --> OTA_STORE
  ACR --"Sync Job"--> ECR
  ARGO --> ACR
  ARGO --> ECR

6. 关键技术决策

决策点 选择 理由
代码托管 自建 GitLab (阿里云 ECS) 代码安全合规，完全自控，CI 与 GitLab 原生集成。
CI Runner GitLab Runner (Docker executor) 隔离构建环境，支持多语言，资源按需伸缩。
国内制品仓 阿里云 ACR 与 ACK 原生集成，国内拉取速度快，有企业版权限管控。
海外制品仓 AWS ECR 与 EKS 原生集成，全球区域低延迟拉取。
CD 工具 ArgoCD (GitOps) 配置即代码，多集群统一，变更有 diff 审计。
镜像安全扫描 Trivy (集成 GitLab CI) 开源免费，扫描快，阻断高危 CVE 合并。

7. 数据模型

模型 关键字段 说明
PipelineRun id、project、branch、commit、status、triggered_by、started_at 流水线执行记录。
ArtifactRecord id、pipeline_id、type、name、tag、registry_uri、size、created_at 制品记录。
DeployRecord id、artifact_id、env、cluster、approvers、deployed_at、status 部署审计记录。
BuildImage id、name、lang、version、base_image、maintained_by 构建镜像台账。

8. 接口设计

接口 方法 说明
/pipelines GET 流水线执行记录查询，含状态和制品链接。
/artifacts GET 制品列表，按项目/类型/分支/时间筛选。
/artifacts/{id}/download GET 下载制品，记录审计。
/deployments GET/POST 部署记录查询 / 触发生产部署（需 approve）。

9. 验收点

验收点 量化标准
代码收口 核心代码仓 100% 迁入 GitLab，无游离外部仓库。
分支保护 main/release 分支 100% 开启保护，禁止 force push，合并须 CI 通过。
制品可追溯 每个制品 100% 有 commit hash、构建时间、流水线 ID 可查。
生产审批 生产部署 100% 有 2 人 approve 记录，0 例未审批直接上线。
安全扫描 高危 CVE 阻断合并，扫描覆盖率 100% 核心镜像。
制品清理 feature 分支制品 7 天自动清理，存储使用率可见。

10. 风险与应对

风险 应对
GitLab 自建单点故障 定期备份 Git 数据到 OSS，配置高可用 PostgreSQL；灾难恢复演练每季度一次。
CI Runner 资源瓶颈 Runner 按类型（固件/Docker/测试）分组，按需弹性扩容阿里云 ECS。
制品仓存储成本失控 强制 TTL 策略，每月成本报表，高存量项目人工复盘。
跨区镜像同步延迟 非实时同步（5 分钟以内），海外部署前检查 ECR 镜像已同步。