ClickHouse 26.x Docker Compose 部署指南

目标：使用 Docker Compose 部署单节点 ClickHouse 26.9（官方镜像 clickhouse/clickhouse-server:26.9，实测 26.9.3.38），含数据/日志持久化、配置挂载、健康检查、环境变量用户管理，并给出等价 docker run 命令。本文档已在 /opt/data/ops/clickhouse 目录实测通过（容器 clickhouse-26-x，端口 18123/19000）。

环境信息

Docker 版本：Docker Engine 29.4.1（Compose v2）
镜像版本：clickhouse/clickhouse-server:26.9（实测 ClickHouse 26.9.3.38，与 latest 一致）
容器名称：clickhouse-26-x
端口映射：宿主机 18123 → 容器 8123（HTTP）、宿主机 19000 → 容器 9000（native TCP）
数据目录：宿主机 /opt/data/ops/clickhouse/data → 容器 /var/lib/clickhouse（实测重启后数据保留）
日志目录：宿主机 /opt/data/ops/clickhouse/log → 容器 /var/log/clickhouse-server
配置目录：宿主机 /opt/data/ops/clickhouse/conf/{config.d,users.d} → 容器对应目录（自动 include）
部署文件：/opt/data/ops/clickhouse/docker-compose.yaml

镜像选型说明

镜像标签	对应版本	说明
`clickhouse/clickhouse-server:latest`	26.9.3.38（实测）	最新稳定版
`clickhouse/clickhouse-server:26.9`	26.9.3.38（实测）	26.9 系列 tag，随小版本更新，推荐
`clickhouse/clickhouse-server:26.8`	26.8.x	上一代 26.x LTS 线
`clickhouse/clickhouse-server:24.8`	24.8.x	老 LTS 线（生产存量环境）

⚠️ 镜像源说明：本次实测 docker.io 直拉成功。若直拉失败可换 m.daocloud.io/docker.io/clickhouse/clickhouse-server:26.9 加速。

前置条件

Docker Engine + Compose 插件
已规划数据/日志/配置目录（/opt/data/ops/clickhouse/{data,log,conf}）
内存 ≥ 2GB（实测限制 2GB 可正常启动）
端口 18123/19000 未被占用

部署步骤

步骤 1. 创建目录与配置文件

mkdir -p /opt/data/ops/clickhouse/{data,log,conf/config.d,conf/users.d}

💡 命令解释：{data,log,...} 为 shell 大括号展开，一次创建多个目录。data/log 分别持久化数据与日志，conf 下挂载 config.d（服务器配置覆盖）与 users.d（用户配置覆盖）。

创建 /opt/data/ops/clickhouse/conf/config.d/00-listen.xml（关键，见常见问题 1）：

<clickhouse>
    <!-- 26.x 官方镜像默认只监听 127.0.0.1/::1（本机回环），宿主机端口映射无法访问！
         必须显式开放监听（生产注意用防火墙/安全组收敛来源） -->
    <listen_host>0.0.0.0</listen_host>
    <listen_try>1</listen_try>
</clickhouse>

创建 /opt/data/ops/clickhouse/conf/config.d/01-memory.xml：

<clickhouse>
    <!-- 服务器级内存上限：2GB（实测容器可正常启动） -->
    <max_server_memory_usage>2147483648</max_server_memory_usage>
    <!-- MergeTree 引擎默认参数覆盖（与 system.merge_tree_settings 对应） -->
    <merge_tree>
        <parts_to_throw_insert>3000</parts_to_throw_insert>
        <parts_to_delay_insert>1000</parts_to_delay_insert>
        <index_granularity>8192</index_granularity>
    </merge_tree>
</clickhouse>

创建 /opt/data/ops/clickhouse/conf/users.d/01-app-user.xml：

<clickhouse>
    <users>
        <!-- 业务用户 app：生产环境务必把 password 替换为强密码（生成方式见文档 1 配置说明） -->
        <app>
            <!-- 明文密码占位 -->
            <password>CHANGE_ME_TO_A_STRONG_PASSWORD</password>
            <!-- 允许来源：::/0 表示所有来源（生产建议收敛为具体网段） -->
            <networks>
                <ip>::/0</ip>
            </networks>
            <profile>default</profile>
            <quota>default</quota>
        </app>
    </users>
</clickhouse>

💡 说明：config.d/users.d 下的文件会被 ClickHouse 启动时自动 include 合并到主配置，无需改主配置；修改后 docker compose restart clickhouse 生效。

