nxxmdata/docs/DEPLOYMENT.md

# 宁夏智慧养殖监管平台部署指南

## 概述

本文档详细说明了宁夏智慧养殖监管平台的部署流程，包括开发环境、测试环境和生产环境的部署方案。

## 系统要求

### 基础要求
- **操作系统**: Linux (推荐 Ubuntu 18.04+), macOS 10.14+, Windows 10+
- **Node.js**: 18.0 或更高版本
- **MySQL**: 8.0 或更高版本
- **内存**: 最少 4GB RAM（推荐 8GB+）
- **存储**: 最少 20GB 可用空间

### 推荐配置（生产环境）
- **CPU**: 4核 或更高
- **内存**: 16GB RAM
- **存储**: 100GB SSD
- **网络**: 100Mbps 带宽

## 前期准备

### 1. 环境检查
```bash
# 检查 Node.js 版本
node --version  # 应显示 v18.0.0 或更高

# 检查 npm 版本
npm --version

# 检查 MySQL 版本
mysql --version  # 应显示 8.0 或更高
```

### 2. 数据库准备
```sql
-- 创建数据库
CREATE DATABASE nxxmdata CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建数据库用户（可选）
CREATE USER 'nxxmdata_user'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON nxxmdata.* TO 'nxxmdata_user'@'localhost';
FLUSH PRIVILEGES;
```

### 3. 获取源代码
```bash
# 克隆项目（如果使用Git）
git clone <repository-url>
cd nxxmdata

# 或者解压源码包
unzip nxxmdata.zip
cd nxxmdata
```

## 开发环境部署

### 1. 安装依赖

#### 后端依赖安装
```bash
cd backend
npm install
```

#### 前端依赖安装
```bash
# 管理后台
cd admin-system/frontend
npm install

# 官网大屏
cd ../../website/data-screen
npm install

# 微信小程序（可选）
cd ../../mini_program/farm-monitor-dashboard
npm install
```

### 2. 环境配置

#### 后端环境配置
在 `backend` 目录下创建 `.env` 文件：
```bash
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_NAME=nxxmdata
DB_USER=root
DB_PASSWORD=your_mysql_password

# JWT配置
JWT_SECRET=your_jwt_secret_key_here
JWT_EXPIRES_IN=24h

# 服务器配置
PORT=5350
NODE_ENV=development

# 百度地图API配置
BAIDU_MAP_API_KEY=your_baidu_map_api_key

# 日志配置
LOG_LEVEL=debug
LOG_FILE_PATH=./logs/
```

#### 前端环境配置
在 `admin-system/frontend` 目录下创建 `.env` 文件：
```bash
# API配置
VITE_API_BASE_URL=http://localhost:5350/api
VITE_BAIDU_MAP_API_KEY=your_baidu_map_api_key

# 开发服务器配置
VITE_PORT=5301
```

### 3. 数据库初始化
```bash
cd backend

# 运行数据库迁移
npm run init-db

# 或者手动执行SQL脚本
mysql -u root -p nxxmdata < create_tables.sql
```

### 4. 启动开发服务器

#### 启动后端服务
```bash
cd backend
npm run dev
# 服务将在 http://localhost:5350 启动
```

#### 启动前端服务
```bash
# 启动管理后台
cd admin-system/frontend
npm run dev
# 服务将在 http://localhost:5301 启动

# 启动官网大屏
cd ../../website/data-screen
npm run dev
# 服务将在 http://localhost:5302 启动
```

### 5. 验证部署
访问以下URL验证部署是否成功：
- 后端API: http://localhost:5350/api/health
- 管理后台: http://localhost:5301
- 官网大屏: http://localhost:5302
- API文档: http://localhost:5350/api-docs

## 测试环境部署

### 1. 使用PM2管理进程
```bash
# 安装PM2
npm install -g pm2

# 构建项目
cd admin-system/frontend
npm run build

cd ../../website/data-screen  
npm run build

# 启动后端服务
cd ../../backend
pm2 start ecosystem.config.js --env test
```

### 2. Nginx配置
创建 `/etc/nginx/sites-available/nxxmdata-test` 文件：
```nginx
server {
    listen 80;
    server_name test.nxxmdata.com;

    # 前端静态文件
    location / {
        root /path/to/nxxmdata/admin-system/frontend/dist;
        try_files $uri $uri/ /index.html;
    }

    # 官网大屏
    location /screen {
        root /path/to/nxxmdata/website/data-screen/dist;
        try_files $uri $uri/ /index.html;
    }

    # API代理
    location /api {
        proxy_pass http://localhost:5350;
        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;
    }
}
```

