ClickHouse-go连接Docker容器时TLS握手错误的解决方案

在使用ClickHouse-go客户端库连接Docker容器中的ClickHouse服务时，开发者可能会遇到"first record does not look like a TLS handshake"的错误。这个问题通常是由于端口配置不当导致的协议不匹配。

问题背景

ClickHouse服务在Docker容器中默认会监听多个端口，每个端口对应不同的通信协议：

• 8123端口：HTTP协议接口
• 9000端口：原生TCP协议接口
• 9440端口：安全的TCP协议接口(TLS加密)

当开发者使用ClickHouse-go客户端库时，默认会尝试使用原生TCP协议(9000端口)建立连接。如果在Docker配置中只暴露了8123端口(HTTP)，但客户端代码却尝试使用TCP协议连接，就会出现协议不匹配的错误。

解决方案

方案一：使用正确的TCP协议端口

最简单的解决方案是在Docker配置中同时暴露9000端口，并确保客户端代码连接到这个端口：

version: '3'

services:
  click_server:
    image: clickhouse/clickhouse-server
    ports:
      - "8123:8123"  # HTTP接口
      - "9000:9000"  # 原生TCP接口
    volumes:
      - ./dbfiles:/var/lib/clickhouse
      - ./config/houseadmin.xml:/etc/clickhouse-server/users.d/houseadmin.xml

然后在Go代码中指定9000端口连接，并移除不必要的TLS配置：

conn, err = clickhouse.Open(&clickhouse.Options{
    Addr: []string{"host:9000"},  // 使用9000端口
    Auth: clickhouse.Auth{
        Database: "database",
        Username: "user",
        Password: "password",
    },
    // 移除TLS配置
})

方案二：配置安全的TCP连接

如果需要加密连接，可以配置ClickHouse使用9440安全端口：

1. 创建配置文件tcp_secure.xml：

<clickhouse>
    <tcp_secure>9440</tcp_secure>
</clickhouse>

2. 修改Docker配置挂载此文件并暴露9440端口：

volumes:
  - ./tcp_secure.xml:/etc/clickhouse-server/config.d/tcp_secure.xml
ports:
  - "9440:9440"

3. Go代码中配置TLS连接9440端口：

conn, err = clickhouse.Open(&clickhouse.Options{
    Addr: []string{"host:9440"},
    TLS: &tls.Config{
        InsecureSkipVerify: true,  // 仅测试环境使用
    },
    // 其他配置...
})

方案三：使用HTTP协议连接

也可以选择直接使用HTTP协议连接8123端口，但这需要使用HTTP客户端而非原生TCP客户端。

最佳实践建议

1. 开发环境建议使用方案一，简单直接
2. 生产环境建议使用方案二，确保通信安全
3. 避免在代码中保留InsecureSkipVerify: true，生产环境应配置有效的证书
4. 确保Docker端口映射与客户端连接端口一致
5. 使用环境变量管理连接配置，便于不同环境切换

通过正确理解ClickHouse的端口协议对应关系，并合理配置Docker和客户端代码，可以轻松解决TLS握手错误问题，建立稳定的数据库连接。