步骤 2. 编写 docker-compose.yaml

# =============================================================================
# ClickHouse 26.x（实测 26.9.3.38）Docker Compose 部署文件（单节点）
# 镜像版本：clickhouse/clickhouse-server:26.9
# 使用方式：cd /opt/data/ops/clickhouse && docker compose up -d
# 默认配置：镜像自带 /etc/clickhouse-server/config.xml（监听 0.0.0.0:8123/9000），
#           额外配置放 ./conf/config.d 与 ./conf/users.d（启动时自动合并加载）
# =============================================================================

services:
  clickhouse:
    # 镜像版本：官方稳定版镜像（latest 实测 = 26.9.3.38；直拉失败可用 m.daocloud.io/docker.io/clickhouse/clickhouse-server:26.9 加速）
    image: clickhouse/clickhouse-server:26.9

    # 容器名称，方便 docker ps / docker logs 定位
    container_name: clickhouse-26-x

    # 重启策略：容器异常退出时自动重启（除非手动 stop）
    restart: unless-stopped

    # ---- 环境变量 ----
    # CLICKHOUSE_USER/CLICKHOUSE_PASSWORD：官方镜像 26.x 的 entrypoint 会据此生成 users.d 配置，
    # 创建该用户并放开其网络访问（::/0）；不设置时 default 用户仅限容器本机访问（宿主机连不上，实测踩坑）
    environment:
      - TZ=Asia/Shanghai                      # 容器时区（与宿主机一致）
      - CLICKHOUSE_USER=admin                 # 管理用户（entrypoint 自动创建）
      - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-CHANGE_ME_TO_A_STRONG_PASSWORD}  # 管理用户密码（生产务必修改）

    # ---- 端口映射：宿主机18123 -> 容器8123（HTTP 接口），宿主机19000 -> 容器9000（native TCP）----
    ports:
      - "18123:8123"
      - "19000:9000"

    # ---- 数据持久化（重要）----
    # ./data 为宿主机数据目录，重启容器数据不丢失
    volumes:
      - ./data:/var/lib/clickhouse
      # ---- 日志持久化 ----
      # ./log 为宿主机日志目录（clickhouse-server.log / .err.log）
      - ./log:/var/log/clickhouse-server
      # ---- 配置挂载（可选）----
      # config.d / users.d 会被 ClickHouse 启动时自动 include，修改后 docker compose restart clickhouse 生效
      - ./conf/config.d:/etc/clickhouse-server/config.d
      - ./conf/users.d:/etc/clickhouse-server/users.d

    # ---- 健康检查：HTTP 接口 /ping 返回 Ok. 即认为就绪 ----
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8123/ping"]
      interval: 10s      # 每 10 秒检查一次
      timeout: 5s        # 单次检查超时
      retries: 10        # 连续 10 次失败视为不健康
      start_period: 30s  # 启动后 30 秒才开始检查

    # 容器日志大小限制，防止磁盘被日志占满
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "3"

💡 命令解释：CLICKHOUSE_USER/CLICKHOUSE_PASSWORD 是 26.x 官方镜像 entrypoint 的用户管理开关（实测见常见问题 2）；healthcheck 用 wget --spider http://localhost:8123/ping（镜像内无 curl，实测 wget 可用）；logging max-size 50m + max-file 3 限制容器 json 日志体积。

步骤 3. 启动并验证

cd /opt/data/ops/clickhouse
docker compose up -d
docker compose ps

实测输出：

 Network clickhouse_default Creating
 Network clickhouse_default Created
 Container clickhouse-26-x Creating
 Container clickhouse-26-x Created
 Container clickhouse-26-x Starting
 Container clickhouse-26-x Started
NAME              IMAGE                               COMMAND            SERVICE      CREATED         STATUS                   PORTS
clickhouse-26-x   clickhouse/clickhouse-server:26.9   "/entrypoint.sh"   clickhouse   6 seconds ago   Up 5 seconds (healthy)   9009/tcp, 0.0.0.0:18123->8123/tcp, [::]:18123->8123/tcp, 0.0.0.0:19000->9000/tcp, [::]:19000->9000/tcp

💡 说明：容器启动约 5 秒即进入 healthy（wget /ping 通过）；日志确认 Merging configuration file '/etc/clickhouse-server/config.d/01-memory.xml'.，说明挂载配置已合并生效。

