Keycloak生产环境端口不匹配及Istio健康检查故障排查求助

核心问题定位 #

你的问题本质是Keycloak未按生产模式预期监听8443端口，反而使用了开发模式默认的3000端口，进而导致Istio健康探针连接失败、路由规则无法匹配，最终只能通过NodePort绕过Istio访问。

常见原因与对应解决步骤 #

1. Keycloak启动参数/环境变量配置错误 #

生产模式下Keycloak默认监听8443，但如果启动时被错误参数覆盖，会切换到3000端口。

• 检查Deployment的启动参数：确保使用start --optimized（Keycloak 17+版本生产模式命令），而非start-dev（开发模式默认3000端口）；同时明确指定HTTPS端口：

  args: ["start", "--optimized", "--https-port=8443", "--hostname=your-keycloak-domain"]
  

• 清理干扰环境变量：删除Deployment中可能存在的KC_HTTP_PORT=3000，或显式设置KC_HTTPS_PORT=8443。
• 核对启动日志：如果日志出现Listening on: http://0.0.0.0:3000，直接定位到启动参数问题，按上述修正即可。

2. Dockerfile硬编码错误端口/模式 #

如果自定义了Docker镜像，检查以下点：

• 不要使用start-dev命令，不要硬编码EXPOSE 3000而忽略EXPOSE 8443；
• 正确的Dockerfile示例片段：

  FROM quay.io/keycloak/keycloak:latest
  ENV KC_MODE=production
  ENV KC_HTTPS_PORT=8443
  CMD ["start", "--optimized"]
  

3. Kubernetes Deployment与Service端口不匹配 #

• 容器端口必须映射到8443：

  containers:
  - name: keycloak
    image: your-keycloak-image
    ports:
    - containerPort: 8443
      name: https
      protocol: TCP
  

• 健康探针必须指向8443的HTTPS端点（Keycloak健康端点为/health/live和/health/ready）：

  livenessProbe:
    httpGet:
      path: /health/live
      port: https
      scheme: HTTPS
    initialDelaySeconds: 30
    periodSeconds: 10
  readinessProbe:
    httpGet:
      path: /health/ready
      port: https
      scheme: HTTPS
    initialDelaySeconds: 30
    periodSeconds: 10
  

• Service要关联容器的8443端口：

  apiVersion: v1
  kind: Service
  metadata:
    name: keycloak
  spec:
    ports:
    - port: 8443
      targetPort: https
      name: https
    selector:
      app: keycloak
  

4. Istio配置冲突修正 #

• VirtualService必须指向Service的8443端口：

  apiVersion: networking.istio.io/v1alpha3
  kind: VirtualService
  metadata:
    name: keycloak
  spec:
    hosts:
    - your-keycloak-domain
    gateways:
    - your-gateway
    http:
    - match:
      - uri:
          prefix: /
      route:
      - destination:
          host: keycloak
          port:
            number: 8443
  

• 若Istio Gateway做HTTPS终止，需将Keycloak切换为HTTP模式（设置KC_HTTP_PORT=8080，探针改用HTTP）；若由Keycloak自身提供HTTPS，Gateway需配置为PASSTHROUGH模式，避免TLS握手冲突。
• 针对Istio日志中的500错误：大概率是Keycloak未加载有效SSL证书导致启动异常，生产模式下必须提供合法证书：

  env:
  - name: KC_HTTPS_CERTIFICATE_FILE
    value: /opt/keycloak/conf/tls/tls.crt
  - name: KC_HTTPS_CERTIFICATE_KEY_FILE
    value: /opt/keycloak/conf/tls/tls.key
  volumeMounts:
  - name: tls-secret
    mountPath: /opt/keycloak/conf/tls
    readOnly: true
  volumes:
  - name: tls-secret
    secret:
      secretName: keycloak-tls
  

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