jiebanke/docs/部署指南.md

# 📦 结伴客系统部署指南

## 📋 部署概述

本文档详细说明了结伴客项目的完整部署流程，包括开发环境、测试环境和生产环境的部署配置。项目采用容器化部署方式，支持快速部署和弹性扩容。

## 🛠️ 环境要求

### 系统要求
- **操作系统**：Ubuntu 20.04+ / CentOS 7+ / macOS 10.15+
- **CPU**：最低2核，推荐4核+
- **内存**：最低4GB，推荐8GB+
- **存储**：最低20GB可用空间，推荐50GB+
- **网络**：稳定的互联网连接，带宽10Mbps+

### 软件依赖

#### 基础软件
- **Node.js**：16.x 或 18.x LTS版本
- **npm**：8.x+ 或 yarn 1.22+
- **Git**：2.30+
- **Docker**：20.10+
- **Docker Compose**：2.0+

#### 数据库
- **MySQL**：8.0+
- **Redis**：6.0+（可选，用于缓存）

#### 其他工具
- **Nginx**：1.18+（用于反向代理）
- **PM2**：5.0+（用于进程管理）
- **微信开发者工具**：最新版本

## 🚀 快速部署

### 一键部署脚本

```bash
#!/bin/bash
# 快速部署脚本 - deploy.sh

echo "开始部署结伴客项目..."

# 1. 克隆项目
git clone https://github.com/your-org/jiebanke.git
cd jiebanke

# 2. 安装依赖
echo "安装项目依赖..."
npm install

# 3. 配置环境变量
echo "配置环境变量..."
cp .env.example .env

# 4. 初始化数据库
echo "初始化数据库..."
npm run db:migrate
npm run db:seed

# 5. 构建项目
echo "构建项目..."
npm run build

# 6. 启动服务
echo "启动服务..."
npm run start:prod

echo "部署完成！访问 http://localhost:3000"
```

### Docker一键部署

```bash
# 使用Docker Compose一键部署
docker-compose up -d

# 查看服务状态
docker-compose ps

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

## 🏗️ 开发环境部署

### 1. 环境准备

#### 安装Node.js
```bash
# 使用nvm安装Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18
```

#### 安装MySQL
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install mysql-server

# macOS
brew install mysql
brew services start mysql

# 创建数据库
mysql -u root -p
CREATE DATABASE jiebandata CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'jieban'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON jiebandata.* TO 'jieban'@'localhost';
FLUSH PRIVILEGES;
```

### 2. 项目配置

#### 克隆项目代码
```bash
git clone https://github.com/your-org/jiebanke.git
cd jiebanke
```

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

# 前端管理系统依赖
cd ../admin-system
npm install

# 小程序依赖
cd ../mini-program
npm install

# 官网依赖
cd ../website
npm install
```

#### 配置环境变量
```bash
# 复制环境变量模板
cd backend
cp .env.example .env

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

**环境变量配置示例：**
```env
# 应用配置
NODE_ENV=development
PORT=3000
APP_NAME=结伴客

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_NAME=jiebandata
DB_USER=jieban
DB_PASSWORD=password

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

# JWT配置
JWT_SECRET=your-jwt-secret-key
JWT_EXPIRES_IN=7d

# 微信小程序配置
WECHAT_APP_ID=your-wechat-app-id
WECHAT_APP_SECRET=your-wechat-app-secret

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

# 邮件配置
SMTP_HOST=smtp.qq.com
SMTP_PORT=587
SMTP_USER=your-email@qq.com
SMTP_PASS=your-email-password
```

### 3. 数据库初始化

```bash
# 运行数据库迁移
cd backend
npm run db:migrate

# 运行数据库种子文件
npm run db:seed

# 或者直接执行SQL文件
mysql -u jieban -p jiebandata < scripts/init-database.sql
```

### 4. 启动开发服务

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

# 启动前端管理系统（新终端）
cd admin-system
npm run dev

# 启动官网（新终端）
cd website
npm run dev
```

### 5. 验证部署

访问以下地址验证部署是否成功：
- 后端API：http://localhost:3000/api/health
- 管理系统：http://localhost:8080
- 官网：http://localhost:8081

## 🧪 测试环境部署

### 1. 服务器配置

#### 服务器信息
- **主机**：192.168.0.240
- **操作系统**：Ubuntu 20.04
- **用户**：deploy
- **部署路径**：/var/www/jiebanke

#### 环境变量配置
```env
NODE_ENV=testing
PORT=3000
DB_HOST=192.168.0.240
DB_PORT=3306
DB_NAME=jiebandata_test
DB_USER=jieban_test
DB_PASSWORD=test_password
```

### 2. 自动化部署脚本

```bash
#!/bin/bash
# 测试环境部署脚本 - deploy-test.sh