## 生产环境部署

### 1. Docker部署（推荐）

#### 创建Dockerfile
```dockerfile
# 多阶段构建 - 前端构建阶段
FROM node:18-alpine AS frontend-builder

# 构建管理后台
WORKDIR /app/admin-system/frontend
COPY admin-system/frontend/package*.json ./
RUN npm ci --only=production
COPY admin-system/frontend/ ./
RUN npm run build

# 构建官网大屏
WORKDIR /app/website/data-screen
COPY website/data-screen/package*.json ./
RUN npm ci --only=production
COPY website/data-screen/ ./
RUN npm run build

# 后端运行阶段
FROM node:18-alpine AS backend

WORKDIR /app

# 安装后端依赖
COPY backend/package*.json ./
RUN npm ci --only=production

# 复制后端代码
COPY backend/ ./

# 复制前端构建产物
COPY --from=frontend-builder /app/admin-system/frontend/dist ./public/admin
COPY --from=frontend-builder /app/website/data-screen/dist ./public/screen

# 创建非root用户
RUN addgroup -g 1001 -S nodejs
RUN adduser -S node -u 1001
USER node

EXPOSE 5350

CMD ["npm", "start"]
```

#### 创建docker-compose.yml
```yaml
version: '3.8'
services:
  nxxmdata-app:
    build: .
    ports:
      - "5350:5350"
    environment:
      - NODE_ENV=production
      - DB_HOST=mysql
      - DB_PORT=3306
      - DB_NAME=nxxmdata
      - DB_USER=nxxmdata_user
      - DB_PASSWORD=${DB_PASSWORD}
      - JWT_SECRET=${JWT_SECRET}
    depends_on:
      - mysql
    restart: unless-stopped
    volumes:
      - ./logs:/app/logs

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
      - MYSQL_DATABASE=nxxmdata
      - MYSQL_USER=nxxmdata_user
      - MYSQL_PASSWORD=${DB_PASSWORD}
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql
      - ./create_tables.sql:/docker-entrypoint-initdb.d/init.sql
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./ssl:/etc/nginx/ssl
    depends_on:
      - nxxmdata-app
    restart: unless-stopped

volumes:
  mysql_data:
```

#### 创建环境变量文件
创建 `.env` 文件：
```bash
# 数据库密码
DB_PASSWORD=your_secure_db_password
MYSQL_ROOT_PASSWORD=your_secure_root_password

# JWT密钥
JWT_SECRET=your_very_secure_jwt_secret_key

# 百度地图API
BAIDU_MAP_API_KEY=your_baidu_map_api_key
```

#### 部署命令
```bash
# 构建并启动服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f nxxmdata-app
```

### 2. 传统部署方式

#### 安装和配置
```bash
# 1. 克隆项目
git clone <repository-url>
cd nxxmdata

# 2. 安装依赖
cd backend && npm install --production
cd ../admin-system/frontend && npm install && npm run build
cd ../../website/data-screen && npm install && npm run build

# 3. 配置环境变量
cp backend/.env.example backend/.env
# 编辑 .env 文件，设置生产环境配置

# 4. 初始化数据库
cd backend && npm run init-db

# 5. 使用PM2启动服务
npm install -g pm2
pm2 start ecosystem.config.js --env production
```

#### PM2配置文件 (ecosystem.config.js)
```javascript
module.exports = {
  apps: [{
    name: 'nxxmdata-backend',
    script: './server.js',
    cwd: './backend',
    instances: 'max',
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'production',
      PORT: 5350
    },
    error_file: './logs/pm2-error.log',
    out_file: './logs/pm2-out.log',
    log_file: './logs/pm2-combined.log',
    time: true
  }]
}
```

