agentic_huge_data_base / wiki
页面 Graphiti · 8.2 Docker 与容器部署·DeepWiki 中文全文译文
DeepWiki 中文译文 / Graphiti / 8.2

8.2 · Docker 与容器部署（Docker and Container Deployment）

时序知识图谱与动态事实记忆 · 聚焦本章的模块关系、源码依据与实现要点。

项目Graphiti 章节8.2 状态全文译文 模块配置治理、安装与启动、测试、发布与运维、存储与持久化
项目要点页2.5 参考项目 项目章节目录Graphiti DeepWiki 原始章节Docker and Container Deployment 上一章8.1 下一章8.3
源码线索
  • Dockerfile
  • docker-compose.yml
  • mcp_server/docker/Dockerfile
  • mcp_server/docker/Dockerfile.standalone
  • mcp_server/docker/README-falkordb-combined.md
  • mcp_server/docker/docker-compose-falkordb.yml
  • mcp_server/docker/docker-compose-neo4j.yml
  • mcp_server/docker/docker-compose.yml
  • server/Makefile
  • server/README.md
模块标签
  • 配置治理
  • 安装与启动
  • 测试、发布与运维
  • 存储与持久化
  • 接口与服务契约

章节正文

Docker 与容器部署

原始 DeepWiki 页面https://deepwiki.com/getzep/graphiti/8.2-docker-and-container-deployment

Docker 与容器化部署

相关源文件

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

  • Dockerfile
  • docker-compose.yml
  • mcp_server/docker/Dockerfile
  • mcp_server/docker/Dockerfile.standalone
  • mcp_server/docker/README-falkordb-combined.md
  • mcp_server/docker/docker-compose-falkordb.yml
  • mcp_server/docker/docker-compose-neo4j.yml
  • mcp_server/docker/docker-compose.yml
  • server/Makefile
  • server/README.md

目的与范围

本文档涵盖了 Graphiti 框架的容器化部署，重点介绍 MCP 服务器和基于 FastAPI 的 REST 服务。它详细说明了针对不同数据库后端（FalkorDB 和 Neo4j）的可用 Docker Compose 配置、容器镜像的实现细节，以及在生产或开发环境中运行 Graphiti 的操作流程。

有关 MCP 服务器功能和工具 API 文档，请参见 8.1 AI 智能体的 MCP 服务器。有关 Docker 部署之外的配置选项，请参见 9.1 环境变量与设置。

容器部署选项

Graphiti 提供了多种 Docker 配置，以支持从单容器"开箱即用"设置到分布式多容器架构的各种部署场景。

部署选项Compose 文件使用场景容器数量
FalkorDB 组合mcp_server/docker/docker-compose.yml默认 MCP 设置，最快启动1（组合）
Neo4j 分离mcp_server/docker/docker-compose-neo4j.yml生产级 MCP 部署2（应用 + 数据库）
FalkorDB 分离mcp_server/docker/docker-compose-falkordb.yml使用外部 FalkorDB 的 MCP2（应用 + 数据库）
REST 服务（Neo4j）docker-compose.yml（根目录）带 Neo4j 的 FastAPI REST 服务2（应用 + 数据库）
REST 服务（FalkorDB）docker-compose.yml（根目录）带 FalkorDB 的 FastAPI REST 服务2（应用 + 数据库）

来源： mcp_server/docker/docker-compose.yml:1-45、mcp_server/docker/docker-compose-neo4j.yml:1-56、mcp_server/docker/docker-compose-falkordb.yml:1-51、docker-compose.yml:1-93

FalkorDB 组合容器（默认）

推荐的 MCP 服务器快速启动方式使用单个镜像 zepai/knowledge-graph-mcp:latest，该镜像同时捆绑了 Graphiti MCP 逻辑和 FalkorDB 引擎。

主要特性：

  • 入口点：自定义启动脚本 /start-services.sh 负责进程编排 mcp_server/docker/Dockerfile:136-137。
  • 数据库：FalkorDB 作为后台守护进程在端口 6379 上运行 mcp_server/docker/Dockerfile:76-82。
  • Web 界面：FalkorDB 浏览器可选地在端口 3000 上可用（由 BROWSER 环境变量控制）mcp_server/docker/Dockerfile:93-104。
  • 应用：MCP 服务器使用 uv run main.py 在前台运行 mcp_server/docker/Dockerfile:109。

来源： mcp_server/docker/Dockerfile:1-138、mcp_server/docker/README-falkordb-combined.md:1-13

Neo4j 分离容器

对于需要 Neo4j 完整功能集的生产环境，使用 docker-compose-neo4j.yml 配置。

