VideoAgentTrek-ScreenFilter部署案例：Kubernetes StatefulSet部署多实例负载均衡

1. 引言

在AI应用大规模落地的过程中，一个核心挑战是如何将单机运行的模型服务，扩展为稳定、高可用的分布式服务。今天要聊的，就是一个非常典型的实战案例——如何将VideoAgentTrek-ScreenFilter这个屏幕内容检测服务，从单机部署升级到Kubernetes集群的多实例负载均衡架构。

你可能已经体验过这个服务：上传一张图片或一段视频，它能自动识别出画面中的屏幕（比如电脑显示器、手机屏幕、电视等），并给出精准的检测框和结构化数据。这个功能在内容审核、媒体分析、智能监控等场景下非常有用。

但问题来了：当用户量上来之后，单台服务器根本扛不住。视频处理本身就很耗资源，一个10秒的视频可能就需要处理几百帧，如果同时有几十个用户上传视频，服务瞬间就会崩溃。更不用说单点故障的风险——服务器一挂，所有服务都停了。

这就是为什么我们需要Kubernetes和StatefulSet。通过这个案例，你会看到如何把一个功能完善的AI应用，包装成可水平扩展的云原生服务。整个过程涉及Docker镜像制作、Kubernetes资源配置、服务发现、负载均衡等多个环节，我会一步步拆解，让你不仅知道怎么做，更明白为什么这么做。

2. 理解VideoAgentTrek-ScreenFilter的核心能力

在开始部署之前，我们先搞清楚这个应用到底能做什么。这决定了我们的架构设计要考虑哪些因素。

2.1 两种检测模式，一种核心能力

VideoAgentTrek-ScreenFilter基于YOLO目标检测模型，专门识别图像和视频中的屏幕类物体。它提供了两种使用方式：

图片检测模式：

• 输入：一张JPG或PNG格式的图片
• 处理：单次推理，识别图片中的所有屏幕
• 输出：
  • 可视化结果图：在原图上用方框标出检测到的屏幕
  • JSON明细数据：每个检测框的类别、置信度、坐标位置

视频检测模式：

• 输入：一段视频文件
• 处理：逐帧分析，对每一帧都进行屏幕检测
• 输出：
  • 带检测框的视频：每一帧都叠加了检测结果
  • JSON统计报告：包含总帧数、各类别统计、每帧的检测明细

2.2 技术特点与资源需求

了解这些特点，对我们设计Kubernetes部署方案至关重要：

1. GPU依赖：模型推理需要GPU加速，否则处理速度会慢得无法接受
2. 内存消耗：视频处理需要加载整个模型到显存，每个实例需要独立的GPU资源
3. 状态保持：虽然检测本身是无状态的，但视频处理过程中有中间状态
4. IO密集型：需要读取上传的文件，写入处理结果
5. 服务发现：多实例情况下，前端需要知道后端有哪些可用实例

这些特点决定了我们不能简单地用Deployment来部署，而需要考虑更合适的StatefulSet方案。

3. 从单机到集群：架构演进思考

3.1 单机部署的局限性

我们先看看最简单的部署方式——单机运行：

# 单机直接运行（开发测试用）
python app.py --port 7860 --model-path /root/ai-models/xlangai/VideoAgentTrek-ScreenFilter/best.pt

这种方式在开发阶段没问题，但到了生产环境就暴露出多个问题：

• 资源瓶颈：单GPU的算力有限，无法并发处理多个视频
• 单点故障：服务挂了就全挂了，没有容错能力
• 难以扩展：流量突增时无法快速扩容
• 维护困难：更新、回滚、监控都不方便

3.2 Kubernetes带来的优势

切换到Kubernetes集群部署，我们能获得这些好处：

• 水平扩展：根据负载自动增加或减少实例数量
• 高可用性：实例故障时自动重启或迁移
• 资源隔离：每个Pod有独立的资源限制，不会相互影响
• 服务发现：通过Service自动发现后端实例
• 滚动更新：不中断服务的情况下更新应用版本

3.3 为什么选择StatefulSet而不是Deployment？

这是本案例的一个关键决策点。两种控制器都能管理Pod，但适用场景不同：

特性	Deployment	StatefulSet	我们的选择原因
Pod标识	随机名称（如app-xxx）	有序名称（如app-0, app-1）	需要稳定的网络标识
存储卷	共享或动态	独立持久化存储	每个实例可能需要独立配置
启动顺序	并行启动	顺序启动（可选）	确保服务稳定启动
更新策略	滚动更新	分区更新	更可控的更新过程
服务发现	通过Service负载均衡	通过Headless Service直接访问	需要直接访问特定实例

对于VideoAgentTrek-ScreenFilter，我们选择StatefulSet的主要原因：

