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

API 服务端架构

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 所定义。

应用工厂模式

应用工厂：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。

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

生命周期管理

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

启动序列

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

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

路由架构

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

路由器组织

核心 API 路由器结构

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

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

健康检查与状态端点

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

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

中间件栈

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

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

认证系统

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

认证架构

来源：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 和自定义引擎管理系统。

连接池架构

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