如何配置GitHub Actions实现Node.js应用在cPanel上自动部署？

以下是针对你需求的具体实现方案，基于cPanel API和GitHub Actions完成代码推送后的自动部署：

前置准备 #

1. 生成cPanel API令牌

   • 登录cPanel后台，找到「Security」分类下的「API Tokens」
   • 点击「Create Token」，输入令牌名称，勾选以下权限：
     • Files - All（用于文件上传）
     • Passenger App Management - All（用于重启Node.js应用）
   • 生成后复制令牌内容，妥善保存（仅显示一次）

2. 配置GitHub仓库Secrets
   进入你的GitHub仓库，依次点击「Settings」→「Secrets and variables」→「Actions」→「New repository secret」，添加以下几个Secret：

   • CPANEL_HOST：你的cPanel主机地址（格式示例：yourdomain.com:2083，注意使用HTTPS端口2083）
   • CPANEL_USER：你的cPanel用户名
   • CPANEL_API_TOKEN：刚才生成的API令牌
   • APP_ROOT：cPanel中Node.js应用的根目录（可在「Setup Node.js App」页面查看，示例：/home/yourusername/public_html/your-app）
   • APP_NAME：「Setup Node.js App」中创建的应用名称（页面顶部显示的名称）

编写GitHub Actions工作流 #

在你的GitHub仓库根目录创建.github/workflows/deploy.yml文件，内容如下：

name: Auto Deploy to cPanel Node.js App
on:
  push:
    branches: [ main ] # 修改为你需要触发部署的分支名称

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # 拉取仓库代码
      - name: Checkout code
        uses: actions/checkout@v4

      # 配置Node环境（与cPanel中应用使用的版本一致）
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20' # 替换为你的应用Node.js版本
          cache: 'npm'

      # 安装项目依赖（若已将node_modules提交到仓库可跳过此步骤）
      - name: Install dependencies
        run: npm ci

      # 将代码上传到cPanel应用根目录
      - name: Upload code to cPanel
        uses: garygrossgarten/github-action-scp@v0.7.0
        with:
          local: ./
          remote: ${{ secrets.APP_ROOT }}
          host: ${{ secrets.CPANEL_HOST }}
          username: ${{ secrets.CPANEL_USER }}
          password: ${{ secrets.CPANEL_API_TOKEN }}
          port: 2022 # 若SFTP连接失败，可尝试替换为22（不同主机SFTP端口可能不同）

      # 重启Node.js应用使变更生效
      - name: Restart cPanel Node.js App
        run: |
          curl -X POST "https://${{ secrets.CPANEL_HOST }}/execute/PassengerApps/restart_app" \
          -H "Authorization: cpanel ${{ secrets.CPANEL_USER }}:${{ secrets.CPANEL_API_TOKEN }}" \
          -d "name=${{ secrets.APP_NAME }}"

关键注意事项 #

• 确保GitHub Actions中配置的Node.js版本与cPanel「Setup Node.js App」中选择的版本完全一致，避免依赖兼容性问题
• 若SCP上传失败，检查主机的SFTP端口（部分主机使用22作为默认端口），并修改workflow中的port参数
• 确认API令牌已勾选足够的权限，否则会出现文件上传或应用重启失败的情况
• 若项目无需安装依赖（如静态文件类Node应用），可直接删除「Install dependencies」步骤

内容的提问来源于stack exchange，提问作者Seif Ahmed