agentic_huge_data_base / wiki
页面 Onyx · 2 设置与部署·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 2

2 · 设置与部署（Setup and Deployment）

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

项目Onyx 章节2 状态全文译文 模块安装与启动、存储与持久化、测试、发布与运维、接口与服务契约
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Setup and Deployment 上一章1.2 下一章2.1
源码线索
  • 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
  • ct.yaml
  • 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
模块标签
  • 安装与启动
  • 存储与持久化
  • 测试、发布与运维
  • 接口与服务契约
  • 配置治理

章节正文

设置与部署

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/2-setup-and-deployment

安装与部署

相关源文件

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

  • 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
  • ct.yaml
  • 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
  • deployment/helm/charts/onyx/Chart.lock
  • deployment/helm/charts/onyx/Chart.yaml
  • deployment/helm/charts/onyx/templates/api-deployment.yaml
  • deployment/helm/charts/onyx/templates/celery-beat.yaml
  • deployment/helm/charts/onyx/templates/celery-worker-docfetching.yaml
  • deployment/helm/charts/onyx/templates/celery-worker-docprocessing.yaml
  • deployment/helm/charts/onyx/templates/celery-worker-heavy.yaml
  • deployment/helm/charts/onyx/templates/celery-worker-light.yaml
  • deployment/helm/charts/onyx/templates/celery-worker-monitoring.yaml
  • deployment/helm/charts/onyx/templates/celery-worker-primary.yaml
  • deployment/helm/charts/onyx/templates/configmap.yaml
  • deployment/helm/charts/onyx/templates/indexing-model-deployment.yaml
  • deployment/helm/charts/onyx/templates/inference-model-deployment.yaml
  • deployment/helm/charts/onyx/templates/webserver-deployment.yaml
  • deployment/helm/charts/onyx/values.yaml

本文档概述了在不同环境中部署 Onyx 的方法。它涵盖两种主要部署方式（Docker Compose 和 Kubernetes）、安装过程以及可用的不同部署配置。有关具体方面的详细配置，请参阅环境配置了解所有可用设置，参阅Docker Compose 部署获取分步 Docker 说明，参阅Kubernetes 部署了解编排部署，以及参阅数据库迁移了解模式管理。

部署架构总览

Onyx 以多容器应用的形式部署，核心服务通过 Docker Compose（适用于简单部署）或 Kubernetes（适用于生产规模）进行编排。

系统拓扑图

此图将高层系统组件映射到部署配置中定义的各自容器镜像和服务名称。

Onyx · 系统拓扑图 · 图 1
Onyx · 系统拓扑图 · 图 1

服务职责：

服务容器镜像用途关键环境变量
nginxnginx:1.25.5-alpine反向代理，SSL 终止DOMAIN, NGINX_PROXY_*_TIMEOUT
api_serveronyx-backendREST API，WebSocket 流式传输AUTH_TYPE, POSTGRES_HOST, VESPA_HOST, OPENSEARCH_HOST
web_serveronyx-web-serverNext.js UIINTERNAL_URL, NEXT_PUBLIC_*
backgroundonyx-backend通过 supervisord 管理的 Celery 工作节点CELERY_WORKER_*_CONCURRENCY
inference_model_serveronyx-model-server查询的嵌入向量MIN_THREADS_ML_MODELS
indexing_model_serveronyx-model-server索引的嵌入向量INDEXING_ONLY=True
relational_dbpostgres:15.2-alpine用户数据，聊天历史POSTGRES_USER, POSTGRES_PASSWORD
indexvespaengine/vespa向量 + 关键词搜索VESPA_HOST, VESPA_PORT
opensearchopensearchproject/opensearch备选搜索后端OPENSEARCH_HOST, ENABLE_OPENSEARCH_INDEXING_FOR_ONYX
cacheredis:7.4-alpine任务队列，会话，锁REDIS_HOST
miniominio/minio兼容 S3 的文件存储S3_ENDPOINT_URL, S3_AWS_ACCESS_KEY_ID

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

部署方法

Docker Compose

Docker Compose 是开发、测试以及中小型生产部署的推荐方法。详情请参阅Docker Compose 部署。

