2.1 · Docker Compose 部署（Docker Compose Deployment）

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

项目Onyx 章节2.1 状态全文译文模块安装与启动、存储与持久化、界面与交互、系统架构

项目要点页2.5 参考项目项目章节目录Onyx DeepWiki 原始章节Docker Compose Deployment 上一章2 下一章2.2

源码线索

backend/onyx/file_store/README.md
backend/onyx/file_store/file_store.py
backend/onyx/file_store/gcs_file_store.py
backend/tests/unit/file_store/test_file_store.py
cli/cmd/chat.go
cli/cmd/experiments.go
cli/cmd/root.go
cli/internal/config/config.go
cli/internal/config/config_test.go
cli/internal/config/experiments.go

模块标签

安装与启动
存储与持久化
界面与交互
系统架构
接口与服务契约

中文译文

Docker Compose 部署（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/onyx-dot-app/onyx/2.1-docker-compose-deployment

翻译时间：2026-05-27T08:45:01.285Z

翻译模型：deepseek-chat

原文字符数：18549

项目：Onyx (onyx)

---

Docker Compose 部署

目的与范围

本文档介绍 Onyx 的 Docker Compose 部署配置，包括服务架构、可用的部署模式以及配置管理。有关不同平台上的通用部署策略，请参见安装与部署。有关环境变量配置的详细信息，请参见环境配置。有关 Kubernetes 部署，请参见2.2 Kubernetes 部署。

可用的 Compose 文件

Onyx 为不同的部署场景提供了多个 Docker Compose 配置：

文件	用途	使用场景
`docker-compose.yml`	基础配置	默认单租户部署 `deployment/docker_compose/docker-compose.yml:1-382`
`docker-compose.dev.yml`	开发覆盖层	暴露所有服务端口用于调试 `deployment/docker_compose/docker-compose.dev.yml:1-69`
`docker-compose.prod.yml`	生产环境（带 SSL）	使用 Let's Encrypt 的生产部署 `deployment/docker_compose/docker-compose.prod.yml:1-382`
`docker-compose.prod-no-letsencrypt.yml`	生产环境（不带 SSL）	使用手动 SSL 证书的生产部署 `deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml:1-352`
`docker-compose.prod-cloud.yml`	多租户生产环境	带租户隔离的云部署 `deployment/docker_compose/docker-compose.prod-cloud.yml:1-316`
`docker-compose.multitenant-dev.yml`	多租户开发环境	用于多租户的开发环境 `deployment/docker_compose/docker-compose.multitenant-dev.yml:1-377`
`docker-compose.search-testing.yml`	搜索评估	测试和基准测试搜索性能 `deployment/docker_compose/docker-compose.search-testing.yml:1-267`
`docker-compose.onyx-lite.yml`	最小化部署	不包含向量数据库或模型服务器的部署 `deployment/docker_compose/install.sh:108-119`

来源： deployment/docker_compose/docker-compose.yml:1-382, deployment/docker_compose/docker-compose.dev.yml:1-69, deployment/docker_compose/docker-compose.prod.yml:1-382, deployment/docker_compose/install.sh:108-119

服务架构

系统组件交互

graph TB
    subgraph "外部访问"
        Client["客户端浏览器/API"]
    end

    subgraph "入口层"
        Nginx["nginx:1.25.5-alpine<br/>端口: 80, 443"]
        Certbot["certbot/certbot<br/>SSL 续期"]
    end

    subgraph "应用服务"
        API["api_server<br/>onyxdotapp/onyx-backend<br/>端口 8080<br/>命令: uvicorn onyx.main:app"]
        Web["web_server<br/>onyxdotapp/onyx-web-server<br/>端口 3000<br/>INTERNAL_URL=http://api_server:8080"]
        MCP["mcp_server<br/>onyxdotapp/onyx-backend<br/>端口 8090<br/>命令: python -m onyx.mcp_server_main"]
        Background["background<br/>onyxdotapp/onyx-backend<br/>命令: supervisord_entrypoint.sh"]
    end

    subgraph "AI/ML 服务"
        Inference["inference_model_server<br/>onyxdotapp/onyx-model-server<br/>端口 9000<br/>ENV: INDEXING_ONLY=false"]
        Indexing["indexing_model_server<br/>onyxdotapp/onyx-model-server<br/>端口 9000<br/>ENV: INDEXING_ONLY=True"]
        CodeInterpreter["code-interpreter<br/>onyxdotapp/code-interpreter<br/>端口 8000"]
    end

    subgraph "数据服务"
        Postgres["relational_db<br/>postgres:15.2-alpine<br/>端口 5432<br/>卷: db_volume"]
        Vespa["index<br/>vespaengine/vespa:8.609.39<br/>端口: 19071, 8081<br/>卷: vespa_volume"]
        Redis["cache<br/>redis:7.4-alpine<br/>端口 6379<br/>命令: --save '' --appendonly no"]
        MinIO["minio<br/>minio/minio:RELEASE.2025-07-23<br/>端口: 9000, 9001<br/>卷: minio_data"]
        OpenSearch["opensearch<br/>opensearchproject/opensearch:2.11.0"]
    end

    Client --> Nginx
    Nginx --> Web
    Nginx --> API
    Certbot -.->|续期证书| Nginx

    Web --> API
    API --> MCP
    API --> Postgres
    API --> Vespa
    API --> OpenSearch
    API --> Redis
    API --> MinIO
    API --> Inference

    Background --> Postgres
    Background --> Vespa
    Background --> Redis
    Background --> MinIO
    Background --> Indexing

    MCP --> API

    CodeInterpreter --> API

