2.2 · Kubernetes 部署（Kubernetes Deployment）

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

项目Onyx 章节2.2 状态全文译文模块存储与持久化、系统架构、配置治理、检索、召回与索引

项目要点页2.5 参考项目项目章节目录Onyx DeepWiki 原始章节Kubernetes Deployment 上一章2.1 下一章2.3

源码线索

ct.yaml
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

模块标签

存储与持久化
系统架构
配置治理
检索、召回与索引
安装与启动

中文译文

Kubernetes 部署（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/onyx-dot-app/onyx/2.2-kubernetes-deployment

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

翻译模型：deepseek-chat

原文字符数：15406

项目：Onyx (onyx)

---

Kubernetes 部署

部署架构总览

Onyx 的 Kubernetes 部署主要通过位于 deployment/helm/charts/onyx 的综合性 Helm Chart 进行管理 deployment/helm/charts/onyx/Chart.yaml:1-50。该架构采用微服务模式，将无状态应用逻辑与有状态数据存储分离。

核心组件映射

Docker Compose 服务	Kubernetes 实体	Helm 模板/子 Chart	镜像
`api_server`	Deployment	`api-deployment.yaml`	`onyxdotapp/onyx-backend`
`web_server`	Deployment	`webserver-deployment.yaml`	`onyxdotapp/onyx-web-server`
`relational_db`	集群（CNPG）	`postgresql` 子 Chart	`cloudnative-pg` 操作器
`index`	StatefulSet	`vespa` 子 Chart	`vespaengine/vespa`
`cache`	Deployment	`redis` 子 Chart	`redis`
`inference_model`	Deployment	`inference-model-deployment.yaml`	`onyxdotapp/onyx-model-server`
`indexing_model`	Deployment	`indexing-model-deployment.yaml`	`onyxdotapp/onyx-model-server`

系统数据流

下图将高层系统名称与 Helm 模板中定义的特定 Kubernetes 服务和部署实体关联起来。

graph TB
    subgraph "外部访问"
        Ingress["Ingress 控制器<br/>(ingress-nginx)"]
    end

    subgraph "应用层"
        WebSvc["Service: onyx-webserver-service"]
        WebDeploy["Deployment: onyx-webserver"]
        APISvc["Service: onyx-api-service"]
        APIDeploy["Deployment: onyx-api-server"]
    end

    subgraph "AI 推理层"
        InfSvc["Service: inference-model-service"]
        InfDeploy["Deployment: onyx-inference-model"]
        IdxSvc["Service: indexing-model-service"]
        IdxDeploy["Deployment: onyx-indexing-model"]
    end

    subgraph "数据与协调层"
        Postgres["Cluster: cloudnative-pg<br/>(onyx-postgresql)"]
        Vespa["StatefulSet: vespa<br/>(da-vespa-0)"]
        Redis["Service: onyx-redis-master"]
        Minio["Service: onyx-minio"]
        OpenSearch["Service: onyx-opensearch-master"]
    end

    Ingress --> WebSvc
    Ingress --> APISvc

    WebSvc --> WebDeploy
    APISvc --> APIDeploy

    APIDeploy --> InfSvc
    APIDeploy --> Postgres
    APIDeploy --> Vespa
    APIDeploy --> Redis
    APIDeploy --> OpenSearch

    subgraph "后台工作器"
        WorkerFetch["Deployment: onyx-celery-worker-docfetching"]
        WorkerProc["Deployment: onyx-celery-worker-docprocessing"]
        WorkerLight["Deployment: onyx-celery-worker-light"]
        WorkerHeavy["Deployment: onyx-celery-worker-heavy"]
    end

    WorkerFetch --> IdxSvc
    WorkerProc --> Vespa
    WorkerLight --> Redis
    WorkerHeavy --> Postgres

    来源：[deployment/helm/charts/onyx/values.yaml:1-239]()，[deployment/helm/charts/onyx/templates/api-deployment.yaml:1-111]()，[deployment/helm/charts/onyx/templates/indexing-model-deployment.yaml:1-95]()

