生产级反向代理:MCPHub + Nginx HTTPS 部署完整实战

原创2026-10-17 21:08:272,165 阅读
文章标签:后端API网关MCP 服务AI 应用认证鉴权前端本地部署监控大盘RAG

生产级反向代理:MCPHub + Nginx HTTPS 部署完整实战

MCPHub 是一个开源、自托管的 MCP 网关与控制平面,用于连接、控制和运行 MCP 服务器。本文带你从零完成一次生产级部署实战:用 Docker 跑起 MCPHub,再通过 Nginx 反向代理 + HTTPS 证书把它安全地暴露到公网。全程只需 3 步,即使是新手也能 10 分钟上线。

为什么 MCPHub 需要 Nginx 反向代理?

本地用 docker run -p 3000:3000 启动 MCPHub 后,控制台直接裸露在 3000 端口上。一旦要交给团队或公网客户端使用,就会遇到三类问题:

  • 没有 HTTPS:MCP 端点、OAuth 回调、Bearer Key 都走 HTTP 明文传输,凭据存在泄露风险;
  • 长连接不稳定:MCPHub 的 SSE / Streamable HTTP 端点是长连接,很多代理默认 60 秒就掐断连接,导致工具调用中途失败;
  • 缺少防护:无访问频率限制、无安全响应头、静态资源不走缓存。

Nginx 恰好是解决这三件事的标准答案:做 SSL 终结、调长超时、关闭 SSE 缓冲、限流和缓存。

MCPHub 控制台概览:Nginx 反向代理保护下的 Web 控制台

MCPHub 通过一个统一的 Dashboard 管理所有 MCP 服务器:分组、健康状态、工具调用日志一目了然。

MCPHub 分组管理:为不同客户端生成独立路由

分组功能会为每组生成独立的 MCP 端点,经 Nginx 转发后,不同团队可以各连各的端点,互不干扰。

第一步:Docker 启动 MCPHub(含生产环境变量)

生产部署推荐 Docker Compose 方式,仓库文档 Docker Setup 中给出了完整的生产模板。核心配置如下:

services:
  nginx:
    image: nginx:alpine
    container_name: mcphub-nginx
    ports:
      - '80:80'
      - '443:443'
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - mcphub
    restart: unless-stopped

  mcphub:
    image: samanhappy/mcphub:latest
    container_name: mcphub-app
    expose:            # 只暴露给 Nginx,不映射到宿主机
      - '3000'
    environment:
      - NODE_ENV=production
      - PORT=3000
      - TRUST_PROXY=1                # 关键:告诉 MCPHub 真实 IP 来自代理
      - JWT_SECRET=${JWT_SECRET}    # 关键:固定会话签名密钥
      - INSTALL_BASE_URL=https://mcphub.example.com
    volumes:
      - ./data:/app/data            # 持久化配置、用户与凭据
    depends_on:
      - postgres
    healthcheck:
      test: ['CMD', 'wget', '--quiet', '--tries=1', '--spider', 'http://localhost:3000/health']
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

这里有几个生产必配项,对照官方 环境变量文档:

变量 作用 建议值
TRUST_PROXY 让 MCPHub 信任 Nginx 传来的 X-Forwarded-For,正确记录客户端 IP 和限流 1
JWT_SECRET 会话签名密钥,不设的话每次重启都会让所有登录失效 用 openssl rand -hex 32 生成
INSTALL_BASE_URL 控制台生成客户端配置时使用的公网地址 你的 HTTPS 域名
BASE_PATH 子路径部署时的挂载前缀 默认留空,见第三步

⚠️ mcphub 服务用 expose 而不是 ports,让 3000 端口只对 Nginx 可见,是生产部署的第一道安全线。

第二步:编写 Nginx HTTPS 反向代理配置

仓库自带了一份可直接参考的配置 nginx.conf.example,官方文档 Nginx Configuration 则给出了带 SSL 的完整版。以下是整合后的生产配置,放在宿主机 ./nginx.conf(挂载到容器):

# HTTP 强制跳转 HTTPS
server {
    listen 80;
    server_name mcphub.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name mcphub.example.com;

    ssl_certificate     /etc/nginx/ssl/fullchain.crt;
    ssl_certificate_key /etc/nginx/ssl/privkey.key;
    ssl_protocols       TLSv1.2 TLSv1.3;

    # 安全响应头
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # Gzip 压缩
    gzip on;
    gzip_min_length 1024;
    gzip_types text/plain text/css application/json application/javascript image/svg+xml;

    # 主应用(控制台 + MCP 端点)
    location / {
        proxy_pass http://mcphub:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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_cache_bypass $http_upgrade;

        # 关键:SSE 长连接必须关闭缓冲
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400;
    }

    # API 请求给更长超时(MCP 工具调用可能耗时较久)
    location /api/ {
        proxy_pass http://mcphub:3000;
        proxy_http_version 1.1;
        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 300;
    }
}

