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

8.4 · 配置系统（Configuration System）

企业连接器与统一搜索 · 本章是 Onyx DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目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
翻译时间：2026-05-27T08:44:52.385Z
翻译模型：deepseek-chat
原文字符数：12835
项目：Onyx (onyx)

---

配置系统

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

  • 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

配置架构

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

标题：配置系统架构

graph TB
    subgraph "配置模块"
        AppConfigs["app_configs.py<br/>主要配置"]
        Constants["constants.py<br/>枚举与常量定义"]
    end

    subgraph "环境源"
        EnvVars["环境变量<br/>操作系统环境"]
        DockerEnv[".env 文件<br/>Docker Compose"]
        K8sSecrets["Kubernetes Secrets<br/>ConfigMaps"]
    end

    subgraph "配置类别"
        AppCfg["APP_HOST, APP_PORT<br/>APP_API_PREFIX"]
        AuthCfg["AUTH_TYPE, OAUTH_*<br/>PASSWORD_*, JWT_*"]
        DBCfg["POSTGRES_*, REDIS_*<br/>VESPA_*, CELERY_*"]
        ConnectorCfg["SHOW_EXTRA_CONNECTORS<br/>REQUEST_TIMEOUT_SECONDS"]
        IndexCfg["DISABLE_VECTOR_DB<br/>QUERY_EMBEDDING_CACHE_TTL_S"]
        EECfg["ENTERPRISE_EDITION_ENABLED<br/>ENCRYPTION_KEY_SECRET"]
    end

    subgraph "消费系统"
        APIServer["FastAPI 应用<br/>main.py"]
        Workers["Celery 工作进程<br/>后台任务"]
        ModelServer["模型服务器<br/>嵌入向量"]
        Auth["认证逻辑"]
    end

    EnvVars --> AppConfigs
    DockerEnv --> AppConfigs
    K8sSecrets --> AppConfigs

    AppConfigs --> AppCfg
    AppConfigs --> AuthCfg
    AppConfigs --> DBCfg
    AppConfigs --> ConnectorCfg
    AppConfigs --> IndexCfg
    AppConfigs --> EECfg

    AppCfg --> APIServer
    AuthCfg --> Auth
    DBCfg --> Workers
    DBCfg --> APIServer
    ConnectorCfg --> Workers
    IndexCfg --> ModelServer
    EECfg --> Auth

    Constants --> AppConfigs

来源： 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

认证配置

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

标题：认证配置层级

graph LR
    subgraph "认证类型选择"
        AUTH_TYPE["AUTH_TYPE<br/>AuthType 枚举"]
        DISABLED["AuthType.DISABLED"]
        BASIC["AuthType.BASIC"]
        GOOGLE["AuthType.GOOGLE_OAUTH"]
        OIDC["AuthType.OIDC"]
        SAML["AuthType.SAML"]
    end

    subgraph "认证后端"
        AUTH_BACKEND["AUTH_BACKEND<br/>AuthBackend 枚举"]
        REDIS["AuthBackend.REDIS"]
        POSTGRES["AuthBackend.POSTGRES"]
    end

    subgraph "OAuth/OIDC"
        OAUTH_CLIENT_ID["OAUTH_CLIENT_ID"]
        OAUTH_CLIENT_SECRET["OAUTH_CLIENT_SECRET"]
    end

    subgraph "会话管理"
        SESSION_EXPIRE["SESSION_EXPIRE_TIME_SECONDS<br/>默认值：7 天"]
    end

    subgraph "密码策略"
        MIN_LENGTH["PASSWORD_MIN_LENGTH"]
        MAX_LENGTH["PASSWORD_MAX_LENGTH"]
        REQUIRE_UPPER["PASSWORD_REQUIRE_UPPERCASE"]
    end

    AUTH_TYPE --> DISABLED
    AUTH_TYPE --> BASIC
    AUTH_TYPE --> GOOGLE
    AUTH_TYPE --> OIDC
    AUTH_TYPE --> SAML

    AUTH_BACKEND --> REDIS
    AUTH_BACKEND --> POSTGRES

    GOOGLE --> OAUTH_CLIENT_ID
    OIDC --> OAUTH_CLIENT_ID

关键认证配置项：

配置项类型默认值用途
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。

标题：任务协调配置映射

graph TD
    subgraph "代码实体空间"
        Task["OnyxCeleryTask"]
        Lock["RedisLock"]
        Fence["ACTIVE_FENCES"]
        TenantRedis["TenantRedis"]
    end

    subgraph "自然语言空间"
        Sync["Vespa 同步进程"]
        Primary["主工作进程生命周期"]
        Prefixing["租户键隔离"]
    end

    Sync -- "使用" --> Task["OnyxCeleryTask.CHECK_FOR_VESPA_SYNC_TASK"]
    Task -- "获取" --> Lock["OnyxRedisLocks.CHECK_VESPA_SYNC_BEAT_LOCK"]
    Primary -- "重置" --> Fence["OnyxRedisConstants.ACTIVE_FENCES"]
    Prefixing -- "由...实现" --> TenantRedis

关键协调常量：

  • 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