环境变量

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

核心应用设置

服务器配置

变量	默认值	描述
`PORT`	`3000`	HTTP 服务器的端口号
`DEFAULT_REQUEST_TIMEOUT`	`60000`	当服务器未设置 `options.timeout` 时，上游 MCP 服务器请求使用的默认超时时间（毫秒）
`INIT_TIMEOUT`	`300000`	应用程序的初始超时时间
`STARTUP_CONNECT_CONCURRENCY`	`0`	启动时最多允许多少个上游服务器同时连接。`0`（或不设置）表示全部并行连接。当部署了大量 `stdio` 服务器时，设置上限可以避免它们争抢 CPU、网络和磁盘，进而耗尽 `INIT_TIMEOUT`。排队等待的时间不计入服务器自身的超时预算。
`BASE_PATH`	`''`	应用程序的基本路径
`MCPHUB_REPLICA_MODE`	`false`	显式启用多副本模式，要求 PostgreSQL、共享持久密钥和 `DB_SYNCHRONIZE=false`。
`MCPHUB_NODE_ID`	主机名	多副本诊断、响应头、日志及指标中的节点标识。
`DB_SYNCHRONIZE`	`true`	接入副本设为 `false`；独立运行 `pnpm db:setup` 时设为 `true`。
`SMART_ROUTING_PATH`	`$smart`	智能路由路径段，例如 `my_smart` 对应 `/mcp/my_smart`。允许 1–64 位英文字母、数字、连字符和下划线；修改后重启生效。旧 `$smart` 地址继续可用，服务器名、分组名及分组 ID 不得与配置值冲突。
`READONLY`	`false`	设置为 `true` 以启用只读模式
`MCPHUB_SETTING_PATH`		MCPHub 设置文件的路径
`INSTALL_BASE_URL`	`http://localhost:3000`	当 `systemConfig.install.baseUrl` 未设置时使用的公网安装地址。Dashboard/API 中显式保存的 Base URL 优先于该环境变量，适合 Docker/Kubernetes 等声明式部署和 OAuth 回调地址。
`NODE_ENV`	`development`	应用程序环境 (`development`, `production`, `test`)

PORT=3000
DEFAULT_REQUEST_TIMEOUT=60000
INIT_TIMEOUT=300000
STARTUP_CONNECT_CONCURRENCY=0
BASE_PATH=/api
READONLY=true
MCPHUB_SETTING_PATH=/path/to/settings
INSTALL_BASE_URL=https://mcphub.example.com
NODE_ENV=production

认证与安全

JWT 配置

变量	默认值	描述
`ADMIN_PASSWORD`	`pnpm dev` 中为 `admin123`，其他启动随机生成	首次启动且没有用户时用于创建 `admin` 用户的密码。未设置时，`pnpm dev` 使用 `admin123`；其他启动会生成随机密码并输出到日志。
`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 现在按以下优先级解析：

BETTER_AUTH_* 环境变量
systemConfig.auth.betterAuth（来自 mcp_settings.json 或数据库系统配置）
内置默认值

Provider 的客户端凭据仍然只支持通过环境变量提供。 MCPHub 里的 Better Auth 目前依赖 PostgreSQL 会话存储，因此需要配置 DB_URL；纯文件模式不支持 Better Auth 登录。

变量	描述
`BETTER_AUTH_ENABLED`	Better Auth 总开关。即使打开了它，如果 MCPHub 不在数据库模式下，或者没有任何提供商具备所需凭据，Better Auth 仍会自动禁用。
`BETTER_AUTH_URL`	用于生成 Better Auth 回调 URL 的公网访问地址。优先级高于 `systemConfig.auth.betterAuth.baseUrl`（可在设置 → Better Auth 中配置）和 `systemConfig.install.baseUrl`，其来源也会自动加入可信来源列表。
`BETTER_AUTH_BASE_PATH`	Better Auth 处理器挂载路径，默认 `/api/auth/better`。
`BETTER_AUTH_TRUSTED_ORIGINS`	允许发起 Better Auth 登录流程的额外来源。支持逗号分隔、空白分隔或 JSON 数组。未设置时，MCPHub 仍会自动信任 `BETTER_AUTH_URL` 和 `systemConfig.install.baseUrl` 的来源。
`BETTER_AUTH_DISABLE_PASSWORD_LOGIN`	在至少启用一个 SSO 提供商（且启动时已启用）时关闭用户名/密码登录（`POST /api/auth/login` 和登录表单）。在两个方向上都优先于已保存的 `disablePasswordLogin` 设置，因此当身份提供商不可用时，设为 `false` 即可恢复。默认 `false`。
`BETTER_AUTH_GOOGLE_ENABLED`	在提供了凭据后启用或禁用 Google 登录，默认 `true`。
`GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET`	Google 登录凭据。
`BETTER_AUTH_GITHUB_ENABLED`	在提供了凭据后启用或禁用 GitHub 登录，默认 `true`。
`GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET`	GitHub 登录凭据。
`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_URL`	`BETTER_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

