Ubuntu Node.js项目如何进行持续集成与部署

Ubuntu Node.js项目持续集成与部署（CI/CD）实践指南

在CI/CD这条路上摸爬滚打过的朋友都知道，环境搭对了，后面能省下大把修bug的时间。今天这篇东西，就把Ubuntu上Node.js项目从零到部署的整套流水线拆开揉碎了讲清楚。先别急着动手，看完再干，事半功倍。

一、前期环境准备

配置CI/CD之前，有几项基础工作必须到位——不然跑到一半卡壳，排查起来够你喝一壶的。

1. Ubuntu服务器配置：推荐Ubuntu 20.04及以上版本。22端口（SSH）和项目需要的端口（比如3000、80等）都得先放通。接着安装Node.js、npm以及PM2（进程管理神器）：

   # 安装Node.js 16.x（或指定版本）
   curl -sL https://deb.nodesource.com/setup_16.x | sudo -E bash -
   sudo apt install -y nodejs
   
   # 全局安装PM2
   sudo npm install -g pm2
   
   # 配置PM2开机自启
   pm2 startup systemd
   sudo systemctl enable pm2
   

2. GitHub仓库准备：把Node.js项目推到GitHub仓库，确保根部有package.json，最好也带上ecosystem.config.js（PM2配置文件，非必需但推荐）。

二、基于GitHub Actions的CI/CD配置（推荐）

对Node.js项目来说，GitHub Actions是最省事的CI/CD方案——不用自建服务器，直接在GitHub生态里搞定。下面按步骤走。

1. 配置GitHub Secrets

去仓库的 Settings → Secrets → Actions 添加以下敏感信息（SSH部署时用）：

• SERVER_IP：Ubuntu服务器的公网IP
• SSH_PRIVATE_KEY：服务器SSH私钥（用 cat ~/.ssh/id_rsa 查看）
• DEPLOY_PATH：项目在服务器上的部署路径，比如 /var/www/node-app

2. 创建GitHub Actions工作流

在项目根目录新建 .github/workflows/deploy.yml，写入以下流程（实现“代码推送→依赖安装→构建→PM2重启”）：

name: Node.js CI/CD Pipeline
on:
  push:
    branches: [ main ]   # 监听main分支的push事件
  pull_request:
    branches: [ main ]   # 可选：监听pull request

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      # 1. 检出代码
      - name: Checkout code
        uses: actions/checkout@v3

      # 2. 设置Node.js环境
      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16

      # 3. 安装依赖（--prefer-offline加速）
      - name: Install dependencies
        run: npm ci --prefer-offline

      # 4. 运行测试（如果有测试脚本）
      - name: Run tests
        run: npm test

      # 5. 构建项目（根据项目调整，如Vue/React的build）
      - name: Build project
        run: npm run build

      # 6. SSH部署到服务器
      - 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 delete all || true
            pm2 start app.js --name "node-app"
            pm2 sa ve

3. 关键说明

• 缓存优化：加上 actions/cache 缓存 node_modules，能明显缩短安装时间。参考配置：

  - uses: actions/cache@v3
    with:
      path: |
        **/node_modules
        ${{ github.workspace }}/.npm
      key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
  

• 多环境部署：通过 if 条件判断分支，实现“main分支→生产，dev分支→预发布”。例如：

  jobs:
    deploy:
      if: github.ref == 'refs/heads/main'
      runs-on: ubuntu-latest
      environment: production
      steps: [...]
  

4. 验证部署

• 推送代码到 main 分支，在GitHub Actions页面观察工作流状态，等“Build and Deploy”步骤跑完。
• 登录服务器，检查PM2进程：pm2 list 看是否运行，pm2 logs 看实时日志排障。

三、基于Jenkins的CI/CD配置（备选）

如果项目需要更灵活的流水线控制（比如Docker构建、多环境动态切换），可以用Jenkins。以下是一套能跑通的配置。

1. 安装Jenkins

在Ubuntu服务器上执行：

sudo apt install -y openjdk-11-jdk
wget -q -O - https://pkg.jenkins.io/debian-stable/jenkins.io.key | sudo tee /usr/share/keyrings/jenkins-keyring.asc > /dev/null
echo "deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] https://pkg.jenkins.io/debian-stable binary/" | sudo tee /etc/apt/sources.list.d/jenkins.list > /dev/null
sudo apt update
sudo apt install -y jenkins
sudo systemctl start jenkins
sudo systemctl enable jenkins

然后访问 http://<服务器IP>:8080，按提示完成初始化（需要输入管理员密码）。

2. 配置Jenkins全局工具

• 进入 Manage Jenkins → Global Tool Configuration，配置：
  • Node.js：点击“新增Node.js”，填名称（如 nodejs-16），选版本（16.x）。
  • Git：填Git安装路径（通常是 /usr/bin/git，用 which git 确认）。

3. 创建Jenkins Pipeline

• 点 New Item → 选“Pipeline” → 填名称（如 node-app-ci-cd）→ 确定。
• 在 Pipeline 选项卡中，选“Pipeline script from SCM”：
  • SCM：选 Git，填仓库URL。
  • Branch Specifier：填 */main。
  • Script Path：填 Jenkinsfile。
• 点击“保存”。

4. 编写Jenkinsfile

在项目根目录创建 Jenkinsfile：

pipeline {
    agent any
    tools {
        nodejs 'nodejs-16'
    }
    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }
        stage('Install Dependencies') {
            steps {
                sh 'npm ci --prefer-offline'
            }
        }
        stage('Build') {
            steps {
                sh 'npm run build'
            }
        }
        stage('Deploy') {
            steps {
                sshagent(['jenkins-ssh-key']) {
                    sh '''
ssh root@${SERVER_IP} << 'EOF'
cd ${DEPLOY_PATH}
git pull origin main
npm install --production
pm2 delete all || true
pm2 start app.js --name "node-app"
pm2 sa ve
EOF
'''
                }
            }
        }
    }
    post {
        always {
            echo 'Deployment completed!'
        }
        failure {
            echo 'Deployment failed!'
        }
    }
}

注意：需要在Jenkins的 Manage Jenkins → Credentials 里添加SSH密钥（ID设为 jenkins-ssh-key），并且将 ${SERVER_IP}、${DEPLOY_PATH} 替换为实际值。

5. 触发构建

• 手动触发：进项目页面，点“Build Now”。
• 自动触发：在Jenkinsfile里加 triggers 块，或配置GitHub Webhook（网上有现成教程）。

四、常见问题排查

1. SSH连接失败：检查服务器SSH端口是否开放（sudo ufw allow 22/tcp），GitHub Secrets里的私钥不能有多余换行符。
2. PM2进程未启动：跑 pm2 logs 看错误，用 sudo netstat -tulnp | grep :3000 检查端口是否被占用。
3. 依赖安装失败：核对 package.json 中的版本兼容性，或者 npm cache clean --force 清一下缓存重试。

以上一套组合拳打下来，Ubuntu上的Node.js项目就能实现自动化持续集成与部署。开发效率和线上稳定性，都会有质的提升。