jiebanke/docs/DEPLOYMENT.md

# 📦 部署指南 - 文件同步说明

## 📋 当前部署范围
本文档说明了结伴客项目的文件同步流程。当前部署仅涉及文件同步操作，不包括自动构建、环境配置或服务重启等后续步骤。

注意：本文档适用于需要了解当前部署流程的开发人员和运维人员。请知悉当前部署流程的限制和要求。

## 🛠️ 环境要求

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

### 软件要求
- **Node.js**: 16.x 或 18.x
- **MySQL**: 8.0+
- **Redis**: 6.0+ (可选)
- **Docker**: 20.10+ (可选)
- **npm**: 8.x+

## 🏗️ 开发环境部署

### 1. 克隆项目
```bash
git clone <repository-url>
cd jiebanke
```

### 2. 安装依赖
```bash
# 安装后端依赖
cd backend
npm install

# 安装前端依赖
cd ../admin-system
npm install

cd ../mini-program
npm install

cd ../website
npm install
```

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

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

### 4. 启动数据库
```bash
# 使用Docker启动MySQL
cd backend
docker-compose up -d mysql

# 或者使用本地MySQL
mysql -u root -p < scripts/init-database.sql
```

### 5. 启动应用
```bash
# 启动后端服务
cd backend
npm run dev

# 启动后台管理系统 (新终端)
cd admin-system
npm run dev

# 启动官方网站 (新终端)  
cd website
npm run dev
```

### 6. 验证部署
- 后端API: https://webapi.jiebanke.com/api/v1/health
- 后台管理: https://admin.jiebanke.com
- 官方网站: https://www.jiebanke.com

## 🧪 测试环境部署

### 1. 服务器准备
```bash
# 登录测试服务器
ssh user@test-server

# 创建项目目录
mkdir -p /opt/jiebanke
cd /opt/jiebanke
```

### 2. 部署脚本
```bash
#!/bin/bash
# deploy-test.sh

# 拉取最新代码
git pull origin develop

# 安装依赖
cd backend && npm install --production
cd ../admin-system && npm install --production && npm run build
cd ../website && npm install --production && npm run build

# 重启服务
pm2 restart all
```

### 3. 环境配置
```bash
# 测试环境变量
cat > /opt/jiebanke/backend/.env << EOF
NODE_ENV=test
DB_HOST=192.168.0.240
DB_PORT=3306
DB_USER=root
DB_PASSWORD=aiotAiot123!
DB_DATABASE=jiebandata_test
JWT_SECRET=your-test-jwt-secret
EOF
```

### 4. 进程管理
```bash
# 使用PM2管理进程
npm install -g pm2

# 启动服务
pm2 start ecosystem.config.js --env test

# 查看状态
pm2 status
```

## 🚀 生产环境部署

### 1. 服务器准备
```bash
# 购买云服务器 (阿里云/腾讯云/AWS)
# 配置安全组: 开放80, 443, 3000, 3306, 6379端口

# 服务器初始化
apt update && apt upgrade -y
apt install -y nginx mysql-server redis-server
```

### 2. 数据库部署
```bash
# 安装MySQL
apt install -y mysql-server

# 安全配置
mysql_secure_installation

# 创建生产数据库
mysql -u root -p -e "CREATE DATABASE jiebandata CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 导入数据
mysql -u root -p jiebandata < scripts/prod-database.sql
```

### 3. 应用部署
```bash
# 创建部署用户
adduser deploy
usermod -aG sudo deploy

# 项目目录
mkdir -p /home/deploy/jiebanke
chown deploy:deploy /home/deploy/jiebanke
```

### 4. 自动化部署脚本
```bash
#!/bin/bash
# deploy-prod.sh

set -e

# 变量配置
APP_NAME="jiebanke"
APP_DIR="/home/deploy/jiebanke"
BRANCH="main"

echo "🚀 开始部署 $APP_NAME..."

# 拉取代码
echo "📦 拉取最新代码..."
cd $APP_DIR
git fetch origin
git checkout $BRANCH
git reset --hard origin/$BRANCH

# 安装依赖
echo "🔧 安装依赖..."
cd backend && npm install --production
cd ../admin-system && npm install --production && npm run build
cd ../website && npm install --production && npm run build

# 数据库迁移
echo "🗄️ 执行数据库迁移..."
cd backend
npm run db:migrate

# 重启服务
echo "🔄 重启服务..."
pm2 reload ecosystem.config.js --env production

# 清理
echo "🧹 清理临时文件..."
npm cache clean --force

echo "✅ 部署完成!"
echo "🌐 应用地址: https://your-domain.com"
```

### 5. Nginx 配置
```nginx
# /etc/nginx/sites-available/jiebanke
server {
    listen 80;
    server_name your-domain.com;
    
    # 反向代理到后端API
    location /api {
        proxy_pass http://backend-service:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
    
    # 静态资源服务
    location / {
        root /home/deploy/jiebanke/admin-system/dist;
        index index.html;
        try_files $uri $uri/ /index.html;
    }
}
```