来源： deployment/docker_compose/docker-compose.yml:39-382, deployment/docker_compose/docker-compose.prod.yml:4-382

核心服务

api_server

处理所有 API 请求的 FastAPI 后端服务器。

容器详情：

镜像： onyxdotapp/onyx-backend:${IMAGE_TAG:-latest} deployment/docker_compose/docker-compose.yml:41
端口： 8080（内部） deployment/docker_compose/docker-compose.yml:50
命令： alembic upgrade head && uvicorn onyx.main:app --host 0.0.0.0 --port 8080 deployment/docker_compose/docker-compose.yml:48-50
依赖： relational_db, index, opensearch, cache, inference_model_server, minio deployment/docker_compose/docker-compose.yml:55-69

关键环境变量：

AUTH_TYPE - 认证方式（默认值：basic） deployment/docker_compose/docker-compose.yml:78
FILE_STORE_BACKEND - 文件存储后端（s3 或 postgres） deployment/docker_compose/docker-compose.yml:79
POSTGRES_HOST=relational_db deployment/docker_compose/docker-compose.yml:80
VESPA_HOST=index deployment/docker_compose/docker-compose.yml:81
OPENSEARCH_HOST=opensearch deployment/docker_compose/docker-compose.yml:82
REDIS_HOST=cache deployment/docker_compose/docker-compose.yml:85
MODEL_SERVER_HOST=inference_model_server deployment/docker_compose/docker-compose.yml:86
S3_ENDPOINT_URL=http://minio:9000 deployment/docker_compose/docker-compose.yml:88

该命令首先通过 Alembic 运行数据库迁移，然后启动加载 FastAPI 应用的 Uvicorn ASGI 服务器。

来源： deployment/docker_compose/docker-compose.yml:40-125, deployment/docker_compose/docker-compose.prod.yml:4-57

后台

通过 Supervisord 运行 Celery 任务的后台工作服务。

容器详情：

镜像： onyxdotapp/onyx-backend:${IMAGE_TAG:-latest} deployment/docker_compose/docker-compose.yml:127
命令： /app/scripts/supervisord_entrypoint.sh deployment/docker_compose/docker-compose.yml:141
依赖： relational_db, index, opensearch, cache, inference_model_server, indexing_model_server deployment/docker_compose/docker-compose.yml:145-158

关键环境变量：

INDEXING_MODEL_SERVER_HOST=indexing_model_server deployment/docker_compose/docker-compose.yml:169
DISCORD_BOT_TOKEN - Discord 集成的令牌 deployment/docker_compose/docker-compose.yml:173

该服务使用 Supervisord 管理多个 Celery 工作进程，包括文档获取和文档处理队列。如果启用了 Craft 模板设置，它还会处理该设置 deployment/docker_compose/docker-compose.yml:135-137。

来源： deployment/docker_compose/docker-compose.yml:126-193, deployment/docker_compose/docker-compose.prod.yml:58-125

web_server

Next.js 前端应用。

容器详情：

镜像： onyxdotapp/onyx-web-server:${IMAGE_TAG:-latest} deployment/docker_compose/docker-compose.yml:195
端口： 3000（内部） deployment/docker_compose/docker-compose.yml:209
环境变量： INTERNAL_URL=http://api_server:8080 deployment/docker_compose/docker-compose.yml:207

来源： deployment/docker_compose/docker-compose.yml:194-219, deployment/docker_compose/docker-compose.prod.yml:126-148

