企业官网建设流程全解析

使用 Helm 在 Kubernetes 上部署 Cognee：内置 PostgreSQL + pgvector 的完整指南

【免费下载链接】cogneeCognee is the open-source AI memory platform for agents. Give your AI agents persistent long-term memory across sessions with a self-hosted knowledge graph engine.项目地址: https://gitcode.com/GitHub_Trending/co/cognee

Cognee 是开源 AI 记忆平台，为 Agent 提供跨会话的持久长期记忆与自托管知识图谱引擎。本文基于仓库中的 Cognee Helm Chart 文档，系统讲解如何用 Helm 将 Cognee 后端与配套的 PostgreSQL + pgvector 数据库一键部署到 Kubernetes 集群，涵盖开发环境与生产环境的安装方式、密钥管理、探针配置、伸缩注意事项与完整的 values 参数说明。读完本文，你将掌握一套可复制、可验证的 Cognee 容器化部署方案，并理解 chart 内部模板、健康检查接口与单副本限制背后的实现原理。

一、Chart 概览：一个部署单元，两个核心组件

deployment/helm/目录下的 chart（Chart 元数据见 Chart.yaml，应用版本1.16.0，chart 版本0.1.0）是一个type: application的独立 chart，不依赖任何外部子 chart，一次helm install即可同时拉起两个相互配套的组件：

1. Cognee 后端：FastAPI 服务，默认监听8000端口，负责认知流水线、知识图谱与检索 API；
2. PostgreSQL + pgvector：内置数据库，默认镜像pgvector/pgvector:pg17，同时承担关系数据存储与向量检索双重职责（VECTOR_DB_PROVIDER=pgvector）。

两个组件均为Deployment工作负载（Cognee 见 cognee_deployment.yaml，Postgres 见 postgres_deployment.yaml），并配套Service、ConfigMap、Secret、PVC与ServiceAccount资源。

模板目录结构如下：

提示：仓库根目录的 docker-compose.yml 与 docker-compose-helm.yml 提供了非 Kubernetes 环境下的本地开发体验，Helm chart 则是面向集群环境的官方部署路径。

二、前置条件

在开始安装前，请确认环境满足以下要求：

• Kubernetes 1.25+：chart 使用的 API 与探针特性在该版本及以上的集群中受支持；
• Helm 3.10+：支持 chart 的模板语法与helm upgrade --install的幂等安装方式；
• kubectl 已配置好目标集群：具备创建 Namespace、Deployment、Service、PVC 等资源的权限。

另外，由于 chart 默认启用startupProbe与readinessProbe（通过 HTTP 探测/health），集群需要支持 HTTP 探针，这是所有标准 Kubernetes 发行版都具备的能力。

三、安装 Cognee

3.1 开发环境：内联凭据（快速体验）

对于本地开发或快速验证，可以直接通过--set传入数据库密码与 LLM 配置：

helm upgrade --install cognee deployment/helm \ --namespace cognee --create-namespace \ --set postgres.auth.password="changeme" \ --set cognee.llmProvider="openai" \ --set cognee.llmModel="openai/gpt-4o-mini"

这里需要特别注意两点（README 已明确提示）：

1. 不设置existingSecret时，chart 会基于postgres.auth.password自动创建一个开发用 Secret（模板逻辑见 secrets.yml），其中DB_PASSWORD取当前值，而LLM_API_KEY被硬编码为空字符串；
2. LLM 密钥需要手动补齐：LLM_API_KEY为空时，Cognee 无法调用大模型。安装完成后可以按 NOTES.txt 中的指引用kubectl patch secret补录密钥：

kubectl patch secret cognee-chart-secret \ -n cognee \ --type=merge \ -p '{"data":{"LLM_API_KEY":"'$(echo -n "YOUR_KEY" | base64)'"}}'

开发 Secret 的命名遵循{{ release 名称 }}-{{ chart 名称 }}-secret规则（例如上面的cognee-chart-secret），具体由 _helpers.tpl 中的cognee.fullname模板函数决定。

3.2 生产环境（推荐）：外部 Secret 管理

生产环境强烈建议在 Helm 之外管理凭据，无论使用kubectl、External Secrets Operator 还是 Vault，核心思想是：密钥不落盘在 chart 渲染结果中，而是由集群内已有的 Secret 对象提供。

