mirrors/mcphub
1
0
Fork 0
mirror of https://github.com/samanhappy/mcphub.git synced 2025-12-23 18:29:21 -05:00
Code Issues Packages Projects Releases Wiki Activity

Refactor JWT secret management and enhance documentation (#270)

Browse Source
This commit is contained in:
samanhappy
2025-08-11 19:09:33 +08:00
committed by GitHub
parent 604fe4f71d
commit 77b423fbcc
8 changed files with 54 additions and 628 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
Dockerfile
View File

@@ -2,12 +2,6 @@ FROM python:3.13-slim-bookworm AS base
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
# 添加 HTTP_PROXY 和 HTTPS_PROXY 环境变量
ARG HTTP_PROXY=""
ARG HTTPS_PROXY=""
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY
RUN apt-get update && apt-get install -y curl gnupg git \
&& curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
&& apt-get install -y nodejs \
@@ -15,15 +9,6 @@ RUN apt-get update && apt-get install -y curl gnupg git \
RUN npm install -g pnpm
ARG REQUEST_TIMEOUT=60000
ENV REQUEST_TIMEOUT=$REQUEST_TIMEOUT
ARG BASE_PATH=""
ENV BASE_PATH=$BASE_PATH
ARG READONLY=false
ENV READONLY=$READONLY
ENV PNPM_HOME=/usr/local/share/pnpm
ENV PATH=$PNPM_HOME:$PATH
RUN mkdir -p $PNPM_HOME && \

315
docs/configuration/environment-variables.mdx
View File

@@ -11,261 +11,34 @@ MCPHub uses environment variables for configuration. This guide covers all avail
### Server Configuration
| Variable | Default | Description |
| ----------- | ------------- | ------------------------------------------------------------- |
| `PORT` | `3000` | Port number for the HTTP server |
| `HOST` | `0.0.0.0` | Host address to bind the server |
| `NODE_ENV` | `development` | Application environment (`development`, `production`, `test`) |
| `LOG_LEVEL` | `info` | Logging level (`error`, `warn`, `info`, `debug`) |
| Variable | Default | Description |
| --- | --- | --- |
| `PORT` | `3000` | Port number for the HTTP server |
| `INIT_TIMEOUT` | `300000` | Initial timeout for the application |
| `BASE_PATH` | `''` | The base path of the application |
| `READONLY` | `false` | Set to `true` to enable readonly mode |
| `MCPHUB_SETTING_PATH` | | Path to the MCPHub settings |
| `NODE_ENV` | `development` | Application environment (`development`, `production`, `test`) |
```env
PORT=3000
HOST=0.0.0.0
INIT_TIMEOUT=300000
BASE_PATH=/api
READONLY=true
MCPHUB_SETTING_PATH=/path/to/settings
NODE_ENV=production
LOG_LEVEL=info
```
### Database Configuration
| Variable | Default | Description |
| -------------- | ----------- | ---------------------------------- |
| `DATABASE_URL` | - | PostgreSQL connection string |
| `DB_HOST` | `localhost` | Database host |
| `DB_PORT` | `5432` | Database port |
| `DB_NAME` | `mcphub` | Database name |
| `DB_USER` | `mcphub` | Database username |
| `DB_PASSWORD` | - | Database password |
| `DB_SSL` | `false` | Enable SSL for database connection |
| `DB_POOL_MIN` | `2` | Minimum database pool size |
| `DB_POOL_MAX` | `10` | Maximum database pool size |
```env
# Option 1: Full connection string
DATABASE_URL=postgresql://username:password@localhost:5432/mcphub
# Option 2: Individual components
DB_HOST=localhost
DB_PORT=5432
DB_NAME=mcphub
DB_USER=mcphub
DB_PASSWORD=your-password
DB_SSL=false
```
## Authentication & Security
### JWT Configuration
| Variable | Default | Description |
| ------------------------ | ------- | ------------------------------------------- |
| `JWT_SECRET` | - | Secret key for JWT token signing (required) |
| `JWT_EXPIRES_IN` | `24h` | JWT token expiration time |
| `JWT_REFRESH_EXPIRES_IN` | `7d` | Refresh token expiration time |
| `JWT_ALGORITHM` | `HS256` | JWT signing algorithm |
| Variable | Default | Description |
| --- | --- | --- |
| `JWT_SECRET` | - | Secret key for JWT token signing (required) |
```env
JWT_SECRET=your-super-secret-key-change-this-in-production
JWT_EXPIRES_IN=24h
JWT_REFRESH_EXPIRES_IN=7d
```
### Session & Security
| Variable | Default | Description |
| ------------------- | ------- | ------------------------------- |
| `SESSION_SECRET` | - | Session encryption secret |
| `BCRYPT_ROUNDS` | `12` | bcrypt hashing rounds |
| `RATE_LIMIT_WINDOW` | `15` | Rate limiting window in minutes |
| `RATE_LIMIT_MAX` | `100` | Maximum requests per window |
| `CORS_ORIGIN` | `*` | Allowed CORS origins |
```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
```
## External Services
### OpenAI Configuration
| Variable | Default | Description |
| ------------------------ | ------------------------ | -------------------------------- |
| `OPENAI_API_KEY` | - | OpenAI API key for smart routing |
| `OPENAI_MODEL` | `gpt-3.5-turbo` | OpenAI model for embeddings |
| `OPENAI_EMBEDDING_MODEL` | `text-embedding-ada-002` | Model for vector embeddings |
| `OPENAI_MAX_TOKENS` | `1000` | Maximum tokens per request |
| `OPENAI_TEMPERATURE` | `0.1` | Temperature for AI responses |
```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 Configuration (Optional)
| Variable | Default | Description |
| ---------------- | ----------- | ----------------------- |
| `REDIS_URL` | - | Redis connection string |
| `REDIS_HOST` | `localhost` | Redis host |
| `REDIS_PORT` | `6379` | Redis port |
| `REDIS_PASSWORD` | - | Redis password |
| `REDIS_DB` | `0` | Redis database number |
| `REDIS_PREFIX` | `mcphub:` | Key prefix for Redis |
```env
# Option 1: Full connection string
REDIS_URL=redis://username:password@localhost:6379/0
# Option 2: Individual components
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password
REDIS_DB=0
REDIS_PREFIX=mcphub:
```
## MCP Server Configuration
### Default Settings
| Variable | Default | Description |
| ------------------- | ------------------- | -------------------------------------------- |
| `MCP_SETTINGS_FILE` | `mcp_settings.json` | Path to MCP settings file |
| `MCP_SERVERS_FILE` | `servers.json` | Path to servers configuration |
| `MCP_TIMEOUT` | `30000` | Default timeout for MCP operations (ms) |
| `MCP_MAX_RETRIES` | `3` | Maximum retry attempts for failed operations |
| `MCP_RESTART_DELAY` | `5000` | Delay before restarting failed servers (ms) |
```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
| Variable | Default | Description |
| --------------------------- | ------- | -------------------------------- |
| `SMART_ROUTING_ENABLED` | `true` | Enable AI-powered smart routing |
| `SMART_ROUTING_THRESHOLD` | `0.7` | Similarity threshold for routing |
| `SMART_ROUTING_MAX_RESULTS` | `5` | Maximum tools to return |
| `VECTOR_CACHE_TTL` | `3600` | Vector cache TTL in seconds |
```env
SMART_ROUTING_ENABLED=true
SMART_ROUTING_THRESHOLD=0.7
SMART_ROUTING_MAX_RESULTS=5
VECTOR_CACHE_TTL=3600
```
## File Storage & Uploads
| Variable | Default | Description |
| -------------------- | ---------------- | ----------------------------------- |
| `UPLOAD_DIR` | `./uploads` | Directory for file uploads |
| `MAX_FILE_SIZE` | `10485760` | Maximum file size in bytes (10MB) |
| `ALLOWED_FILE_TYPES` | `image/*,text/*` | Allowed MIME types |
| `STORAGE_TYPE` | `local` | Storage type (`local`, `s3`, `gcs`) |
```env
UPLOAD_DIR=./data/uploads
MAX_FILE_SIZE=10485760
ALLOWED_FILE_TYPES=image/*,text/*,application/json
STORAGE_TYPE=local
```
### S3 Storage (Optional)
| Variable | Default | Description |
| ---------------------- | ----------- | ------------------ |
| `S3_BUCKET` | - | S3 bucket name |
| `S3_REGION` | `us-east-1` | S3 region |
| `S3_ACCESS_KEY_ID` | - | S3 access key |
| `S3_SECRET_ACCESS_KEY` | - | S3 secret key |
| `S3_ENDPOINT` | - | Custom S3 endpoint |
```env
S3_BUCKET=mcphub-uploads
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
```
## Monitoring & Logging
### Application Monitoring
| Variable | Default | Description |
| ------------------------ | ------- | ----------------------------- |
| `METRICS_ENABLED` | `true` | Enable metrics collection |
| `METRICS_PORT` | `9090` | Port for metrics endpoint |
| `HEALTH_CHECK_INTERVAL` | `30000` | Health check interval (ms) |
| `PERFORMANCE_MONITORING` | `false` | Enable performance monitoring |
```env
METRICS_ENABLED=true
METRICS_PORT=9090
HEALTH_CHECK_INTERVAL=30000
PERFORMANCE_MONITORING=true
```
### Logging Configuration
| Variable | Default | Description |
| ------------------ | ------------ | --------------------------------------- |
| `LOG_FORMAT` | `json` | Log format (`json`, `text`) |
| `LOG_FILE` | - | Log file path (if file logging enabled) |
| `LOG_MAX_SIZE` | `10m` | Maximum log file size |
| `LOG_MAX_FILES` | `5` | Maximum number of log files |
| `LOG_DATE_PATTERN` | `YYYY-MM-DD` | Date pattern for log rotation |
```env
LOG_FORMAT=json
LOG_FILE=./logs/mcphub.log
LOG_MAX_SIZE=10m
LOG_MAX_FILES=5
LOG_DATE_PATTERN=YYYY-MM-DD
```
## Development & Debug
| Variable | Default | Description |
| ------------------------ | ------- | ----------------------------------- |
| `DEBUG` | - | Debug namespaces (e.g., `mcphub:*`) |
| `DEV_TOOLS_ENABLED` | `false` | Enable development tools |
| `HOT_RELOAD` | `true` | Enable hot reload in development |
| `MOCK_EXTERNAL_SERVICES` | `false` | Mock external API calls |
```env
DEBUG=mcphub:*
DEV_TOOLS_ENABLED=true
HOT_RELOAD=true
MOCK_EXTERNAL_SERVICES=false
```
## Production Optimization
| Variable | Default | Description |
| ------------------ | ------- | -------------------------------------- |
| `CLUSTER_MODE` | `false` | Enable cluster mode |
| `WORKER_PROCESSES` | `0` | Number of worker processes (0 = auto) |
| `MEMORY_LIMIT` | - | Memory limit per process |
| `CPU_LIMIT` | - | CPU limit per process |
| `GC_OPTIMIZE` | `false` | Enable garbage collection optimization |
```env
CLUSTER_MODE=true
WORKER_PROCESSES=4
MEMORY_LIMIT=512M
GC_OPTIMIZE=true
```
## Configuration Examples
@@ -276,22 +49,9 @@ GC_OPTIMIZE=true
# .env.development
NODE_ENV=development
PORT=3000
LOG_LEVEL=debug
# Database
DATABASE_URL=postgresql://mcphub:password@localhost:5432/mcphub_dev
# Auth
JWT_SECRET=dev-secret-key
JWT_EXPIRES_IN=24h
# OpenAI (optional for development)
# OPENAI_API_KEY=your-dev-key
# Debug
DEBUG=mcphub:*
DEV_TOOLS_ENABLED=true
HOT_RELOAD=true
```
### Production Environment
@@ -300,30 +60,9 @@ HOT_RELOAD=true
# .env.production
NODE_ENV=production
PORT=3000
LOG_LEVEL=info
LOG_FORMAT=json
# Database
DATABASE_URL=postgresql://mcphub:secure-password@db.example.com:5432/mcphub
DB_SSL=true
DB_POOL_MAX=20
# Security
JWT_SECRET=your-super-secure-production-secret
SESSION_SECRET=your-session-secret
BCRYPT_ROUNDS=14
# External Services
OPENAI_API_KEY=your-production-openai-key
REDIS_URL=redis://redis.example.com:6379
# Monitoring
METRICS_ENABLED=true
PERFORMANCE_MONITORING=true
# Optimization
CLUSTER_MODE=true
GC_OPTIMIZE=true
```
### Docker Environment
@@ -331,21 +70,10 @@ GC_OPTIMIZE=true
```env
# .env.docker
NODE_ENV=production
HOST=0.0.0.0
PORT=3000
# Use service names for Docker networking
DATABASE_URL=postgresql://mcphub:password@postgres:5432/mcphub
REDIS_URL=redis://redis:6379
# Security
JWT_SECRET_FILE=/run/secrets/jwt_secret
DB_PASSWORD_FILE=/run/secrets/db_password
# File paths in container
MCP_SETTINGS_FILE=/app/mcp_settings.json
UPLOAD_DIR=/app/data/uploads
LOG_FILE=/app/logs/mcphub.log
```
## Environment Variable Loading
@@ -364,7 +92,6 @@ MCPHub supports variable expansion:
```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}
```
## Security Best Practices
@@ -375,15 +102,3 @@ DATABASE_URL=postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_N
4. **Use environment-specific files**
5. **Validate all environment variables** at startup
6. **Use Docker secrets** for container deployments
## Validation
MCPHub validates environment variables at startup. Invalid configurations will prevent the application from starting with helpful error messages.
Required variables for production:
- `JWT_SECRET`
- `DATABASE_URL` or individual DB components
- `OPENAI_API_KEY` (if smart routing is enabled)
This comprehensive environment configuration ensures MCPHub can be properly configured for any deployment scenario.

2
docs/docs.json
View File

@@ -34,6 +34,7 @@
"group": "Configuration",
"pages": [
"configuration/mcp-settings",
"configuration/environment-variables",
"configuration/docker-setup",
"configuration/nginx"
]
@@ -63,6 +64,7 @@
"group": "配置指南",
"pages": [
"zh/configuration/mcp-settings",
"zh/configuration/environment-variables",
"zh/configuration/docker-setup",
"zh/configuration/nginx"
]

329
docs/zh/configuration/environment-variables.mdx
View File

@@ -1,271 +1,44 @@
---
title: '环境变量配置'
title: '环境变量'
description: '使用环境变量配置 MCPHub'
---
# 环境变量配置
# 环境变量
MCPHub 使用环境变量进行配置。本指南涵盖所有可用变量及其用法。
MCPHub 使用环境变量进行配置。本指南涵盖了所有可用的变量及其用法。
## 核心应用设置
### 服务器配置
| 变量 | 默认值 | 描述 |
| ----------- | ------------- | ----------------------------------------------- |
| `PORT` | `3000` | HTTP 服务器端口号 |
| `HOST` | `0.0.0.0` | 服务器绑定的主机地址 |
| `NODE_ENV` | `development` | 应用环境（`development`、`production`、`test`） |
| `LOG_LEVEL` | `info` | 日志级别（`error`、`warn`、`info`、`debug`） |
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `PORT` | `3000` | HTTP 服务器的端口号 |
| `INIT_TIMEOUT` | `300000` | 应用程序的初始超时时间 |
| `BASE_PATH` | `''` | 应用程序的基本路径 |
| `READONLY` | `false` | 设置为 `true` 以启用只读模式 |
| `MCPHUB_SETTING_PATH` | | MCPHub 设置文件的路径 |
| `NODE_ENV` | `development` | 应用程序环境 (`development`, `production`, `test`) |
```env
PORT=3000
HOST=0.0.0.0
INIT_TIMEOUT=300000
BASE_PATH=/api
READONLY=true
MCPHUB_SETTING_PATH=/path/to/settings
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 签名算法 |
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `JWT_SECRET` | - | 用于 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
```
## 配置示例
@@ -276,22 +49,9 @@ GC_OPTIMIZE=true
# .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
```
### 生产环境
@@ -300,30 +60,9 @@ HOT_RELOAD=true
# .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 环境
@@ -331,21 +70,10 @@ GC_OPTIMIZE=true
```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
```
## 环境变量加载
@@ -353,8 +81,8 @@ LOG_FILE=/app/logs/mcphub.log
MCPHub 按以下顺序加载环境变量：
1. 系统环境变量
2. `.env.local`（被 git 忽略）
3. `.env.{NODE_ENV}`（例如 `.env.production`）
2. `.env.local` (被 git 忽略)
3. `.env.{NODE_ENV}` (例如, `.env.production`)
4. `.env`
### 使用 dotenv-expand
@@ -364,26 +92,13 @@ 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. **为生产使用强唯一密钥**
1. **永远不要将密钥提交**到版本控制
2. **为生产环境使用强大、独特的密钥**
3. **定期轮换密钥**
4. **使用特定于环境的文件**
5. **在启动时验证所有环境变量**
6. **为容器部署使用 Docker 密钥**
## 验证
MCPHub 在启动时验证环境变量。无效配置将阻止应用程序启动并提供有用的错误消息。
生产环境必需变量：
- `JWT_SECRET`
- `DATABASE_URL` 或单独的数据库组件
- `OPENAI_API_KEY`（如果启用智能路由）
这个全面的环境配置确保 MCPHub 可以为任何部署场景正确配置。

1
src/config/index.ts
View File

@@ -11,7 +11,6 @@ dotenv.config();
const defaultConfig = {
port: process.env.PORT || 3000,
initTimeout: process.env.INIT_TIMEOUT || 300000,
timeout: process.env.REQUEST_TIMEOUT || 60000,
basePath: process.env.BASE_PATH || '',
readonly: 'true' === process.env.READONLY || false,
mcpHubName: 'mcphub',

13
src/config/jwt.ts Normal file
View File

@@ -0,0 +1,13 @@
import crypto from 'crypto';
let jwtSecret = process.env.JWT_SECRET;
if (!jwtSecret) {
jwtSecret = crypto.randomBytes(32).toString('hex');
if (process.env.NODE_ENV === 'production') {
console.warn(
'Warning: JWT_SECRET is not set. Using a temporary secret. Please set a strong, persistent secret in your environment variables for production.',
);
}
}
export const JWT_SECRET = jwtSecret;

3
src/controllers/authController.ts
View File

@@ -9,11 +9,10 @@ import {
} from '../models/User.js';
import { getDataService } from '../services/services.js';
import { DataService } from '../services/dataService.js';
import { JWT_SECRET } from '../config/jwt.js';
const dataService: DataService = getDataService();
// Default secret key - in production, use an environment variable
const JWT_SECRET = process.env.JWT_SECRET || 'your-secret-key-change-this';
const TOKEN_EXPIRY = '24h';
// Login user

4
src/middlewares/auth.ts
View File

@@ -2,9 +2,7 @@ import { Request, Response, NextFunction } from 'express';
import jwt from 'jsonwebtoken';
import { loadSettings } from '../config/index.js';
import defaultConfig from '../config/index.js';
// Default secret key - in production, use an environment variable
const JWT_SECRET = process.env.JWT_SECRET || 'your-secret-key-change-this';
import { JWT_SECRET } from '../config/jwt.js';
const validateBearerAuth = (req: Request, routingConfig: any): boolean => {
if (!routingConfig.enableBearerAuth) {