GitHub Actions自动部署到VPS

---

GitHub Actions是GitHub提供的CI/CD服务，可以在代码推送时自动执行构建、测试和部署。配合搬瓦工VPS，可以实现代码推送到GitHub后自动部署到服务器，省去手动SSH登录和执行部署命令的步骤。本文介绍完整的自动部署配置流程。

前提准备

• 项目代码已托管在GitHub仓库
• 搬瓦工VPS已配置好运行环境（Nginx、Node.js/Python等）
• VPS允许SSH密钥登录

第一步：生成SSH密钥对

在本地生成专用于部署的SSH密钥对：

# 生成ED25519密钥对（推荐）
ssh-keygen -t ed25519 -C "github-actions-deploy" -f ~/.ssh/deploy_key

# 将公钥添加到VPS的authorized_keys
ssh-copy-id -i ~/.ssh/deploy_key.pub root@your-vps-ip

# 或手动复制
cat ~/.ssh/deploy_key.pub | ssh root@your-vps-ip "cat >> ~/.ssh/authorized_keys"

# 测试SSH登录
ssh -i ~/.ssh/deploy_key root@your-vps-ip

第二步：配置GitHub Secrets

在GitHub仓库中存储敏感信息（密钥、服务器地址等），打开仓库页面，进入 Settings - Secrets and variables - Actions，添加以下Secrets：

• VPS_HOST - VPS的IP地址或域名
• VPS_USER - SSH用户名（通常是root或deploy用户）
• VPS_SSH_KEY - SSH私钥内容（deploy_key文件的全部内容）
• VPS_PORT - SSH端口（搬瓦工默认随机端口）

# 查看私钥内容（复制到GitHub Secrets）
cat ~/.ssh/deploy_key

Tip： 搬瓦工VPS的SSH端口不是默认的22，在KiwiVM面板中查看实际端口号。

第三步：创建Workflow文件

在项目根目录创建 .github/workflows/deploy.yml：

Node.js应用部署示例：

name: Deploy to VPS

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '20'
        cache: 'npm'

    - name: Install dependencies
      run: npm ci

    - name: Run tests
      run: npm test

    - name: Build
      run: npm run build

    - name: Deploy to VPS
      uses: appleboy/ssh-action@v1
      with:
        host: ${{ secrets.VPS_HOST }}
        username: ${{ secrets.VPS_USER }}
        key: ${{ secrets.VPS_SSH_KEY }}
        port: ${{ secrets.VPS_PORT }}
        script: |
          cd /var/www/myapp
          git pull origin main
          npm ci --production
          npm run build
          pm2 reload myapp

Python应用部署示例：

name: Deploy Python App

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Deploy via SSH
      uses: appleboy/ssh-action@v1
      with:
        host: ${{ secrets.VPS_HOST }}
        username: ${{ secrets.VPS_USER }}
        key: ${{ secrets.VPS_SSH_KEY }}
        port: ${{ secrets.VPS_PORT }}
        script: |
          cd /var/www/flask-app
          git pull origin main
          source venv/bin/activate
          pip install -r requirements.txt
          sudo systemctl restart flask-app

使用Rsync同步文件

对于需要上传构建产物（而非在VPS上git pull）的场景：

name: Deploy with Rsync

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '20'

    - name: Build
      run: |
        npm ci
        npm run build

    - name: Deploy via Rsync
      uses: burnett01/rsync-deployments@6
      with:
        switches: -avz --delete --exclude='node_modules' --exclude='.env'
        path: ./
        remote_path: /var/www/myapp/
        remote_host: ${{ secrets.VPS_HOST }}
        remote_user: ${{ secrets.VPS_USER }}
        remote_key: ${{ secrets.VPS_SSH_KEY }}
        remote_port: ${{ secrets.VPS_PORT }}

    - name: Restart application
      uses: appleboy/ssh-action@v1
      with:
        host: ${{ secrets.VPS_HOST }}
        username: ${{ secrets.VPS_USER }}
        key: ${{ secrets.VPS_SSH_KEY }}
        port: ${{ secrets.VPS_PORT }}
        script: |
          cd /var/www/myapp
          npm ci --production
          pm2 reload myapp

Docker部署方式

name: Docker Deploy

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - name: Build and deploy
      uses: appleboy/ssh-action@v1
      with:
        host: ${{ secrets.VPS_HOST }}
        username: ${{ secrets.VPS_USER }}
        key: ${{ secrets.VPS_SSH_KEY }}
        port: ${{ secrets.VPS_PORT }}
        script: |
          cd /var/www/myapp
          git pull origin main
          docker compose down
          docker compose up -d --build
          docker compose ps

部署通知

部署完成后发送通知（以Telegram为例）：

    - name: Notify on success
      if: success()
      run: |
        curl -s -X POST "https://api.telegram.org/bot${{ secrets.TG_BOT_TOKEN }}/sendMessage" \
          -d "chat_id=${{ secrets.TG_CHAT_ID }}" \
          -d "text=Deploy succeeded: ${{ github.repository }} @ ${{ github.sha }}"

    - name: Notify on failure
      if: failure()
      run: |
        curl -s -X POST "https://api.telegram.org/bot${{ secrets.TG_BOT_TOKEN }}/sendMessage" \
          -d "chat_id=${{ secrets.TG_CHAT_ID }}" \
          -d "text=Deploy FAILED: ${{ github.repository }} @ ${{ github.sha }}"

安全建议

• 最小权限原则：创建专用deploy用户，只授予部署所需的权限，避免使用root
• 限制SSH来源：在VPS防火墙中限制SSH登录的IP范围（GitHub Actions的IP段可在官方文档查看）
• 密钥轮换：定期更换部署密钥
• 保护main分支：在GitHub设置分支保护规则，要求PR审核后才能合并到main
• 环境分离：使用GitHub Environments功能分离staging和production，production部署需要审批

常见问题

• SSH连接超时：检查VPS_PORT是否正确，搬瓦工SSH端口不是22
• Permission denied：确认公钥已正确添加到VPS的authorized_keys，私钥已完整复制到Secrets
• Host key verification failed：ssh-action会自动处理，如使用原生ssh命令需添加 StrictHostKeyChecking=no
• 部署脚本执行失败：检查VPS上的路径和环境变量是否正确，ssh-action默认使用非登录Shell

Tip： 更多教程请查看新手教程。