GitLab私有化部署后CI/CD默认不工作，因Shared Runners默认关闭且项目未启用CI/CD；需确保Runner注册URL与内网地址严格匹配、executor类型适配环境、.gitlab-ci.yml显式声明image和服务，并配置Nginx支持WebSocket连接。
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。
典型写法示例：
stages: - build - test <p>build-job: stage: build image: node:18-alpine script:</p><ul><li>npm ci</li><li>npm run build artifacts: paths:<ul><li>dist/</li></ul></li></ul><p>test-job: stage: test image: python:3.9-slim services:</p><ul><li>redis:alpine script:</li><li>pip install pytest</li><li>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 才算真正就绪。
