← 返回博客
RUENZHESARPTDEFRJAKOITTRIDVIFAHI

GitLab代理：如何为团队和CI/CD管道无缝配置访问权限

GitLab在您的地区被封锁或无法访问？我们将讨论如何为GitLab设置代理，以便整个团队顺利工作，CI/CD管道不会中断。

📅2026年7月19日
```html

GitLab是一个流行的代码存储和DevOps流程管理平台，全球数千个团队正在使用它。但是，如果访问GitLab在提供商、企业网络或整个国家的层面被封锁，该怎么办？更糟糕的是，当CI/CD管道在半夜崩溃，仅仅因为runner无法访问存储库。

在本文中，我们将讨论如何在Git客户端、GitLab Runner和企业服务器层面上为GitLab设置代理，以便整个团队可以在世界任何地方稳定工作。

为什么需要GitLab的代理：真实场景

在设置代理之前，重要的是要理解您正在解决的具体问题。情况各不相同，这将影响代理的类型选择和连接方式。

场景1：GitLab被提供商或国家封锁

在一些国家和企业网络中，访问gitlab.com受到限制。开发人员打开终端，输入 git pull — 然后得到超时。此时，代理作为中介工作：流量不是直接到gitlab.com，而是通过一个在没有限制的国家的中间服务器。

场景2：分布在不同国家的团队

想象一下：部分团队在俄罗斯工作，部分在哈萨克斯坦，部分在欧洲。每个人的网络条件和限制都不同。为了确保所有人都能稳定且以相同的速度工作，公司部署了企业代理服务器，通过该服务器，所有流量都通过统一的通道访问GitLab。

场景3：CI/CD runner无法访问外部依赖

GitLab Runner启动管道，在 npm install 或 pip install 阶段一切崩溃 — 因为运行runner的服务器位于没有直接互联网访问的封闭网络中。代理允许runner获取外部依赖，而无需为整个服务器打开完全的互联网访问。

场景4：自托管的GitLab在企业防火墙后

公司在内部网络中维护自己的GitLab服务器。远程开发人员需要连接到它。与为所有流量设置VPN不同，可以仅为GitLab流量设置代理 — 这更快且更易于管理。

场景5：流量监控和审计

大型公司通过企业代理将所有流量引导到存储库，以记录活动，监控谁在推送什么，并阻止不必要的操作。这是安全要求，而不是绕过封锁。

在设置之前重要的是要理解：

GitLab的代理可能需要在三个层面上同时使用：在开发者的机器上（Git客户端）、在GitLab Runner的服务器上（CI/CD），以及在GitLab服务器本身（如果是自托管的）。每个层面都单独配置。

哪种类型的代理适合GitLab

GitLab通过HTTPS和SSH协议工作。这立即决定了哪些类型的代理适用，哪些不适用。我们来看看选项。

代理类型 协议 适合GitLab 何时使用
HTTP/HTTPS代理 HTTP, HTTPS ✓ 是 通过HTTPS的Git，GitLab的Web界面
SOCKS5代理 TCP（任何） ✓ 是（最佳选择） 通过HTTPS和SSH的Git，CI/CD
SOCKS4代理 TCP ~ 部分适用 仅在没有SOCKS5时使用
透明代理 HTTP ✗ 否 不适用 — 不会绕过封锁

对于与GitLab的工作，最佳选择是 SOCKS5。它在TCP层工作，因此同样适合代理HTTPS连接（Web界面，通过HTTPS的git clone）和SSH连接（通过SSH在22或443端口的git push/pull）。

住宅代理与数据中心代理的比较

这完全取决于任务。如果目标是绕过GeoIP封锁或获得稳定的IP用于认证，数据中心代理是合适的选择 — 它们更快、更便宜，并提供低延迟，这在处理大型存储库时至关重要。

如果您的企业IP被GitLab列入黑名单（在进行激进扫描或发生安全事件时可能会发生），那么可以考虑使用住宅代理 — 它们的IP地址属于真实的家庭用户，极少被平台封锁。

为Git客户端设置代理（全局）

这是最常见的场景：开发人员在自己的机器上无法连接到GitLab。设置通过Git的配置进行 — 一次设置，适用于所有存储库。

选项A：为Git设置HTTPS代理

如果您通过HTTPS与GitLab工作（存储库地址以 https:// 开头），请在终端中执行： 

# 全局设置HTTP代理
git config --global http.proxy http://您的_代理_IP:端口

# 如果代理需要认证
git config --global http.proxy http://用户名:密码@您的_代理_IP:端口

# 对于SOCKS5代理（推荐）
git config --global http.proxy socks5://您的_代理_IP:端口

# 检查设置是否已应用
git config --global --get http.proxy

选项B：仅为gitlab.com设置代理（不影响其他存储库）

如果您不希望代理应用于所有Git操作（例如，GitHub或Bitbucket正常工作），可以仅为特定域设置代理： 

# 仅为gitlab.com设置代理
git config --global http.https://gitlab.com.proxy socks5://您的_代理_IP:端口

# 或者为您的自托管GitLab
git config --global http.https://git.yourcompany.com.proxy socks5://您的_代理_IP:端口

选项C：通过代理使用SSH（适用于通过SSH工作的人）

如果您通过SSH克隆存储库（[email protected]:...），则代理设置在SSH配置中，而不是在Git中。打开文件 ~/.ssh/config 并添加： 

# 对于Linux/macOS — 通过nc（netcat）
Host gitlab.com
    HostName gitlab.com
    User git
    ProxyCommand nc -X 5 -x 您的_代理_IP:端口 %h %p

# 对于Windows — 通过connect.exe（Git for Windows）
Host gitlab.com
    HostName gitlab.com
    User git
    ProxyCommand connect -S 您的_代理_IP:端口 %h %p

设置完成后，请通过命令 ssh -T [email protected] 检查连接。如果一切设置正确，您将看到来自GitLab的欢迎消息。

如何在不再需要时禁用代理

# 删除全局代理
git config --global --unset http.proxy

# 删除特定域的代理
git config --global --unset http.https://gitlab.com.proxy

GitLab Runner和CI/CD管道的代理

GitLab Runner是一个执行来自 .gitlab-ci.yml 的任务的代理。如果runner位于封闭网络中或在限制互联网访问的服务器上，则需要单独设置代理。开发人员的Git客户端设置在这里无效 — runner在另一台机器上工作。

方法1：在runner配置中设置环境变量

打开GitLab Runner的配置文件（通常是 /etc/gitlab-runner/config.toml）并在 [runners.env] 部分添加环境变量： 

[[runners]]
  name = "my-runner"
  url = "https://gitlab.com/"
  token = "您的_令牌"
  executor = "shell"
  environment = [
    "HTTP_PROXY=http://您的_代理_IP:端口",
    "HTTPS_PROXY=http://您的_代理_IP:端口",
    "NO_PROXY=localhost,127.0.0.1,您的内部域名.com"
  ]

修改配置后，重启runner： sudo gitlab-runner restart

方法2：在.gitlab-ci.yml中设置变量（在管道级别）

如果您不是runner的管理员，或者希望仅为特定项目设置代理，请直接在管道文件中添加变量： 

variables:
  HTTP_PROXY: "http://您的_代理_IP:端口"
  HTTPS_PROXY: "http://您的_代理_IP:端口"
  NO_PROXY: "localhost,127.0.0.1,.internal.company.com"

stages:
  - build
  - test
  - deploy

build:
  stage: build
  script:
    - npm install   # 现在将通过代理进行
    - npm run build

方法3：在GitLab项目设置中设置变量（不提交到存储库）

对于敏感数据（需要认证的代理），最佳方法是：转到设置 → CI/CD → 变量您的项目，并将变量 HTTP_PROXY、 HTTPS_PROXY、 NO_PROXY 作为受保护（masked）变量添加。它们将自动在所有管道中可用，但不会在日志中显示。

关于NO_PROXY — 不要忘记！

变量 NO_PROXY 是至关重要的。它需要添加所有内部域名和IP，runner应直接连接，绕过代理。否则，runner将尝试通过代理访问内部服务 — 这将导致管道崩溃。

Docker执行器的代理

如果runner使用Docker执行器，容器默认不会继承主机的代理设置。需要将变量添加到 config.toml 的 [runners.docker] 部分，或者在运行runner的主机上创建文件 /etc/systemd/system/docker.service.d/proxy.conf： 

[Service]
Environment="HTTP_PROXY=http://您的_代理_IP:端口"
Environment="HTTPS_PROXY=http://您的_代理_IP:端口"
Environment="NO_PROXY=localhost,127.0.0.1"

之后： sudo systemctl daemon-reload && sudo systemctl restart docker

自托管GitLab服务器的代理

如果您管理自己的GitLab服务器（通过Omnibus或Helm安装），则需要代理，以便GitLab本身可以访问外部服务：发送通知，连接外部CI系统，上传用户头像，与Jira或Slack集成。

在gitlab.rb中设置（Omnibus安装）

打开文件 /etc/gitlab/gitlab.rb 并添加或取消注释以下行： 

# GitLab的代理（Omnibus）
gitlab_rails['env'] = {
  "http_proxy" => "http://您的_代理_IP:端口",
  "https_proxy" => "http://您的_代理_IP:端口",
  "no_proxy" => "localhost,127.0.0.1,您的内部域名"
}

# 如果代理需要认证：
gitlab_rails['env'] = {
  "http_proxy" => "http://用户名:密码@您的_代理_IP:端口",
  "https_proxy" => "http://用户名:密码@您的_代理_IP:端口",
  "no_proxy" => "localhost,127.0.0.1"
}

修改配置后，应用设置： sudo gitlab-ctl reconfigure

通过管理区域设置出站连接

在GitLab 15.0+中，可以通过Web界面直接设置代理：转到管理区域 → 设置 → 网络 → 出站请求。在这里可以指定出站Webhooks的代理，并限制GitLab可以访问的IP范围。这对于安全性很有用 — 防止通过Webhooks进行的SSRF攻击。

通过代理为整个团队组织访问

当需要为5到50人的团队提供稳定的GitLab访问时，在每台机器上进行单独设置并不是最佳方法。让我们考虑更具可扩展性的解决方案。

方法1：企业代理服务器

部署一个代理服务器（例如，Squid或3proxy）以访问互联网。所有开发人员都将Git配置为使用该服务器。优点：集中管理，单一控制点，可以记录流量。缺点：服务器成为单点故障。

方法2：镜像（mirror）存储库

GitLab支持存储库镜像。可以将自托管的GitLab设置为gitlab.com的镜像。开发人员与内部服务器工作，而内部服务器通过代理与外部同步。这减少了每个开发人员对代理连接质量的依赖。

方法3：通过dotfiles或入职脚本进行自动设置

对于每个开发人员自行设置环境的团队，创建一个入职脚本是方便的，该脚本自动写入所需的Git设置。脚本存储在企业存储库中，并在设置新工作站时运行。 

#!/bin/bash
# setup-git-proxy.sh — 在设置新工作站时运行

PROXY_HOST="proxy.company.com"
PROXY_PORT="3128"

echo "为访问GitLab设置Git代理..."
git config --global http.https://gitlab.com.proxy "socks5://${PROXY_HOST}:${PROXY_PORT}"
git config --global http.sslVerify true
echo "完成！检查：git config --global --list | grep proxy"

团队部署的检查清单

  • 确定是否需要在开发者、runner或GitLab服务器（或所有三个层面）上设置代理
  • 选择代理类型：SOCKS5以实现最大兼容性
  • 为所有内部域和服务设置 NO_PROXY
  • 检查通过代理的SSH密钥是否正常工作（单独的步骤！）
  • 在企业wiki中记录设置
  • 为新员工创建入职脚本
  • 设置代理服务器的可用性监控

常见问题及其解决方案

即使在正确设置后，有时也会出现问题。以下是最常见的问题及其诊断方法。

问题1：SSL证书问题：无法获取本地颁发者证书

当代理服务器（尤其是企业代理）执行SSL检查 — 用自己的证书替换GitLab的证书时，会出现此错误。Git不信任此证书。解决方案：将企业根证书添加到受信任的证书中。 

# 临时解决方案（用于调试，不适用于生产环境！）
git config --global http.sslVerify false

# 正确的解决方案：添加企业证书
git config --global http.sslCAInfo /path/to/corporate-ca-bundle.crt

问题2：代理对HTTPS有效，但SSH无效

这是经典情况：在Git中设置了 http.proxy，HTTPS克隆工作正常，但SSH操作仍然无法通过。原因：SSH流量不通过HTTP代理。需要单独设置 ~/.ssh/config，如Git客户端部分所述。

替代方案：切换到通过HTTPS与GitLab工作。为此，请更改远程URL： 

# 检查当前远程
git remote -v

# 从SSH更改为HTTPS
git remote set-url origin https://gitlab.com/username/repo.git

问题3：CI/CD管道在克隆存储库阶段挂起

Runner直接从GitLab克隆存储库，使用令牌。如果runner位于代理后面，则此克隆也必须通过代理进行。确保在 config.toml 中设置了 HTTP_PROXY 和 HTTPS_PROXY，而不仅仅是在 .gitlab-ci.yml 中 — CI文件中的变量在克隆后应用，而不是之前。

问题4：代理有效，但非常慢

如果push/pull工作正常，但耗时比平时多5到10倍，问题可能出在代理服务器的带宽或其地理位置。对于处理大型存储库（100+ MB），选择低延迟和高带宽的代理非常重要。在这种情况下，数据中心代理优于住宅代理 — 它们提供更稳定的通道。

问题5：通过代理进行身份验证时需要重新输入密码

如果代理需要基本身份验证，而Git每次都要求输入密码，请设置凭据助手： 

# macOS — 使用钥匙串
git config --global credential.helper osxkeychain

# Windows — 使用Windows凭据管理器
git config --global credential.helper manager

# Linux — 缓存1小时
git config --global credential.helper "cache --timeout=3600"

如何快速诊断代理问题：

使用 GIT_TRACE=1 GIT_CURL_VERBOSE=1 git clone https://gitlab.com/... — 这将输出所有HTTP请求和响应的详细日志，包括有关代理的信息。

结论和建议

为GitLab设置代理是一个需要在多个层面上同时解决的任务。开发人员在工作机器上只需在Git或SSH的配置中写入几行即可。对于CI/CD，需要在runner的配置或项目设置中添加环境变量。对于自托管的GitLab — 更新 gitlab.rb 并重新构建配置。

有助于避免大多数问题的主要规则：

  • 使用SOCKS5 — 它同时适用于HTTPS和SSH
  • 始终为内部服务设置 NO_PROXY
  • 不要在生产环境中禁用SSL验证 — 添加企业证书
  • 对于CI/CD，将代理设置在 config.toml 中，而不仅仅是在 .gitlab-ci.yml 中
  • 记录设置 — 新团队的开发人员会感谢您

如果您正在寻找可靠的代理，以便从世界任何地方组织稳定的GitLab访问，建议考虑 数据中心代理 — 它们提供高速传输和低延迟，这在处理大型存储库和密集的CI/CD管道时尤为重要。对于那些需要最大匿名性或绕过GeoIP封锁的团队，住宅代理是合适的选择，它们的IP来自真实的家庭用户。

```