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

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

一、前期环境准备

在开始配置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配置（推荐）

GitHub Actions是Node.js项目最常用的CI/CD工具之一，无需自建服务器，直接集成在GitHub中。以下是详细步骤：

1. 配置GitHub Secrets

在GitHub仓库的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文件，定义CI/CD流程（以下示例实现“代码推送→依赖安装→构建→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  # 使用GitHub提供的Ubuntu runner
    
    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  # 匹配项目要求的Node.js版本
    
    # 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  # 使用GitHub Marketplace的SSH Action
      with:
        host: ${{ secrets.SERVER_IP }}
        username: root  # 服务器用户名（如ubuntu、root）
        key: ${{ secrets.SSH_PRIVATE_KEY }}
        script: |
          # 进入部署目录
          cd ${{ secrets.DEPLOY_PATH }}
          # 拉取最新代码（若使用Git部署）
          git pull origin main
          # 安装生产依赖（避免安装devDependencies）
          npm install --production
          # 重启PM2进程（先删除旧进程，再启动新进程）
          pm2 delete all || true  # 忽略“进程不存在”的错误
          pm2 start app.js --name "node-app"  # 替换为你的入口文件（如app.js、index.js）
          pm2 save  # 保存当前进程列表

3. 关键说明

• 缓存优化：通过actions/cache Action缓存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'  # 仅main分支触发生产部署
      runs-on: ubuntu-latest
      environment: production  # 关联GitHub Environment（需提前创建）
      steps: [...]
  

4. 验证部署

• 推送代码到main分支，观察GitHub Actions工作流运行状态（需等待“Build and Deploy”步骤完成）。
• 登录服务器，检查PM2进程状态：

  pm2 list  # 查看进程是否运行
  pm2 logs  # 查看实时日志（排查部署问题）
  

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

若需更灵活的流水线控制（如Docker构建、多环境切换），可使用Jenkins。以下是简要步骤：

1. 安装Jenkins

在Ubuntu服务器上执行以下命令安装Jenkins：

# 安装Java（Jenkins依赖）
sudo apt install -y openjdk-11-jdk
# 添加Jenkins仓库并安装
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
# 启动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），点击“OK”。
• 在Pipeline选项卡中，选择“Pipeline script from SCM”，配置以下信息：
  • SCM：选择Git，填写仓库URL（如https://github.com/your-repo/node-app.git）。
  • Branch Specifier：填写*/main（监听main分支）。
  • Script Path：填写Jenkinsfile（项目根目录下的流水线脚本文件）。
• 点击“保存”。

4. 编写Jenkinsfile

在项目根目录创建Jenkinsfile，定义流水线步骤（以下示例实现“拉取代码→安装依赖→构建→SSH部署”）：

pipeline {
    agent any
    
    tools {
        nodejs 'nodejs-16'  // 使用全局配置的Node.js工具
    }
    
    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']) {  // 使用Jenkins存储的SSH密钥
                    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 save
                        EOF
                    '''
                }
            }
        }
    }
    
    post {
        always {
            echo 'Deployment completed!'
        }
        failure {
            echo 'Deployment failed!'
        }
    }
}

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

5. 触发构建

• 手动触发：进入Jenkins项目页面，点击“Build Now”。
• 自动触发：在Jenkinsfile中添加triggers块，或配置GitHub Webhook（参考）。

四、常见问题排查

1. SSH连接失败：检查服务器SSH端口是否开放（sudo ufw allow 22/tcp），GitHub Secrets中的私钥是否正确（无换行符）。
2. PM2进程未启动：查看PM2日志（pm2 logs），确认应用端口是否被占用（sudo netstat -tulnp | grep :3000）。
3. 依赖安装失败：检查package.json中的依赖版本是否兼容，或尝试npm cache clean --force清理缓存。

通过以上步骤，即可实现Ubuntu Node.js项目的持续集成与部署，提升开发效率和应用稳定性。