mirror of
https://github.com/samanhappy/mcphub.git
synced 2025-12-24 02:39:19 -05:00
374 lines
8.2 KiB
Plaintext
374 lines
8.2 KiB
Plaintext
---
|
||
title: 'Nginx 配置'
|
||
description: '配置 Nginx 作为 MCPHub 的反向代理'
|
||
---
|
||
|
||
# Nginx 配置
|
||
|
||
本指南说明如何配置 Nginx 作为 MCPHub 的反向代理，包括 SSL 终止、负载均衡和缓存策略。
|
||
|
||
## 基本反向代理设置
|
||
|
||
### 配置文件
|
||
|
||
创建或更新您的 Nginx 配置文件（`/etc/nginx/sites-available/mcphub`）：
|
||
|
||
```nginx
|
||
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;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 启用配置
|
||
|
||
```bash
|
||
# 创建符号链接启用站点
|
||
sudo ln -s /etc/nginx/sites-available/mcphub /etc/nginx/sites-enabled/
|
||
|
||
# 测试配置
|
||
sudo nginx -t
|
||
|
||
# 重新加载 Nginx
|
||
sudo systemctl reload nginx
|
||
```
|
||
|
||
## 负载均衡配置
|
||
|
||
对于具有多个 MCPHub 实例的高可用性设置：
|
||
|
||
```nginx
|
||
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;
|
||
# 其他代理设置...
|
||
}
|
||
}
|
||
```
|
||
|
||
## 缓存配置
|
||
|
||
### 浏览器缓存
|
||
|
||
```nginx
|
||
# 缓存静态资源
|
||
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` 块中添加：
|
||
|
||
```nginx
|
||
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（服务器发送事件）：
|
||
|
||
```nginx
|
||
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;
|
||
}
|
||
```
|
||
|
||
## 安全配置
|
||
|
||
### 速率限制
|
||
|
||
```nginx
|
||
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 白名单
|
||
|
||
```nginx
|
||
# 为管理端点允许特定 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;
|
||
# 其他代理设置...
|
||
}
|
||
```
|
||
|
||
## 监控和日志
|
||
|
||
### 访问日志
|
||
|
||
```nginx
|
||
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;
|
||
|
||
# 其他配置...
|
||
}
|
||
}
|
||
```
|
||
|
||
### 状态页面
|
||
|
||
```nginx
|
||
location /nginx_status {
|
||
stub_status;
|
||
allow 127.0.0.1;
|
||
deny all;
|
||
}
|
||
```
|
||
|
||
## Docker 集成
|
||
|
||
当在 Docker 中运行 MCPHub 时，更新代理配置：
|
||
|
||
```nginx
|
||
upstream mcphub_docker {
|
||
server mcphub:3000; # Docker 服务名
|
||
}
|
||
|
||
server {
|
||
location / {
|
||
proxy_pass http://mcphub_docker;
|
||
# 其他代理设置...
|
||
}
|
||
}
|
||
```
|
||
|
||
## 完整示例配置
|
||
|
||
使用提供的 `nginx.conf.example` 的生产就绪示例：
|
||
|
||
```bash
|
||
# 复制示例配置
|
||
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` 头
|
||
|
||
**缓存问题**：清除代理缓存或在开发中禁用
|
||
|
||
### 调试命令
|
||
|
||
```bash
|
||
# 测试 Nginx 配置
|
||
sudo nginx -t
|
||
|
||
# 检查 Nginx 状态
|
||
sudo systemctl status nginx
|
||
|
||
# 查看错误日志
|
||
sudo tail -f /var/log/nginx/error.log
|
||
|
||
# 检查 MCPHub 是否响应
|
||
curl -I http://localhost:3000
|
||
```
|
||
|
||
## 性能优化
|
||
|
||
### 工作进程
|
||
|
||
```nginx
|
||
# 在 nginx.conf 中
|
||
worker_processes auto;
|
||
worker_connections 1024;
|
||
```
|
||
|
||
### 缓冲区大小
|
||
|
||
```nginx
|
||
proxy_buffering on;
|
||
proxy_buffer_size 128k;
|
||
proxy_buffers 4 256k;
|
||
proxy_busy_buffers_size 256k;
|
||
```
|
||
|
||
### Keep-Alive
|
||
|
||
```nginx
|
||
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 提供了坚实的基础，具有适当的安全性、性能和可靠性功能。
|