SERVER_HOST="192.168.0.240"
SERVER_USER="deploy"
DEPLOY_PATH="/var/www/jiebanke"

echo "开始部署到测试环境..."

# 1. 构建项目
echo "构建项目..."
npm run build

# 2. 打包文件
echo "打包部署文件..."
tar -czf jiebanke-$(date +%Y%m%d-%H%M%S).tar.gz \
  backend/ admin-system/dist/ website/dist/ \
  package.json docker-compose.yml

# 3. 上传到服务器
echo "上传文件到服务器..."
scp jiebanke-*.tar.gz $SERVER_USER@$SERVER_HOST:$DEPLOY_PATH/

# 4. 远程部署
echo "执行远程部署..."
ssh $SERVER_USER@$SERVER_HOST << 'EOF'
cd /var/www/jiebanke
tar -xzf jiebanke-*.tar.gz
docker-compose down
docker-compose up -d --build
docker-compose ps
EOF

echo "测试环境部署完成！"
```

## 🌐 生产环境部署

### 1. 服务器配置

#### 服务器信息
- **主机**：129.211.213.226
- **端口**：9527
- **操作系统**：CentOS 7
- **用户**：root
- **部署路径**：/opt/jiebanke

#### 高可用架构
```mermaid
graph TB
    A[负载均衡器 Nginx] --> B[应用服务器1]
    A --> C[应用服务器2]
    A --> D[应用服务器3]
    B --> E[MySQL主库]
    C --> E
    D --> E
    E --> F[MySQL从库1]
    E --> G[MySQL从库2]
    B --> H[Redis集群]
    C --> H
    D --> H
```

### 2. Docker容器化部署

#### Dockerfile配置
```dockerfile
# 后端服务Dockerfile
FROM node:18-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production && npm cache clean --force

FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .

EXPOSE 3000
USER node
CMD ["npm", "start"]
```

#### Docker Compose配置
```yaml
version: '3.8'

services:
  # 后端API服务
  api:
    build:
      context: ./backend
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DB_HOST=mysql
      - REDIS_HOST=redis
    depends_on:
      - mysql
      - redis
    restart: unless-stopped
    networks:
      - jiebanke-network

  # 前端管理系统
  admin:
    build:
      context: ./admin-system
      dockerfile: Dockerfile
    ports:
      - "8080:80"
    restart: unless-stopped
    networks:
      - jiebanke-network

  # MySQL数据库
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: jiebandata
      MYSQL_USER: jieban
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - mysql_data:/var/lib/mysql
      - ./scripts/init-database.sql:/docker-entrypoint-initdb.d/init.sql
    ports:
      - "3306:3306"
    restart: unless-stopped
    networks:
      - jiebanke-network

  # Redis缓存
  redis:
    image: redis:6-alpine
    command: redis-server --appendonly yes --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis_data:/data
    ports:
      - "6379:6379"
    restart: unless-stopped
    networks:
      - jiebanke-network

  # Nginx反向代理
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf
      - ./nginx/ssl:/etc/nginx/ssl
    depends_on:
      - api
      - admin
    restart: unless-stopped
    networks:
      - jiebanke-network

volumes:
  mysql_data:
  redis_data:

networks:
  jiebanke-network:
    driver: bridge
```

### 3. Nginx配置

```nginx
# nginx.conf
upstream api_backend {
    server api:3000;
}

upstream admin_backend {
    server admin:80;
}

# API服务器配置
server {
    listen 80;
    server_name api.jiebanke.com;
    
    # 重定向到HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.jiebanke.com;
    
    # SSL证书配置
    ssl_certificate /etc/nginx/ssl/api.jiebanke.com.crt;
    ssl_certificate_key /etc/nginx/ssl/api.jiebanke.com.key;
    
    # SSL安全配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;
    
    # 安全头
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";
    
    # API代理
    location /api/ {
        proxy_pass http://api_backend;
        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;
    }
    
    # 文件上传大小限制
    client_max_body_size 10M;
}

# 管理系统配置
server {
    listen 443 ssl http2;
    server_name admin.jiebanke.com;
    
    ssl_certificate /etc/nginx/ssl/admin.jiebanke.com.crt;
    ssl_certificate_key /etc/nginx/ssl/admin.jiebanke.com.key;
    
    location / {
        proxy_pass http://admin_backend;
        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;
    }
}
```

### 4. 生产环境部署脚本

```bash
#!/bin/bash
# 生产环境部署脚本 - deploy-prod.sh

set -e

