nxxmdata/docs/operations/部署文档.md

# 宁夏智慧养殖监管平台部署文档

## 版本历史

| 版本 | 日期 | 修改内容 | 修改人 |
|------|------|----------|--------|
| v1.0 | 2024-01-15 | 初始版本，基础部署流程 | 开发团队 |
| v2.0 | 2024-01-20 | 全面重构，增加多端部署和容器化支持 | 开发团队 |

## 1. 部署概述

### 1.1 部署架构
本平台采用前后端分离架构，支持多端部署：
- **后端服务**: Node.js + Express + MySQL
- **管理后台**: Vue.js 3 + Ant Design Vue
- **官网大屏**: Vue.js 3 + ECharts
- **微信小程序**: 原生小程序开发
- **移动端应用**: 基于 Vue.js 的响应式设计

### 1.2 部署环境
- **开发环境**: 本地开发调试
- **测试环境**: 功能测试和集成测试
- **预生产环境**: 性能测试和用户验收
- **生产环境**: 正式运行环境

## 2. 系统要求

### 2.1 基础要求
- **操作系统**: Linux (推荐 Ubuntu 20.04+), CentOS 8+, macOS 11+, Windows 10+
- **Node.js**: 18.0+ (推荐 18.17.0)
- **MySQL**: 8.0+ (推荐 8.0.33)
- **Redis**: 6.0+ (推荐 7.0.11)
- **Nginx**: 1.18+ (生产环境)

### 2.2 硬件要求

#### 开发环境
- **CPU**: 2核心
- **内存**: 8GB RAM
- **存储**: 50GB 可用空间
- **网络**: 10Mbps

#### 生产环境
- **CPU**: 8核心或更高
- **内存**: 32GB RAM
- **存储**: 500GB SSD
- **网络**: 100Mbps 专线
- **负载均衡**: 支持高可用部署

### 2.3 软件依赖
```bash
# 必需软件
- Node.js 18.17.0+
- MySQL 8.0.33+
- Redis 7.0.11+
- PM2 (生产环境进程管理)
- Nginx (反向代理和静态文件服务)

# 可选软件
- Docker & Docker Compose (容器化部署)
- Git (版本控制)
- SSL证书 (HTTPS支持)
```

## 3. 环境准备

### 3.1 系统环境检查
```bash
# 检查 Node.js 版本
node --version  # 应显示 v18.17.0 或更高

# 检查 npm 版本
npm --version   # 应显示 9.0.0 或更高

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

# 检查 Redis 版本
redis-server --version # 应显示 7.0.11 或更高
```

### 3.2 数据库初始化
```sql
-- 创建主数据库
CREATE DATABASE nxxmdata CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建测试数据库
CREATE DATABASE nxxmdata_test CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建专用用户
CREATE USER 'nxxmdata_user'@'%' IDENTIFIED BY 'NxxmData2024!@#';
GRANT ALL PRIVILEGES ON nxxmdata.* TO 'nxxmdata_user'@'%';
GRANT ALL PRIVILEGES ON nxxmdata_test.* TO 'nxxmdata_user'@'%';
FLUSH PRIVILEGES;

-- 优化配置
SET GLOBAL innodb_buffer_pool_size = 2147483648; -- 2GB
SET GLOBAL max_connections = 1000;
SET GLOBAL query_cache_size = 268435456; -- 256MB
```

### 3.3 Redis 配置
```bash
# Redis 配置文件 /etc/redis/redis.conf
bind 127.0.0.1
port 6379
timeout 300
tcp-keepalive 60
maxmemory 1gb
maxmemory-policy allkeys-lru
save 900 1
save 300 10
save 60 10000
```

## 4. 源码部署

### 4.1 获取源码
```bash
# 方式1: Git克隆
git clone https://github.com/your-org/nxxmdata.git
cd nxxmdata

# 方式2: 下载压缩包
wget https://github.com/your-org/nxxmdata/archive/main.zip
unzip main.zip
cd nxxmdata-main

# 检查项目结构
ls -la
# 应该看到: backend/, admin-system/, website/, mini-app/, docs/
```

### 4.2 后端服务部署

#### 4.2.1 安装依赖
```bash
cd backend
npm install --production

# 安装全局依赖
npm install -g pm2 nodemon
```

