为GitLab私有化部署配置CI/CD流水线的完整教程-git-PHP中文网

gitlab私有化部署后ci/cd默认不工作，因shared runners默认关闭且项目未启用ci/cd；需确保runner注册url与内网地址严格匹配、executor类型适配环境、.gitlab-ci.yml显式声明image和服务，并配置nginx支持websocket连接。

为gitlab私有化部署配置ci/cd流水线的完整教程

GitLab私有化部署后，CI/CD默认不工作

刚装完 GitLab Server 和 Runner，.gitlab-ci.yml 提交后流水线状态一直显示 pending 或直接不触发，不是配置写错了，而是两个关键开关没打开：Runner 未注册成功、项目未启用 CI/CD。私有化环境里，Shared runners 默认关闭，且 Runner 注册用的 URL 和 registration token 必须严格匹配 GitLab 实例的内网地址（比如 http://gitlab.internal:8080），不能填公网域名或 localhost。

检查步骤：

进项目 Settings > CI/CD > Runners，确认 “Disable shared runners” 已勾选，下方列出的 Active Runners 数量 ≥1
在 Runner 服务器上执行 sudo gitlab-runner verify，返回 Running in system-mode 且无报错
查看 /etc/gitlab-runner/config.toml，确认 url 值与 GitLab Web 界面右下角 “Set up a specific runner manually” 中的 URL 完全一致（协议、端口、路径都不能差）

Runner 注册时选错 executor 类型会导致构建失败

私有化部署常见错误是注册 Runner 时盲目选 docker，结果在无 Docker 的 CentOS 7 服务器上卡在 Preparing environment。executor 类型必须和实际运行环境匹配：

shell：适合简单脚本、Node.js/Python 项目，无需容器，但隔离性差，多个 job 可能互相污染环境
docker：需宿主机已安装 Docker，推荐配合 docker:dind 使用；注意内核参数 vm.max_map_count 和 net.ipv4.ip_forward 必须开启
ssh：适合已有稳定测试机集群的场景，但密钥管理复杂，调试困难

金融类项目常用 docker+privileged 模式跑 SonarQube 扫描，但医疗系统因合规要求禁用特权容器，就得切回 shell + 预装 JDK/Maven 的方式。

`.gitlab-ci.yml` 在私有化环境要显式声明 image 和 services

公有云 GitLab 默认提供 ruby:2.7 等基础镜像，私有化部署的 Runner 不自带任何运行时。不写 image: 就会报错 command not found: npm 或 java: command not found。

Github Auto

管PR、盯Issue、跑CI、发Release——GitHub仓库日常运维扔给它。少开几个Chrome标签页。

下载

典型写法示例：

stages:
  - build
  - test
<p>build-job:
stage: build
image: node:18-alpine
script:</p>

npm ci
npm run build artifacts: paths:
- dist/

test-job: stage: test image: python:3.9-slim services:

redis:alpine script:
pip install pytest
pytest tests/
注意点：
- image 必须是私有 Registry 可拉取的镜像；若用 Docker Hub，需在 Runner 配置中加 pull_policy = "if-not-present" 避免每次重建缓存
- services 仅对当前 job 生效，跨 job 不共享；Redis/PostgreSQL 等服务启动后，连接地址固定为 redis / postgres，不用写 IP
- Java 项目建议用 maven:3.9-openjdk-17 而非 openjdk:17，避免手动装 Maven

流水线卡在 “Waiting for a runner” 通常是网络或权限问题

私有化环境下最隐蔽的问题：Runner 服务器能 ping 通 GitLab，但无法反向建立 WebSocket 连接，导致状态始终为 waiting_for_runner。根本原因常是防火墙或反向代理配置遗漏。

GitLab Server 的 Nginx 配置中，必须包含 proxy_http_version 1.1 和 proxy_set_header Upgrade $http_upgrade，否则 Runner 注册握手失败
Runner 服务器出方向需放行 GitLab Server 的 443/80 端口，且不能被企业级 WAF 拦截 Connection: upgrade 请求头
若 Runner 和 GitLab 分属不同 VLAN，需确认二层互通；某些银行环境要求 Runner 必须和 GitLab 在同一安全域，否则即使端口通也无法注册

验证方法：在 Runner 服务器执行 curl -v https://gitlab.internal/api/v4/runners/status，HTTP 200 且响应体含 "online":true 才算真正就绪。