2.3 · 环境配置（Environment Configuration）

环境配置（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/onyx-dot-app/onyx/2.3-environment-configuration

翻译时间：2026-05-27T08:44:46.984Z

翻译模型：deepseek-chat

原文字符数：11657

项目：Onyx (onyx)

---

环境配置

相关源文件

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

• .vscode/env_template.txt
• 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/scripts/restart_containers.sh
• backend/supervisord.conf
• backend/tests/external_dependency_unit/redis/test_tenant_redis.py
• deployment/aws_ecs_fargate/cloudformation/deploy.sh
• deployment/aws_ecs_fargate/cloudformation/uninstall.sh
• deployment/data/nginx/app.conf.template
• deployment/data/nginx/app.conf.template.no-letsencrypt
• deployment/data/nginx/app.conf.template.prod
• deployment/data/nginx/run-nginx.sh
• deployment/docker_compose/env.nginx.template
• deployment/helm/charts/onyx/templates/nginx-conf.yaml
• web/lib/opal/scripts/README.md
• web/lib/opal/scripts/convert-svg.sh
• web/lib/opal/src/icons/discord.tsx
• web/lib/opal/src/icons/icons.stories.tsx
• web/lib/opal/src/icons/slack.tsx
• web/lib/opal/src/illustrations/illustrations.stories.tsx
• web/lib/opal/src/logos/azure.tsx

本文档详细介绍了用于配置 Onyx 部署的所有环境变量，系统如何加载和处理这些变量，以及不同部署模式（开发、生产、多租户）如何使用不同的配置方案。内容涵盖基础设施连接、认证方法、功能开关和性能调优参数。

有关数据库模式迁移的信息，请参见数据库迁移。有关部署编排的详细信息，请参见Docker Compose 部署和Kubernetes 部署。

---

配置加载架构

Onyx 配置系统通过 app_configs.py 加载环境变量，该文件作为中央配置注册表。所有服务（API 服务器、后台工作者、模型服务器）都从此模块读取运行时参数。

配置加载流程

graph TB
    EnvFile["环境模板<br/>.vscode/env_template.txt"]
    OSEnv["操作系统环境<br/>变量"]
    DockerCompose["docker-compose.yml<br/>环境配置段"]

    EnvFile --> OSEnv
    DockerCompose --> OSEnv

    OSEnv --> AppConfigs["app_configs.py<br/>os.environ.get()"]

    AppConfigs --> APIServer["API 服务器<br/>(onyx.server.api_server)"]
    AppConfigs --> Background["Celery 工作者<br/>(onyx.background.celery)"]
    AppConfigs --> ModelServer["模型服务器<br/>(推理/索引)"]

    APIServer --> PostgresDB["PostgreSQL<br/>SqlEngine"]
    APIServer --> RedisCache["Redis<br/>RedisPool"]
    APIServer --> VespaIndex["Vespa<br/>VespaDocumentIndex"]

    Background --> CeleryBeat["celery_beat<br/>DynamicTenantScheduler"]

来源： backend/onyx/configs/app_configs.py:1-41, backend/onyx/redis/redis_pool.py:22-38, backend/onyx/background/celery/apps/beat.py:27-50

配置处理模式

环境变量在 app_configs.py 中使用标准模式进行处理：

# 字符串配置
APP_API_PREFIX = os.environ.get("API_PREFIX", "")

# 整数配置，带默认值和范围限制
_raw_max_upload_size_mb = int(os.environ.get("MAX_ALLOWED_UPLOAD_SIZE_MB", "250"))

# 布尔配置（显式检查）
DISABLE_VECTOR_DB = os.environ.get("DISABLE_VECTOR_DB", "").lower() == "true"

# 枚举配置，带校验
_auth_type_str = (os.environ.get("AUTH_TYPE") or "").lower()
if _auth_type_str in [auth_type.value for auth_type in AuthType]:
    AUTH_TYPE = AuthType(_auth_type_str)
else:
    AUTH_TYPE = AuthType.BASIC

来源： backend/onyx/configs/app_configs.py:27-130

---

核心服务连接配置

数据库连接设置

环境变量	默认值	用途	代码引用
POSTGRES_HOST	127.0.0.1	PostgreSQL 主机名	app_configs.py:31
POSTGRES_USER	postgres	数据库用户名	restart_containers.sh:49
MULTI_TENANT	false	启用基于模式的租户隔离	shared_configs/configs.py:54

数据库连接使用特定的 application_name 标签用于可观测性，例如 POSTGRES_WEB_APP_NAME（"web"）和 POSTGRES_CELERY_BEAT_APP_NAME（"celery_beat"）。

来源： backend/onyx/configs/constants.py:81-97, backend/onyx/background/celery/apps/primary.py:119-123

Redis 配置

Redis 用于缓存、分布式锁和会话存储。系统使用 TenantRedis 包装器在多租户环境中自动为键添加 tenant_id 前缀。

