# 智能客服系统 - 部署指南

## 🚀 快速部署

### 前提条件
- Docker 20.10+
- Docker Compose 2.0+
- Node.js 18+ (仅开发需要)
- Go 1.21+ (仅开发需要)

### 一键启动
```bash
# 克隆项目
git clone https://giter.top/openclaw/smart-customer-service.git
cd smart-customer-service

# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

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

### 访问地址
- **前端应用**: http://localhost:3000
- **后端API**: http://localhost:8080
- **数据库管理**: http://localhost:8082 (Adminer)
- **WebSocket**: ws://localhost:8081

## 📦 服务说明

### 1. 数据库服务 (PostgreSQL)
- 端口: 5432
- 数据库: customer_service
- 用户名: postgres
- 密码: postgres
- 数据卷: postgres_data

### 2. 缓存服务 (Redis)
- 端口: 6379
- 数据卷: redis_data

### 3. 后端服务 (Golang)
- API端口: 8080
- WebSocket端口: 8081
- 环境变量: 见 `.env.example`

### 4. 前端服务 (React)
- 端口: 3000
- 构建工具: Vite

## 🔧 环境配置

### 后端环境变量
创建 `.env` 文件：
```bash
# 服务器配置
SERVER_PORT=8080
SERVER_MODE=debug

# 数据库配置
DB_HOST=postgres
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=customer_service
DB_SSL_MODE=disable

# Redis配置
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# JWT配置
JWT_SECRET=your-secret-key-change-in-production
JWT_EXPIRATION=86400

# AI配置
AI_PROVIDER=openai
AI_API_KEY=your-openai-api-key
AI_MODEL=gpt-3.5-turbo
AI_BASE_URL=https://api.openai.com/v1
AI_MAX_TOKENS=1000
AI_TEMPERATURE=0.7

# WebSocket配置
WS_PORT=8081
WS_PATH=/ws
```

### 前端环境变量
创建 `frontend/.env` 文件：
```bash
VITE_API_URL=http://localhost:8080
VITE_WS_URL=ws://localhost:8081
```

## 🐳 Docker 构建

### 生产环境构建
```bash
# 构建所有镜像
docker-compose -f docker-compose.prod.yml build

# 启动生产环境
docker-compose -f docker-compose.prod.yml up -d
```

### 开发环境构建
```bash
# 使用开发配置
docker-compose build

# 启动开发环境（热重载）
docker-compose up
```

## 📊 数据库管理

### 初始化数据库
```bash
# 进入数据库容器
docker-compose exec postgres psql -U postgres -d customer_service

# 运行迁移脚本
docker-compose exec postgres psql -U postgres -d customer_service -f /docker-entrypoint-initdb.d/001_init_schema.sql
```

### 备份数据库
```bash
# 备份
docker-compose exec postgres pg_dump -U postgres customer_service > backup_$(date +%Y%m%d).sql

# 恢复
docker-compose exec -T postgres psql -U postgres -d customer_service < backup.sql
```

## 🔐 安全配置

### 1. 修改默认密码
```bash
# 修改数据库密码
docker-compose exec postgres psql -U postgres -c "ALTER USER postgres WITH PASSWORD 'new-strong-password';"

# 更新环境变量
sed -i 's/DB_PASSWORD=.*/DB_PASSWORD=new-strong-password/' .env
```

### 2. 生成JWT密钥
```bash
# 生成随机密钥
openssl rand -base64 32

# 更新环境变量
sed -i 's/JWT_SECRET=.*/JWT_SECRET=generated-secret-key/' .env
```

### 3. 启用HTTPS
```nginx
# nginx配置示例
server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://frontend:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    location /api {
        proxy_pass http://backend:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    location /ws {
        proxy_pass http://backend:8081;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

## 📈 监控和日志

### 查看日志
```bash
# 查看所有服务日志
docker-compose logs

# 实时查看后端日志
docker-compose logs -f backend

# 查看特定时间段的日志
docker-compose logs --since 1h backend
```

### 健康检查
```bash
# API健康检查
curl http://localhost:8080/health

# 数据库健康检查
docker-compose exec postgres pg_isready -U postgres

# Redis健康检查
docker-compose exec redis redis-cli ping
```

## 🔄 更新和升级

### 更新代码
```bash
# 拉取最新代码
git pull origin main

# 重新构建服务
docker-compose build

# 重启服务
docker-compose up -d
```

### 数据库迁移
```bash
# 创建新的迁移文件
cat > backend/migrations/002_new_feature.sql << 'EOF'
-- 新功能迁移脚本
ALTER TABLE users ADD COLUMN new_column VARCHAR(100);
EOF

# 应用迁移
docker-compose exec postgres psql -U postgres -d customer_service -f /docker-entrypoint-initdb.d/002_new_feature.sql
```

## 🚨 故障排除

### 常见问题

#### 1. 端口冲突
```bash
# 检查端口占用
sudo lsof -i :3000
sudo lsof -i :8080

# 修改docker-compose.yml中的端口映射
```

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

# 检查数据库日志
docker-compose logs postgres

# 手动测试连接
docker-compose exec postgres psql -U postgres -c "\l"
```

#### 3. 内存不足
```bash
# 查看容器资源使用
docker stats

# 限制容器内存
# 在docker-compose.yml中添加：
# services:
#   backend:
#     mem_limit: 512m
```

#### 4. 构建失败
```bash
# 清理Docker缓存
docker system prune -a

# 重新构建
docker-compose build --no-cache
```

## 📞 支持

### 获取帮助
- **GitHub Issues**: https://giter.top/openclaw/smart-customer-service/issues
- **文档**: 查看项目根目录的README.md和PROJECT_PLAN.md

### 紧急恢复
```bash
# 停止所有服务
docker-compose down

# 删除所有数据（谨慎操作！）
docker-compose down -v

# 重新启动
docker-compose up -d
```

---

**最后更新**: 2026-02-27  
**维护者**: 小弟 (大哥的AI助手)  
**仓库**: https://giter.top/openclaw/smart-customer-service