#### 4.2.2 环境配置
创建 `backend/.env` 文件：
```bash
# 应用配置
NODE_ENV=production
PORT=5350
APP_NAME=宁夏智慧养殖监管平台

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_NAME=nxxmdata
DB_USER=nxxmdata_user
DB_PASSWORD=NxxmData2024!@#
DB_POOL_MIN=5
DB_POOL_MAX=20

# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# JWT配置
JWT_SECRET=nxxmdata_jwt_secret_2024_very_secure_key
JWT_EXPIRES_IN=24h
JWT_REFRESH_EXPIRES_IN=7d

# 文件上传配置
UPLOAD_PATH=/var/www/nxxmdata/uploads
MAX_FILE_SIZE=10485760
ALLOWED_FILE_TYPES=jpg,jpeg,png,gif,pdf,doc,docx,xls,xlsx

# 第三方服务配置
BAIDU_MAP_AK=your_baidu_map_api_key
WECHAT_APPID=your_wechat_appid
WECHAT_SECRET=your_wechat_secret

# 邮件配置
SMTP_HOST=smtp.qq.com
SMTP_PORT=587
SMTP_USER=your_email@qq.com
SMTP_PASS=your_email_password

# 日志配置
LOG_LEVEL=info
LOG_PATH=/var/log/nxxmdata
```

#### 4.2.3 数据库迁移
```bash
# 运行数据库迁移
npm run migrate

# 初始化基础数据
npm run seed

# 验证数据库连接
npm run db:check
```

#### 4.2.4 启动后端服务
```bash
# 开发环境
npm run dev

# 生产环境
npm run start

# 使用PM2管理进程
pm2 start ecosystem.config.js
pm2 save
pm2 startup
```

### 4.3 管理后台部署

#### 4.3.1 安装依赖
```bash
cd admin-system
npm install
```

#### 4.3.2 环境配置
创建 `admin-system/.env.production` 文件：
```bash
# API配置
VITE_API_BASE_URL=https://api.nxxmdata.com
VITE_API_TIMEOUT=30000

# 应用配置
VITE_APP_TITLE=宁夏智慧养殖监管平台
VITE_APP_VERSION=2.0.0
VITE_APP_ENV=production

# 地图配置
VITE_BAIDU_MAP_AK=your_baidu_map_api_key

# 文件上传配置
VITE_UPLOAD_URL=https://api.nxxmdata.com/api/upload
VITE_MAX_FILE_SIZE=10485760

# 功能开关
VITE_ENABLE_MOCK=false
VITE_ENABLE_DEBUG=false
```

#### 4.3.3 构建和部署
```bash
# 构建生产版本
npm run build

# 检查构建结果
ls -la dist/

# 部署到Web服务器
sudo cp -r dist/* /var/www/nxxmdata/admin/
sudo chown -R www-data:www-data /var/www/nxxmdata/admin/
```

### 4.4 官网大屏部署

#### 4.4.1 安装依赖
```bash
cd website
npm install
```

#### 4.4.2 环境配置
创建 `website/.env.production` 文件：
```bash
# API配置
VITE_API_BASE_URL=https://api.nxxmdata.com
VITE_WS_URL=wss://api.nxxmdata.com/ws

# 大屏配置
VITE_SCREEN_WIDTH=1920
VITE_SCREEN_HEIGHT=1080
VITE_AUTO_REFRESH_INTERVAL=30000

# 地图配置
VITE_BAIDU_MAP_AK=your_baidu_map_api_key
VITE_MAP_CENTER_LNG=106.2309
VITE_MAP_CENTER_LAT=38.4872
```

#### 4.4.3 构建和部署
```bash
# 构建生产版本
npm run build

# 部署到Web服务器
sudo cp -r dist/* /var/www/nxxmdata/screen/
sudo chown -R www-data:www-data /var/www/nxxmdata/screen/
```

### 4.5 微信小程序部署

#### 4.5.1 配置小程序
编辑 `mini-app/project.config.json`：
```json
{
  "appid": "your_wechat_miniprogram_appid",
  "projectname": "宁夏智慧养殖监管平台",
  "setting": {
    "urlCheck": true,
    "es6": true,
    "enhance": true,
    "postcss": true,
    "minified": true
  }
}
```

#### 4.5.2 配置API地址
编辑 `mini-app/config/index.js`：
```javascript
const config = {
  development: {
    baseURL: 'https://dev-api.nxxmdata.com'
  },
  production: {
    baseURL: 'https://api.nxxmdata.com'
  }
}

export default config[process.env.NODE_ENV || 'production']
```

