agentic_huge_data_base / wiki
页面 Onyx · 1.1 系统架构·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 1.1

1.1 · 系统架构（System Architecture）

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

项目Onyx 章节1.1 状态全文译文 模块存储与持久化、系统架构、安装与启动、测试、发布与运维
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节System Architecture 上一章1 下一章1.2
源码线索
  • 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/model_server/constants.py
  • backend/model_server/encoders.py
  • backend/model_server/main.py
  • backend/model_server/management_endpoints.py
  • backend/model_server/utils.py
  • backend/onyx/file_store/README.md
模块标签
  • 存储与持久化
  • 系统架构
  • 安装与启动
  • 测试、发布与运维
  • 检索、召回与索引

章节正文

系统架构

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/1.1-system-architecture

系统架构

相关源文件

以下文件为本维基页面的生成提供了上下文：

  • 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/model_server/constants.py
  • backend/model_server/encoders.py
  • backend/model_server/main.py
  • backend/model_server/management_endpoints.py
  • backend/model_server/utils.py
  • backend/onyx/file_store/README.md
  • backend/onyx/file_store/file_store.py
  • backend/onyx/file_store/gcs_file_store.py
  • backend/onyx/main.py
  • backend/onyx/natural_language_processing/constants.py
  • backend/onyx/natural_language_processing/search_nlp_models.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/onyx/utils/gpu_utils.py
  • backend/onyx/utils/search_nlp_models_utils.py
  • backend/shared_configs/configs.py
  • backend/shared_configs/model_server_models.py
  • backend/static/images/logo.png
  • backend/tests/unit/file_store/test_file_store.py
  • backend/tests/unit/model_server/test_embedding.py
  • backend/tests/unit/onyx/natural_language_processing/test_search_nlp_models.py
  • backend/tests/unit/onyx/server/scim/test_admin.py
  • backend/tests/unit/onyx/utils/test_gpu_utils.py
  • deployment/docker_compose/docker-compose.dev.yml
  • deployment/docker_compose/docker-compose.multitenant-dev.yml
  • deployment/docker_compose/docker-compose.prod-cloud.yml
  • deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml
  • deployment/docker_compose/docker-compose.prod.yml
  • deployment/docker_compose/docker-compose.search-testing.yml
  • deployment/docker_compose/docker-compose.yml
  • deployment/docker_compose/env.prod.template
  • deployment/docker_compose/env.template
  • [web/src/app/api/[...path]/route.ts](web/src/app/api/[...path]/route.ts)
  • web/src/app/auth/saml/callback/route.ts
  • web/src/lib/redirectSS.ts

本文档描述了 Onyx 平台的高层架构，包括其容器化服务、网络、数据存储和后台处理基础设施。

关于特定子系统的详细信息，请参见：

  • 后台处理与 Celery 配置：7. 后台处理与协调
  • 多租户数据隔离：9.2. 多租户架构
  • 前端构建与配置：10.1. 应用结构与配置

系统概述

Onyx 是一个由 Docker Compose 或 Kubernetes 编排的多容器应用。系统采用分层架构，包含入口层、应用逻辑层、后台处理层、AI/ML 工作负载层和数据持久化层。