宿主机侧访问验证：

curl -s http://127.0.0.1:18123/ping
curl -s -u admin:CHANGE_ME_TO_A_STRONG_PASSWORD "http://127.0.0.1:18123/?query=SELECT%20version()"
docker exec clickhouse-26-x clickhouse-client -u admin --password CHANGE_ME_TO_A_STRONG_PASSWORD -q "SELECT version(), currentDatabase()"

实测输出：

Ok.
26.9.3.38
26.9.3.38       default

💡 说明：/ping 无需认证返回 Ok.；带 -u admin --password ... 访问 HTTP 与 native 均成功；容器内默认库为 default。

验证业务用户（users.d 生效）与配置覆盖（内存参数生效）：

docker exec clickhouse-26-x clickhouse-client --user app --password CHANGE_ME_TO_A_STRONG_PASSWORD -q "SELECT 1 AS ok"
docker exec clickhouse-26-x clickhouse-client -q "SELECT name, value FROM system.server_settings WHERE name='max_server_memory_usage'"

实测输出：

1
max_server_memory_usage 2147483648

步骤 4. 数据持久化实测（重启容器数据保留）

docker exec clickhouse-26-x clickhouse-client -u admin --password CHANGE_ME_TO_A_STRONG_PASSWORD \
  -q "CREATE DATABASE IF NOT EXISTS demo; CREATE TABLE IF NOT EXISTS demo.sensor (ts DateTime, sensor_id UInt32, value Float64) ENGINE = MergeTree ORDER BY ts; INSERT INTO demo.sensor VALUES (now(), 1, 23.5), (now(), 2, 45.1), (now(), 1, 26.8); SELECT count() FROM demo.sensor"
docker restart clickhouse-26-x
docker exec clickhouse-26-x clickhouse-client -u admin --password CHANGE_ME_TO_A_STRONG_PASSWORD \
  -q "SELECT count() AS rows, round(avg(value),2) AS avg_value FROM demo.sensor"

实测输出：

3
3       31.8

💡 说明：重启前写入 3 行（avg 31.8），重启后数据完整保留——./data:/var/lib/clickhouse 挂载持久化生效，宿主机 data/ 目录下可见 store/、metadata/ 等真实数据文件。

等价 docker run 命令

docker run -d --name clickhouse-26-x \
  --restart unless-stopped \
  -e TZ=Asia/Shanghai \
  -e CLICKHOUSE_USER=admin \
  -e CLICKHOUSE_PASSWORD=CHANGE_ME_TO_A_STRONG_PASSWORD \
  -p 18123:8123 -p 19000:9000 \
  -v /opt/data/ops/clickhouse/data:/var/lib/clickhouse \
  -v /opt/data/ops/clickhouse/log:/var/log/clickhouse-server \
  -v /opt/data/ops/clickhouse/conf/config.d:/etc/clickhouse-server/config.d \
  -v /opt/data/ops/clickhouse/conf/users.d:/etc/clickhouse-server/users.d \
  --health-cmd "wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1" \
  --health-interval 10s --health-timeout 5s --health-retries 10 --health-start-period 30s \
  clickhouse/clickhouse-server:26.9

💡 命令解释：-e 传环境变量；-p 端口映射；-v 卷挂载；--health-* 与 compose 的 healthcheck 等价；--restart unless-stopped 等价于 compose restart 策略。实测：用同一 data 目录跑 docker run（容器 clickhouse-26-x-docker-run），15 秒内 healthy、/ping 返回 Ok.、demo 库 4 行数据完整读取——与 compose 完全等价。

配置说明

