开发环境部署
目录
简介
本文档提供AgentChat项目的本地开发环境部署指南，涵盖两种主要部署方式：基于Docker的容器化部署和基于脚本的直接运行部署。文档详细说明了各服务的配置参数、依赖关系、端口映射和环境变量设置，并提供常见问题的解决方案。
容器化部署方案
AgentChat项目提供了完整的Docker Compose配置，用于在隔离环境中快速启动所有服务。该方案通过docker-compose.yml文件定义了MySQL、Redis、后端API和前端服务的配置。
图示来源
本节来源
服务配置详解
MySQL服务
MySQL服务作为项目的主要数据存储，配置如下：
- 容器名称: agentchat-mysql
- 端口映射: 3306:3306 (主机:容器)
- 环境变量:
- MYSQL_ROOT_PASSWORD: 123456
- MYSQL_DATABASE: agentchat
- MYSQL_USER: agentchat_user
- MYSQL_PASSWORD: 123456
- 数据卷: mysql_data (持久化存储)
- 健康检查: 使用mysqladmin ping命令检测服务状态
Redis服务
Redis服务提供缓存功能，配置如下：
- 容器名称: agentchat-redis
- 端口映射: 6379:6379 (主机:容器)
- 环境变量: TZ: Asia/Shanghai
- 数据卷: redis_data (持久化存储)
- 健康检查: 使用redis-cli ping命令检测服务状态
后端API服务
后端服务基于FastAPI框架，配置如下：
- 容器名称: agentchat-backend
- 端口映射: 7860:7860 (主机:容器)
- 环境变量:
- DATABASE_URL: mysql://agentchat_user:123456@mysql:3306/agentchat
- REDIS_URL: redis://redis:6379/0
- APP_ENV: development
- JWT_SECRET_KEY: your-super-secret-jwt-key-change-in-production
- OPENAI_API_KEY: $
- 依赖关系: 依赖MySQL和Redis服务，且需等待它们健康后才启动
- 健康检查: 通过curl访问http://localhost:7860/health接口检测服务状态
前端服务
前端服务基于Vue框架，配置如下：
- 容器名称: agentchat-frontend
- 端口映射: 8090:8090 (主机:容器)
- 环境变量:
- NODE_ENV: development
- VITE_API_BASE_URL: http://localhost:7860
- 依赖关系: 依赖后端服务
- 健康检查: 通过curl访问http://localhost:8090检测服务状态
本节来源
非容器化部署方案
对于需要频繁调试的开发者，项目提供了scripts/start.py脚本，可直接在本地环境中启动服务。
脚本执行流程
图示来源
本节来源
实现逻辑分析
start.py脚本的主要功能包括：
- 路径设置: 自动识别项目根目录、后端目录和前端目录
- 依赖安装: 在项目根目录查找
request*.txt或requirements.txt文件并安装Python依赖 - 并发启动: 使用subprocess.Popen同时启动后端和前端服务
- 进程管理: 维护进程列表，支持通过Ctrl+C优雅关闭所有服务
后端服务通过uvicorn启动，监听7860端口；前端服务通过npm run dev启动，监听8090端口。脚本会实时显示两个服务的日志输出。
本节来源
部署方式对比
| 特性 | 容器化部署 | 非容器化部署 |
|---|---|---|
| 环境隔离 | 高，完全隔离 | 低，依赖本地环境 |
| 依赖管理 | 内置，自动安装 | 需手动管理 |
| 启动速度 | 较慢，需构建镜像 | 快，直接运行 |
| 调试便利性 | 较差，需进入容器 | 好，直接修改代码 |
| 端口冲突 | 少，独立网络 | 可能发生 |
| 适用场景 | 生产环境、团队协作 | 本地开发、调试 |
本节来源
常见问题排查
端口冲突
当指定端口已被占用时，服务无法启动。解决方案：
- 使用
netstat -ano | findstr :端口号（Windows）或lsof -i :端口号（Linux/Mac）查找占用进程 - 终止占用进程或修改docker-compose.yml中的端口映射
依赖安装失败
可能原因及解决方案：
- 缺少requirements.txt: 确保项目根目录存在依赖文件
- 网络问题: 配置pip镜像源或使用国内镜像
- 权限问题: 以管理员权限运行安装命令
服务启动超时
特别是MySQL和后端服务可能因初始化耗时较长而超时：
- 增加healthcheck的retries和timeout值
- 检查数据库初始化脚本是否过于复杂
- 确保有足够的系统资源
环境变量未设置
对于AI模型相关的API密钥，需在运行前设置：
bash
export OPENAI_API_KEY=your_key
export ANTHROPIC_API_KEY=your_key本节来源
服务验证方法
访问前端界面
启动成功后，可通过浏览器访问http://localhost:8090查看前端界面是否正常加载。
调用健康检查接口
各服务提供了健康检查接口，可用于验证服务状态：
- 前端: http://localhost:8090/health (返回"healthy")
- 后端: http://localhost:7860/health (返回{"status": "OK"})
- MySQL: 使用mysql客户端连接3306端口
- Redis: 使用redis-cli ping命令
API功能测试
通过前端界面或Postman等工具调用主要API接口，验证数据交互是否正常。
本节来源