### [GitHub Actions自托管Runner怎么走代理？拉代码、Actions与容器排查](https://www.jiyueip.com/article/7953)

**Published:** 2026-07-22T17:59:47

**Author:** 斑斓助理

**Excerpt:** GitHub Actions自托管Runner使用代理时，要区分Runner服务、Git、Node运行时、容器任务和包管理器。本文说明服务环境、NO_PROXY、凭据保护、拉取Actions失败与分层验证。

自托管GitHub Actions Runner部署在受限网络里，最常见的现象是Runner显示在线，但checkout失败、下载Action超时，或容器步骤无法拉镜像。因为Runner服务、Git、Node.js、Docker守护进程和作业内命令可能读取不同代理配置。

先依据组织政策确认代理用途和允许访问的GitHub端点，再逐层配置。不要用代理规避仓库、组织或网络访问控制。

## 一、流水线里有哪些网络客户端

| 组件  | 网络动作 | 配置来源 |
| --- | --- | --- |
| Runner服务 | 连接GitHub、接收任务 | 服务环境与Runner文档 |
| Git | clone、fetch子模块 | 环境变量或Git配置 |
| Action运行时 | 下载依赖、调用API | Node/程序自身代理能力 |
| 包管理器 | npm、pip、Maven等 | 各自配置与证书库 |
| Docker | 拉镜像、容器网络 | 守护进程与容器配置 |

## 二、Runner作为服务为什么不继承终端代理

Runner常以systemd、Windows服务或其他服务管理器启动，不继承管理员当前Shell。需要把代理配置放进服务的有效环境，并重启Runner服务。具体变量与支持范围应查看当前Runner官方文档。

Linux服务环境可参考[systemd代理drop-in方法](https://www.jiyueip.com/article/7931)。

## 三、NO\_PROXY不要漏掉内部依赖

自托管Runner可能访问内部Git、制品库、缓存、容器仓库和企业API。若它们错误经过外部代理，会造成DNS、TLS或权限问题。NO\_PROXY应按实际依赖列出，不复制其他服务器模板。

不同工具对后缀、CIDR和大小写变量的支持不同，要逐个验证。

## 四、Git checkout失败怎么定位

先在Runner服务账户下执行最小Git连接测试，确认：

-   Git是否读取预期代理；
-   仓库和子模块域名是否均获准访问；
-   证书链和企业TLS检查是否匹配；
-   凭据权限与代理认证是否混淆；
-   Git LFS是否使用额外端点。

Git代理作用域见[Git配置后浏览器不变的原因](https://www.jiyueip.com/article/7143)。

## 五、uses步骤下载失败是什么层

GitHub Actions需要获取Action元数据和代码。Runner服务能保持在线，不代表所有下载域名和对象存储路径可达。查看Runner诊断日志中的目标类别和错误阶段，但提交工单前脱敏仓库、令牌和内部主机名。

## 六、容器作业为什么又失败

`container:` 或服务容器依赖Docker。Runner进程的HTTP\_PROXY不会自动配置Docker守护进程拉镜像；容器内部的包管理器也需要自己的代理环境。

三层差异见[Docker Compose代理构建与运行指南](https://www.jiyueip.com/article/7951)。

## 七、秘密如何安全传递

-   代理密码进入GitHub Secrets或企业密钥系统；
-   不要在workflow YAML中写明文；
-   不要echo代理URL或运行会展开变量的调试命令；
-   限制Secret只用于需要的仓库、环境和Runner组；
-   轮换后检查Runner工作目录和缓存；
-   避免让不受信的拉取请求接触高权限秘密。

GitHub会掩码已登记的秘密，但不能依赖掩码修复所有变形、编码或拼接后的泄露。

## 八、第三方Action的供应链风险

代理打通网络后，第三方Action也获得了网络访问能力。应固定到经过审查的版本或提交、限制权限、使用最小 `GITHUB_TOKEN` 权限，并评估Action是否需要秘密。

## 九、分层验证清单

1.  Runner服务稳定在线并能接收任务；
2.  checkout一个低风险测试仓库；
3.  验证子模块和LFS（若业务使用）；
4.  运行不含秘密的网络诊断作业；
5.  验证包管理器和证书；
6.  验证Docker拉镜像与容器内访问；
7.  检查内部服务是否按NO\_PROXY直连。

## 十、常见错误

| 现象  | 优先检查 |
| --- | --- |
| Runner离线 | 服务环境、代理认证和GitHub连接 |
| checkout 407 | 代理凭据与服务账户环境 |
| 证书不受信 | Runner/Git/Node各自信任库 |
| Docker pull超时 | Docker守护进程代理 |
| 内部制品库502 | NO\_PROXY和内部DNS |

## 十一、变更与回滚

代理变更先在专用测试Runner组灰度，不直接修改所有生产Runner。保存服务配置、workflow基线和成功作业ID；失败时恢复旧环境、重启服务并验证。

## 十二、日志该保存什么

记录Runner ID、作业ID、配置版本、失败阶段、状态码和代理节点ID，不记录GitHub令牌、代理密码、完整仓库URL参数或用户数据。

自托管Runner代理的目标是让获准的构建步骤有明确出口，同时保持内部依赖、秘密和供应链权限可控。

**Tags:** 云服务器, 代理IP, 企业网络合规, 服务器运维

**Categories:** 行业洞察

---