Retinaface+CurricularFace 基于 Kubernetes StatefulSet 部署方案

Retinaface+CurricularFace 部署教程：Kubernetes StatefulSet 部署最佳实践

1. 为什么选择 StatefulSet 部署人脸识别服务？

在开始动手之前，我们先搞清楚一个问题：为什么不用更常见的 Deployment，而要选择 StatefulSet？

我见过太多团队在部署有状态服务时踩坑。人脸识别模型服务有几个特点：

• 模型文件大：Retinaface 和 CurricularFace 的模型文件加起来有好几百 MB
• 加载时间长：模型初始化需要时间，频繁重启会影响服务可用性
• 需要持久化存储：日志、临时文件、缓存等需要持久保存
• 服务发现需要稳定：每个实例需要有稳定的网络标识

如果用普通的 Deployment，每次 Pod 重启都可能被调度到不同的节点，存储会丢失，网络名称也会变。而 StatefulSet 正好解决了这些问题：

• 稳定的网络标识：Pod 名称固定（如 face-recognition-0, face-recognition-1）
• 有序的部署和扩展：按顺序创建、删除 Pod，避免脑裂问题
• 持久化存储：每个 Pod 可以绑定自己的 PVC，数据不会丢失
• 优雅的滚动更新：支持金丝雀发布、蓝绿部署等高级更新策略

下面这张图展示了 StatefulSet 与 Deployment 在部署有状态服务时的核心区别：

graph TD A[人脸识别服务需求] --> B{选择部署方式} B --> C[Deployment] B --> D[StatefulSet] C --> C1[无状态服务] C --> C2[Pod 名称随机] C --> C3[存储随 Pod 删除] C --> C4[适合 Web 前端] D --> D1[有状态服务] D --> D2[Pod 名称固定] D --> D3[存储持久化] D --> D4[适合数据库/模型服务] E[Retinaface+CurricularFace] --> F[模型文件大] E --> G[加载时间长] E --> H[需要持久存储] F --> D G --> D H --> D 

明白了为什么选择 StatefulSet，接下来我们就开始实际的部署工作。

2. 环境准备与镜像说明

2.1 镜像环境配置

我们使用的 Retinaface+CurricularFace 镜像已经预置了完整的推理环境。先来了解一下镜像的基本配置：

# 镜像环境概览 基础镜像：Ubuntu 20.04 Python 版本：3.11.14 深度学习框架：PyTorch 2.5.0 + CUDA 12.1 人脸识别算法：RetinaFace（检测） + CurricularFace（识别） 工作目录：/root/Retinaface_CurricularFace 

这个镜像最大的优点是'开箱即用'。你不需要自己安装 PyTorch、CUDA 这些复杂的依赖，也不需要手动下载和配置模型文件。所有东西都已经准备好了，包括：

• 预训练的 RetinaFace 人脸检测模型
• 预训练的 CurricularFace 人脸识别模型
• 优化过的推理脚本
• 完整的 Python 环境

2.2 本地测试验证

在部署到 Kubernetes 之前，我强烈建议你先在本地测试一下镜像的基本功能。这能帮你提前发现环境问题，避免在集群部署时浪费时间。

进入容器测试的步骤很简单：

# 1. 拉取镜像（如果你还没有的话）
docker pull your-registry/retinaface-curricularface:latest
# 2. 运行容器并进入
docker run -it --gpus all your-registry/retinaface-curricularface:latest bash
# 3. 在容器内激活环境并测试
cd /root/Retinaface_CurricularFace
conda activate torch25
# 4. 运行测试脚本
python inference_face.py 

如果一切正常，你会看到类似这样的输出：

检测到人脸，开始特征提取...
图片 1 特征维度：512
图片 2 特征维度：512
相似度得分：0.856
判定结果：同一人 

这个测试能验证三件事：

1. GPU 驱动和 CUDA 是否正常工作
2. 模型文件是否完整
3. 推理脚本是否能正确运行

3. Kubernetes StatefulSet 部署配置

现在进入核心部分：编写 StatefulSet 的配置文件。我会分步骤详细解释每个配置的作用。

3.1 创建命名空间和存储

首先，为我们的服务创建一个独立的命名空间：

# 1-namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: face-recognition
  labels:
    name: face-recognition

接下来是存储配置。人脸识别服务需要持久化存储来保存：

• 模型文件（虽然镜像里已有，但持久化可以加速启动）
• 推理日志
• 临时处理文件

