环境配置
环境配置
相关源文件
本章引用的主要源码文件：
.vscode/env_template.txtbackend/ee/onyx/background/celery/apps/primary.pybackend/ee/onyx/background/celery/tasks/beat_schedule.pybackend/onyx/background/celery/apps/app_base.pybackend/onyx/background/celery/apps/beat.pybackend/onyx/background/celery/apps/heavy.pybackend/onyx/background/celery/apps/light.pybackend/onyx/background/celery/apps/monitoring.pybackend/onyx/background/celery/apps/primary.pybackend/onyx/background/celery/tasks/beat_schedule.pybackend/onyx/background/celery/tasks/shared/tasks.pybackend/onyx/background/celery/tasks/vespa/tasks.pybackend/onyx/configs/app_configs.pybackend/onyx/configs/constants.pybackend/onyx/document_index/factory.pybackend/onyx/redis/redis_pool.pybackend/scripts/dev_run_background_jobs.pybackend/scripts/restart_containers.shbackend/supervisord.confbackend/tests/external_dependency_unit/redis/test_tenant_redis.pydeployment/aws_ecs_fargate/cloudformation/deploy.shdeployment/aws_ecs_fargate/cloudformation/uninstall.shdeployment/data/nginx/app.conf.templatedeployment/data/nginx/app.conf.template.no-letsencryptdeployment/data/nginx/app.conf.template.proddeployment/data/nginx/run-nginx.shdeployment/docker_compose/env.nginx.templatedeployment/helm/charts/onyx/templates/nginx-conf.yamlweb/lib/opal/scripts/README.mdweb/lib/opal/scripts/convert-svg.shweb/lib/opal/src/icons/discord.tsxweb/lib/opal/src/icons/icons.stories.tsxweb/lib/opal/src/icons/slack.tsxweb/lib/opal/src/illustrations/illustrations.stories.tsxweb/lib/opal/src/logos/azure.tsx
本文档详细介绍了用于配置 Onyx 部署的所有环境变量，系统如何加载和处理这些变量，以及不同部署模式（开发、生产、多租户）如何使用不同的配置方案。内容涵盖基础设施连接、认证方法、功能开关和性能调优参数。
有关数据库模式迁移的信息，请参见数据库迁移。有关部署编排的详细信息，请参见Docker Compose 部署和Kubernetes 部署。
配置加载架构
Onyx 配置系统通过 app_configs.py 加载环境变量，该文件作为中央配置注册表。所有服务（API 服务器、后台工作者、模型服务器）都从此模块读取运行时参数。
配置加载流程
来源： 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
数据流：从环境变量到代码实体
此图将环境变量映射到使用它们的特定类和函数。
来源： 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