在Github Action中使用WireGuard建隧道时卡住的问题排查

核心原因：AllowedIPs全路由设置与Github Action环境冲突 #

你的AllowedIPs配置0.0.0.0/1, 128.0.0.0/1, ::/1, 8000::/1本质是把所有IPv4和IPv6流量都强制走WireGuard隧道，但Github Action的Runner本身依赖原生网络访问外部资源（比如Github API、软件源、你的WG服务器公网Endpoint）。当wg-quick up修改路由表后，Runner的原生网络连接被切断：

• 即使WG隧道能建立，后续的DNS解析、命令执行依赖的网络请求会全部被导向隧道，而此时隧道可能还未完全就绪，或者Runner环境不允许这种全流量劫持，导致进程卡住无法完成初始化。

Action本身可能存在的辅助问题 #

部分WireGuard Action可能未适配Github Action的环境限制：

• 未正确申请NET_ADMIN权限：WireGuard修改网络接口、路由表需要该权限，若Action未配置（比如在容器环境下未添加cap_add: NET_ADMIN），会导致wg-quick执行失败或卡住。
• 缺少前置依赖：部分Runner环境可能未预装WireGuard工具包，Action若未自动安装依赖，也会导致执行异常。

解决步骤 #

1. 缩小AllowedIPs范围
   只将需要通过隧道访问的目标网段加入AllowedIPs，而非全流量路由。比如你只需要访问WG服务器所在的10.2.53.0/24和fc10:253::/64网段，修改配置：

   [Peer]
   ...
   AllowedIPs = 10.2.53.0/24, fc10:253::/64
   ...
   

   这样默认流量仍走Runner原生网络，不会导致断网。

2. 验证Action权限配置
   在Github Action的Job中明确授予NET_ADMIN权限，比如使用容器运行时：

   jobs:
     test-wireguard:
       runs-on: ubuntu-latest
       container:
         image: ubuntu:latest
         options: --cap-add=NET_ADMIN
       steps:
         - name: Setup WireGuard
           uses: easy-wireguard-action@v1
           ...
   

   若使用非容器环境，确保Action脚本中使用sudo执行wg-quick，并确认Runner允许sudo操作。

3. 添加调试日志定位问题
   在wg-quick up命令前添加调试步骤，或使用verbose模式执行：

   # 查看当前路由表
   ip route
   # 测试WG服务器连通性
   ping -c 3 <你的WG服务器公网IP>
   # verbose模式启动WireGuard，输出详细日志
   sudo wg-quick -vv up ./wg0.conf
   

   从日志中可以明确是路由修改失败、DNS配置错误还是Peer连接超时，进一步定位问题。

内容的提问来源于stack exchange，提问作者Marco Fedele