Compose 文件矩阵：

文件使用场景主要区别
docker-compose.yml基础配置标准服务定义，AUTH_TYPE=basic deployment/docker_compose/docker-compose.yml:78-78
docker-compose.dev.yml开发暴露所有端口（8080, 5432, 19071, 6379, 9000）deployment/docker_compose/docker-compose.dev.yml:12-69
docker-compose.prod.yml生产包含生产 nginx 和资源限制 deployment/docker_compose/docker-compose.prod.yml:1-148
docker-compose.multitenant-dev.yml多租户MULTI_TENANT=true，使用 schema_private 迁移 deployment/docker_compose/docker-compose.multitenant-dev.yml:11-25
docker-compose.prod-cloud.yml云平台使用 Dockerfile.cloud，针对云原生存储优化 deployment/docker_compose/docker-compose.prod-cloud.yml:8-32
docker-compose.search-testing.yml评估AUTH_TYPE=basic，使用 .env_eval 进行基准测试 deployment/docker_compose/docker-compose.search-testing.yml:22-24
Kubernetes

Kubernetes 部署使用 Helm Chart 进行编排，为企业环境提供高可用性和可扩展性。详情请参阅Kubernetes 部署。

Helm Chart 组件：

  • 依赖项： 包含 cloudnative-pg、vespa、opensearch、redis 和 minio 的子 Chart deployment/helm/charts/onyx/Chart.yaml:20-50。
  • 可配置性： 通过 vectorDB.enabled 和 opensearch.enabled 切换搜索后端 deployment/helm/charts/onyx/values.yaml:36-82。
  • 资源管理： 为模型服务器和数据库设置显式的 CPU/内存请求和限制 deployment/helm/charts/onyx/values.yaml:160-166。

环境配置

配置通过环境变量管理，这些变量控制服务行为、认证和功能开关。完整参考请参阅环境配置。

配置优先级与加载

系统从 .env 文件加载配置，并用活动环境变量覆盖它们。

Onyx · 配置优先级与加载 · 图 2
Onyx · 配置优先级与加载 · 图 2

关键配置类别：

  • 认证： 由 AUTH_TYPE（basic、google_oauth、oidc、saml、cloud）控制 deployment/docker_compose/env.template:23。
  • 搜索后端： 使用 OPENSEARCH_FOR_ONYX_ENABLED 在 Vespa 和 OpenSearch 之间切换 deployment/docker_compose/env.template:72。
  • 企业功能： 通过 ENABLE_PAID_ENTERPRISE_EDITION_FEATURES 启用 deployment/docker_compose/env.template:47。

来源：deployment/docker_compose/env.template:1-120, deployment/docker_compose/env.prod.template:1-69

数据库迁移

数据库模式演进通过 Alembic 管理。系统支持标准的单租户模式和多租户私有模式。详情请参阅数据库迁移。

迁移执行流程
Onyx · 迁移执行流程 · 图 3
Onyx · 迁移执行流程 · 图 3

关键命令：

  • 标准： alembic upgrade head deployment/docker_compose/docker-compose.yml:48。
  • 多租户： alembic -n schema_private upgrade head deployment/docker_compose/docker-compose.multitenant-dev.yml:11。

来源：deployment/docker_compose/docker-compose.yml:47-50, deployment/docker_compose/docker-compose.multitenant-dev.yml:9-13

健康检查与初始化

服务使用 Docker 健康检查来确保依赖项在启动相关逻辑之前已就绪。

服务检查实现重要性
api_serverurllib.request.urlopen('.../health')确保 FastAPI 正在接受请求 deployment/docker_compose/docker-compose.yml:114-114
indexcurl -sf .../state/v1/health验证 Vespa 配置服务器已就绪 deployment/docker_compose/docker-compose.dev.yml:37
relational_dbpg_isready确保 Postgres 已准备好进行迁移（Alpine 镜像中的标准做法）deployment/docker_compose/docker-compose.yml:189-191

来源：deployment/docker_compose/docker-compose.yml:108-119, deployment/docker_compose/docker-compose.dev.yml:34-41