Docker容器连接IPv6 Postgres数据库遇UnknownHostException求助

核心问题定位 #

你遇到的java.net.UnknownHostException和java.net.SocketException: Protocol family unavailable，本质是Docker默认未启用IPv6支持，导致容器内无法通过IPv6协议访问外部服务，和应用本身（Keycloak/Spring Boot/Quarkus）的配置无关。

分步解决方案 #

1. 开启Docker全局IPv6支持 #

修改Docker daemon配置文件（路径通常为/etc/docker/daemon.json，不存在则新建），添加以下配置：

{
  "ipv6": true,
  "fixed-cidr-v6": "fd00:dead:beef::/48",
  "ip6tables": true
}

• ipv6: 启用Docker的IPv6功能
• fixed-cidr-v6: 为Docker分配私有IPv6网段（可自定义，只要不与现有网络冲突）
• ip6tables: 启用IPv6防火墙规则，保证网络连通性

修改完成后重启Docker服务：

systemctl restart docker

2. 启动容器时启用IPv6 #

方式一：使用默认网络启动

直接添加--ipv6参数开启容器的IPv6支持，以Keycloak为例：

docker run -d \
  --name keycloak \
  --ipv6 \
  -e JAVA_OPTS="-Djava.net.preferIPv6Addresses=true" \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:20.0.1 start-dev

方式二：使用自定义IPv6网络

先创建支持IPv6的自定义网络：

docker network create --ipv6 --subnet fd00:dead:beef::/48 my-ipv6-net

再将容器加入该网络启动：

docker run -d \
  --name keycloak \
  --network my-ipv6-net \
  -e JAVA_OPTS="-Djava.net.preferIPv6Addresses=true" \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:20.0.1 start-dev

3. 验证网络连通性 #

进入容器内部，测试是否能ping通Postgres的IPv6地址：

docker exec -it keycloak ping6 <你的Postgres IPv6地址>

如果ping通，说明网络层面配置正常；如果不通，检查以下两点：

• Postgres的postgresql.conf中，listen_addresses是否包含::（允许IPv6监听）
• 主机防火墙是否开放了Postgres端口（5432）的IPv6入站规则

4. 修正数据库连接URL #

应用连接IPv6数据库时，URL中的IPv6地址需要用方括号包裹，以Postgres JDBC连接为例：

jdbc:postgresql://[<Postgres IPv6地址>]:5432/数据库名

Docker Compose 配置补充 #

如果使用Docker Compose编排服务，需要在docker-compose.yml中添加IPv6支持：

version: '3.8'
services:
  keycloak:
    image: quay.io/keycloak/keycloak:20.0.1
    environment:
      JAVA_OPTS: "-Djava.net.preferIPv6Addresses=true"
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    networks:
      - ipv6-net
    command: start-dev

networks:
  ipv6-net:
    enable_ipv6: true
    ipam:
      config:
        - subnet: fd00:dead:beef::/48

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