MCP AI Service Platform

# MCP生产级客户端部署指南 本指南将详细介绍如何部署MCP生产级客户端，包括本地开发环境和生产环境部署。 ## 前置条件 ### 系统要求 - **操作系统**：Linux、macOS或Windows（推荐Linux） - **Python**：3.11或更高版本 - **内存**：至少4GB（推荐8GB） - **存储**：至少20GB可用空间 ### 必需软件 - Python 3.11+ - Git - Docker（Docker部署） - Docker Compose（Docker部署） ## 方式一：本地部署 ### 1. 获取代码 ```bash git clone <仓库地址> cd python-mcp-server-client ``` ### 2. 创建虚拟环境 ```bash # 创建虚拟环境 python3 -m venv venv # 激活虚拟环境 # Linux/macOS: source venv/bin/activate # Windows: venv\Scripts\activate ``` ### 3. 安装依赖 ```bash # 推荐使用uv（更快） pip install uv uv pip install -r pyproject.toml # 或使用传统pip pip install -e . ``` ### 4. 配置环境变量 ```bash # 复制环境变量模板 cp .env.example .env # 编辑环境变量文件 nano .env ``` **重要配置项：** ```bash # OpenAI API配置（必须） OPENAI_API_KEY=your_openai_api_key_here OPENAI_BASE_URL=https://api.openai.com/v1 OPENAI_MODEL=gpt-4 # 数据库配置 POSTGRES_HOST=localhost POSTGRES_PORT=5432 POSTGRES_DB=mcp_rag POSTGRES_USER=mcp_user POSTGRES_PASSWORD=your_secure_password # Redis配置 REDIS_HOST=localhost REDIS_PORT=6379 ``` ### 5. 安装数据库 #### PostgreSQL + pgvector ```bash # Ubuntu/Debian sudo apt update sudo apt install postgresql postgresql-contrib sudo -u postgres psql -c "CREATE USER mcp_user WITH PASSWORD 'your_password';" sudo -u postgres psql -c "CREATE DATABASE mcp_rag OWNER mcp_user;" # 安装pgvector扩展 sudo apt install postgresql-16-pgvector sudo -u postgres psql -d mcp_rag -c "CREATE EXTENSION vector;" ``` #### Redis ```bash # Ubuntu/Debian sudo apt install redis-server sudo systemctl start redis-server sudo systemctl enable redis-server ``` ### 6. 运行数据库迁移 ```bash # 初始化数据库 python -c " from src.core.database import init_database import asyncio asyncio.run(init_database()) " ``` ### 7. 启动服务 ```bash # 使用启动脚本 chmod +x scripts/start.sh ./scripts/start.sh start # 或直接运行 python -m src.api.main ``` ### 8. 验证部署 访问以下地址验证服务： - API文档：http://localhost:8000/docs - 健康检查：http://localhost:8000/health - Prometheus指标：http://localhost:8001/metrics ## 方式二：Docker部署（推荐） ### 1. 获取代码 ```bash git clone <仓库地址> cd python-mcp-server-client ``` ### 2. 配置环境变量 ```bash # 复制环境变量模板 cp .env.example .env # 编辑环境变量 nano .env ``` **必需配置：** ```bash # OpenAI API密钥（必须设置） OPENAI_API_KEY=your_openai_api_key_here # 数据库密码 POSTGRES_PASSWORD=your_secure_password # Grafana密码 GRAFANA_PASSWORD=your_admin_password ``` ### 3. 启动服务 ```bash # 使用脚本启动 ./scripts/start.sh docker # 或直接使用docker-compose docker-compose up -d ``` ### 4. 查看服务状态 ```bash # 查看所有服务状态 docker-compose ps # 查看服务日志 docker-compose logs -f mcp-client ``` ### 5. 访问服务 - **API服务**：http://localhost:8000 - **API文档**：http://localhost:8000/docs - **Prometheus监控**：http://localhost:9090 - **Grafana面板**：http://localhost:3000（admin/你的密码） ## 生产环境部署 ### 1. 服务器准备 ```bash # 更新系统 sudo apt update && sudo apt upgrade -y # 安装Docker curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER # 安装Docker Compose sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose ``` ### 2. 安全配置 ```bash # 创建专用用户 sudo useradd -m -s /bin/bash mcpuser sudo usermod -aG docker mcpuser # 切换到专用用户 sudo su - mcpuser ``` ### 3. 部署应用 ```bash # 获取代码 git clone <仓库地址> /home/mcpuser/mcp-client cd /home/mcpuser/mcp-client # 配置环境变量 cp .env.example .env # 编辑.env设置生产环境配置 # 启动服务 docker-compose up -d ``` ### 4. 配置反向代理（Nginx） ```bash # 安装Nginx sudo apt install nginx # 创建配置文件 sudo nano /etc/nginx/sites-available/mcp-client ``` **Nginx配置示例：** ```nginx server { listen 80; server_name your-domain.com; location / { proxy_pass http://localhost:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 300s; proxy_connect_timeout 75s; } } ``` ```bash # 启用站点 sudo ln -s /etc/nginx/sites-available/mcp-client /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx ``` ### 5. 配置SSL（可选） ```bash # 安装Certbot sudo apt install certbot python3-certbot-nginx # 获取SSL证书 sudo certbot --nginx -d your-domain.com ``` ### 6. 设置自动启动 ```bash # 创建systemd服务 sudo nano /etc/systemd/system/mcp-client.service ``` **服务配置：** ```ini [Unit] Description=MCP Client Service Requires=docker.service After=docker.service [Service] Type=oneshot RemainAfterExit=true WorkingDirectory=/home/mcpuser/mcp-client ExecStart=/usr/local/bin/docker-compose up -d ExecStop=/usr/local/bin/docker-compose down User=mcpuser Group=mcpuser [Install] WantedBy=multi-user.target ``` ```bash # 启用服务 sudo systemctl daemon-reload sudo systemctl enable mcp-client.service sudo systemctl start mcp-client.service ``` ## 环境变量详解 ### OpenAI配置 ```bash OPENAI_API_KEY=sk-xxx # OpenAI API密钥（必需） OPENAI_BASE_URL=https://api.openai.com/v1 # API基础URL OPENAI_MODEL=gpt-4 # 默认模型 OPENAI_MAX_TOKENS=1000 # 最大令牌数 OPENAI_TIMEOUT=30 # 请求超时时间 ``` ### 数据库配置 ```bash POSTGRES_HOST=localhost # PostgreSQL主机 POSTGRES_PORT=5432 # PostgreSQL端口 POSTGRES_DB=mcp_rag # 数据库名 POSTGRES_USER=mcp_user # 数据库用户 POSTGRES_PASSWORD=password # 数据库密码 POSTGRES_MAX_CONNECTIONS=20 # 最大连接数 ``` ### Redis配置 ```bash REDIS_HOST=localhost # Redis主机 REDIS_PORT=6379 # Redis端口 REDIS_DB=0 # Redis数据库编号 REDIS_PASSWORD= # Redis密码（可选） REDIS_MAX_CONNECTIONS=20 # 最大连接数 ``` ### API服务配置 ```bash API_HOST=0.0.0.0 # 监听地址 API_PORT=8000 # 监听端口 API_WORKERS=1 # 工作进程数 API_MAX_CONCURRENT_REQUESTS=100 # 最大并发请求 API_REQUEST_TIMEOUT=300 # 请求超时时间 API_RATE_LIMIT_PER_MINUTE=60 # 每分钟请求限制 ``` ### RAG配置 ```bash RAG_EMBEDDING_MODEL=text-embedding-ada-002 # 嵌入模型 RAG_CHUNK_SIZE=1000 # 文本块大小 RAG_CHUNK_OVERLAP=200 # 文本块重叠 RAG_SIMILARITY_THRESHOLD=0.7 # 相似度阈值 RAG_MAX_SEARCH_RESULTS=10 # 最大搜索结果 ``` ## 常见问题 ### 1. 数据库连接失败 ```bash # 检查PostgreSQL状态 sudo systemctl status postgresql sudo systemctl start postgresql # 检查用户权限 sudo -u postgres psql -c "\du" ``` ### 2. Redis连接失败 ```bash # 检查Redis状态 sudo systemctl status redis-server redis-cli ping ``` ### 3. 端口占用 ```bash # 检查端口占用 sudo netstat -tlnp | grep 8000 sudo lsof -i :8000 # 杀死占用进程 sudo kill -9 <PID> ``` ### 4. Docker权限问题 ```bash # 添加用户到docker组 sudo usermod -aG docker $USER # 重新登录或执行 newgrp docker ``` ### 5. 内存不足 ```bash # 检查内存使用 free -h docker stats # 调整Docker限制 # 编辑docker-compose.yml中的resources限制 ``` ## 监控和维护 ### 1. 健康检查 ```bash # 检查API健康状态 curl http://localhost:8000/health # 检查Docker服务状态 docker-compose ps ``` ### 2. 日志查看 ```bash # 查看应用日志 docker-compose logs -f mcp-client # 查看系统日志 sudo journalctl -u mcp-client.service -f ``` ### 3. 性能监控 - 访问Grafana面板：http://localhost:3000 - 查看Prometheus指标：http://localhost:9090 - 监控API响应时间和错误率 ### 4. 备份数据 ```bash # 备份PostgreSQL数据 docker exec postgres_container pg_dump -U mcp_user mcp_rag > backup.sql # 备份Redis数据 docker exec redis_container redis-cli SAVE ``` ### 5. 更新部署 ```bash # 停止服务 docker-compose down # 更新代码 git pull # 重新构建并启动 docker-compose build --no-cache docker-compose up -d ``` ## 故障排除 ### 1. 启动失败 - 检查.env文件配置 - 确认API密钥有效 - 检查端口是否被占用 - 查看错误日志 ### 2. 性能问题 - 检查数据库连接池配置 - 监控内存和CPU使用率 - 调整worker进程数 - 检查网络延迟 ### 3. API错误 - 检查API密钥额度 - 确认模型名称正确 - 检查网络连接 - 查看详细错误日志 --- 部署完成后，请继续阅读[API调用示例](API调用示例.md)了解如何使用服务。