本地Keycloak连接Mailhog发邮件报错：连接被拒绝

核心原因：容器网络隔离 #

容器内的localhost、127.0.0.1指向容器自身，而非宿主机；如果Keycloak和Mailhog不在同一Docker网络，用容器名也无法互相访问。

具体排查与修复步骤 #

1. 确认Docker Compose网络配置

   • 确保两个容器处于同一网络（Docker Compose默认会创建default网络，显式定义更清晰）。检查你的docker-compose.yml，示例配置如下：

     version: '3.8'
     services:
       keycloak:
         image: quay.io/keycloak/keycloak:latest
         # 其他配置（端口、环境变量等）
         networks:
           - app-network
       mailhog:
         image: mailhog/mailhog:latest
         ports:
           - "1025:1025" # SMTP端口映射
           - "8025:8025" # Web管理界面端口
         networks:
           - app-network
     networks:
       app-network:
         driver: bridge
     

   • 若未指定网络，Docker Compose会自动生成默认网络，此时直接用Mailhog的服务名（即docker-compose.yml里的mailhog字段）即可被Keycloak解析。

2. 修正Keycloak的SMTP配置

   • 主机名填写Mailhog的服务名（比如mailhog），端口填1025；Mailhog默认无需用户名/密码，留空即可。
   • 绝对不要用localhost/127.0.0.1——Keycloak容器内的localhost指向自身，根本访问不到Mailhog容器。

3. 验证容器间网络连通性

   • 进入Keycloak容器，测试能否ping通Mailhog服务名：

     docker exec -it <你的Keycloak容器ID> ping mailhog
     

   • 如果ping不通，检查网络是否正确关联，或服务名拼写是否有误。

4. 检查Mailhog监听状态

   • 查看Mailhog日志，确认它在0.0.0.0:1025监听（默认就是此配置），日志里会有类似内容：

     [SMTP] Binding to address: 0.0.0.0:1025

   • 若日志显示监听其他地址，需调整Mailhog的启动参数。

5. 排除宿主机端口冲突

   • 确认宿主机1025端口未被其他进程占用，Linux用netstat -tulpn | grep 1025，Windows用netstat -ano | findstr :1025检查。

常见错误点提醒 #

• 混淆容器内端口与宿主机映射端口：Keycloak容器内访问Mailhog用1025，和宿主机映射端口一致是巧合，若映射其他端口，容器内仍用Mailhog本身的1025端口。
• 错误使用network_mode: host：虽然此模式下Keycloak能用localhost访问宿主机的Mailhog，但会破坏容器隔离性，不推荐使用。

内容的提问来源于stack exchange，提问作者Johannes M.