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)了解如何使用服务。