PROD_SERVER="129.211.213.226"
PROD_USER="root"
DEPLOY_PATH="/opt/jiebanke"
BACKUP_PATH="/opt/backups"

echo "开始生产环境部署..."

# 1. 备份当前版本
echo "备份当前版本..."
ssh $PROD_USER@$PROD_SERVER << EOF
if [ -d "$DEPLOY_PATH" ]; then
    sudo mkdir -p $BACKUP_PATH
    sudo tar -czf $BACKUP_PATH/jiebanke-backup-$(date +%Y%m%d-%H%M%S).tar.gz -C $DEPLOY_PATH .
fi
EOF

# 2. 构建生产版本
echo "构建生产版本..."
NODE_ENV=production npm run build

# 3. 创建部署包
echo "创建部署包..."
tar -czf jiebanke-prod-$(date +%Y%m%d-%H%M%S).tar.gz \
  backend/ admin-system/dist/ website/dist/ \
  docker-compose.prod.yml nginx/ scripts/

# 4. 上传到生产服务器
echo "上传到生产服务器..."
scp jiebanke-prod-*.tar.gz $PROD_USER@$PROD_SERVER:$DEPLOY_PATH/

# 5. 执行部署
echo "执行生产部署..."
ssh $PROD_USER@$PROD_SERVER << 'EOF'
cd /opt/jiebanke
tar -xzf jiebanke-prod-*.tar.gz

# 停止旧服务
docker-compose -f docker-compose.prod.yml down

# 启动新服务
docker-compose -f docker-compose.prod.yml up -d --build

# 等待服务启动
sleep 30

# 检查服务状态
docker-compose -f docker-compose.prod.yml ps

# 健康检查
curl -f http://localhost:3000/api/health || exit 1

echo "生产环境部署成功！"
EOF

echo "部署完成！"
```

## 🔍 部署验证

### 健康检查

```bash
# API健康检查
curl -X GET http://localhost:3000/api/health

# 数据库连接检查
curl -X GET http://localhost:3000/api/health/db

# Redis连接检查
curl -X GET http://localhost:3000/api/health/redis
```

### 性能测试

```bash
# 使用Apache Bench进行压力测试
ab -n 1000 -c 10 http://localhost:3000/api/health

# 使用wrk进行性能测试
wrk -t12 -c400 -d30s http://localhost:3000/api/health
```

## 📊 监控配置

### 系统监控

#### Prometheus配置
```yaml
# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'jiebanke-api'
    static_configs:
      - targets: ['localhost:3000']
    metrics_path: '/metrics'
```

#### Grafana仪表板
- **系统指标**：CPU、内存、磁盘使用率
- **应用指标**：QPS、响应时间、错误率
- **业务指标**：用户注册量、订单量、收入

### 日志管理

#### 日志收集配置
```yaml
# filebeat.yml
filebeat.inputs:
- type: log
  enabled: true
  paths:
    - /opt/jiebanke/logs/*.log
  fields:
    service: jiebanke
    environment: production

output.elasticsearch:
  hosts: ["elasticsearch:9200"]
```

## 🚨 故障排除

### 常见问题

#### 1. 数据库连接失败
```bash
# 检查数据库服务状态
docker-compose ps mysql

# 查看数据库日志
docker-compose logs mysql

# 测试数据库连接
mysql -h localhost -u jieban -p jiebandata
```

#### 2. Redis连接失败
```bash
# 检查Redis服务状态
docker-compose ps redis

# 测试Redis连接
redis-cli -h localhost -p 6379 ping
```

#### 3. 应用启动失败
```bash
# 查看应用日志
docker-compose logs api

# 检查环境变量
docker-compose exec api env

# 进入容器调试
docker-compose exec api sh
```

### 回滚操作

```bash
#!/bin/bash
# 回滚脚本 - rollback.sh

BACKUP_FILE=$1
DEPLOY_PATH="/opt/jiebanke"

if [ -z "$BACKUP_FILE" ]; then
    echo "请指定备份文件名"
    exit 1
fi

echo "开始回滚到版本: $BACKUP_FILE"

# 停止当前服务
docker-compose down

# 恢复备份
tar -xzf /opt/backups/$BACKUP_FILE -C $DEPLOY_PATH

# 启动服务
docker-compose up -d

echo "回滚完成！"
```

## 📞 技术支持

### 联系方式
- **技术支持邮箱**：tech-support@jiebanke.com
- **紧急联系电话**：400-xxx-xxxx
- **技术文档**：https://docs.jiebanke.com

### 支持时间
- **工作日**：9:00 - 18:00
- **紧急故障**：7×24小时响应

---

*文档版本：v1.0*  
*最后更新：2025年1月*