服务器级参数（listen_host、max_server_memory_usage、merge_tree）→ conf/config.d/*.xml
用户/权限（密码、networks、profile、quota）→ conf/users.d/*.xml
修改后：docker compose restart clickhouse（无需重建容器）
需要重建的场景：修改 ports/volumes/environment 时 → docker compose up -d --force-recreate

注意事项

26.x 镜像默认只监听回环地址，必须挂载 config.d 开放 listen_host（或依赖 CLICKHOUSE_USER/PASSWORD 分支行为，见常见问题 1/2）
不设置 CLICKHOUSE_USER/CLICKHOUSE_PASSWORD 时，default 用户仅限容器本机访问，宿主机 HTTP 报 Connection reset by peer、native 报 Connection refused（实测）
生产密码不要用占位值：export CLICKHOUSE_PASSWORD='强密码' 后 compose 自动读取（${CLICKHOUSE_PASSWORD:-...} 语法）
容器内无 curl（镜像精简），healthcheck/调试用 wget
数据目录被占用时不要直接删除，先 docker compose down（保留容器可用 docker compose stop）

常见问题

问题 1：宿主机访问 18123/19000 失败（HTTP reset / native refused）

原因： 26.x 官方镜像的 config.xml 默认 listen_host 只有 127.0.0.1/::1，且镜像内不再内置旧版 docker_related_config.xml（实测确认），容器内服务只监听回环，端口映射后连接被拒。

解决： 挂载 conf/config.d/00-listen.xml（<listen_host>0.0.0.0</listen_host>）后重启：

docker compose restart clickhouse
curl -s http://127.0.0.1:18123/ping   # 预期 Ok.

问题 2：不设环境变量时 default 用户宿主机连不上，或报 `Authentication failed: password is incorrect`

原因： entrypoint 逻辑实测：未设置 CLICKHOUSE_USER/CLICKHOUSE_PASSWORD 时，自动生成 users.d/default-user.xml 把 default 限制为仅本机（::1/127.0.0.1）；若手动挂载的 users.d 覆盖与它冲突，可能出现"需要密码"的认证失败。

解决： 按官方推荐设置环境变量（自动创建 admin 用户并允许 ::/0）：

environment:
  - CLICKHOUSE_USER=admin
  - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-CHANGE_ME_TO_A_STRONG_PASSWORD}

问题 3：HTTP POST 插入报 `Cannot parse input: expected '('` 或 `Expected ',' after the value`

原因： INSERT INTO t VALUES 的 POST body 必须按 VALUES 元组语法书写，4,99.9（无括号）或不匹配列数均报语法错误。

解决： 按表列数带括号提交（实测 demo.sensor 3 列）：

curl -s -u admin:CHANGE_ME_TO_A_STRONG_PASSWORD -X POST \
  -d "(now(), 4, 99.9)" "http://127.0.0.1:18123/?query=INSERT%20INTO%20demo.sensor%20VALUES"

问题 4：挂载 users.d 后 default 用户行为异常

原因： entrypoint 生成的 default-user.xml 与手动挂载的 users.d 文件同时生效，XML 合并行为可能不符合直觉（实测发生过）。

解决： 用户管理统一走环境变量（CLICKHOUSE_USER/PASSWORD），users.d 只放额外业务用户，避免重复定义 default。

卸载方式

cd /opt/data/ops/clickhouse
docker compose stop        # 停止（保留容器与数据）
# 彻底清理（删除容器与数据）：
docker compose down -v
rm -rf /opt/data/ops/clickhouse/data /opt/data/ops/clickhouse/log

💡 说明：down -v 会删除命名卷与网络，但本项目数据在 bind mount（./data），需手动删除；删除前确认数据已备份。

参考链接

官方 Docker 镜像：https://hub.docker.com/r/clickhouse/clickhouse-server
Docker 部署文档：https://clickhouse.com/docs/install/docker
镜像 entrypoint（用户初始化逻辑）：https://github.com/ClickHouse/ClickHouse/blob/master/docker/server/entrypoint.sh
配置参考：https://clickhouse.com/docs/operations/server-configuration-parameters/settings

本文档由 www.quzuo.net 平台开发

ClickHouse 26.x Docker Compose 部署指南

ClickHouse 26.x Docker Compose 部署指南

环境信息

镜像选型说明

前置条件

部署步骤

步骤 1. 创建目录与配置文件

步骤 2. 编写 docker-compose.yaml

步骤 3. 启动并验证

步骤 4. 数据持久化实测（重启容器数据保留）

等价 docker run 命令

配置说明

注意事项

常见问题

问题 1：宿主机访问 18123/19000 失败（HTTP reset / native refused）

问题 2：不设环境变量时 default 用户宿主机连不上，或报 Authentication failed: password is incorrect

问题 3：HTTP POST 插入报 Cannot parse input: expected '(' 或 Expected ',' after the value

问题 4：挂载 users.d 后 default 用户行为异常

卸载方式

参考链接

问题 2：不设环境变量时 default 用户宿主机连不上，或报 `Authentication failed: password is incorrect`

问题 3：HTTP POST 插入报 `Cannot parse input: expected '('` 或 `Expected ',' after the value`