生产级反向代理:MCPHub + Nginx HTTPS 部署完整实战
生产级反向代理: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 通过一个统一的 Dashboard 管理所有 MCP 服务器:分组、健康状态、工具调用日志一目了然。
分组功能会为每组生成独立的 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;
}
}
三个最容易踩的坑
proxy_buffering off:Nginx 默认会缓冲上游响应,SSE 事件会被攒住不推送。MCPHub 的 MCP SSE 端点必须在 location 中显式关闭缓冲,参考 nginx.conf.example 中的注释说明。proxy_read_timeout要调大:MCP 长连接空闲时没有数据传输,默认 60 秒会被 Nginx 断开。建议 86400(1 天)以上。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 文档。
配置完成后,客户端无论走智能路由还是分组端点,都只面对这一个 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 中持久化该密钥 |
一切就绪后,登录控制台(默认用户 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 加密、长连接稳定、访问可管控的生产级能力。



