1.1 · 系统架构（System Architecture）

企业连接器与统一搜索 · 本章是 Onyx DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目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

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

翻译模型：deepseek-chat

原文字符数：17815

项目：Onyx (onyx)

---

系统架构

系统概述

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

核心服务

服务	镜像	端口	用途
`nginx`	`nginx:1.25.5-alpine`	80, 443	反向代理、SSL 终止和负载均衡 `deployment/docker_compose/docker-compose.search-testing.yml:192-203`。
`web_server`	`onyxdotapp/onyx-web-server`	3000（内部）	Next.js 前端应用 `deployment/docker_compose/docker-compose.prod.yml:128-141`。
`api_server`	`onyxdotapp/onyx-backend`	8080	通过 Uvicorn 运行 `onyx.main:app` 的 FastAPI 后端 `deployment/docker_compose/docker-compose.prod.yml:4-13`。
`mcp_server`	`onyxdotapp/onyx-backend`	8090	运行 `onyx.mcp_server_main` 的模型上下文协议（Model Context Protocol）服务器 `deployment/docker_compose/docker-compose.prod.yml:151-163`。
`background`	`onyxdotapp/onyx-backend`	-	由 `supervisord_entrypoint.sh` 管理的 Celery 工作进程 `deployment/docker_compose/docker-compose.prod.yml:59-69`。
`inference_model_server`	`onyxdotapp/onyx-model-server`	9000	运行时嵌入向量和推理 `deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml:171-182`。
`indexing_model_server`	`onyxdotapp/onyx-model-server`	9000	使用 `INDEXING_ONLY=True` 的文档处理嵌入向量 `deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml:199-212`。
`relational_db`	`postgres:15.2-alpine`	5432	主 PostgreSQL 数据库 `deployment/docker_compose/docker-compose.prod.yml:190-194`。
`index`	`vespaengine/vespa:8.609.39`	19071, 8081	向量搜索和文档索引引擎 `deployment/docker_compose/docker-compose.search-testing.yml:176-183`。
`opensearch`	`opensearchproject/opensearch:2.11.0`	9200	备选文档索引后端 `deployment/docker_compose/docker-compose.dev.yml:43-45`。
`cache`	`redis:7.4-alpine`	6379	会话存储、Celery 消息代理和协调 `deployment/docker_compose/docker-compose.dev.yml:56-58`。
`minio`	`minio/minio`	9000, 9001	兼容 S3 的对象存储，用于文件存储 `deployment/docker_compose/docker-compose.prod.yml:19`。
`code-interpreter`	`onyxdotapp/code-interpreter`	8000	用于 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

---

容器架构图

graph TB
    subgraph "入口层"
        nginx["nginx<br/>(nginx:1.25.5-alpine)<br/>端口 80, 443"]
    end

    subgraph "应用层"
        web_server["web_server<br/>(onyxdotapp/onyx-web-server)<br/>Next.js<br/>内部端口 3000"]
        api_server["api_server<br/>(onyxdotapp/onyx-backend)<br/>FastAPI + Uvicorn<br/>端口 8080"]
        mcp_server["mcp_server<br/>(onyxdotapp/onyx-backend)<br/>模型上下文协议<br/>端口 8090"]
    end

    subgraph "后台处理层"
        background["background<br/>(onyxdotapp/onyx-backend)<br/>Celery + supervisord"]
        celery_beat["celery_beat<br/>(background 内部)"]
    end

    subgraph "AI/ML 层"
        inference["inference_model_server<br/>(onyxdotapp/onyx-model-server)<br/>端口 9000"]
        indexing["indexing_model_server<br/>(onyxdotapp/onyx-model-server)<br/>INDEXING_ONLY=True<br/>端口 9000"]
    end

    subgraph "数据层"
        relational_db[("relational_db<br/>(postgres:15.2-alpine)<br/>端口 5432")]
        index_vespa[("index<br/>(vespaengine/vespa)<br/>端口 19071, 8081")]
        opensearch[("opensearch<br/>(opensearchproject/opensearch)<br/>端口 9200")]
        cache[("cache<br/>(redis:7.4-alpine)<br/>端口 6379")]
        minio[("minio<br/>(minio/minio)<br/>端口 9000, 9001")]
    end

    subgraph "外部服务"
        code_interpreter["code-interpreter<br/>(onyxdotapp/code-interpreter)<br/>端口 8000"]
    end

    nginx --> web_server
    nginx --> api_server

    web_server -->|INTERNAL_URL| api_server
    api_server --> mcp_server

    api_server --> relational_db
    api_server --> index_vespa
    api_server --> opensearch
    api_server --> cache
    api_server --> minio
    api_server --> inference

    background --> relational_db
    background --> index_vespa
    background --> opensearch
    background --> cache
    background --> minio
    background --> indexing

    mcp_server --> relational_db
    mcp_server --> cache
    mcp_server -->|API 调用| api_server

    api_server -.->|可选| code_interpreter

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

---

代码实体映射

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

graph LR
    subgraph "代码入口点"
        main_app["FastAPI 应用<br/>(onyx.main:app)"]
        model_app["模型服务器应用<br/>(model_server.main:app)"]
        bg_entry["Supervisord 入口点<br/>(supervisord_entrypoint.sh)"]
    end

    subgraph "系统服务"
        api_server_svc["api_server 服务"]
        background_svc["background 服务"]
        model_server_svc["inference_model_server"]
    end

    subgraph "配置符号"
        auth_type_cfg["AUTH_TYPE<br/>(onyx.configs.app_configs)"]
        indexing_only_cfg["INDEXING_ONLY<br/>(shared_configs.configs)"]
        model_host_cfg["MODEL_SERVER_HOST<br/>(shared_configs.configs)"]
    end

    api_server_svc --> main_app
    background_svc --> bg_entry
    model_server_svc --> model_app

    main_app --> auth_type_cfg
    model_app --> indexing_only_cfg
    api_server_svc --> model_host_cfg

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

---

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

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

graph TD
    subgraph "后台任务"
        fetcher["连接器获取"]
        processor["文档处理"]
    end

    subgraph "模型服务器"
        embed_fn["embed_text<br/>(model_server.encoders)"]
        st_model["SentenceTransformer<br/>(get_embedding_model)"]
    end

    subgraph "数据存储"
        vespa_idx["Vespa 索引<br/>(index 服务)"]
        pg_db["PostgreSQL<br/>(relational_db)"]
    end

    fetcher --> processor
    processor -->|EmbedRequest| embed_fn
    embed_fn --> st_model
    st_model -->|EmbedResponse| processor
    processor -->|Upsert| vespa_idx
    processor -->|元数据| pg_db

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