mcp_server

模型上下文协议服务器（可选）。

容器详情：

镜像： onyxdotapp/onyx-backend:${IMAGE_TAG:-latest} deployment/docker_compose/docker-compose.prod.yml:151
端口： 8090 deployment/docker_compose/docker-compose.prod.yml:176
命令： 在运行 python -m onyx.mcp_server_main 之前检查 MCP_SERVER_ENABLED deployment/docker_compose/docker-compose.prod.yml:158-163

来源： deployment/docker_compose/docker-compose.prod.yml:149-187

inference_model_server 和 indexing_model_server

用于嵌入向量和推理的专用模型服务器。

容器详情：

镜像： onyxdotapp/onyx-model-server:${IMAGE_TAG:-latest} deployment/docker_compose/docker-compose.prod.yml:198
端口： 9000 deployment/docker_compose/docker-compose.prod.yml:226
命令： uvicorn model_server.main:app --host 0.0.0.0 --port 9000 deployment/docker_compose/docker-compose.prod.yml:203-209

关键区别：

inference_model_server：处理运行时查询的嵌入向量。
indexing_model_server：处理文档索引的嵌入向量（环境变量：INDEXING_ONLY=True） deployment/docker_compose/docker-compose.prod.yml:235。

来源： deployment/docker_compose/docker-compose.prod.yml:197-246

数据服务

服务	镜像	用途
`relational_db`	`postgres:15.2-alpine`	主要元数据存储 `deployment/docker_compose/docker-compose.prod.yml:189`
`index`	`vespaengine/vespa:8.609.39`	向量和关键词搜索 `deployment/docker_compose/docker-compose.prod.yml:249`
`opensearch`	`opensearchproject/opensearch:2.11.0`	辅助搜索引擎 `deployment/docker_compose/docker-compose.yml:320`
`cache`	`redis:7.4-alpine`	任务队列和会话缓存 `deployment/docker_compose/docker-compose.prod.yml:335`
`minio`	`minio/minio:RELEASE.2025-07-23`	兼容 S3 的文件存储 `deployment/docker_compose/docker-compose.prod.yml:319`

来源： deployment/docker_compose/docker-compose.prod.yml:173-343, deployment/docker_compose/docker-compose.yml:320-353

部署模式

开发模式

Compose 文件： docker-compose.yml + docker-compose.dev.yml

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

关键特性：

所有服务端口均已暴露（例如，Postgres 端口 5432，Vespa 端口 19071，MinIO 端口 9004/9005） deployment/docker_compose/docker-compose.dev.yml:12-69
可以通过 API_SERVER_CPU_LIMIT 和 API_SERVER_MEM_LIMIT 配置资源限制 deployment/docker_compose/docker-compose.dev.yml:18-19
OpenSearch 的 ulimit 已重置以支持无根 Docker deployment/docker_compose/docker-compose.dev.yml:48

来源： deployment/docker_compose/docker-compose.dev.yml:1-69

生产模式（单租户）

Compose 文件： docker-compose.prod.yml

关键特性：

通过 Nginx（80/443）和 Certbot 进行 SSL 入口 deployment/docker_compose/docker-compose.prod.yml:265-317
优化日志记录（50MB x 6 个文件） deployment/docker_compose/docker-compose.prod.yml:51-52
认证默认使用 oidc deployment/docker_compose/docker-compose.prod.yml:23

来源： deployment/docker_compose/docker-compose.prod.yml:1-382

多租户生产环境（云）

Compose 文件： docker-compose.prod-cloud.yml

关键特性：

API 服务器使用 Dockerfile.cloud deployment/docker_compose/docker-compose.prod-cloud.yml:8
运行租户特定的迁移：alembic -n schema_private upgrade head deployment/docker_compose/docker-compose.prod-cloud.yml:10
认证类型默认使用 oidc deployment/docker_compose/docker-compose.prod-cloud.yml:22

来源： deployment/docker_compose/docker-compose.prod-cloud.yml:1-316

多租户开发环境

Compose 文件： docker-compose.multitenant-dev.yml

关键特性：

MULTI_TENANT=true 和 ENABLE_PAID_ENTERPRISE_EDITION_FEATURES=true deployment/docker_compose/docker-compose.multitenant-dev.yml:24-25
AUTH_TYPE=cloud deployment/docker_compose/docker-compose.multitenant-dev.yml:27
通过 alembic -n schema_private upgrade head 实现基于模式的隔离 deployment/docker_compose/docker-compose.multitenant-dev.yml:11