三个最容易踩的坑

  1. proxy_buffering off:Nginx 默认会缓冲上游响应,SSE 事件会被攒住不推送。MCPHub 的 MCP SSE 端点必须在 location 中显式关闭缓冲,参考 nginx.conf.example 中的注释说明。
  2. proxy_read_timeout 要调大:MCP 长连接空闲时没有数据传输,默认 60 秒会被 Nginx 断开。建议 86400(1 天)以上。
  3. Upgrade / Connection 头不能漏:WebSocket 升级和 SSE 都依赖这两个头,漏掉任何一行都会出现连接闪断。

可选:给登录接口加限流

在 http 块中定义限流区,防止暴力破解:

limit_req_zone $binary_remote_addr zone=login:10m rate=1r/s;

# 在 server 块内
location /api/auth/login {
    limit_req zone=login burst=5;
    proxy_pass http://mcphub:3000;
    # ... 其余代理头
}

更多缓存、负载均衡(多实例 least_conn)、IP 白名单写法,可直接查阅 Nginx Configuration 文档。

MCPHub 智能路由:经 HTTPS 网关统一暴露的工具搜索端点

配置完成后,客户端无论走智能路由还是分组端点,都只面对这一个 HTTPS 地址。

第三步:子路径部署(可选,一个域名挂多个服务)

如果你的域名已经给别的服务用了,可以把 MCPHub 挂到 /mcphub 子路径下。仓库示例 nginx.conf.example 展示了两种做法,推荐「Nginx 剥离前缀」:

location /mcphub/ {
    rewrite ^/mcphub/(.*)$ /$1 break;   # 转发前去掉 /mcphub 前缀
    proxy_pass http://mcphub:3000/;
    # ... 其余代理头同前
    proxy_buffering off;
    proxy_read_timeout 24h;
}

注意:不要同时给 MCPHub 设置 BASE_PATH=/mcphub。如果改用「保留前缀」方案(proxy_pass http://mcphub:3000/mcphub/),才需要配合环境变量 BASE_PATH=/mcphub,两种方案二选一即可。

部署验证与常见故障排查

上线后按顺序验证:

# 1. 检查 Nginx 配置语法
sudo nginx -t && sudo systemctl reload nginx

# 2. 直连后端健康检查(确认 MCPHub 活着)
curl -I http://localhost:3000/health

# 3. 走 HTTPS 访问控制台
curl -I https://mcphub.example.com/

遇到异常时对照下表快速定位:

现象 原因 处理
502 Bad Gateway MCPHub 容器未启动或 3000 端口不通 docker logs mcphub 查看启动日志
504 Gateway Timeout 工具调用耗时超过 proxy_read_timeout 调大超时,见上文配置
SSE 连接频繁断开 缓冲未关闭或超时太短 检查 proxy_buffering off
客户端 IP 全显示 127.0.0.1 未信任代理 设置 TRUST_PROXY=1 并重启容器
重启后登录全部失效 JWT_SECRET 未固定 在 compose 中持久化该密钥

MCPHub 市场:控制台内一键安装 MCP 服务器

一切就绪后,登录控制台(默认用户 admin,首次启动的随机密码打印在容器日志中),即可在市场里一键安装 MCP 服务器,团队成员用 https://mcphub.example.com/mcp 统一接入。

总结

一次生产级 MCPHub 部署只需记住这张清单:

  • ✅ Docker Compose 启动,expose 代替 ports 隐藏 3000 端口;
  • ✅ 设置 TRUST_PROXY=1、固定 JWT_SECRET、指定 INSTALL_BASE_URL;
  • ✅ Nginx 443 SSL 终结 + HTTP 301 跳转;
  • ✅ MCP/SSE 端点关闭 proxy_buffering 并调大 proxy_read_timeout;
  • ✅ 登录接口限流,安全响应头齐备。

完整配置模板可参考仓库中的 nginx.conf.example 与 Docker 部署文档。按这套方案上线后,你的 MCP 网关就具备了 HTTPS 加密、长连接稳定、访问可管控的生产级能力。

登录后查看全文
mcphub