GitHub主分支PR合并后自动更新树莓派服务器代码方案咨询

优先推荐直接用GitHub Actions原生SSH能力替代第三方封装的SSH action，兼容性最好，能避开绝大多数第三方工具的适配问题，具体配置步骤如下：

• 在树莓派上生成专属部署用的ed25519格式SSH密钥对，执行命令ssh-keygen -t ed25519 -C "github-deploy" -f ~/.ssh/github_deploy_key，生成过程无需设置密码。
• 将公钥文件~/.ssh/github_deploy_key.pub的内容追加到树莓派部署用户的~/.ssh/authorized_keys文件中，同时修正权限配置：chmod 700 ~/.ssh && chmod 600 ~/.ssh/*，权限不符合要求时SSH服务会直接拒绝密钥登录，是最常见的连接失败原因。
• 进入GitHub对应仓库的设置页，找到Actions密钥配置项，新增3个仓库密钥：SSH_PRIVATE_KEY填入刚生成的私钥文件完整内容，SSH_HOST填入树莓派可被GitHub访问的公网地址，SSH_USER填入登录树莓派部署应用的用户名。
• 在仓库中新建.github/workflows/auto_deploy.yml工作流文件，触发条件设置为main分支的push事件（PR合入本质就是向main分支推送合并提交），直接调用系统原生SSH客户端执行远程部署命令，参考配置如下：

name: 自动部署到树莓派
on:
  push:
    branches: [ "main" ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 安装SSH客户端
        run: sudo apt update && sudo apt install -y openssh-client
      - name: 配置SSH连接参数
        run: |
          mkdir -p ~/.ssh
          echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/id_ed25519
          chmod 600 ~/.ssh/id_ed25519
          ssh-keyscan ${{ secrets.SSH_HOST }} >> ~/.ssh/known_hosts
      - name: 远程执行部署命令
        run: |
          ssh ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }} << 'EOF'
            cd /your/app/absolute/path
            git pull origin main
            # 替换为实际的应用重启命令，比如docker compose up -d --build、pm2 restart app等
            bash ./restart.sh
          EOF

注意：所有需要GitHub主动发起连接的方案，都要求树莓派有可被公网访问的地址，且对应端口的防火墙、端口映射配置正确，否则必然连接失败。

方案一：本地Webhook监听触发 #

如果不想暴露SSH端口到公网，或者树莓派在家庭内网没有固定公网IP，可以反过来让树莓派主动接收GitHub的事件通知，完全避开SSH连接问题：

• 树莓派上直接通过apt安装轻量Webhook服务：sudo apt install webhook
• 编写Webhook触发规则，配置自定义校验密钥，规则匹配后执行本地部署脚本，脚本核心逻辑为切换到应用目录、拉取最新main分支代码、安装依赖、重启服务。
• 给Webhook服务单独分配一个不常用的端口，配置防火墙仅允许GitHub官方IP段访问该端口；如果树莓派没有公网IP，可以搭配内网穿透工具将该端口暴露到公网。
• 进入GitHub仓库设置的Webhook配置页，新增Webhook，填写Webhook服务的公网访问地址，选择json格式传输，填入之前设置的校验密钥，触发事件选择main分支的push事件即可。
  该方案不需要开放SSH公网登录权限，安全性更高，也不会出现SSH密钥、指纹校验这类常见连接问题。

方案二：本地定时轮询仓库 #

如果不想折腾公网穿透、端口映射，这个方案成本最低，只要树莓派能正常访问GitHub就能用，唯一缺点是同步存在分钟级延迟，对个人应用完全够用：

• 给树莓派上的应用目录配置好Git远程地址，生成一个仅拥有仓库只读权限的部署密钥，添加到GitHub仓库的Deploy Keys中。
• 编写轮询部署脚本：

#!/bin/bash
cd /your/app/absolute/path
git fetch origin main
LOCAL_COMMIT=$(git rev-parse HEAD)
REMOTE_COMMIT=$(git rev-parse origin/main)
if [ "$LOCAL_COMMIT" != "$REMOTE_COMMIT" ]; then
  git pull origin main
  # 替换为实际的应用重启命令
  bash ./restart.sh
fi

• 给脚本加执行权限chmod +x /path/to/poll_deploy.sh，然后将脚本加入crontab定时任务，比如配置为每分钟执行一次：* * * * * /path/to/poll_deploy.sh >> /var/log/app_deploy.log 2>&1

之前第三方SSH action连接失败的常见排查点 #

如果还想继续尝试之前使用的SSH action，可以逐一核对以下配置，90%以上的连接问题都是这些原因导致的：

• 密钥格式不兼容：优先用ed25519格式密钥，避免用旧的rsa格式密钥在新系统上被拒绝；复制私钥时要完整包含首尾的标识行和所有换行，不能缺漏内容。
• 缺少主机指纹校验：非交互模式下SSH首次连接会因为主机指纹确认提示直接中断，必须提前将树莓派的主机指纹加入可信列表。
• 端口配置错误：如果树莓派SSH服务没有使用默认22端口，必须在action参数里显式指定端口，同时核对路由器端口映射、防火墙规则是否放通对应端口。
• 文件权限错误：树莓派上.ssh目录权限必须为700，目录下的密钥、授权文件权限必须为600，否则SSH服务会直接拒绝密钥登录请求。

内容的提问来源于stack exchange，提问作者Pi-R