在 GitHub Actions 与 CI/CD 中配置代理

在 GitHub Actions 和 CI/CD 中配置代理，指的是在 workflow 定义中（通常位于 job 或 step 级别）设置 HTTP_PROXY、HTTPS_PROXY、NO_PROXY 等标准代理环境变量。这样，CI/CD 流水线中执行的 action、脚本和工具就会将网络流量经由指定的代理服务器转发。

企业经常部署代理服务器，用于控制出站网络访问、执行安全策略、过滤内容以及缓存高频访问的资源。对于运行在此类环境中的 CI/CD 流水线，配置代理是必需的，只有这样构建工具、依赖管理器和测试脚本才能访问外部服务、软件包仓库或 API。GitHub Actions 的 runner，尤其是 self-hosted runner，可能需要配置代理才能访问 GitHub 本身或其他互联网资源。

设置代理环境变量

在基于 Linux 的环境中（GitHub 托管的 runner 主要使用该环境），配置代理最常见、通用性最强的方法就是环境变量。

• HTTP_PROXY：指定用于 HTTP 请求的代理服务器。
• HTTPS_PROXY：指定用于 HTTPS 请求的代理服务器。
• NO_PROXY：以逗号分隔的主机名、域名或 IP 地址列表，这些目标将绕过代理。对于直接访问内部资源而言至关重要。

HTTP_PROXY 和 HTTPS_PROXY 的格式通常为 http://[user:password@]host:port。
多数工具对这些变量的大写形式（HTTP_PROXY）和小写形式（http_proxy）都能识别；环境变量使用大写是通行做法。

workflow 级别的代理配置

在 job 级别设置代理，可确保该 job 内的所有 step 都继承该配置。

name: CI with Proxy
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: http://proxy.example.com:8080
      HTTPS_PROXY: http://proxy.example.com:8080
      NO_PROXY: localhost,127.0.0.1,.internal.company.com,github.com
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Node.js dependencies
        run: npm install

      - name: Download a file via curl
        run: curl -v https://api.example.com/data

      - name: Access internal service (bypasses proxy)
        run: curl -v http://internal-service.internal.company.com/status

step 级别的代理配置

如果某些 step 需要不同的代理设置，或需要覆盖 job 级别的配置，可以在 step 级别定义环境变量。

name: CI with Specific Step Proxy
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env: # job 的默认代理（如有）
      HTTP_PROXY: http://default-proxy:8080
      HTTPS_PROXY: http://default-proxy:8080
      NO_PROXY: localhost,127.0.0.1
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Step using default proxy
        run: curl https://external-api.com/v1

      - name: Step using a different proxy
        env:
          HTTP_PROXY: http://special-proxy:3128
          HTTPS_PROXY: http://special-proxy:3128
          NO_PROXY: localhost,127.0.0.1,api.special-domain.com
        run: curl https://api.special-domain.com/v2

使用 secrets 进行代理认证

如果代理需要认证，请将用户名和密码直接写入代理 URL。出于安全考虑，请将凭据保存为 GitHub Actions secret，并在 workflow 中引用。

首先在 GitHub 仓库设置中创建仓库 secret（例如 PROXY_USER、PROXY_PASS）。

name: Authenticated Proxy Workflow
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: http://${{ secrets.PROXY_USER }}:${{ secrets.PROXY_PASS }}@proxy.example.com:8080
      HTTPS_PROXY: http://${{ secrets.PROXY_USER }}:${{ secrets.PROXY_PASS }}@proxy.example.com:8080
      NO_PROXY: localhost,127.0.0.1,.internal.company.com
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Perform network operation
        run: npm install # 或 curl 等

常用工具与代理的交互

虽然 HTTP_PROXY 和 HTTPS_PROXY 被广泛支持，但部分工具提供了各自专门的配置方式。

git 命令

git 在远程操作中通常会遵循 HTTP_PROXY 和 HTTPS_PROXY。若需要显式配置，或环境变量不足以生效，可以使用 git config。

# 为 HTTP 和 HTTPS 的 git 操作设置代理
git config --global http.proxy http://proxy.example.com:8080
git config --global https.proxy http://proxy.example.com:8080

# 为特定 remote 配置专用代理
git config http.https://github.com/.proxy http://github-proxy:8080

