makemd/docs/Deployment_Guide.md

# 部署文档

## 1. 系统概述

Crawlful Hub 是一个多平台电商管理系统，支持多租户、多店铺管理，提供商品、订单、财务、营销等核心功能。本指南将帮助您部署和配置系统。

## 2. 硬件要求

### 2.1 最低配置

| 组件 | 要求 |
|------|------|
| CPU | 4核 |
| 内存 | 8GB |
| 存储 | 100GB SSD |
| 网络 | 100Mbps |

### 2.2 推荐配置

| 组件 | 要求 |
|------|------|
| CPU | 8核 |
| 内存 | 16GB |
| 存储 | 200GB SSD |
| 网络 | 1Gbps |

## 3. 软件依赖

### 3.1 核心依赖

| 软件 | 版本 | 用途 |
|------|------|------|
| Node.js | 16.x 或更高 | 运行时环境 |
| npm | 8.x 或更高 | 包管理工具 |
| MySQL | 8.0 或更高 | 数据库 |
| Redis | 6.0 或更高 | 缓存和队列 |
| NGINX | 1.18 或更高 | 反向代理 |

### 3.2 可选依赖

| 软件 | 版本 | 用途 |
|------|------|------|
| Docker | 20.10 或更高 | 容器化部署 |
| Docker Compose | 1.29 或更高 | 容器编排 |
| PM2 | 5.x 或更高 | 进程管理 |

## 4. 安装步骤

### 4.1 环境准备

#### 4.1.1 安装 Node.js 和 npm

**Ubuntu/Debian**：

```bash
# 添加 Node.js 源
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -

# 安装 Node.js 和 npm
sudo apt-get install -y nodejs

# 验证安装
node -v
npm -v
```

**CentOS/RHEL**：

```bash
# 添加 Node.js 源
sudo curl -fsSL https://rpm.nodesource.com/setup_16.x | bash -

# 安装 Node.js 和 npm
sudo yum install -y nodejs

# 验证安装
node -v
npm -v
```

**Windows**：

