NestJS 项目部署流程

最新推荐文章于 2025-12-09 22:36:07 发布

原创最新推荐文章于 2025-12-09 22:36:07 发布 · 461 阅读

10 ·

CC 4.0 BY-SA版权

文章标签：

#linux

nestjs 专栏收录该内容

1 篇文章

订阅专栏

我将为您提供详细的 NestJS 项目部署到 Linux 环境的步骤，分为桌面环境和服务器环境两部分。

一、Linux Desktop 部署步骤

1. 环境准备

bash

# 1. 更新系统
sudo apt update && sudo apt upgrade -y

# 2. 安装 Node.js (推荐使用 nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# 重新打开终端或执行：
source ~/.bashrc

# 3. 安装 Node.js LTS 版本
nvm install --lts
nvm use --lts

# 4. 安装 PM2 进程管理
npm install -g pm2

# 5. 安装 Docker 和 Docker Compose (可选，如果使用容器部署)
sudo apt install docker.io docker-compose -y
sudo usermod -aG docker $USER
# 需要重新登录使权限生效

2. 项目部署

bash

# 1. 克隆或复制项目到本地
cd ~
mkdir projects
cd projects
# 将 cas-api 项目复制到此目录

# 2. 进入项目目录
cd cas-api

# 3. 安装依赖
npm install

# 4. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置数据库连接等参数
nano .env

# 5. 构建项目
npm run build

# 6. 测试运行
npm run start:prod

3. 使用 PM2 管理进程

bash

# 1. 创建 ecosystem 配置文件
pm2 init simple
# 编辑生成的 ecosystem.config.js：

module.exports = {
  apps: [{
    name: 'cas-api',
    script: 'dist/main.js',
    instances: 1,
    autorestart: true,
    watch: false,
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'production'
    }
  }]
};

# 2. 启动应用
pm2 start ecosystem.config.js

# 3. 设置开机自启
pm2 startup
# 按照提示执行生成的命令
pm2 save

# 4. 常用 PM2 命令
pm2 status              # 查看状态
pm2 logs cas-api        # 查看日志
pm2 restart cas-api     # 重启应用
pm2 stop cas-api        # 停止应用
pm2 delete cas-api      # 删除应用

二、Linux Server 部署步骤

1. 服务器环境配置

bash

# 1. 创建部署用户（安全考虑）
sudo adduser deploy
sudo usermod -aG sudo deploy
su - deploy

# 2. 安装必要软件
sudo apt update
sudo apt install -y git curl wget nginx ufw

# 3. 配置防火墙
sudo ufw allow OpenSSH
sudo ufw allow 80
sudo ufw allow 443
sudo ufw --force enable

2. Node.js 环境安装

bash

# 方法一：使用 NodeSource 安装
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# 方法二：使用 nvm（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 18
nvm alias default 18

# 验证安装
node --version
npm --version

3. 项目部署自动化脚本

创建部署脚本 deploy.sh：

bash

#!/bin/bash
set -e

echo "=== 开始部署 CAS-API ==="

# 项目配置
PROJECT_NAME="cas-api"
PROJECT_DIR="/home/deploy/$PROJECT_NAME"
GIT_REPO="your-git-repo-url"  # 替换为实际 Git 仓库地址
BRANCH="main"

# 创建项目目录
mkdir -p $PROJECT_DIR
cd $PROJECT_DIR

# 克隆或拉取代码
if [ -d ".git" ]; then
    echo "拉取最新代码..."
    git pull origin $BRANCH
else
    echo "克隆代码仓库..."
    git clone -b $BRANCH $GIT_REPO .
fi

# 安装依赖
echo "安装依赖..."
npm install

# 构建项目
echo "构建项目..."
npm run build

# 复制环境文件
if [ -f ".env.production" ]; then
    cp .env.production .env
fi

# 重启应用
if pm2 list | grep -q $PROJECT_NAME; then
    echo "重启应用..."
    pm2 restart $PROJECT_NAME
