10.1 · Docker 部署（Docker Deployment）

Docker 部署

Docker 部署

相关源文件

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

• .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 网络进行交互。

来源： 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.yml:43-157

环境配置

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

数据流与初始化

入口点执行流程

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

来源： entrypoint.sh:15-53

MCP 服务器连接模式

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

来源： 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

部署汇总表

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