mirrors/mcphub
1
0
Fork 0
mirror of https://github.com/samanhappy/mcphub.git synced 2025-12-24 02:39:19 -05:00
Code Issues Packages Projects Releases Wiki Activity

generate documents using mintlify (#153)

Browse Source
This commit is contained in:
samanhappy
2025-06-01 00:17:09 +08:00
committed by GitHub
parent 65c95aaa0b
commit 9675cd8533
40 changed files with 18018 additions and 165 deletions
Download Patch File Download Diff File Expand all files Collapse all files

539
docs/zh/configuration/docker-setup.mdx Normal file
View File

@@ -0,0 +1,539 @@
---
title: 'Docker 部署'
description: '使用 Docker 和 Docker Compose 部署 MCPHub'
---
# Docker 部署
本指南介绍使用 Docker 部署 MCPHub，包括开发和生产配置。
## Docker 快速开始
### 使用预构建镜像
```bash
# 拉取最新镜像
docker pull mcphub/mcphub:latest
# 使用默认配置运行
docker run -d \
--name mcphub \
-p 3000:3000 \
-v $(pwd)/mcp_settings.json:/app/mcp_settings.json \
mcphub/mcphub:latest
```
### 从源码构建
```bash
# 克隆仓库
git clone https://github.com/your-username/mcphub.git
cd mcphub
# 构建 Docker 镜像
docker build -t mcphub:local .
# 运行容器
docker run -d \
--name mcphub \
-p 3000:3000 \
-v $(pwd)/mcp_settings.json:/app/mcp_settings.json \
mcphub:local
```
## Docker Compose 设置
### 基本配置
创建 `docker-compose.yml` 文件：
```yaml
version: '3.8'
services:
mcphub:
image: mcphub/mcphub:latest
# 本地开发时使用：
# build: .
container_name: mcphub
ports:
- '3000:3000'
environment:
- NODE_ENV=production
- PORT=3000
- JWT_SECRET=${JWT_SECRET:-your-jwt-secret}
- DATABASE_URL=postgresql://mcphub:password@postgres:5432/mcphub
volumes:
- ./mcp_settings.json:/app/mcp_settings.json:ro
- ./servers.json:/app/servers.json:ro
- mcphub_data:/app/data
depends_on:
postgres:
condition: service_healthy
restart: unless-stopped
networks:
- mcphub-network
postgres:
image: postgres:15-alpine
container_name: mcphub-postgres
environment:
- POSTGRES_DB=mcphub
- POSTGRES_USER=mcphub
- POSTGRES_PASSWORD=password
volumes:
- postgres_data:/var/lib/postgresql/data
- ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init-db.sql:ro
ports:
- '5432:5432'
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U mcphub -d mcphub']
interval: 10s
timeout: 5s
retries: 5
restart: unless-stopped
networks:
- mcphub-network
volumes:
postgres_data:
mcphub_data:
networks:
mcphub-network:
driver: bridge
```
### 生产配置（包含 Nginx）
```yaml
version: '3.8'
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
- nginx_logs:/var/log/nginx
depends_on:
- mcphub
restart: unless-stopped
networks:
- mcphub-network
mcphub:
image: mcphub/mcphub:latest
container_name: mcphub-app
expose:
- '3000'
environment:
- NODE_ENV=production
- PORT=3000
- JWT_SECRET=${JWT_SECRET}
- JWT_EXPIRES_IN=${JWT_EXPIRES_IN:-24h}
- DATABASE_URL=postgresql://mcphub:${POSTGRES_PASSWORD}@postgres:5432/mcphub
- OPENAI_API_KEY=${OPENAI_API_KEY}
- REDIS_URL=redis://redis:6379
volumes:
- ./mcp_settings.json:/app/mcp_settings.json:ro
- ./servers.json:/app/servers.json:ro
- mcphub_data:/app/data
- mcphub_logs:/app/logs
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
restart: unless-stopped
networks:
- mcphub-network
healthcheck:
test: ['CMD', 'wget', '--quiet', '--tries=1', '--spider', 'http://localhost:3000/health']
interval: 30s
timeout: 10s
retries: 3
postgres:
image: postgres:15-alpine
container_name: mcphub-postgres
environment:
- POSTGRES_DB=mcphub
- POSTGRES_USER=mcphub
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
volumes:
- postgres_data:/var/lib/postgresql/data
- ./backups:/backups
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U mcphub -d mcphub']
interval: 10s
timeout: 5s
retries: 5
restart: unless-stopped
networks:
- mcphub-network
redis:
image: redis:7-alpine
container_name: mcphub-redis
command: redis-server --appendonly yes --requirepass ${REDIS_PASSWORD}
volumes:
- redis_data:/data
healthcheck:
test: ['CMD', 'redis-cli', 'ping']
interval: 10s
timeout: 5s
retries: 5
restart: unless-stopped
networks:
- mcphub-network
volumes:
postgres_data:
redis_data:
mcphub_data:
mcphub_logs:
nginx_logs:
networks:
mcphub-network:
driver: bridge
```
### 环境变量
为 Docker Compose 创建 `.env` 文件：
```env
# 应用程序
NODE_ENV=production
JWT_SECRET=your-super-secret-jwt-key-change-this
JWT_EXPIRES_IN=24h
# 数据库
POSTGRES_PASSWORD=your-secure-database-password
# Redis
REDIS_PASSWORD=your-secure-redis-password
# 外部 API
OPENAI_API_KEY=your-openai-api-key
# 可选：自定义端口
# PORT=3000
```
## 开发设置
### 开发 Docker Compose
创建 `docker-compose.dev.yml`：
```yaml
version: '3.8'
services:
mcphub-dev:
build:
context: .
dockerfile: Dockerfile.dev
container_name: mcphub-dev
ports:
- '3000:3000'
- '5173:5173' # 前端开发服务器
- '9229:9229' # 调试端口
environment:
- NODE_ENV=development
- PORT=3000
- DATABASE_URL=postgresql://mcphub:password@postgres:5432/mcphub
volumes:
- .:/app
- /app/node_modules
- /app/frontend/node_modules
depends_on:
- postgres
command: pnpm dev
networks:
- mcphub-dev
postgres:
image: postgres:15-alpine
container_name: mcphub-postgres-dev
environment:
- POSTGRES_DB=mcphub
- POSTGRES_USER=mcphub
- POSTGRES_PASSWORD=password
ports:
- '5432:5432'
volumes:
- postgres_dev_data:/var/lib/postgresql/data
networks:
- mcphub-dev
volumes:
postgres_dev_data:
networks:
mcphub-dev:
driver: bridge
```
### 开发 Dockerfile
创建 `Dockerfile.dev`：
```dockerfile
FROM node:20-alpine
# 安装 pnpm
RUN npm install -g pnpm
# 设置工作目录
WORKDIR /app
# 复制包文件
COPY package.json pnpm-lock.yaml ./
COPY frontend/package.json ./frontend/
# 安装依赖
RUN pnpm install
# 复制源代码
COPY . .
# 暴露端口
EXPOSE 3000 5173 9229
# 启动开发服务器
CMD ["pnpm", "dev"]
```
## 运行应用程序
### 开发模式
```bash
# 启动开发环境
docker-compose -f docker-compose.dev.yml up -d
# 查看日志
docker-compose -f docker-compose.dev.yml logs -f mcphub-dev
# 停止开发环境
docker-compose -f docker-compose.dev.yml down
```
### 生产模式
```bash
# 启动生产环境
docker-compose up -d
# 查看日志
docker-compose logs -f mcphub
# 停止生产环境
docker-compose down
```
## 配置管理
### MCP 设置卷挂载
创建您的 `mcp_settings.json`：
```json
{
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
},
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--headless"]
},
"amap": {
"command": "npx",
"args": ["-y", "@amap/amap-maps-mcp-server"],
"env": {
"AMAP_MAPS_API_KEY": "your-api-key"
}
}
}
}
```
### 密钥管理
对于生产环境，使用 Docker 密钥：
```yaml
version: '3.8'
services:
mcphub:
image: mcphub/mcphub:latest
environment:
- JWT_SECRET_FILE=/run/secrets/jwt_secret
- DATABASE_PASSWORD_FILE=/run/secrets/db_password
secrets:
- jwt_secret
- db_password
secrets:
jwt_secret:
file: ./secrets/jwt_secret.txt
db_password:
file: ./secrets/db_password.txt
```
## 数据持久化
### 数据库备份
在 `docker-compose.yml` 中添加备份服务：
```yaml
services:
backup:
image: postgres:15-alpine
container_name: mcphub-backup
environment:
- PGPASSWORD=${POSTGRES_PASSWORD}
volumes:
- ./backups:/backups
- ./scripts/backup.sh:/backup.sh:ro
command: /bin/sh -c "chmod +x /backup.sh && /backup.sh"
depends_on:
- postgres
profiles:
- backup
networks:
- mcphub-network
```
创建 `scripts/backup.sh`：
```bash
#!/bin/sh
BACKUP_FILE="/backups/mcphub_$(date +%Y%m%d_%H%M%S).sql"
pg_dump -h postgres -U mcphub -d mcphub > "$BACKUP_FILE"
echo "备份已创建：$BACKUP_FILE"
# 只保留最近 7 天的备份
find /backups -name "mcphub_*.sql" -mtime +7 -delete
```
运行备份：
```bash
docker-compose --profile backup run --rm backup
```
## 监控和健康检查
### 健康检查端点
在您的应用程序中添加：
```javascript
// 在您的 Express 应用中
app.get('/health', (req, res) => {
res.json({
status: 'healthy',
timestamp: new Date().toISOString(),
uptime: process.uptime(),
memory: process.memoryUsage(),
version: process.env.npm_package_version,
});
});
```
### Docker 健康检查
```yaml
services:
mcphub:
# ... 其他配置
healthcheck:
test: ['CMD', 'wget', '--quiet', '--tries=1', '--spider', 'http://localhost:3000/health']
interval: 30s
timeout: 10s
retries: 3
start_period: 60s
```
### 使用 Watchtower 监控
添加自动更新：
```yaml
services:
watchtower:
image: containrrr/watchtower
container_name: mcphub-watchtower
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- WATCHTOWER_CLEANUP=true
- WATCHTOWER_POLL_INTERVAL=3600
- WATCHTOWER_INCLUDE_STOPPED=true
restart: unless-stopped
```
## 故障排除
### 常见问题
**容器启动失败**：使用 `docker-compose logs mcphub` 检查日志
**数据库连接错误**：确保 PostgreSQL 健康且可访问
**端口冲突**：检查端口 3000/5432 是否已被占用
**卷挂载问题**：验证文件路径和权限
### 调试命令
```bash
# 检查容器状态
docker-compose ps
# 查看日志
docker-compose logs -f [service_name]
# 在容器中执行命令
docker-compose exec mcphub sh
# 检查数据库连接
docker-compose exec postgres psql -U mcphub -d mcphub
# 重启特定服务
docker-compose restart mcphub
# 重新构建并重启
docker-compose up --build -d
```
### 性能优化
```yaml
services:
mcphub:
# ... 其他配置
deploy:
resources:
limits:
memory: 512M
cpus: '0.5'
reservations:
memory: 256M
cpus: '0.25'
```
此 Docker 设置为 MCPHub 提供了完整的容器化环境，包含开发和生产配置。

389
docs/zh/configuration/environment-variables.mdx Normal file
View File

@@ -0,0 +1,389 @@
---
title: '环境变量配置'
description: '使用环境变量配置 MCPHub'
---
# 环境变量配置
MCPHub 使用环境变量进行配置。本指南涵盖所有可用变量及其用法。
## 核心应用设置
### 服务器配置
| 变量 | 默认值 | 描述 |
| ----------- | ------------- | ----------------------------------------------- |
| `PORT` | `3000` | HTTP 服务器端口号 |
| `HOST` | `0.0.0.0` | 服务器绑定的主机地址 |
| `NODE_ENV` | `development` | 应用环境（`development`、`production`、`test`） |
| `LOG_LEVEL` | `info` | 日志级别（`error`、`warn`、`info`、`debug`） |
```env
PORT=3000
HOST=0.0.0.0
NODE_ENV=production
LOG_LEVEL=info
```
### 数据库配置
| 变量 | 默认值 | 描述 |
| -------------- | ----------- | --------------------- |
| `DATABASE_URL` | - | PostgreSQL 连接字符串 |
| `DB_HOST` | `localhost` | 数据库主机 |
| `DB_PORT` | `5432` | 数据库端口 |
| `DB_NAME` | `mcphub` | 数据库名称 |
| `DB_USER` | `mcphub` | 数据库用户名 |
| `DB_PASSWORD` | - | 数据库密码 |
| `DB_SSL` | `false` | 启用数据库 SSL 连接 |
| `DB_POOL_MIN` | `2` | 最小数据库连接池大小 |
| `DB_POOL_MAX` | `10` | 最大数据库连接池大小 |
```env
# 选项 1：完整连接字符串
DATABASE_URL=postgresql://username:password@localhost:5432/mcphub
# 选项 2：单独组件
DB_HOST=localhost
DB_PORT=5432
DB_NAME=mcphub
DB_USER=mcphub
DB_PASSWORD=your-password
DB_SSL=false
```
## 认证与安全
### JWT 配置
| 变量 | 默认值 | 描述 |
| ------------------------ | ------- | ------------------------ |
| `JWT_SECRET` | - | JWT 令牌签名密钥（必需） |
| `JWT_EXPIRES_IN` | `24h` | JWT 令牌过期时间 |
| `JWT_REFRESH_EXPIRES_IN` | `7d` | 刷新令牌过期时间 |
| `JWT_ALGORITHM` | `HS256` | JWT 签名算法 |
```env
JWT_SECRET=your-super-secret-key-change-this-in-production
JWT_EXPIRES_IN=24h
JWT_REFRESH_EXPIRES_IN=7d
```
### 会话与安全
| 变量 | 默认值 | 描述 |
| ------------------- | ------ | -------------------- |
| `SESSION_SECRET` | - | 会话加密密钥 |
| `BCRYPT_ROUNDS` | `12` | bcrypt 哈希轮数 |
| `RATE_LIMIT_WINDOW` | `15` | 速率限制窗口（分钟） |
| `RATE_LIMIT_MAX` | `100` | 每个窗口最大请求数 |
| `CORS_ORIGIN` | `*` | 允许的 CORS 来源 |
```env
SESSION_SECRET=your-session-secret
BCRYPT_ROUNDS=12
RATE_LIMIT_WINDOW=15
RATE_LIMIT_MAX=100
CORS_ORIGIN=https://your-domain.com,https://admin.your-domain.com
```
## 外部服务
### OpenAI 配置
| 变量 | 默认值 | 描述 |
| ------------------------ | ------------------------ | ------------------------------- |
| `OPENAI_API_KEY` | - | OpenAI API 密钥（用于智能路由） |
| `OPENAI_MODEL` | `gpt-3.5-turbo` | OpenAI 嵌入模型 |
| `OPENAI_EMBEDDING_MODEL` | `text-embedding-ada-002` | 向量嵌入模型 |
| `OPENAI_MAX_TOKENS` | `1000` | 每个请求最大令牌数 |
| `OPENAI_TEMPERATURE` | `0.1` | AI 响应温度 |
```env
OPENAI_API_KEY=sk-your-openai-api-key
OPENAI_MODEL=gpt-3.5-turbo
OPENAI_EMBEDDING_MODEL=text-embedding-ada-002
OPENAI_MAX_TOKENS=1000
OPENAI_TEMPERATURE=0.1
```
### Redis 配置（可选）
| 变量 | 默认值 | 描述 |
| ---------------- | ----------- | ---------------- |
| `REDIS_URL` | - | Redis 连接字符串 |
| `REDIS_HOST` | `localhost` | Redis 主机 |
| `REDIS_PORT` | `6379` | Redis 端口 |
| `REDIS_PASSWORD` | - | Redis 密码 |
| `REDIS_DB` | `0` | Redis 数据库编号 |
| `REDIS_PREFIX` | `mcphub:` | Redis 键前缀 |
```env
# 选项 1：完整连接字符串
REDIS_URL=redis://username:password@localhost:6379/0
# 选项 2：单独组件
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password
REDIS_DB=0
REDIS_PREFIX=mcphub:
```
## MCP 服务器配置
### 默认设置
| 变量 | 默认值 | 描述 |
| ------------------- | ------------------- | ---------------------------- |
| `MCP_SETTINGS_FILE` | `mcp_settings.json` | MCP 设置文件路径 |
| `MCP_SERVERS_FILE` | `servers.json` | 服务器配置文件路径 |
| `MCP_TIMEOUT` | `30000` | MCP 操作默认超时（毫秒） |
| `MCP_MAX_RETRIES` | `3` | 失败操作最大重试次数 |
| `MCP_RESTART_DELAY` | `5000` | 重启失败服务器的延迟（毫秒） |
```env
MCP_SETTINGS_FILE=./config/mcp_settings.json
MCP_SERVERS_FILE=./config/servers.json
MCP_TIMEOUT=30000
MCP_MAX_RETRIES=3
MCP_RESTART_DELAY=5000
```
### 智能路由
| 变量 | 默认值 | 描述 |
| --------------------------- | ------ | ---------------------- |
| `SMART_ROUTING_ENABLED` | `true` | 启用 AI 驱动的智能路由 |
| `SMART_ROUTING_THRESHOLD` | `0.7` | 路由相似度阈值 |
| `SMART_ROUTING_MAX_RESULTS` | `5` | 返回的最大工具数 |
| `VECTOR_CACHE_TTL` | `3600` | 向量缓存 TTL（秒） |
```env
SMART_ROUTING_ENABLED=true
SMART_ROUTING_THRESHOLD=0.7
SMART_ROUTING_MAX_RESULTS=5
VECTOR_CACHE_TTL=3600
```
## 文件存储与上传
| 变量 | 默认值 | 描述 |
| -------------------- | ---------------- | -------------------------------- |
| `UPLOAD_DIR` | `./uploads` | 文件上传目录 |
| `MAX_FILE_SIZE` | `10485760` | 最大文件大小（字节，10MB） |
| `ALLOWED_FILE_TYPES` | `image/*,text/*` | 允许的 MIME 类型 |
| `STORAGE_TYPE` | `local` | 存储类型（`local`、`s3`、`gcs`） |
```env
UPLOAD_DIR=./data/uploads
MAX_FILE_SIZE=10485760
ALLOWED_FILE_TYPES=image/*,text/*,application/json
STORAGE_TYPE=local
```
### S3 存储（可选）
| 变量 | 默认值 | 描述 |
| ---------------------- | ----------- | -------------- |
| `S3_BUCKET` | - | S3 存储桶名称 |
| `S3_REGION` | `us-east-1` | S3 区域 |
| `S3_ACCESS_KEY_ID` | - | S3 访问密钥 |
| `S3_SECRET_ACCESS_KEY` | - | S3 密钥 |
| `S3_ENDPOINT` | - | 自定义 S3 端点 |
```env
S3_BUCKET=mcphub-uploads
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
```
## 监控与日志
### 应用监控
| 变量 | 默认值 | 描述 |
| ------------------------ | ------- | -------------------- |
| `METRICS_ENABLED` | `true` | 启用指标收集 |
| `METRICS_PORT` | `9090` | 指标端点端口 |
| `HEALTH_CHECK_INTERVAL` | `30000` | 健康检查间隔（毫秒） |
| `PERFORMANCE_MONITORING` | `false` | 启用性能监控 |
```env
METRICS_ENABLED=true
METRICS_PORT=9090
HEALTH_CHECK_INTERVAL=30000
PERFORMANCE_MONITORING=true
```
### 日志配置
| 变量 | 默认值 | 描述 |
| ------------------ | ------------ | -------------------------------- |
| `LOG_FORMAT` | `json` | 日志格式（`json`、`text`） |
| `LOG_FILE` | - | 日志文件路径（如果启用文件日志） |
| `LOG_MAX_SIZE` | `10m` | 最大日志文件大小 |
| `LOG_MAX_FILES` | `5` | 最大日志文件数 |
| `LOG_DATE_PATTERN` | `YYYY-MM-DD` | 日志轮换日期模式 |
```env
LOG_FORMAT=json
LOG_FILE=./logs/mcphub.log
LOG_MAX_SIZE=10m
LOG_MAX_FILES=5
LOG_DATE_PATTERN=YYYY-MM-DD
```
## 开发与调试
| 变量 | 默认值 | 描述 |
| ------------------------ | ------- | ------------------------------- |
| `DEBUG` | - | 调试命名空间（例如 `mcphub:*`） |
| `DEV_TOOLS_ENABLED` | `false` | 启用开发工具 |
| `HOT_RELOAD` | `true` | 在开发中启用热重载 |
| `MOCK_EXTERNAL_SERVICES` | `false` | 模拟外部 API 调用 |
```env
DEBUG=mcphub:*
DEV_TOOLS_ENABLED=true
HOT_RELOAD=true
MOCK_EXTERNAL_SERVICES=false
```
## 生产优化
| 变量 | 默认值 | 描述 |
| ------------------ | ------- | ---------------------- |
| `CLUSTER_MODE` | `false` | 启用集群模式 |
| `WORKER_PROCESSES` | `0` | 工作进程数（0 = 自动） |
| `MEMORY_LIMIT` | - | 每个进程内存限制 |
| `CPU_LIMIT` | - | 每个进程 CPU 限制 |
| `GC_OPTIMIZE` | `false` | 启用垃圾回收优化 |
```env
CLUSTER_MODE=true
WORKER_PROCESSES=4
MEMORY_LIMIT=512M
GC_OPTIMIZE=true
```
## 配置示例
### 开发环境
```env
# .env.development
NODE_ENV=development
PORT=3000
LOG_LEVEL=debug
# 数据库
DATABASE_URL=postgresql://mcphub:password@localhost:5432/mcphub_dev
# 认证
JWT_SECRET=dev-secret-key
JWT_EXPIRES_IN=24h
# OpenAI（开发时可选）
# OPENAI_API_KEY=your-dev-key
# 调试
DEBUG=mcphub:*
DEV_TOOLS_ENABLED=true
HOT_RELOAD=true
```
### 生产环境
```env
# .env.production
NODE_ENV=production
PORT=3000
LOG_LEVEL=info
LOG_FORMAT=json
# 数据库
DATABASE_URL=postgresql://mcphub:secure-password@db.example.com:5432/mcphub
DB_SSL=true
DB_POOL_MAX=20
# 安全
JWT_SECRET=your-super-secure-production-secret
SESSION_SECRET=your-session-secret
BCRYPT_ROUNDS=14
# 外部服务
OPENAI_API_KEY=your-production-openai-key
REDIS_URL=redis://redis.example.com:6379
# 监控
METRICS_ENABLED=true
PERFORMANCE_MONITORING=true
# 优化
CLUSTER_MODE=true
GC_OPTIMIZE=true
```
### Docker 环境
```env
# .env.docker
NODE_ENV=production
HOST=0.0.0.0
PORT=3000
# 使用 Docker 网络的服务名
DATABASE_URL=postgresql://mcphub:password@postgres:5432/mcphub
REDIS_URL=redis://redis:6379
# 安全
JWT_SECRET_FILE=/run/secrets/jwt_secret
DB_PASSWORD_FILE=/run/secrets/db_password
# 容器中的文件路径
MCP_SETTINGS_FILE=/app/mcp_settings.json
UPLOAD_DIR=/app/data/uploads
LOG_FILE=/app/logs/mcphub.log
```
## 环境变量加载
MCPHub 按以下顺序加载环境变量：
1. 系统环境变量
2. `.env.local`（被 git 忽略）
3. `.env.{NODE_ENV}`（例如 `.env.production`）
4. `.env`
### 使用 dotenv-expand
MCPHub 支持变量扩展：
```env
BASE_URL=https://api.example.com
API_ENDPOINT=${BASE_URL}/v1
DATABASE_URL=postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}
```
## 安全最佳实践
1. **永远不要提交密钥**到版本控制
2. **为生产使用强唯一密钥**
3. **定期轮换密钥**
4. **使用特定于环境的文件**
5. **在启动时验证所有环境变量**
6. **为容器部署使用 Docker 密钥**
## 验证
MCPHub 在启动时验证环境变量。无效配置将阻止应用程序启动并提供有用的错误消息。
生产环境必需变量：
- `JWT_SECRET`
- `DATABASE_URL` 或单独的数据库组件
- `OPENAI_API_KEY`（如果启用智能路由）
这个全面的环境配置确保 MCPHub 可以为任何部署场景正确配置。

564
docs/zh/configuration/mcp-settings.mdx Normal file
View File

@@ -0,0 +1,564 @@
---
title: 'MCP 设置配置'
description: '配置 MCPHub 的 MCP 服务器及其设置'
---
# MCP 设置配置
本指南说明如何使用 `mcp_settings.json` 文件和相关配置在 MCPHub 中配置 MCP 服务器。
## 配置文件概述
MCPHub 使用几个配置文件：
- **`mcp_settings.json`**：主要的 MCP 服务器配置
- **`servers.json`**：服务器元数据和分组
- **`.env`**：环境变量和密钥
## 基本 MCP 设置结构
### mcp_settings.json
```json
{
"mcpServers": {
"server-name": {
"command": "command-to-run",
"args": ["arg1", "arg2"],
"env": {
"ENV_VAR": "value"
},
"cwd": "/working/directory",
"timeout": 30000,
"restart": true
}
}
}
```
### 示例配置
```json
{
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"],
"env": {
"USER_AGENT": "MCPHub/1.0"
}
},
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--headless"],
"timeout": 60000
},
"slack": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-slack"],
"env": {
"SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
"SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
}
}
}
}
```
## 服务器配置选项
### 必需字段
| 字段 | 类型 | 描述 |
| --------- | ------ | ---------------- |
| `command` | string | 可执行命令或路径 |
| `args` | array | 命令行参数 |
### 可选字段
| 字段 | 类型 | 默认值 | 描述 |
| -------------- | ------- | --------------- | ------------------ |
| `env` | object | `{}` | 环境变量 |
| `cwd` | string | `process.cwd()` | 工作目录 |
| `timeout` | number | `30000` | 启动超时（毫秒） |
| `restart` | boolean | `true` | 失败时自动重启 |
| `maxRestarts` | number | `5` | 最大重启次数 |
| `restartDelay` | number | `5000` | 重启间延迟（毫秒） |
| `stdio` | string | `pipe` | stdio 配置 |
## 常见 MCP 服务器示例
### Web 和 API 服务器
#### Fetch 服务器
```json
{
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"],
"env": {
"USER_AGENT": "MCPHub/1.0",
"MAX_REDIRECTS": "10"
}
}
}
```
#### 使用 Playwright 进行网页抓取
```json
{
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--headless"],
"timeout": 60000,
"env": {
"PLAYWRIGHT_BROWSERS_PATH": "/tmp/browsers"
}
}
}
```
### 文件和系统服务器
#### 文件系统服务器
```json
{
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
"env": {
"ALLOWED_OPERATIONS": "read,write,list"
}
}
}
```
#### SQLite 服务器
```json
{
"sqlite": {
"command": "uvx",
"args": ["mcp-server-sqlite", "--db-path", "/path/to/database.db"],
"env": {
"SQLITE_READONLY": "false"
}
}
}
```
### 通信服务器
#### Slack 服务器
```json
{
"slack": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-slack"],
"env": {
"SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
"SLACK_TEAM_ID": "${SLACK_TEAM_ID}",
"SLACK_APP_TOKEN": "${SLACK_APP_TOKEN}"
}
}
}
```
#### 邮件服务器
```json
{
"email": {
"command": "python",
"args": ["-m", "mcp_server_email"],
"env": {
"SMTP_HOST": "smtp.gmail.com",
"SMTP_PORT": "587",
"EMAIL_USER": "${EMAIL_USER}",
"EMAIL_PASSWORD": "${EMAIL_PASSWORD}"
}
}
}
```
### 开发和 API 服务器
#### GitHub 服务器
```json
{
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
}
}
```
#### Google Drive 服务器
```json
{
"gdrive": {
"command": "npx",
"args": ["-y", "@google/mcp-server-gdrive"],
"env": {
"GOOGLE_CLIENT_ID": "${GOOGLE_CLIENT_ID}",
"GOOGLE_CLIENT_SECRET": "${GOOGLE_CLIENT_SECRET}",
"GOOGLE_REFRESH_TOKEN": "${GOOGLE_REFRESH_TOKEN}"
}
}
}
```
### 地图和位置服务
#### 高德地图服务器
```json
{
"amap": {
"command": "npx",
"args": ["-y", "@amap/amap-maps-mcp-server"],
"env": {
"AMAP_MAPS_API_KEY": "${AMAP_API_KEY}",
"AMAP_LANGUAGE": "zh-cn"
}
}
}
```
#### OpenStreetMap 服务器
```json
{
"osm": {
"command": "python",
"args": ["-m", "mcp_server_osm"],
"env": {
"OSM_USER_AGENT": "MCPHub/1.0"
}
}
}
```
## 高级配置
### 环境变量替换
MCPHub 支持使用 `${VAR_NAME}` 语法进行环境变量替换：
```json
{
"mcpServers": {
"api-server": {
"command": "python",
"args": ["-m", "api_server"],
"env": {
"API_KEY": "${API_KEY}",
"API_URL": "${API_BASE_URL}/v1",
"DEBUG": "${NODE_ENV:development}"
}
}
}
}
```
可以使用 `${VAR_NAME:default}` 指定默认值：
```json
{
"timeout": "${MCP_TIMEOUT:30000}",
"maxRestarts": "${MCP_MAX_RESTARTS:5}"
}
```
### 条件配置
根据环境使用不同配置：
```json
{
"mcpServers": {
"database": {
"command": "python",
"args": ["-m", "db_server"],
"env": {
"DB_URL": "${NODE_ENV:development == 'production' ? DATABASE_URL : DEV_DATABASE_URL}"
}
}
}
}
```
### 自定义服务器脚本
#### 本地 Python 服务器
```json
{
"custom-python": {
"command": "python",
"args": ["./servers/custom_server.py"],
"cwd": "/app/custom-servers",
"env": {
"PYTHONPATH": "/app/custom-servers",
"CONFIG_FILE": "./config.json"
}
}
}
```
#### 本地 Node.js 服务器
```json
{
"custom-node": {
"command": "node",
"args": ["./servers/custom-server.js"],
"cwd": "/app/custom-servers",
"env": {
"NODE_ENV": "production"
}
}
}
```
## 服务器元数据配置
### servers.json
使用服务器元数据补充 `mcp_settings.json`：
```json
{
"servers": {
"fetch": {
"name": "Fetch 服务器",
"description": "用于网络请求的 HTTP 客户端",
"category": "web",
"tags": ["http", "api", "web"],
"version": "1.0.0",
"author": "MCPHub 团队",
"documentation": "https://docs.mcphub.com/servers/fetch",
"enabled": true
},
"playwright": {
"name": "Playwright 浏览器",
"description": "网页自动化和抓取",
"category": "automation",
"tags": ["browser", "scraping", "automation"],
"version": "2.0.0",
"enabled": true
}
},
"groups": {
"web-tools": {
"name": "网页工具",
"description": "用于网页交互的工具",
"servers": ["fetch", "playwright"],
"access": "public"
},
"admin-tools": {
"name": "管理工具",
"description": "管理实用程序",
"servers": ["filesystem", "database"],
"access": "admin"
}
}
}
```
## 组管理
### 组配置
```json
{
"groups": {
"production": {
"name": "生产工具",
"description": "稳定的生产服务器",
"servers": ["fetch", "slack", "github"],
"access": "authenticated",
"rateLimit": {
"requestsPerMinute": 100,
"burstLimit": 20
}
},
"experimental": {
"name": "实验功能",
"description": "测试版和实验性服务器",
"servers": ["experimental-ai", "beta-search"],
"access": "admin",
"enabled": false
}
}
}
```
### 访问控制
| 访问级别 | 描述 |
| --------------- | ------------------- |
| `public` | 无需认证 |
| `authenticated` | 需要有效的 JWT 令牌 |
| `admin` | 需要管理员角色 |
| `custom` | 自定义权限逻辑 |
## 动态配置
### 热重载
MCPHub 支持配置热重载：
```bash
# 不重启重新加载配置
curl -X POST http://localhost:3000/api/admin/reload-config \
-H "Authorization: Bearer your-admin-token"
```
### 配置验证
MCPHub 在启动和重新加载时验证配置：
```json
{
"validation": {
"strict": true,
"allowUnknownServers": false,
"requireDocumentation": true
}
}
```
## 最佳实践
### 安全
1. **对敏感数据使用环境变量**：
```json
{
"env": {
"API_KEY": "${API_KEY}",
"DATABASE_PASSWORD": "${DB_PASSWORD}"
}
}
```
2. **限制服务器权限**：
```json
{
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/restricted/path"],
"env": {
"READONLY": "true"
}
}
}
```
### 性能
1. **设置适当的超时**：
```json
{
"timeout": 30000,
"maxRestarts": 3,
"restartDelay": 5000
}
```
2. **资源限制**：
```json
{
"env": {
"NODE_OPTIONS": "--max-old-space-size=512",
"MEMORY_LIMIT": "512MB"
}
}
```
### 监控
1. **启用健康检查**：
```json
{
"healthCheck": {
"enabled": true,
"interval": 30000,
"timeout": 5000
}
}
```
2. **日志配置**：
```json
{
"env": {
"LOG_LEVEL": "info",
"LOG_FORMAT": "json"
}
}
```
## 故障排除
### 常见问题
**服务器无法启动**：检查命令和参数
```bash
# 手动测试命令
uvx mcp-server-fetch
```
**找不到环境变量**：验证 `.env` 文件
```bash
# 检查环境
printenv | grep API_KEY
```
**权限错误**：检查文件权限和路径
```bash
# 验证可执行权限
ls -la /path/to/server
```
### 调试配置
启用调试模式进行详细日志记录：
```json
{
"debug": {
"enabled": true,
"logLevel": "debug",
"includeEnv": false,
"logStartup": true
}
}
```
### 验证错误
常见验证错误和解决方案：
1. **缺少必需字段**：添加 `command` 和 `args`
2. **无效超时**：使用数字，不是字符串
3. **找不到环境变量**：检查 `.env` 文件
4. **找不到命令**：验证安装和 PATH
这个全面的指南涵盖了在 MCPHub 中为各种用例和环境配置 MCP 服务器的所有方面。

373
docs/zh/configuration/nginx.mdx Normal file
View File

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