DEPLOYMENT.md•8.06 kB
# 部署指南
本文档详细描述了如何部署和运行微信公众号文章读取 MCP 服务器。
## 部署方式
MCP 服务器支持两种部署方式：
1. **本地部署**：使用 stdio 传输协议，适合本地开发和测试
2. **远程部署**：使用 HTTP 传输协议，适合生产环境和多用户场景
## 本地部署
### 环境要求
- Python 3.8 或更高版本
- pip 包管理器
- 操作系统：Windows、macOS 或 Linux
### 安装步骤
1. **克隆仓库**
```bash
git clone <repository-url>
cd mcp-server-wechat
```
2. **创建虚拟环境**
```bash
python -m venv venv
source venv/bin/activate # Linux/macOS
# 或
venv\Scripts\activate # Windows
```
3. **安装依赖**
```bash
pip install -r requirements.txt
```
4. **配置环境变量**
创建 `.env` 文件：
```env
# 日志级别
LOG_LEVEL=INFO
# 浏览器配置
HEADLESS=true
BROWSER_TIMEOUT=30
# 请求限制
MAX_CONCURRENT_REQUESTS=5
REQUEST_TIMEOUT=30
```
5. **运行服务器**
```bash
python -m src.mcp_server_wechat.server
```
### 与 Claude Desktop 集成
1. **编辑 Claude Desktop 配置文件**
配置文件位置：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
2. **添加 MCP 服务器配置**
```json
{
"mcpServers": {
"wechat": {
"command": "python",
"args": [
"-m",
"src.mcp_server_wechat.server"
],
"cwd": "/path/to/mcp-server-wechat"
}
}
}
```
3. **重启 Claude Desktop**
## 远程部署
### 环境要求
- Python 3.8 或更高版本
- Web 服务器（如 Nginx）或 WSGI 服务器（如 Gunicorn）
- 反向代理（可选，但推荐）
### 安装步骤
1. **克隆仓库**
```bash
git clone <repository-url>
cd mcp-server-wechat
```
2. **创建虚拟环境**
```bash
python -m venv venv
source venv/bin/activate # Linux/macOS
```
3. **安装依赖**
```bash
pip install -r requirements.txt
pip install gunicorn # 或其他 WSGI 服务器
```
4. **配置环境变量**
创建 `.env` 文件：
```env
# 服务器配置
HOST=0.0.0.0
PORT=8080
# 日志级别
LOG_LEVEL=INFO
# 浏览器配置
HEADLESS=true
BROWSER_TIMEOUT=30
# 请求限制
MAX_CONCURRENT_REQUESTS=5
REQUEST_TIMEOUT=30
# 安全配置
API_KEY=your_api_key_here
CORS_ORIGINS=https://yourdomain.com
```
5. **创建 WSGI 入口文件**
创建 `wsgi.py`：
```python
import os
from src.mcp_server_wechat.http_server import create_app
app = create_app()
if __name__ == "__main__":
app.run(host=os.getenv("HOST", "0.0.0.0"), port=int(os.getenv("PORT", 8080)))
```
6. **运行服务器**
使用 Gunicorn：
```bash
gunicorn --bind 0.0.0.0:8080 --workers 4 wsgi:app
```
7. **配置反向代理（可选）**
Nginx 配置示例：
```nginx
server {
listen 80;
server_name yourdomain.com;
location / {
proxy_pass http://127.0.0.1:8080;
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;
}
}
```
## Docker 部署
### 创建 Dockerfile
```dockerfile
FROM python:3.9-slim
# 设置工作目录
WORKDIR /app
# 安装系统依赖
RUN apt-get update && apt-get install -y \
wget \
gnupg \
unzip \
curl \
&& rm -rf /var/lib/apt/lists/*
# 安装 Chrome
RUN wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | apt-key add - \
&& echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" > /etc/apt/sources.list.d/google.list \
&& apt-get update \
&& apt-get install -y google-chrome-stable \
&& rm -rf /var/lib/apt/lists/*
# 安装 ChromeDriver
RUN CHROMEDRIVER_VERSION=`curl -sS chromedriver.storage.googleapis.com/LATEST_RELEASE` && \
wget -N http://chromedriver.storage.googleapis.com/$CHROMEDRIVER_VERSION/chromedriver_linux64.zip && \
unzip chromedriver_linux64.zip && \
chmod +x chromedriver && \
mv chromedriver /usr/local/bin/ && \
rm chromedriver_linux64.zip
# 复制依赖文件
COPY requirements.txt .
# 安装 Python 依赖
RUN pip install --no-cache-dir -r requirements.txt
# 复制应用代码
COPY . .
# 创建非 root 用户
RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
USER appuser
# 暴露端口
EXPOSE 8080
# 启动命令
CMD ["gunicorn", "--bind", "0.0.0.0:8080", "--workers", "4", "wsgi:app"]
```
### 构建 Docker 镜像
```bash
docker build -t mcp-server-wechat .
```
### 运行 Docker 容器
```bash
docker run -d \
--name mcp-wechat \
-p 8080:8080 \
-e LOG_LEVEL=INFO \
-e HEADLESS=true \
-e BROWSER_TIMEOUT=30 \
-e MAX_CONCURRENT_REQUESTS=5 \
-e REQUEST_TIMEOUT=30 \
mcp-server-wechat
```
## Kubernetes 部署
### 创建 Deployment 配置
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: mcp-wechat
spec:
replicas: 3
selector:
matchLabels:
app: mcp-wechat
template:
metadata:
labels:
app: mcp-wechat
spec:
containers:
- name: mcp-wechat
image: mcp-server-wechat:latest
ports:
- containerPort: 8080
env:
- name: LOG_LEVEL
value: "INFO"
- name: HEADLESS
value: "true"
- name: BROWSER_TIMEOUT
value: "30"
- name: MAX_CONCURRENT_REQUESTS
value: "5"
- name: REQUEST_TIMEOUT
value: "30"
resources:
requests:
memory: "512Mi"
cpu: "500m"
limits:
memory: "1Gi"
cpu: "1000m"
```
### 创建 Service 配置
```yaml
apiVersion: v1
kind: Service
metadata:
name: mcp-wechat-service
spec:
selector:
app: mcp-wechat
ports:
- protocol: TCP
port: 80
targetPort: 8080
type: LoadBalancer
```
## 监控和日志
### 日志配置
日志级别可通过环境变量 `LOG_LEVEL` 设置：
- `DEBUG`: 详细调试信息
- `INFO`: 一般信息（默认）
- `WARNING`: 警告信息
- `ERROR`: 错误信息
### 监控指标
服务器提供以下监控指标：
- 请求计数
- 响应时间
- 错误率
- 并发请求数
### 健康检查
服务器提供健康检查端点：
```
GET /health
```
响应：
```json
{
"status": "healthy",
"timestamp": "2023-01-01T12:00:00Z"
}
```
## 故障排除
### 常见问题
1. **浏览器启动失败**
- 检查是否安装了 Chrome 或 Chromium
- 确保浏览器版本与 ChromeDriver 兼容
2. **请求超时**
- 增加 `BROWSER_TIMEOUT` 环境变量值
- 检查网络连接
3. **内存不足**
- 减少 `MAX_CONCURRENT_REQUESTS` 值
- 增加服务器内存
4. **Docker 容器无法启动**
- 检查 Docker 日志：`docker logs <container-id>`
- 确保所有环境变量已正确设置
### 日志分析
查看应用日志：
```bash
# 本地部署
tail -f logs/app.log
# Docker 部署
docker logs -f <container-id>
# Kubernetes 部署
kubectl logs -f deployment/mcp-wechat
```
## 性能优化
### 调优建议
1. **并发请求**
- 根据服务器资源调整 `MAX_CONCURRENT_REQUESTS`
- 监控 CPU 和内存使用情况
2. **浏览器优化**
- 使用无头模式：`HEADLESS=true`
- 调整浏览器超时：`BROWSER_TIMEOUT`
3. **缓存策略**
- 实现文章内容缓存
- 使用 Redis 或 Memcached
4. **负载均衡**
- 部署多个服务器实例
- 使用负载均衡器分发请求
## 安全考虑
1. **API 认证**
- 使用 API 密钥验证请求
- 实施 IP 白名单
2. **数据保护**
- 不存储敏感用户数据
- 使用 HTTPS 传输数据
3. **访问控制**
- 限制 API 调用频率
- 实施请求大小限制