8.2 · API 服务端架构（API Server Architecture）

API 服务端架构（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/onyx-dot-app/onyx/8.2-api-server-architecture

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

翻译模型：deepseek-chat

原文字符数：14210

项目：Onyx (onyx)

---

API 服务器架构

相关源文件

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

• 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/main.py
• backend/onyx/server/auth_check.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/unit/onyx/server/scim/test_admin.py
• web/src/app/auth/saml/callback/route.ts
• web/src/lib/redirectSS.ts

目的与范围

本文档描述了基于 FastAPI 的 API 服务器，它为 Onyx 的后端操作提供支持。内容涵盖应用初始化、路由结构、中间件栈、认证集成、数据库连接管理以及可观测性配置。有关 Web 服务器（Next.js 前端）的信息，请参阅应用结构与配置。有关后台任务处理，请参阅Celery 工作器架构。

---

应用入口点与初始化

API 服务器是一个 FastAPI 应用，在 backend/onyx/main.py 中初始化，企业版扩展位于 backend/ee/onyx/main.py。该应用运行在主机 0.0.0.0 和端口 8080 上，如 backend/onyx/configs/app_configs.py:37-38 所定义。

应用工厂模式

graph TB
    get_application["get_application() [ee/onyx/main.py]"]
    get_application_base["get_application_base() [onyx/main.py]"]
    lifespan["lifespan() [ee/onyx/main.py]"]
    lifespan_base["lifespan_base() [onyx/main.py]"]
    FastAPI["FastAPI(lifespan=...)"]

    get_application -->|"调用（企业版）"| get_application_base
    get_application -->|"传递覆盖"| lifespan
    lifespan -->|"包装"| lifespan_base
    get_application_base -->|创建| FastAPI
    FastAPI -->|"使用"| lifespan

    get_application_base -->|"添加路由器"| Routers["路由器注册"]
    get_application -->|"添加企业版路由器"| EERouters["企业版路由器注册"]

应用工厂：MIT 版 vs 企业版

来源：backend/onyx/main.py:335-344, backend/ee/onyx/main.py:81-159

企业版中的 get_application() 函数将 global_version 设置为企业版模式，并在注册企业版专属路由器之前应用额外的中间件，例如许可证强制执行或租户跟踪 backend/ee/onyx/main.py:81-159。

graph LR
    subgraph "FastAPI 配置 [onyx/main.py]"
        Title["title: 'Onyx Backend'"]
        Version["version: __version__"]
        Description["description: API 文档"]
        Servers["servers: WEB_DOMAIN/api"]
        Lifespan["lifespan: AsyncContextManager"]
    end

来源：backend/onyx/main.py:336-344

---

生命周期管理

应用生命周期通过一个 @asynccontextmanager 进行管理，它处理启动和关闭操作。在企业版中，生命周期还通过 seed_db() 处理数据库种子数据 backend/ee/onyx/main.py:74。

sequenceDiagram
    participant App as FastAPI 应用
    participant Lifespan as lifespan()
    participant SqlEngine
    participant WarmUp as warm_up_connections()
    participant Setup as setup_onyx()
    participant Seed as seed_db()
    participant RateLimiter as 认证速率限制器

    App->>Lifespan: 启动
    Lifespan->>Lifespan: 设置递归限制
    Lifespan->>SqlEngine: init_engine(pool_size, overflow)
    Lifespan->>SqlEngine: init_readonly_engine(pool_size, overflow)
    Lifespan->>Lifespan: verify_auth_setting()
    Lifespan->>WarmUp: warm_up_connections()
    Lifespan->>Setup: 初始化数据库模式
    Lifespan->>Seed: seed_db() [仅企业版]
    Lifespan->>RateLimiter: setup_auth_limiter()（如果启用）
    Lifespan->>App: 就绪

    Note over App: 应用运行中

    App->>Lifespan: 关闭
    Lifespan->>SqlEngine: reset_engine()
    Lifespan->>RateLimiter: close_auth_limiter()（如果启用）
    Lifespan->>App: 完成

启动序列

来源：backend/onyx/main.py:244-309, backend/ee/onyx/main.py:67-79

步骤	操作	配置
1	设置递归限制	SYSTEM_RECURSION_LIMIT
2	初始化主引擎	POSTGRES_API_SERVER_POOL_SIZE=40, POSTGRES_API_SERVER_POOL_OVERFLOW=10
3	初始化只读引擎	POSTGRES_API_SERVER_READ_ONLY_POOL_SIZE=10, POSTGRES_API_SERVER_READ_ONLY_POOL_OVERFLOW=5
4	验证认证	检查 AuthType 有效性
5	预热连接	warm_up_connections()
6	运行数据库迁移	setup_onyx() 或 setup_multitenant_onyx()
7	种子数据库（企业版）	seed_db()
8	初始化速率限制器	如果 AUTH_RATE_LIMITING_ENABLED

