Skip to main content

​
环境变量

MCPHub 使用环境变量进行配置。本指南涵盖了所有可用的变量及其用法。

​
核心应用设置

​
服务器配置

变量默认值描述
PORT3000HTTP 服务器的端口号
DEFAULT_REQUEST_TIMEOUT60000当服务器未设置 options.timeout 时，上游 MCP 服务器请求使用的默认超时时间（毫秒）
INIT_TIMEOUT300000应用程序的初始超时时间
BASE_PATH''应用程序的基本路径
READONLYfalse设置为 true 以启用只读模式
MCPHUB_SETTING_PATHMCPHub 设置文件的路径
NODE_ENVdevelopment应用程序环境 (development, production, test)
PORT=3000
DEFAULT_REQUEST_TIMEOUT=60000
INIT_TIMEOUT=300000
BASE_PATH=/api
READONLY=true
MCPHUB_SETTING_PATH=/path/to/settings
NODE_ENV=production

​
认证与安全

​
JWT 配置

变量默认值描述
JWT_SECRET-用于 JWT 令牌签名的密钥 (必需)
JWT_SECRET=your-super-secret-key-change-this-in-production

​
Better Auth（可选：GitHub / Google / 本地 OIDC 登录）

Better Auth 会在 src/betterAuth.ts 中于启动时初始化一次，因此无论是改环境变量还是改 systemConfig.auth.betterAuth / systemConfig.install.baseUrl，都需要重启后才会生效。 对于非敏感的 Better Auth 配置，MCPHub 现在按以下优先级解析：
  1. BETTER_AUTH_* 环境变量
  2. systemConfig.auth.betterAuth（来自 mcp_settings.json 或数据库系统配置）
  3. 内置默认值
Provider 的客户端凭据仍然只支持通过环境变量提供。 MCPHub 里的 Better Auth 目前依赖 PostgreSQL 会话存储，因此需要配置 DB_URL；纯文件模式不支持 Better Auth 登录。
变量描述
BETTER_AUTH_ENABLEDBetter Auth 总开关。即使打开了它，如果 MCPHub 不在数据库模式下，或者没有任何提供商具备所需凭据，Better Auth 仍会自动禁用。
BETTER_AUTH_URL用于生成 Better Auth 回调 URL 的公网访问地址。现在它会优先于 systemConfig.install.baseUrl 生效，其来源也会自动加入可信来源列表。
BETTER_AUTH_BASE_PATHBetter Auth 处理器挂载路径，默认 /api/auth/better。
BETTER_AUTH_TRUSTED_ORIGINS允许发起 Better Auth 登录流程的额外来源。支持逗号分隔、空白分隔或 JSON 数组。未设置时，MCPHub 仍会自动信任 BETTER_AUTH_URL 和 systemConfig.install.baseUrl 的来源。
BETTER_AUTH_GOOGLE_ENABLED在提供了凭据后启用或禁用 Google 登录，默认 true。
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRETGoogle 登录凭据。
BETTER_AUTH_GITHUB_ENABLED在提供了凭据后启用或禁用 GitHub 登录，默认 true。
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRETGitHub 登录凭据。
BETTER_AUTH_OIDC_ENABLED启用或禁用通用 OIDC Provider，默认 false。
BETTER_AUTH_OIDC_PROVIDER_ID传给 Better Auth generic OAuth 插件的 Provider 标识，默认 oidc。
BETTER_AUTH_OIDC_DISCOVERY_URL本地 OIDC Issuer 的 discovery 地址。
OIDC_DISCOVERY_URLBETTER_AUTH_OIDC_DISCOVERY_URL 的兼容别名；如果仍在配置文件里使用 ${OIDC_DISCOVERY_URL} 插值，也可以继续保留。
BETTER_AUTH_OIDC_SCOPES本地 OIDC 登录请求的 scopes。支持逗号分隔、空白分隔或 JSON 数组，默认 openid profile email。
BETTER_AUTH_OIDC_PKCE是否启用本地 OIDC 登录的 PKCE，默认 true。
BETTER_AUTH_OIDC_PROMPT可选的 OIDC prompt 参数（如 login、consent、select_account）。
OIDC_CLIENT_ID / OIDC_CLIENT_SECRET本地 OIDC Provider（例如 Keycloak、Authentik、Dex）的客户端凭据。
非敏感的 Better Auth 配置仍然可以放在 systemConfig.auth.betterAuth 中，但现在推荐优先使用 BETTER_AUTH_* 环境变量。一个纯环境变量驱动的本地 OIDC 配置示例如下： 
BETTER_AUTH_ENABLED=true
BETTER_AUTH_URL=https://mcphub.example.com
BETTER_AUTH_BASE_PATH=/api/auth/better
BETTER_AUTH_TRUSTED_ORIGINS=https://dashboard.example.com,https://admin.example.com

BETTER_AUTH_OIDC_ENABLED=true
BETTER_AUTH_OIDC_PROVIDER_ID=local-oidc
BETTER_AUTH_OIDC_DISCOVERY_URL=https://auth.example.com/.well-known/openid-configuration
BETTER_AUTH_OIDC_SCOPES=openid,profile,email
BETTER_AUTH_OIDC_PKCE=true
BETTER_AUTH_OIDC_PROMPT=login
OIDC_CLIENT_ID=your-oidc-client-id
OIDC_CLIENT_SECRET=your-oidc-client-secret

​
配置示例

​
开发环境

# .env.development
NODE_ENV=development
PORT=3000

# 认证
JWT_SECRET=dev-secret-key

​
生产环境

# .env.production
NODE_ENV=production
PORT=3000

# 安全
JWT_SECRET=your-super-secure-production-secret

​
Docker 环境

# .env.docker
NODE_ENV=production
PORT=3000

# 安全
JWT_SECRET_FILE=/run/secrets/jwt_secret

​
环境变量加载

MCPHub 按以下顺序加载环境变量：
  1. 系统环境变量
  2. .env.local (被 git 忽略)
  3. .env.{NODE_ENV} (例如, .env.production)
  4. .env

​
使用 dotenv-expand

MCPHub 支持变量扩展： 
BASE_URL=https://api.example.com
API_ENDPOINT=${BASE_URL}/v1

​
安全最佳实践

  1. 永远不要将密钥提交到版本控制
  2. 为生产环境使用强大、独特的密钥
  3. 定期轮换密钥
  4. 使用特定于环境的文件
  5. 在启动时验证所有环境变量
  6. 为容器部署使用 Docker 密钥