跳到主要内容

本地开发部署

环境要求​

组件版本要求说明
Python>= 3.10推荐使用 3.11+
Node.js>= 18推荐使用 20 LTS
npm>= 9包管理工具
pip>= 23Python 包管理
Docker>= 20.10用于启动 MySQL + Milvus 基础设施
Docker Compose>= 2.0服务编排
Git>= 2.30版本控制

初始化项目​

1. 克隆代码​

git clone https://github.com/xmgfy/MGAgent.git
cd MGAgent

2. 一键初始化​

chmod +x scripts/init.sh
./scripts/init.sh

初始化脚本自动完成：

  • 安装 mgagent-backend 的 Python 依赖
  • 安装 mgagent-admin-backend 的 Python 依赖
  • 安装 mgagent-frontend 的 Node.js 依赖
  • 安装 mgagent-admin-frontend 的 Node.js 依赖
  • 创建必要的数据目录

启动基础设施​

启动 MySQL + Milvus + etcd + MinIO​

chmod +x scripts/docker-services.sh
./scripts/docker-services.sh start

服务列表：

服务端口说明
MySQL3306关系数据库
Milvus19530向量数据库
Attu8003Milvus 管理界面

验证基础设施​

# 查看状态
./scripts/docker-services.sh status

# 检查 MySQL
docker exec -it mgagent-mysql mysql -u mgagent -pmgagent_password_2024 -e "SELECT 1"

# 检查 Milvus
curl http://localhost:19530/healthz

启动应用服务​

一键启动​

# 启动所有 4 个应用服务
./scripts/start-all.sh

# 停止所有服务
./scripts/stop-all.sh

# 检查服务状态
./scripts/status.sh

启动的服务：

服务端口日志文件
Chat 后端8000mgagent-backend/backend.log
Admin 后端8001mgagent-admin-backend/admin-backend.log
Chat 前端5173mgagent-frontend/frontend.log
Admin 前端5174mgagent-admin-frontend/admin-frontend.log

访问地址​

服务地址
Chat 前端http://localhost:5173
Admin 前端http://localhost:5174
Chat APIhttp://localhost:8000
Admin APIhttp://localhost:8001
Attuhttp://localhost:8003

手动启动（可选）​

启动 Chat 后端​

cd mgagent-backend
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

启动 Admin 后端​

cd mgagent-admin-backend
uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload

启动 Chat 前端​

cd mgagent-frontend
npm run dev

启动 Admin 前端​

cd mgagent-admin-frontend
npm run dev -- --port 5174

本地 Embedding 模型部署（可选）​

如需使用本地 Embedding 模型替代云端 API：

cd mgagent-admin-backend

# 安装依赖
pip install sentence-transformers

# 下载模型
python scripts/download_local_models.py --list          # 查看可用模型
python scripts/download_local_models.py --model bge-small-zh   # 下载

然后在 Admin 后台 → 模型管理 → Embedding 模型 中启用。

可用模型列表​

模型 ID模型名称维度大小说明
bge-small-zhBAAI/bge-small-zh-v1.5512~100MB轻量级，适合调试
bge-base-zhBAAI/bge-base-zh-v1.5768~400MB效果均衡
bge-large-zhBAAI/bge-large-zh-v1.51024~1.3GB最佳效果
bge-m3BAAI/bge-m31024~2.3GB中英双语

调试技巧​

查看日志​

tail -f mgagent-backend/backend.log
tail -f mgagent-admin-backend/admin-backend.log

端口冲突处理​

# 查看端口占用
lsof -i :8000 :8001 :5173 :5174

# 释放端口
kill -9 $(lsof -t -i:端口号)

完全重置​

# 停止所有
./scripts/stop-all.sh
./scripts/docker-services.sh stop

# 清理 Docker 数据卷（清空 MySQL + Milvus 数据）
docker compose -f docker-compose.infra.yml down -v

# 重新启动
./scripts/docker-services.sh start
./scripts/start-all.sh

下一步​