LobeHub 怎么通过 FEATURE_FLAGS 环境变量控制功能开关？

自托管部署 LobeHub 时，你可能会遇到这类需求：不想让用户看到欢迎建议，或者想开放默认关闭的 API 密钥管理页面。LobeHub 提供了 FEATURE_FLAGS 环境变量来统一控制这些功能开关——所有功能特性都通过这唯一的特性标志配置变量来启停，不需要改代码。本文介绍它的取值语法、完整配置项列表，以及在部署时如何传入并在界面中确认开关生效。

FEATURE_FLAGS 的取值语法

FEATURE_FLAGS 是一个可选的环境变量，默认值为 -（即不配置，所有功能均采用各自默认值）。取值规则（来自 特性标志文档）：

• 使用 + 前缀启用一个功能，- 前缀关闭一个功能，例如 +api_key_manage、-welcome_suggest；
• 多个功能标志之间使用英文逗号 , 隔开；
• 整个值最外层建议加上引号 "，避免解析错误。

文档给出的示例是：

"-welcome_suggest"

按同样语法可以组合多个开关，例如：

"-welcome_suggest,+api_key_manage"

以上为示例取值，其中两个标志均出自下方配置项表。

有两点需要特别注意：

1. 不支持 all 关键字。与 OPENAI_MODEL_LIST 变量不同，FEATURE_FLAGS 不能一次性接管全部标志；未显式配置的标志会保持各自的默认值，需要手动逐个控制。
2. 引号不要省，否则值可能被解析错误。

在部署时配置

在 Docker 部署中，Dockerfile 在构建阶段声明了 FEATURE_FLAGS 构建参数（ARG FEATURE_FLAGS），并在最终运行阶段将其重置为空字符串。也就是说镜像内该变量默认为空，你在容器启动时通过环境变量传入即可，运行时传入的值会生效。

常见的两种传入方式：

# docker-compose 示例：在 LobeHub 服务的 environment 中追加
environment:
  - FEATURE_FLAGS="-welcome_suggest,+api_key_manage"

# docker run 示例：<你的LobeHub镜像> 替换为你实际部署使用的镜像地址
docker run -d \
  -p 3210:3210 \
  -e FEATURE_FLAGS="-welcome_suggest,+api_key_manage" \
  <你的LobeHub镜像>

其中端口 3210 取自 Dockerfile 中 PORT="3210" 的默认值。环境变量在容器创建时生效，修改配置后需要按你现有方式重建/重启容器。项目内置的部署编排文件可参考 docker-compose/deploy/docker-compose.yml，在其中的 LobeHub 服务上追加同样的 environment 条目即可。

可配置的功能标志列表

特性标志文档 列出的配置项及默认值如下：

配置项	解释	默认值
check_updates	允许检查更新。	开启
provider_settings	控制模型供应商设置的显示。	开启
openai_api_key	允许用户自定义 OpenAI API Key。	开启
openai_proxy_url	允许用户自定义 OpenAI 代理 URL。	开启
api_key_manage	控制 API 密钥管理页面 (/profile/apikey) 的访问。	关闭
edit_agent	允许用户编辑助手。	开启
ai_image	控制 AI 图像生成功能和页面 (/image)。	开启
speech_to_text	启用语音转文本功能。	开启
token_counter	保留用于令牌计数器显示。	开启
welcome_suggest	显示欢迎建议。	开启
changelog	控制更新日志弹窗 / 页面的显示。	开启
market	启用助手市场功能。	开启
knowledge_base	启用知识库功能。	开启
rag_eval	控制 RAG 评估功能 (/repos/[id]/evals)。	关闭
cloud_promotion	控制用户菜单中云服务推广链接的显示。	关闭
commercial_hide_github	隐藏设置页面底部的 GitHub 相关链接（需要商业授权）。	关闭
commercial_hide_docs	隐藏文档和帮助菜单，包括更新日志、文档和反馈（需要商业授权）。	关闭

文档同时指出：最新的特性标志列表以 featureFlags 定义 为准。该文件中还定义了上表之外的标志，例如 agent_share、voice_dictation、workspace、auth_captcha 等；其中 agent_self_iteration、agent_onboarding、dev_dock、onboarding_v2、workspace 的默认值取决于是否处于开发环境（development）。另外 commercial_hide_github、commercial_hide_docs 两个标志仅限商业授权使用。

从 解析实现 可以看到两个行为细节：

• 解析时会把中文逗号替换为英文逗号再按逗号拆分，所以分隔符写错成中文逗号不会直接报错；
• 值只支持布尔开关（+/-）。不在 schema 中的标志名，或只接受用户 ID 数组的标志（如 dev_dock_workspaces），不会被布尔值覆盖，相当于被忽略。

验证开关是否生效

环境变量本身没有专门的查询接口，验证方式是核对 特性标志文档 表格中各标志"控制"的界面入口在重启后是否按预期出现或消失：

• -welcome_suggest：首页不再显示欢迎建议；
• -ai_image：AI 图像生成功能和 /image 页面入口消失；
• +api_key_manage：可以访问默认关闭的 API 密钥管理页面 /profile/apikey；
• -changelog：更新日志弹窗 / 页面不再显示；
• -market：助手市场入口消失。

判断基准就是上表的默认值：如果你没有设置 FEATURE_FLAGS，界面表现应与"默认值"一列一致；设置后，被 +/- 显式控制的条目应发生翻转，未列出的条目保持默认。

限制与注意

• FEATURE_FLAGS 不支持 all 关键字，未列出的标志一律保持默认值，必须逐个手动控制。
• 多标志值要加引号、用英文逗号分隔（中文逗号虽能被解析，仍建议遵循文档写法）。
• commercial_hide_github、commercial_hide_docs 需要商业授权，自托管场景下不要依赖它们实现隐藏。
• schema 注释 说明 agent_share 是仅云端的灰度开关，自托管构建在服务端被 ENABLE_BUSINESS_FEATURES 硬性拦截，在自托管环境配置该标志不会启用对应功能。
• 功能标志的完整清单随版本演进，部署前以 featureFlags schema 和 基础环境变量文档 中的说明为准。