如何为本地Keycloak 21实例配置TLS证书启用HTTPS访问？

问题背景 #

本地通过Docker Compose部署Keycloak 21.0.0实例，计划配置TLS证书将访问地址从http://localhost:8081切换到https://localhost:8843，使用Let's Encrypt生成的本地证书localhostcert.pem和localhostkey.pem挂载到容器中，但HTTP端口可正常访问，HTTPS端口8843无法打开页面。

当前使用的docker-compose配置如下：

services:
  keycloak:
    image: quay.io/keycloak/keycloak:21.0.0
    command: start-dev
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=admin
      - KC_HTTPS_CERTIFICATE_FILE=/opt/keycloak/demo/certs/localhostcert.pem
      - KC_HTTPS_CERTIFICATE_KEY_FILE=/opt/keycloak/demo/certs/localhostkey.pem
    ports:
      - 8081:8080
      - 8843:8843
    volumes: 
       - type: bind
         source: ./keycloak-restrict-client-auth.jar
         target: /opt/keycloak/providers/keycloak-restrict-client-auth.jar
       - ./certs:/opt/keycloak/demo/certs

问题排查与解决方案 #

• 修正端口映射配置
  Keycloak默认HTTPS端口是8443，当前配置中容器内未监听8843端口，导致端口映射无效。两种修改方式：

  1. 调整端口映射为8843:8443，修改后的ports段：

     ports:
       - 8081:8080
       - 8843:8443
     

  2. 通过环境变量指定容器内HTTPS端口为8843，添加到environment中：

     - KC_HTTPS_PORT=8843
     

• 检查证书权限与格式

  • 确保容器内Keycloak进程能读取证书文件，本地执行chmod 644 ./certs/*修改权限，再重新启动容器。
  • 验证证书格式：用openssl x509 -in localhostcert.pem -text检查证书有效性，openssl rsa -in localhostkey.pem -check确认私钥未加密（Keycloak无法读取带密码的私钥）。

• 查看启动日志定位错误
  执行docker-compose logs keycloak查看容器日志，搜索HTTPS相关信息，若存在证书加载失败、权限报错等内容，根据日志提示修复问题。

• 排查本地网络与防火墙

  • Ubuntu系统下，执行ufw status检查防火墙规则，若8843端口未开放，执行ufw allow 8843/tcp添加放行规则。
  • 本地用curl -v https://localhost:8843或telnet localhost 8843测试端口连通性，确认端口是否正常监听。

• 确认证书域名匹配
  Let's Encrypt默认不签发localhost域名的证书，若为自签证书，需确保证书的Subject或Subject Alternative Name包含localhost，执行openssl x509 -in localhostcert.pem -noout -subject -ext subjectAltName检查域名是否匹配。

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