转发认证

转发认证信任上游网关签发给用户的 JWT，并使用身份提供方的 JWKS 进行验证。行为说明参见认证 → 转发认证。取值优先级：FORWARD_AUTH_* 环境变量，其次为 systemConfig.auth.forwardAuth，最后为内置默认值。配置在每次请求时读取，无需重启。

变量	说明
`FORWARD_AUTH_ENABLED`	启用转发认证。默认 `false`。
`FORWARD_AUTH_MODE`	验证模式，目前仅支持 `jwks`。
`FORWARD_AUTH_JWKS_URI`	身份提供方的 JWKS 端点。必须为 `https`（仅 `localhost` 允许 `http`）。必填。
`FORWARD_AUTH_ISSUER`	期望的 `iss` 声明。必填。
`FORWARD_AUTH_AUDIENCE`	接受的 `aud` 值，支持逗号分隔或 JSON 数组；值中可以包含空格。必填。
`FORWARD_AUTH_ALGORITHMS`	允许的非对称算法，默认 `RS256,ES256`。永远不接受 `HS*` 和 `none`。
`FORWARD_AUTH_TOKEN_HEADER`	携带 JWT 的请求头，可为原始 JWT 或 `Bearer <jwt>`（例如 `Cf-Access-Jwt-Assertion`）。默认使用 Bearer 认证请求头。
`FORWARD_AUTH_USERNAME_CLAIM`	新建用户的用户名所用声明，默认 `preferred_username`。
`FORWARD_AUTH_EMAIL_CLAIM`	新建用户的邮箱所用声明，默认 `email`。
`FORWARD_AUTH_AUTO_CREATE`	为新身份创建非管理员本地用户，默认 `true`。

智能路由与嵌入

智能路由使用 PostgreSQL + pgvector 和嵌入服务，对上游工具执行向量搜索。启用智能路由至少需要配置 DB_URL、OpenAI 兼容嵌入服务和开关变量。

变量	默认值	描述
`SMART_ROUTING_ENABLED`	`false`	智能路由的规范总开关。`ENABLE_SMART_ROUTING` 仍作为旧版兼容别名；两者同时设置时，以本变量为准。
`SMART_ROUTING_EMBEDDING_PROVIDER`	`openai`	嵌入提供商，目前支持 `openai` 和 `azure_openai`。
`SMART_ROUTING_EMBEDDING_ENCODING_FORMAT`	`auto`	覆盖发送给嵌入 API 的 `encoding_format`。
`SMART_ROUTING_BASE_PACING_DELAY_MS`	`0`	嵌入请求之间的基础等待时间（毫秒）。
`SMART_ROUTING_PROGRESSIVE_DISCLOSURE`	`false`	是否启用渐进式工具信息披露。
`SMART_ROUTING_SERVER_DESCRIPTION_MODE`	`names`	`search_tools` 中服务器信息的展示方式：`names` 或 `full`。
`EMBEDDING_MODEL`	`text-embedding-3-small`	嵌入模型名称。`OPENAI_API_EMBEDDING_MODEL` 仍作为旧版兼容别名；两者同时设置时，以本变量为准。
`EMBEDDING_DIMENSIONS`	未设置	支持该参数的提供方可使用的嵌入输出维度；未设置时使用提供方的模型默认值。
`EMBEDDING_DIMENSIONS_API_PASSTHROUGH`	`false`	设为 `true` 时，始终将 `embeddingDimensions` 作为 `dimensions` 请求参数转发给提供方。默认情况下 MCPHub 仅对已知支持 Matryoshka（MRL）表示的模型（`text-embedding-3-`、`gemini-embedding-`）转发 `dimensions`；许多开源模型/后端（Qwen3-Embedding、BGE、vLLM/sglang 等）会直接拒绝该参数（issue #1131）。仅对其它支持 MRL 的模型开启。
`EMBEDDING_MAX_TOKENS`	按模型决定	生成嵌入前的最大 token 数。
`SMART_ROUTING_EMBEDDING_QUERY_PREFIX`	空	嵌入前添加到 `search_tools` 查询开头的任务前缀（如 EmbeddingGemma 的 `task: search result \| query:` ），按原样使用，包括末尾空格。
`SMART_ROUTING_EMBEDDING_DOCUMENT_PREFIX`	空	嵌入前添加到工具和服务器文档开头的任务前缀（如 EmbeddingGemma 的 `title: none \| text:` ）。修改后会重新生成所有服务器的嵌入。
`SMART_ROUTING_SIMILARITY_THRESHOLD`	未设置	`search_tools` 结果的最低查询-工具相似度（0-1）。未设置时按查询长度启发式决定（0.2 / 0.3 / 0.4）。
`SMART_ROUTING_FULL_SCHEMA_TOP_N`	未设置	只有前 N 个 `search_tools` 结果带完整定义；其余结果只有名称、描述和分数，并列出 `describe_tool` 以获取完整定义。未设置时返回全部完整结果。启用渐进式披露时忽略。
`SMART_ROUTING_TOOL_DEFINITION_FIELDS`	`title,annotations`	以逗号分隔的可选工具字段，完整的 `search_tools` 结果和 `describe_tool` 会在名称、描述和 `inputSchema` 之外附带：`title`、`annotations`、`outputSchema`、`execution`、`icons`、`_meta`。`none` 表示都不附带。

