10.6 · Kubernetes 与 Helm 部署（Kubernetes and Helm Deployment）

Kubernetes 与 Helm 部署

Kubernetes 与 Helm 部署

相关源文件

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

• .devcontainer/devcontainer.json
• .github/workflows/distributed_test.yml
• .github/workflows/temporal_graph_tests.yml
• cognee/tests/test_temporal_graph.py
• deployment/helm/Dockerfile
• deployment/setup_ubuntu_instance.sh
• distributed/Dockerfile
• distributed/deploy/README.md
• distributed/deploy/daytona.yaml
• distributed/deploy/daytona_sandbox.py
• distributed/deploy/devcontainer.json
• distributed/deploy/fly-deploy.sh
• distributed/deploy/fly.toml
• distributed/deploy/modal-deploy.sh
• distributed/deploy/modal_app.py
• distributed/deploy/railway-template.json
• distributed/deploy/railway.toml
• distributed/deploy/render.yaml
• tools/check-lockfile.py

Cognee 提供了适合在 Kubernetes 中编排的容器化架构。核心引擎通常作为 FastAPI 服务部署，但系统也可以以分布式模式部署，或作为模型上下文协议（MCP）服务器用于 AI 代理交互。本文档记录了在 Kubernetes 上运行 Cognee 的部署模式、配置值和生产环境注意事项。

架构总览

Kubernetes 中典型的 Cognee 部署包含以下组件：

1. Cognee 核心服务：基于 FastAPI 的引擎，处理 add、cognify 和 search 操作。
2. Cognee MCP 服务器：可选服务，为代理工作流提供模型上下文协议访问。
3. 数据库依赖：关系型（PostgreSQL）、向量型（PGVector）和图型（Neo4j/Kuzu）数据的持久化存储 .github/workflows/temporal_graph_tests.yml:105-118。
4. 分布式工作节点：当启用 COGNEE_DISTRIBUTED 时，用于图保存和数据点处理的可选工作节点 distributed/Dockerfile:7。

部署数据流

下图展示了外部请求如何通过 Kubernetes 服务流入 Cognee 逻辑层，特别突出了 API 与底层数据库引擎之间的交互。

Kubernetes 到代码实体映射

来源：cognee/tests/test_temporal_graph.py:3-9、.github/workflows/temporal_graph_tests.yml:156-186、distributed/deploy/daytona_sandbox.py:115

容器配置

Cognee 提供了多个针对不同部署场景优化的 Dockerfile 配置，包括标准的基于 Helm 的部署和分布式执行。

Helm 优化镜像

针对 Helm 的 Dockerfile 设计灵活，允许安装各种存储和 AI 框架的额外组件。

• 基础镜像：python:3.11-slim deployment/helm/Dockerfile:1。
• 依赖管理：使用 poetry，并指定了 postgres、neo4j、kuzu 和 langchain 等额外组件 deployment/helm/Dockerfile:4-16。
• 入口点：运行 entrypoint.sh 来处理初始设置和服务启动 deployment/helm/Dockerfile:54-59。

分布式/生产镜像

对于大规模处理，使用基于 uv 的专用镜像来最小化构建时间并优化运行时性能。

• 基础镜像：ghcr.io/astral-sh/uv:python3.13-bookworm-slim distributed/Dockerfile:1。
• 环境：设置 COGNEE_DISTRIBUTED=true 和 RUN_MODE=modal distributed/Dockerfile:5-7。
• 性能：使用 uv sync --frozen 确保跨工作节点的确定性依赖解析 distributed/Dockerfile:23。

Helm Chart 配置（Values）

通过 Helm 部署时，以下配置模式对生产环境的稳定性至关重要。

数据库提供者选择

Cognee 支持多种数据库组合，必须通过 Helm values.yaml 中的环境变量进行配置。

服务和资源配置

对于生产工作负载，建议使用托管数据库（例如用于 Postgres 的 RDS），而不是 Pod 内基于文件的数据库（如 SQLite 或 LanceDB），因为它们在容器化环境中无法很好地处理并发写入 distributed/deploy/README.md:171。

服务部署序列

来源：deployment/helm/Dockerfile:54-59、distributed/deploy/daytona_sandbox.py:102-131、distributed/deploy/README.md:149-165

生产环境注意事项

1. 数据库迁移

在 Kubernetes 中，工作节点上通常设置 SKIP_MIGRATIONS=true 以防止并发模式修改 distributed/Dockerfile:6。主 API Pod 或专用的 Helm pre-install 钩子应使用提供的配置处理 alembic 迁移 deployment/helm/Dockerfile:51-52。

2. 存储与持久化

对于基于文件的引擎（LanceDB、Kuzu），必须在 DATA_ROOT_DIRECTORY 和 SYSTEM_ROOT_DIRECTORY 定义的路径上挂载持久卷 distributed/deploy/modal_app.py:39-40。在 Fly.io 或 Render 等平台上，这些路径会映射到持久磁盘 distributed/deploy/README.md:68-105。

3. 环境变量安全性

敏感凭证（如 LLM_API_KEY、GRAPH_DATABASE_PASSWORD 和 DB_PASSWORD）应通过 Kubernetes Secrets 管理，并作为环境变量注入 .github/workflows/temporal_graph_tests.yml:86-97、distributed/deploy/README.md:15。

4. 端口转发与访问

要与集群中运行的 Cognee 实例交互：

• API 访问：转发 FastAPI 端口（默认 8000）.devcontainer/devcontainer.json:9。
• Neo4j 浏览器：转发端口 7474 以直接访问图可视化界面 .github/workflows/temporal_graph_tests.yml:167。
• Postgres：转发端口 5432 以检查关系型数据 .github/workflows/temporal_graph_tests.yml:118。

来源：distributed/Dockerfile:1-32、deployment/helm/Dockerfile:1-60、.github/workflows/temporal_graph_tests.yml:1-155、cognee/tests/test_temporal_graph.py:1-13、distributed/deploy/README.md:1-200