自托管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方法。
三、NO_PROXY不要漏掉内部依赖
自托管Runner可能访问内部Git、制品库、缓存、容器仓库和企业API。若它们错误经过外部代理，会造成DNS、TLS或权限问题。NO_PROXY应按实际依赖列出，不复制其他服务器模板。
不同工具对后缀、CIDR和大小写变量的支持不同，要逐个验证。
四、Git checkout失败怎么定位
先在Runner服务账户下执行最小Git连接测试，确认：
- Git是否读取预期代理；
- 仓库和子模块域名是否均获准访问；
- 证书链和企业TLS检查是否匹配；
- 凭据权限与代理认证是否混淆；
- Git LFS是否使用额外端点。
Git代理作用域见Git配置后浏览器不变的原因。
五、uses步骤下载失败是什么层
GitHub Actions需要获取Action元数据和代码。Runner服务能保持在线，不代表所有下载域名和对象存储路径可达。查看Runner诊断日志中的目标类别和错误阶段，但提交工单前脱敏仓库、令牌和内部主机名。
六、容器作业为什么又失败
container: 或服务容器依赖Docker。Runner进程的HTTP_PROXY不会自动配置Docker守护进程拉镜像；容器内部的包管理器也需要自己的代理环境。
三层差异见Docker Compose代理构建与运行指南。
七、秘密如何安全传递
- 代理密码进入GitHub Secrets或企业密钥系统；
- 不要在workflow YAML中写明文；
- 不要echo代理URL或运行会展开变量的调试命令；
- 限制Secret只用于需要的仓库、环境和Runner组；
- 轮换后检查Runner工作目录和缓存；
- 避免让不受信的拉取请求接触高权限秘密。
GitHub会掩码已登记的秘密，但不能依赖掩码修复所有变形、编码或拼接后的泄露。
八、第三方Action的供应链风险
代理打通网络后，第三方Action也获得了网络访问能力。应固定到经过审查的版本或提交、限制权限、使用最小 GITHUB_TOKEN 权限，并评估Action是否需要秘密。
九、分层验证清单
- Runner服务稳定在线并能接收任务；
- checkout一个低风险测试仓库；
- 验证子模块和LFS（若业务使用）；
- 运行不含秘密的网络诊断作业；
- 验证包管理器和证书；
- 验证Docker拉镜像与容器内访问；
- 检查内部服务是否按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代理的目标是让获准的构建步骤有明确出口，同时保持内部依赖、秘密和供应链权限可控。