npm、yarn

npm、yarn 等 Node.js 包管理器会遵循 HTTP_PROXY 和 HTTPS_PROXY 环境变量。它们同时提供各自的配置命令用于持久化设置。

# 使用 npm config
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080
npm config set no-proxy localhost,127.0.0.1,.internal.com

# 使用 yarn config
yarn config set proxy http://proxy.example.com:8080
yarn config set httpsProxy http://proxy.example.com:8080
yarn config set no-proxy localhost,127.0.0.1,.internal.com

docker（镜像构建与容器运行时）

Docker 的代理设置需要分别处理镜像构建阶段和容器运行阶段。

Docker 构建阶段代理

对于在 docker build 过程中执行的命令（例如 RUN apk add、RUN apt-get update），必须将代理设置作为构建参数传入。

Dockerfile 示例：

FROM alpine:latest

# 定义代理设置的构建参数
ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

# 为后续 RUN 命令设置环境变量
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY
ENV NO_PROXY=$NO_PROXY

# 示例：安装软件包时使用代理
RUN apk add --no-cache curl

# ... Dockerfile 的其余部分

GitHub Actions workflow step：

- name: Build Docker image with proxy
  run: |
    docker build . \
      --build-arg HTTP_PROXY=${{ env.HTTP_PROXY }} \
      --build-arg HTTPS_PROXY=${{ env.HTTPS_PROXY }} \
      --build-arg NO_PROXY=${{ env.NO_PROXY }} \
      -t my-app:latest

Docker 容器运行时代理

如果 workflow 运行 Docker 容器（例如使用 container: 键或 docker run），必须将代理设置作为环境变量传入容器。

使用 container: 键：

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: my-custom-image:latest
      env:
        HTTP_PROXY: ${{ env.HTTP_PROXY }}
        HTTPS_PROXY: ${{ env.HTTPS_PROXY }}
        NO_PROXY: ${{ env.NO_PROXY }}
    steps:
      - name: Run command inside container
        run: curl https://external-api.com/data

在 step 中使用 docker run：

- name: Run Docker container with proxy
  run: |
    docker run \
      -e HTTP_PROXY=${{ env.HTTP_PROXY }} \
      -e HTTPS_PROXY=${{ env.HTTPS_PROXY }} \
      -e NO_PROXY=${{ env.NO_PROXY }} \
      my-app:latest /app/script.sh

Java 应用（Maven、Gradle）

Java 应用（包括 Maven、Gradle 等构建工具）通常要求以 Java 系统属性的形式传入代理设置。常见做法是通过 MAVEN_OPTS 或 _JAVA_OPTIONS 环境变量设置。

# Maven 用
export MAVEN_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080 -Dhttp.nonProxyHosts='localhost|127.0.0.1|*.internal.com'"

# Gradle 用（同样适用于其他基于 JVM 的工具）
export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080 -Dhttp.nonProxyHosts='localhost|127.0.0.1|*.internal.com'"

此外，Maven 也可以通过 ~/.m2/settings.xml 配置，Gradle 可以通过项目目录或用户主目录中的 gradle.properties 配置。

代理问题排查

• 确认环境变量：在某个 step 中执行 run: env | grep -i proxy，确认代理环境变量已正确设置且对 runner 的 shell 可见。
• 检查 NO_PROXY：确保内部主机和 GitHub 相关域名已正确列入 NO_PROXY，避免不必要的代理转发或路由问题。
• 代理服务器日志：如有条件，请在代理服务器日志中查找来自 GitHub Actions runner IP 地址的连接尝试。这有助于判断请求是否到达代理，以及被拒绝的原因（例如认证失败、访问被拒）。
• 网络连通性：在 workflow step 中使用 curl -v --proxy <your-proxy-url> <target-url>，显式测试经由代理到某个已知外部端点的连通性。
• SSL/TLS 证书问题：如果使用 HTTPS 代理，或通过 HTTP 代理访问 HTTPS 站点，且代理会做 SSL 检测，runner 可能出现证书校验错误。此时需要将代理的根 CA 证书加入 runner 的信任库。这属于复杂配置，通常在 self-hosted runner 环境中处理。

代理配置速查