1 · 总览（Overview）

总览

概述

相关源文件

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

• CONTRIBUTING.md
• README.md
• README.zh-CN.md
• backend/alembic/README.md
• backend/alembic/versions/6a804aeb4830_duplicated_no_harm_user_file_migration.py
• backend/alembic/versions/9aadf32dfeb4_add_user_files.py
• backend/alembic_tenants/versions/3b45e0018bf1_add_new_available_tenant_table.py
• backend/ee/onyx/background/celery/apps/primary.py
• backend/ee/onyx/background/celery/tasks/beat_schedule.py
• backend/ee/onyx/background/celery/tasks/tenant_provisioning/tasks.py
• backend/ee/onyx/server/tenants/schema_management.py
• backend/onyx/background/celery/apps/app_base.py
• backend/onyx/background/celery/apps/beat.py
• backend/onyx/background/celery/apps/heavy.py
• backend/onyx/background/celery/apps/light.py
• backend/onyx/background/celery/apps/monitoring.py
• backend/onyx/background/celery/apps/primary.py
• backend/onyx/background/celery/tasks/beat_schedule.py
• backend/onyx/background/celery/tasks/shared/tasks.py
• backend/onyx/background/celery/tasks/vespa/tasks.py
• backend/onyx/configs/app_configs.py
• backend/onyx/configs/constants.py
• backend/onyx/connectors/README.md
• backend/onyx/db/tag.py
• backend/onyx/document_index/factory.py
• backend/onyx/redis/redis_pool.py
• backend/onyx/server/features/build/db/sandbox.py
• backend/scripts/dev_run_background_jobs.py
• backend/supervisord.conf
• backend/tests/external_dependency_unit/db/test_tag_race_condition.py
• backend/tests/external_dependency_unit/redis/test_tenant_redis.py
• backend/tests/integration/multitenant_tests/tenants/test_tenant_provisioning_rollback.py
• backend/tests/integration/tests/indexing/file_connector/test_files/.onyx_metadata.json
• backend/tests/unit/ee/onyx/server/tenants/test_schema_management.py
• backend/tests/unit/onyx/background/celery/tasks/tenant_provisioning/__init__.py
• backend/tests/unit/onyx/background/celery/tasks/tenant_provisioning/test_check_available_tenants.py
• deployment/README.md
• deployment/docker_compose/README.md

本文档提供 Onyx 系统架构、核心组件和部署模型的高层概述。Onyx 是一个基于 AI 的知识管理和聊天平台，它结合了文档索引、语义搜索和大语言模型（LLM）集成，能够对已连接的数据源进行企业级问答。

有关特定子系统的详细信息，请参考以下内容：

• 系统架构详情：系统架构
• 关键概念与定义：关键概念与术语
• 连接器配置：数据源与连接器
• 聊天系统内部机制：聊天与会话系统
• 部署流程：安装与部署
• 后台任务处理：后台处理与协调

什么是 Onyx

Onyx 是一个开源 AI 平台，作为大语言模型（LLM）的应用层 README.md:28-31。它提供了功能丰富的界面，用于：

1. 连接 60 多种数据源，包括 Slack、Confluence、Google Drive、GitHub 和 SharePoint，通过基于索引的连接器或 MCP 实现 README.md:31-33。
2. 索引和向量化文档，使用嵌入向量模型实现高级检索增强生成（RAG）README.md:47-48。
3. 提供 AI 聊天界面，支持网络搜索、代码执行、文件创建和深度研究模式 README.md:49-57。
4. 支持多租户部署，通过基于模式的隔离机制适用于企业级和云环境 README.md:92-96。
5. 实现权限感知搜索，通过同步源系统的访问控制确保数据安全访问 README.md:97。

来源： README.md:28-118，backend/onyx/configs/app_configs.py:126-150

系统架构总览

以下图表展示了主要服务及其关系，突出了应用程序代码与数据基础设施之间的交互。

系统交互图

后台协调图

此图将系统组件映射到管理它们的代码实体，特别展示了 celery 工作者在代码库中是如何定义和隔离的。

来源： backend/supervisord.conf:30-125，backend/onyx/background/celery/apps/primary.py:53-172，backend/onyx/background/celery/apps/beat.py:27-161，CONTRIBUTING.md:80-86

核心组件

前端：Next.js Web 应用程序

Web 界面是一个 Next.js 应用程序，提供主要的用户和管理员体验。

• 主要用户界面： 用于对话式 AI 的聊天界面和用于系统配置的管理员仪表盘。
• 独立构建： 构建为独立的 Next.js 应用程序，适用于容器化部署。
• 状态管理： 使用 SWR 进行数据获取和缓存。

来源： README.md:30-41，CONTRIBUTING.md:131-143

后端 API：FastAPI 服务器

核心 API 服务器处理业务逻辑、安全性和协调工作。

• 职责： REST API 端点、用于聊天流式的 WebSocket/SSE，以及大语言模型（LLM）编排。
• 数据库访问： 使用 SQLAlchemy 进行关系数据管理，使用 alembic 进行迁移。
• 配置： 通过 onyx.configs.app_configs 管理，该模块负责解析环境变量 backend/onyx/configs/app_configs.py:22-150。

来源： backend/onyx/configs/app_configs.py:1-150，CONTRIBUTING.md:98-130

文档索引与搜索

Onyx 支持高性能混合搜索（向量 + 关键词）。

• Vespa： 用于检索增强生成（RAG）工作负载的默认主索引。
• OpenSearch： 系统支持的替代索引后端。
• 索引管线： 由后台任务协调，例如 check_for_vespa_sync_task backend/onyx/background/celery/tasks/vespa/tasks.py:82-109。

来源： README.md:79-85，backend/onyx/background/celery/tasks/vespa/tasks.py:75-120

后台处理

异步工作负载由 Celery 工作者管理，通过 Redis 进行协调。

• 工作者池： 分为 primary、light、heavy、docprocessing 和 docfetching，以防止瓶颈 backend/supervisord.conf:30-103。
• 任务调度： 由 DynamicTenantScheduler 管理，该调度器会动态调整任务生成速率 backend/onyx/background/celery/apps/beat.py:27-48。
• 多租户： 使用 TenantRedis 提供基于模式的隔离，通过自动为 Redis 键添加 tenant_id 前缀实现 backend/onyx/redis/redis_pool.py:65-91。

来源： backend/supervisord.conf:30-125，backend/onyx/background/celery/apps/beat.py:27-161，backend/onyx/redis/redis_pool.py:65-180

部署模式

Onyx 支持两种主要部署模式，以平衡资源使用和功能需求：

部署平台： 支持 Docker、Kubernetes（Helm）和主流云服务提供商 README.md:68-70。

技术栈总结

来源： README.md:79-85，CONTRIBUTING.md:80-86，backend/onyx/redis/redis_pool.py:65-180