### 6. SSL证书配置
```bash
# 安装Certbot
apt install -y certbot python3-certbot-nginx

# 获取SSL证书
certbot --nginx -d your-domain.com

# 自动续期
certbot renew --dry-run
```

## 📊 监控与日志

### 应用监控
```bash
# 安装PM2监控
pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 30

# 监控面板
pm2 monitor
```

### 日志管理
```bash
# 查看实时日志
pm2 logs

# 查看特定应用日志
pm2 logs backend

# 日志文件位置
/root/.pm2/logs/
/var/log/nginx/
/var/log/mysql/
```

### 性能监控
```bash
# 安装监控工具
apt install -y htop iotop nmon

# 监控系统资源
top
htop

# 监控磁盘使用
df -h
```

## 🔒 安全配置

### 防火墙配置
```bash
# 配置UFW防火墙
apt install -y ufw
ufw allow ssh
ufw allow http
ufw allow https
ufw enable
```

### 数据库安全
```bash
# 修改MySQL默认端口
vim /etc/mysql/mysql.conf.d/mysqld.cnf
# port = 3307

# 创建应用专用用户
mysql -u root -p -e "
CREATE USER 'appuser'@'%' IDENTIFIED BY 'strongpassword';
GRANT SELECT, INSERT, UPDATE, DELETE ON jiebandata.* TO 'appuser'@'%';
FLUSH PRIVILEGES;
"
```

### SSH安全
```bash
# 禁用root登录
vim /etc/ssh/sshd_config
# PermitRootLogin no

# 使用密钥认证
# PasswordAuthentication no

# 重启SSH
systemctl restart sshd
```

## 📦 容器化部署

### Docker Compose
```yaml
# docker-compose.prod.yml
version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DB_HOST=mysql
      - DB_PORT=3306
      - DB_USER=root
      - DB_PASSWORD=rootpassword
    depends_on:
      - mysql

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=rootpassword
      - MYSQL_DATABASE=jiebandata
    volumes:
      - mysql_data:/var/lib/mysql
    ports:
      - "3306:3306"

volumes:
  mysql_data:
```

### Kubernetes部署
```yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: jiebanke-backend
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: app
        image: jiebanke-backend:latest
        ports:
        - containerPort: 3000
        env:
        - name: NODE_ENV
          value: "production"
```

## 🚨 故障排除

### 常见问题

1. **端口占用**
```bash
# 查找占用端口的进程
lsof -i :3000

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

2. **权限问题**
```bash
# 修改文件权限
chown -R deploy:deploy /home/deploy/jiebanke
chmod -R 755 /home/deploy/jiebanke
```

3. **数据库连接失败**
```bash
# 检查MySQL服务
systemctl status mysql

# 检查防火墙
ufw status
```

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

# 查看应用日志
tail -f /root/.pm2/logs/backend-error.log

# 数据库日志
tail -f /var/log/mysql/error.log
```

## 📞 支持与维护

### 紧急联系人
- **运维团队**: ops@jiebanke.com
- **开发团队**: dev@jiebanke.com  
- **值班电话**: +86-138-0013-8000

### 维护窗口
- **常规维护**: 每周四凌晨 2:00-4:00
- **紧急维护**: 随时响应
- **系统监控**: 7x24小时

### 备份策略
```bash
# 数据库备份
mysqldump -u root -p jiebandata > backup-$(date +%Y%m%d).sql

# 文件备份
tar -czf backup-$(date +%Y%m%d).tar.gz /home/deploy/jiebanke

# 上传到云存储
rclone copy backup-* remote:backups/
```

---
*最后更新: 2024年* 📅

# 结伴客项目部署指南

## 概述

n g本文档详细说明了如何将结伴客项目部署到生产环境。项目包含三个主要模块：
1. 后端服务 (backend)
2. 后台管理系统 (admin-system)
3. 官方网站 (website)

注意：微信小程序不需要部署到远程服务器，需要使用微信开发者工具进行构建和上传。

## 部署环境要求

### 服务器要求
- CentOS 7+ (推荐 CentOS 8)
- Node.js 16.x+
- MySQL 8.0+
- Nginx 1.18+
- Docker 和 Docker Compose (可选，用于容器化部署)

### 本地开发环境要求
- Node.js 16.x+
- SSH 客户端
- rsync (用于文件同步)

## 自动部署脚本

项目提供了自动部署脚本，支持 Linux/Mac 和 Windows 系统。

### Linux/Mac 部署脚本

脚本位置：`scripts/deploy.sh`

使用方法：
```bash
# 进入脚本目录
cd scripts

# 给脚本添加执行权限
chmod +x deploy.sh

# 部署所有模块
./deploy.sh all

# 部署指定模块
./deploy.sh backend      # 部署后端服务
./deploy.sh admin        # 部署后台管理系统
./deploy.sh website      # 部署官方网站
./deploy.sh mini-program # 构建微信小程序
```