来源：backend/onyx/main.py:246-308, backend/onyx/configs/app_configs.py:50-57, backend/ee/onyx/main.py:76

---

路由架构

API 服务器使用模块化的路由器结构。路由按功能领域组织，包含 MIT 版和企业版路由器。

路由器组织

核心 API 路由器结构

graph TB
    subgraph "聊天与查询路由器"
        chat_router["chat_router [onyx/server/query_and_chat/chat_backend.py]"]
        query_router["query_router [onyx/server/query_and_chat/query_backend.py]"]
    end

    subgraph "文档管理路由器"
        document_router["document_router [/document]"]
        connector_router["connector_router [/manage/admin/connector]"]
        credential_router["credential_router [/manage/credential]"]
        cc_pair_router["cc_pair_router [/manage/admin/cc-pair]"]
    end

    subgraph "管理与配置路由器"
        admin_router["admin_router [/admin]"]
        admin_persona_router["admin_persona_router [/admin/persona]"]
        llm_admin_router["llm_admin_router [/admin/llm]"]
        embedding_admin_router["embedding_admin_router [/admin/embedding]"]
    end

    subgraph "认证路由器"
        auth_router["auth_router [fastapi_users.get_auth_router()]"]
        oauth_router["oauth_router [create_onyx_oauth_router()]"]
    end

    FastAPIApp["FastAPI 应用 [onyx/main.py]"]

    FastAPIApp -->|"include_router"| chat_router
    FastAPIApp -->|"include_router"| query_router
    FastAPIApp -->|"include_router"| document_router
    FastAPIApp -->|"include_router"| admin_router

来源：backend/onyx/main.py:363-424, backend/onyx/auth/users.py:33

全局前缀处理

所有路由器都通过 include_router_with_global_prefix_prepended() 注册，该函数处理可选的 APP_API_PREFIX 环境变量 backend/onyx/main.py:207-223。

graph LR
    Router["APIRouter"]
    Function["include_router_with_global_prefix_prepended()"]
    APP_API_PREFIX["APP_API_PREFIX [例如 '/api']"]
    FinalRoute["最终路径"]

    Router -->|"传递给"| Function
    APP_API_PREFIX -->|"前置"| Function
    Function -->|"生成"| FinalRoute

来源：backend/onyx/main.py:207-223, backend/onyx/configs/app_configs.py:36

路由器注册模式

MIT 版路由器（在 backend/onyx/main.py:363-424 中注册）：

• 聊天：chat_router, chat_v0_router
• 查询：query_router, admin_query_router
• 文档：document_router, connector_router, credential_router, cc_pair_router
• 管理：admin_router, user_router, admin_persona_router
• 配置：llm_router, llm_admin_router, embedding_router, embedding_admin_router

企业版路由器（在 backend/ee/onyx/main.py:130-155 中注册）：

• 访问控制：user_group_router
• 分析：analytics_router, query_history_router
• 企业设置：enterprise_settings_router, enterprise_settings_admin_router
• 多租户：tenants_router（如果 MULTI_TENANT=true）
• 计费：billing_router

来源：backend/onyx/main.py:363-424, backend/ee/onyx/main.py:130-164

---

健康检查与状态端点

服务器提供多个公共端点，用于健康监控、版本跟踪和客户端配置。

端点	方法	用途	文件
/health	GET	返回 200 以验证服务器可用性	backend/onyx/server/auth_check.py:25
/auth/type	GET	返回当前的 AUTH_TYPE	backend/onyx/server/auth_check.py:28
/version	GET	返回应用版本（例如 0.3.11）	backend/onyx/server/auth_check.py:30
/settings	GET	获取通用应用和用户特定设置	backend/onyx/server/settings/api.py:71
/enterprise-settings	GET	（企业版）获取 Logo、标识和自定义 UI 配置	backend/ee/onyx/server/enterprise_settings/api.py:135

来源：backend/onyx/server/auth_check.py:17-65, backend/ee/onyx/server/enterprise_settings/api.py:134-141

---

中间件栈

中间件通过 app.add_middleware() 注册，并按注册顺序的逆序执行。

