GitLab中Stuck状态指CI/CD流水线卡住无法继续执行

Question

在GitLab CI/CD中，流水线任务常因Runner未正确配置或离线而处于“Stuck”状态。常见问题是：作业已触发但无可用Runner执行，尤其当使用特定标签（tag）的Runner时，若无匹配的活跃Runner，任务将无限等待。此外，共享Runner被禁用、项目未关联Runner或权限设置错误也会导致此问题。需检查项目Runner配置、确保Runner处于活动状态并正确分配标签。

Answer 1

1. GitLab CI/CD 流水线“Stuck”状态的初步识别

在GitLab CI/CD中，当流水线作业触发后长时间未开始执行，且界面显示为“pending”或“stuck”，通常意味着没有可用Runner来处理该任务。这种现象在使用标签（tags）进行Runner匹配时尤为常见。例如，若作业配置了 tag: deploy-prod，但系统中没有运行带有该标签的活跃Runner，则作业将无限等待。

• 作业状态：pending / stuck
• 常见提示信息：“Job is stuck, no runners are available”
• 触发条件：新提交推送、手动触发流水线
• 影响范围：单个作业或整个流水线阻塞

2. Runner类型与作用域分析

GitLab支持三种类型的Runner：

Runner类型	作用范围	是否默认启用	典型问题
Shared Runner	所有项目（白名单内）	可全局启用/禁用	被管理员禁用
Group Runner	所属群组及子项目	需显式分配	权限配置错误
Project Runner	仅当前项目	需手动注册并关联	未正确绑定项目

3. 标签（Tags）匹配机制深度解析

GitLab通过标签实现作业与Runner的精准调度。每个作业可指定一个或多个tag，而Runner也需注册时声明其所支持的tag集合。只有当两者完全匹配时，Runner才会拉取并执行该作业。

deploy_job:
  script:
    - echo "Deploying..."
  tags:
    - k8s
    - production

上述作业要求Runner同时具备 k8s 和 production 标签。若任意标签缺失或拼写错误（如prod vs production），则无法匹配。

4. 检查Runner状态与配置流程

排查“stuck”问题应遵循以下步骤：

1. 进入项目页面 → Settings → CI / CD → Runners
2. 确认是否有活跃Runner显示
3. 检查Runner状态是否为“online”
4. 核对Runner的tag列表是否包含作业所需标签
5. 查看Runner是否被锁定（locked）或暂停（paused）
6. 验证Runner是否已正确注册到GitLab实例
7. 检查网络连通性与认证token有效性
8. 审查config.toml中的并发设置与executor类型

5. 常见配置错误与修复方案

以下是导致Runner不可用的典型配置问题及其应对策略：

问题类型	症状表现	诊断方法	解决方案
标签不匹配	作业stuck，无日志输出	对比.gitlab-ci.yml与Runner配置	统一标签命名规范
共享Runner关闭	项目无任何Runner可用	检查Admin Area → Runners	启用共享Runner或注册专用Runner
Runner离线	Status显示“offline”	查看Runner主机运行状态	重启gitlab-runner服务
权限不足	Runner无法访问项目资源	检查CI_JOB_TOKEN权限	调整项目访问级别

6. 自动化监控与预防机制设计

为避免频繁出现“stuck”问题，建议构建自动化监控体系。可通过Prometheus + Grafana采集Runner健康指标，并设置告警规则：

# gitlab-runner exporter metrics 示例
- alert: RunnerOffline
  expr: gitlab_runner_status{status="offline"} == 1
  for: 5m
  labels:
    severity: critical
  annotations:
    summary: "GitLab Runner {{ $labels.name }} is offline"

7. 高级场景下的分布式Runner架构

在大规模部署中，推荐采用分层Runner架构：

graph TD A[GitLab Server] --> B{Runner Dispatcher} B --> C[Kubernetes Executor - Tags: k8s,container] B --> D[Docker Executor - Tags: docker,test] B --> E[Shell Executor - Tags: legacy,local] C --> F[Pod in Cluster] D --> G[Docker Host] E --> H[On-premise Server]

该模型实现了资源隔离、弹性伸缩与故障隔离，显著降低因单一Runner失效引发的大面积“stuck”风险。