来源：deployment/helm/charts/onyx/Chart.yaml:1-50，deployment/helm/charts/onyx/values.yaml:1-239，deployment/helm/charts/onyx/templates/api-deployment.yaml:1-111

---

Helm Chart 配置

Onyx 的 Helm Chart 使用 values.yaml 文件来驱动所有子 Chart 和本地模板的配置。

全局设置

Chart 定义了镜像版本和主机配置的全局变量，以确保整个技术栈的一致性 deployment/helm/charts/onyx/values.yaml:5-11。

组件开关

主开关 vectorDB.enabled（默认值：true）控制索引基础设施的部署 deployment/helm/charts/onyx/values.yaml:36-37。当禁用时：

后端 Pod 上会设置 DISABLE_VECTOR_DB 为 true。
索引模型服务器和所有 Celery 工作器部署（primary、light、heavy、docfetching 等）会被跳过 deployment/helm/charts/onyx/values.yaml:28-35。

API 服务器初始化

API 服务器部署在启动过程中会自动处理数据库迁移，在启动 uvicorn 进程之前执行 alembic upgrade head deployment/helm/charts/onyx/templates/api-deployment.yaml:73-75。

来源：deployment/helm/charts/onyx/values.yaml:1-239，deployment/helm/charts/onyx/templates/api-deployment.yaml:1-111

---

后台工作器专业化

Kubernetes 部署将后台工作拆分为专门的工作器池，以实现独立的扩缩容和资源分配。

工作器池定义

每种工作器类型都在各自的模板文件中定义，并监听特定的 Celery 队列。

工作器部署	队列/角色	配置要点
`light`	`vespa_metadata_sync`，`connector_deletion`，`doc_permissions_upsert`，`opensearch_migration`	处理元数据同步和清理任务 `deployment/helm/charts/onyx/templates/celery-worker-light.yaml:70-72`
`heavy`	`connector_pruning`，`connector_doc_permissions_sync`，`csv_generation`，`sandbox`	处理资源密集型的修剪和权限同步 `deployment/helm/charts/onyx/templates/celery-worker-heavy.yaml:64-72`
`primary`	`celery`，`periodic_tasks`	通用任务处理和 Celery Beat 任务消费 `deployment/helm/charts/onyx/templates/celery-worker-primary.yaml:64-72`
`monitoring`	`monitoring`	专门用于系统健康监控任务的池 `deployment/helm/charts/onyx/templates/celery-worker-monitoring.yaml:64-72`
`beat`	不适用	触发周期性任务的调度器 `deployment/helm/charts/onyx/templates/celery-beat.yaml:62-67`

健康探针

工作器使用专门的 Python 探针脚本 onyx/background/celery/celery_k8s_probe.py 进行就绪探针和存活探针检查，以确保 Celery 消费者实际可用 deployment/helm/charts/onyx/templates/celery-worker-light.yaml:100-112。

graph LR
    subgraph "Kubelet"
        Liveness["存活探针"]
        Readiness["就绪探针"]
    end

    subgraph "工作器 Pod"
        ProbeScript["onyx/background/celery/celery_k8s_probe.py"]
        WorkerProcess["Celery 工作器进程"]
        HeartbeatFile["/tmp/onyx_k8s_*_liveness.txt"]
    end

    Liveness --> ProbeScript
    Readiness --> ProbeScript
    ProbeScript -->|检查| HeartbeatFile
    WorkerProcess -->|更新| HeartbeatFile

    来源：[deployment/helm/charts/onyx/templates/celery-worker-light.yaml:93-112]()

来源：deployment/helm/charts/onyx/templates/celery-worker-light.yaml:1-118，deployment/helm/charts/onyx/templates/celery-worker-heavy.yaml:1-118，deployment/helm/charts/onyx/templates/celery-worker-primary.yaml:1-118，deployment/helm/charts/onyx/templates/celery-worker-monitoring.yaml:1-118

---

AI 模型服务器

Onyx 区分了推理（实时聊天/搜索）和索引（批量文档处理）模型服务器。

推理模型服务器