默认凭据和连接性：

  • Neo4j 镜像：neo4j:5.26.0 mcp_server/docker/docker-compose-neo4j.yml:3。
  • 认证：neo4j/${NEO4J_PASSWORD:-demodemo} mcp_server/docker/docker-compose-neo4j.yml:8。
  • 应用连接性：使用 standalone 镜像变体，该变体排除了内部数据库引擎 mcp_server/docker/docker-compose-neo4j.yml:26-29。

来源： mcp_server/docker/docker-compose-neo4j.yml:1-56、mcp_server/docker/Dockerfile.standalone:1-82

容器架构图

进程编排（组合镜像）

此图将 start-services.sh 逻辑映射到 zepai/knowledge-graph-mcp 镜像中运行的系统组件。

Graphiti · 进程编排（组合镜像） · 图 1
Graphiti · 进程编排（组合镜像） · 图 1

来源： mcp_server/docker/Dockerfile:70-112、mcp_server/docker/README-falkordb-combined.md:162-167

服务拓扑（REST 服务 + Neo4j）

此图将根目录 docker-compose.yml 配置与 graph_service 代码实体连接起来。

Graphiti · 服务拓扑（REST 服务 + Neo4j） · 图 2
Graphiti · 服务拓扑（REST 服务 + Neo4j） · 图 2

来源： docker-compose.yml:2-30、Dockerfile:78、server/README.md:43-72

环境配置

关键变量与优先级

配置按以下优先级顺序解析：

  1. 命令行参数（例如，传递给 main.py 的参数）
  2. 环境变量（在 .env 或 Compose environment 块中定义）mcp_server/docker/docker-compose.yml:15-25
  3. 配置文件（config.yaml）mcp_server/docker/docker-compose.yml:24
变量默认值用途
OPENAI_API_KEY（必需）大语言模型（LLM）和嵌入向量的 API 密钥 docker-compose.yml:23
SEMAPHORE_LIMIT10剧集处理的并发限制 mcp_server/docker/docker-compose.yml:23
GRAPHITI_GROUP_IDmain图数据的命名空间 mcp_server/docker/docker-compose.yml:22
FALKORDB_URIredis://localhost:6379数据库连接的 URI mcp_server/docker/docker-compose.yml:20
NEO4J_PASSWORDpasswordNeo4j 的默认密码 docker-compose.yml:26

来源： mcp_server/docker/docker-compose.yml:15-28、docker-compose.yml:22-28、mcp_server/docker/README-falkordb-combined.md:78-96

镜像构建过程

项目使用多个 Dockerfile 来针对不同的服务类型。两者都利用 uv 进行高性能依赖管理。

MCP 服务器 Dockerfile（mcp_server/docker/Dockerfile）
  • 基础镜像：falkordb/falkordb:latest（基于 Debian）mcp_server/docker/Dockerfile:5。
  • 依赖管理：安装 uv，复制 pyproject.toml 和 uv.lock，并运行 uv sync mcp_server/docker/Dockerfile:19-53。
  • 优化：使用 UV_COMPILE_BYTECODE=1 和 UV_LINK_MODE=copy 实现高效构建 mcp_server/docker/Dockerfile:26-27。
  • 额外功能：自动安装 graphiti-core[falkordb] mcp_server/docker/Dockerfile:45。
REST 服务 Dockerfile（Dockerfile）
  • 基础镜像：python:3.12-slim Dockerfile:2。
  • 安全性：创建非 root 用户 app，并在执行前切换到该用户 Dockerfile:36-71。
  • 动态版本控制：接受 GRAPHITI_VERSION 作为构建参数，以固定 graphiti-core 的特定版本 Dockerfile:49-61。
  • 运行时：执行 uvicorn graph_service.main:app Dockerfile:78。

来源： mcp_server/docker/Dockerfile:1-138、Dockerfile:1-79

操作流程

持久化存储

Graphiti 容器使用 Docker 卷来确保数据在容器重启后持久化。

  • FalkorDB：/var/lib/falkordb/data mcp_server/docker/docker-compose.yml:27
  • Neo4j：neo4j_data 卷映射到 /data docker-compose.yml:45-46
  • 日志：mcp_logs 卷映射到 /var/log/graphiti mcp_server/docker/docker-compose.yml:28
健康检查

容器包含内置的健康检查，以确保服务可用性：

  • FalkorDB：使用 redis-cli -p 6379 ping mcp_server/docker/docker-compose.yml:34。
  • REST 服务：使用 urllib.request 轮询 http://localhost:8000/healthcheck 端点 docker-compose.yml:14。
  • MCP 独立模式：使用 curl -f http://localhost:8000/health mcp_server/docker/Dockerfile.standalone:78。
故障排查日志

组合镜像中所有服务的日志都会被聚合。浏览器或数据库的单独日志可以在容器内的 /var/log/graphiti/ 目录下找到 mcp_server/docker/Dockerfile:67。

来源： mcp_server/docker/docker-compose.yml:33-38、docker-compose.yml:8-18、mcp_server/docker/README-falkordb-combined.md:104-112