agentic_huge_data_base / wiki
页面 Cognee · 10 部署指南·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 10

10 · 部署指南（Deployment Guide）

记忆管道与知识图谱构建 · 聚焦本章的模块关系、源码依据与实现要点。

项目Cognee 章节10 状态全文译文 模块安装与启动、测试、发布与运维、存储与持久化、接口与服务契约
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节Deployment Guide 上一章9.3 下一章10.1
源码线索
  • .github/actions/cognee_setup/action.yml
  • .github/workflows/basic_tests.yml
  • .github/workflows/db_examples_tests.yml
  • .github/workflows/dockerhub-mcp.yml
  • .github/workflows/e2e_tests.yml
  • .github/workflows/examples_tests.yml
  • .github/workflows/graph_db_tests.yml
  • .github/workflows/relational_db_migration_tests.yml
  • .github/workflows/reusable_notebook.yml
  • .github/workflows/search_db_tests.yml
模块标签
  • 安装与启动
  • 测试、发布与运维
  • 存储与持久化
  • 接口与服务契约
  • 界面与交互

章节正文

部署指南

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/10-deployment-guide

部署指南

相关源文件

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

  • .github/actions/cognee_setup/action.yml
  • .github/workflows/basic_tests.yml
  • .github/workflows/db_examples_tests.yml
  • .github/workflows/dockerhub-mcp.yml
  • .github/workflows/e2e_tests.yml
  • .github/workflows/examples_tests.yml
  • .github/workflows/graph_db_tests.yml
  • .github/workflows/relational_db_migration_tests.yml
  • .github/workflows/reusable_notebook.yml
  • .github/workflows/search_db_tests.yml
  • .github/workflows/test_s3_file_storage.yml
  • .github/workflows/vector_db_tests.yml
  • .github/workflows/weighted_edges_tests.yml
  • Dockerfile
  • cognee-mcp/Dockerfile
  • cognee-mcp/README.md
  • cognee-mcp/entrypoint.sh
  • cognee-mcp/pyproject.toml
  • cognee-mcp/src/__init__.py
  • cognee-mcp/src/client.py
  • cognee-mcp/src/cognee_client.py
  • cognee-mcp/src/server.py
  • cognee-mcp/uv.lock
  • cognee/alembic/versions/7c5d4e2f8a91_add_parent_user_id_to_users.py
  • cognee/modules/users/authentication/default/default_transport.py
  • cognee/modules/users/authentication/get_api_auth_backend.py
  • cognee/modules/users/authentication/get_client_auth_backend.py
  • cognee/tests/unit/test_add_parent_user_id_migration.py
  • docker-compose.yml
  • entrypoint.sh

本指南介绍了如何在各种环境中部署 Cognee，涵盖从本地开发到生产环境的容器化部署。文档记录了基础设施搭建、Docker 配置、持续集成/持续部署（CI/CD）管线以及测试框架，这些组件共同实现了跨不同平台的可靠部署。

部署后如需配置数据库，请参见数据库配置与选择。如需将 MCP 服务器与 AI 助手集成，请参见面向 AI 代理的 MCP 服务器。如需了解测试策略和夹具，请参见测试指南。

开发环境搭建

使用 uv 进行本地开发

Cognee 使用 uv 作为包管理器，以实现快速、可靠的依赖管理。开发环境要求 Python 3.10-3.13。

基本安装：

项目依赖在 pyproject.toml 中定义，并带有特定的 Python 版本约束 cognee-mcp/pyproject.toml:6-6。开发依赖包括测试框架和调试工具 cognee-mcp/pyproject.toml:36-41。

# 安装 uv
pip install uv

# 安装核心依赖并同步
uv sync --dev --all-extras

可选的依赖组：

组名用途关键依赖
postgres-binaryPostgreSQL 支持psycopg2-binary、pgvector、asyncpg cognee-mcp/pyproject.toml:43-47
dev开发工具debugpy、pytest、pytest-asyncio cognee-mcp/pyproject.toml:37-41
awsS3 存储支持s3fs、boto3 cognee-mcp/README.md:142-142
neo4jNeo4j 图数据库neo4j 驱动 cognee-mcp/README.md:144-144
chromadbChromaDB 向量存储chromadb 客户端 cognee-mcp/README.md:146-146
scraping网页抓取playwright、beautifulsoup4 cognee-mcp/README.md:147-147

来源：cognee-mcp/pyproject.toml:1-73、cognee-mcp/README.md:61-68

运行测试和示例

开发工作流支持运行单元测试和执行示例，以验证环境是否正确：

# 运行单元测试
uv run pytest cognee/tests/unit/

# 运行简单示例
uv run python ./examples/demos/simple_cognee_example.py

来源：.github/workflows/basic_tests.yml:71-71、.github/workflows/basic_tests.yml:103-103

Docker 部署

多阶段构建架构

Cognee 使用多阶段 Docker 构建来优化镜像大小和构建缓存。构建过程将依赖安装与最终运行时镜像分离。

构建工作流图

