无法连接ClickHouse容器：迁移报错Could not resolve host问题排查

环境信息 #

Docker Compose配置（ClickHouse容器） #

clickhouse-server:
    image: yandex/clickhouse-server
    container_name: clickhouse-server
    ports:
        - '8123:8123'
        - '9000:9000'
    volumes:
        - ./db:/var/lib/clickhouse
    ulimits:
        nofile: 262144

连接参数（.env文件） #

CLICKHOUSE_HOST=clickhouse-server
CLICKHOUSE_PORT=8123
CLICKHOUSE_DATABASE=memorial_analitucs
CLICKHOUSE_USERNAME=default
CLICKHOUSE_PASSWORD=
CLICKHOUSE_TIMEOUT_CONNECT=5
CLICKHOUSE_TIMEOUT_QUERY=5

报错信息 #

执行数据库迁移时触发错误：

2024_04_18_182025_create_analytics_table ............................................................................................ 3,710ms FAIL

  ClickHouseDB\Exception\QueryException 

  Could not resolve host: clickhouse-server

备注：直接访问http://localhost:8123显示“OK”，说明ClickHouse服务本身运行正常。

排查方向与解决方案 #

• 网络隔离导致无法解析容器名
  Docker默认会为每个Compose项目创建独立网络，只有同网络内的容器才能通过容器名互相访问。如果执行迁移的进程（应用/迁移工具）运行在宿主机上，或者不在ClickHouse容器的网络内，就会无法解析clickhouse-server。
  • 解决：若迁移工具在宿主机运行，将.env中的CLICKHOUSE_HOST改为localhost；若迁移工具是另一个容器，确保它与ClickHouse容器加入同一个Docker网络（可通过Compose将两者放在同一配置文件，或手动添加网络）。
• DNS缓存异常
  宿主机或容器内的DNS缓存可能导致解析失败，尝试重启执行迁移的进程/容器，或手动刷新DNS缓存。
• 容器名拼写核对
  再次确认.env中的CLICKHOUSE_HOST值与容器名clickhouse-server完全一致（当前配置无拼写错误，但需排除手动输入失误）。
• Docker网络配置问题
  执行docker inspect clickhouse-server查看Networks字段，确认容器网络配置正常；若存在网络异常，尝试重启Docker服务修复。

内容的提问来源于stack exchange，提问作者Андрей Двойкин