graph TB
    Request["传入的 HTTP 请求"]

    subgraph "中间件栈"
        CORSMiddleware["CORSMiddleware [onyx/main.py]"]
        TenantMiddleware["TenantIDMiddleware [ee/onyx/server/middleware/tenant_tracking.py]"]
        RateLimitMiddleware["RateLimitingMiddleware [onyx/server/middleware/rate_limiting.py]"]
        LatencyMiddleware["LatencyLoggingMiddleware [onyx/server/middleware/latency_logging.py]"]
    end

    Handler["路由处理器"]

    Request --> CORSMiddleware
    CORSMiddleware --> TenantMiddleware
    TenantMiddleware --> RateLimitMiddleware
    RateLimitMiddleware --> LatencyMiddleware
    LatencyMiddleware --> Handler

来源：backend/onyx/main.py:427-448, backend/ee/onyx/main.py:89-94

---

认证系统

API 服务器使用 FastAPI Users，并支持可插拔的认证后端。

认证架构

graph TB
    subgraph "认证后端 [onyx/auth/users.py]"
        AuthBackend["auth_backend [Redis 或 Postgres 策略]"]
        CookieTransport["CookieTransport"]
    end

    subgraph "用户管理"
        UserManager["UserManager [onyx/auth/users.py]"]
        SQLAlchemyUserDB["SQLAlchemyUserDatabase"]
    end

    subgraph "FastAPI Users 实例"
        fastapi_users["fastapi_users [FastAPIUsers[User, UUID]]"]
    end

    AuthBackend --> CookieTransport
    CookieTransport --> fastapi_users
    UserManager --> fastapi_users
    SQLAlchemyUserDB --> UserManager

来源：backend/onyx/auth/users.py:32-34

公共路由与私有路由

check_router_auth 函数强制执行所有路由要么明确标记为公共，要么需要用户依赖 backend/onyx/server/auth_check.py:101-108。

• 公共路由：在 PUBLIC_ENDPOINT_SPECS 中定义，包括 /health、/version 和 OAuth 回调路径 backend/onyx/server/auth_check.py:16-68。
• 私有路由：必须包含诸如 current_user 或 require_permission(Permission.FULL_ADMIN_PANEL_ACCESS) 之类的依赖 backend/onyx/server/auth_check.py:130-146。

来源：backend/onyx/server/auth_check.py:17-68, backend/onyx/server/auth_check.py:101-154

SAML 和 OAuth 回调

SAML 回调需要特殊处理，以确保安全重定向和用户插入/更新。SAML 用户由其身份提供者预先验证 backend/onyx/server/saml.py:51-119。

来源：backend/onyx/server/saml.py:51-119, web/src/app/auth/saml/callback/route.ts:10-68

---

数据库层

API 服务器使用 SQLAlchemy 和自定义引擎管理系统。

连接池架构

graph TB
    subgraph "SqlEngine [onyx/db/engine/sql_engine.py]"
        MainEngine["主引擎 [读写]"]
        ReadOnlyEngine["只读引擎"]
    end

    subgraph "连接池配置"
        PoolSize["POSTGRES_API_SERVER_POOL_SIZE"]
        PoolOverflow["POSTGRES_API_SERVER_POOL_OVERFLOW"]
    end

    MainEngine --> PoolSize
    MainEngine --> PoolOverflow

来源：backend/onyx/main.py:250-261, backend/onyx/configs/app_configs.py:52-55

多租户模式隔离

对于多租户部署（MULTI_TENANT=true），每个租户都有一个隔离的 PostgreSQL 模式。get_session_with_current_tenant() 函数使用 CURRENT_TENANT_ID_CONTEXTVAR 检索为当前租户上下文配置的会话 backend/onyx/db/engine/sql_engine.py:63。

来源：backend/onyx/db/engine/sql_engine.py:63

---

错误处理

API 服务器通过 register_onyx_exception_handlers 实现全面的错误处理 backend/onyx/main.py:65。

• 校验错误：捕获 RequestValidationError 并返回标准化的 JSONResponse，状态码为 422 backend/onyx/main.py:17-19。
• 自定义异常：处理 OnyxError 和 HTTPException，以确保向前端发送一致的错误消息 backend/onyx/main.py:14-15。

来源：backend/onyx/main.py:14-65

---

监控与可观测性

Sentry 集成

如果提供了 SENTRY_DSN，则会使用 FastApiIntegration 和 StarletteIntegration 初始化 Sentry，以跟踪错误和性能 backend/onyx/main.py:10-25。

来源：backend/onyx/main.py:10-25

Prometheus 指标

服务器通过 setup_prometheus_metrics 暴露 Prometheus 指标。此外，还使用 setup_postgres_connection_pool_metrics 监控数据库连接池的健康状况 backend/onyx/main.py:132-135。

来源：backend/onyx/main.py:132-135