assistant/DEPLOYMENT.md

# B2B Shopping AI Assistant - 生产环境部署指南

## 📋 目录

- [部署前准备](#部署前准备)
- [快速部署](#快速部署)
- [详细配置](#详细配置)
- [监控与维护](#监控与维护)
- [故障排查](#故障排查)
- [升级策略](#升级策略)

---

## 🚀 部署前准备

### 系统要求

- **操作系统**: Linux (推荐 Ubuntu 20.04+)
- **Docker**: 20.10+
- **Docker Compose**: 2.0+
- **CPU**: 4 核心以上
- **内存**: 8GB 以上
- **磁盘**: 50GB 以上

### 网络要求

- **开放端口**:
  - `8000`: Agent 服务
  - `8001-8004`: MCP 服务
  - `3000-3001`: Chatwoot (如果部署在同一服务器)
  - `9090`: Prometheus (可选)
  - `3001`: Grafana (可选)

### 外部依赖

1. **Chatwoot**: 需要提前部署并配置好
2. **Strapi CMS**: 用于 FAQ 和知识库管理
3. **Hyperf API**: 后端业务 API
4. **Redis**: 使用 Docker Compose 内置，或外部 Redis 实例

---

## ⚡ 快速部署

### 1. 准备配置文件

```bash
# 复制环境变量模板
cp .env.production.example .env.production

# 编辑配置文件
vim .env.production
```

**必须配置的关键参数**:

```env
# AI 模型
ZHIPU_API_KEY=your_actual_api_key

# Redis 密码（必须修改）
REDIS_PASSWORD=your_strong_password_here

# Chatwoot
CHATWOOT_API_URL=https://your-chatwoot.com
CHATWOOT_API_TOKEN=your_chatwoot_token
CHATWOOT_WEBHOOK_SECRET=your_webhook_secret

# API 地址
HYPERF_API_URL=https://api.yourdomain.com
MALL_API_URL=https://apicn.yourdomain.com
STRAPI_API_URL=https://cms.yourdomain.com
```

### 2. 执行部署

```bash
# 使用部署脚本（推荐）
./scripts/deploy-production.sh

# 或手动部署
docker-compose -f docker-compose.prod.yml up -d
```

### 3. 验证部署

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

# 健康检查
curl http://localhost:8000/health

# 查看日志
docker-compose -f docker-compose.prod.yml logs -f agent
```

---

## 🔧 详细配置

### 生产环境与开发环境差异

| 配置项 | 开发环境 | 生产环境 |
|--------|---------|---------|
| 日志级别 | INFO | WARNING |
| 代码挂载 | 是（支持热更新） | 否（使用镜像） |
| 资源限制 | 无 | 有限制 |
| 健康检查 | 基础 | 完整 |
| 日志轮转 | 无 | 有（10MB x 3） |
| 重启策略 | unless-stopped | always |
| Redis 密码 | 无 | 必须 |

### 资源配置

生产环境默认资源配置（可在 `docker-compose.prod.yml` 中调整）:

| 服务 | CPU 限制 | 内存限制 | CPU 预留 | 内存预留 |
|------|---------|---------|---------|---------|
| Agent | 2 核 | 2GB | 0.5 核 | 512MB |
| MCP 服务 | 0.5 核 | 512MB | 0.25 核 | 256MB |

### 健康检查

所有服务都配置了健康检查：

- **Agent**: 每 30 秒检查 `/health` 端点
- **MCP 服务**: 每 30 秒检查 `/health` 端点
- **Redis**: 每 10 秒 ping 检查

---

## 📊 监控与维护

### 启用监控（可选）

```bash
# 启动 Prometheus + Grafana
docker-compose -f docker-compose.prod.yml --profile monitoring up -d
```

监控服务地址：
- **Prometheus**: http://localhost:9090
- **Grafana**: http://localhost:3001 (默认用户名/密码: admin/admin)

### 日志管理

```bash
# 查看实时日志
docker-compose -f docker-compose.prod.yml logs -f

# 查看特定服务日志
docker-compose -f docker-compose.prod.yml logs -f agent

# 查看最近 100 行日志
docker-compose -f docker-compose.prod.yml logs --tail=100 agent

# 导出日志
docker-compose -f docker-compose.prod.yml logs agent > agent.log
```

日志文件位置：
- **Agent 日志**: `agent_logs_prod` volume
- **日志轮转**: 每个日志文件最大 10MB，保留 3 个文件

### 数据备份

```bash
# 备份 Redis 数据
docker run --rm \
  -v ai_redis_data_prod:/data \
  -v $(pwd)/backups:/backup \
  alpine tar czf /backup/redis-$(date +%Y%m%d).tar.gz /data

# 备份 Grafana 配置
docker run --rm \
  -v ai_grafana_data:/data \
  -v $(pwd)/backups:/backup \
  alpine tar czf /backup/grafana-$(date +%Y%m%d).tar.gz /data
```

### 性能监控

使用 Docker 命令监控资源使用：

```bash
# 查看容器资源使用情况
docker stats

# 查看特定容器
docker stats ai_agent_prod
```

---

## 🔍 故障排查

### 常见问题

#### 1. 服务无法启动

**检查日志**:
```bash
docker-compose -f docker-compose.prod.yml logs agent
```

**常见原因**:
- 环境变量未配置或配置错误
- 端口被占用
- 依赖服务未启动

#### 2. API 调用失败

**检查步骤**:
1. 验证 API Token 是否正确
2. 检查网络连接
3. 查看 API 服务状态

```bash
# 测试 API 连接
docker exec ai_agent_prod curl https://api.yourdomain.com/health
```

#### 3. Redis 连接失败

**检查 Redis 容器**:
```bash
docker exec ai_redis_prod redis-cli -a YOUR_PASSWORD ping
```

#### 4. 内存不足

**解决方案**:
- 增加 Docker 内存限制
- 减少并发数
- 优化模型调用

### 服务重启

```bash
# 重启所有服务
docker-compose -f docker-compose.prod.yml restart

# 重启特定服务
docker-compose -f docker-compose.prod.yml restart agent

# 强制重新创建（更新环境变量后）
docker-compose -f docker-compose.prod.yml up -d --force-recreate agent
```

### 完全重置

⚠️ **警告**: 此操作会删除所有容器和数据卷

```bash
# 停止并删除所有容器
docker-compose -f docker-compose.prod.yml down -v

# 重新部署
./scripts/deploy-production.sh
```

---

## 🔄 升级策略

### 滚动升级（零停机）

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

# 2. 构建新镜像
docker-compose -f docker-compose.prod.yml build

# 3. 逐个重启服务
docker-compose -f docker-compose.prod.yml up -d --no-deps agent

# 4. 验证新版本
curl http://localhost:8000/health
```

### 蓝绿部署

```bash
# 1. 部署新版本到不同端口
docker-compose -f docker-compose.prod.yml up -d

# 2. 切换流量（修改 Nginx 配置）

# 3. 停止旧版本
docker-compose -f docker-compose.prod.yml down
```

### 回滚

```bash
# 回滚到上一个版本
git checkout PREVIOUS_VERSION_TAG

# 重新构建
docker-compose -f docker-compose.prod.yml build

# 重启服务
docker-compose -f docker-compose.prod.yml up -d
```

---

## 🔐 安全建议

### 环境变量管理

1. **使用密钥管理服务**:
   - AWS Secrets Manager
   - HashiCorp Vault
   - Azure Key Vault

2. **文件权限**:
   ```bash
   chmod 600 .env.production
   ```

3. **不要提交敏感信息**:
   ```bash
   # .gitignore
   .env.production
   .env
   ```

### 网络安全

1. **使用防火墙限制端口访问**
2. **配置 HTTPS/TLS**
3. **使用 VPN 或专线连接服务**
4. **定期更新 Docker 镜像**

### API 安全

1. **定期轮换 API Token**
2. **限制 API Token 权限**
3. **监控异常调用**
4. **设置速率限制**

---

## 📝 部署检查清单

部署前确认：

- [ ] 所有环境变量已配置
- [ ] Redis 密码已设置
- [ ] API Token 已验证
- [ ] 端口未被占用
- [ ] DNS 解析已配置
- [ ] SSL 证书已安装
- [ ] 监控已配置
- [ ] 备份策略已制定
- [ ] 回滚方案已准备

部署后验证：

- [ ] 所有容器正常运行
- [ ] 健康检查通过
- [ ] API 调用成功
- [ ] 日志正常输出
- [ ] 资源使用正常
- [ ] 监控数据正常

---

## 🆘 获取帮助

- **文档**: `/docs` 目录
- **Issues**: GitHub Issues
- **日志**: `docker-compose logs`
- **监控**: Grafana Dashboard (如果启用)

---

**最后更新**: 2026-01-26