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:**
```bash
# 安装 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:**
```bash
# 下载并安装 nvm-windows
# https://github.com/coreybutler/nvm-windows/releases

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

#### 2.1.2 验证安装
```bash
node --version  # 应显示 v18.x.x
npm --version   # 应显示 8.x.x 或更高
```

### 2.2 数据库配置

#### 2.2.1 MySQL 安装

**macOS (使用 Homebrew):**
```bash
brew install mysql
brew services start mysql
```

**Ubuntu/Debian:**
```bash
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 数据库初始化
```bash
# 登录 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:**
```bash
brew install redis
brew services start redis
```

**Ubuntu/Debian:**
```bash
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
```bash
redis-cli ping
# 应返回 PONG
```

### 2.4 项目配置

#### 2.4.1 克隆项目
```bash
git clone https://github.com/nxxmdata/smart-farming-platform.git
cd smart-farming-platform
```

#### 2.4.2 安装依赖

**后端依赖:**
```bash
cd backend
npm install
```

**前端依赖:**
```bash
cd admin-system
npm install
```

**小程序依赖:**
```bash
cd bank_mini_program
npm install
```

#### 2.4.3 环境变量配置

**后端环境变量 (.env):**
```bash
# 复制环境变量模板
cp backend/.env.example backend/.env

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

```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):**
```env
# 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 运行迁移
```bash
cd backend
npm run migrate
```

### 3.2 填充种子数据
```bash
npm run seed
```

### 3.3 重置数据库
```bash
npm run db:reset
```

## 4. 启动项目

### 4.1 启动后端服务
```bash
cd backend
npm run dev
```

### 4.2 启动前端服务
```bash
cd admin-system
npm run dev
```

### 4.3 启动小程序开发
```bash
cd bank_mini_program
npm run dev:mp-weixin
```

### 4.4 验证服务
```bash
# 检查后端服务
curl http://localhost:5350/api/health

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

## 5. 测试环境配置

### 5.1 环境变量

**后端测试环境 (.env.test):**
```env
NODE_ENV=test
PORT=5351

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

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

### 5.2 测试数据库初始化
```bash
# 创建测试数据库
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 运行测试
```bash
# 后端测试
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):**
```env
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):**
```bash
#!/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:**
```dockerfile
FROM node:18-alpine

WORKDIR /app

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

COPY . .

EXPOSE 5350

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

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

### 7.2 Docker Compose

**docker-compose.yml:**
```yaml
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 日志配置:**
```javascript
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 健康检查

**健康检查端点:**
```javascript
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 端口占用
```bash
# 查看端口占用
lsof -i :5350

# 杀死进程
kill -9 <PID>
```

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

# 重启 MySQL 服务
sudo systemctl restart mysql

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

#### 9.1.3 Redis 连接失败
```bash
# 检查 Redis 服务状态
sudo systemctl status redis

# 重启 Redis 服务
sudo systemctl restart redis

# 测试 Redis 连接
redis-cli ping
```

### 9.2 性能优化

#### 9.2.1 数据库优化
```sql
-- 添加索引
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 缓存优化
```javascript
// 缓存配置
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 配置:**
```nginx
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 防火墙配置:**
```bash
# 启用防火墙
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 数据库备份

**自动备份脚本:**
```bash
#!/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 文件备份

**文件备份脚本:**
```bash
#!/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  
**维护团队**: 宁夏智慧养殖平台开发团队