agentic_huge_data_base / wiki
页面 Cognee · 10.1 Docker 部署·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 10.1

10.1 · Docker 部署（Docker Deployment）

记忆管道与知识图谱构建 · 本章是 Cognee DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Cognee 章节10.1 状态全文译文 模块系统架构、测试、发布与运维、存储与持久化、界面与交互
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节Docker Deployment 上一章10 下一章10.2
源码线索
  • .github/actions/image_builder/action.yaml
  • .github/workflows/community_greetings.yml
  • .github/workflows/dockerhub-mcp.yml
  • .github/workflows/dockerhub.yml
  • .github/workflows/release_discord_action.yml
  • Dockerfile
  • LICENSE
  • bin/dockerize
  • cognee-mcp/Dockerfile
  • cognee-mcp/README.md
模块标签
  • 系统架构
  • 测试、发布与运维
  • 存储与持久化
  • 界面与交互
  • 安装与启动

中文译文

Docker 部署（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/10.1-docker-deployment
翻译时间：2026-05-27T08:45:17.117Z
翻译模型：deepseek-chat
原文字符数：10528
项目：Cognee (cognee)

---

Docker 部署

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

  • .github/actions/image_builder/action.yaml
  • .github/workflows/community_greetings.yml
  • .github/workflows/dockerhub-mcp.yml
  • .github/workflows/dockerhub.yml
  • .github/workflows/release_discord_action.yml
  • Dockerfile
  • LICENSE
  • bin/dockerize
  • 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

目的与范围

本文档记录了基于 Docker 的 Cognee 部署方案，包括多服务 Docker Compose 配置、基于配置文件的（Profile）服务激活机制，以及使用 uv 包管理器的多阶段构建流程。Cognee 设计为高度可移植，既支持本地容器化开发，也支持使用外部数据库的生产级部署。

---

Docker Compose 架构

Cognee 使用模块化的 docker-compose.yml 文件，将服务按逻辑组织到不同的配置文件中。这允许用户只启动他们需要的组件（例如，仅启动 API，或启动 API 配合 Neo4j 图数据库）。

系统组件图

下图展示了各个 Docker 服务之间的关系，以及它们如何通过共享的 cognee-network 网络进行交互。

graph TD
    subgraph "核心服务"
        cognee["cognee<br/>(FastAPI 服务器)<br/>端口 8000"]
        redisinsight["redisinsight<br/>(Redis 用户界面)<br/>端口 5540"]
    end

    subgraph "配置文件: mcp"
        cognee_mcp["cognee-mcp<br/>(MCP 服务器)<br/>端口 8000"]
    end

    subgraph "配置文件: ui"
        frontend["frontend<br/>(Next.js 用户界面)<br/>端口 3000"]
    end

    subgraph "数据库配置文件"
        postgres["postgres<br/>(pgvector/pg17)<br/>端口 5432"]
        neo4j["neo4j<br/>(Neo4j 5.26)<br/>端口 7687"]
        chromadb["chromadb<br/>(Chroma 0.6.3)<br/>端口 3002"]
        redis["redis<br/>(Redis 7-alpine)<br/>端口 6379"]
    end

    subgraph "基础设施"
        network["cognee-network"]
        env_file[".env 配置"]
        vol_pg["postgres_data"]
        vol_ch["chromadb_data"]
        vol_rd["redis_data"]
    end

    cognee --> network
    cognee_mcp --> network
    frontend --> network
    postgres --> network
    neo4j --> network
    chromadb --> network
    redis --> network

    env_file -.-> cognee
    env_file -.-> cognee_mcp

    postgres --> vol_pg
    chromadb --> vol_ch
    redis --> vol_rd

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

---

Docker 镜像构建过程

使用 uv 的多阶段构建

Cognee 采用多阶段构建策略，在保持高性能构建环境的同时，最小化最终镜像大小。它利用 ghcr.io/astral-sh/uv 来处理依赖解析和虚拟环境创建。

阶段 1：构建器（uv） 此阶段安装系统依赖（例如用于 PostgreSQL 支持的 libpq-dev），并使用 uv.lock 同步 Python 环境。

# 首先构建依赖以实现层缓存
COPY README.md pyproject.toml uv.lock entrypoint.sh ./
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --extra debug --extra api --extra postgres --extra neo4j \
    --frozen --no-install-project --no-dev --no-editable

来源： Dockerfile:1-35

阶段 2：运行时 最终镜像基于 python:3.12-slim-bookworm。它从构建器阶段复制预构建的环境，并设置 PATH 以包含虚拟环境。

COPY --from=uv /app /app
ENV PATH="/app/.venv/bin:$PATH"
ENV PYTHONPATH=/app
ENTRYPOINT ["/app/entrypoint.sh"]

来源： Dockerfile:49-72

MCP 服务器镜像构建

MCP 服务器遵循一个复杂的多阶段模式，包括一个 Node.js 阶段，用于在 Python 环境设置之前构建工作区用户界面包（Next.js/Vite）。

阶段 1：Node 构建 构建位于 cognee-mcp/apps-src 中的用户界面包，生成 visualize-graph.html。 来源： cognee-mcp/Dockerfile:1-10

