Cognee Docker Compose 全栈 E2E 测试指南【免费下载链接】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/tests/e2e/docker_compose/README.md为核心系统讲解 Cognee 开源 AI 记忆平台为 Agent 提供跨会话持久长期记忆的自托管知识图谱引擎基于docker-compose.yml部署形态的完整端到端测试方案。读者将掌握如何理解该测试套件的四大覆盖维度API golden flow、MCP 服务、日志卫生、Postgres 持久化、如何在本机复现 CI 相同的启动与运行流程以及每个环境变量的含义与底层源码实现。全文以文档为主线结合仓库源码、CI 工作流与 compose 配置进行纵深印证可直接作为在本地验证或二次开发该部署形态的实战参考。文档定位一次“真实的”端到端测试cognee/tests/e2e/docker_compose/README.md描述的测试套件其定位是docker-compose.yml部署形态的真实端到端测试full-stack e2e。它在 .github/workflows/docker_compose.yml 中与 workflow 层的 remember/recall 冒烟测试并行运行重点覆盖冒烟测试没有覆盖的三个部分MCP 服务cognee-mcp端口 8001Postgres 支撑的持久化named volumepostgres_data服务日志卫生traceback 扫描关键设计原则是“mock LLM by default”默认情况下依赖 LLM 的测试腿cognify search是关闭的套件从不调用真实模型因此作为 PR 阻塞门禁时具有确定性与低成本。只有当显式设置COGNEE_E2E_RUN_LLM1并提供真实 LLM Key 时才会执行 cognify/search 腿。套件覆盖的四类断言文档给出了覆盖矩阵从源码cognee/tests/e2e/docker_compose/test_full_stack_e2e.py可以得到一一对应的实现测试断言内容test_golden_flow_api针对:8000上 API 的health → login → add → datasets → data当提供 LLM Key 时额外执行 cognify searchtest_mcp_health_and_tool_callcognee-mcp的/health:8001并且通过 SSE 完成一次真实的 MCP 工具调用cognify_statustest_service_logs_are_traceback_free没有任何服务输出未处理的 Python traceback在 Postgres recreate 之前运行因为 recreate 会合法地记录连接错误test_postgres_persistence_across_recreate通过 API 添加的数据在 Postgres 容器强制重建后仍然存在——证明postgres_data卷是必需配置1. Golden Flow核心公共契约的端到端验证test_golden_flow_api对应golden_flow.py中的golden_flow()函数它走完一个真实客户端依赖的核心公共契约health - login - add - 列出 datasets - 列出 data - (可选) cognify - search具体到源码实现每一步都有明确的 HTTP 行为liveness 检查check_livenessGET /必须返回 200 且消息体为Hello, World, I am alive!GET /health必须返回 200登录loginPOST /api/v1/auth/login以 form 数据提交用户名/密码默认账户为default_userexample.com/default_password返回access_token添加文档add_textPOST /api/v1/add带 Bearer Token 头以 multipart 表单上传一个内存中的 txt 文档run_in_background: false同步摄取接受 200 或 201确认数据集wait_for_dataset轮询GET /api/v1/datasets直到新数据集出现默认超时 120 秒确认数据项list_dataset_dataGET /api/v1/datasets/{id}/data必须非空LLM 腿cognify_and_search仅COGNEE_E2E_RUN_LLM1时POST /api/v1/cognify构建知识图谱随后POST /api/v1/search以GRAPH_COMPLETION类型执行一次查询要求返回非空结果。golden_flow()返回GoldenFlowResult含token、dataset_name、dataset_id、data_count、searched供持久化测试在 Postgres 重建后重新校验同一数据集仍然存在。2. MCP 服务一次真实的 SSE 工具调用test_mcp_health_and_tool_call是这套 e2e 独有的亮点cognee-mcp服务以TRANSPORT_MODEsse运行见 docker-compose.yml 中 cognee-mcp 服务的环境变量因此它遵循标准 MCP SSE 协议在/sse端点提供服务。mcp_client.py实现了一个最小化的 MCP-over-SSE 客户端使用官方mcp库的sse_clientClientSession建立会话并initialize()list_tools()确认工具面——源码中只断言remember、recall、forget三个记忆工具必然暴露服务器在tools/list前有工具搜索变换COGNEE_MCP_TOOL_MODE的门控隐藏工具仍可按名直接调用这是工作区 UI 依赖的契约call_tool(cognify_status, {})完成一次真实的工具调用往返。选择cognify_status是因为它无需 LLM、无副作用是理想的往返探针。断言结果文本匹配{pipeline 状态映射 dict 字符串或❌ Dataset ...API 模式下未摄取时的显式提示行两者都证明了一次 LLM-free 的工具调用真实往返成功。3. 日志卫生无未处理 tracebacktest_service_logs_are_traceback_free通过compose_utils.service_logs()抓取cognee、cognee-mcp、postgres三个服务的日志docker compose logs --no-color合并 stdout/stderr扫描是否存在Traceback (most recent call last)。若有则断言失败并附带每个违规服务日志的最后 40 行作为诊断。测试顺序是刻意设计的该测试必须运行在持久化测试之前。因为 force-recreate Postgres 会合法地丢弃 API 的实时数据库连接由此产生的已恢复的暂时性错误可能以 traceback 形式被记录放在前面可以避免误报。4. Postgres 持久化数据跨越容器重建test_postgres_persistence_across_recreate是这套测试的核心价值所在。它首先通过golden_flow()创建数据集然后调用compose_utils.recreate_service(postgres)执行docker compose up -d --force-recreate --no-deps postgrescompose_utils.py的注释解释了这个操作的本质与restart复用同一容器、保留可写层不同up --force-recreate会丢弃容器并构建全新容器。命名卷named volumes会保留而只写入容器层的数据会丢失——这正是持久化检查有意义的原因如果没有命名卷数据会消失。重建后测试会重新等待 API 健康 → 在 90 秒内反复尝试重新登录并find_dataset因为应用在数据库弹跳后需要重建连接池首次请求可能暂时失败→ 断言数据集仍然存在。源码中明确写道如果失败报错信息会提示“the postgres_data volume is likely missing from docker-compose.yml”。而 docker-compose.yml 中 Postgres 服务确实声明了volumes: - postgres_data:/var/lib/postgresql/data并把postgres_data声明在顶层volumes:段——注释同样写明“docker-compose e2e 依赖这个卷没有它重建的 postgres 容器会以空库启动。”本机运行与 CI 完全一致的流程文档给出了本机运行命令并说明 compose 驱动的测试需要COGNEE_E2E_MANAGE_COMPOSE1# 1. 按 CI 使用的相同 profiles 拉起整个栈。 cp .env.template .env # 仅当需要 LLM 腿时才设置 LLM_API_KEY docker compose --profile postgres --profile mcp up -d --build # 2. 运行测试套件compose 驱动测试需要 COGNEE_E2E_MANAGE_COMPOSE1。 COGNEE_E2E_MANAGE_COMPOSE1 \ uv run --no-project --with pytest --with requests --with mcp \ python -m pytest cognee/tests/e2e/docker_compose -v环境变量配置全部通过环境变量驱动文档中的配置表其默认值可直接在 config.py 中溯源变量默认值用途COGNEE_API_URLhttp://localhost:8000主 API 的 base URLCOGNEE_MCP_URLhttp://localhost:8001MCP 服务的 base URLCOGNEE_E2E_RUN_LLM0是否执行 cognify/search 腿需要真实 LLM KeyCOGNEE_E2E_MANAGE_COMPOSE0是否允许套件驱动docker compose持久化与日志测试COGNEE_E2E_COMPOSE_PROFILESpostgres,mcp传给docker compose的 profiles从源码看除了文档表中的五个变量config.py 还支持以下补充变量_env_bool接受1/true/yes/on作为布尔真值COGNEE_DEFAULT_USER默认default_userexample.com、COGNEE_DEFAULT_PASSWORD默认default_password首次启动时种子的默认账户COGNEE_E2E_STARTUP_TIMEOUT默认300秒等待服务变为健康的最长时间COGNEE_E2E_POLL_INTERVAL默认3秒健康轮询间隔COGNEE_E2E_COMPOSE_FILE默认docker-compose.ymlcompose 文件路径。健康等待机制取代古老的sleep 30conftest.py提供三个 session 级 fixture确保测试不会与栈的启动过程赛跑api_ready阻塞直到主 API 在:8000的/health返回健康调用wait_for_http_okmcp_ready阻塞直到 MCP 服务在:8001健康requires_compose当COGNEE_E2E_MANAGE_COMPOSE未开启时pytest.skip掉 compose 驱动测试持久化与日志测试方便开发者在已有运行栈上仅跑 API 与 MCP 测试。底层wait_for_http_ok()compose_utils.py在超时时间内每poll_interval秒轮询一次 URL期待默认 HTTP 200超时则抛出ServiceNotHealthy并附带最后一次错误信息。测试套件与 cognee 包解耦conftest.py顶部有一个重要的设计决策该套件刻意不属于可导入的cognee包——它只通过 HTTP 与运行中的栈通信因此必须在未安装 cognee 的最小 runner 上完成 collect。它把自身目录插入sys.path让兄弟模块以顶层导入方式from config import ...工作从而不引入cognee/__init__.py及其沉重的依赖树。这解释了为什么运行命令使用uv run --no-project避免同步整个项目与pytest --confcutdir避免加载祖先 conftest与 CI 保持一致。CI 集成workflow 如何驱动这套测试.github/workflows/docker_compose.yml 展示了套件在 CI 中的完整运行脉络值得本地复现时参考构建镜像docker compose -f docker-compose.yml buildENV: dev生成容器 .envdocker-compose.yml将./.envbind-mount 进容器而 CI 没有入库的.env所以用printenv | grep -E ^(LLM_|EMBEDDING_)...从 secrets 生成空 secret 会被过滤掉避免LLM_ARGS空值把 dict 字段搞挂并追加DB_PROVIDERpostgres、DB_HOSTpostgres等让关系型存储真正指向 postgres 服务——这也印证了持久化测试确实是Postgres-backed的先启动 Postgres应用服务没有对 postgres 的depends_on所以先把数据库拉起来避免应用服务启动时 crash-loop循环pg_isready等待就绪启动全栈并分别等待 cognee:8000/health与 cognee-mcp:8001/health健康运行 e2e 套件COGNEE_E2E_MANAGE_COMPOSE1、COGNEE_E2E_COMPOSE_PROFILESpostgres,mcpuv run --no-project --with pytest --with pytest-timeout --with requests --with mcp运行pytest ... --confcutdircognee/tests/e2e/docker_compose -v --timeout900workflow 层 remember/recall 冒烟先POST /api/v1/remember摄取一条事实再用CHUNKS类型的/api/v1/recall逐字校验原文返回无 LLM、确定性检查最后用GRAPH_COMPLETION类型的 recall 验证图谱补全能提到该实体此处使用真实 LLM失败时输出过滤掉 key 形状行api_key|authorization|bearer的服务日志always()收尾docker compose down -v清理。套件运行早于真实 LLM 往返冒烟测试是有意为之这样 traceback 扫描只覆盖确定性的 LLM-free 路径启动、摄取、MCP、持久化不会因模型提供商的噪声而 flake。被测栈docker-compose.yml 的关键服务为了让套件断言有意义需要理解 docker-compose.yml 中被测的部署形态默认栈 两个 profilecognee:8000主 API 服务healthcheck用curl -f http://localhost:8000/health每 30s 探测挂载cognee_system与cognee_data两个命名卷数据库默认sqlite开启 postgres profile 时通过环境变量切到DB_PROVIDERpostgres、DB_HOSTpostgrescognee-mcpprofilemcp容器内:8000映射到宿主:8001MCP 服务器command: --no-migrationTRANSPORT_MODEsse与主服务共享cognee_system/cognee_data卷——“API 与 MCP 服务器共享内存正是同时运行两者的意义”源码注释原话两者都以 uid 1000 运行其 healthcheck 因镜像无 curl 改用urllib探测postgresprofilepostgrespgvector/pgvector:pg17用户名/密码/库名均为cognee/cognee/cognee_db数据落在postgres_data命名卷healthcheck 用pg_isreadyfrontendprofileui:3000、neo4jprofileneo4j:7474/:7687、redisprofileredis:6379等可选服务不在 e2e 覆盖范围内说明该套件的覆盖边界就是“API MCP Postgres 持久化 日志”。本地快速启动的 .env 参考本机复现时从 .env.template 拷贝一份.env即可满足大部分需求其 TIER 1 区只需设置LLM_API_KEY仅在需要 LLM 腿时其余均有可用默认值默认文件型数据库 SQLite/LanceDB/KuzuDB 无需额外设置。要切换 Postgres按 TIER 2 区的注释设置DB_PROVIDERpostgres、DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD、DB_NAME即可——注意在容器场景下DB_HOST应使用服务名postgres而非127.0.0.1。覆盖边界与使用建议从源码与 workflow 可以总结出这套 e2e 的能力边界覆盖API 公共契约含摄取、MCP 真实工具调用SSE、无 LLM 的确定性路径、Postgres 命名卷持久化的必要性验证、服务日志卫生不覆盖真实 LLM 路径默认关闭属于可选腿、workflow 层的 remember/recall 冒烟由 .github/workflows/docker_compose.yml 中的 shell 步骤承担二者互补。实用建议日常开发如果栈已在本地运行可不设COGNEE_E2E_MANAGE_COMPOSE套件会自动跳过需要驱动 compose 的两个测试requires_composefixture 会 skip只跑 API 与 MCP 断言本地完整验证按文档命令以postgres,mcp两个 profile 起栈并设置COGNEE_E2E_MANAGE_COMPOSE1即获得与 CI 相同覆盖想跑 LLM 腿在.env中设置LLM_API_KEY并设COGNEE_E2E_RUN_LLM1套件会追加执行 cognify 与 GRAPH_COMPLETION 搜索注意 cognify 超时为 900 秒、search 为 300 秒请确保模型可用且配额充足排查持久化问题若持久化测试失败首先检查 docker-compose.yml 的 postgres 服务是否仍挂载postgres_data:/var/lib/postgresql/data——这是该测试存在的全部意义。【免费下载链接】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），仅供参考