首先创建包含LLM_API_KEY与DB_PASSWORD两个键的 Secret：

kubectl create secret generic cognee-credentials \ --namespace cognee \ --from-literal=LLM_API_KEY="sk-..." \ --from-literal=DB_PASSWORD="strongpassword"

然后安装时通过existingSecret引用它，同时将postgres.auth.password置空（避免生成多余的开发 Secret）：

helm upgrade --install cognee deployment/helm \ --namespace cognee --create-namespace \ --set existingSecret="cognee-credentials" \ --set postgres.auth.password=""

Cognee Deployment 与 Postgres Deployment 都会从这个 Secret 读取凭据：

• Cognee 容器通过secretKeyRef读取LLM_API_KEY与DB_PASSWORD（见 cognee_deployment.yaml）；
• Postgres 容器通过secretKeyRef将DB_PASSWORD注入POSTGRES_PASSWORD环境变量（见 postgres_deployment.yaml）。

密钥轮换自动生效：chart 在 Deployment 的 Pod 模板注解中注入了checksum/config与checksum/secret（cognee_deployment.yaml），内容基于 ConfigMap 与 Secret 渲染结果的 SHA256 哈希。一旦 Secret 内容变更，注解哈希随之变化，Deployment 会自动触发滚动重启，无需手动干预。

3.3 安装输出与使用指引

安装完成后，Helm 会打印 NOTES.txt 渲染出的指引，包括：

Cognee has been deployed. 1. Access the API: kubectl port-forward svc/cognee-cognee-chart -n cognee 8000:8000 API available at http://localhost:8000 2. Check pod status: kubectl get pods -n cognee -l app.kubernetes.io/instance=cognee 3. View logs: kubectl logs -n cognee -l app.kubernetes.io/name=cognee-chart -f

同时，NOTES 模板会根据渲染时的值动态给出警告：未设置existingSecret时会提示开发 Secret 中LLM_API_KEY为空需要 patch；replicaCount > 1时会提示存在进程内锁与缓存，需要先验证分布式协调能力。

四、升级与卸载

升级到新版本 chart 或新镜像标签：

helm upgrade cognee deployment/helm --namespace cognee

由于前面安装使用的是helm upgrade --install，后续升级保持同样的 Release 名称即可无缝覆盖；也可以结合--set image.tag=...指定新的应用镜像版本。

卸载整个 Release：

helm uninstall cognee --namespace cognee

需要说明的是，Helm 卸载默认不会删除 Postgres 的 PVC（PVC 生命周期由独立资源管理），因此数据卷会保留；如需彻底清理，请在确认数据已备份后手动删除 PVC：

kubectl delete pvc -n cognee -l app.kubernetes.io/instance=cognee

五、配置参数速查表

以下参数均定义在 values.yaml 中，并可由 values.schema.json 在渲染前做类型与取值校验（例如service.type只允许ClusterIP/NodePort/LoadBalancer，pullPolicy只允许Always/Never/IfNotPresent，replicaCount最小为 1）。

六、环境变量的注入链路

Cognee 容器本身的运行参数全部来自环境变量，chart 通过两种方式注入：

ConfigMap（非敏感配置）：见 configmap.yaml，渲染后包含：

ENV: "local" PYTHONPATH: "." DB_PROVIDER: "postgres" DB_HOST: "<release>-cognee-chart-postgres" DB_PORT: "5432" DB_NAME: "cognee_db" DB_USERNAME: "cognee" VECTOR_DB_PROVIDER: "pgvector" LLM_PROVIDER: "openai" LLM_MODEL: "openai/gpt-4o-mini" ENABLE_BACKEND_ACCESS_CONTROL: "false"

其中DB_HOST由cognee.postgres.fullname模板函数生成（postgres_service.yaml 创建的 Service 名称），保证应用与数据库在同一 Release 内通过集群 DNS 相互发现。

Secret（敏感配置）：DB_PASSWORD与LLM_API_KEY通过env[].valueFrom.secretKeyRef注入（cognee_deployment.yaml），Secret 来源优先取existingSecret，否则回退到 chart 生成的*-secret。

由此可以看到 chart 的设计取向：把「哪些是敏感信息、哪些是可公开配置」在资源层面强制分离，生产环境只需替换 Secret 的来源即可，无需改动其他配置。

七、探针策略：为什么默认关闭 Liveness 探针