1. 访问 [Node.js 官网](https://nodejs.org/en/download/)
2. 下载并安装 Node.js LTS 版本
3. 验证安装：打开命令提示符，运行 `node -v` 和 `npm -v`

#### 4.1.2 安装 MySQL

**Ubuntu/Debian**：

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

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

# 配置 MySQL
mysql_secure_installation
```

**CentOS/RHEL**：

```bash
# 安装 MySQL
sudo yum update
sudo yum install -y mysql-server

# 启动 MySQL 服务
sudo systemctl start mysqld
sudo systemctl enable mysqld

# 配置 MySQL
mysql_secure_installation
```

**Windows**：

1. 访问 [MySQL 官网](https://dev.mysql.com/downloads/installer/)
2. 下载并安装 MySQL Installer
3. 按照向导完成安装和配置

#### 4.1.3 安装 Redis

**Ubuntu/Debian**：

```bash
# 安装 Redis
sudo apt-get update
sudo apt-get install -y redis-server

# 启动 Redis 服务
sudo systemctl start redis-server
sudo systemctl enable redis-server
```

**CentOS/RHEL**：

```bash
# 安装 Redis
sudo yum update
sudo yum install -y redis

# 启动 Redis 服务
sudo systemctl start redis
sudo systemctl enable redis
```

**Windows**：

1. 访问 [Redis 官网](https://github.com/tporadowski/redis/releases)
2. 下载并安装 Redis for Windows
3. 启动 Redis 服务

#### 4.1.4 安装 NGINX

**Ubuntu/Debian**：

```bash
# 安装 NGINX
sudo apt-get update
sudo apt-get install -y nginx

# 启动 NGINX 服务
sudo systemctl start nginx
sudo systemctl enable nginx
```

**CentOS/RHEL**：

```bash
# 安装 NGINX
sudo yum update
sudo yum install -y nginx

# 启动 NGINX 服务
sudo systemctl start nginx
sudo systemctl enable nginx
```

**Windows**：

1. 访问 [NGINX 官网](https://nginx.org/en/download.html)
2. 下载并解压 NGINX
3. 启动 NGINX 服务

### 4.2 系统安装

#### 4.2.1 克隆代码库

```bash
# 克隆代码库
git clone https://github.com/crawlful/crawlful-hub.git
cd crawlful-hub
```

#### 4.2.2 安装依赖

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

# 安装前端依赖
cd ../dashboard
npm install
```

#### 4.2.3 配置环境变量

**后端配置**：

在 `server` 目录下创建 `.env` 文件：

```env
# 服务器配置
PORT=3000
NODE_ENV=production

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=crawlful_hub

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

# JWT 配置
JWT_SECRET=your_jwt_secret
JWT_EXPIRES_IN=24h

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

# 其他配置
API_PREFIX=/api/v1
CORS_ORIGIN=*
```

**前端配置**：

在 `dashboard` 目录下创建 `.env` 文件：

```env
# 前端配置
REACT_APP_API_URL=http://localhost:3000/api/v1
REACT_APP_SYSTEM_NAME=Crawlful Hub
REACT_APP_ENV=production
```

#### 4.2.4 数据库初始化

```bash
# 进入后端目录
cd server

# 运行数据库迁移
npm run migrate

# 初始化数据
npm run seed
```

#### 4.2.5 构建前端

```bash
# 进入前端目录
cd ../dashboard

# 构建前端
npm run build

# 将构建产物复制到后端静态目录
cp -r build/* ../server/public/
```

## 5. 配置说明

### 5.1 数据库配置

#### 5.1.1 创建数据库

```sql
CREATE DATABASE crawlful_hub CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

#### 5.1.2 创建用户

```sql
CREATE USER 'crawlful'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON crawlful_hub.* TO 'crawlful'@'localhost';
FLUSH PRIVILEGES;
```

### 5.2 Redis 配置

编辑 Redis 配置文件（通常位于 `/etc/redis/redis.conf`）：

```conf
# 绑定地址
bind 127.0.0.1

# 端口
port 6379

# 密码
requirepass your_redis_password

# 内存限制
maxmemory 2gb
maxmemory-policy allkeys-lru

# 持久化
save 900 1
save 300 10
save 60 10000
```

### 5.3 NGINX 配置

创建 NGINX 配置文件（通常位于 `/etc/nginx/sites-available/crawlful.conf`）：

```nginx
server {
    listen 80;
    server_name example.com;

    location / {
        root /path/to/crawlful-hub/server/public;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    error_page 404 /404.html;
    error_page 500 502 503 504 /500.html;
}
```

启用配置：

```bash
sudo ln -s /etc/nginx/sites-available/crawlful.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

### 5.4 PM2 配置

创建 PM2 配置文件（`ecosystem.config.js`）：

```javascript
module.exports = {
  apps: [
    {
      name: 'crawlful-api',
      script: 'server.js',
      cwd: '/path/to/crawlful-hub/server',
      instances: 2,
      exec_mode: 'cluster',
      env: {
        NODE_ENV: 'production'
      },
      restart_delay: 1000,
      max_memory_restart: '1G'
    }
  ]
};
```

## 6. 启动和停止

### 6.1 使用 PM2 管理

```bash
# 启动服务
pm install -g pm2
cd /path/to/crawlful-hub
pm run start:pm2

# 查看状态
pm run status

# 停止服务
npm run stop

# 重启服务
npm run restart
```

### 6.2 直接启动

```bash
# 启动后端
cd /path/to/crawlful-hub/server
npm start

# 启动前端（开发模式）
cd /path/to/crawlful-hub/dashboard
npm start
```

### 6.3 系统服务

创建系统服务文件（`/etc/systemd/system/crawlful.service`）：

```ini
[Unit]
Description=Crawlful Hub
After=network.target mysql.service redis.service

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/path/to/crawlful-hub/server
ExecStart=/usr/bin/node server.js
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

启用服务：

```bash
sudo systemctl daemon-reload
sudo systemctl enable crawlful
sudo systemctl start crawlful
```

## 7. 监控和维护

### 7.1 日志管理

**后端日志**：

```bash
# 查看后端日志
cd /path/to/crawlful-hub/server
npm run logs

# 或使用 PM2 查看日志
pm run logs:pm2
```

**NGINX 日志**：

```bash
# 查看访问日志
tail -f /var/log/nginx/access.log

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

### 7.2 数据库备份

```bash
# 备份数据库
mysqldump -u root -p crawlful_hub > crawlful_hub_backup.sql

# 恢复数据库
mysql -u root -p crawlful_hub < crawlful_hub_backup.sql
```

### 7.3 系统更新

```bash
# 拉取最新代码
git pull

# 更新依赖
cd server && npm install && cd ..
cd dashboard && npm install && cd ..

# 构建前端
cd dashboard && npm run build && cp -r build/* ../server/public/ && cd ..

# 重启服务
npm run restart
```

### 7.4 性能监控

**使用 PM2 监控**：

```bash
# 查看监控面板
pm run monit
```

**使用 Redis 监控**：

```bash
# 连接 Redis
redis-cli

# 查看 Redis 信息
info
```

**使用 MySQL 监控**：

```bash
# 连接 MySQL
mysql -u root -p

# 查看 MySQL 状态
SHOW GLOBAL STATUS;
```

## 8. 常见问题

### 8.1 数据库连接失败

- 检查数据库服务是否运行
- 检查数据库配置是否正确
- 检查数据库用户权限是否正确

### 8.2 Redis 连接失败

- 检查 Redis 服务是否运行
- 检查 Redis 配置是否正确
- 检查 Redis 密码是否正确

### 8.3 前端无法访问后端 API

- 检查后端服务是否运行
- 检查 NGINX 配置是否正确
- 检查 CORS 配置是否正确

### 8.4 系统性能问题

- 检查服务器资源使用情况
- 优化数据库查询
- 增加服务器资源
- 启用缓存

### 8.5 安全问题

- 定期更新系统和依赖
- 使用 HTTPS
- 配置防火墙
- 定期备份数据

## 9. 故障排查

### 9.1 查看错误日志

```bash
# 查看后端错误日志
cd /path/to/crawlful-hub/server
npm run logs

# 查看系统错误日志
tail -f /var/log/syslog
```

### 9.2 检查服务状态

```bash
# 检查后端服务状态
npm run status

# 检查数据库服务状态
sudo systemctl status mysql

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

# 检查 NGINX 服务状态
sudo systemctl status nginx
```

### 9.3 测试 API 接口

```bash
# 测试 API 接口
curl -X GET http://localhost:3000/api/v1/system/info
```

### 9.4 数据库连接测试

```bash
# 测试数据库连接
mysql -u root -p -e "SELECT 1;"
```

### 9.5 Redis 连接测试

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

## 10. 联系支持

如果您在部署过程中遇到任何问题，可以通过以下方式联系支持：

- **在线客服**：系统右下角的在线客服按钮
- **邮件支持**：support@crawlful.com
- **电话支持**：400-123-4567
- **技术支持**：tech@crawlful.com

---

本指南会定期更新，以反映系统的最新部署和配置要求。