# 2-storageclass.yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast-ssd
provisioner: kubernetes.io/gce-pd # 根据你的云平台调整
parameters:
  type: pd-ssd
  replication-type: none
---
# 3-pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: face-model-pvc
  namespace: face-recognition
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: fast-ssd
  resources:
    requests:
      storage: 10Gi

3.2 StatefulSet 核心配置

这是最关键的配置文件，我加了详细注释帮你理解每个部分：

# 4-statefulset.yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: face-recognition
  namespace: face-recognition
  labels:
    app: face-recognition
spec:
  serviceName: "face-recognition-service" # 必须指定，用于服务发现
  replicas: 3 # 启动 3 个副本，根据你的需求调整
  # Pod 选择器
  selector:
    matchLabels:
      app: face-recognition
  # Pod 模板
  template:
    metadata:
      labels:
        app: face-recognition
    spec:
      # 节点选择：优先调度到有 GPU 的节点
      nodeSelector:
        accelerator: nvidia-tesla-t4 # 根据你的 GPU 类型调整
      # 容器配置
      containers:
      - name: face-recognition-container
        image: your-registry/retinaface-curricularface:latest
        imagePullPolicy: Always
        # 资源限制
        resources:
          limits:
            nvidia.com/gpu: 1 # 申请 1 个 GPU
            memory: "8Gi"
            cpu: "4"
          requests:
            nvidia.com/gpu: 1
            memory: "4Gi"
            cpu: "2"
        # 环境变量
        env:
        - name: MODEL_DIR
          value: "/models"
        - name: LOG_LEVEL
          value: "INFO"
        # 容器端口
        ports:
        - containerPort: 8000
          name: http
          protocol: TCP
        # 启动命令
        command: ["/bin/bash", "-c"]
        args:
        - |
          # 激活 conda 环境
          source /root/miniconda3/bin/activate torch25
          # 复制模型文件到持久化存储（如果不存在）
          if [ ! -f /data/models/retinaface.pth ]; then
            echo "复制模型文件到持久化存储..."
            cp -r /root/Retinaface_CurricularFace/models/* /data/models/
          fi
          # 启动 HTTP 服务
          cd /root/Retinaface_CurricularFace
          python http_server.py --port 8000 --model-dir /data/models
        # 存活探针
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 60 # 给模型加载留出时间
          periodSeconds: 30
          timeoutSeconds: 10
          failureThreshold: 3
        # 就绪探针
        readinessProbe:
          httpGet:
            path: /ready
            port: 8000
          initialDelaySeconds: 90 # 需要更长时间确保模型完全加载
          periodSeconds: 20
          timeoutSeconds: 5
        # 卷挂载
        volumeMounts:
        - name: model-storage
          mountPath: /data/models
          readOnly: false
        - name: log-storage
          mountPath: /var/log/face-recognition
          readOnly: false
      # 卷声明模板
      volumeClaimTemplates:
      - metadata:
          name: model-storage
        spec:
          accessModes: ["ReadWriteOnce"]
          storageClassName: "fast-ssd"
          resources:
            requests:
              storage: 10Gi
      - metadata:
          name: log-storage
        spec:
          accessModes: ["ReadWriteOnce"]
          storageClassName: "fast-ssd"
          resources:
            requests:
              storage: 5Gi

这个配置有几个关键点需要注意：

1. serviceName 必须设置：这是 StatefulSet 的硬性要求，用于生成稳定的 DNS 记录
2. GPU 资源申请：通过 nvidia.com/gpu 来申请 GPU 资源
3. 探针配置：给了足够的初始延迟，因为模型加载需要时间
4. volumeClaimTemplates：这是 StatefulSet 的特色，每个 Pod 都会自动创建自己的 PVC

3.3 服务暴露配置

部署好 StatefulSet 后，我们需要通过 Service 来暴露服务：

# 5-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: face-recognition-service
  namespace: face-recognition
spec:
  clusterIP: None # Headless Service，用于 StatefulSet
  selector:
    app: face-recognition
  ports:
  - port: 8000
    targetPort: 8000
    name: http
---
# 6-ingress.yaml（如果需要外部访问）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: face-recognition-ingress
  namespace: face-recognition
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "10m"
spec:
  ingressClassName: nginx
  rules:
  - host: face-recognition.your-domain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: face-recognition-service
            port:
              number: 8000

4. 部署与验证

4.1 执行部署

现在我们可以开始部署了。按照顺序执行以下命令：

# 1. 创建命名空间
kubectl apply -f 1-namespace.yaml
# 2. 创建存储类（如果还没有）
kubectl apply -f 2-storageclass.yaml
# 3. 创建 PVC
kubectl apply -f 3-pvc.yaml
# 4. 部署 StatefulSet
kubectl apply -f 4-statefulset.yaml
# 5. 创建 Service
kubectl apply -f 5-service.yaml
# 6. 创建 Ingress（如果需要）
kubectl apply -f 6-ingress.yaml

4.2 验证部署状态

部署完成后，检查各个资源的状态：

# 查看 StatefulSet 状态
kubectl get statefulset -n face-recognition
# 查看 Pod 状态
kubectl get pods -n face-recognition -l app=face-recognition
# 查看 PVC 状态
kubectl get pvc -n face-recognition
# 查看 Service
kubectl get svc -n face-recognition
# 查看 Pod 日志（以 face-recognition-0 为例）
kubectl logs -f face-recognition-0 -n face-recognition

正常状态下，你应该看到类似这样的输出：

NAME READY STATUS RESTARTS AGE
face-recognition-0 1/1 Running 0 2m
face-recognition-1 1/1 Running 0 1m
face-recognition-2 1/1 Running 0 30s

4.3 功能测试

部署完成后，测试服务是否正常工作：

# 方法 1：通过端口转发测试
kubectl port-forward face-recognition-0 8000:8000 -n face-recognition
# 然后在另一个终端测试
curl http://localhost:8000/health
# 预期输出：{"status": "healthy"}
# 方法 2：进入 Pod 内部测试
kubectl exec -it face-recognition-0 -n face-recognition -- bash
cd /root/Retinaface_CurricularFace
conda activate torch25
python inference_face.py

5. 生产环境优化建议

基础的部署完成了，但在生产环境中，我们还需要考虑更多优化措施。

5.1 性能优化配置

根据我的经验，以下几个配置能显著提升服务性能：

# 在 StatefulSet 的容器配置中添加
containers:
- name: face-recognition-container
  # ... 其他配置 ...
  # 性能优化配置
  lifecycle:
    postStart:
      exec:
        command: ["/bin/bash", "-c", "|"]
        # 预热模型，减少第一次推理的延迟
        python /root/Retinaface_CurricularFace/warmup.py
  # 安全上下文
  securityContext:
    capabilities:
      add: ["IPC_LOCK"] # 允许锁定内存，提升性能
    privileged: false
    readOnlyRootFilesystem: true # 增强安全性
  # 资源优化
  resources:
    limits:
      nvidia.com/gpu: 1
      memory: "12Gi" # 适当增加内存，避免 OOM
      cpu: "6"
      ephemeral-storage: "20Gi" # 临时存储限制
    requests:
      nvidia.com/gpu: 1
      memory: "8Gi"
      cpu: "4"
      ephemeral-storage: "10Gi"

5.2 监控与日志收集

生产环境必须要有完善的监控。我推荐使用以下方案：

# 7-monitoring.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: face-recognition-metrics
  namespace: face-recognition
data:
  prometheus-scrape.yaml: |
    - job_name: 'face-recognition'
      scrape_interval: 30s
      static_configs:
      - targets: ['face-recognition-0.face-recognition-service.face-recognition.svc.cluster.local:8000', 'face-recognition-1.face-recognition-service.face-recognition.svc.cluster.local:8000', 'face-recognition-2.face-recognition-service.face-recognition.svc.cluster.local:8000']
      metrics_path: '/metrics'

在推理脚本中添加指标收集：

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

# 定义指标
REQUEST_COUNT = Counter('face_recognition_requests_total', 'Total requests')
REQUEST_LATENCY = Histogram('face_recognition_request_latency_seconds', 'Request latency')
SIMILARITY_SCORE = Histogram('face_recognition_similarity_score', 'Similarity score distribution')

@app.route('/compare', methods=['POST'])
def compare_faces():
    start_time = time.time()
    REQUEST_COUNT.inc()
    # ... 处理逻辑 ...
    latency = time.time() - start_time
    REQUEST_LATENCY.observe(latency)
    SIMILARITY_SCORE.observe(similarity_score)
    return result

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

5.3 自动扩缩容配置

根据负载自动调整副本数：

# 8-hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: face-recognition-hpa
  namespace: face-recognition
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: StatefulSet
    name: face-recognition
  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
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300 # 缩容冷却时间
    policies:
    - type: Percent
      value: 10
      periodSeconds: 60

6. 常见问题与解决方案

在部署和运行过程中，你可能会遇到一些问题。这里我总结了一些常见问题及其解决方案：

6.1 GPU 相关问题

问题 1：Pod 无法调度，提示"No GPU available"

解决方案：
1. 检查节点标签：kubectl get nodes --show-labels | grep gpu
2. 给节点打标签：kubectl label nodes <node-name> accelerator=nvidia-tesla-t4
3. 安装 NVIDIA 设备插件：kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/v0.14.1/nvidia-device-plugin.yml

问题 2：CUDA 版本不匹配

解决方案：
1. 检查节点 CUDA 版本：nvidia-smi
2. 确保镜像 CUDA 版本与节点匹配
3. 如果使用官方镜像，可以指定 CUDA 版本标签

6.2 存储相关问题

问题 3：PVC 一直处于 Pending 状态

可能原因：
1. StorageClass 配置错误
2. 存储配额不足
3. 云平台存储服务异常
解决方案：
1. 检查 StorageClass：kubectl get storageclass
2. 查看 PVC 事件：kubectl describe pvc <pvc-name> -n face-recognition
3. 检查存储配额：kubectl describe quota -n face-recognition

6.3 服务发现问题

问题 4：Pod 之间无法通过 DNS 名称访问

StatefulSet 的 Pod 有固定的 DNS 名称：
face-recognition-0.face-recognition-service.face-recognition.svc.cluster.local
验证方法：
1. 进入一个 Pod：kubectl exec -it face-recognition-0 -n face-recognition -- bash
2. 测试 DNS 解析：nslookup face-recognition-1.face-recognition-service
3. 如果解析失败，检查 CoreDNS 配置和服务网络

6.4 性能优化问题

问题 5：第一次推理延迟很高

原因：模型加载和初始化需要时间
解决方案：
1. 使用 preStop 钩子延迟终止：给 Pod 足够的优雅终止时间
2. 实现模型预热：在容器启动后立即加载模型
3. 使用就绪探针延迟：确保模型完全加载后再接收流量

7. 总结与最佳实践

通过今天的教程，我们完成了一个完整的 Retinaface+CurricularFace 人脸识别模型在 Kubernetes 上的 StatefulSet 部署。让我总结一下关键要点：

7.1 为什么这套方案有效？

1. 稳定性：StatefulSet 为每个 Pod 提供稳定的网络标识和存储，适合有状态服务
2. 可扩展性：结合 HPA，可以根据负载自动扩缩容
3. 高可用：多副本部署确保服务不间断
4. 易维护：完整的监控和日志收集，便于问题排查

7.2 部署流程回顾

整个部署流程可以概括为以下几个步骤：

1. 环境准备：验证镜像功能，准备 Kubernetes 集群
2. 资源配置：创建命名空间、存储类、PVC
3. 核心部署：编写和部署 StatefulSet 配置
4. 服务暴露：创建 Service 和 Ingress
5. 验证测试：检查部署状态，测试服务功能
6. 生产优化：添加监控、日志、自动扩缩容

7.3 给你的实用建议

根据我多年的部署经验，给你几个实用建议：

对于小规模部署（< 10 QPS）：

• 从 2 个副本开始，使用 HPA 自动扩缩容
• 使用本地 SSD 存储，降低成本
• 简化监控，只关注核心指标（CPU、内存、GPU 使用率）

对于中大规模部署（10-100 QPS）：

• 使用节点亲和性，将 Pod 调度到 GPU 节点
• 实现多级缓存（内存缓存+Redis 缓存）
• 建立完整的监控告警体系

对于超大规模部署（> 100 QPS）：

• 考虑使用模型服务网格（如 KServe）
• 实现金丝雀发布和 A/B 测试
• 建立跨区域容灾方案

7.4 下一步学习方向

如果你已经成功部署了基础服务，可以考虑进一步优化：

1. 性能优化：模型量化、推理引擎优化（TensorRT）、批处理
2. 功能扩展：添加人脸库管理、实时视频流处理、多人脸检测
3. 架构升级：引入消息队列（Kafka）异步处理、实现微服务架构
4. 安全加固：添加身份认证、请求限流、数据加密

记住，技术部署从来不是一劳永逸的事情。随着业务增长和技术发展，你需要不断调整和优化你的部署方案。今天的 StatefulSet 部署方案为你提供了一个坚实的基础，你可以在这个基础上构建更强大、更稳定的人脸识别服务。