nxxmdata/docs/development/环境配置文档.md

宁夏智慧养殖监管平台 环境配置文档

版本历史

版本	日期	作者	描述
v1.0	2025-01-20	开发团队	初始版本

1. 环境概述

1.1 环境分类

本项目包含以下几种环境：

• 开发环境 (Development): 本地开发使用
• 测试环境 (Testing): QA测试使用
• 预生产环境 (Staging): 用户验收测试使用
• 生产环境 (Production): 正式运行环境

1.2 技术栈要求

基础环境：

• Node.js: 18.0+ (推荐 LTS 版本)
• npm: 8.0+ 或 yarn: 1.22+ 或 pnpm: 7.0+
• MySQL: 8.0+
• Redis: 6.0+
• Git: 2.25+

开发工具：

• Visual Studio Code (推荐)
• Postman (API测试)
• MySQL Workbench (数据库管理)

2. 开发环境配置

2.1 Node.js 安装

2.1.1 使用 nvm 管理 Node.js 版本

macOS/Linux:

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

# 重启终端或执行
source ~/.bashrc

# 安装并使用 Node.js 18
nvm install 18
nvm use 18
nvm alias default 18

Windows:

# 下载并安装 nvm-windows
# https://github.com/coreybutler/nvm-windows/releases

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

2.1.2 验证安装

node --version  # 应显示 v18.x.x
npm --version   # 应显示 8.x.x 或更高

2.2 数据库配置

2.2.1 MySQL 安装

macOS (使用 Homebrew):

brew install mysql
brew services start mysql

Ubuntu/Debian:

sudo apt update
sudo apt install mysql-server
sudo systemctl start mysql
sudo systemctl enable mysql

Windows: 下载并安装 MySQL Community Server： https://dev.mysql.com/downloads/mysql/

2.2.2 数据库初始化

# 登录 MySQL
mysql -u root -p

# 创建数据库
CREATE DATABASE nxxm_farming_dev CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 创建用户
CREATE USER 'nxxm_dev'@'localhost' IDENTIFIED BY 'dev_password_123';
GRANT ALL PRIVILEGES ON nxxm_farming_dev.* TO 'nxxm_dev'@'localhost';
FLUSH PRIVILEGES;

2.3 Redis 配置

2.3.1 Redis 安装

macOS:

brew install redis
brew services start redis

Ubuntu/Debian:

sudo apt update
sudo apt install redis-server
sudo systemctl start redis-server
sudo systemctl enable redis-server

Windows: 下载并安装 Redis for Windows： https://github.com/microsoftarchive/redis/releases

2.3.2 验证 Redis

redis-cli ping
# 应返回 PONG

2.4 项目配置

2.4.1 克隆项目

git clone https://github.com/nxxmdata/smart-farming-platform.git
cd smart-farming-platform

2.4.2 安装依赖

后端依赖:

cd backend
npm install

前端依赖:

cd admin-system
npm install

小程序依赖:

cd bank_mini_program
npm install

2.4.3 环境变量配置

后端环境变量 (.env):

# 复制环境变量模板
cp backend/.env.example backend/.env

# 编辑环境变量
vim backend/.env

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

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_NAME=nxxm_farming_dev
DB_USER=nxxm_dev
DB_PASSWORD=dev_password_123
DB_DIALECT=mysql

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

# JWT 配置
JWT_SECRET=your_jwt_secret_key_here
JWT_EXPIRES_IN=24h

# 文件上传配置
UPLOAD_PATH=./uploads
UPLOAD_MAX_SIZE=10485760

# 日志配置
LOG_LEVEL=debug
LOG_FILE=logs/app.log

前端环境变量 (.env.development):

# API 配置
VITE_API_BASE_URL=http://localhost:5350/api
VITE_API_TIMEOUT=10000

# 百度地图配置
VITE_BAIDU_MAP_AK=your_baidu_map_ak

# 上传配置
VITE_UPLOAD_URL=http://localhost:5350/api/upload

3. 数据库迁移

3.1 运行迁移

cd backend
npm run migrate

3.2 填充种子数据

npm run seed

3.3 重置数据库

npm run db:reset

4. 启动项目

4.1 启动后端服务

cd backend
npm run dev

4.2 启动前端服务

cd admin-system
npm run dev

4.3 启动小程序开发

cd bank_mini_program
npm run dev:mp-weixin

4.4 验证服务

# 检查后端服务
curl http://localhost:5350/api/health

# 检查前端服务
# 浏览器访问 http://localhost:3000

5. 测试环境配置

5.1 环境变量

后端测试环境 (.env.test):

NODE_ENV=test
PORT=5351

# 测试数据库
DB_NAME=nxxm_farming_test
DB_USER=nxxm_test
DB_PASSWORD=test_password_123

# 其他配置保持与开发环境一致

5.2 测试数据库初始化

# 创建测试数据库
mysql -u root -p -e "CREATE DATABASE nxxm_farming_test CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 运行测试迁移
NODE_ENV=test npm run migrate

5.3 运行测试

# 后端测试
cd backend
npm test

# 前端测试
cd admin-system
npm run test

# 小程序测试
cd bank_mini_program
npm test

6. 生产环境配置

6.1 服务器要求

最低配置：

• CPU: 2核
• 内存: 4GB
• 存储: 50GB SSD
• 网络: 10Mbps

推荐配置：

• CPU: 4核
• 内存: 8GB
• 存储: 100GB SSD
• 网络: 100Mbps

6.2 环境变量

生产环境 (.env.production):

NODE_ENV=production
PORT=5350

