环境变量
LobeHub 在部署时提供了一些额外的配置项,你可以使用环境变量进行自定义设置。
通用变量
KEY_VAULTS_SECRET
- 类型:可选
- 描述:添加访问 LobeHub 服务的密码,你可以设置一个长密码以防被爆破
- 默认值:-
- 示例:
Kix2wcUONd4CX51E/ZPAd36BqM4wzJgKjPtz2sGztqQ=
此密钥用于加密敏感数据,一旦设置后请勿更改,否则已加密的数据将无法解密。
KEY_VAULTS_SECRET='点击按钮生成'API_KEY_SELECT_MODE
- 类型:可选
- 描述:用于控制多个 API Keys 时,选择 Key 的模式,当前支持
random和turn - 默认值:
random - 示例:
random或turn
使用 random 模式下,将在多个 API Keys 中随机获取一个 API Key。
使用 turn 模式下,将按照填写的顺序,轮询获取得到 API Key。
DEFAULT_AGENT_CONFIG
- 类型:可选
- 描述:用于配置 LobeHub 默认助理的默认配置。它支持多种数据类型和结构,包括键值对、嵌套字段、数组值等。
- 默认值:
- - 示例:
'model=gpt-4o;params.max_tokens=300;plugins=search-engine,lobe-image-designer'
DEFAULT_AGENT_CONFIG 用于配置 LobeHub 默认助理的默认配置。它支持多种数据类型和结构,包括键值对、嵌套字段、数组值等。下表详细说明了 DEFAULT_AGENT_CONFIG 环境变量的配置项、示例以及相应解释:
| 配置项类型 | 示例 | 解释 |
|---|---|---|
| 基本键值对 | model=gpt-4 | 设置模型为 gpt-4。 |
| 嵌套字段 | tts.voice.openai=nova | 设置 OpenAI 文本转语音的默认音色为 nova。 |
| 数组 | plugins=search-engine,lobe-image-designer | 启用 search-engine 和 lobe-image-designer 插件。 |
| 中文逗号 | plugins=search-engine,lobe-image-designer | 同上,演示支持中文逗号分隔。 |
| 多个配置项 | model=glm-4;provider=zhipu | 设置模型为 glm-4 且模型服务商为 zhipu。 |
| 数字值 | params.max_tokens=300, chatConfig.historyCount=5 | 设置最大令牌数为 300,设置历史消息条数为 5。 |
| 布尔值 | chatConfig.enableHistoryCount=true,chatConfig.enableCompressThreshold=true, chatConfig.enableStreaming=true | 启用历史消息数量限制,历史长度压缩阈值,流式输出。 |
| 特殊字符 | inputTemplate="Hello; I am a bot;" | 设置输入模板为 Hello; I am a bot;。 |
| 错误处理 | model=gpt-4;maxToken | 忽略无效条目 maxToken,仅解析出 model=gpt-4。 |
| 值覆盖 | model=gpt-4;model=gpt-4o | 如果键重复,使用最后一次出现的值,此处 model 的值为 gpt-4o。 |
相关阅读:
SYSTEM_AGENT
- 类型:可选
- 描述:用于配置 LobeHub 系统助手(如主题生成、翻译等功能)的模型和供应商。
- 默认值:
- - 示例:
default=ollama/deepseek-v3或topic=openai/gpt-4,translation=anthropic/claude-sonnet-4-5-20250929
SYSTEM_AGENT 环境变量支持两种配置方式:
- 使用
default=供应商/模型为所有系统助手设置相同的默认配置 - 针对特定的系统助手进行单独配置,格式为
助手名称=供应商/模型
配置项说明:
| 配置项 | 格式 | 解释 |
|---|---|---|
| 默认设置 | default=ollama/deepseek-v3 | 为所有系统助手设置默认模型为 ollama 的 deepseek-v3 |
| 特定设置 | topic=openai/gpt-4 | 为主题生成设置特定的供应商和模型 |
| 混合配置 | default=ollama/deepseek-v3,topic=openai/gpt-4 | 先为所有助手设置默认值,然后针对特定助手进行覆盖 |
可配置的系统助手及其作用:
| 系统助手 | 键名 | 作用描述 |
|---|---|---|
| 主题生成 | topic | 根据聊天内容自动生成主题名称和摘要 |
| 翻译 | translation | 文本翻译使用的助手 |
| 元数据生成 | agentMeta | 为助手生成描述性信息和元数据 |
| 分支对话 | thread | 自动生成分支对话的标题 |
| 图片生成命名 | generationTopic | AI 图片自动命名话题 |
| 输入自动补全 | inputCompletion | 输入自动补全建议(类似 GitHub Copilot 幽灵文本) |
| 提示词重写 | promptRewrite | 生成前优化提示词 |
| 图片生成命名 | generationTopic | AI 图片自动命名话题 |
FEATURE_FLAGS
- 类型:可选
- 描述:用于控制 LobeHub 的特性功能,支持多个功能标志,使用
+增加一个功能,使用-来关闭一个功能,多个功能标志之间使用英文逗号,隔开,最外层建议添加引号"以避免解析错误。 - 默认值:
- - 示例:
"-welcome_suggest"
具体的内容可以参见 特性标志 中的说明。
ENABLE_AGENT_GATEWAY
- 类型:可选
- 描述:为自托管部署启用 Gateway Mode。仅在同时配置
AGENT_GATEWAY_URL时生效。 - 默认值:
0 - 示例:
1
商业版本会自动启用 Gateway Mode。自托管部署可以同时设置 ENABLE_AGENT_GATEWAY=1 和 AGENT_GATEWAY_URL,让客户端显示 Gateway Mode。
AGENT_GATEWAY_URL
- 类型:可选
- 描述:Agent Gateway 端点,用于让 Gateway Mode 通过后端运行支持的助理任务。浏览器会向该地址建立 WebSocket 连接,因此必须能被浏览器访问。
- 默认值:-
- 示例:
https://agent-gateway.example.com
AGENT_GATEWAY_PROTOCOL
- 类型:可选
- 描述:客户端可以使用的 Agent Gateway 协议版本。
1是按运行建连的 WebSocket(GET /ws),也就是lobehub/lobehub-gateway提供的那个;2额外提供按用户复用的连接(GET /v2/ws)。自托管部署默认为1—— 网关没有/v2/ws时,客户端会一直拨不通,直到回退才能恢复流式输出。只有当你运行的网关确实提供/v2/ws时才需要设置。 - 默认值:
1 - 示例:
2
AGENT_GATEWAY_INTERNAL_URL
- 类型:可选
- 描述:服务端访问 Agent Gateway 使用的地址。当 LobeHub 服务端无法直接访问
AGENT_GATEWAY_URL时配置,例如使用 Docker Compose 服务名。未设置时回退到AGENT_GATEWAY_URL。 - 默认值:-
- 示例:
http://gateway:8787
AGENT_GATEWAY_SERVICE_TOKEN
- 类型:可选
- 描述:Agent Gateway 验证 Token,用于 Gateway Mode 与自部署 Agent Gateway 的鉴权
- 默认值:-
- 示例:
dev-secret
DEVICE_GATEWAY_URL
- 类型:可选
- 描述:服务端访问设备网关的内部地址,不会下发给客户端。
- 默认值:-
- 示例:
http://gateway:8788
DEVICE_GATEWAY_PUBLIC_URL
- 类型:可选
- 描述:桌面端和 CLI 自动获取的设备网关地址。不配置时可在客户端手动指定。使用不带
/ws后缀的 HTTP 或 HTTPS 地址,不含账号密码、查询参数或#片段。 - 默认值:-
- 示例:
https://device-gateway.example.com或http://your_server_ip:8788
PROXY_URL
- 类型:可选
- 描述:用于指定连接到外部服务的代理 URL。该变量的值在不同的部署环境中应该有所不同。
- 默认值:-
- 示例:
http://127.0.0.1:7890或socks5://localhost:7891
Docker Desktop 在 Windows 和 macOS 上走的是虚拟机方案,如果是 localhost / 127.0.0.1
是走到自身容器的 localhost,此时请尝试用 host.docker.internal 替代 localhost。 使用
http://user:password@127.0.0.1:7890 来连接到带认证的代理服务器。
SSRF_ALLOW_PRIVATE_IP_ADDRESS
- 类型:可选
- 描述:控制是否允许连接私有 IP 地址。设置为
1时将关闭 SSRF 防护并允许所有私有 IP 地址。在可信环境(如内网部署)中,可以启用此选项以访问内部资源。 - 默认值:
0 - 示例:
1或0
安全提示:启用此选项将关闭 SSRF 防护,允许连接私有 IP 地址段(127.0.0.0/8、10.0.0.0/8、172.16.0.0/12、192.168.0.0/16 等)。仅在需要访问内网资源的可信环境中启用。
应用场景:
LobeHub 会在以下场景执行 SSRF 安全检查:
-
图片 / 视频 URL 转 Base64:在处理媒体消息时(例如视觉模型、多模态模型),LobeHub 会将图片和视频 URL 转换为 base64 格式。此检查可防止恶意用户通过媒体 URL 访问内网资源。
举例:
- 图片:用户发送图片消息,URL 为
http://192.168.1.100/admin/secrets.png - 视频:用户发送视频消息,URL 为
http://10.0.0.50/internal/meeting.mp4
若无 SSRF 防护,这些请求可能导致内网资源泄露。
- 图片:用户发送图片消息,URL 为
-
网页爬取:使用网页爬取功能获取外部内容时。
-
代理请求:代理外部 API 请求时。
-
HTTP MCP 服务器与连接器:服务端连接 Streamable HTTP 类型的 MCP 服务器或连接器时(包括其 OAuth 发现与令牌请求)。检查基于域名实际解析出的 IP,每次请求和重定向都会检查。未配置设备网关、需要直连本地网络中 MCP 服务器的自部署实例,需通过
SSRF_ALLOW_PRIVATE_IP_ADDRESS或SSRF_ALLOW_IP_ADDRESS_LIST放行;经桌面端在用户本机运行的 MCP 服务器不受影响。
配置示例:
SSRF_ALLOW_IP_ADDRESS_LIST
- 类型:可选
- 描述:允许访问的 IP 地址白名单,多个 IP 地址用逗号分隔。仅在
SSRF_ALLOW_PRIVATE_IP_ADDRESS为0时生效。使用此选项可以在保持 SSRF 防护的同时,允许访问特定的内网 IP 地址。 - 默认值:-
- 示例:
192.168.1.100,10.0.0.50,172.16.0.10
常见使用场景:
- 允许访问内网图片存储服务器:
192.168.1.100 - 允许访问内网 API 网关:
10.0.0.50 - 允许访问内网文档服务器:
172.16.0.10
ASSET_BASE_URL
- 类型:可选
- 描述:构建产物(Next.js 静态资源与 SPA 包)的基础 URL。设置为 CDN 或对象存储的域名,即可让构建产物不再由应用自身分发。它对应 Next.js 的 assetPrefix。不设置时,所有资源仍由应用同源提供。
- 默认值:-
- 示例:
https://cdn.example.com
当它指向与应用不同的域名时,该资源域名必须返回覆盖应用域名的 Access-Control-Allow-Origin
响应头。一旦配置了资源基础 URL,LobeHub 会在生成的 <script> 与 <link> 标签上带出
crossorigin;缺少该响应头会让浏览器拒绝执行这些资源,页面直接白屏。它同时也让这些文件的脚本报错能带着真实堆栈进入错误监控,而不是一条无信息的
Script error.。
NEXT_PUBLIC_ASSET_PREFIX
- 类型:可选,已废弃 —— 请改用
ASSET_BASE_URL - 描述:
ASSET_BASE_URL的旧名称。在未设置ASSET_BASE_URL时仍会作为回退生效,并且同样受上述跨域要求约束。 - 默认值:-
- 示例:
https://cdn.example.com
多模态理解
MULTIMODAL_UNDERSTANDING_PROVIDER
- 类型:可选
- 描述:兜底多模态理解模型的服务商 ID。与
MULTIMODAL_UNDERSTANDING_MODEL一起配置后,不具备原生音频、图片或视频理解能力的模型可以通过内置多模态理解工具分析上传的媒体。 - 默认值:-
- 示例:
openai、google或ollama
MULTIMODAL_UNDERSTANDING_MODEL
- 类型:可选
- 描述:内置多模态理解工具使用的模型 ID。该模型应支持你希望分析的媒体类型。仅当
MULTIMODAL_UNDERSTANDING_PROVIDER与MULTIMODAL_UNDERSTANDING_MODEL同时配置时,此功能才会启用。 - 默认值:-
- 示例:
gemini-2.5-flash或你的本地多模态模型 ID
MULTIMODAL_UNDERSTANDING_IMAGE_FORMATS
- 类型:可选
- 描述:兜底多模态理解模型支持的图片格式,使用英文逗号分隔。可填写
jpeg、png、webp或对应的 MIME 类型。系统优先根据 URL 后缀判断格式;不支持的格式会在发送给模型前转换为列表中的第一个格式。URL 没有可识别的后缀时,系统会下载图片后识别格式。 - 默认值:
jpeg,png - 示例:
png,jpeg,webp
配置示例:
为兼容迁移,旧环境变量 VISUAL_UNDERSTANDING_PROVIDER 和 VISUAL_UNDERSTANDING_MODEL 仍可继续使用。同时配置新旧变量时,MULTIMODAL_UNDERSTANDING_* 优先。
启用后,当当前模型没有对应的原生多模态能力但支持工具调用时,用户仍可上传音频、图片或视频,并由兜底多模态理解模型进行分析。文件上传本身仍需要部署中正常配置文件存储能力。
AI 图像
AI_IMAGE_DEFAULT_IMAGE_NUM
- 类型:可选
- 描述:设置 AI 图像生成的默认图片数量。用户仍可在个人设置中覆盖此值。
- 默认值:
2 - 示例:
6 - 范围:
1-20
此环境变量允许管理员为其部署自定义默认图片生成数量。值必须在 1 到 20 之间。如果未设置,默认为 2。用户仍可在个人设置中调整此值。
插件服务
TOOL_NAME_MAX_LENGTH
- 类型:可选
- 描述:函数调用工具名超过该长度后会被压缩为不可读的
MD5HASH_…。OpenAI 限制函数名不超过 64 字符,而没有该限制的模型只会白白损失可读性,因此该阈值可配置。设为0可完全关闭基于长度的压缩,保留完整可读的工具名。包含服务商不接受字符(非 ASCII、点、空格等)的名称仍会被哈希,不受该配置影响。 - 默认值:
64 - 示例:
0 - 说明:未设置、非法或负数时回退为默认值。
PLUGINS_INDEX_URL
- 类型:可选
- 描述:LobeHub 插件市场的索引地址,如果你自行部署了插件市场的服务,可以使用该变量来覆盖默认的插件市场地址
- 默认值:
https://registry.npmmirror.com/@lobehub/plugins-index/v1/files/public
PLUGIN_SETTINGS
- 类型:可选
- 描述:用于配置插件的设置,使用
插件名:设置字段=设置值的格式来配置插件的设置,多个设置字段用英文分号;隔开,多个插件设置使用英文逗号,隔开。 - 默认值:
- - 示例:
search-engine:SERPAPI_API_KEY=xxxxx,plugin-2:key1=value1;key2=value2
上述示例表示设置 search-engine 插件的 SERPAPI_API_KEY 为 xxxxx,设置 plugin-2 的 key1 为 value1,key2 为 value2。生成的插件设置配置如下:
助手市场
AGENTS_INDEX_URL
- 类型:可选
- 描述:LobeHub 助手市场的索引地址,如果你自行部署了助手市场的服务,可以使用该变量来覆盖默认的市场地址
- 默认值:
https://registry.npmmirror.com/@lobehub/agents-index/v1/files/public