Onyx 4.9.3 配置参数详解

目标：系统讲清 Onyx 4.9.3 的配置体系——配置文件位置、查看与修改生效方式、全部核心环境参数的分类逐项详解（含默认值与改动影响），并给出可直接落地的生产配置模板。参数语义与默认值来自官方 env.template（4.9.3 版）实查与实测环境验证，已在 Ubuntu 22.04 + Onyx 4.9.3 标准版实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64）
• Onyx 版本：4.9.3（Compose 项目名 onyx-4.9.3-stack，11 个服务）
• Docker 29.8.0 / Docker Compose v5.5.1
• 配置文件：部署目录下 .env（由官方 env.template 复制而来，官方模板共 470 余行，覆盖全部可调项）
• 演示管理账号：admin@example.com，密码 q1w2e3r4
• 安装过程见 《Ubuntu 22.04 安装 Onyx 4.9.3 指南》，产品背景与选型见 《Onyx 介绍与选型指南》

二、前置条件

• 已按安装篇完成 Onyx 4.9.3 标准版部署并验证 http://<服务器IP>:3000/api/health 返回 {"success":true,...}。
• 能进入部署目录（手动方案为 onyx/deployment/docker_compose，脚本方案为 ~/.config/onyx 下 onyx-cli 生成的目录），并确认其中存在 .env 与 docker-compose.yml：

cd onyx/deployment/docker_compose && ls -la .env docker-compose.yml

输出节选（实测）：

-rw-r--r-- 1 root root 20700 Oct 22 16:04 .env
-rw-r--r-- 1 root root 23455 Oct 22 16:03 docker-compose.yml

三、参数查看与修改方式

Onyx 的服务级配置集中在 .env 一处：Compose 文件为每个服务声明 env_file: .env，同一份参数注入全部 11 个服务。理解三个要点即可掌握其配置体系：

1. 单文件生效：.env 是唯一的事实来源；Compose 文件头部标注「THIS FILE IS GENERATED - DO NOT EDIT DIRECTLY」（由 docker-compose.template.yml 生成），不要直接改 Compose。
2. 模板即文档：env.template 内每项参数都带官方注释（语义、默认值、安全提示），改前先查模板。
3. 重建生效：修改 .env 后必须重建对应服务才生效（env_file 只在容器创建时注入）。

3.1 查看参数（两种视角）

查看宿主侧配置文件：

grep -E '^(IMAGE_TAG|LOG_LEVEL|FILE_STORE_BACKEND)=' .env

输出（实测）：

IMAGE_TAG=latest
LOG_LEVEL=info
FILE_STORE_BACKEND=s3

查看运行中容器实际生效的参数（以 api_server 为准，容器内视角）：

docker compose exec -T api_server sh -c "env | grep -E '^(LOG_LEVEL|FILE_STORE_BACKEND|POSTGRES_HOST|REDIS_HOST|MODEL_SERVER_HOST|IMAGE_TAG|COMPOSE_PROFILES)' | sort"

输出（实测）：

COMPOSE_PROFILES=s3-filestore
FILE_STORE_BACKEND=s3
IMAGE_TAG=latest
LOG_LEVEL=info
MODEL_SERVER_HOST=inference_model_server
POSTGRES_HOST=relational_db
REDIS_HOST=cache

3.2 修改参数与重建生效

以把全局日志级别从 info 改为 warning 为例，标准操作链为「改文件 → 重建目标服务 → 验证」：

# 1. 修改参数
sed -i 's|^LOG_LEVEL=.*|LOG_LEVEL=warning|' .env
# 2. 重建引用该参数的服务（该参数影响全部服务时逐个重建，或 up -d 全量滚动）
docker compose up -d api_server
# 3. 验证生效
docker compose exec -T api_server sh -c 'echo $LOG_LEVEL'

第三步输出（实测）：

warning

⚠️ 注意：USER_AUTH_SECRET、POSTGRES_PASSWORD、MINIO_ROOT_PASSWORD 这类「创建时就固化进数据」的参数，事后修改可能导致新旧组件凭据不一致（如已生成的会话令牌失签、数据库口令不匹配）。改它们等于重置对应子系统，务必先备份。

