Files
yunrui_asset/DEPLOYMENT.md
T

22 KiB
Raw Blame History

IDC设备管理系统 - 部署指南

本文档详细介绍IDC设备管理系统的多种部署方式,包括开发环境、测试环境、生产环境的配置方法。


目录


快速开始

一键部署脚本(推荐)

我们提供了交互式安装脚本,自动完成环境检测、依赖安装、数据库初始化和服务启动。

# 克隆项目(选择其一)
# Gitee(国内推荐)
git clone https://gitee.com/zhang96110/idc_assest.git
# GitHub
git clone https://github.com/gituib/idc_assest.git
cd idc_assest

# 运行部署脚本
npm run deploy
# 或
node install.js

脚本功能:

  • 自动检测 Node.js、npm、PM2、Nginx
  • Linux 系统支持自动安装 Node.js(交互式)
  • 交互式配置数据库(SQLite/MySQL
  • 交互式选择前端部署方式(Nginx/PM2 serve
  • 自动安装项目依赖
  • 自动初始化数据库
  • 自动构建前端项目
  • 使用 PM2 启动和管理服务

环境要求

基础运行环境

项目 最低要求 推荐配置
操作系统 Windows 10/11、macOS 12+、Linux (Ubuntu 20.04+/CentOS 8+) 同最低要求
Node.js ≥14.0.0 20.x LTS
npm ≥6.0.0 10.x
内存 4GB 8GB+
磁盘空间 2GB 10GB+

生产环境服务器要求

最低配置

资源 要求
CPU 2 核心
内存 4GB
磁盘 40GB SSD
带宽 5Mbps

推荐配置

资源 要求
CPU 4 核心+
内存 8GB+
磁盘 100GB SSD
带宽 10Mbps+

软件依赖

软件 版本要求 说明
Node.js ≥14.0.0 (推荐 20.x LTS) 运行时环境
npm ≥6.0.0 包管理器
PM2 5.x+ 进程管理器(生产环境)
Nginx 1.18+ Web服务器/反向代理
MySQL 8.0+ 数据库(生产环境,推荐)
SQLite -(开发/小型 数据库部署)

端口要求

端口 用途 协议
8000 后端API服务 HTTP
3000 前端开发服务 HTTP
80 Nginx HTTP HTTP
443 Nginx HTTPS HTTPS

开发环境部署

1. 环境准备

Windows

方式一:官方安装包(推荐)

  1. 访问: https://nodejs.org/
  2. 下载 LTS 版本(推荐 v20.x
  3. 运行安装包,按向导完成安装

方式二:nvm-windows(推荐开发者)

  1. 下载安装 nvm-windows: https://github.com/coreybutler/nvm-windows/releases
  2. 执行: nvm install 20
  3. 执行: nvm use 20

方式三:WingetWindows 10/11

winget install OpenJS.NodeJS.LTS

macOS

方式一:Homebrew(推荐)

brew install node@20

方式二:nvm(推荐开发者)

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装 Node.js 20
nvm install 20
nvm use 20

Linux

Ubuntu/Debian:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

CentOS/RHEL/Fedora:

curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

使用 nvm(推荐开发者):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

2. 克隆项目

# 从Gitee克隆(国内访问更快)
git clone https://gitee.com/zhang96110/idc_assest.git

# 或从GitHub克隆
git clone https://github.com/gituib/idc_assest.git

cd idc_assest

3. 安装依赖

# 安装后端依赖
cd backend
npm install

# 安装前端依赖(新终端)
cd ../frontend
npm install

4. 配置环境变量

cd ../backend
cp .env.example .env

编辑 .env 文件(开发环境使用默认SQLite配置即可):

# 开发环境配置
NODE_ENV=development
PORT=8000
DB_TYPE=sqlite
DB_PATH=./idc_management.db

# JWT配置(开发环境可使用简单密钥)
JWT_SECRET=dev_secret_key_change_in_production
JWT_EXPIRES_IN=7d

5. 初始化数据库

node scripts/init-database.js

6. 启动服务

同时启动前后端(推荐):

# 项目根目录
npm start

分别启动:

# 终端1 - 启动后端(端口8000)
cd backend
npm run dev

# 终端2 - 启动前端(端口3000)
cd frontend
npm run dev

7. 访问开发环境

服务 地址
前端应用 http://localhost:3000
后端API http://localhost:8000/api
健康检查 http://localhost:8000/health

8. 开发命令

# 项目根目录命令
npm start                 # 同时启动前后端
npm run start:backend    # 仅启动后端
npm run start:frontend  # 仅启动前端
npm run install:all     # 安装所有依赖

# 后端命令
cd backend
npm run dev             # 开发模式启动(热重载)
npm start               # 生产模式启动

# 前端命令
cd frontend
npm run dev             # 开发模式启动
npm run build           # 构建生产版本
npm run preview         # 预览生产版本

测试环境部署

1. 服务器准备

测试环境配置要求:

项目 配置
操作系统 Ubuntu 20.04 LTS / CentOS 8
Node.js 20.x LTS
内存 4GB
磁盘 20GB SSD
数据库 MySQL 8.0(与生产一致)

2. 配置数据库

# 安装MySQL
sudo apt update
sudo apt install -y mysql-server

# 启动MySQL
sudo systemctl start mysql
sudo systemctl enable mysql

# 创建数据库和用户
sudo mysql
CREATE DATABASE idc_management CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'idc_test'@'localhost' IDENTIFIED BY 'test_password';
GRANT ALL PRIVILEGES ON idc_management.* TO 'idc_test'@'localhost';
FLUSH PRIVILEGES;
EXIT;

3. 配置环境变量

cd backend
cp .env.example .env

编辑 .env 文件:

NODE_ENV=test
PORT=8000
DB_TYPE=mysql
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USERNAME=idc_test
MYSQL_PASSWORD=test_password
MYSQL_DATABASE=idc_management
JWT_SECRET=test_jwt_secret_key
JWT_EXPIRES_IN=24h

4. 安装依赖并初始化

# 安装后端依赖
cd backend
npm install

# 初始化数据库
node scripts/init-database.js

# 安装前端依赖并构建
cd ../frontend
npm install
npm run build

5. 使用PM2启动服务

# 安装PM2
npm install -g pm2

# 启动后端服务
cd ../backend
pm2 start server.js --name "idc-test-backend" --env test

# 启动前端静态服务
cd ../frontend
pm2 serve --name "idc-test-frontend" -s dist -l 3000

# 保存PM2配置
pm2 save

# 配置开机自启
pm2 startup

6. 测试验证

# 测试后端API
curl http://localhost:8000/health

# 测试前端
curl http://localhost:3000

生产环境部署

1. 服务器要求

硬件要求

规模 CPU 内存 磁盘
小型(<100设备) 2核心 4GB 40GB
中型(100-500设备) 4核心 8GB 80GB
大型(>500设备) 8核心+ 16GB+ 100GB+

软件要求

软件 版本 说明
操作系统 Ubuntu 20.04+ / CentOS 8+ 推荐 Ubuntu 22.04 LTS
Node.js 20.x LTS 运行时环境
MySQL 8.0+ 数据库
Nginx 1.18+ 反向代理/静态文件
PM2 5.x+ 进程管理

2. 系统配置

创建部署用户(非root

# 创建用户
sudo adduser idcadmin

# 赋予sudo权限
sudo usermod -aG sudo idcadmin

# 切换到部署用户
sudo su - idcadmin

配置防火墙

# Ubuntu
sudo ufw allow 22    # SSH
sudo ufw allow 80    # HTTP
sudo ufw allow 443   # HTTPS
sudo ufw enable

# CentOS
sudo firewall-cmd --permanent --add-port=22/tcp
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --reload

3. 安装软件

安装Node.js

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 安装PM2
sudo npm install -g pm2

安装MySQL

# Ubuntu
sudo apt install -y mysql-server

sudo apt update
# 启动并配置
sudo systemctl start mysql
sudo systemctl enable mysql

安装Nginx

# Ubuntu
sudo apt install -y nginx
sudo systemctl start nginx
sudo systemctl enable nginx

4. 配置数据库

sudo mysql
-- 创建数据库
CREATE DATABASE idc_management CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建用户(生产环境使用强密码)
CREATE USER 'idc_prod'@'localhost' IDENTIFIED BY 'YOUR_STRONG_PASSWORD_HERE';
GRANT ALL PRIVILEGES ON idc_management.* TO 'idc_prod'@'localhost';
FLUSH PRIVILEGES;

EXIT;

5. 部署项目

克隆项目

cd /var/www
# 选择其一
# Gitee(国内推荐)
sudo git clone https://gitee.com/zhang96110/idc_assest.git
# GitHub
sudo git clone https://github.com/gituib/idc_assest.git
sudo chown -R idcadmin:idcadmin idc_assest

配置环境变量

cd /var/www/idc_assest/backend
cp .env.example .env
nano .env

编辑 .env 文件:

# 生产环境配置
NODE_ENV=production
PORT=8000
DB_TYPE=mysql
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USERNAME=idc_prod
MYSQL_PASSWORD=YOUR_STRONG_PASSWORD_HERE
MYSQL_DATABASE=idc_management

# JWT配置(使用强随机密钥)
JWT_SECRET=$(openssl rand -base64 32)
JWT_EXPIRES_IN=24h

# 日志配置
LOG_LEVEL=info

6. 安装依赖

# 安装后端依赖
cd /var/www/idc_assest/backend
npm install --production

# 安装前端依赖并构建
cd ../frontend
npm install
npm run build

7. 初始化数据库

cd ../backend
node scripts/init-database.js

8. 配置PM2

# 创建PM2配置文件
nano /var/www/idc_assest/ecosystem.config.js
module.exports = {
  apps: [
    {
      name: 'idc-backend',
      script: './server.js',
      cwd: '/var/www/idc_assest/backend',
      instances: 1,
      exec_mode: 'fork',
      env: {
        NODE_ENV: 'production',
        PORT: 8000
      },
      max_memory_restart: '1G',
      log_file: '/var/log/idc/combined.log',
      out_file: '/var/log/idc/out.log',
      error_file: '/var/log/idc/error.log',
      log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
      merge_logs: true,
      autorestart: true,
      watch: false
    }
  ]
};
# 创建日志目录
sudo mkdir -p /var/log/idc
sudo chown -R idcadmin:idcadmin /var/log/idc

# 启动服务
cd /var/www/idc_assest
pm2 start ecosystem.config.js
pm2 save
pm2 startup

9. 配置Nginx

sudo nano /etc/nginx/sites-available/idc
upstream idc_backend {
    server 127.0.0.1:8000;
}

server {
    listen 80;
    server_name your-domain.com;  # 替换为实际域名

    # 前端静态文件
    root /var/www/idc_assest/frontend/dist;
    index index.html;

    # Gzip压缩
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css text/xml text/javascript application/javascript application/xml+rss application/json;

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # 前端路由支持(SPA
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API代理
    location /api {
        proxy_pass http://idc_backend;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        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;
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }

    # 文件上传代理
    location /uploads {
        proxy_pass http://idc_backend;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        client_max_body_size 50M;
    }

    # 健康检查
    location /health {
        proxy_pass http://idc_backend/health;
    }
}
# 启用配置
sudo ln -s /etc/nginx/sites-available/idc /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx

10. 配置SSL证书(可选)

使用 Let's Encrypt 免费证书:

# 安装Certbot
sudo apt install -y certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d your-domain.com

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

Zeabur 云平台部署(推荐免费方案)

Zeabur 是国内团队开发的云平台,国内访问速度快,提供免费额度。

1. 准备工作

  • GitHub 账号
  • 项目代码已推送到 GitHub 仓库

2. 注册 Zeabur

  1. 访问 Zeabur 官网
  2. 点击「Sign in with GitHub」使用 GitHub 登录
  3. 授权 Zeabur 访问你的仓库

3. 创建项目

  1. 进入 Zeabur Dashboard
  2. 点击「New Project」创建新项目
  3. 选择区域(推荐:Hong Kong 或 Singapore

4. 部署 MySQL 数据库

  1. 在项目中点击「Add Service」→「Prebuilt」
  2. 搜索并选择「MySQL」
  3. 点击部署
  4. 记录数据库连接信息(稍后配置后端使用)

5. 部署后端服务

  1. 点击「Add Service」→「Git」
  2. 选择你的 GitHub 仓库
  3. 选择 backend 目录
  4. 配置环境变量:
NODE_ENV=production
PORT=8000
DB_TYPE=mysql
JWT_SECRET=your-strong-jwt-secret-at-least-32-characters
TOKEN_EXPIRY=24h
  1. 配置数据库连接(从 MySQL 服务获取):
MYSQL_HOST=${mysql:MYSQL_HOST}
MYSQL_PORT=${mysql:MYSQL_PORT}
MYSQL_USERNAME=${mysql:MYSQL_USERNAME}
MYSQL_PASSWORD=${mysql:MYSQL_PASSWORD}
MYSQL_DATABASE=${mysql:MYSQL_DATABASE}
  1. 点击部署

6. 部署前端服务

  1. 点击「Add Service」→「Git」
  2. 选择同一个仓库
  3. 选择 frontend 目录
  4. 配置环境变量:
VITE_API_URL=${idc-backend:ZEABUR_WEB_URL}
  1. 点击部署

7. 配置域名

  1. 进入前端服务 →「Domains」
  2. 点击「Generate Domain」生成免费域名
  3. 或绑定自定义域名

8. 部署完成

访问生成的域名即可使用系统。

Zeabur 配置文件说明

项目根目录的 zeabur.yaml 文件定义了服务配置:

services:
  - name: idc-backend
    type: prebuilt
    source:
      type: static
      path: backend
    env:
      NODE_ENV: production
      PORT: 8000
      DB_TYPE: mysql

  - name: idc-frontend
    type: prebuilt
    source:
      type: static
      path: frontend
    env:
      NODE_ENV: production

  - name: mysql
    type: prebuilt
    source:
      type: image
      url: mysql:8.0
    env:
      MYSQL_DATABASE: idc_management

常见问题

Q: 部署失败怎么办?

  • 检查构建日志,确认依赖安装成功
  • 确认环境变量配置正确
  • 检查 Dockerfile 是否存在

Q: 数据库连接失败?

  • 确认 MySQL 服务已启动
  • 检查环境变量引用格式:${mysql:MYSQL_HOST}

Q: 前端无法访问后端 API

  • 检查 VITE_API_URL 环境变量
  • 确认后端服务已启动并分配域名

数据库配置

SQLite(开发环境/小规模)

  • 默认配置,无需额外设置
  • 数据库文件:backend/idc_management.db
  • 优点:零配置,便携
  • 缺点:不适合高并发,单文件限制

MySQL(生产环境推荐)

创建数据库

CREATE DATABASE idc_management CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

配置优化

# my.cnf 或 my.ini
[mysqld]
character-set-server=utf8mb4
collation-server=utf8mb4_unicode_ci
max_connections=200
innodb_buffer_pool_size=1G

数据备份

SQLite备份

# 手动备份
cp backend/idc_management.db backup/database_$(date +%Y%m%d).db

MySQL备份

# 手动备份
mysqldump -u idc_prod -p idc_management > backup/database_$(date +%Y%m%d).sql

# 自动备份脚本
#!/bin/bash
BACKUP_DIR="/var/backups/idc"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR
mysqldump -u idc_prod -pYourPassword idc_management > "$BACKUP_DIR/database_$DATE.sql"
gzip "$BACKUP_DIR/database_$DATE.sql"

# 清理30天前的备份
find $BACKUP_DIR -name "database_*.gz" -mtime +30 -delete

添加到crontab

crontab -e
# 每天凌晨2点执行
0 2 * * * /path/to/backup_script.sh

部署验证

1. 服务状态检查

# PM2服务状态
pm2 status

# Nginx状态
sudo systemctl status nginx

# MySQL状态
sudo systemctl status mysql

2. 接口验证

# 健康检查
curl http://localhost:8000/health

# API测试
curl http://localhost:8000/api/rooms

# 上传接口测试
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

3. 日志检查

# PM2日志
pm2 logs idc-backend

# 错误日志
pm2 logs idc-backend --err

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

4. 性能测试

# 使用curl测试响应时间
time curl -o /dev/null -s -w "%{http_code}\n" http://localhost:8000/health

更新升级

方式一:一键更新脚本(推荐)

npm run update

功能:自动备份 → 拉取代码 → 更新依赖 → 重建前端 → 重启服务

方式二:手动更新

1. 备份数据

# 备份数据库
mysqldump -u idc_prod -p idc_management > /var/backups/idc/database_backup_$(date +%Y%m%d).sql

# 或备份SQLite
cp backend/idc_management.db /var/backups/idc/

2. 拉取最新代码

cd /var/www/idc_assest
git pull origin main

3. 更新依赖

# 更新后端依赖
cd backend
npm install

# 更新前端依赖并构建
cd ../frontend
npm install
npm run build

4. 运行数据库迁移(如有)

cd ../backend
node scripts/migrate-all.js

5. 重启服务

pm2 restart idc-backend
sudo nginx -t && sudo nginx -s reload

监控维护

服务管理命令

# PM2 管理
pm2 status                    # 查看服务状态
pm2 logs idc-backend          # 查看后端日志
pm2 logs idc-backend --err    # 查看错误日志
pm2 restart idc-backend       # 重启后端服务
pm2 stop idc-backend          # 停止后端服务
pm2 delete idc-backend        # 删除后端服务
pm2 save                      # 保存当前进程列表
pm2 startup                   # 配置开机自启
pm2 monit                     # 实时监控

# Nginx 管理
sudo nginx -t                 # 测试配置
sudo systemctl restart nginx  # 重启服务
sudo systemctl status nginx   # 查看状态

性能监控

PM2配置(ecosystem.config.js

module.exports = {
  apps: [{
    name: 'idc-backend',
    script: './server.js',
    cwd: './backend',
    instances: 1,
    exec_mode: 'fork',
    max_memory_restart: '1G',
    autorestart: true,
    env: {
      NODE_ENV: 'production'
    },
    log_file: './logs/combined.log',
    out_file: './logs/out.log',
    error_file: './logs/error.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss Z'
  }]
};

常见问题

端口冲突

# 检查端口占用
# Linux
netstat -tulpn | grep :8000

# Windows
netstat -ano | findstr :8000

# 修改端口
# 编辑 backend/.env 文件
PORT=8001

依赖安装失败

# 清理缓存
npm cache clean --force

# 删除 node_modules 重新安装
rm -rf node_modules package-lock.json
npm install

数据库连接失败

MySQL

  • 检查服务状态:sudo systemctl status mysql
  • 验证连接参数(主机、端口、用户名、密码)
  • 确认数据库已创建
  • 检查防火墙设置
  • 确认用户权限:SHOW GRANTS FOR 'idc_prod'@'localhost'

前端构建失败

# 检查 Node.js 版本
node -v

# 清理并重新构建
cd frontend
rm -rf node_modules dist
npm install
npm run build

权限问题

# 修复文件权限
sudo chown -R $(whoami):$(whoami) /var/www/idc_assest

# 上传目录权限
sudo chmod -R 777 backend/uploads

内存不足

# 增加 Node.js 内存限制
node --max-old-space-size=4096 server.js

# PM2 配置
pm2 start server.js --name "idc-backend" --node-args="--max-old-space-size=4096"

Nginx 502 Bad Gateway

  1. 检查后端服务是否运行:pm2 status
  2. 检查后端端口是否监听:netstat -tulpn | grep 8000
  3. 检查Nginx配置:nginx -t
  4. 查看错误日志:tail -f /var/log/nginx/error.log

SSL证书问题

# 检查证书是否过期
sudo certbot certificates

# 手动续期
sudo certbot renew

# 查看证书详情
sudo certbot certificates

项目结构

idc_assest/
├── backend/              # 后端服务
│   ├── middleware/       # 中间件(认证、验证)
│   ├── models/          # 数据模型(Sequelize
│   ├── routes/          # API路由
│   ├── scripts/         # 数据库脚本
│   ├── uploads/        # 文件上传目录
│   ├── validation/     # 数据验证Schema
│   ├── server.js       # 服务入口
│   └── package.json
├── frontend/            # 前端应用
│   ├── src/
│   │   ├── api/        # API接口
│   │   ├── components/ # 组件
│   │   ├── pages/      # 页面
│   │   └── utils/      # 工具函数
│   ├── dist/           # 构建输出
│   └── package.json
├── docs/                # 项目文档
│   ├── api/             # 接口文档
│   └── images/          # 文档图片
├── install.js           # 交互式安装脚本 ⭐
├── update.js            # 一键更新脚本 ⭐
├── uninstall.js         # 卸载脚本
├── check.js             # 环境检查脚本
├── modify.js            # 配置修改脚本
├── package.json
├── README.md            # 项目说明
├── CHANGELOG.md         # 版本记录
└── DEPLOYMENT.md       # 本文件

如果这个部署指南对您有帮助,请给我们一个Star!