chart 默认启用了startupProbe与readinessProbe，两者都 HTTP 探测/health，但默认关闭livenessProbe——这是 README 中特别强调的一个设计决策。

原因在于仓库中/health端点的实现语义：查看 get_health_router.py 可以看到，GET /health会调用health_checker.get_health_status()，返回状态取决于外部依赖（数据库、向量库、图谱库、文件系统）的整体健康情况，依赖异常时返回 HTTP 503 与"not ready"。

• 将这种依赖型检查接到readiness 探针是合理的：依赖不健康时，Pod 从 Service 的 Endpoints 中摘除，流量不再进入，等待依赖恢复后自动重新接入；
• 若同样接到liveness 探针，问题就出现了：数据库短暂不可用（例如重启、网络抖动）时，liveness 探测失败会让 kubelet 直接重启容器，导致CrashLoopBackOff，反而阻断了依赖自然恢复的过程。

因此 chart 的建议是：只有当仓库暴露一个只反映进程存活性的独立端点（例如/live，回答「进程是否活着」，与外部系统无关）时，才适合开启 liveness 探针。当前仓库并没有这类进程级端点，所以默认关闭是正确选择。

Postgres 侧的探针则完全不同：三个探针全部使用exec执行pg_isready -U <user> -d <database>（postgres_deployment.yaml），直接验证数据库自身的就绪状态。

八、伸缩注意事项：单副本假设

replicaCount是可配置的，但 README 明确警告：当前仓库存在进程内（process-local）状态，包括：

• 进程内 LRU 缓存；
• asyncio 锁（asyncio.Lock类）；
• 信号量（semaphores）；
• 会话锁模块 session_lock.py 中明确注明：Scope: single-worker FastAPI. For multi-worker deployments, layer a ...（即该实现仅适用于单 worker FastAPI，多 worker 部署需要在其上层叠加分布式协调方案）。

这意味着将副本数扩展到 1 以上之前，必须先验证应用的分布式协调需求——例如会话锁、缓存一致性、任务互斥是否能在多副本间正确工作。NOTES 模板也会在replicaCount > 1时打印同样的提示。生产环境如需高可用，建议在验证通过后再调整--set replicaCount=2之类的值。

九、访问 API

chart 默认创建ClusterIP类型的 Service，集群内可通过 Service DNS 访问；本地调试最直接的方式是端口转发：

kubectl port-forward svc/cognee-cognee-chart -n cognee 8000:8000

之后 API 即可在http://localhost:8000访问，例如：

curl http://localhost:8000/health

若需要集群外直接访问，可改用--set service.type=LoadBalancer（云环境）或--set service.type=NodePort（自建集群）。

十、安全基线

chart 内置了多项开箱即用的安全加固，均通过 values 显式控制：

• 最小权限 ServiceAccount：默认创建专用 ServiceAccount，且automountServiceAccountToken=false，避免无谓地把集群 API Token 挂载进业务 Pod；
• 容器安全上下文：allowPrivilegeEscalation: false禁止提权，capabilities.drop: [ALL]丢弃全部 Linux capabilities；
• 密钥不落盘：生产模式要求通过existingSecret从集群 Secret 读取LLM_API_KEY与DB_PASSWORD，chart 自身不渲染明文密码；
• 多租户访问控制开关：cognee.enableBackendAccessControl控制后端多租户访问控制能力，默认关闭，需要多租户隔离场景时可通过--set cognee.enableBackendAccessControl=true开启。

结语

通过 deployment/helm/README.md 对应的这套 Helm chart，Cognee 可以在一组命令之内完成 Kubernetes 部署：开发环境用内联凭据秒级拉起，生产环境通过existingSecret接入外部密钥体系，探针、资源、安全上下文全部参数化可调。理解checksum注解驱动的自动滚动重启、/health依赖型检查与 liveness 的取舍、以及单副本假设下的伸缩边界，是把这个 chart 用好、用稳的关键。在此基础上，可以进一步阅读仓库中的 values.yaml、values.schema.json 与模板目录 templates，按需定制属于你自己的部署形态。

【免费下载链接】cogneeCognee is the open-source AI memory platform for agents. Give your AI agents persistent long-term memory across sessions with a self-hosted knowledge graph engine.项目地址: https://gitcode.com/GitHub_Trending/co/cognee