agentic_huge_data_base / wiki
页面 Onyx · 8 后端核心系统·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 8

8 · 后端核心系统

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

项目Onyx 章节8 状态全文译文 模块系统架构、存储与持久化、文档对象与元数据、配置治理
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Backend Core Systems 上一章7.6 下一章8.1
源码线索
  • backend/alembic/versions/74379b447d4c_add_paste_as_tile_to_user.py
  • backend/ee/onyx/main.py
  • backend/ee/onyx/server/auth_check.py
  • backend/ee/onyx/server/enterprise_settings/api.py
  • backend/ee/onyx/server/enterprise_settings/store.py
  • backend/onyx/auth/schemas.py
  • backend/onyx/auth/users.py
  • backend/onyx/db/enums.py
  • backend/onyx/db/models.py
  • backend/onyx/db/user_preferences.py
模块标签
  • 系统架构
  • 存储与持久化
  • 文档对象与元数据
  • 配置治理
  • 测试、发布与运维

章节正文

后端核心系统

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/8-backend-core-systems

后端核心系统

相关源文件

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

  • backend/alembic/versions/74379b447d4c_add_paste_as_tile_to_user.py
  • backend/ee/onyx/main.py
  • backend/ee/onyx/server/auth_check.py
  • backend/ee/onyx/server/enterprise_settings/api.py
  • backend/ee/onyx/server/enterprise_settings/store.py
  • backend/onyx/auth/schemas.py
  • backend/onyx/auth/users.py
  • backend/onyx/db/enums.py
  • backend/onyx/db/models.py
  • backend/onyx/db/user_preferences.py
  • backend/onyx/main.py
  • backend/onyx/server/auth_check.py
  • backend/onyx/server/manage/get_state.py
  • backend/onyx/server/manage/models.py
  • backend/onyx/server/manage/users.py
  • backend/onyx/server/runtime/onyx_runtime.py
  • backend/onyx/server/saml.py
  • backend/onyx/utils/file.py
  • backend/static/images/logo.png
  • backend/tests/api/test_api.py
  • backend/tests/unit/onyx/auth/test_single_tenant_jwt_strategy.py
  • backend/tests/unit/onyx/server/scim/test_admin.py
  • deployment/aws_ecs_fargate/cloudformation/services/onyx_nginx_service_template.yaml
  • deployment/aws_ecs_fargate/cloudformation/services/onyx_web_server_service_template.yaml
  • web/src/app/auth/saml/callback/route.ts
  • web/src/hooks/useTokenRefresh.test.tsx
  • web/src/hooks/useTokenRefresh.ts
  • web/src/lib/redirectSS.ts
  • web/src/providers/UserProvider.tsx

目的与范围

本文档涵盖 Onyx 的基础后端基础设施，包括配置系统、数据库引擎、API 服务器架构以及文档索引后端。这些核心系统提供了所有其他后端功能所依赖的基础层。

有关特定子系统的详细信息，请参阅以下子页面：

系统架构总览

后端核心由多个相互连接的子系统组成，它们协同工作以提供 Onyx 平台。该架构采用多进程模型，各进程职责明确，并通过 Redis 和 PostgreSQL 进行协调。

自然语言到代码实体空间：系统总览

下图将高层系统组件映射到对应的代码实体和配置。

Onyx · 自然语言到代码实体空间：系统总览 · 图 1
Onyx · 自然语言到代码实体空间：系统总览 · 图 1

来源： backend/onyx/main.py:11-150, backend/onyx/db/engine/sql_engine.py:61-63, backend/onyx/db/models.py:118-125

配置系统

Onyx 后端使用基于环境变量的集中式配置系统。所有配置在应用启动时进行解析和校验。

关键配置组件
配置文件用途关键导出项
app_configs.py环境变量解析APP_HOST, AUTH_TYPE, POSTGRES_*, REDIS_*
constants.py系统常量与枚举DocumentSource, MessageType, AuthType

系统广泛使用 os.environ.get 来提供默认值，同时允许覆盖。例如，AUTH_TYPE 决定了整个应用使用的认证策略 backend/onyx/auth/users.py:88-88。

有关完整变量列表和校验逻辑，请参阅 配置系统。

来源： backend/onyx/auth/users.py:86-103, backend/onyx/configs/constants.py:50-53, backend/onyx/main.py:36-58

数据库与数据持久化

Onyx 使用 PostgreSQL 存储关系型数据（用户、会话、连接器配置），并使用专门的索引进行文档搜索。

数据库引擎与模型

SqlEngine 管理连接池。关系型数据通过 SQLAlchemy 的 Mapped 列和 relationship 定义进行映射 backend/onyx/db/models.py:38-41。敏感数据（如连接器凭证）使用 EncryptedString 和 EncryptedJson 类型存储，这些类型将值包装在 SensitiveValue 对象中 backend/onyx/db/models.py:122-161。

文档索引后端

Onyx 目前支持两种主要的文档存储和混合搜索后端：

  1. Vespa：默认的高性能向量和关键词搜索引擎。
  2. OpenSearch：备选后端，支持从 Vespa 迁移文档 backend/onyx/db/enums.py:249-254。
代码实体空间：用户与认证持久化

下图展示了用户数据和认证令牌在数据库中的结构。

Onyx · 代码实体空间：用户与认证持久化 · 图 2
Onyx · 代码实体空间：用户与认证持久化 · 图 2

来源： backend/onyx/db/models.py:126-129, backend/onyx/auth/users.py:62-62, backend/onyx/auth/users.py:119-122

有关模式定义的详细信息，请参阅 数据库模型与模式。有关搜索实现，请参阅 文档搜索与索引后端。

API 服务器架构

API 服务器基于 FastAPI 构建，是前端和外部集成的主要接口。

  • 初始化：应用在 onyx.main:get_application 中初始化，注册中间件（CORS、延迟日志记录）和异常处理器 backend/onyx/main.py:155-200。
  • 认证：集成 fastapi_users 进行会话管理，并通过 AUTH_TYPE 支持多种后端（例如 google_oauth、oidc、saml）backend/onyx/auth/users.py:88-88。
  • 路由：路由按功能模块组织（例如 connector_router、persona_router、cc_pair_router），并添加 APP_API_PREFIX 前缀 backend/onyx/main.py:68-150。
  • 安全：所有私有路由通过 check_router_auth 进行校验，确保它们包含用户依赖 backend/onyx/server/auth_check.py:101-155。
  • 企业扩展：企业版（EE）包装基础应用，添加多租户和高级分析路由 backend/ee/onyx/main.py:79-91。

有关完整路由表和中间件栈，请参阅 API 服务器架构。

来源： backend/onyx/main.py:1-150, backend/onyx/auth/users.py:109-156, backend/ee/onyx/main.py:129-161

模型服务器与推理

Onyx 将繁重的 AI 工作负载与核心 API 逻辑分离。

  • 双服务器逻辑：系统可以区分用于推理（聊天）和索引（文档嵌入）的服务器。
  • 推理模型：通过抽象接口处理，支持与 OpenAI、Anthropic 以及本地 Ollama 实例等提供商集成。
  • 嵌入向量：文档使用本地缓存的模型转换为向量。INDEXING_ONLY 标志可以将模型服务器实例限制为仅处理文档嵌入。

有关模型部署和缓存的详细信息，请参阅 模型服务器。

来源： backend/onyx/configs/app_configs.py:42-42, backend/onyx/db/enums.py:163-174