agentic_huge_data_base / wiki
页面 Onyx · 8.4 配置系统·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 8.4

8.4 · 配置系统（Configuration System）

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节8.4 状态全文译文 模块配置治理、测试、发布与运维、存储与持久化、检索、召回与索引
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Configuration System 上一章8.3 下一章8.5
源码线索
  • backend/ee/onyx/background/celery/apps/primary.py
  • backend/ee/onyx/background/celery/tasks/beat_schedule.py
  • backend/onyx/background/celery/apps/app_base.py
  • backend/onyx/background/celery/apps/beat.py
  • backend/onyx/background/celery/apps/heavy.py
  • backend/onyx/background/celery/apps/light.py
  • backend/onyx/background/celery/apps/monitoring.py
  • backend/onyx/background/celery/apps/primary.py
  • backend/onyx/background/celery/tasks/beat_schedule.py
  • backend/onyx/background/celery/tasks/shared/tasks.py
模块标签
  • 配置治理
  • 测试、发布与运维
  • 存储与持久化
  • 检索、召回与索引
  • 文档对象与元数据

章节正文

配置系统

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/8.4-configuration-system

配置系统

相关源文件

本章引用的主要源码文件：

  • backend/ee/onyx/background/celery/apps/primary.py
  • backend/ee/onyx/background/celery/tasks/beat_schedule.py
  • backend/onyx/background/celery/apps/app_base.py
  • backend/onyx/background/celery/apps/beat.py
  • backend/onyx/background/celery/apps/heavy.py
  • backend/onyx/background/celery/apps/light.py
  • backend/onyx/background/celery/apps/monitoring.py
  • backend/onyx/background/celery/apps/primary.py
  • backend/onyx/background/celery/tasks/beat_schedule.py
  • backend/onyx/background/celery/tasks/shared/tasks.py
  • backend/onyx/background/celery/tasks/vespa/tasks.py
  • backend/onyx/configs/app_configs.py
  • backend/onyx/configs/constants.py
  • backend/onyx/document_index/factory.py
  • backend/onyx/redis/redis_pool.py
  • backend/scripts/dev_run_background_jobs.py
  • backend/supervisord.conf
  • backend/tests/external_dependency_unit/redis/test_tenant_redis.py

Onyx 中的配置系统提供了对 200 多个配置参数的集中管理，这些参数控制着所有子系统的应用行为。该系统在启动时读取环境变量，并将其作为 Python 常量暴露给整个代码库，从而在 API 服务器、后台工作进程和模型服务器之间实现一致的配置。

有关部署特定的配置处理，请参阅环境配置。有关多租户模式配置，请参阅多租户架构。

概述

配置系统主要在 backend/onyx/configs/app_configs.py 中实现，该文件定义了应用配置参数。该模块在整个代码库中被导入，并作为运行时配置的唯一真实来源。系统处理以下内容：

  • 环境变量解析，包含类型转换和校验 backend/onyx/configs/app_configs.py:48-71
  • 可选配置的默认值管理 backend/onyx/configs/app_configs.py:118-120
  • 根据其他设置计算得出的派生配置 backend/onyx/configs/app_configs.py:159-163
  • 多租户与单租户的行为切换 backend/onyx/background/celery/apps/beat.py:88-112
  • 企业版功能的条件配置 backend/onyx/background/celery/tasks/beat_schedule.py:183-185

来源： backend/onyx/configs/app_configs.py:1-174, backend/onyx/background/celery/apps/beat.py:88-112

配置架构

配置系统遵循从环境源通过集中配置模块到消费系统的单向数据流。所有配置值在导入时被实例化。

标题：配置系统架构

Onyx · 配置架构 · 图 1
Onyx · 配置架构 · 图 1

来源： backend/onyx/configs/app_configs.py:22-166, backend/onyx/configs/constants.py:7-125

主要配置类别

应用与 Web 配置
配置项类型默认值用途
APP_HOST字符串"0.0.0.0"API 服务器绑定地址 backend/onyx/configs/app_configs.py:22
APP_PORT整数8080API 服务器端口 backend/onyx/configs/app_configs.py:23
APP_API_PREFIX字符串""所有 API 路由的基础路径前缀 backend/onyx/configs/app_configs.py:27
WEB_DOMAIN字符串"http://localhost:3000"OAuth 重定向的前端域名 backend/onyx/configs/app_configs.py:118
SEND_USER_METADATA_TO_LLM_PROVIDER布尔值false是否向大语言模型（LLM）提供商发送用户 ID backend/onyx/configs/app_configs.py:39-41

来源： backend/onyx/configs/app_configs.py:22-118

认证配置

认证系统通过一套全面的配置支持多种后端和身份提供商。

标题：认证配置层级

Onyx · 认证配置 · 图 2
Onyx · 认证配置 · 图 2

关键认证配置项：

