GitHub Actions 中 Agent Reach 配置指南：新手避坑与实战

共计 2099 个字符，预计需要花费 6 分钟才能阅读完成。

背景痛点

在企业或个人项目中，使用 GitHub Actions 的自托管 runner（agent）时，经常会遇到连接失败的问题。这主要是由于以下几个原因：

• 企业防火墙限制 ：许多企业网络会限制对外部服务的访问，尤其是对 GitHub 的 API 和 runner 通信端口。
• DNS 解析问题 ：某些网络环境可能无法正确解析 api.github.com 或其他 GitHub 服务的域名。
• 代理配置缺失 ：在需要代理的环境中，如果没有正确配置代理，runner 将无法连接到 GitHub 服务器。

这些问题会导致 runner 无法正常注册或执行工作流，尤其是对于新手来说，调试起来非常困难。

技术对比：GitHub-hosted runner vs 自托管 runner

GitHub-hosted runner 和自托管 runner 在网络架构上有显著差异：

• GitHub-hosted runner：由 GitHub 官方托管，运行在 GitHub 的云环境中，天生具备与 GitHub 服务的良好连接性，无需额外配置。
• 自托管 runner：运行在用户自己的服务器或本地机器上，网络环境复杂，可能受到防火墙、代理或 DNS 限制的影响。

因此，自托管 runner 需要额外的网络配置才能确保其与 GitHub 服务的正常通信。

核心方案：测试 agent 可达性

在配置自托管 runner 之前，建议先测试其网络可达性。以下是具体步骤：

1. 使用 telnet 测试端口连通性 ：

telnet api.github.com 443

如果连接成功，说明 443 端口是开放的；如果失败，可能是防火墙或代理问题。

1. 使用 curl 测试 API 访问 ：

curl -v https://api.github.com

通过 -v 参数可以查看详细的请求和响应信息，帮助诊断问题。

1. 检查 DNS 解析 ：

nslookup api.github.com

确保域名能够正确解析为 GitHub 的 IP 地址。

代码示例：测试可达性的工作流文件

以下是一个示例的 .github/workflows/test-reachability.yml 文件，用于验证 runner 的网络连接性：

name: Test Runner Reachability

on: [push]

jobs:
  test-reachability:
    runs-on: self-hosted
    steps:
      - name: Check GitHub API connectivity
        run: |
          curl -v https://api.github.com
          echo "API connectivity test completed."
      - name: Check proxy settings (if applicable)
        env:
          HTTP_PROXY: ${{secrets.HTTP_PROXY}}
          HTTPS_PROXY: ${{secrets.HTTPS_PROXY}}
          NO_PROXY: ${{secrets.NO_PROXY}}
        run: |
          echo "Proxy settings:"
          echo "HTTP_PROXY: $HTTP_PROXY"
          echo "HTTPS_PROXY: $HTTPS_PROXY"
          echo "NO_PROXY: $NO_PROXY"

关键参数说明：

• runs-on: self-hosted：指定工作流在自托管 runner 上运行。
• env：配置代理环境变量，通过 GitHub Secrets 安全存储敏感信息。
• curl -v https://api.github.com：测试与 GitHub API 的连接。

避坑指南：常见封锁端口及替代方案

企业网络中常见的封锁端口及其解决方案：

1. 443 端口封锁 ：
2. 问题：GitHub Actions 默认使用 443 端口（HTTPS）通信，如果被封锁，runner 无法连接。

3. 解决方案：配置代理服务器，通过 HTTP_PROXY 或 HTTPS_PROXY 环境变量绕过封锁。

4. 22 端口封锁（SSH）：

5. 问题：某些网络可能封锁 SSH 端口，影响 runner 的注册和通信。

6. 解决方案：使用 HTTPS 协议代替 SSH，或在代理后运行 runner。

7. DNS 污染或拦截 ：

8. 问题：无法解析 api.github.com 或其他 GitHub 域名。
9. 解决方案：手动配置 hosts 文件，或使用公共 DNS 服务（如 8.8.8.8）。

验证方法：通过 workflow 日志分析连接问题

在 GitHub Actions 的工作流运行完成后，可以通过日志分析连接问题：

1. 查看 curl -v 的输出 ：日志中会显示详细的 HTTP 请求和响应信息，包括是否成功连接、代理是否生效等。
2. 检查代理配置 ：如果配置了代理，确保日志中显示的代理地址和端口正确。
3. 排查 DNS 问题 ：如果 curl 命令返回域名解析失败，说明 DNS 配置有问题。

总结

配置自托管 runner 的网络连接性可能会遇到各种问题，但通过系统的测试和合理的代理配置，大多数问题都可以解决。本文提供的步骤和示例工作流可以帮助新手快速诊断和解决连接性问题。

如果你的网络环境特别严格，建议与企业 IT 部门合作，确保必要的端口和域名是可访问的。此外，定期测试 runner 的连接性，可以避免因网络变动导致的工作流失败。

希望这篇指南能帮助你顺利配置自托管 runner，享受 GitHub Actions 的强大功能！