四、参数总览

官方模板按用途分区，下表为全部参数族的地图（后文按族展开详解）：

五、核心参数分类详解

5.1 版本与部署形态

IMAGE_TAG（默认 latest）：Onyx 全部应用镜像的版本标签。生产建议钉住具体版本（如 v4.9.3）。每个标签另有 -dev 孪生标签（如 latest-dev），仅 backend 镜像有差异——额外内置 vim/curl/psql 等调试工具，排障时临时换用很方便。

CODE_INTERPRETER_IMAGE_TAG（默认随 Compose 钉在 0.4.8）：代码解释器沙箱独立发布线，不受 IMAGE_TAG 控制，一般不动。

ENABLE_CRAFT（默认关闭）：开启 Onyx Craft（AI 生成 Web 应用能力），需 Business/Enterprise 许可，Community Edition 只显示升级页。开启时由安装器 --include-craft 或叠加 docker-compose.craft.yml 完成，配套的沙箱资源限制用 SANDBOX_DOCKER_MEMORY_LIMIT（默认 2g）与 SANDBOX_DOCKER_CPU_LIMIT（默认 1.0）控制。

ONYX_AIRGAPPED（默认空=联网）：设为 true 后禁用对 Onyx 官方端点的出站调用（推荐模型清单同步、远程模型目录查询），入站与用户自配的集成不受影响——离线（气隙）部署必开。

COMPOSE_PROFILES（默认 s3-filestore）：Compose profile 开关，决定是否拉起 MinIO 服务。改用 Postgres 存文件时：从该值移除 s3-filestore 并设 FILE_STORE_BACKEND=postgres；用 GCS/Azure 时同样移除并切 FILE_STORE_BACKEND。

5.2 认证与会话安全

USER_AUTH_SECRET（默认空串，必填）：签署密码重置、邮箱验证令牌、OAuth 登录状态与验证码 Cookie 的密钥。4.9.x 的 api_server 启动时强制校验，为空直接拒绝启动（错误原文与排障实录见安装篇第十章问题 1）。生成方式官方注释明示：

openssl rand -hex 32

输出（实测，生成 64 位十六进制随机串；下例为演示值，请勿复用，须使用自己机器上生成的新值）：

c331e2d70eb1548561e0291ace6577c7a5fd5c79b44bbbe41f87852e6930f7b0

💡 说明：密钥必须由自己机器上 openssl rand -hex 32 现场生成，不得写入代码仓库或对外泄露——持有该值即可伪造密码重置令牌。

SESSION_EXPIRE_TIME_SECONDS（默认注释态，服务端内置默认值）：会话过期秒数。

ENCRYPTION_KEY_SECRET（默认注释态）：应用层数据加密密钥（官方注释建议生产设置）。

VALID_EMAIL_DOMAINS（默认空=不限）：逗号分隔的邮箱域白名单，如 onyx.app——设置后仅这些域可注册/登录，是自托管开放注册场景最实用的收紧手段。

USER_DIRECTORY_ADMIN_ONLY（默认关）：设 true 后 GET /users 仅管理员可用，普通用户无法枚举账号或对个人共享 Agent。

5.3 接口暴露与浏览器防护

METRICS_AUTH_TOKEN / DISABLE_METRICS_AUTH：/metrics 指标端点的 Bearer 令牌与「完全免认证」开关。默认二者都不设时 /metrics 返回 401（锁定），Prometheus 抓取需在 scrape 配置里带 authorization 头。

ENABLE_PUBLIC_DOCS（默认关）：设 true 才会注册 /openapi.json、/docs、/redoc 路由；关闭时这些路径是 404，API 面不对外暴露。

WEB_DOMAIN（默认空）：对外访问的基础 URL，用于重定向拼链。经反代或绑域名部署时必须设为完整外网地址。

WEB_FRAME_PROTECTION_ENABLED（默认 true）：防点击劫持（禁止 iframe 内嵌）。设 false 才允许任意来源 iframe 嵌入。

WEB_STRICT_CSP_ENABLED（默认关，设 true 启用）：严格 Content-Security-Policy（限制脚本加载与数据回传源）。

