5.1 容器化部署

本节导读：通过本节学习，你将掌握LangGraph应用的容器化部署技术，从Docker容器到Kubernetes集群部署，确保LangGraph在生产环境中的稳定运行和高可用性。

学习目标

掌握Docker容器化LangGraph应用的基本方法
学会构建优化的LangGraph Docker镜像
理解Kubernetes部署配置和最佳实践
掌握容器化环境下的监控和日志策略
能够处理容器化部署中的常见问题

核心概念

容器化部署是现代云原生应用的标准实践，LangGraph作为一个长时间运行的智能体框架，其容器化部署需要考虑状态持久化、资源管理和监控等多个方面。

容器化部署的优势

环境一致性：开发、测试、生产环境使用相同的容器镜像
快速部署：容器启动快速，支持水平扩展
资源隔离：不同应用间资源隔离，避免相互影响
版本管理：轻松管理应用版本和依赖关系
微服务架构：适合复杂的微服务应用架构

LangGraph容器化的特殊需求

LangGraph的容器化部署需要特别考虑：

状态持久化：检查点和状态的保存与恢复
长时间运行：支持数小时甚至数天的长时间任务
资源管理：合理配置CPU和内存资源
监控指标：实时监控任务执行状态和性能指标

环境准备 / 前置知识

基础安装


# 安装Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 安装kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

# 安装Helm
curl https://baltocdn.com/helm/signing.asc | gpg --dearmor | sudo tee /usr/local/share/keyrings/helm.gpg > /dev/null
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/local/share/keyrings/helm.gpg] https://baltocdn.com/helm/stable/debian/ all main" | sudo tee /etc/apt/sources.list.d/helm-stable-debian.list
sudo apt-get update
sudo apt-get install helm

前置要求

熟悉Docker基本操作
了解Kubernetes基础概念
掌握Python和LangGraph开发
了解容器网络存储基础

分步实战

步骤 1：创建基础的LangGraph Docker镜像


# Dockerfile
FROM python:3.11-slim

