基于GitHub Actions+SSH+PM2的Node.js自动化部署全流程指南

基于GitHub Actions+SSH+PM2的Node.js自动化部署全流程指南

一、前期环境准备

1. 基础设施准备

• 云服务器：推荐Ubuntu 20.04+（开放22端口）
• GitHub仓库：存放Node.js项目代码（需包含package.json）
• 本地开发环境：Node.js 16+环境

2. 安装必要组件

# 在服务器执行
curl -sL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt install -y nodejs
sudo npm install pm2 -g

二、GitHub配置关键步骤

1. 配置仓库Secrets

在仓库Settings → Secrets → Actions中添加：

• SERVER_IP: 服务器公网IP
• SSH_PRIVATE_KEY: 服务器的SSH私钥（通过cat ~/.ssh/id_rsa获取）
• DEPLOY_PATH: 项目部署路径（如/var/www/express-app）

2. 生成SSH密钥对（如未生成）

ssh-keygen -t rsa -b 4096 -C "github_actions"
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys

三、创建GitHub Actions工作流

在项目.github/workflows/deploy.yml中配置

name: Node.js CI/CD Pipeline

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout code
      uses: actions/checkout@v3

    - name: Install dependencies
      uses: actions/setup-node@v3
      with:
        node-version: 16
        
    - name: SSH Deploy
      uses: appleboy/ssh-action@v0.1.10
      with:
        host: ${{ secrets.SERVER_IP }}
        username: root
        key: ${{ secrets.SSH_PRIVATE_KEY }}
        script: |
          cd ${{ secrets.DEPLOY_PATH }}
          git pull origin main
          npm install --production
          pm2 reload ecosystem.config.js --env production
          pm2 save

四、PM2配置与监控

1. 创建ecosystem配置文件

// ecosystem.config.js
module.exports = {
  apps: [{
    name: "express-app",
    script: "app.js",
    instances: "max",
    autorestart: true,
    watch: false,
    env: {
      NODE_ENV: "production",
      PORT: 3000
    }
  }]
}

2. 常用PM2监控命令

pm2 monit        # 实时监控面板
pm2 logs         # 查看实时日志
pm2 list         # 查看进程状态
pm2 save         # 保存当前进程列表

五、典型问题排查

1. 部署失败：权限不足

# 服务器执行
chmod 600 ~/.ssh/authorized_keys
chmod 700 ~/.ssh

2. PM2进程未启动

检查服务器防火墙设置：

sudo ufw allow 3000/tcp  # 开放应用端口
sudo ufw allow 22/tcp    # 确保SSH端口开放

3. GitHub Action报错"Host key verification failed"

在SSH步骤前添加：

 1. name: Add known hosts
  run: |
    mkdir -p ~/.ssh
    ssh-keyscan ${{ secrets.SERVER_IP }} >> ~/.ssh/known_hosts

六、进阶优化方向

1. 多环境部署：通过Git分支管理dev/stage/prod环境
2. Webhook通知：集成Slack/Discord发送部署结果通知
3. 回滚机制：结合PM2的日志快照功能实现快速回滚
4. 健康检查：在workflow中添加curl健康检查步骤