核心服务
服务镜像端口用途
nginxnginx:1.25.5-alpine80, 443反向代理、SSL 终止和负载均衡 deployment/docker_compose/docker-compose.search-testing.yml:192-203。
web_serveronyxdotapp/onyx-web-server3000（内部）Next.js 前端应用 deployment/docker_compose/docker-compose.prod.yml:128-141。
api_serveronyxdotapp/onyx-backend8080通过 Uvicorn 运行 onyx.main:app 的 FastAPI 后端 deployment/docker_compose/docker-compose.prod.yml:4-13。
mcp_serveronyxdotapp/onyx-backend8090运行 onyx.mcp_server_main 的模型上下文协议（Model Context Protocol）服务器 deployment/docker_compose/docker-compose.prod.yml:151-163。
backgroundonyxdotapp/onyx-backend-由 supervisord_entrypoint.sh 管理的 Celery 工作进程 deployment/docker_compose/docker-compose.prod.yml:59-69。
inference_model_serveronyxdotapp/onyx-model-server9000运行时嵌入向量和推理 deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml:171-182。
indexing_model_serveronyxdotapp/onyx-model-server9000使用 INDEXING_ONLY=True 的文档处理嵌入向量 deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml:199-212。
relational_dbpostgres:15.2-alpine5432主 PostgreSQL 数据库 deployment/docker_compose/docker-compose.prod.yml:190-194。
indexvespaengine/vespa:8.609.3919071, 8081向量搜索和文档索引引擎 deployment/docker_compose/docker-compose.search-testing.yml:176-183。
opensearchopensearchproject/opensearch:2.11.09200备选文档索引后端 deployment/docker_compose/docker-compose.dev.yml:43-45。
cacheredis:7.4-alpine6379会话存储、Celery 消息代理和协调 deployment/docker_compose/docker-compose.dev.yml:56-58。
miniominio/minio9000, 9001兼容 S3 的对象存储，用于文件存储 deployment/docker_compose/docker-compose.prod.yml:19。
code-interpreteronyxdotapp/code-interpreter8000用于 Python 工具的代码执行沙箱 deployment/docker_compose/docker-compose.dev.yml:66-68。

来源： deployment/docker_compose/docker-compose.prod.yml:1-215、deployment/docker_compose/docker-compose.yml:1-185、deployment/docker_compose/docker-compose.dev.yml:11-69

容器架构图

Onyx · 容器架构图 · 图 1
Onyx · 容器架构图 · 图 1

来源： deployment/docker_compose/docker-compose.prod.yml:4-215、deployment/docker_compose/docker-compose.yml:40-185、deployment/docker_compose/docker-compose.dev.yml:11-69

部署配置

Onyx 通过不同的 Docker Compose 文件和环境标志支持多种部署配置：

生产部署模式
配置文件使用场景主要特性
docker-compose.yml默认配置定义所有服务；标准设置 deployment/docker_compose/docker-compose.yml:1-35。
docker-compose.prod.yml使用 Let's Encrypt 的生产环境仅 Nginx 入口、certbot 集成和 TLS deployment/docker_compose/docker-compose.prod.yml:1-215。
docker-compose.prod-no-letsencrypt.yml使用自定义 SSL 的生产环境通过 custom-ca.crt 提供用户自备证书 deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml:1-130。
docker-compose.multitenant-dev.yml多租户开发环境MULTI_TENANT=true、AUTH_TYPE=cloud、基于模式的隔离 deployment/docker_compose/docker-compose.multitenant-dev.yml:24-27。
docker-compose.dev.yml开发覆盖配置暴露内部端口（如 5432、6379）以便调试 deployment/docker_compose/docker-compose.dev.yml:1-10。
docker-compose.search-testing.yml集成测试AUTH_TYPE=basic、特定的搜索评估环境 deployment/docker_compose/docker-compose.search-testing.yml:22-24。

来源： deployment/docker_compose/docker-compose.yml:1-35、deployment/docker_compose/docker-compose.prod.yml:1-215、deployment/docker_compose/docker-compose.multitenant-dev.yml:24-27、deployment/docker_compose/docker-compose.dev.yml:1-10

网络架构

入口与路由

系统使用 Nginx 作为主要入口点，将流量路由到 Next.js web_server 或 FastAPI api_server。

服务间通信： 所有服务在 Docker 网络内使用服务名作为主机名进行通信：

  • Web → API：INTERNAL_URL=http://api_server:8080 deployment/docker_compose/docker-compose.prod.yml:141。
  • API → 数据库：POSTGRES_HOST=relational_db deployment/docker_compose/docker-compose.prod.yml:24。
  • API → Vespa：VESPA_HOST=index deployment/docker_compose/docker-compose.prod.yml:25。
  • API → OpenSearch：OPENSEARCH_HOST=opensearch deployment/docker_compose/docker-compose.prod.yml:26。
  • API → Redis：REDIS_HOST=cache deployment/docker_compose/docker-compose.prod.yml:29。
  • API → MinIO：S3_ENDPOINT_URL=http://minio:9000 deployment/docker_compose/docker-compose.prod.yml:37。
  • API → 模型服务器：MODEL_SERVER_HOST=inference_model_server deployment/docker_compose/docker-compose.prod.yml:30。

