QT+GitLab+CI/CD架构与本地搭建全流程指南(windos系统)

目录

一、核心架构总览

二、完整流程与底层代码原理

1. 触发事件：流水线的起点

2. 流水线调度：GitLab 的核心大脑

3. Runner 轮询：任务领取的核心机制

4. Runner 执行 Job：真正干活的环节

5. 结果同步与流水线推进

三、GitLab CI/CD 本地搭建实战

【整体架构】

第一步：开启 WSL + 安装 Ubuntu

第二步：在 WSL Ubuntu 安装 GitLab 服务端

第三步：Windows 安装 GitLab Runner（最关键）

第四步：测试 CI/CD 是否能跑

配置 Qt 环境

给 Qt 项目写 CI/CD 配置

遇到的问题

• GitLab Server（Rails 后端）：负责事件监听、YAML 解析、流水线调度、状态管理和数据存储。
• GitLab Runner（Go 客户端）：主动轮询任务，隔离环境执行，负责日志与产物回传。
• PostgreSQL：存储全链路数据（如分区表是核心数据载体）。

• git push 推送代码
• 创建/更新 Merge Request
• 打 Tag
• 定时任务
• API 手动触发

• 事件触发后，Ci::CreatePipelineService 被调用，作为流水线创建的入口服务。
• 主要步骤：

1. 校验项目是否启用 CI/CD，是否存在 .gitlab-ci.yml
2. 解析 YAML 配置，生成流水线结构（Stage → Job）
3. 在数据库中创建流水线、阶段、Job 记录

• 作为调度中枢，负责状态流转和任务下发。

• 同一 Stage 内 Job 并行执行，前一 Stage 所有 Job 成功后，才进入下一 Stage
• 任一 Job 失败，流水线默认终止（可配置 allow_failure 跳过）
• Job 状态流转：created → pending → running → success/failed
• 数据库状态实时更新（p_ci_pipelines、p_ci_stages、p_ci_builds 的 status 字段）
• 记录 Job 的 started_at、finished_at、duration 等执行耗时

• Runner 是独立的 Go 二进制程序，主动长轮询 GitLab API（/api/v4/jobs/request）

• 每隔几秒向 GitLab 发送请求：「有没有任务给我？」
• GitLab 根据 Runner 标签、并发限制、项目权限，匹配并下发 Job
• Runner 领取任务后，进入执行流程

• Pull 模型：GitLab 不主动连接 Runner，Runner 主动拉取，防火墙友好，天然分布式
• 每个 Runner 可配置并发数，支持水平扩容，多 Runner 自动负载均衡

1. 环境准备：调用本地 Docker API，拉取 Job 指定镜像，启动全新容器，实现完全隔离
2. 代码拉取：自动执行 git clone，拉取对应分支/Commit 的代码
3. 脚本执行：按顺序执行 .gitlab-ci.yml 中 script 定义的命令（如构建、测试、打包、部署）
4. 日志实时回传：边执行边将 stdout/stderr 分块上传到 ci_build_trace_chunks 表
5. 产物上传：执行完成后，将 artifacts（如 dist 包、jar 包等）上传到 ci_job_artifacts 表
6. 状态回传：向 GitLab 返回 Job 执行结果（success/failed），销毁容器

• 更新 p_ci_builds 的 status、runner_id、duration、coverage 等字段
• 向 ci_build_trace_chunks 插入日志分块，向 ci_job_artifacts 插入产物元数据

• 接收 Runner 回传的 Job 结果，更新 p_ci_builds 状态
• 重新触发 ProcessPipelineService，检查当前 Stage 所有 Job 状态
• 若 Stage 全部成功，将下一 Stage 的 Job 状态从 created → pending，等待 Runner 领取
• 若所有 Stage 完成，更新 p_ci_pipelines 的最终状态（success/failed），记录总耗时

• 发送邮件/钉钉通知，更新 GitLab 页面流水线状态
• 页面展示的流水线、Job、日志，全部从 PostgreSQL 分区表读取

1. 提交信息加关键词：如“修复了xxx [skip ci]”，带 [skip ci] 会跳过
2. 构建脚本判断：仅指定分支构建
3. 手动触发：需自行点击触发

• WSL Ubuntu：运行 GitLab 服务端（网页、数据库、CI/CD 调度）
• Windows 10/11：运行 GitLab Runner（实际执行 CI/CD 任务）
• 通信方式：Runner 主动连接 WSL 中的 GitLab

1. 以管理员身份打开 Windows 终端（PowerShell）

1. 打开 Ubuntu，设置用户名/密码

1. 安装依赖

1. 添加 GitLab 源

1. 安装 GitLab 社区版（CE）

1. 启动 GitLab（如未自动启动）

1. 查看 GitLab 初始 root 密码

1. 浏览器访问 GitLab

• 打开 http://localhost
• 登录账号：root，密码为刚才复制的

1. 下载 Windows Runner

• 打开 PowerShell（普通用户即可）：

1. 注册 Runner 到 WSL 的 GitLab

• 前往 GitLab 获取注册地址和 token：
  • 打开 http://localhost
  • 进入 Menu → Admin → Runners
  • 点击 Register an instance runner，复制 URL 和 Token

• 回到 Windows PowerShell 执行注册：

• 按提示输入：
  • GitLab instance URL: http://localhost
  • token: 复制的 token
  • 描述：windows-runner
  • 标签：windows
  • 执行器：powershell

1. 安装服务并启动

• 在 GitLab 新建项目，
• 创建文件 .gitlab-ci.yml：

• test_job:
    tags:
      - windows
    script:
      - echo "我在 Windows 上运行 CI/CD 成功！"

• 提交后，前往 CI/CD → Pipelines 查看运行结果。

1. 添加以下路径到系统 PATH：

1. 测试是否配置成功

• 打开新的 CMD / PowerShell 输入：

• 重启 GitLab Runner：

• 在项目根目录创建 .gitlab-ci.yml：

stages:
  - build

build_qt:
  stage: build
  tags:
    - windows       # 必须匹配你的 runner 标签
  script:
    - echo "========== 开始编译 Qt 项目 =========="
    - qmake your_project_name.pro   # 替换成你的 pro 文件
    - mingw32-make -j4
    - echo "========== 编译完成 =========="
  artifacts:
    paths:
      - release/*.exe

• 提交并推送，即可在 Pipelines 查看构建结果！