Docker环境中ClickHouse无法与Node.js连接的问题排查

操作回顾 #

• 已拉取ClickHouse官方Docker镜像
• 用host网络模式启动容器：

docker run --network=host --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server

• 通过docker exec -it some-clickhouse-server clickhouse-client成功连接，客户端显示连接到localhost:9000

遇到的问题 #

1. 浏览器访问8123（HTTP默认端口）和9000端口都无法连接
2. Node.js客户端连接报错（代码如下）：

const { ClickHouse } = require("clickhouse");
const clickhouse = new ClickHouse({
  url: "http://localhost",
  port: 9000,
});

错误信息：

Error inserting row: Error: connect ECONNREFUSED ::1:9000
    at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1532:16) {
  errno: -61,
  code: 'ECONNREFUSED',
  syscall: 'connect',
  address: '::1',
  port: 9000
}

问题原因及解决办法 #

1. 端口用错了！ #

9000是ClickHouse的原生TCP协议端口，仅用于clickhouse-client这类原生客户端连接；HTTP接口默认用的是8123端口，你Node.js代码里写9000本身就不对，先把端口改成8123试试。

2. ClickHouse默认只绑定本地回环地址 #

即使Docker用了host网络，默认情况下ClickHouse可能只监听容器内的127.0.0.1，主机的localhost和容器的localhost不是同一个（除非明确让ClickHouse监听所有IP）。

解决方式：

• 启动容器时添加环境变量，强制ClickHouse监听所有IP：

docker run --network=host --name some-clickhouse-server --ulimit nofile=262144:262144 -e CLICKHOUSE_LISTEN_HOST=0.0.0.0 clickhouse/clickhouse-server

• 或者进入容器修改/etc/clickhouse-server/config.xml，找到<listen_host>节点，改成<listen_host>0.0.0.0</listen_host>，然后重启容器。

3. IPv6连接失败 #

报错里显示连接的是::1（IPv6的localhost），可能是ClickHouse没开启IPv6支持，或者主机IPv6配置有问题。

解决方式：

• Node.js代码里改用IPv4地址：

const clickhouse = new ClickHouse({
  url: "http://127.0.0.1",
  port: 8123,
});

• 或者在ClickHouse配置里添加IPv6监听，在config.xml里加一行<listen_host>::</listen_host>。

4. 防火墙拦截 #

检查主机的防火墙（比如ufw、iptables），确保8123端口没有被拦截，放行该端口的入站请求。

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