#### 4.5.3 上传发布
```bash
# 使用微信开发者工具上传代码
# 或使用命令行工具
npm install -g miniprogram-ci
npm run upload
```

## 5. Nginx 配置

### 5.1 安装 Nginx
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install nginx

# CentOS/RHEL
sudo yum install nginx
```

### 5.2 配置文件
创建 `/etc/nginx/sites-available/nxxmdata` 文件：
```nginx
# 管理后台配置
server {
    listen 80;
    server_name admin.nxxmdata.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name admin.nxxmdata.com;
    
    ssl_certificate /etc/ssl/certs/nxxmdata.crt;
    ssl_certificate_key /etc/ssl/private/nxxmdata.key;
    
    root /var/www/nxxmdata/admin;
    index index.html;
    
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    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;
    }
    
    location /uploads {
        alias /var/www/nxxmdata/uploads;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

# 大屏展示配置
server {
    listen 80;
    server_name screen.nxxmdata.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name screen.nxxmdata.com;
    
    ssl_certificate /etc/ssl/certs/nxxmdata.crt;
    ssl_certificate_key /etc/ssl/private/nxxmdata.key;
    
    root /var/www/nxxmdata/screen;
    index index.html;
    
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    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;
    }
    
    location /ws {
        proxy_pass http://localhost:5350;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;
    }
}