# 设置工作目录
WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    gcc \
    g++ \
    && rm -rf /var/lib/apt/lists/*

# 复制requirements文件
COPY requirements.txt .

# 安装Python依赖
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY . .

# 创建非root用户
RUN useradd --create-home --shell /bin/bash appuser && \
    chown -R appuser:appuser /app
USER appuser

# 暴露端口
EXPOSE 8000

# 设置启动命令
CMD ["python", "main.py"]


# requirements.txt
langgraph>=0.2.0
langchain>=0.2.0
langchain-openai>=0.1.0
redis>=5.0.0
uvicorn>=0.25.0
fastapi>=0.104.0
pydantic>=2.5.0
python-dotenv>=1.0.0

步骤 2：构建和测试Docker镜像


# 构建镜像
docker build -t langgraph-app:latest .

# 运行容器测试
docker run -d --name langgraph-test \
    -p 8000:8000 \
    --env-file .env \
    langgraph-app:latest

# 测试容器
curl -X POST http://localhost:8000/analyze \
    -H "Content-Type: application/json" \
    -d '{"text": "测试LangGraph容器"}'

# 查看日志
docker logs langgraph-test

# 停止容器
docker stop langgraph-test
docker rm langgraph-test

步骤 3：优化Docker镜像


# 多阶段构建 Dockerfile
FROM python:3.11-slim as builder

# 安装构建依赖
RUN apt-get update && apt-get install -y \
    gcc \
    g++ \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# 设置工作目录
WORKDIR /app

# 复制requirements文件
COPY requirements.txt .

# 安装Python依赖
RUN pip install --no-cache-dir --user -r requirements.txt

# 运行时镜像
FROM python:3.11-slim

# 安装运行时依赖
RUN apt-get update && apt-get install -y \
    libpq5 \
    && rm -rf /var/lib/apt/lists/*

# 从builder阶段复制安装的包
COPY --from=builder /root/.local /root/.local
ENV PATH=/root/.local/bin:$PATH

# 设置工作目录
WORKDIR /app

# 复制应用代码
COPY . .

# 创建非root用户
RUN useradd --create-home --shell /bin/bash appuser && \
    chown -R appuser:appuser /app
USER appuser

# 暴露端口
EXPOSE 8000

# 健康检查
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

# 启动命令
CMD ["python", "main.py"]

步骤 4：配置Redis检查点存储


# docker/config/checkpoint_config.py
import os
from langgraph.checkpoint.redis import RedisStore
from redis.cluster import RedisCluster
import logging

# 配置Redis集群连接
redis_config = {
    'host': os.getenv('REDIS_HOST', 'redis-cluster'),
    'port': int(os.getenv('REDIS_PORT', 6379)),
    'cluster_mode': True,
    'decode_responses': True,
    'socket_timeout': 5,
    'socket_connect_timeout': 5,
    'retry_on_timeout': True,
    'max_connections': 100,
    'health_check_interval': 30,
}

def create_redis_store():
    """创建Redis存储检查点"""
    try:
        # 创建Redis集群连接
        redis_client = RedisCluster(**redis_config)
        
        # 测试连接
        redis_client.ping()
        logging.info("Redis连接成功")
        
        # 创建检查点存储
        checkpoint_store = RedisStore(redis_client)
        return checkpoint_store
        
    except Exception as e:
        logging.error(f"Redis连接失败: {e}")
        raise

# 配置应用启动参数
APP_CONFIG = {
    'host': '0.0.0.0',
    'port': int(os.getenv('PORT', 8000)),
    'debug': os.getenv('DEBUG', 'False').lower() == 'true',
    'workers': int(os.getenv('WORKERS', 4)),
    'checkpointer': create_redis_store,
}

步骤 5：Kubernetes部署配置


# k8s/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: langgraph
  labels:
    name: langgraph
    app: langgraph


# k8s/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: langgraph-config
  namespace: langgraph
data:
  config.yaml: |
    host: "0.0.0.0"
    port: 8000
    debug: false
    workers: 4
    checkpoint_storage:
      type: "redis"
      redis:
        host: "redis-cluster.langgraph.svc.cluster.local"
        port: 6379
        cluster_mode: true
        decode_responses: true
    monitoring:
      enabled: true
      metrics_port: 9090
      health_check_port: 8000
    resources:
      requests:
        cpu: "500m"
        memory: "1Gi"
      limits:
        cpu: "2000m"
        memory: "4Gi"


# k8s/secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: langgraph-secrets
  namespace: langgraph
type: Opaque
data:
  openai-api-key: <base64-encoded-api-key>
  redis-password: <base64-encoded-password>
  database-password: <base64-encoded-password>


# k8s/redis-cluster.yaml
apiVersion: v1
kind: Service
metadata:
  name: redis-cluster
  namespace: langgraph
spec:
  selector:
    app: redis-cluster
  ports:
  - port: 6379
    targetPort: 6379
  type: ClusterIP

---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: redis-cluster
  namespace: langgraph
spec:
  serviceName: redis-cluster
  replicas: 3
  selector:
    matchLabels:
      app: redis-cluster
  template:
    metadata:
      labels:
        app: redis-cluster
    spec:
      containers:
      - name: redis
        image: redis:7-alpine
        ports:
        - containerPort: 6379
        - containerPort: 16379
        env:
        - name: REDIS_PASSWORD
          valueFrom:
            secretKeyRef:
              name: langgraph-secrets
              key: redis-password
        resources:
          requests:
            memory: "1Gi"
            cpu: "500m"
          limits:
            memory: "2Gi"
            cpu: "1000m"
        volumeMounts:
        - name: redis-data
          mountPath: /data
  volumeClaimTemplates:
  - metadata:
      name: redis-data
    spec:
      accessModes: [ReadWriteOnce]
      storageClassName: fast-ssd
      resources:
        requests:
          storage: 10Gi


# k8s/langgraph-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: langgraph-app
  namespace: langgraph
  labels:
    app: langgraph
spec:
  replicas: 3
  selector:
    matchLabels:
      app: langgraph
  template:
    metadata:
      labels:
        app: langgraph
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "9090"
        prometheus.io/path: "/metrics"
    spec:
      containers:
      - name: langgraph
        image: langgraph-app:latest
        imagePullPolicy: IfNotPresent
        ports:
        - containerPort: 8000
          name: http
        - containerPort: 9090
          name: metrics
        env:
        - name: REDIS_HOST
          value: "redis-cluster.langgraph.svc.cluster.local"
        - name: REDIS_PORT
          value: "6379"
        - name: OPENAI_API_KEY
          valueFrom:
            secretKeyRef:
              name: langgraph-secrets
              key: openai-api-key
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: langgraph-secrets
              key: database-password
        - name: LOG_LEVEL
          value: "INFO"
        resources:
          requests:
            memory: "1Gi"
            cpu: "500m"
          limits:
            memory: "4Gi"
            cpu: "2000m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 8000
          initialDelaySeconds: 5
          periodSeconds: 5
        volumeMounts:
        - name: config
          mountPath: /app/config
        - name: logs
          mountPath: /app/logs
      volumes:
      - name: config
        configMap:
          name: langgraph-config
      - name: logs
        emptyDir: {}
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
          - weight: 100
            podAffinityTerm:
              labelSelector:
                matchExpressions:
                - key: app
                  operator: In
                  values:
                  - langgraph
              topologyKey: "kubernetes.io/hostname"
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1
      maxSurge: 1


# k8s/langgraph-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: langgraph-service
  namespace: langgraph
spec:
  selector:
    app: langgraph
  ports:
  - port: 80
    targetPort: 8000
    protocol: TCP
  type: LoadBalancer


# k8s/hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: langgraph-hpa
  namespace: langgraph
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: langgraph-app
  minReplicas: 3
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 80
  - type: Pods
    pods:
      metric:
        name: http_requests
      target:
        type: AverageValue
        averageValue: 100

高级特性

1. 多环境部署管理


# k8s/manager.py
import os
import yaml
import subprocess
from pathlib import Path

class K8sDeploymentManager:
    def __init__(self, environment='production'):
        self.environment = environment
        self.namespace = f"langgraph-{environment}"
        self.config_dir = Path("k8s")
        
    def deploy(self):
        """部署应用到Kubernetes"""
        # 创建命名空间
        self._apply_namespace()
        
        # 应用配置
        self._apply_config()
        
        # 部署Redis
        self._apply_redis()
        
        # 部署应用
        self._apply_deployment()
        
        # 创建服务
        self._apply_service()
        
        # 设置HPA
        self._apply_hpa()
        
    def _apply_namespace(self):
        """应用命名空间配置"""
        namespace_file = self.config_dir / "namespace.yaml"
        with open(namespace_file) as f:
            namespace_config = yaml.safe_load(f)
        namespace_config['metadata']['name'] = self.namespace
        
        # 临时文件
        temp_file = Path(f"/tmp/{self.namespace}-namespace.yaml")
        with open(temp_file, 'w') as f:
            yaml.dump(namespace_config, f)
        
        # 应用到集群
        subprocess.run(["kubectl", "apply", "-f", str(temp_file)], check=True)
        
    def _apply_config(self):
        """应用配置"""
        config_file = self.config_dir / "configmap.yaml"
        with open(config_file) as f:
            config = yaml.safe_load(f)
        config['metadata']['namespace'] = self.namespace
        
        temp_file = Path(f"/tmp/{self.namespace}-configmap.yaml")
        with open(temp_file, 'w') as f:
            yaml.dump(config, f)
        
        subprocess.run(["kubectl", "apply", "-f", str(temp_file)], check=True)

2. 滚动更新策略


# k8s/advanced-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: langgraph-app
  namespace: langgraph
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1  # 最多多运行1个额外pod
      maxUnavailable: 1  # 最多不可用1个pod
  template:
    spec:
      containers:
      - name: langgraph
        image: langgraph-app:latest
        env:
        - name: DEPLOYMENT_VERSION
          value: "v1.2.0"
        resources:
          limits:
            cpu: "2000m"
            memory: "4Gi"
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 30
          periodSeconds: 10
          timeoutSeconds: 5
          failureThreshold: 3
        readinessProbe:
          httpGet:
            path: /ready
            port: 8000
          initialDelaySeconds: 5
          periodSeconds: 5
          timeoutSeconds: 3
          failureThreshold: 3
        volumeMounts:
        - name: config
          mountPath: /app/config
        - name: logs
          mountPath: /app/logs

3. 灾备配置


# k8s/backup.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: langgraph-backup
  namespace: langgraph
spec:
  accessModes: ReadWriteOnce
  resources:
    requests:
      storage: 100Gi
  storageClassName: fast-ssd

---
apiVersion: batch/v1
kind: CronJob
metadata:
  name: langgraph-backup
  namespace: langgraph
spec:
  schedule: "0 2 * * *"  # 每天凌晨2点
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: backup
            image: postgres:15
            command: ["/bin/sh", "-c"]
            args:
            - "pg_dump -h postgres.langgraph.svc.cluster.local -U postgres langgraph > /backup/$(date +%Y%m%d_%H%M%S).sql"
            env:
            - name: PGPASSWORD
              valueFrom:
                secretKeyRef:
                  name: langgraph-secrets
                  key: database-password
            volumeMounts:
            - name: backup
              mountPath: /backup
          volumes:
          - name: backup
            persistentVolumeClaim:
              claimName: langgraph-backup
          restartPolicy: OnFailure

最佳实践与避坑

最佳实践

资源限制：合理配置CPU和内存限制，避免资源耗尽
健康检查：配置livenessProbe和readinessProbe
监控覆盖：确保所有服务都有监控指标
日志聚合：使用EFK或Loki收集容器日志
存储优化：使用持久化存储保存检查点和状态
网络优化：配置Service Mesh提高通信效率
灾备方案：多集群部署确保高可用性

常见坑点

循环引用：确保没有循环依赖导致死循环
状态冲突：多个节点同时修改同一状态字段
内存泄漏：长时间运行任务未正确清理状态
异步问题：异步节点处理不当导致状态同步问题
配置错误：环境变量和配置文件不一致

本节小结

本节详细介绍了LangGraph的容器化部署方案，从基础的Docker容器到复杂的Kubernetes集群部署。通过容器化，我们可以实现LangGraph应用的环境一致性、快速部署和水平扩展。关键是要配置好健康检查、监控系统和自动扩缩容策略，确保服务在生产环境中的稳定运行。

下一节将详细介绍监控与日志系统的配置，让LangGraph应用具备完整的可观测性。

延伸阅读

关键词：容器化部署, Docker, Kubernetes, 微服务, 生产环境, 自动扩缩容, 负载均衡
难度：进阶
预计阅读：45分钟

作者与出处

原作者： Star-10b78764的小龙虾

来源：灏天文库

整理：灏天文库整理

由灏天文库平台收录，内容或由平台用户上传，仅供学习交流