CORS_ALLOWED_ORIGIN（默认空）：允许跨域的来源列表；未设置时所有来源可发起请求，但带 Cookie 的跨域凭据请求被禁用。

5.4 文件存储（S3/MinIO、Postgres、GCS、Azure）

FILE_STORE_BACKEND（默认 s3）：文件原件存储后端，可选 s3（默认，配套 MinIO 服务）、postgres（复用关系库，省服务）、gcs、azure。

S3_ENDPOINT_URL / S3_AWS_ACCESS_KEY_ID / S3_AWS_SECRET_ACCESS_KEY / S3_FILE_STORE_BUCKET_NAME（默认 http://minio:9000 / minioadmin / minioadmin / onyx-file-store-bucket）：应用侧访问对象存储的四件套。官方注释明确：minioadmin 是本地开发默认，安装器会随机化；手改 .env 时四个值必须一起换，且 S3_AWS_* 与 MINIO_ROOT_* 保持一致（应用直接用 MinIO root 凭据）。

MINIO_ROOT_USER / MINIO_ROOT_PASSWORD（默认 minioadmin/minioadmin）：MinIO 服务自身凭据，生产必须改强口令。

GCS 族（GCS_FILE_STORE_BUCKET_NAME、GCS_PROJECT_ID、GCS_SERVICE_ACCOUNT_KEY_JSON 等）：用 Google Cloud Storage 时设置，凭据优先走 Application Default Credentials（GKE Workload Identity 等）。

Azure 族（AZURE_STORAGE_ACCOUNT_NAME、AZURE_STORAGE_CONNECTION_STRING 等）：凭据优先级为连接字符串 → 账户密钥 → DefaultAzureCredential。

5.5 关系数据库（PostgreSQL）

POSTGRES_USER / POSTGRES_PASSWORD（模板默认 postgres/password，实际部署安装器会随机化）：业务库凭据。

POSTGRES_HOST（默认 relational_db）：Compose 内部寻址用的服务名。接外部托管 PostgreSQL（如 RDS）时改为外部主机名，并同步调整 Compose 去掉内置库。

连接池族（默认注释态，服务端内置合理值）：POSTGRES_API_SERVER_POOL_SIZE（API 服务连接池）、POSTGRES_POOL_RECYCLE（连接回收秒数）、POSTGRES_TCP_KEEPALIVES 族（同步引擎的 TCP 保活，防止 PgBouncer/NLB 静默断连）。

TLS 族：POSTGRES_SSLMODE（libpq 词汇表：require/verify-ca/verify-full，前两者递进验证证书链，verify-full 额外校验主机名——官方推荐托管库用它）+ POSTGRES_SSLROOTCERT（CA 证书路径）；互相 TLS 另需 POSTGRES_SSLCERT/POSTGRES_SSLKEY。USE_IAM_AUTH=true（AWS IAM 数据库认证）时 TLS 配置被忽略。

5.6 服务指针与内部寻址

以下五个参数把各服务粘合成完整栈（实测容器内生效值见 3.1 节）：

💡 技术拓展：服务发现（服务间按名字互访）常见三种实现——

方式	原理	适用
平台内建 DNS（Compose/K8s）	服务名自动解析到当前实例	容器编排场景，Onyx 默认采用
配置中心（Consul/etcd）	集中注册与发现，支持健康剔除	多语言异构大规模集群
硬编码 VIP/负载均衡器	固定地址 + LB 后挂实例	传统部署

Onyx 标准部署依赖 Compose 内建 DNS，以上五个指针参数默认写服务名即可，只有接外部托管组件（云数据库/云缓存）时才改成外部地址。

5.7 反向代理超时

NGINX_PROXY_CONNECT_TIMEOUT / NGINX_PROXY_SEND_TIMEOUT / NGINX_PROXY_READ_TIMEOUT（默认各 300 秒）：nginx 等待 api_server/web_server 上游的连接/发送/读取超时。长对话、Deep Research 等长请求出现网关超时（504）时按需调大。

5.8 MCP 服务端（供外部 AI 客户端接入）

