​
Nginx 配置

本指南说明如何配置 Nginx 作为 MCPHub 的反向代理，包括 SSL 终止、负载均衡和缓存策略。

​
基本反向代理设置

​
配置文件

创建或更新您的 Nginx 配置文件（/etc/nginx/sites-available/mcphub）： 
server {
    listen 80;
    server_name your-domain.com;

    # 将 HTTP 重定向到 HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL 配置
    ssl_certificate /path/to/your/certificate.crt;
    ssl_certificate_key /path/to/your/private.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;

    # 安全头
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

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

    # 主应用程序
    location / {
        proxy_pass http://127.0.0.1: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;
        proxy_read_timeout 86400;
    }

    # API 端点，为 MCP 操作设置更长的超时
    location /api/ {
        proxy_pass http://127.0.0.1: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;
        proxy_read_timeout 300;
        proxy_connect_timeout 60;
        proxy_send_timeout 60;
    }

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        proxy_pass http://127.0.0.1:3000;
        proxy_cache_valid 200 1d;
        proxy_cache_valid 404 1m;
        add_header Cache-Control "public, immutable";
        expires 1y;
    }
}

​
启用配置

# 创建符号链接启用站点
sudo ln -s /etc/nginx/sites-available/mcphub /etc/nginx/sites-enabled/

# 测试配置
sudo nginx -t

# 重新加载 Nginx
sudo systemctl reload nginx

​
负载均衡配置

对于具有多个 MCPHub 实例的高可用性设置： 
upstream mcphub_backend {
    least_conn;
    server 127.0.0.1:3000 weight=1 max_fails=3 fail_timeout=30s;
    server 127.0.0.1:3001 weight=1 max_fails=3 fail_timeout=30s;
    server 127.0.0.1:3002 weight=1 max_fails=3 fail_timeout=30s;

    # 健康检查（Nginx Plus 功能）
    # health_check interval=5s fails=3 passes=2;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL 和其他配置...

    location / {
        proxy_pass http://mcphub_backend;
        # 其他代理设置...
    }
}

​
缓存配置

​
浏览器缓存

# 缓存静态资源
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
    proxy_pass http://127.0.0.1:3000;
    expires 1y;
    add_header Cache-Control "public, immutable";
}

# 缓存 API 响应（小心动态内容）
location /api/public/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_cache mcphub_cache;
    proxy_cache_valid 200 5m;
    proxy_cache_key "$scheme$request_method$host$request_uri";
    add_header X-Cache-Status $upstream_cache_status;
}

​
Nginx 代理缓存

在 nginx.conf 的 http 块中添加： 
http {
    # 代理缓存配置
    proxy_cache_path /var/cache/nginx/mcphub
                     levels=1:2
                     keys_zone=mcphub_cache:10m
                     max_size=1g
                     inactive=60m
                     use_temp_path=off;

    # 其他配置...
}

​
WebSocket 支持

对于实时功能和 SSE（服务器发送事件）： 
location /api/stream {
    proxy_pass http://127.0.0.1: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_buffering off;
    proxy_cache off;

    # 长连接超时
    proxy_read_timeout 24h;
    proxy_send_timeout 24h;
}

​
安全配置

​
速率限制

http {
    # 定义速率限制区域
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
    limit_req_zone $binary_remote_addr zone=login:10m rate=1r/s;

    server {
        # 对 API 端点应用速率限制
        location /api/ {
            limit_req zone=api burst=20 nodelay;
            # 其他配置...
        }

        # 登录端点的严格速率限制
        location /api/auth/login {
            limit_req zone=login burst=5;
            # 其他配置...
        }
    }
}

​
IP 白名单

# 为管理端点允许特定 IP
location /api/admin/ {
    allow 192.168.1.0/24;
    allow 10.0.0.0/8;
    deny all;

    proxy_pass http://127.0.0.1:3000;
    # 其他代理设置...
}

​
监控和日志

​
访问日志

http {
    # 自定义日志格式
    log_format mcphub_format '$remote_addr - $remote_user [$time_local] '
                            '"$request" $status $body_bytes_sent '
                            '"$http_referer" "$http_user_agent" '
                            '$request_time $upstream_response_time';

    server {
        # 启用访问日志
        access_log /var/log/nginx/mcphub_access.log mcphub_format;
        error_log /var/log/nginx/mcphub_error.log;

        # 其他配置...
    }
}

​
状态页面

location /nginx_status {
    stub_status;
    allow 127.0.0.1;
    deny all;
}

​
Docker 集成

当在 Docker 中运行 MCPHub 时，更新代理配置： 
upstream mcphub_docker {
    server mcphub:3000;  # Docker 服务名
}

server {
    location / {
        proxy_pass http://mcphub_docker;
        # 其他代理设置...
    }
}

​
完整示例配置

使用提供的 nginx.conf.example 的生产就绪示例： 
# 复制示例配置
cp nginx.conf.example /etc/nginx/sites-available/mcphub

# 使用您的域名和路径更新配置
sudo nano /etc/nginx/sites-available/mcphub

# 启用站点
sudo ln -s /etc/nginx/sites-available/mcphub /etc/nginx/sites-enabled/

# 测试并重新加载
sudo nginx -t && sudo systemctl reload nginx

​
故障排除

​
常见问题

502 Bad Gateway：检查 MCPHub 是否正在运行且可访问 504 Gateway Timeout：为长时间运行的操作增加 proxy_read_timeout WebSocket 连接失败：确保正确的 Upgrade 和 Connection 头 缓存问题：清除代理缓存或在开发中禁用

​
调试命令

# 测试 Nginx 配置
sudo nginx -t

# 检查 Nginx 状态
sudo systemctl status nginx

# 查看错误日志
sudo tail -f /var/log/nginx/error.log

# 检查 MCPHub 是否响应
curl -I http://localhost:3000

​
性能优化

​
工作进程

# 在 nginx.conf 中
worker_processes auto;
worker_connections 1024;

​
缓冲区大小

proxy_buffering on;
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;

​
Keep-Alive

upstream mcphub_backend {
    server 127.0.0.1:3000;
    keepalive 32;
}

location / {
    proxy_pass http://mcphub_backend;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
}
此配置为在 Nginx 后运行 MCPHub 提供了坚实的基础，具有适当的安全性、性能和可靠性功能。