Kubernetes无法部署本地构建的FastAPI镜像task1问题排查

1. 先定位Pod的具体故障原因 #

Deployment未就绪的核心原因是Pod启动失败或健康检查不通过，先执行以下命令查看Pod状态：

kubectl get pods

如果Pod状态显示CrashLoopBackOff、ImagePullBackOff或Error，执行以下命令查看详细错误信息：

# 查看Pod启动日志
kubectl logs <你的Pod名称>
# 查看Pod的详细事件描述
kubectl describe pod <你的Pod名称>

2. 确保minikube节点能获取到本地构建的镜像 #

minikube运行在独立的虚拟机中，本地Docker构建的镜像默认不会同步到minikube的Docker环境里，这是最常见的问题之一：

• 方法一：将本地镜像加载到minikube节点

  minikube image load task1:latest
  

• 方法二：切换到minikube的Docker环境后重新构建镜像

  # 切换环境（当前终端生效，重启后需重新执行）
  eval $(minikube docker-env)
  # 重新构建镜像
  docker build -t task1:latest .
  

完成后重新部署Deployment：

kubectl apply -f task1-deployment.yaml

3. 检查FastAPI的启动配置 #

如果Pod日志显示服务启动但无法被访问，大概率是FastAPI监听的是127.0.0.1而非0.0.0.0，导致容器内部无法对外提供服务：

• 修改Dockerfile中的启动命令，确保绑定到0.0.0.0：

  CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]
  

• 重新构建镜像并同步到minikube（参考步骤2）

4. 解决本地访问问题 #

即使Pod正常运行，直接访问localhost:8080也无法连接，因为minikube是虚拟机，需要通过端口转发或Service暴露服务：

• 临时端口转发（适合调试）：

  kubectl port-forward pod/<你的Pod名称> 8080:8080
  

  执行后即可通过localhost:8080访问服务
• 长期暴露服务：创建一个Service配置文件（比如task1-service.yaml）：

  apiVersion: v1
  kind: Service
  metadata:
    name: task1-service
  spec:
    selector:
      app: task1
    ports:
      - protocol: TCP
        port: 80
        targetPort: 8080
    type: NodePort
  

  部署后执行minikube service task1-service，会自动打开浏览器访问服务

内容的提问来源于stack exchange，提问作者X HOxha