### Windows PowerShell 部署脚本

脚本位置：`scripts/deploy.ps1`

使用方法：
```powershell
# 进入脚本目录
cd scripts

# 部署所有模块
.\deploy.ps1 all

# 部署指定模块
.\deploy.ps1 backend      # 部署后端服务
.\deploy.ps1 admin        # 部署后台管理系统
.\deploy.ps1 website      # 部署官方网站
```

## 手动部署

### 后端服务部署

1. 构建项目：
```bash
cd backend
npm run build
```

2. 同步文件到服务器：
```bash
rsync -avz --delete \
  --exclude node_modules \
  --exclude .git \
  --exclude logs \
  ./ root@1.13.156.49:/data/nodejs/jiebanke/
```

3. 在服务器上安装依赖：
```bash
ssh root@1.13.156.49
cd /data/nodejs/jiebanke
npm install --production
```

4. 重启服务：
```bash
# 使用 PM2 管理服务（推荐）
pm2 restart jiebanke-backend

# 或使用 systemd
systemctl restart jiebanke-backend
```

### 后台管理系统部署

1. 构建项目：
```bash
cd admin-system
npm run build
```

2. 同步文件到服务器：
```bash
rsync -avz --delete \
  --exclude node_modules \
  --exclude .git \
  --exclude dist \
  ./ root@1.13.156.49:/data/vue/jiebanke/
```

3. 在服务器上安装依赖：
```bash
ssh root@1.13.156.49
cd /data/vue/jiebanke
npm install --production
```

### 官方网站部署

1. 同步文件到服务器：
```bash
rsync -avz --delete \
  --exclude node_modules \
  --exclude .git \
  ./website/ root@1.13.156.49:/data/website/jiebanke/
```

2. 配置 Nginx 服务器指向该目录。

### 微信小程序构建

微信小程序需要使用微信开发者工具进行构建和上传：
1. 打开微信开发者工具
2. 导入 `mini-program` 目录
3. 点击"上传"按钮
4. 在微信公众平台提交审核

## 容器化部署

项目支持使用 Docker 进行容器化部署。

### 使用 docker-compose 部署

```bash
# 构建并启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

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

### 单独构建镜像

每个模块都可以单独构建 Docker 镜像：

```bash
# 后端服务
cd backend
docker build -t jiebanke/backend .

# 后台管理系统
cd admin-system
docker build -t jiebanke/admin .

# 官方网站
cd website
docker build -t jiebanke/website .
```

## 部署目录结构

远程服务器 CentOS (IP: 1.13.156.49) 上各项目的部署目录如下：

```
/
├── data/
│   ├── nodejs/
│   │   └── jiebanke/     # 后端服务部署目录
│   ├── vue/
│   │   └── jiebanke/     # 后台管理系统部署目录
│   └── website/
│       └── jiebanke/     # 官方网站部署目录
```

## 环境变量配置

每个模块都需要配置相应的环境变量：

### 后端服务
创建 `.env` 文件：
```env
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=jiebanke
DB_PASSWORD=your_password
DB_NAME=jiebanke

# JWT 密钥
JWT_SECRET=your_jwt_secret_key

# 其他配置...
```

### 后台管理系统
创建 `.env.production` 文件：
```env
VITE_APP_TITLE=结伴客后台管理系统
VITE_API_BASE_URL=https://api.jiebanke.com
VITE_APP_VERSION=v1.0.0
```

## 常见问题和解决方案

### SSH 连接问题
确保本地 SSH 公钥已添加到远程服务器的 `~/.ssh/authorized_keys` 文件中。

### 权限问题
确保部署脚本有执行权限：
```bash
chmod +x scripts/deploy.sh
```

### 文件同步问题
如果 rsync 命令执行失败，请检查：
1. 本地是否安装了 rsync
2. 远程服务器 SSH 连接是否正常
3. 目标目录权限是否正确

## 监控和日志

### 后端服务日志
```bash
# 使用 PM2 查看日志
pm2 logs jiebanke-backend

# 或查看日志文件
tail -f /var/log/jiebanke/backend.log
```

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

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

## 回滚方案

如果部署出现问题，可以通过以下方式回滚：

1. 使用 Git 版本回滚：
```bash
git checkout v1.0.0  # 回滚到指定版本
```

2. 使用 Docker 镜像回滚：
```bash
docker-compose down
docker rmi jiebanke/backend:latest
docker pull jiebanke/backend:v1.0.0
docker-compose up -d
```

## 性能优化建议

1. 使用 Nginx 反向代理和缓存
2. 启用 Gzip 压缩
3. 使用 CDN 加速静态资源
4. 数据库查询优化
5. 使用 Redis 缓存热点数据