# API服务配置
server {
    listen 80;
    server_name api.nxxmdata.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.nxxmdata.com;
    
    ssl_certificate /etc/ssl/certs/nxxmdata.crt;
    ssl_certificate_key /etc/ssl/private/nxxmdata.key;
    
    location / {
        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;
        
        # CORS配置
        add_header Access-Control-Allow-Origin *;
        add_header Access-Control-Allow-Methods 'GET, POST, PUT, DELETE, OPTIONS';
        add_header Access-Control-Allow-Headers 'DNT,X-Mx-ReqToken,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization';
        
        if ($request_method = 'OPTIONS') {
            return 204;
        }
    }
    
    location /uploads {
        alias /var/www/nxxmdata/uploads;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}
```

### 5.3 启用配置
```bash
# 创建软链接
sudo ln -s /etc/nginx/sites-available/nxxmdata /etc/nginx/sites-enabled/

# 测试配置
sudo nginx -t

# 重启Nginx
sudo systemctl restart nginx
sudo systemctl enable nginx
```

## 6. 容器化部署

### 6.1 Docker 配置

#### 6.1.1 后端 Dockerfile
创建 `backend/Dockerfile`：
```dockerfile
FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .

EXPOSE 5350

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

#### 6.1.2 前端 Dockerfile
创建 `admin-system/Dockerfile`：
```dockerfile
FROM node:18-alpine as builder

WORKDIR /app
COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

### 6.2 Docker Compose 配置
创建 `docker-compose.yml`：
```yaml
version: '3.8'

services:
  mysql:
    image: mysql:8.0
    container_name: nxxmdata-mysql
    environment:
      MYSQL_ROOT_PASSWORD: root_password
      MYSQL_DATABASE: nxxmdata
      MYSQL_USER: nxxmdata_user
      MYSQL_PASSWORD: NxxmData2024!@#
    volumes:
      - mysql_data:/var/lib/mysql
      - ./backend/database/init.sql:/docker-entrypoint-initdb.d/init.sql
    ports:
      - "3306:3306"
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: nxxmdata-redis
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    restart: unless-stopped

  backend:
    build: ./backend
    container_name: nxxmdata-backend
    environment:
      NODE_ENV: production
      DB_HOST: mysql
      REDIS_HOST: redis
    ports:
      - "5350:5350"
    depends_on:
      - mysql
      - redis
    volumes:
      - uploads_data:/app/uploads
    restart: unless-stopped

  admin:
    build: ./admin-system
    container_name: nxxmdata-admin
    ports:
      - "8080:80"
    restart: unless-stopped

  screen:
    build: ./website
    container_name: nxxmdata-screen
    ports:
      - "8081:80"
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    container_name: nxxmdata-nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf
      - ./nginx/ssl:/etc/ssl
      - uploads_data:/var/www/uploads
    depends_on:
      - backend
      - admin
      - screen
    restart: unless-stopped

volumes:
  mysql_data:
  redis_data:
  uploads_data:
```

### 6.3 容器部署命令
```bash
# 构建和启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f backend

# 停止服务
docker-compose down

# 更新服务
docker-compose pull
docker-compose up -d --force-recreate
```

## 7. 生产环境优化

### 7.1 性能优化
```bash
# PM2 集群模式
pm2 start ecosystem.config.js --env production

# Nginx 缓存配置
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

# 数据库连接池优化
DB_POOL_MIN=10
DB_POOL_MAX=50
DB_POOL_IDLE=10000
DB_POOL_ACQUIRE=60000
```

### 7.2 安全配置
```bash
# 防火墙配置
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

# SSL证书配置
sudo certbot --nginx -d admin.nxxmdata.com -d api.nxxmdata.com -d screen.nxxmdata.com

# 定期更新证书
sudo crontab -e
0 12 * * * /usr/bin/certbot renew --quiet
```

### 7.3 监控配置
```bash
# 安装监控工具
npm install -g pm2-logrotate
pm2 install pm2-server-monit

# 日志轮转
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 30
pm2 set pm2-logrotate:compress true
```

## 8. 备份与恢复

### 8.1 数据库备份
```bash
#!/bin/bash
# 创建备份脚本 /opt/nxxmdata/backup.sh

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/opt/nxxmdata/backups"
DB_NAME="nxxmdata"
DB_USER="nxxmdata_user"
DB_PASS="NxxmData2024!@#"

# 创建备份目录
mkdir -p $BACKUP_DIR

# 数据库备份
mysqldump -u$DB_USER -p$DB_PASS $DB_NAME > $BACKUP_DIR/db_backup_$DATE.sql

# 文件备份
tar -czf $BACKUP_DIR/files_backup_$DATE.tar.gz /var/www/nxxmdata/uploads

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

echo "Backup completed: $DATE"
```

### 8.2 自动备份
```bash
# 添加到crontab
sudo crontab -e
0 2 * * * /opt/nxxmdata/backup.sh >> /var/log/nxxmdata-backup.log 2>&1
```

### 8.3 数据恢复
```bash
# 恢复数据库
mysql -u nxxmdata_user -p nxxmdata < /opt/nxxmdata/backups/db_backup_20240120_020000.sql

# 恢复文件
tar -xzf /opt/nxxmdata/backups/files_backup_20240120_020000.tar.gz -C /
```

## 9. 故障排除

### 9.1 常见问题

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

# 检查端口占用
netstat -tlnp | grep 3306

# 检查防火墙
sudo ufw status

# 测试连接
mysql -h localhost -u nxxmdata_user -p nxxmdata
```

#### 9.1.2 Node.js 服务异常
```bash
# 查看PM2进程状态
pm2 status

# 查看应用日志
pm2 logs backend

# 重启应用
pm2 restart backend

# 查看系统资源
htop
df -h
```

#### 9.1.3 Nginx 配置错误
```bash
# 测试配置文件
sudo nginx -t

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

# 重新加载配置
sudo nginx -s reload
```

### 9.2 性能监控
```bash
# 系统监控
htop
iotop
nethogs

# 应用监控
pm2 monit

# 数据库监控
SHOW PROCESSLIST;
SHOW STATUS LIKE 'Threads_connected';
```

## 10. 维护计划

### 10.1 日常维护
- **每日**: 检查系统日志和应用状态
- **每周**: 检查磁盘空间和数据库性能
- **每月**: 更新系统补丁和依赖包
- **每季度**: 性能评估和容量规划

### 10.2 更新流程
```bash
# 1. 备份当前版本
./backup.sh

# 2. 下载新版本
git pull origin main

# 3. 更新依赖
cd backend && npm install
cd ../admin-system && npm install && npm run build

# 4. 数据库迁移
npm run migrate

# 5. 重启服务
pm2 restart all

# 6. 验证功能
curl -f http://localhost:5350/api/health
```

### 10.3 回滚计划
```bash
# 1. 停止服务
pm2 stop all

# 2. 恢复代码
git checkout previous-stable-tag

# 3. 恢复数据库
mysql -u nxxmdata_user -p nxxmdata < backup.sql

# 4. 重启服务
pm2 start all
```

## 11. 联系支持

### 11.1 技术支持
- **邮箱**: support@nxxmdata.com
- **电话**: 400-xxx-xxxx
- **工作时间**: 周一至周五 9:00-18:00

### 11.2 紧急联系
- **24小时热线**: 138-xxxx-xxxx
- **微信群**: 宁夏智慧养殖技术支持群

---

**注意**: 本文档会根据系统更新持续维护，请定期查看最新版本。