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 提供了坚实的基础，具有适当的安全性、性能和可靠性功能。

开始使用

核心功能

配置指南

Nginx 配置

Nginx 配置

基本反向代理设置

配置文件

启用配置

负载均衡配置

缓存配置

浏览器缓存

Nginx 代理缓存

WebSocket 支持

安全配置

速率限制

IP 白名单

监控和日志

访问日志

状态页面

Docker 集成

完整示例配置

故障排除

常见问题

调试命令

性能优化

工作进程

缓冲区大小

Keep-Alive

​Nginx 配置

​基本反向代理设置

​配置文件

​启用配置

​负载均衡配置

​缓存配置

​浏览器缓存

​Nginx 代理缓存

​WebSocket 支持

​安全配置

​速率限制

​IP 白名单

​监控和日志

​访问日志

​状态页面

​Docker 集成

​完整示例配置

​故障排除

​常见问题

​调试命令

​性能优化

​工作进程

​缓冲区大小

​Keep-Alive

Nginx 配置

基本反向代理设置

配置文件

启用配置

负载均衡配置

缓存配置

浏览器缓存

Nginx 代理缓存

WebSocket 支持

安全配置

速率限制

IP 白名单

监控和日志

访问日志

状态页面

Docker 集成

完整示例配置

故障排除

常见问题

调试命令

性能优化

工作进程

缓冲区大小

Keep-Alive