graphiti容器化部署：Docker与Kubernetes实践-优快云博客

graphiti容器化部署：Docker与Kubernetes实践

【免费下载链接】graphiti 用于构建和查询时序感知知识图谱的框架，专为在动态环境中运行的 AI 代理量身定制。项目地址: https://gitcode.com/GitHub_Trending/grap/graphiti

你是否还在为知识图谱框架的部署流程复杂而烦恼？是否担心生产环境中的扩展性和稳定性问题？本文将带你一步到位掌握graphiti的容器化部署方案，从本地开发到生产环境，让时序感知知识图谱的构建和查询变得简单高效。读完本文，你将能够：使用Docker快速搭建开发环境，通过Docker Compose管理多服务应用，以及基于Kubernetes实现生产级部署。

为什么选择容器化部署graphiti

graphiti作为用于构建和查询时序感知知识图谱的框架，专为动态环境中的AI代理设计。其容器化部署具有以下优势：

环境一致性：确保开发、测试和生产环境的一致性，减少"在我机器上能运行"的问题
快速部署：几分钟内即可完成整个系统的部署，包括依赖的数据库服务
弹性扩展：根据负载情况轻松扩展服务实例数量
资源隔离：各组件独立运行，避免相互干扰

项目中提供了完整的容器化配置文件，包括Dockerfile、docker-compose.yml和mcp_server/docker-compose.yml，为容器化部署提供了坚实基础。

Docker快速启动：本地开发环境搭建

准备工作

在开始之前，请确保你的系统已经安装了Docker和Docker Compose。如果尚未安装，可以参考Docker官方文档进行安装。

首先，克隆项目代码库：

git clone https://gitcode.com/GitHub_Trending/grap/graphiti
cd graphiti

构建Docker镜像

graphiti提供了优化的Dockerfile，采用多阶段构建策略，减小最终镜像体积。核心构建步骤包括：

构建阶段：使用Python 3.12-slim基础镜像，安装依赖并构建wheel包
运行阶段：仅包含运行时必要的依赖和文件，使用非root用户运行