# 数据库配置
DB_HOST=your_production_db_host
DB_PORT=3306
DB_NAME=nxxm_farming_prod
DB_USER=nxxm_prod
DB_PASSWORD=your_secure_password

# Redis 配置
REDIS_HOST=your_redis_host
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password

# JWT 配置
JWT_SECRET=your_very_secure_jwt_secret
JWT_EXPIRES_IN=24h

# HTTPS 配置
HTTPS_ENABLED=true
SSL_CERT_PATH=/path/to/cert.pem
SSL_KEY_PATH=/path/to/key.pem

# 日志配置
LOG_LEVEL=info
LOG_FILE=/var/log/nxxm-farming/app.log

6.3 部署脚本

部署脚本 (deploy.sh):

#!/bin/bash

# 拉取最新代码
git pull origin main

# 安装依赖
npm ci --production

# 运行数据库迁移
npm run migrate

# 构建前端
cd admin-system
npm run build
cd ..

# 重启服务
pm2 restart nxxm-farming-backend
pm2 restart nxxm-farming-frontend

echo "部署完成"

7. Docker 配置

7.1 Dockerfile

后端 Dockerfile:

FROM node:18-alpine

WORKDIR /app

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

COPY . .

EXPOSE 5350

CMD ["npm", "start"]

前端 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

7.2 Docker Compose

docker-compose.yml:

version: '3.8'

services:
  backend:
    build: ./backend
    ports:
      - "5350:5350"
    environment:
      - NODE_ENV=production
      - DB_HOST=mysql
      - REDIS_HOST=redis
    depends_on:
      - mysql
      - redis

  frontend:
    build: ./admin-system
    ports:
      - "80:80"
    depends_on:
      - backend

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: nxxm_farming_prod
      MYSQL_USER: nxxm_prod
      MYSQL_PASSWORD: prodpassword
    volumes:
      - mysql_data:/var/lib/mysql

  redis:
    image: redis:6-alpine
    volumes:
      - redis_data:/data

volumes:
  mysql_data:
  redis_data:

8. 监控和日志

8.1 日志配置

Winston 日志配置:

const winston = require('winston');

const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  transports: [
    new winston.transports.File({ 
      filename: 'logs/error.log', 
      level: 'error' 
    }),
    new winston.transports.File({ 
      filename: 'logs/combined.log' 
    })
  ]
});

if (process.env.NODE_ENV !== 'production') {
  logger.add(new winston.transports.Console({
    format: winston.format.simple()
  }));
}

8.2 健康检查

健康检查端点:

app.get('/api/health', async (req, res) => {
  try {
    // 检查数据库连接
    await sequelize.authenticate();
    
    // 检查 Redis 连接
    await redis.ping();
    
    res.json({
      status: 'healthy',
      timestamp: new Date().toISOString(),
      services: {
        database: 'connected',
        redis: 'connected'
      }
    });
  } catch (error) {
    res.status(503).json({
      status: 'unhealthy',
      error: error.message
    });
  }
});

9. 故障排除

9.1 常见问题

9.1.1 端口占用

# 查看端口占用
lsof -i :5350

# 杀死进程
kill -9 <PID>

9.1.2 数据库连接失败

# 检查 MySQL 服务状态
sudo systemctl status mysql

# 重启 MySQL 服务
sudo systemctl restart mysql

# 检查数据库连接
mysql -u nxxm_dev -p -h localhost

9.1.3 Redis 连接失败

# 检查 Redis 服务状态
sudo systemctl status redis

# 重启 Redis 服务
sudo systemctl restart redis

# 测试 Redis 连接
redis-cli ping

9.2 性能优化

9.2.1 数据库优化

-- 添加索引
CREATE INDEX idx_farm_status ON farms(status);
CREATE INDEX idx_animal_farm_id ON animals(farm_id);

-- 查看慢查询
SHOW VARIABLES LIKE 'slow_query_log';
SET GLOBAL slow_query_log = 'ON';

9.2.2 Redis 缓存优化

// 缓存配置
const redis = new Redis({
  host: process.env.REDIS_HOST,
  port: process.env.REDIS_PORT,
  maxRetriesPerRequest: 3,
  retryDelayOnFailover: 100,
  lazyConnect: true
});

10. 安全配置

10.1 HTTPS 配置

Nginx HTTPS 配置:

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

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512;
    
    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;
    }
}

10.2 防火墙配置

UFW 防火墙配置:

# 启用防火墙
sudo ufw enable

# 允许 SSH
sudo ufw allow ssh

# 允许 HTTP/HTTPS
sudo ufw allow 80
sudo ufw allow 443

# 允许应用端口（仅内网）
sudo ufw allow from 10.0.0.0/8 to any port 5350

11. 备份和恢复

11.1 数据库备份

自动备份脚本:

#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/mysql"
DB_NAME="nxxm_farming_prod"

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

# 备份数据库
mysqldump -u root -p$MYSQL_ROOT_PASSWORD $DB_NAME > $BACKUP_DIR/backup_$DATE.sql

# 压缩备份文件
gzip $BACKUP_DIR/backup_$DATE.sql

# 删除7天前的备份
find $BACKUP_DIR -name "backup_*.sql.gz" -mtime +7 -delete

11.2 文件备份

文件备份脚本:

#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/files"
SOURCE_DIR="/app/uploads"

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

# 备份文件
tar -czf $BACKUP_DIR/files_$DATE.tar.gz -C $SOURCE_DIR .

# 删除30天前的备份
find $BACKUP_DIR -name "files_*.tar.gz" -mtime +30 -delete

---

最后更新: 2025年1月20日
文档版本: v1.0
维护团队: 宁夏智慧养殖平台开发团队