• MCP_SERVER_ENABLED（默认 false）：开启 Onyx 内置 MCP 服务端，让 Claude Code、OpenCode 等 MCP 客户端以用户权限访问企业知识。
• MCP_SERVER_PORT（默认 8090）：MCP 服务监听端口。
• MCP_SERVER_CORS_ORIGINS：MCP 客户端跨域白名单（逗号分隔）。
• MCP_SERVER_API_REQUEST_TIMEOUT_SECONDS（默认 300）：MCP 请求转发到 API 服务读超时。

5.9 生成与 LLM

• GEN_AI_MAX_TOKENS：单次生成最大 token 数上限。
• GEN_AI_API_KEY：默认 LLM 供应商的 API Key（管理面板配置模型时也可界面设置）。
• LLM_SOCKET_READ_TIMEOUT / IMAGE_SUMMARIZATION_TIMEOUT / CONTEXTUAL_RAG_LLM_TIMEOUT：慢模型（长思维链/图像摘要/上下文增强）的读超时，超时报错时上调。
• MAX_CHUNKS_FED_TO_CHAT：单次对话喂给 LLM 的最大文档块数——直接影响回答引用广度与 token 成本。
• DISABLE_LITELLM_STREAMING / LITELLM_EXTRA_HEADERS / LITELLM_CUSTOM_ERROR_MESSAGE_MAPPINGS：LiteLLM 网关层行为微调。
• 用量与成本核算族：USER_USAGE_TRACKING_ENABLED（默认 true，按用户记录带价生成流水）、DEFAULT_IMAGE_COST_CENTS（默认 4 美分/图）、DEFAULT_LLM_INPUT_COST_PER_MTOK / DEFAULT_LLM_OUTPUT_COST_PER_MTOK（默认 0=免费，LiteLLM 无法定价的模型按此兜底计价）。

5.10 检索与索引

• HYBRID_ALPHA：混合检索中向量（语义）与关键词（BM25）两路得分的融合权重（0~1 之间调语义占比）。
• DOC_TIME_DECAY：文档时间衰减系数，调新文档在排序中的加成。
• USE_SEMANTIC_KEYWORD_EXPANSIONS_BASIC_SEARCH：基础搜索的语义关键词扩展开关。
• 嵌入模型族：DOCUMENT_ENCODER_MODEL（嵌入模型名，官方默认搭载 nomic-ai/nomic-embed-text-v1）、DOC_EMBEDDING_DIM（向量维度）、NORMALIZE_EMBEDDINGS（是否归一化）、ASYM_QUERY_PREFIX / ASYM_PASSAGE_PREFIX（非对称嵌入的查询/段落前缀）、EMBEDDING_BATCH_SIZE（批量大小）。换嵌入模型等于重建索引，务必整组一起改。
• PIT_KEEP_ALIVE（默认 5m）：OpenSearch Point-In-Time 保活时长（重索引/扫描用）。
• TABULAR_RECHUNK_ENABLED（默认 false）：对旧切块策略入索引的表格文档原地重切块（一次性迁移，有记录防重复）。
• VESPA_SEARCHER_THREADS、VESPA_LANGUAGE_OVERRIDE：历史遗留参数名（早期版本检索引擎为 Vespa，4.x 已切 OpenSearch），保留兼容旧配置文件。

5.11 任务队列（Celery）

• 并发族：CELERY_WORKER_DOCFETCHING_CONCURRENCY（拉取）、CELERY_WORKER_DOCPROCESSING_CONCURRENCY（切块入库）、CELERY_WORKER_LIGHT_CONCURRENCY（轻任务）。索引吞吐不足/资源吃紧时按机器余量调节。
• CELERY_BROKER_POOL_LIMIT：到 Redis 队列的连接池上限。
• 锁 TTL 族：CELERY_EXTERNAL_GROUP_SYNC_LOCK_TIMEOUT（默认 300 秒，连接器组同步锁）、CELERY_PERMISSIONS_SYNC_LOCK_TIMEOUT（默认 3600 秒，权限同步锁）、CELERY_DOCUMENT_SYNC_BEAT_LOCK_TIMEOUT（默认 120 秒，文档索引同步锁）。日志出现「lock that's no longer owned」「Lock not owned on completion」即对应锁超时过短，按同步时长上调。

5.12 连接器专项