# 构建阶段
FROM python:3.12-slim as builder
WORKDIR /app
# 安装系统依赖和uv包管理器
RUN apt-get update && apt-get install -y --no-install-recommends gcc curl ca-certificates && rm -rf /var/lib/apt/lists/*
ADD https://astral.sh/uv/install.sh /uv-installer.sh
RUN sh /uv-installer.sh && rm /uv-installer.sh
ENV PATH="/root/.local/bin:$PATH"
# 复制项目文件并构建
COPY ./pyproject.toml ./README.md ./
COPY ./graphiti_core ./graphiti_core
RUN --mount=type=cache,target=/root/.cache/uv uv build
RUN --mount=type=cache,target=/root/.cache/uv pip install dist/*.whl

# 运行阶段
FROM python:3.12-slim
# 安装运行时依赖
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates && rm -rf /var/lib/apt/lists/*
# 复制构建产物并安装
COPY --from=builder /app/dist/*.whl /tmp/
RUN --mount=type=cache,target=/root/.cache/uv uv pip install --system /tmp/*.whl
# 创建非root用户并设置权限
RUN groupadd -r app && useradd -r -d /app -g app app
WORKDIR /app
COPY ./server/pyproject.toml ./server/README.md ./server/uv.lock ./
COPY ./server/graph_service ./graph_service
RUN --mount=type=cache,target=/root/.cache/uv uv sync --frozen --no-dev
RUN chown -R app:app /app
USER app
# 暴露端口并设置启动命令
ENV PORT=8000
EXPOSE $PORT
CMD ["uv", "run", "uvicorn", "graph_service.main:app", "--host", "0.0.0.0", "--port", "8000"]

使用以下命令构建镜像：

docker build -t graphiti:latest .

单容器运行

如果只需要运行graphiti服务（假设已有外部数据库），可以使用以下命令：

docker run -d -p 8000:8000 \
  -e OPENAI_API_KEY="your_api_key" \
  -e NEO4J_URI="bolt://external-neo4j:7687" \
  -e NEO4J_USER="neo4j" \
  -e NEO4J_PASSWORD="your_password" \
  --name graphiti-server \
  graphiti:latest

Docker Compose：多服务协同部署

对于本地开发和测试，使用Docker Compose可以轻松管理graphiti及其依赖服务。项目提供的docker-compose.yml文件定义了两个服务：graphiti应用本身和Neo4j数据库。

docker-compose.yml配置解析

services:
  graph:
    build:
      context: .
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/healthcheck')"]
      interval: 10s
      timeout: 5s
      retries: 3
    depends_on:
      neo4j:
        condition: service_healthy
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - NEO4J_URI=bolt://neo4j:${NEO4J_PORT:-7687}
      - NEO4J_USER=${NEO4J_USER}
      - NEO4J_PASSWORD=${NEO4J_PASSWORD}
      - PORT=8000
  neo4j:
    image: neo4j:5.26.2
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:${NEO4J_PORT:-7474} || exit 1"]
      interval: 1s
      timeout: 10s
      retries: 10
      start_period: 3s
    ports:
      - "7474:7474" # HTTP
      - "${NEO4J_PORT:-7687}:${NEO4J_PORT:-7687}" # Bolt
    volumes:
      - neo4j_data:/data
    environment:
      - NEO4J_AUTH=${NEO4J_USER}/${NEO4J_PASSWORD}

volumes:
  neo4j_data:

这个配置文件定义了两个服务：

graph服务：graphiti应用本身，构建当前目录的Dockerfile，依赖neo4j服务，暴露8000端口
neo4j服务：Neo4j数据库，使用5.26.2版本，暴露7474（HTTP）和7687（Bolt）端口，使用命名卷存储数据

环境变量配置

在启动之前，需要创建.env文件设置必要的环境变量：

OPENAI_API_KEY=your_openai_api_key_here
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_neo4j_password

启动和管理服务

使用以下命令启动所有服务：

docker compose up -d

启动后，可以通过以下命令查看服务状态：

docker compose ps

查看服务日志：

# 查看所有服务日志
docker compose logs

# 仅查看graph服务日志并实时跟踪
docker compose logs -f graph

停止服务：

# 停止服务但不删除数据
docker compose down

# 停止服务并删除数据卷
docker compose down -v

MCP服务器的Docker Compose部署

对于需要MCP（Model Context Protocol）服务器的场景，可以使用mcp_server目录下的专用Docker Compose配置：

cd mcp_server
docker compose up -d

mcp_server/docker-compose.yml配置包含了针对MCP服务器优化的设置，包括额外的环境变量和健康检查。

Kubernetes部署：生产环境方案

虽然项目中没有直接提供Kubernetes配置文件，但我们可以基于现有的Dockerfile和Docker Compose配置，构建生产级的Kubernetes部署方案。

基本部署架构

在Kubernetes环境中部署graphiti通常需要以下组件：

Deployment：管理graphiti应用的Pod
StatefulSet：管理Neo4j数据库（如需在K8s中部署）
Service：暴露应用服务
Ingress：处理外部流量
ConfigMap：管理配置数据
Secret：存储敏感信息，如API密钥和密码
PersistentVolumeClaim：为数据库提供持久化存储

构建Kubernetes部署文件

以下是一个基本的Kubernetes部署示例：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: graphiti-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: graphiti
  template:
    metadata:
      labels:
        app: graphiti
    spec:
      containers:
      - name: graphiti
        image: graphiti:latest
        ports:
        - containerPort: 8000
        env:
        - name: OPENAI_API_KEY
          valueFrom:
            secretKeyRef:
              name: graphiti-secrets
              key: openai-api-key
        - name: NEO4J_URI
          valueFrom:
            configMapKeyRef:
              name: graphiti-config
              key: neo4j-uri
        - name: NEO4J_USER
          valueFrom:
            secretKeyRef:
              name: graphiti-secrets
              key: neo4j-user
        - name: NEO4J_PASSWORD
          valueFrom:
            secretKeyRef:
              name: graphiti-secrets
              key: neo4j-password
        livenessProbe:
          httpGet:
            path: /healthcheck
            port: 8000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /healthcheck
            port: 8000
          initialDelaySeconds: 5
          periodSeconds: 5
        resources:
          requests:
            memory: "512Mi"
            cpu: "200m"
          limits:
            memory: "1Gi"
            cpu: "500m"

对应的Service配置：

apiVersion: v1
kind: Service
metadata:
  name: graphiti-service
spec:
  selector:
    app: graphiti
  ports:
  - port: 80
    targetPort: 8000
  type: ClusterIP

配置管理

使用ConfigMap存储非敏感配置：

apiVersion: v1
kind: ConfigMap
metadata:
  name: graphiti-config
data:
  neo4j-uri: "bolt://neo4j-service:7687"
  port: "8000"
  log-level: "info"

使用Secret存储敏感信息：

apiVersion: v1
kind: Secret
metadata:
  name: graphiti-secrets
type: Opaque
data:
  openai-api-key: <base64-encoded-api-key>
  neo4j-user: <base64-encoded-username>
  neo4j-password: <base64-encoded-password>

数据库考虑事项

在生产环境中，Neo4j数据库的部署需要特别注意：

使用StatefulSet而非Deployment以确保稳定的网络标识
配置适当的持久化存储
考虑使用Neo4j的企业版以获得集群功能
配置定期备份策略

部署命令

应用Kubernetes配置：

# 创建命名空间
kubectl create namespace graphiti

# 应用配置
kubectl apply -f k8s/configmap.yaml -n graphiti
kubectl apply -f k8s/secret.yaml -n graphiti
kubectl apply -f k8s/deployment.yaml -n graphiti
kubectl apply -f k8s/service.yaml -n graphiti

# 检查部署状态
kubectl get pods -n graphiti
kubectl get services -n graphiti

常见问题与优化建议

性能优化

资源分配：根据实际负载调整CPU和内存资源。graphiti的LLM相关操作可能需要较多内存。
连接池：确保数据库连接池配置合理，避免连接耗尽。
缓存策略：考虑为频繁访问的数据添加缓存层。

安全最佳实践

最小权限原则：容器内使用非root用户运行，如Dockerfile中定义的app用户。
敏感信息管理：所有敏感信息通过环境变量或Secret注入，不要硬编码在镜像中。
镜像安全：定期更新基础镜像，扫描镜像漏洞。

监控与日志

健康检查：利用Kubernetes的存活探针和就绪探针监控应用状态。
日志收集：配置集中式日志收集，如使用ELK栈或Loki。
性能监控：使用Prometheus和Grafana监控应用性能指标。

扩展性考虑

水平扩展：通过增加Deployment的副本数实现水平扩展。
自动扩缩容：配置HPA（Horizontal Pod Autoscaler）实现基于负载的自动扩缩容。

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: graphiti-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: graphiti-deployment
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 80

部署流程总结

graphiti的容器化部署流程可以总结为以下步骤：

mermaid

无论是本地开发还是生产部署，graphiti的容器化方案都能帮助你快速、可靠地搭建整个系统。通过本文介绍的Docker和Kubernetes部署方法，你可以根据实际需求选择合适的部署策略，轻松应对从开发测试到生产运行的各种场景。

对于更详细的配置选项和高级功能，请参考项目中的Dockerfile、docker-compose.yml和mcp_server/README.md文件。如有任何问题，欢迎参与项目的社区讨论或提交issue。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考