环境变量	默认值	用途
REDIS_HOST	localhost	Redis 服务器地址
REDIS_PORT	6379	Redis 端口
CACHE_BACKEND	redis	临时状态的后端存储
REDIS_POOL_MAX_CONNECTIONS	20	最大连接池大小

来源： backend/onyx/redis/redis_pool.py:65-91, backend/onyx/configs/app_configs.py:83-87

向量数据库配置

Onyx 支持 Vespa 和 OpenSearch。在迁移期间支持双索引。

环境变量	默认值	用途
DISABLE_VECTOR_DB	false	禁用向量数据库（仅聊天模式）
ENABLE_OPENSEARCH_INDEXING_FOR_ONYX	false	启用向 OpenSearch 的索引
ONYX_DISABLE_VESPA	false	关闭 Vespa 操作

来源： backend/onyx/configs/app_configs.py:79-81, backend/onyx/background/celery/apps/app_base.py:31-33

---

认证配置

AUTH_TYPE 变量决定系统使用的 AuthType 枚举。

AUTH_TYPE 值	描述
basic	用户名/密码认证（默认）
google_oauth	Google OAuth 2.0 流程
oidc	通用 OpenID Connect
saml	SAML SSO（企业版功能）
disabled	无需认证

密码策略配置

• PASSWORD_MIN_LENGTH：默认 8。
• PASSWORD_REQUIRE_UPPERCASE：默认 false。
• PASSWORD_REQUIRE_DIGIT：默认 false。

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

---

后台任务与 Celery 配置

Onyx 使用 Celery 并配备多个专门的工作者池。配置通过 supervisord.conf 和环境特定的 Celery 应用进行管理。

工作者池定义

• celery_worker_primary：处理常规任务。
• celery_worker_light：元数据同步、删除、检查点清理。
• celery_worker_heavy：修剪、权限同步、外部组同步。
• celery_worker_docprocessing：文档索引和嵌入向量生成。

任务调度（Celery Beat）

DynamicTenantScheduler 为所有租户生成调度计划。CLOUD_BEAT_MULTIPLIER_DEFAULT（默认 8.0）用于在云环境中调整任务频率。

来源： backend/supervisord.conf:30-115, backend/onyx/background/celery/apps/beat.py:27-36, backend/onyx/background/celery/tasks/beat_schedule.py:33-35

---

功能开关与 AI 设置

AI 与大语言模型（LLM）设置

• GEN_AI_MODEL_VERSION：默认模型名称（例如 gpt-4o）。
• SEND_USER_METADATA_TO_LLM_PROVIDER：是否向提供商发送用户 ID/邮箱。
• QUERY_EMBEDDING_CACHE_ENABLED：缓存查询嵌入向量以降低 API 成本。

系统功能开关

• ENABLE_PAID_ENTERPRISE_EDITION_FEATURES：激活企业版特定的代码路径。
• DISABLE_USER_KNOWLEDGE：阻止用户向助手上传个人文件。
• SHOW_EXTRA_CONNECTORS：在管理界面中显示不常见的数据源。

来源： backend/onyx/configs/app_configs.py:39-41, backend/onyx/configs/app_configs.py:77-101, .vscode/env_template.txt:48-51

---

开发与生产配置对比

开发环境（.vscode/env_template.txt）

• DEV_MODE=true：启用详细日志和热重载。
• LOG_LEVEL=debug：设置日志详细程度。
• S3_ENDPOINT_URL=http://localhost:9004：指向本地 MinIO。

生产环境（supervisord.conf）

• nodaemon=true：Supervisord 在前台运行。
• autorestart=true：自动重启崩溃的工作者。
• stopasgroup=true：确保子进程随工作者一起终止。

来源： .vscode/env_template.txt:13-21, backend/supervisord.conf:1-40

---

数据流：从环境变量到代码实体

此图将环境变量映射到使用它们的特定类和函数。

graph LR
    subgraph "环境空间"
        E1["AUTH_TYPE"]
        E2["REDIS_HOST"]
        E3["MULTI_TENANT"]
        E4["ENABLE_OPENSEARCH_INDEXING_FOR_ONYX"]
    end

    subgraph "代码实体空间"
        C1["onyx.configs.app_configs.AUTH_TYPE"]
        C2["onyx.redis.redis_pool.TenantRedis"]
        C3["onyx.background.celery.apps.app_base.TenantAwareTask"]
        C4["onyx.document_index.factory.get_all_document_indices"]
    end

    E1 --> C1
    E2 --> C2
    E3 --> C3
    E4 --> C4

来源： backend/onyx/configs/app_configs.py:126-130, backend/onyx/redis/redis_pool.py:65-68, backend/onyx/background/celery/apps/app_base.py:80-83, backend/onyx/document_index/factory.py:52