下图展示了主 cognee 服务的多阶段构建过程，将 Docker 阶段与对应的代码实体和入口点关联起来。

Cognee · 多阶段构建架构 · 图 1
Cognee · 多阶段构建架构 · 图 1

构建配置：

Dockerfile 实现了多种优化策略：

  • 基于 UV 的依赖解析，使用锁文件 Dockerfile:31-35
  • 依赖与源代码分离的层缓存 Dockerfile:38-47
  • 使用 python:3.12-slim-bookworm 的最小化运行时镜像 Dockerfile:49-57
  • 入口点脚本的 Windows 换行符规范化 Dockerfile:63

来源：Dockerfile:1-73、entrypoint.sh:1-55

构建和运行
# 构建镜像
docker build -t cognee:latest .

# 使用环境文件运行
docker run --env-file .env -p 8000:8000 cognee:latest

入口点脚本 entrypoint.sh:1-55 负责处理数据库设置和服务器执行：

  1. 运行 Alembic 迁移以更新关系模式 entrypoint.sh:20-20。
  2. 如果迁移失败，则回退到 cognee/modules/engine/operations/setup.py entrypoint.sh:28-28。
  3. 通过 Gunicorn 使用 cognee.api.client:app 启动 FastAPI 应用程序 entrypoint.sh:50-53。

来源：Dockerfile:1-73、entrypoint.sh:1-55

Docker Compose 部署

服务架构

Docker Compose 编排了整个 Cognee 技术栈，包括核心引擎、MCP 服务器以及各种数据库提供者。

系统部署拓扑图

此图将部署服务与其具体角色和内部代码引用关联起来。

Cognee · 服务架构 · 图 2
Cognee · 服务架构 · 图 2

来源：docker-compose.yml:1-185、cognee-mcp/src/cognee_client.py:31-68

服务配置文件

Docker Compose 使用配置文件来管理可选组件：

配置文件服务描述
mcpcognee-mcp用于 IDE 集成的模型上下文协议服务器 docker-compose.yml:41-44
uifrontendNext.js Web 界面 docker-compose.yml:84-90
neo4jneo4j带有 GDS 和 APOC 的 Neo4j 图数据库 docker-compose.yml:103-108
chromadbchromadbChroma 向量数据库 docker-compose.yml:118-123
postgrespostgres支持 pgvector 的 PostgreSQL docker-compose.yml:137-142
redisredis用于缓存和会话管理的 Redis docker-compose.yml:153-157

来源：docker-compose.yml:1-185

MCP 服务器部署

传输模式

MCP 服务器支持三种主要的传输机制 cognee-mcp/README.md:40-40：

  1. stdio：标准输入/输出（默认用于本地命令行/IDE 使用）。
  2. SSE：通过 run_sse_with_cors() 实现的服务器发送事件 cognee-mcp/src/server.py:166-185。
  3. HTTP：通过 run_http_with_cors() 实现的可流式 HTTP cognee-mcp/src/server.py:187-205。
连接模式：API 与直接连接

CogneeClient 类抽象了 MCP 服务器与核心引擎的交互方式 cognee-mcp/src/cognee_client.py:31-42：

  • 直接模式：导入 cognee 库并直接调用函数 cognee-mcp/src/cognee_client.py:64-68。
  • API 模式：通过 httpx.AsyncClient 与远程 Cognee FastAPI 服务器通信 cognee-mcp/src/cognee_client.py:58-62。

来源：cognee-mcp/src/server.py:1-205、cognee-mcp/src/cognee_client.py:1-106、cognee-mcp/README.md:38-48

持续集成/持续部署（CI/CD）管线

工作流结构

持续集成/持续部署（CI/CD）管线使用可复用的 GitHub Actions 工作流构建，以确保在不同部署目标上的质量：

  • 集成测试：执行服务器启动测试和遥测验证 e2e_tests.yml:42-95。
  • 去重测试：使用实时 PostgreSQL 服务验证内容去重功能 e2e_tests.yml:128-170。
  • 示例验证：运行多媒体、评估和时间感知示例 examples_tests.yml:16-127。
可复用的 cognee_setup

工作流使用共享的 cognee_setup 操作来标准化环境搭建，包括 uv 安装和依赖同步 e2e_tests.yml:52-56。

来源：.github/workflows/e2e_tests.yml:1-200、.github/workflows/examples_tests.yml:1-182

部署检查清单

  • [ ] 在环境变量或 .env 文件中设置 LLM_API_KEY cognee-mcp/README.md:73-76。
  • [ ] 配置 DB_PROVIDER（默认为 sqlite）docker-compose.yml:62。
  • [ ] 对于 MCP 部署，选择 TRANSPORT_MODE（默认为 stdio）docker-compose.yml:60。
  • [ ] 确保数据库主机可达；对于 Docker 外部的本地数据库，使用 host.docker.internal docker-compose.yml:22-24。
  • [ ] 如果使用 UI，请将 NEXT_PUBLIC_BACKEND_API_URL 设置为指向 Cognee API docker-compose.yml:88。

来源：docker-compose.yml:1-185、cognee-mcp/README.md:1-152