### 3. Nginx配置（生产环境）
```nginx
server {
    listen 80;
    server_name nxxmdata.com www.nxxmdata.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name nxxmdata.com www.nxxmdata.com;

    ssl_certificate /etc/nginx/ssl/nxxmdata.com.crt;
    ssl_certificate_key /etc/nginx/ssl/nxxmdata.com.key;

    # SSL配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512;
    ssl_prefer_server_ciphers off;

    # Gzip压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml;

    # 管理后台
    location / {
        root /path/to/nxxmdata/admin-system/frontend/dist;
        try_files $uri $uri/ /index.html;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # 官网大屏
    location /screen {
        alias /path/to/nxxmdata/website/data-screen/dist;
        try_files $uri $uri/ /index.html;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # API代理
    location /api {
        proxy_pass http://localhost:5350;
        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 30s;
        proxy_send_timeout 30s;
        proxy_read_timeout 30s;
    }

    # API文档
    location /api-docs {
        proxy_pass http://localhost:5350;
        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;
    }
}
```

## 监控和维护

### 1. 日志管理
```bash
# PM2日志管理
pm2 logs
pm2 logs nxxmdata-backend
pm2 flush  # 清空日志

# 应用日志位置
tail -f backend/logs/app.log
tail -f backend/logs/error.log
```

### 2. 性能监控
```bash
# PM2监控
pm2 monit

# 系统资源监控
htop
iostat -x 1
```

### 3. 数据库备份
```bash
# 创建备份脚本 backup.sh
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
mysqldump -u root -p nxxmdata > /backup/nxxmdata_$DATE.sql
find /backup -name "nxxmdata_*.sql" -mtime +7 -delete

# 设置定时任务
crontab -e
# 添加: 0 2 * * * /path/to/backup.sh
```

### 4. 自动更新脚本
```bash
#!/bin/bash
# update.sh
cd /path/to/nxxmdata
git pull origin main

# 构建前端
cd admin-system/frontend && npm run build
cd ../../website/data-screen && npm run build

# 重启服务
pm2 restart nxxmdata-backend
```

## 故障排除

### 常见问题

1. **端口占用**
```bash
# 查看端口占用
lsof -i :5350
netstat -tulpn | grep :5350

# 解决方法：杀死占用进程或更改端口
```

2. **数据库连接失败**
```bash
# 检查MySQL服务状态
systemctl status mysql

# 检查连接配置
mysql -u root -p -h localhost
```

3. **内存不足**
```bash
# 查看内存使用
free -h
top

# 优化PM2配置，减少实例数量
```

4. **磁盘空间不足**
```bash
# 查看磁盘使用
df -h

# 清理日志文件
pm2 flush
find /path/to/logs -name "*.log" -mtime +30 -delete
```

## 安全加固

### 1. 防火墙配置
```bash
# 使用ufw
ufw allow 22     # SSH
ufw allow 80     # HTTP
ufw allow 443    # HTTPS
ufw enable
```

### 2. SSL证书配置
```bash
# 使用Let's Encrypt
certbot --nginx -d nxxmdata.com -d www.nxxmdata.com

# 自动续期
echo "0 12 * * * /usr/bin/certbot renew --quiet" | crontab -
```

### 3. 定期安全更新
```bash
# 系统更新
apt update && apt upgrade -y

# Node.js依赖安全检查
npm audit
npm audit fix
```

## 性能优化

### 1. 数据库优化
```sql
-- 添加必要的索引
CREATE INDEX idx_farms_location ON farms(location);
CREATE INDEX idx_devices_status ON devices(status);
CREATE INDEX idx_alerts_created_at ON alerts(created_at);

-- 定期优化表
OPTIMIZE TABLE farms, devices, alerts, users;
```

### 2. 缓存配置
```bash
# 安装Redis（可选）
apt install redis-server

# 在应用中配置Redis缓存
```

### 3. CDN配置
- 静态资源使用CDN加速
- 图片和视频文件外部存储

## 回滚策略

### 1. 代码回滚
```bash
# Git回滚
git revert <commit-hash>
git push origin main

# 重新部署
./update.sh
```

### 2. 数据库回滚
```bash
# 恢复数据库备份
mysql -u root -p nxxmdata < /backup/nxxmdata_20231201_020000.sql
```

### 3. 服务回滚
```bash
# 停止当前版本
pm2 stop nxxmdata-backend

# 恢复上一版本
pm2 start ecosystem.config.js.backup
```

---

## 联系信息

如有部署问题，请联系技术支持团队：
- 邮箱: tech-support@nxxmdata.com
- 电话: 400-xxx-xxxx

*最后更新: 2025年1月*