来源： deployment/docker_compose/docker-compose.prod.yml:21-40、deployment/docker_compose/docker-compose.yml:76-90

数据存储架构

Onyx 使用多种数据存储来处理不同类型的信息：

PostgreSQL 配置（relational_db）
  • 用途：用户、连接器、凭证和聊天记录的主要关系型存储。
  • 持久化：命名卷 db_volume deployment/docker_compose/docker-compose.search-testing.yml:173。
  • 配置：最大连接数设置为 250 deployment/docker_compose/docker-compose.prod.yml:193。多租户部署使用 alembic -n schema_private upgrade head deployment/docker_compose/docker-compose.multitenant-dev.yml:11。
文档索引（index / opensearch）
  • Vespa：主要的向量和关键词搜索引擎 deployment/docker_compose/docker-compose.prod.yml:25。
  • OpenSearch：备选索引后端。通过 ENABLE_OPENSEARCH_INDEXING_FOR_ONYX 启用 deployment/docker_compose/docker-compose.prod.yml:28。
  • 搜索逻辑：通过特定的模型服务器编码器支持混合搜索和文档索引 backend/model_server/encoders.py:22。
Redis 缓存（cache）
  • 用途：Celery 的任务消息代理、分布式锁和会话缓存。
  • 后端：可通过环境变量配置 deployment/docker_compose/docker-compose.prod.yml:29。
MinIO 对象存储（minio）
  • 用途：兼容 S3 的存储，用于上传文件和持久化文档存储 deployment/docker_compose/docker-compose.prod.yml:37-39。
  • 配置：使用 S3_ENDPOINT_URL、S3_AWS_ACCESS_KEY_ID 和 S3_AWS_SECRET_ACCESS_KEY deployment/docker_compose/docker-compose.prod.yml:93-95。

来源： deployment/docker_compose/docker-compose.prod.yml:21-40、deployment/docker_compose/docker-compose.multitenant-dev.yml:11、backend/model_server/encoders.py:22

后端基础设施

FastAPI 应用（api_server）

后端是一个 FastAPI 应用，负责处理：

  • 认证：通过 AUTH_TYPE（oidc、basic、cloud）支持多种认证方式 backend/onyx/main.py:40。
  • 数据库迁移：启动时运行 alembic upgrade head deployment/docker_compose/docker-compose.prod.yml:11。
  • API 路由：组织为聊天、角色和文档管理的子路由器 backend/onyx/main.py:73-131。
后台处理（后台）

后台任务通过 Celery 管理，并由 supervisord_entrypoint.sh 监督 deployment/docker_compose/docker-compose.prod.yml:69。

  • 模型交互：使用 indexing_model_server 进行后台文档嵌入向量生成 deployment/docker_compose/docker-compose.prod.yml:87。
  • 任务协调：使用 Redis 进行任务队列和协调 deployment/docker_compose/docker-compose.prod.yml:85。
模型服务器

系统将模型工作负载分离为两个服务，以防止索引过程拖慢用户聊天：

  • 推理服务器：处理实时查询嵌入向量和重排序 deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml:171-182。
  • 索引服务器：专门用于后台文档嵌入向量生成，配置为 INDEXING_ONLY=True backend/shared_configs/configs.py:66。

来源： backend/onyx/main.py:1-131、deployment/docker_compose/docker-compose.prod.yml:59-101、backend/shared_configs/configs.py:64-66

代码实体映射

此图将高层服务架构与具体的代码入口点和配置符号关联起来。

Onyx · 代码实体映射 · 图 2
Onyx · 代码实体映射 · 图 2

来源： backend/onyx/main.py:12、backend/model_server/main.py:129、deployment/docker_compose/docker-compose.prod.yml:9-69、backend/shared_configs/configs.py:14-66

数据流：从文档索引到搜索

此图展示了数据从后台处理到文档索引的流动过程。

Onyx · 数据流：从文档索引到搜索 · 图 3
Onyx · 数据流：从文档索引到搜索 · 图 3

来源： backend/model_server/encoders.py:28-103、backend/onyx/natural_language_processing/search_nlp_models.py:70-75、deployment/docker_compose/docker-compose.prod.yml:59-87