1. 稳定的网络标识：每个实例有固定的主机名，便于监控和日志追踪
2. 独立的存储：每个Pod可以挂载独立的配置文件或模型缓存
3. 有序部署：避免所有实例同时启动冲击共享资源（如模型下载）
4. 更精细的控制：可以逐个实例更新，降低风险

4. 构建生产就绪的Docker镜像

4.1 基础镜像选择与优化

Docker镜像是Kubernetes部署的基础。我们需要一个包含所有依赖的镜像：

# Dockerfile
FROM nvidia/cuda:11.8.0-runtime-ubuntu22.04

# 设置环境变量
ENV DEBIAN_FRONTEND=noninteractive \
    PYTHONUNBUFFERED=1 \
    MAX_VIDEO_SECONDS=60

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    python3.10 \
    python3-pip \
    libgl1-mesa-glx \
    libglib2.0-0 \
    ffmpeg \
    supervisor \
    && rm -rf /var/lib/apt/lists/*

# 创建工作目录
WORKDIR /app

# 复制应用代码
COPY . /app/

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

# 创建必要的目录
RUN mkdir -p /var/log/supervisor /root/ai-models

# 复制Supervisor配置
COPY supervisord.conf /etc/supervisor/conf.d/

# 暴露端口
EXPOSE 7860

# 启动命令
CMD ["supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]

这个Dockerfile有几个关键点：

1. 基于NVIDIA CUDA镜像：确保GPU支持
2. 安装FFmpeg：视频处理必备
3. 使用Supervisor：进程管理，确保服务异常时自动重启
4. 设置环境变量：如MAX_VIDEO_SECONDS控制视频处理时长

4.2 Supervisor配置确保高可用

Supervisor负责管理我们的Python应用进程：

; supervisord.conf
[program:videoagent-screenfilter]
command=python3 app.py --port 7860 --model-path /root/ai-models/xlangai/VideoAgentTrek-ScreenFilter/best.pt
directory=/app
autostart=true
autorestart=true
startretries=3
user=root
stdout_logfile=/var/log/supervisor/videoagent-screenfilter.out.log
stdout_logfile_maxbytes=50MB
stdout_logfile_backups=10
stderr_logfile=/var/log/supervisor/videoagent-screenfilter.err.log
stderr_logfile_maxbytes=50MB
stderr_logfile_backups=10
environment=PYTHONUNBUFFERED=1

这样配置后，即使应用崩溃，Supervisor也会自动重启它，保证服务持续可用。

4.3 镜像构建与推送

构建并推送镜像到私有仓库：

# 构建镜像
docker build -t your-registry/videoagent-screenfilter:1.0.0 .

# 测试运行
docker run --gpus all -p 7860:7860 your-registry/videoagent-screenfilter:1.0.0

# 推送镜像
docker push your-registry/videoagent-screenfilter:1.0.0

5. Kubernetes部署实战：StatefulSet配置详解

5.1 命名空间与资源配置

首先创建独立的命名空间和资源限制：

# 01-namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: videoagent
---
apiVersion: v1
kind: ResourceQuota
metadata:
  name: videoagent-quota
  namespace: videoagent
spec:
  hard:
    requests.cpu: "8"
    requests.memory: 16Gi
    limits.cpu: "16"
    limits.memory: 32Gi
    requests.nvidia.com/gpu: "4"
    limits.nvidia.com/gpu: "4"

5.2 StatefulSet核心配置

这是最关键的配置文件，定义了如何运行我们的应用：

# 02-statefulset.yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: videoagent-screenfilter
  namespace: videoagent
spec:
  serviceName: videoagent-service
  replicas: 3  # 初始3个实例，可根据需要调整
  selector:
    matchLabels:
      app: videoagent-screenfilter
  template:
    metadata:
      labels:
        app: videoagent-screenfilter
    spec:
      containers:
      - name: videoagent
        image: your-registry/videoagent-screenfilter:1.0.0
        imagePullPolicy: IfNotPresent
        ports:
        - containerPort: 7860
          name: http
        env:
        - name: MAX_VIDEO_SECONDS
          value: "60"
        - name: CONFIDENCE_THRESHOLD
          value: "0.25"
        - name: IOU_THRESHOLD
          value: "0.45"
        resources:
          requests:
            memory: "4Gi"
            cpu: "2"
            nvidia.com/gpu: "1"
          limits:
            memory: "8Gi"
            cpu: "4"
            nvidia.com/gpu: "1"
        volumeMounts:
        - name: model-storage
          mountPath: /root/ai-models
          readOnly: true
        - name: temp-storage
          mountPath: /tmp
        livenessProbe:
          httpGet:
            path: /health
            port: 7860
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 7860
          initialDelaySeconds: 5
          periodSeconds: 5
  volumeClaimTemplates:
  - metadata:
      name: model-storage
    spec:
      accessModes: [ "ReadOnlyMany" ]
      storageClassName: "fast-ssd"
      resources:
        requests:
          storage: 10Gi
  - metadata:
      name: temp-storage
    spec:
      accessModes: [ "ReadWriteOnce" ]
      storageClassName: "standard"
      resources:
        requests:
          storage: 5Gi

这个配置有几个重要部分：

1. 资源请求与限制：每个Pod请求1个GPU、4GB内存，确保有足够资源运行模型
2. 健康检查：livenessProbe检测应用是否存活，readinessProbe检测是否就绪
3. 存储卷：
   • model-storage：只读共享存储，存放模型文件
   • temp-storage：每个Pod独立的临时存储，存放处理中的文件
4. 环境变量：可配置的处理参数

5.3 服务暴露与负载均衡

创建Service来暴露服务并实现负载均衡：

# 03-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: videoagent-service
  namespace: videoagent
spec:
  selector:
    app: videoagent-screenfilter
  ports:
  - port: 7860
    targetPort: 7860
    name: http
  type: ClusterIP
---
apiVersion: v1
kind: Service
metadata:
  name: videoagent-headless
  namespace: videoagent
spec:
  clusterIP: "None"  # Headless Service，无集群IP
  selector:
    app: videoagent-screenfilter
  ports:
  - port: 7860
    name: http

这里创建了两个Service：

1. ClusterIP Service：用于内部负载均衡，前端通过这个Service访问后端
2. Headless Service：用于StatefulSet Pod的直接访问，每个Pod有稳定的DNS名称

5.4 Ingress配置对外访问

如果需要从集群外部访问，还需要配置Ingress：

# 04-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: videoagent-ingress
  namespace: videoagent
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "100m"
spec:
  ingressClassName: nginx
  rules:
  - host: videoagent.yourdomain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: videoagent-service
            port:
              number: 7860

6. 部署操作与验证

6.1 逐步部署应用

按顺序应用配置文件：

# 创建命名空间和资源配额
kubectl apply -f 01-namespace.yaml

# 部署StatefulSet
kubectl apply -f 02-statefulset.yaml

# 部署Service
kubectl apply -f 03-service.yaml

# 部署Ingress（如果需要）
kubectl apply -f 04-ingress.yaml

6.2 验证部署状态

检查各个资源的状态：

# 查看StatefulSet状态
kubectl get statefulset -n videoagent

# 查看Pod状态（应该看到3个Pod）
kubectl get pods -n videoagent -l app=videoagent-screenfilter

# 查看Pod详情
kubectl describe pod videoagent-screenfilter-0 -n videoagent

# 查看Service
kubectl get svc -n videoagent

# 查看Ingress
kubectl get ingress -n videoagent

6.3 测试服务功能

通过端口转发测试服务是否正常：

# 端口转发到本地
kubectl port-forward svc/videoagent-service 7860:7860 -n videoagent

# 在浏览器访问 http://localhost:7860
# 或者用curl测试
curl http://localhost:7860/health

7. 多实例负载均衡策略

7.1 Kubernetes Service的负载均衡机制

当创建了Service后，Kubernetes会自动实现负载均衡：

# 查看Service的Endpoints（后端Pod列表）
kubectl get endpoints videoagent-service -n videoagent -o yaml

Service通过kube-proxy组件实现流量分发：

• iptables模式：默认模式，通过iptables规则转发
• IPVS模式：性能更好，支持更多负载均衡算法
• userspace模式：旧模式，不推荐使用

7.2 自定义负载均衡策略

如果需要更精细的控制，可以使用Ingress Controller的注解：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: videoagent-ingress
  namespace: videoagent
  annotations:
    nginx.ingress.kubernetes.io/load-balance: "ewma"
    nginx.ingress.kubernetes.io/upstream-hash-by: "$remote_addr"
spec:
  # ... 其他配置

支持的负载均衡算法：

• round-robin：轮询（默认）
• least_conn：最少连接数
• ip_hash：基于客户端IP的哈希
• ewma：指数加权移动平均

7.3 会话保持（Session Affinity）

对于某些需要会话保持的场景：

apiVersion: v1
kind: Service
metadata:
  name: videoagent-service
  namespace: videoagent
spec:
  selector:
    app: videoagent-screenfilter
  sessionAffinity: ClientIP
  sessionAffinityConfig:
    clientIP:
      timeoutSeconds: 10800
  ports:
  - port: 7860
    targetPort: 7860

8. 监控、日志与运维

8.1 监控指标收集

配置Prometheus监控：

# 添加Prometheus注解到Pod
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: videoagent-screenfilter
  namespace: videoagent
spec:
  template:
    metadata:
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "7860"
        prometheus.io/path: "/metrics"
    # ... 其他配置

应用需要暴露/metrics端点：

# 在app.py中添加
from prometheus_client import Counter, Histogram, generate_latest

REQUEST_COUNT = Counter('videoagent_requests_total', 'Total requests')
PROCESSING_TIME = Histogram('videoagent_processing_seconds', 'Processing time')

@app.route('/metrics')
def metrics():
    return generate_latest()

8.2 集中式日志收集

使用Fluentd或Filebeat收集日志：

# 添加sidecar容器收集日志
spec:
  containers:
  - name: videoagent
    # ... 主容器配置
  - name: fluentd-sidecar
    image: fluent/fluentd:latest
    volumeMounts:
    - name: app-logs
      mountPath: /var/log/app
    - name: fluentd-config
      mountPath: /fluentd/etc
volumes:
- name: app-logs
  emptyDir: {}
- name: fluentd-config
  configMap:
    name: fluentd-config

8.3 自动扩缩容配置

配置HPA（Horizontal Pod Autoscaler）实现自动扩缩容：

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: videoagent-hpa
  namespace: videoagent
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: StatefulSet
    name: videoagent-screenfilter
  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

9. 常见问题与解决方案

9.1 GPU资源不足问题

问题现象：Pod处于Pending状态，事件显示"0/3 nodes are available: 3 Insufficient nvidia.com/gpu"

解决方案：

1. 检查节点GPU资源：kubectl describe node <node-name> | grep -A 10 Allocatable
2. 考虑使用节点选择器将Pod调度到有GPU的节点：

spec:
  template:
    spec:
      nodeSelector:
        accelerator: nvidia-tesla-t4
      tolerations:
      - key: "nvidia.com/gpu"
        operator: "Exists"
        effect: "NoSchedule"

9.2 存储卷挂载失败

问题现象：Pod启动失败，日志显示"Unable to mount volumes"

解决方案：

1. 检查StorageClass是否存在：kubectl get storageclass
2. 确保PVC已绑定：kubectl get pvc -n videoagent
3. 检查PV是否可用：kubectl get pv

9.3 服务发现与网络问题

问题现象：Pod之间无法通信，或外部无法访问服务

解决方案：

1. 检查Service的Endpoints：kubectl get endpoints videoagent-service -n videoagent
2. 检查网络策略：kubectl get networkpolicy -n videoagent
3. 测试Pod间网络：kubectl exec -it videoagent-screenfilter-0 -n videoagent -- curl http://videoagent-screenfilter-1.videoagent-headless:7860/health

9.4 性能优化建议

根据实际运行情况调整配置：

# 优化建议配置
spec:
  template:
    spec:
      containers:
      - name: videoagent
        resources:
          requests:
            memory: "8Gi"  # 增加内存请求
            cpu: "4"
            nvidia.com/gpu: "1"
          limits:
            memory: "16Gi"  # 增加内存限制
            cpu: "8"
            nvidia.com/gpu: "1"
        # 添加GPU相关环境变量
        env:
        - name: CUDA_VISIBLE_DEVICES
          value: "0"
        - name: TF_FORCE_GPU_ALLOW_GROWTH
          value: "true"

10. 总结与最佳实践

通过这个案例，我们完成了VideoAgentTrek-ScreenFilter从单机部署到Kubernetes多实例集群的完整迁移。整个过程涉及多个关键技术点：

10.1 关键收获

1. StatefulSet的优势：对于需要稳定标识、有序部署、独立存储的应用，StatefulSet比Deployment更合适
2. GPU资源管理：Kubernetes可以很好地管理GPU资源，确保每个Pod获得独立的GPU
3. 服务发现机制：通过Service和Headless Service的组合，实现了灵活的访问方式
4. 健康检查：liveness和readiness探针确保了服务的高可用性
5. 存储设计：合理使用PVC模板，为每个Pod提供必要的存储

10.2 生产环境建议

基于实际运维经验，我建议：

1. 监控告警：一定要配置完整的监控体系，特别是GPU使用率和显存占用
2. 日志聚合：使用ELK或Loki集中管理日志，便于问题排查
3. 备份策略：定期备份模型文件和配置
4. 灰度发布：使用金丝雀发布策略，先更新少量实例验证
5. 成本优化：根据业务峰谷期动态调整副本数，节省资源

10.3 扩展思考

这个架构还可以进一步优化：

1. 异构计算：混合使用不同型号的GPU，通过节点选择器调度
2. 边缘计算：在边缘节点部署轻量级版本，减少中心集群压力
3. 函数计算：将视频拆分为帧，通过函数计算并行处理
4. 模型版本管理：集成模型仓库，支持热更新模型文件

部署完成后，你的VideoAgentTrek-ScreenFilter服务就具备了企业级的高可用性和可扩展性。无论是面对突发流量，还是需要滚动更新，都有了完善的解决方案。最重要的是，这个架构模式可以复用到其他AI应用上，形成一套标准的AI服务部署范式。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。