问题描述

部署 LLaMa-Factory 的 llamafactory-cli webui 时，Pod 资源无法正常启动或 WebUI 无法访问，可能涉及资源配置不足、端口配置错误或环境变量缺失。

常见原因与排查方法

资源配额不足

• 现象：Pod 处于 Pending 或 CrashLoopBackOff 状态，日志显示 OOMKilled 或 CPUThrottling。
• 解决：调整 resources 配置，确保足够的内存和 CPU。示例配置：

  resources:
    limits:
      cpu: "4"
      memory: "16Gi"
    requests:
      cpu: "2"
      memory: "8Gi"
  

端口配置错误

• 现象：Pod 运行但无法访问 WebUI，日志显示端口冲突或无监听。
• 解决：
  1. 检查 webui 默认端口（通常为 7860），在容器中确认服务是否监听：

     kubectl exec <pod-name> -- netstat -tuln | grep 7860
     

  2. 确保 Service 或 Ingress 正确暴露端口：

     ports:
       - protocol: TCP
         port: 80
         targetPort: 7860
     

环境变量缺失

• 现象：Pod 启动失败，日志提示缺少必要参数（如 MODEL_NAME 或 API_KEY）。
• 解决：在 Deployment 中补充环境变量：

  env:
    - name: MODEL_NAME
      value: "llama-2-7b"
    - name: HF_TOKEN
      valueFrom:
        secretKeyRef:
          name: hf-secret
          key: token
  

高级调试步骤

检查日志与事件

1. 获取 Pod 日志：

   kubectl logs <pod-name> --tail=100
   

2. 查看 Pod 事件：

   kubectl describe pod <pod-name>
   

调整存活探针
若服务启动较慢，需延长 livenessProbe 的初始延迟：

livenessProbe:
  httpGet:
    path: /
    port: 7860
  initialDelaySeconds: 60
  periodSeconds: 10

存储卷权限问题
若使用持久化存储，确保挂载目录可写：

volumeMounts:
  - mountPath: /data
    name: storage
volumes:
  - name: storage
    persistentVolumeClaim:
      claimName: llamafactory-pvc

参考配置示例

以下为完整的 Deployment 片段（需替换占位符）：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: llamafactory-webui
spec:
  replicas: 1
  selector:
    matchLabels:
      app: llamafactory-webui
  template:
    metadata:
      labels:
        app: llamafactory-webui
    spec:
      containers:
        - name: webui
          image: llamafactory/llamafactory-cli:latest
          command: ["llamafactory-cli", "webui"]
          ports:
            - containerPort: 7860
          env:
            - name: MODEL_NAME
              value: "llama-2-7b"
          resources:
            limits:
              memory: "16Gi"
              cpu: "4"
            requests:
              memory: "8Gi"
              cpu: "2"