阶段 2：Python 构建器 使用 uv 从 cognee-mcp/pyproject.toml 和 cognee-mcp/uv.lock 安装依赖。 来源： cognee-mcp/Dockerfile:13-56

阶段 3：入口点逻辑 MCP 的 entrypoint.sh 包含逻辑，可以在运行时动态安装额外的 cognee 扩展包（如果提供了 EXTRAS 环境变量）。 来源： cognee-mcp/entrypoint.sh:7-40

---

服务配置文件与配置

配置文件激活

Cognee 中的服务通过 Docker Compose 配置文件进行门控。要运行特定的服务栈，请使用 --profile 标志：

配置文件命令包含的服务
默认docker compose upcognee, redisinsight
mcpdocker compose --profile mcp upcognee-mcp
uidocker compose --profile ui upfrontend
postgresdocker compose --profile postgres uppostgres (pgvector)
neo4jdocker compose --profile neo4j upneo4j (含 APOC/GDS)
chromadbdocker compose --profile chromadb upchromadb
redisdocker compose --profile redis upredis

来源： docker-compose.yml:43-157

环境配置

cognee 和 cognee-mcp 服务依赖环境变量来配置数据库连接和大语言模型（LLM）提供商设置。

变量描述文件引用
DB_PROVIDER数据库类型（例如 sqlite, postgres）docker-compose.yml:62
TRANSPORT_MODEMCP 传输模式（例如 sse, http, stdio）docker-compose.yml:60, cognee-mcp/entrypoint.sh:45
CORS_ALLOWED_ORIGINSAPI 访问允许的来源docker-compose.yml:21
EXTRASMCP 服务器的运行时 cognee 扩展包cognee-mcp/entrypoint.sh:7
API_URLMCP 服务器在 API 模式下连接 Cognee 的 URLcognee-mcp/entrypoint.sh:63

---

数据流与初始化

入口点执行流程

当 cognee 容器启动时，entrypoint.sh 脚本管理数据库迁移和服务器启动。

sequenceDiagram
    participant OS as Docker 容器
    participant EP as entrypoint.sh
    participant AL as Alembic
    participant SU as setup.py
    participant GN as Gunicorn/Uvicorn

    OS->>EP: 执行 ENTRYPOINT
    EP->>AL: cd cognee && alembic upgrade head
    alt 迁移失败
        AL-->>EP: 错误码
        EP->>SU: python cognee/modules/engine/operations/setup.py
        SU-->>EP: 表已初始化
    else 迁移成功
        AL-->>EP: 成功
    end
    EP->>EP: sleep 2 (等待数据库)
    alt ENVIRONMENT == dev/local AND DEBUG == true
        EP->>GN: debugpy --wait-for-client ... cognee.api.client:app
    else 生产环境
        EP->>GN: gunicorn -w 1 ... cognee.api.client:app
    end

来源： entrypoint.sh:15-53

MCP 服务器连接模式

cognee-mcp 服务器使用 CogneeClient 来确定其操作模式。它可以运行"直接模式"（使用本地 cognee 库）或"API 模式"（作为远程服务器的客户端）。

graph LR
    subgraph "Docker 网络"
        MCP["cognee-mcp 容器"]
        API["cognee 容器"]
        HOST["宿主机"]
    end

    MCP -- "API_URL: host.docker.internal" --> API
    MCP -- "直接访问" --> LIB["cognee 库"]
    API -- "内部桥接" --> DB["Postgres/Neo4j"]

来源： cognee-mcp/src/cognee_client.py:31-68, cognee-mcp/entrypoint.sh:63-89

---

卷挂载与持久化

主机文件入库

要将主机上的文件导入到容器化的 Cognee 实例中，用户必须将主机目录挂载到容器中。

volumes:
  - ./cognee:/app/cognee
  - .env:/app/.env
  # 取消注释以允许从主机导入本地文件：
  # - /path/to/your/data:/data

来源： docker-compose.yml:10-14

MCP 服务器实现中包含一个针对 Docker 环境的检查，当使用本地文件路径而未进行卷挂载时，会提供有用的错误消息。 来源： cognee-mcp/src/server.py:155-158

数据库持久化

使用命名卷来确保数据库引擎的数据在容器重建后仍然存在：

  • postgres_data 映射到 /var/lib/postgresql/data docker-compose.yml:183
  • chromadb_data 映射到 /chroma/chroma/ docker-compose.yml:131
  • redis_data 映射到 /data docker-compose.yml:163

---

部署汇总表

特性实现细节来源
基础镜像python:3.12-slim-bookwormDockerfile:49
包管理器uvDockerfile:2, cognee-mcp/Dockerfile:13
服务器引擎gunicorn 配合 UvicornWorkerentrypoint.sh:48
健康检查curl -f http://localhost:8000/healthdocker-compose.yml:29
网络cognee-network (桥接)docker-compose.yml:178
默认端口8000docker-compose.yml:26

来源： Dockerfile:1-73, docker-compose.yml:1-185, entrypoint.sh:1-55, cognee-mcp/entrypoint.sh:1-102