部署指南

MCP Server 支持两种部署模式：托管 HTTP 模式和本地 stdio 模式。

架构概览

托管 HTTP 模式的架构：

用户 AI 客户端 (Cherry Studio / Claude / Cursor)
    ↓  HTTPS: mcp.priceminder.online?key=xxx
    ↓
Nginx (443 → 反向代理)
    ↓
MCP Server (127.0.0.1:8020)
    ↓  认证后获取 sentinel_token
    ↓
Backend API (priceminder.online/shopee)

方式一：Docker 部署（推荐）

# 1. 构建镜像
cd sentinel-mcp-server
docker build -t sentinel-mcp .

# 2. 运行容器
docker run -d \
  --name sentinel-mcp \
  --restart always \
  -p 127.0.0.1:8020:8020 \
  -e SENTINEL_API_BASE=https://priceminder.online/shopee \
  -e SENTINEL_MCP_INTERNAL_KEY=sentinel-mcp-internal-2026 \
  -e MCP_MODE=http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8020 \
  -e LOG_LEVEL=info \
  sentinel-mcp

# 3. 验证
curl http://127.0.0.1:8020/health
# 应返回: {"status":"ok","service":"sentinel-mcp"}

方式二：systemd 部署

# 1. 安装
cd /opt
git clone <repo> sentinel-mcp-server
cd sentinel-mcp-server
python3.12 -m venv venv
venv/bin/pip install .

# 2. 安装服务
cp deploy/sentinel-mcp.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable sentinel-mcp
systemctl start sentinel-mcp

# 3. 验证
systemctl status sentinel-mcp
curl http://127.0.0.1:8020/health

Nginx 反向代理

# 1. 复制配置
cp deploy/nginx-mcp.conf /etc/nginx/sites-available/mcp.priceminder.online

# 2. 启用
ln -s /etc/nginx/sites-available/mcp.priceminder.online /etc/nginx/sites-enabled/

# 3. SSL 证书
certbot --nginx -d mcp.priceminder.online

# 4. 重载
nginx -t && systemctl reload nginx

Nginx 关键配置（SSE 支持）：

location / {
    proxy_pass http://127.0.0.1:8020;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_set_header Host $host;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 300s;
}

关键注意事项

1. SENTINEL_MCP_INTERNAL_KEY 必须与后端 API 配置一致
2. SSL 证书必须有效（MCP 客户端要求 HTTPS）
3. proxy_buffering off 是 SSE 流式传输的必需配置
4. 数据库需执行迁移添加 mcp_usage_logs 表

健康检查

部署完成后，验证服务状态：

# 本地检查
curl http://127.0.0.1:8020/health
# {"status":"ok","service":"sentinel-mcp"}

# 通过 Nginx 检查（需有效 SSL）
curl https://mcp.priceminder.online/health