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. 准备配置文件

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

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

必须配置的关键参数:

# 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. 执行部署

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

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

3. 验证部署

# 检查服务状态
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 检查

---

📊 监控与维护

启用监控（可选）

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

监控服务地址：

• Prometheus: http://localhost:9090
• Grafana: http://localhost:3001 (默认用户名/密码: admin/admin)

日志管理

# 查看实时日志
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 个文件

数据备份

# 备份 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 命令监控资源使用：

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

# 查看特定容器
docker stats ai_agent_prod

---

🔍 故障排查

常见问题

1. 服务无法启动

检查日志:

docker-compose -f docker-compose.prod.yml logs agent

常见原因:

• 环境变量未配置或配置错误
• 端口被占用
• 依赖服务未启动

2. API 调用失败

检查步骤:

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

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

3. Redis 连接失败

检查 Redis 容器:

docker exec ai_redis_prod redis-cli -a YOUR_PASSWORD ping

4. 内存不足

解决方案:

• 增加 Docker 内存限制
• 减少并发数
• 优化模型调用

服务重启

# 重启所有服务
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

完全重置

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

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

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

---

🔄 升级策略

滚动升级（零停机）

# 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

蓝绿部署

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

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

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

回滚

# 回滚到上一个版本
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. 文件权限:

   chmod 600 .env.production
   

3. 不要提交敏感信息:

   # .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