来源： deployment/docker_compose/docker-compose.multitenant-dev.yml:1-377

搜索测试模式

Compose 文件： docker-compose.search-testing.yml

关键特性：

AUTH_TYPE=basic deployment/docker_compose/docker-compose.search-testing.yml:24
LICENSE_ENFORCEMENT_ENABLED=false 用于评估 deployment/docker_compose/docker-compose.search-testing.yml:33
支持通过 ENV_SEED_CONFIGURATION 进行数据播种 deployment/docker_compose/docker-compose.search-testing.yml:30

来源： deployment/docker_compose/docker-compose.search-testing.yml:1-267

生产环境加固检查清单

docker-compose.yml 文件包含一份生产部署检查清单：

安全加固： 移除除 Nginx（80/443）之外的所有端口暴露 deployment/docker_compose/docker-compose.yml:12-15。
SSL/TLS 设置： 使用 Certbot 服务和生产 Nginx 模板 deployment/docker_compose/docker-compose.yml:16-20。
环境配置： 使用显式环境变量而非 env_file deployment/docker_compose/docker-compose.yml:21-23。
认证： 配置 OIDC、SAML 或 Google OAuth deployment/docker_compose/docker-compose.yml:24-26。
域名配置： 为 Nginx 和 DNS 设置 DOMAIN 变量 deployment/docker_compose/docker-compose.yml:30-32。

来源： deployment/docker_compose/docker-compose.yml:7-35

部署协调

代码实体到系统的映射

graph LR
    subgraph "后端代码实体"
        MainApp["onyx.main:app"]
        MCPServer["onyx.mcp_server_main"]
        Supervisord["supervisord_entrypoint.sh"]
        ModelApp["model_server.main:app"]
        S3Store["S3BackedFileStore"]
    end

    subgraph "Docker 服务"
        API["api_server"]
        MCP["mcp_server"]
        BG["background"]
        InfModel["inference_model_server"]
        MinIO["minio"]
    end

    MainApp --- API
    MCPServer --- MCP
    Supervisord --- BG
    ModelApp --- InfModel
    S3Store --- MinIO

来源： deployment/docker_compose/docker-compose.prod.yml:13,69,162,181, backend/onyx/file_store/file_store.py:177-180

数据流和卷映射

graph TD
    subgraph "容器路径"
        LogPath["/var/log/onyx"]
        DataPath["/var/lib/postgresql/data"]
        VespaPath["/opt/vespa/var"]
        FilePath["/app/file-system"]
        HuggingFaceCache["/app/.cache/huggingface/"]
    end

    subgraph "命名卷"
        LogVol["api_server_logs"]
        DBVol["db_volume"]
        VespaVol["vespa_volume"]
        FileVol["file-system"]
        HFVol["model_cache_huggingface"]
    end

    LogPath --- LogVol
    DataPath --- DBVol
    VespaPath --- VespaVol
    FilePath --- FileVol
    HuggingFaceCache --- HFVol

来源： deployment/docker_compose/docker-compose.prod.yml:55,190,261,370-382

安装脚本（`install.sh`）

自动化安装脚本负责处理环境设置和资源验证：

资源要求： 10GB 内存和 32GB 磁盘（在 --lite 模式下减少到 4GB/16GB） deployment/docker_compose/install.sh:6-7, 101-104。
Onyx Craft： 通过 --include-craft 启用，设置 ENABLE_CRAFT=true 并使用 IMAGE_TAG=craft-latest deployment/docker_compose/install.sh:29-32, deployment/docker_compose/env.template:13-19。
部署控制： 支持 --shutdown 暂停容器和 --delete-data 完全移除 deployment/docker_compose/install.sh:21-28。
配置管理： 使用 compose_file_args 动态包含覆盖层，例如 docker-compose.onyx-lite.yml deployment/docker_compose/install.sh:113-120。

来源： deployment/docker_compose/install.sh:1-120, deployment/docker_compose/env.template:1-19

2.1 · Docker Compose 部署（Docker Compose Deployment）

中文译文

Docker Compose 部署（中文译文）

Docker Compose 部署

目的与范围

可用的 Compose 文件

服务架构

系统组件交互

核心服务

api_server

后台

web_server

mcp_server

inference_model_server 和 indexing_model_server

数据服务

部署模式

开发模式

生产模式（单租户）

多租户生产环境（云）

多租户开发环境

搜索测试模式

生产环境加固检查清单

部署协调

代码实体到系统的映射

数据流和卷映射

安装脚本（install.sh）

安装脚本（`install.sh`）