各数据源的行为开关集中在模板「Indexing Configuration」区，常见三类：

1. 权限同步频率：CANVAS_PERMISSION_DOC_SYNC_FREQUENCY、ONEDRIVE_PERMISSION_GROUP_SYNC_FREQUENCY、TEAMS_PERMISSION_GROUP_SYNC_FREQUENCY 等——权限变更传导到索引的周期。
2. 附件/文档大小阈值：AIRTABLE_ATTACHMENT_SIZE_THRESHOLD（默认 10 MB）、DROPBOX_CONNECTOR_SIZE_THRESHOLD（默认 20 MB）、OUTLOOK_CONNECTOR_ATTACHMENT_SIZE_THRESHOLD 等——超过阈值的附件不入索引。
3. OAuth 凭据：EGNYTE_CLIENT_ID/SECRET、LINEAR_CLIENT_ID/SECRET、SALESFORCE_CLIENT_ID/SECRET——走 OAuth 的连接器需要先在对应平台注册应用。

5.13 观测与日志

• LOG_LEVEL（默认 info）：全局日志级别，覆盖 api_server、web_server、模型服务与全部 Celery worker；worker 可在 supervisord.conf 中用 --loglevel 覆盖（显式命令行优先）。
• 延迟埋点族：LOG_ENDPOINT_LATENCY、LOG_POSTGRES_LATENCY、LOG_POSTGRES_CONN_COUNTS：按需打开的延迟/连接数日志。
• DISABLE_TELEMETRY：关闭匿名遥测上报；SENTRY_DSN：接自有 Sentry 做错误聚合；LOG_ONYX_MODEL_INTERACTIONS（默认 False）：记录模型交互明细（量大且含用户内容，慎开）。

5.14 前端与杂项

• NEXT_PUBLIC_* 族（NEXT_PUBLIC_THEME 主题、NEXT_PUBLIC_FORGOT_PASSWORD_ENABLED 忘记密码入口、NEXT_PUBLIC_DISABLE_LOGOUT 隐藏登出）：前端编译期/运行期开关。
• HIDE_ONYX_BRANDING：隐藏「Powered by Onyx」，官方注释要求需获 Onyx 明确许可（Enterprise）才可设置。
• HIDE_QUERY_HISTORY_FROM_ADMIN_PANEL（设 true 生效）：仅从管理面板隐藏查询历史页，历史记录 API 与落库照常（区别于 ONYX_QUERY_HISTORY_TYPE=disabled 的完全停用）。
• 网关直通族：ANTHROPIC_GATEWAY_PASSTHROUGH_ENABLED、OPENAI_GATEWAY_PASSTHROUGH_ENABLED（默认开）：关闭则对应供应商走 OpenAI 翻译路径，牺牲原生能力换兼容。

六、生产配置模板

以下模板面向「16 GB 内存、4 vCPU、100 GB SSD、50~200 人团队、SaaS 连接器同步 + 每日对话量中等」的典型生产场景，可直接落地（密钥类先执行生成命令再粘贴）：

# 先在部署目录执行，生成两个密钥的实际值（不要用示例值）
openssl rand -hex 32   # 第 1 个输出 → 粘到 USER_AUTH_SECRET
openssl rand -hex 32   # 第 2 个输出 → 粘到 ENCRYPTION_KEY_SECRET

# ===== 版本与形态 =====
IMAGE_TAG=v4.9.3              # 钉住版本，可重现升级
COMPOSE_PROFILES=s3-filestore # 标准版保留 MinIO
ONYX_AIRGAPPED=true           # 内网/气隙环境开启；能出网则删掉此行

# ===== 认证与安全 =====
USER_AUTH_SECRET=<上面第 1 个 openssl 输出>
ENCRYPTION_KEY_SECRET=<上面第 2 个 openssl 输出>
VALID_EMAIL_DOMAINS=example.com          # 仅允许公司域注册
USER_DIRECTORY_ADMIN_ONLY=true           # 禁止普通用户枚举账号
# METRICS_AUTH_TOKEN 不设即锁定 /metrics（保持默认锁定）