用途： 为用户查询和聊天交互提供嵌入向量服务。
服务： 通过 inference-model-service 在端口 9000 上暴露 deployment/helm/charts/onyx/values.yaml:141-147。
资源： 默认请求 2 个 CPU 和 3Gi 内存 deployment/helm/charts/onyx/values.yaml:162-164。

索引模型服务器

用途： 批量处理文档以构建向量索引。
配置： 设置 INDEXING_ONLY="True" 以优化批量吞吐量 deployment/helm/charts/onyx/templates/indexing-model-deployment.yaml:68-69。
优化： 启动命令中包含 --limit-concurrency 标志（默认值：10），以防止在大量索引期间发生内存溢出（OOM）deployment/helm/charts/onyx/templates/indexing-model-deployment.yaml:59。

来源：deployment/helm/charts/onyx/values.yaml:140-221，deployment/helm/charts/onyx/templates/indexing-model-deployment.yaml:1-95

---

数据层与持久化

PostgreSQL（CloudNativePG）

Onyx 使用 CloudNativePG 操作器来管理 PostgreSQL。

名称覆盖： 必须设置为 cloudnative-pg 以便操作器发现 deployment/helm/charts/onyx/values.yaml:15-18。
存储： 默认值为 10Gi，并启用 enableSuperuserAccess: true deployment/helm/charts/onyx/values.yaml:19-24。

Vespa

存储： 部署时使用 30Gi 的 PersistentVolumeClaim 用于索引 deployment/helm/charts/onyx/values.yaml:43-51。
安全： 以 root 身份运行并具有特权上下文，以允许 Vespa 的内部内存管理 deployment/helm/charts/onyx/values.yaml:63-65。

OpenSearch

初始化： 对于 2.12 及以上版本，需要设置 OPENSEARCH_INITIAL_ADMIN_PASSWORD deployment/helm/charts/onyx/values.yaml:99-103。
Java 选项： 堆大小通过 opensearchJavaOpts 自动配置（默认值：4g）deployment/helm/charts/onyx/values.yaml:122-125。

来源：deployment/helm/charts/onyx/values.yaml:13-126，deployment/helm/charts/onyx/Chart.yaml:20-50

---

基础设施即代码（Terraform）

对于 AWS 部署，Onyx 提供了 Terraform 模块来配置底层的 EKS 集群和托管服务。

EKS 集群配置

eks 模块负责创建 Kubernetes 控制平面和节点组，包括用于 S3 和 RDS 访问的 IRSA（服务账户的 IAM 角色）deployment/terraform/modules/aws/onyx/main.tf:69-94。

托管数据存储

生产环境通常使用托管的 AWS 服务，而不是集群内部署：

RDS PostgreSQL： 通过 postgres 模块配置，包含自动备份和 CloudWatch 告警 deployment/terraform/modules/aws/onyx/main.tf:46-60。
Elasticache Redis： 配置了 auth_token 以实现传输加密 deployment/terraform/modules/aws/onyx/main.tf:33-44。
OpenSearch 服务： 支持多可用区部署，包含备用节点和专用主节点 deployment/terraform/modules/aws/onyx/main.tf:112-145。

graph TB
    subgraph "AWS 云"
        EKS["EKS 集群<br/>(onyx-eks)"]
        RDS["RDS Postgres<br/>(onyx-postgres)"]
        S3["S3 存储桶<br/>(onyx-file-store)"]
        OS["OpenSearch 服务<br/>(onyx-opensearch)"]
        WAF["WAF v2<br/>(Web ACL)"]
    end

    subgraph "EKS Pods"
        API["api-server Pods"]
        Workers["Celery 工作器"]
    end

    API -->|IAM 认证| RDS
    API -->|S3 API| S3
    Workers --> OS
    WAF -->|保护| EKS

    来源：[deployment/terraform/modules/aws/onyx/main.tf:1-145]()

来源：deployment/terraform/modules/aws/onyx/main.tf:1-145，deployment/terraform/modules/aws/onyx/variables.tf:1-256，deployment/terraform/modules/aws/postgres/main.tf:1-60