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

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

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

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

翻译模型：deepseek-chat

原文字符数：12901

项目：Onyx (onyx)

---

安装与部署

部署架构总览

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

系统拓扑图

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

graph TB
    subgraph "入口点"
        nginx["nginx:1.25.5-alpine<br/>反向代理<br/>端口 80/443"]
    end

    subgraph "应用层"
        api_server["api_server<br/>FastAPI 后端<br/>端口 8080<br/>镜像: onyx-backend"]
        web_server["web_server<br/>Next.js 前端<br/>镜像: onyx-web-server"]
        background["background<br/>Celery 工作节点<br/>镜像: onyx-backend<br/>supervisord_entrypoint.sh"]
    end

    subgraph "机器学习层"
        inference_model_server["inference_model_server<br/>端口 9000<br/>镜像: onyx-model-server"]
        indexing_model_server["indexing_model_server<br/>端口 9000<br/>镜像: onyx-model-server<br/>INDEXING_ONLY=True"]
    end

    subgraph "数据层"
        relational_db["relational_db<br/>postgres:15.2-alpine<br/>端口 5432"]
        index["index<br/>vespaengine/vespa:8.609.39<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<br/>配置文件: s3-filestore"]
    end

    subgraph "可选服务"
        code_interpreter["code-interpreter<br/>端口 8000<br/>CODE_INTERPRETER_BASE_URL"]
        mcp_server["mcp_server<br/>端口 8090<br/>MCP_SERVER_ENABLED"]
    end

    nginx --> api_server
    nginx --> web_server

    api_server --> relational_db
    api_server --> index
    api_server --> opensearch
    api_server --> cache
    api_server --> minio
    api_server --> inference_model_server

    background --> relational_db
    background --> index
    background --> opensearch
    background --> cache
    background --> minio
    background --> inference_model_server
    background --> indexing_model_server

    web_server --> api_server

服务职责：

服务	容器镜像	用途	关键环境变量
`nginx`	`nginx:1.25.5-alpine`	反向代理，SSL 终止	`DOMAIN`, `NGINX_PROXY_*_TIMEOUT`
`api_server`	`onyx-backend`	REST API，WebSocket 流式传输	`AUTH_TYPE`, `POSTGRES_HOST`, `VESPA_HOST`, `OPENSEARCH_HOST`
`web_server`	`onyx-web-server`	Next.js UI	`INTERNAL_URL`, `NEXT_PUBLIC_*`
`background`	`onyx-backend`	通过 supervisord 管理的 Celery 工作节点	`CELERY_WORKER_*_CONCURRENCY`
`inference_model_server`	`onyx-model-server`	查询的嵌入向量	`MIN_THREADS_ML_MODELS`
`indexing_model_server`	`onyx-model-server`	索引的嵌入向量	`INDEXING_ONLY=True`
`relational_db`	`postgres:15.2-alpine`	用户数据，聊天历史	`POSTGRES_USER`, `POSTGRES_PASSWORD`
`index`	`vespaengine/vespa`	向量 + 关键词搜索	`VESPA_HOST`, `VESPA_PORT`
`opensearch`	`opensearchproject/opensearch`	备选搜索后端	`OPENSEARCH_HOST`, `ENABLE_OPENSEARCH_INDEXING_FOR_ONYX`
`cache`	`redis:7.4-alpine`	任务队列，会话，锁	`REDIS_HOST`
`minio`	`minio/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 文件加载配置，并用活动环境变量覆盖它们。

graph LR
    subgraph "配置源"
        template["env.template<br/>参考默认值"]
        prod_template["env.prod.template<br/>生产默认值"]
        dot_env[".env 文件<br/>本地覆盖"]
    end

    subgraph "应用消费"
        api_env["api_server<br/>env_file: .env"]
        bg_env["background<br/>env_file: .env"]
        model_env["model_server<br/>环境变量"]
    end

    template --> dot_env
    prod_template --> dot_env
    dot_env --> api_env
    dot_env --> bg_env

关键配置类别：

认证： 由 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 管理。系统支持标准的单租户模式和多租户私有模式。详情请参阅数据库迁移。

迁移执行流程

sequenceDiagram
    participant API as api_server
    participant DB as relational_db

    Note over API: 容器启动
    API->>API: 检测部署模式

    alt 标准模式
        API->>DB: alembic upgrade head
    else 多租户模式
        API->>DB: alembic -n schema_private upgrade head
    end

    Note over API: 启动 Uvicorn

关键命令：

标准： 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_server`	`urllib.request.urlopen('.../health')`	确保 FastAPI 正在接受请求 `deployment/docker_compose/docker-compose.yml:114-114`
`index`	`curl -sf .../state/v1/health`	验证 Vespa 配置服务器已就绪 `deployment/docker_compose/docker-compose.dev.yml:37`
`relational_db`	`pg_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