OpenAI 或兼容服务

变量	描述
`DB_URL`	PostgreSQL 连接 URL；数据库需要启用 `pgvector` 扩展。
`OPENAI_API_KEY`	OpenAI 或兼容嵌入服务的 API 密钥。
`OPENAI_API_BASE_URL`	OpenAI 兼容 API 的 Base URL，例如 LocalAI 或其他兼容服务。

Azure OpenAI

变量	描述
`AZURE_OPENAI_API_KEY`	Azure OpenAI API 密钥。
`AZURE_OPENAI_ENDPOINT`	Azure OpenAI 资源地址。
`AZURE_OPENAI_API_VERSION`	Azure OpenAI API 版本。
`AZURE_OPENAI_EMBEDDING_DEPLOYMENT`	Azure 中的嵌入 deployment 名称。
`AZURE_OPENAI_EMBEDDING_MODEL`	deployment 背后的实际 OpenAI 模型名称，用于 tokenizer 和 token 上限选择。

环境变量优先于面板配置。 上表中的每个变量都会覆盖 Dashboard 中保存的同名字段。解析顺序为 环境变量 → 面板配置 → 内置默认值。因此 .env 里遗留的旧值会静默覆盖你刚在面板里填入的密钥：嵌入请求会以鉴权失败告终，而界面上仍然显示着新密钥（issue #642）。面板现在会提示这一点：受影响字段下方会显示警告，并指出实际生效的环境变量名。若要让面板配置生效，请从环境中移除该变量并重启。「智能路由 → 启用」与「数据库 URL」同样遵循该顺序，但面板会直接反映环境变量的结果，而不是显示警告：开关会跟随环境变量，URL 字段会显示 ${DB_URL} 占位符。

配置示例

开发环境

# .env（开发环境）
NODE_ENV=development
PORT=3000

# 认证
JWT_SECRET=dev-secret-key

生产环境

# .env（生产环境）
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 启动时只读取工作目录下的 .env 一个文件，不会读取 .env.local 或 .env.{NODE_ENV}（例如 .env.production）。进程环境中已经存在的变量（shell、Docker 的 -e / env_file、Kubernetes 清单等）优先，.env 不会覆盖它们。 .env 中的值按原样使用，其中的 ${VAR} 引用不会被展开。mcp_settings.json 支持 ${VAR} 展开，参见 MCP 设置。

安全最佳实践

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

自定义智能路由地址

例如配置 PORT=6001、BASE_PATH=/mcp_manage 和 SMART_ROUTING_PATH=my_smart 后，Streamable HTTP 连接地址为 http://localhost:6001/mcp_manage/mcp/my_smart。追加 /<group> 可限定到分组；在 /mcp 前加 /<user> 可使用用户范围路由。旧版客户端使用的 /sse 同样支持该别名。配置的路径段将保留给智能路由。启动时若存在同名服务器、分组或分组 ID，将明确报错；后续配置写入也拒绝新增冲突。请先修改路径段或重命名冲突目标。修改路径段后需要重启，并更新使用旧自定义地址的客户端；$smart 始终保留兼容，CLI 也继续使用该入口。此配置不改变鉴权和权限范围。

开始使用

核心功能

配置指南

环境变量

环境变量

核心应用设置

服务器配置

认证与安全

JWT 配置

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

转发认证

智能路由与嵌入

OpenAI 或兼容服务

Azure OpenAI

配置示例

开发环境

生产环境

Docker 环境

环境变量加载

安全最佳实践

自定义智能路由地址

​环境变量

​核心应用设置

​服务器配置

​认证与安全

​JWT 配置

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

​转发认证

​智能路由与嵌入

​OpenAI 或兼容服务

​Azure OpenAI

​配置示例

​开发环境

​生产环境

​Docker 环境

​环境变量加载

​安全最佳实践

​自定义智能路由地址

环境变量

核心应用设置

服务器配置

认证与安全

JWT 配置

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

转发认证

智能路由与嵌入

OpenAI 或兼容服务

Azure OpenAI

配置示例

开发环境

生产环境

Docker 环境

环境变量加载

安全最佳实践

自定义智能路由地址