else
    echo "启动应用..."
    pm2 start dist/main.js --name $PROJECT_NAME
fi

echo "=== 部署完成 ==="

给脚本执行权限：

bash

chmod +x deploy.sh

4. Nginx 反向代理配置

bash

# 创建 Nginx 配置文件
sudo nano /etc/nginx/sites-available/cas-api

# 配置文件内容：
server {
    listen 80;
    server_name your-domain.com;  # 替换为你的域名或 IP
    
    location / {
        proxy_pass http://localhost:3000;  # 假设 NestJS 运行在 3000 端口
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    # 静态文件缓存（如果有）
    location /public/ {
        alias /home/deploy/cas-api/public/;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

# 启用站点
sudo ln -s /etc/nginx/sites-available/cas-api /etc/nginx/sites-enabled/
sudo nginx -t  # 测试配置
sudo systemctl restart nginx

5. SSL 证书配置（可选）

bash

# 使用 Certbot 获取免费 SSL 证书
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

# 自动续期测试
sudo certbot renew --dry-run

6. Docker 部署（如果使用 Docker Compose）

bash

# 1. 安装 Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# 2. 安装 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# 3. 使用 docker-compose.yml 部署
cd cas-api
# 修改 docker-compose.yml 中的环境配置
docker-compose up -d

完整的 NestJS 项目 Docker Compose 配置示例


version: '3.8' #指定 Docker Compose 文件格式版本 不同版本支持的功能不同，3.x 版本是最常用的
services:  #服务定义
  # NestJS 应用服务
  app:
    build:
      context: . # 构建上下文路径
      dockerfile: Dockerfile  # Dockerfile 文件名
      args:
        NODE_ENV: production # 多阶段构建目标（如果有）
    container_name: cas-api-app # 自定义容器名称
    hostname: cas-api-app         # 容器主机名
    restart: unless-stopped  # 重启策略：
                                # no: 不重启
                                # always: 总是重启
                                # on-failure: 失败时重启
                                # unless-stopped: 除非手动停止

    ports:
      - "3000:3000"  # 端口映射：主机端口:容器端口
      - "9229:9229"              # 调试端口（如果需要）
     expose:
        - "3000"                    # 仅暴露给其他容器，不映射到主机
    environment:    # 环境变量
      NODE_ENV: production
      PORT: 3000
      DB_HOST: postgres
      DB_PORT: 5432
      REDIS_HOST: redis
    env_file:  # 环境变量文件
      - .env # 默认文件
      - .env.production          # 优先级高于默认
    volumes:                          # 数据卷挂载
      - ./uploads:/app/uploads   # 绑定挂载：主机路径:容器路径
      - ./logs:/app/logs   # 命名卷挂载
    networks:   # 网络连接
      - cas-network
    depends_on:    # 依赖关系
      - postgres   # 先启动 postgres
      - redis   # 再启动 redis
    healthcheck:   # 健康检查
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s  # 检查间隔
      timeout: 10s # 超时时间
      retries: 3 # 重试次数
      start_period: 40s  # 容器启动后的等待时间

  # PostgreSQL 数据库服务
  postgres:
    image: postgres:15-alpine
    container_name: cas-api-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${DB_NAME:-cas_db}
      POSTGRES_USER: ${DB_USER:-cas_user}
      POSTGRES_PASSWORD: ${DB_PASSWORD:-changeme}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./db/init.sql:/docker-entrypoint-initdb.d/init.sql
    ports:
      - "5432:5432"
    networks:
      - cas-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-cas_user}"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Redis 缓存服务
  redis:
    image: redis:7-alpine
    container_name: cas-api-redis
    restart: unless-stopped
    command: redis-server --requirepass ${REDIS_PASSWORD:-redis_password}
    volumes:
      - redis_data:/data
    ports:
      - "6379:6379"
    networks:
      - cas-network
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3

  # Nginx 反向代理（可选）
  nginx:
    image: nginx:alpine
    container_name: cas-api-nginx
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d
      - ./nginx/ssl:/etc/nginx/ssl
      - ./logs/nginx:/var/log/nginx
    depends_on:
      - app
    networks:
      - cas-network

  # PGAdmin 数据库管理（仅开发环境）
  pgadmin:
    image: dpage/pgadmin4
    container_name: cas-api-pgadmin
    restart: unless-stopped
    environment:
      PGADMIN_DEFAULT_EMAIL: ${PGADMIN_EMAIL:-admin@example.com}
      PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD:-admin}
    volumes:
      - pgadmin_data:/var/lib/pgadmin
    ports:
      - "5050:80"
    networks:
      - cas-network
    profiles:
      - dev

  # Redis 管理界面（可选）
  redis-commander:
    image: rediscommander/redis-commander:latest
    container_name: cas-api-redis-commander
    restart: unless-stopped
    environment:
      REDIS_HOSTS: local:redis:6379
      REDIS_PASSWORD: ${REDIS_PASSWORD:-redis_password}
    ports:
      - "8081:8081"
    networks:
      - cas-network
    profiles:
      - dev

networks:
  cas-network:
    driver: bridge
    name: cas-network

volumes:
  postgres_data:
    name: cas-api-postgres-data
  redis_data:
    name: cas-api-redis-data
  pgadmin_data:
    name: cas-api-pgadmin-data

7. 监控和维护

bash

# 1. 查看应用日志
pm2 logs cas-api
# 或
tail -f /home/deploy/.pm2/logs/cas-api-out.log

# 2. 查看系统资源使用
htop
# 或
pm2 monit

# 3. 设置日志轮转
sudo nano /etc/logrotate.d/pm2-logs

# 添加内容：
/home/deploy/.pm2/logs/*.log {
    daily
    rotate 30
    compress
    delaycompress
    missingok
    notifempty
    create 644 deploy deploy
}

三、项目特定配置

1. 环境变量配置示例

.env.production 文件示例：

env

NODE_ENV=production
PORT=3000

# 数据库配置
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=cas_user
DB_PASSWORD=secure_password
DB_DATABASE=cas_db

# Redis 配置（如果有）
REDIS_HOST=localhost
REDIS_PORT=6379

# JWT 配置
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRES_IN=86400

# 其他配置
API_RATE_LIMIT=100
CORS_ORIGIN=https://your-domain.com

2. 数据库迁移（如果使用 TypeORM）

bash

# 在 package.json 中添加脚本
"scripts": {
  "typeorm": "ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli",
  "migration:run": "npm run typeorm migration:run -- -d src/config/data-source.ts",
  "migration:generate": "npm run typeorm migration:generate -- -d src/config/data-source.ts",
  "migration:create": "npm run typeorm migration:create"
}

# 生产环境运行迁移
npm run build
npm run migration:run

四、故障排查

常见问题解决：

端口被占用

bash

sudo lsof -i :3000
kill -9 <PID>

权限问题

bash

sudo chown -R deploy:deploy /home/deploy/cas-api

内存不足

bash

# 增加 swap 空间
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# 永久生效，添加到 /etc/fstab

查看错误日志

bash

# PM2 日志
pm2 logs cas-api --lines 100

# Nginx 日志
sudo tail -f /var/log/nginx/error.log
sudo tail -f /var/log/nginx/access.log

五、安全建议

使用非 root 用户运行
定期更新系统和软件
配置防火墙
使用 HTTPS
定期备份数据
监控系统日志
限制 SSH 访问

六、一键部署脚本

创建完整的部署脚本 setup-server.sh：

bash

#!/bin/bash
# 服务器初始化脚本

echo "开始初始化服务器..."

# 1. 系统更新
sudo apt update && sudo apt upgrade -y

# 2. 安装基础软件
sudo apt install -y git curl wget nginx ufw htop

# 3. 安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# 4. 安装 PM2
sudo npm install -g pm2

# 5. 配置防火墙
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw --force enable

echo "服务器初始化完成！"