GitHub Actions无法连接树莓派问题求助

核心原因分析 #

1. GitHub托管Runner的网络隔离问题 #

如果你的Actions用的是GitHub官方托管的Runner，它本质运行在GitHub云服务器上，和树莓派所在局域网完全隔离：

• 局域网IP仅在你的内网有效，云服务器无法访问，因此用IP连接会超时。
• raspberrypi.local依赖局域网mDNS（多播DNS）服务解析，云服务器未接入你的内网mDNS网络，必然解析失败。

2. 自托管Runner的配置缺失 #

如果是你部署在局域网内的Runner，问题通常出在以下几点：

• Runner所在系统未安装mDNS解析工具，无法识别.local域名。
• Runner和树莓派不在同一网段，或路由器/防火墙阻断了通信。
• SSH连接的验证方式（如密码登录）被树莓派禁用，或权限配置错误。

针对性解决办法 #

针对GitHub托管Runner的解决方案 #

放弃直接连接局域网树莓派，二选一：

• 方案一：把树莓派暴露到公网
  1. 在路由器上给树莓派设置端口转发（将公网端口映射到树莓派22端口）。
  2. 配置动态域名（如No-IP、花生壳），避免公网IP变动。
  3. 树莓派开启防火墙，仅允许指定IP（GitHub Actions的IP段）访问22端口，或改用SSH密钥登录。
• 方案二：部署自托管Runner到局域网
  在你的局域网内找一台机器（甚至可以是树莓派本身）部署GitHub Actions自托管Runner，确保它和目标树莓派处于同一内网环境。

针对自托管Runner的解决方案 #

1. 先验证网络连通性
   登录到Runner所在机器，执行：

   ping 树莓派的局域网IP
   

   如果ping不通，检查路由器网段设置、两台设备的防火墙规则，确保树莓派22端口对外开放。

2. 安装mDNS解析工具

   • Linux系统Runner：

     sudo apt update && sudo apt install avahi-daemon libnss-mdns
     sudo systemctl restart avahi-daemon
     

   • Windows系统Runner：
     安装苹果官方的Bonjour Print Services（自带mDNS解析功能）。

3. 改用静态IP+SSH密钥登录

   • 给树莓派设置静态局域网IP，避免IP变动导致连接失败。
   • 生成Runner的SSH密钥对：

     ssh-keygen -t ed25519 -N "" -f ~/.ssh/raspi_key
     

   • 将公钥~/.ssh/raspi_key.pub的内容添加到树莓派的/home/pi/.ssh/authorized_keys文件中。
   • 修改Actions中的命令：

     Run ssh -i ~/.ssh/raspi_key pi@树莓派静态IP "cd Desktop; git pull; python3 main.py"
     

4. 开启SSH调试排查细节
   在命令中加入-v参数，查看连接过程的详细日志：

   ssh -v pi@raspberrypi.local "cd Desktop; git pull; python3 main.py"
   

   根据日志报错信息（如密钥验证失败、端口被拒）进一步定位问题。

内容的提问来源于stack exchange，提问作者Dev Br