agentic_huge_data_base / wiki
页面 Onyx · 2.1 Docker Compose 部署·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 2.1

2.1 · Docker Compose 部署（Docker Compose Deployment）

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

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

Docker Compose 部署

相关源文件

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

  • 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
  • cli/internal/starprompt/starprompt.go
  • cli/internal/tui/app.go
  • cli/internal/tui/commands.go
  • cli/internal/tui/experiments.go
  • cli/internal/tui/help.go
  • cli/internal/tui/input.go
  • cli/internal/tui/viewport.go
  • cli/internal/tui/viewport_test.go
  • deployment/docker_compose/docker-compose.dev.yml
  • deployment/docker_compose/docker-compose.multitenant-dev.yml
  • deployment/docker_compose/docker-compose.onyx-lite.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
  • deployment/docker_compose/install.ps1
  • deployment/docker_compose/install.sh
  • deployment/helm/charts/onyx/values-lite.yaml

目的与范围

本文档介绍 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

服务架构

系统组件交互
Onyx · 系统组件交互 · 图 1
Onyx · 系统组件交互 · 图 1

来源： 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_dbpostgres:15.2-alpine主要元数据存储 deployment/docker_compose/docker-compose.prod.yml:189
indexvespaengine/vespa:8.609.39向量和关键词搜索 deployment/docker_compose/docker-compose.prod.yml:249
opensearchopensearchproject/opensearch:2.11.0辅助搜索引擎 deployment/docker_compose/docker-compose.yml:320
cacheredis:7.4-alpine任务队列和会话缓存 deployment/docker_compose/docker-compose.prod.yml:335
miniominio/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 文件包含一份生产部署检查清单：

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

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

部署协调

代码实体到系统的映射
Onyx · 代码实体到系统的映射 · 图 2
Onyx · 代码实体到系统的映射 · 图 2

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

数据流和卷映射
Onyx · 数据流和卷映射 · 图 3
Onyx · 数据流和卷映射 · 图 3

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