配置项类型默认值用途
AUTH_TYPEAuthTypeBASIC主要认证方法 backend/onyx/configs/app_configs.py:126-130
AUTH_BACKENDAuthBackendREDIS会话存储后端 backend/onyx/configs/app_configs.py:157
SESSION_EXPIRE_TIME_SECONDS整数604800会话生命周期 backend/onyx/configs/app_configs.py:159-163
PASSWORD_MIN_LENGTH整数8最小密码长度 backend/onyx/configs/app_configs.py:132
VALID_EMAIL_DOMAINS字符串列表[]允许注册的邮箱域名 backend/onyx/configs/app_configs.py:168-174

来源： backend/onyx/configs/app_configs.py:126-174, backend/onyx/configs/constants.py:34-47

数据库与搜索配置

系统管理 PostgreSQL、Redis、Vespa 和 OpenSearch 的配置。

配置项类型默认值用途
CACHE_BACKENDCacheBackendTyperedis缓存和锁的后端 backend/onyx/configs/app_configs.py:85-87
DISABLE_VECTOR_DB布尔值false完全禁用向量数据库 backend/onyx/configs/app_configs.py:81
ENABLE_OPENSEARCH_INDEXING_FOR_ONYX布尔值false启用 OpenSearch 作为索引后端 backend/onyx/background/celery/tasks/beat_schedule.py:11
MULTI_TENANT布尔值false启用基于模式的隔离 backend/onyx/background/celery/tasks/beat_schedule.py:20

来源： backend/onyx/configs/app_configs.py:81-87, backend/onyx/background/celery/tasks/beat_schedule.py:11-20

任务协调与围栏

配置系统与 Redis 集成，使用"围栏"来防止任务重叠执行，从而实现任务协调。TenantRedis 类会自动为键添加 tenant_id 前缀，以确保多租户环境中的隔离性 backend/onyx/redis/redis_pool.py:65-91。

标题：任务协调配置映射

Onyx · 任务协调与围栏 · 图 3
Onyx · 任务协调与围栏 · 图 3

关键协调常量：

  • CELERY_VESPA_SYNC_BEAT_LOCK_TIMEOUT：120 秒 backend/onyx/configs/constants.py:130
  • CELERY_PRIMARY_WORKER_LOCK_TIMEOUT：120 秒 backend/onyx/configs/constants.py:133
  • ACTIVE_FENCES：活动任务锁的注册表 backend/onyx/configs/constants.py:163, backend/onyx/background/celery/tasks/vespa/tasks.py:163

来源： backend/onyx/configs/constants.py:130-163, backend/onyx/background/celery/tasks/vespa/tasks.py:92-102, backend/onyx/redis/redis_pool.py:65-91

动态配置存储

虽然 app_configs.py 处理环境变量，但键值存储中的各种键允许进行运行时调整。

  • KV_SETTINGS_KEY：存储通用 Onyx 设置 backend/onyx/configs/constants.py:119
  • KV_REINDEX_KEY：指示索引需要重新索引 backend/onyx/configs/constants.py:107
  • KV_ENTERPRISE_SETTINGS_KEY：存储企业版特定配置 backend/onyx/configs/constants.py:122
  • KV_KG_CONFIG_KEY：存储知识图谱配置 backend/onyx/configs/constants.py:124

来源： backend/onyx/configs/constants.py:106-124

配置加载模式

环境变量读取

配置系统使用一致的模式来读取环境变量：

# backend/onyx/configs/app_configs.py
# 模式：小写字符串转布尔值
SEND_USER_METADATA_TO_LLM_PROVIDER = (
    os.environ.get("SEND_USER_METADATA_TO_LLM_PROVIDER", "")
).lower() == "true"

# 模式：带校验和回退的整数
_raw_max_upload_size_mb = int(os.environ.get("MAX_ALLOWED_UPLOAD_SIZE_MB", "250"))
if _raw_max_upload_size_mb < 0:
    _raw_max_upload_size_mb = 250
MAX_ALLOWED_UPLOAD_SIZE_MB = _raw_max_upload_size_mb

来源： backend/onyx/configs/app_configs.py:39-57

多租户与单租户

配置通常根据 MULTI_TENANT 标志进行分支。在多租户模式下，使用 DynamicTenantScheduler 动态生成所有活动租户的调度计划 backend/onyx/background/celery/apps/beat.py:27-183。

# backend/onyx/background/celery/apps/primary.py
if MULTI_TENANT:
    return  # 在多租户模式下跳过单例清理

CLOUD_BEAT_MULTIPLIER_DEFAULT（默认值为 8.0）用于调整任务生成速率，以防止多租户环境中数据库负载激增 backend/onyx/background/celery/tasks/beat_schedule.py:33。

来源： backend/onyx/background/celery/apps/primary.py:132-133, backend/onyx/background/celery/tasks/beat_schedule.py:33, backend/onyx/background/celery/apps/beat.py:27-47