Keycloak配置LDAP用户联邦时连接测试失败，提示查看server.log报错

最高概率根因修正 #

你提到重启了Docker容器，说明Keycloak本身运行在Docker容器环境中，这个场景下最容易踩的地址错配问题：
容器内部的localhost/127.0.0.1指向的是Keycloak容器自身的网络栈，根本不是运行Apache Directory Studio的宿主机。
你在本地Apache Directory Studio能正常连接localhost:10389，是因为Studio运行在你的物理机/宿主机上，回环地址直接指向本地LDAP服务；但Keycloak容器内的回环地址没有对应的10389端口服务，自然会抛出连接失败的通用错误。

对应修正方案： #

• 如果LDAP服务运行在宿主机上，和Keycloak容器同属一台物理机：
  • Docker Desktop（Mac/Windows环境）：将Keycloak的Connection URL修改为ldap://host.docker.internal:10389
  • 原生Linux环境的Docker：bridge模式下，获取宿主机在docker0网桥上的网关地址（通常为172.17.0.1），Connection URL修改为ldap://172.17.0.1:10389；或者启动Keycloak容器时加--network host参数，让容器直接共享宿主机网络栈，此时再用localhost:10389就能正常连通
• 如果LDAP服务也运行在独立的Docker容器中：
  • 手动创建一个自定义Docker网络，把Keycloak和LDAP容器都接入该网络，直接用LDAP的容器名作为连接主机名，比如LDAP容器名为apache-ds，连接地址写ldap://apache-ds:10389即可

逐层排查流程 #

不要反复在Keycloak测试连接按钮上做无效操作，按以下顺序逐步验证：

1. 先确认网络连通性：进入Keycloak容器内部执行连通性测试
   • 终端执行docker exec -it [你的Keycloak容器名称/ID] sh进入容器shell
   • 执行nc -zv 目标LDAP地址 10389，若返回连通成功，说明网络层没问题，再去验证认证配置；若返回连接拒绝/超时，优先解决路由、端口监听的问题
2. 排查Keycloak服务端日志的具体报错
   • 界面的Test Connection只返回通用错误，真实异常都会存在Keycloak服务日志里：执行docker logs [你的Keycloak容器名称/ID]拉取最近的日志，定位LDAP连接相关的具体异常：
     • 若报Connection refused：对应网络路由不通的地址错配问题
     • 若报UnknownHostException：说明填写的主机名无法被容器解析
     • 若报SSLHandshakeException：要么是你给明文LDAP写了ldaps://开头的加密地址，要么是LDAP服务开了加密端口但你用了ldap://明文连接
     • 若报Invalid credentials：说明网络是通的，问题出在你填写的Bind DN、绑定密码不匹配
3. 确认LDAP服务的监听配置
   • 检查Apache Directory Server的监听绑定地址：如果默认绑定了127.0.0.1，会只允许本机回环的连接，外部容器无法访问，需要将绑定地址改为0.0.0.0，允许非回环地址的连接
4. 排除无效测试操作
   • 你之前尝试填写的ldap://localhost:389本身就和你实际运行的10389端口LDAP不匹配，这类测试没有参考价值

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