在Minikube中部署含自定义SPI的Keycloak无法通过端口转发访问

问题现象 #

• 包含自定义SPI的Keycloak镜像在本地Docker容器运行正常
• 部署到Minikube后，执行kubectl port-forward <pod-name> 8080:8080时出现连接拒绝错误
• kubectl describe pod <pod-name>显示容器端口（Ports）和主机端口（Host Ports）均为NONE

排查与解决步骤 #

1. 确认Pod内Keycloak是否正常监听8080端口 #

先进入Pod内部，验证服务是否真的在运行并监听正确端口：

kubectl exec -it <pod-name> -- /bin/bash
# 检查端口监听状态
netstat -tulpn | grep 8080
# 或用ss命令替代（部分容器无netstat）
ss -tulpn | grep 8080
# 本地访问测试
curl http://localhost:8080

如果没有监听记录或curl失败，说明Keycloak未正常启动，查看启动日志排查问题：

kubectl logs <pod-name>

重点检查SPI加载是否报错、启动脚本是否执行异常。

2. 修正Dockerfile的启动命令配置 #

你的Dockerfile修改了ENTRYPOINT为/usr/bin/env，可能干扰了原Keycloak镜像的启动流程：

# 原Dockerfile
FROM jboss/keycloak:latest
ADD common-keycloak-spi-0.1.jar /opt/jboss/keycloak/standalone/deployments/
ENTRYPOINT ["/usr/bin/env"]
CMD ["sh","/opt/jboss/tools/docker-entrypoint.sh"]

jboss/keycloak镜像默认的ENTRYPOINT就是/opt/jboss/tools/docker-entrypoint.sh，无需用/usr/bin/env包裹。修改Dockerfile为：

FROM jboss/keycloak:latest
ADD common-keycloak-spi-0.1.jar /opt/jboss/keycloak/standalone/deployments/
# 保留原镜像启动流程，无需自定义ENTRYPOINT/CMD

重新构建镜像并部署到Minikube，验证问题是否解决。

3. 确保Deployment正确配置容器端口 #

检查你的Deployment YAML文件，确认容器端口已正确声明：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: keycloak-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: keycloak
  template:
    metadata:
      labels:
        app: keycloak
    spec:
      containers:
      - name: keycloak
        image: your-custom-keycloak-image:tag
        ports:
        - containerPort: 8080  # 必须声明此端口，否则kubectl describe会显示NONE
          protocol: TCP
        env:
        - name: KEYCLOAK_USER
          value: "admin"
        - name: KEYCLOAK_PASSWORD
          value: "admin"

添加containerPort:8080后，kubectl describe pod会显示正确的端口信息，同时确保Keycloak启动时监听0.0.0.0（默认配置，若SPI有修改需额外确认）。

4. 验证Minikube网络配置 #

如果以上步骤都没问题，检查Minikube的网络状态：

minikube status
minikube tunnel  # 若需要将服务暴露到外部网络可执行此命令

确认Minikube节点正常运行，端口转发功能未被防火墙或网络策略拦截。

内容的提问来源于stack exchange，提问作者Vipul Tiwari