使用 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/cogneeCognee 是开源 AI 记忆平台为 Agent 提供跨会话的持久长期记忆与自托管知识图谱引擎。本文基于仓库中的 Cognee Helm Chart 文档系统讲解如何用 Helm 将 Cognee 后端与配套的 PostgreSQL pgvector 数据库一键部署到 Kubernetes 集群涵盖开发环境与生产环境的安装方式、密钥管理、探针配置、伸缩注意事项与完整的 values 参数说明。读完本文你将掌握一套可复制、可验证的 Cognee 容器化部署方案并理解 chart 内部模板、健康检查接口与单副本限制背后的实现原理。一、Chart 概览一个部署单元两个核心组件deployment/helm/目录下的 chartChart 元数据见 Chart.yaml应用版本1.16.0chart 版本0.1.0是一个type: application的独立 chart不依赖任何外部子 chart一次helm install即可同时拉起两个相互配套的组件Cognee 后端FastAPI 服务默认监听8000端口负责认知流水线、知识图谱与检索 APIPostgreSQL pgvector内置数据库默认镜像pgvector/pgvector:pg17同时承担关系数据存储与向量检索双重职责VECTOR_DB_PROVIDERpgvector。两个组件均为Deployment工作负载Cognee 见 cognee_deployment.yamlPostgres 见 postgres_deployment.yaml并配套Service、ConfigMap、Secret、PVC与ServiceAccount资源。模板目录结构如下模板文件作用cognee_deployment.yamlCognee 主 Deployment环境变量、探针、资源限制cognee_service.yaml暴露 Cognee API 的 Service默认ClusterIP:8000configmap.yaml全部非敏感环境变量DB 连接、LLM 配置等secrets.yml开发环境自动生成的 SecretLLM_API_KEY与DB_PASSWORDpostgres_deployment.yamlPostgreSQL 主 Deploymentpg_isready探针、PVC 挂载postgres_pvc.yamlPostgres 数据持久卷声明默认2Gipostgres_service.yamlPostgres 内部 Service默认5432serviceaccount.yaml专用 ServiceAccountNOTES.txt安装完成后输出的使用指引提示仓库根目录的 docker-compose.yml 与 docker-compose-helm.yml 提供了非 Kubernetes 环境下的本地开发体验Helm chart 则是面向集群环境的官方部署路径。二、前置条件在开始安装前请确认环境满足以下要求Kubernetes 1.25chart 使用的 API 与探针特性在该版本及以上的集群中受支持Helm 3.10支持 chart 的模板语法与helm upgrade --install的幂等安装方式kubectl 已配置好目标集群具备创建 Namespace、Deployment、Service、PVC 等资源的权限。另外由于 chart 默认启用startupProbe与readinessProbe通过 HTTP 探测/health集群需要支持 HTTP 探针这是所有标准 Kubernetes 发行版都具备的能力。三、安装 Cognee3.1 开发环境内联凭据快速体验对于本地开发或快速验证可以直接通过--set传入数据库密码与 LLM 配置helm upgrade --install cognee deployment/helm \ --namespace cognee --create-namespace \ --set postgres.auth.passwordchangeme \ --set cognee.llmProvideropenai \ --set cognee.llmModelopenai/gpt-4o-mini这里需要特别注意两点README 已明确提示不设置existingSecret时chart 会基于postgres.auth.password自动创建一个开发用 Secret模板逻辑见 secrets.yml其中DB_PASSWORD取当前值而LLM_API_KEY被硬编码为空字符串LLM 密钥需要手动补齐LLM_API_KEY为空时Cognee 无法调用大模型。安装完成后可以按 NOTES.txt 中的指引用kubectl patch secret补录密钥kubectl patch secret cognee-chart-secret \ -n cognee \ --typemerge \ -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两个键的 Secretkubectl create secret generic cognee-credentials \ --namespace cognee \ --from-literalLLM_API_KEYsk-... \ --from-literalDB_PASSWORDstrongpassword然后安装时通过existingSecret引用它同时将postgres.auth.password置空避免生成多余的开发 Secrethelm upgrade --install cognee deployment/helm \ --namespace cognee --create-namespace \ --set existingSecretcognee-credentials \ --set postgres.auth.passwordCognee Deployment 与 Postgres Deployment 都会从这个 Secret 读取凭据Cognee 容器通过secretKeyRef读取LLM_API_KEY与DB_PASSWORD见 cognee_deployment.yamlPostgres 容器通过secretKeyRef将DB_PASSWORD注入POSTGRES_PASSWORD环境变量见 postgres_deployment.yaml。密钥轮换自动生效chart 在 Deployment 的 Pod 模板注解中注入了checksum/config与checksum/secretcognee_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/instancecognee 3. View logs: kubectl logs -n cognee -l app.kubernetes.io/namecognee-chart -f同时NOTES 模板会根据渲染时的值动态给出警告未设置existingSecret时会提示开发 Secret 中LLM_API_KEY为空需要 patchreplicaCount 1时会提示存在进程内锁与缓存需要先验证分布式协调能力。四、升级与卸载升级到新版本 chart 或新镜像标签helm upgrade cognee deployment/helm --namespace cognee由于前面安装使用的是helm upgrade --install后续升级保持同样的 Release 名称即可无缝覆盖也可以结合--set image.tag...指定新的应用镜像版本。卸载整个 Releasehelm uninstall cognee --namespace cognee需要说明的是Helm 卸载默认不会删除 Postgres 的 PVCPVC 生命周期由独立资源管理因此数据卷会保留如需彻底清理请在确认数据已备份后手动删除 PVCkubectl delete pvc -n cognee -l app.kubernetes.io/instancecognee五、配置参数速查表以下参数均定义在 values.yaml 中并可由 values.schema.json 在渲染前做类型与取值校验例如service.type只允许ClusterIP/NodePort/LoadBalancerpullPolicy只允许Always/Never/IfNotPresentreplicaCount最小为 1。Key默认值说明replicaCount1Cognee 副本数参见下文「伸缩注意事项」image.repositorycognee/cogneeCognee 镜像仓库image.tagmain镜像标签image.pullPolicyIfNotPresent镜像拉取策略service.typeClusterIP服务类型ClusterIP、NodePort或LoadBalancerservice.port8000服务端口cognee.envlocal运行环境注入ENV环境变量cognee.llmProvideropenaiLLM 提供商cognee.llmModelopenai/gpt-4o-miniLLM 模型cognee.vectorDbProviderpgvector向量数据库提供商cognee.enableBackendAccessControlfalse启用多租户访问控制existingSecret已存在的 Secret 名称须含LLM_API_KEY与DB_PASSWORDresources.requests.cpu500mCPU 请求resources.requests.memory512Mi内存请求resources.limits.cpu4000mCPU 上限resources.limits.memory2Gi内存上限serviceAccount.createtrue创建专用 ServiceAccountserviceAccount.name覆盖 ServiceAccount 名称serviceAccount.automountServiceAccountTokenfalse是否将 API Token 挂载进 PodpodSecurityContext{}Pod 级安全上下文securityContext.allowPrivilegeEscalationfalse禁止权限提升securityContext.capabilities.drop[ALL]丢弃全部 Linux capabilitiesstartupProbe.enabledtrue启动探针防止迁移完成前进入流量startupProbe.failureThreshold30判定 Pod 失败前的尝试次数startupProbe.periodSeconds10探测间隔秒数readinessProbe.enabledtrue就绪探针依赖不健康时从 Service 摘除readinessProbe.initialDelaySeconds10首次就绪探测前等待秒数readinessProbe.periodSeconds10就绪探测间隔秒数livenessProbe.enabledfalse存活探针默认关闭原因见下文postgres.image.repositorypgvector/pgvectorPostgres 镜像postgres.image.tagpg17Postgres 镜像标签postgres.port5432Postgres 端口postgres.auth.usernamecogneePostgres 用户名postgres.auth.passwordPostgres 密码仅开发使用生产用existingSecretpostgres.auth.databasecognee_dbPostgres 数据库名postgres.storage2GiPostgres 数据 PVC 大小postgres.resources.requests.cpu250mPostgres CPU 请求postgres.resources.requests.memory256MiPostgres 内存请求postgres.resources.limits.cpu1000mPostgres CPU 上限postgres.resources.limits.memory1GiPostgres 内存上限六、环境变量的注入链路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.yamlSecret 来源优先取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 databasepostgres_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 replicaCount2之类的值。九、访问 APIchart 默认创建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.typeLoadBalancer云环境或--set service.typeNodePort自建集群。十、安全基线chart 内置了多项开箱即用的安全加固均通过 values 显式控制最小权限 ServiceAccount默认创建专用 ServiceAccount且automountServiceAccountTokenfalse避免无谓地把集群 API Token 挂载进业务 Pod容器安全上下文allowPrivilegeEscalation: false禁止提权capabilities.drop: [ALL]丢弃全部 Linux capabilities密钥不落盘生产模式要求通过existingSecret从集群 Secret 读取LLM_API_KEY与DB_PASSWORDchart 自身不渲染明文密码多租户访问控制开关cognee.enableBackendAccessControl控制后端多租户访问控制能力默认关闭需要多租户隔离场景时可通过--set cognee.enableBackendAccessControltrue开启。结语通过 deployment/helm/README.md 对应的这套 Helm chartCognee 可以在一组命令之内完成 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考