8 · 后端核心 Systems（Backend Core Systems）

后端核心 Systems（中文译文）

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

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

翻译模型：deepseek-chat

原文字符数：10207

项目：Onyx (onyx)

---

后端核心系统

相关源文件

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

• 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 服务器架构以及文档索引后端。这些核心系统提供了所有其他后端功能所依赖的基础层。

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

• 数据库模型与模式 —— SQLAlchemy 模型及其关系。
• API 服务器架构 —— FastAPI 结构与路由。
• 模型服务器 —— 推理与索引模型托管。
• 配置系统 —— 环境变量管理与校验。
• 文档搜索与索引后端 —— Vespa 和 OpenSearch 实现。
• 知识图谱系统 —— 实体提取与 Vespa 中的图谱存储。

---

系统架构总览

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

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

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

graph TB
    subgraph "入口点"
        APIServer["FastAPI 应用<br/>onyx.main:get_application"]
        Supervisord["supervisord_entrypoint.sh<br/>进程管理器"]
    end

    subgraph "配置层"
        AppConfigs["onyx.configs.app_configs<br/>环境变量"]
        Constants["onyx.configs.constants<br/>枚举与系统常量"]
        SqlEngine["onyx.db.engine.sql_engine:SqlEngine<br/>连接管理器"]
    end

    subgraph "进程管理"
        DocFetching["onyx.background.celery.tasks.docfetching<br/>文档检索"]
        DocProcessing["onyx.background.celery.tasks.docprocessing<br/>片段切分与嵌入向量"]
        RedisPool["onyx.redis.redis_pool:RedisPool<br/>协调"]
    end

    subgraph "数据层"
        PostgreSQL[("PostgreSQL<br/>onyx.db.models:Base")]
        Redis[("Redis<br/>onyx.redis.redis_pool")]
        Vespa[("Vespa/OpenSearch<br/>onyx.document_index")]
    end

    APIServer --> AppConfigs
    APIServer --> SqlEngine
    Supervisord --> DocFetching
    Supervisord --> DocProcessing

    DocFetching --> SqlEngine
    DocProcessing --> SqlEngine

    SqlEngine --> PostgreSQL
    DocFetching --> RedisPool
    DocProcessing --> RedisPool
    RedisPool --> Redis

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

代码实体空间：用户与认证持久化

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

graph LR
    subgraph "认证模型"
        User["onyx.db.models:User<br/>(表: user)"]
        AccessToken["onyx.db.models:AccessToken<br/>(表: access_token)"]
        OAuthAccount["onyx.db.models:OAuthAccount<br/>(表: oauth_account)"]
    end

    subgraph "持久化逻辑"
        UserDB["onyx.db.auth:SQLAlchemyUserDatabase<br/>(FastAPI Users 集成)"]
        AsyncSession["onyx.db.engine.async_sql_engine:get_async_session<br/>(异步 IO)"]
    end

    User --> UserDB
    AccessToken --> UserDB
    OAuthAccount --> UserDB
    UserDB --> AsyncSession

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