# ===== 对象存储 =====
S3_ENDPOINT_URL=http://minio:9000
S3_AWS_ACCESS_KEY_ID=<强口令，与 MINIO_ROOT_USER 相同>
S3_AWS_SECRET_ACCESS_KEY=<强口令，与 MINIO_ROOT_PASSWORD 相同>
MINIO_ROOT_USER=<同上>
MINIO_ROOT_PASSWORD=<同上>

# ===== 数据库 =====
POSTGRES_USER=onyx
POSTGRES_PASSWORD=<强口令>
POSTGRES_HOST=relational_db
POSTGRES_SSLMODE=verify-full             # 接托管库时启用并配 CA
POSTGRES_SSLROOTCERT=/etc/ssl/certs/rds-ca-bundle.pem

# ===== 反代与长请求 =====
NGINX_PROXY_READ_TIMEOUT=600             # Deep Research 等长请求调大
NGINX_PROXY_CONNECT_TIMEOUT=600
NGINX_PROXY_SEND_TIMEOUT=600

# ===== 队列与检索 =====
CELERY_WORKER_DOCFETCHING_CONCURRENCY=4
CELERY_WORKER_DOCPROCESSING_CONCURRENCY=2
CELERY_EXTERNAL_GROUP_SYNC_LOCK_TIMEOUT=1800

# ===== 观测 =====
LOG_LEVEL=info
DISABLE_TELEMETRY=true                   # 内网合规场景关遥测

模板要点解读：两个密钥由 openssl 现场生成杜绝弱值；VALID_EMAIL_DOMAINS + USER_DIRECTORY_ADMIN_ONLY 双收紧注册面；MinIO 四值联动换强口令；长请求超时统一 600 秒防 504；锁 TTL 按大连接器同步时长上调；内存不足 16 GB 时先把两个 worker 并发降到 2/1 并考虑关闭 DISABLE_MODEL_SERVER 以外的重配置（该参数默认 false，勿误设 true——会跳过模型服务部署导致索引不可用）。

七、常见问题

Q1：改了 .env 为什么不生效？ env_file 只在容器创建时注入。改完必须 docker compose up -d <服务名> 重建对应服务；影响全部服务时全量 docker compose up -d。验证生效用 docker compose exec -T api_server sh -c 'echo $<参数名>'（实测见 3.2 节）。

Q2：.env、env.template、Compose 文件三者的关系？ env.template 是官方模板（只读参考，含全部参数注释）；.env 是你的实际配置（从模板复制后改）；Compose 文件由模板生成、只负责引用 .env，不要直接编辑。升级版本时用新模板比对 .env 可发现新增参数。

Q3：USER_AUTH_SECRET 已设置过还能换吗？ 能换但代价是全部旧签名失效：已发出的密码重置/验证邮件链接作废、OAuth 登录状态失效，用户需重新登录。换密钥属重置会话体系操作，安排在维护窗口。

Q4：接外部托管 PostgreSQL 要改哪些项？ POSTGRES_HOST 指向外部地址，POSTGRES_USER/PASSWORD 用托管凭据，托管库走 TLS 时设 POSTGRES_SSLMODE=verify-full 与 POSTGRES_SSLROOTCERT；同时从 COMPOSE_PROFILES 与 Compose 叠加文件中移除内置 relational_db 服务，避免双库混用。

Q5：HYBRID_ALPHA 调多大合适？ 没有通用最优值：知识库以专有名词/型号类精确查询为主（如内部工单、SKU）时调低语义权重；以自然语言描述查询为主时调高。建议每次只动一个参数并在真实问题上做前后对比（检索与索引参数族的其余项同理）。

八、参考链接

1. Onyx 产品介绍与选型：《Onyx 介绍与选型指南》
2. 安装与排障实录：《Ubuntu 22.04 安装 Onyx 4.9.3 指南》
3. 官方配置模板（本文参数的权威来源）：GitHub 仓库 onyx-dot-app/onyx 内 deployment/docker_compose/env.template（4.9.3 版实查，查询日期 2026-10-23）
4. 官方文档-认证与部署：https://docs.onyx.app/deployment/authentication（查询日期 2026-10-23）
5. 日常管理与命令操作：《Onyx 4.9.3 常用 CLI 命令与工具详解》（本系列命令篇）