ClickHouse 官方 Docker 镜像完全指南：启动、配置、用户管理与初始化脚本实战-开发者社区

ClickHouse 官方 Docker 镜像完全指南：启动、配置、用户管理与初始化脚本实战

【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse

本文基于 ClickHouse 仓库中docker/server/目录下的官方 Docker 镜像使用文档（README.src/content.md）编写。内容覆盖镜像版本体系与架构兼容性要求、启动服务实例、客户端与 HTTP 接口连接、端口映射与网络模型、数据持久化挂载、Linux capabilities 可选增强、配置覆盖、用户/密码/数据库环境变量的完整行为，以及通过/docker-entrypoint-initdb.d扩展镜像做初始化的全部实操。读完后你可以直接使用 Dockerfile 构建的clickhouse/clickhouse-server镜像在生产或开发环境部署 ClickHouse，并理解 entrypoint.sh 在容器启动时做了哪些事。

1. 镜像版本体系与硬件兼容性

1.1 版本标签（Tags）

官方镜像的标签规则如下：

latest标签指向最新稳定分支的最新 release；
分支标签如22.2指向对应分支的最新 release；
完整版本标签如22.2.3和22.2.3.5指向对应的具体 release；
head标签由默认分支的最新 commit 构建（非稳定版本，仅用于跟踪主干）；
每个标签都可选-alpine后缀，表示基于 Alpine Linux 构建（对应 Dockerfile.alpine）。

除了默认 Ubuntu 基础镜像和 Alpine 变体外，仓库中还提供 Dockerfile.distroless，用于构建无 shell、无包管理器的精简安全镜像，其 entrypoint 直接复用编译后的clickhouse docker-init子命令（对应 programs/docker-init 程序）。

1.2 硬件兼容性要求

从源码构建体系看，ClickHouse 对 SIMD 指令集有硬性依赖，因此在拉取镜像前需确认目标硬件：

amd64 镜像：要求 CPU 支持 x86-64-v3 微架构级别，即 AVX2、BMI1、BMI2、F16C、FMA、LZCNT、MOVBE、XSAVE 指令集。2015 年之后的绝大多数 x86 CPU 均满足该要求；
arm64 镜像：要求 ARMv8.2-A 架构，并额外要求 Load-Acquire RCpc 寄存器（该寄存器在 ARMv8.2-A 中为可选、在 ARMv8.3-A 中为强制）。AWS Graviton ≥2、Azure 和 GCP 实例均受支持；典型不支持的设备包括 Raspberry Pi 4（ARMv8.0-A）与 Jetson AGX Xavier/Orin（ARMv8.2-A 但缺 RCpc）；
Docker 版本要求：自 ClickHouse 24.11 起，Ubuntu 镜像改用ubuntu:22.04作为基础镜像，要求 Docker 版本不低于20.10.10（含对应 seccomp 补丁）。若无法升级 Docker，可用docker run --security-opt seccomp=unconfined作为临时规避方案，但存在安全影响，不推荐生产使用。

2. 快速启动与连接

2.1 启动一个服务实例

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

要点：

--ulimit nofile=262144:262144将进程文件描述符上限提升到 262144，ClickHouse 处理大量并发连接与文件时需要较宽的 fd 限制；
默认情况下，ClickHouse 仅能通过 Docker 网络访问（见下文网络一节）；
默认使用无密码的default用户运行。

2.2 使用原生客户端连接

docker run -it --rm --network=container:some-clickhouse-server --entrypoint clickhouse-client clickhouse/clickhouse-server # 或者 docker exec -it some-clickhouse-server clickhouse-client

第一种方式复用服务容器的网络命名空间，直接以clickhouse-client作为 entrypoint 进入交互式客户端；第二种方式直接在已运行容器内 exec。两种方式本质都是走 9000 端口的 native（TCP）协议。

2.3 使用 curl 通过 HTTP 接口连接

echo "SELECT 'Hello, ClickHouse!'" | docker run -i --rm --network=container:some-clickhouse-server buildpack-deps:curl curl 'http://localhost:8123/?query=' -s --data-binary @-

HTTP 接口（8123 端口）是 ClickHouse 最常用的接入方式，可直接以 POST body 传 SQL。

2.4 停止与删除容器

docker stop some-clickhouse-server docker rm some-clickhouse-server

3. 网络模型：端口映射与 default 用户的安全边界

3.1 通过映射端口对外暴露

docker run -d -p 18123:8123 -p 19000:9000 -e CLICKHOUSE_PASSWORD=changeme --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server echo 'SELECT version()' | curl 'http://localhost:18123/?password=changeme' --data-binary @-

3.2 使用 host 网络

docker run -d --network=host --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server echo 'SELECT version()' | curl 'http://localhost:8123/' --data-binary @-

--network=host让容器直接使用宿主机端口（8123/9000），同时可获得更好的网络性能。

3.3`default`用户的网络访问控制（重要）

文档中有一个关键安全约定：预定义用户default默认不具备网络访问权限，除非为其设置了密码。这一点在 entrypoint.sh 的manage_clickhouse_user函数中有完整实现：

若设置了CLICKHOUSE_USER（非default）、CLICKHOUSE_PASSWORD或CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT，entrypoint 会向/etc/clickhouse-server/users.d/default-user.xml写入配置：删除内置default用户（<default remove="remove">），创建新用户并授予<networks><ip>::/0</ip></networks>全网段访问；
若以上变量均未设置且未手动修改过default用户定义，entrypoint 会写入限制配置，将default的<networks>收敛为仅::1与127.0.0.1——即仅允许容器内本地连接；
entrypoint 还会通过clickhouse extract-from-config提取原始与合并后配置中users.default的 sha256 摘要进行比对，若发现用户已通过挂载文件自行修改了default用户，则保持原样、不做覆盖（见 entrypoint.sh）。

因此上例中"host 网络下default用户仅对 localhost 请求可用"的备注，正是这条默认行为导致的。如需让default用户无密码可远程访问（不安全，仅建议本地调试），可设置：

docker run --rm -e CLICKHOUSE_SKIP_USER_SETUP=1 -p 9000:9000/tcp clickhouse/clickhouse-server

CLICKHOUSE_SKIP_USER_SETUP=1会跳过 entrypoint 的全部用户改写逻辑。

4. 数据持久化：挂载 Volumes

为获得持久化，通常需要挂载以下目录：

/var/lib/clickhouse/—— ClickHouse 存放数据的主目录；
/var/log/clickhouse-server/—— 日志目录。

docker run -d \ -v "$PWD/ch_data:/var/lib/clickhouse/" \ -v "$PWD/ch_logs:/var/log/clickhouse-server/" \ --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server

此外还可挂载：

/etc/clickhouse-server/config.d/*.xml—— 服务端配置调整文件；
/etc/clickhouse-server/users.d/*.xml—— 用户设置调整文件；
/docker-entrypoint-initdb.d/—— 数据库初始化脚本目录（见第 7 节）。

源码层面值得注意的两点：

Dockerfile 中VOLUME /var/lib/clickhouse已声明数据目录为匿名卷，docker run不带-v时数据仍保存在容器内卷中，容器删除后不保证保留；
entrypoint 启动时会调用clickhouse extract-from-config从配置中解析出path、tmp_path、user_files_path、logger.log、logger.errorlog、format_schema_path以及所有storage_configuration.disks.*.path/metadata_path（见 entrypoint.sh），并对这些目录逐个mkdir -p与chown，所以即使你在配置中自定义了磁盘路径，容器启动时也会自动创建并修正属主。该解析依赖 programs/extract-from-config 独立程序实现。

5. Linux Capabilities（可选增强）

ClickHouse 的部分高级功能需要启用若干 Linux capabilities，均为可选项，可通过 docker 命令行参数开启：

docker run -d \ --cap-add=SYS_NICE --cap-add=NET_ADMIN --cap-add=IPC_LOCK \ --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server

三个 capability 的典型用途：

SYS_NICE：允许调整进程 nice value，影响线程优先级策略；
IPC_LOCK：允许mlock锁定内存页，常用于避免内存被换出以稳定低延迟查询；
NET_ADMIN：网络相关高级操作（如绑定某些网络配置）所需。

6. 配置：自定义 config、自定义用户、root 启动

容器默认暴露 8123（HTTP 接口）与 9000（native 客户端端口）。ClickHouse 的主配置为config.xml，容器内默认为/etc/clickhouse-server/config.xml（由 Dockerfile 中ENV CLICKHOUSE_CONFIG=/etc/clickhouse-server/config.xml设定，可用环境变量CLICKHOUSE_CONFIG覆盖）。镜像还预置了 docker_related_config.xml，其内容是让服务监听通配地址：

<clickhouse> <!-- Listen wildcard address to allow accepting connections from other containers and host network. --> <listen_host>::</listen_host> <listen_host>0.0.0.0</listen_host> <listen_try>1</listen_try> </clickhouse>

这正是容器内服务默认能接受跨容器连接的原因。

6.1 使用自定义配置文件启动

docker run -d --name some-clickhouse-server --ulimit nofile=262144:262144 -v /path/to/your/config.xml:/etc/clickhouse-server/config.xml clickhouse/clickhouse-server

6.2 以自定义用户运行（本地目录挂载场景）

# $PWD/data/clickhouse should exist and be owned by current user docker run --rm --user "${UID}:${GID}" --name some-clickhouse-server --ulimit nofile=262144:262144 -v "$PWD/logs/clickhouse:/var/log/clickhouse-server" -v "$PWD/data/clickhouse:/var/lib/clickhouse" clickhouse/clickhouse-server

使用本地目录挂载时，容器内需要以与宿主机属主一致的 uid/gid 运行，否则目录无法写入。对应地，entrypoint 检测到当前非 root 运行时会把DO_CHOWN置 0、跳过 chown（entrypoint.sh）。Dockerfile 特意以固定 uid/gid=101 预创建clickhouse用户，正是因为 rootless 容器无法 chown，挂载卷的属主需要外部自行设置。

6.3 以 root 身份启动（用户命名空间场景）

docker run --rm -e CLICKHOUSE_RUN_AS_ROOT=1 --name clickhouse-server-userns -v "$PWD/logs/clickhouse:/var/log/clickhouse-server" -v "$PWD/data/clickhouse:/var/lib/clickhouse" clickhouse/clickhouse-server

启用用户命名空间（user namespace）时容器内 uid 映射会变化，entrypoint 的 chown 逻辑可能失败；设置CLICKHOUSE_RUN_AS_ROOT=1后，entrypoint.sh 会令USER=0 GROUP=0，以 root 运行服务端并跳过 chown。

6.4 启动时创建默认数据库与用户

使用环境变量CLICKHOUSE_DB、CLICKHOUSE_USER、CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT、CLICKHOUSE_PASSWORD：

docker run --rm -e CLICKHOUSE_DB=my_database -e CLICKHOUSE_USER=username -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 -e CLICKHOUSE_PASSWORD=password -p 9000:9000/tcp clickhouse/clickhouse-server

从源码看，各变量的具体行为：

变量	默认值	作用
`CLICKHOUSE_DB`	空	初始化阶段执行`CREATE DATABASE IF NOT EXISTS $CLICKHOUSE_DB`（entrypoint.sh）
`CLICKHOUSE_USER`	`default`	自定义业务用户名；非`default`时触发用户改写（entrypoint.sh）
`CLICKHOUSE_PASSWORD`	空	新用户的密码；也可通过`CLICKHOUSE_PASSWORD_FILE`指向的文件读取（entrypoint.sh）
`CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT`	`0`	写入新用户配置中的`<access_management>`，置 1 表示允许 SQL 级访问管理
`CLICKHOUSE_SKIP_USER_SETUP`	`0`	置 1 时完全跳过`default`用户的安全限制改写
`CLICKHOUSE_CONFIG`	`/etc/clickhouse-server/config.xml`	主配置文件路径
`CLICKHOUSE_RUN_AS_ROOT`	`0`	置 1 时以 root 运行并禁用 chown
`CLICKHOUSE_INIT_TIMEOUT`	`1000`	初始化阶段等待服务端就绪的最大重试次数（每次间隔 1 秒，见 entrypoint.sh）
`CLICKHOUSE_ALWAYS_RUN_INITDB_SCRIPTS`	空	非空时即使数据目录已存在数据库也强制重跑初始化脚本
`CLICKHOUSE_WATCHDOG_ENABLE`	`0`（容器场景）	容器启动时默认关闭 watchdog（entrypoint.sh）

7. 扩展镜像：`/docker-entrypoint-initdb.d`初始化脚本

要对基于该镜像的派生镜像做额外初始化，在/docker-entrypoint-initdb.d下放置一个或多个*.sql、*.sql.gz或*.sh脚本即可。entrypoint 在调用initdb阶段会：

先临时以--listen_host=127.0.0.1启动clickhouse-server（仅监听本地，防止初始化期间被外部访问），并通过http://127.0.0.1:$HTTP_PORT/ping轮询等待就绪；
若设置了CLICKHOUSE_DB，先创建该数据库；
依次执行/docker-entrypoint-initdb.d/中的文件：可执行的*.sh直接运行、不可执行的*.sh以 source 方式加载、*.sql交给clickhouse-client --multiquery执行、*.sql.gz先gunzip -c再执行，其余文件忽略（entrypoint.sh）；
完成后向临时服务进程发送 SIGTERM 退出，再exec正式启动服务。

初始化使用的连接凭证即CLICKHOUSE_USER与CLICKHOUSE_PASSWORD，这两个环境变量在初始化阶段会被传给clickhouse-client。另外，初始化只在数据目录为空（$DATA_DIR/data不存在）时执行；如果检测到已有数据库，会打印 "ClickHouse Database directory appears to contain a database; Skipping initialization" 并跳过（entrypoint.sh）。

文档给出的标准示例——在/docker-entrypoint-initdb.d/init-db.sh中添加用户库表：

#!/bin/bash set -e clickhouse client -n <<-EOSQL CREATE DATABASE docker; CREATE TABLE docker.docker (x Int32) ENGINE = Log; EOSQL

8. 镜像构建方式补充

Dockerfile 支持三种安装路径，便于 CI 与离线构建：

ARG deb_location_url：从指定 URL 拉取clickhouse-client/clickhouse-server/clickhouse-common-static三个 deb 包安装（CI 构建产物的典型用法）；
ARG DIRECT_DOWNLOAD_URLS：从预定义的多个 deb 直链下载；
ARG single_binary_location_url：从单个二进制 URL 安装（用于 sanitizer 版本、非标准构建）；
若以上均未设置，则回退到官方 apt 仓库（packages.clickhouse.com/deb，stable通道），通过 GPG key3a9ea1193a97b548be1457d48919f6bd2b48d754校验签名后安装（Dockerfile）。

仓库中 README.sh 展示了文档的生成流程：本文章的骨架来源content.md与 license 拼接后经sed替换%%IMAGE%%占位符为clickhouse/clickhouse-server，生成最终 README.md。

9. 小结

日常启动牢记三要素：--ulimit nofile=262144:262144、数据/日志卷挂载、通过CLICKHOUSE_PASSWORD等环境变量完成身份初始化；
网络暴露前先理解default用户默认只能本地访问的安全设计，按需设置CLICKHOUSE_SKIP_USER_SETUP或创建独立用户；
配置修改优先走config.d/*.xml增量挂载，而不是整体替换config.xml；
需要高级性能特性时通过--cap-add授予SYS_NICE、NET_ADMIN、IPC_LOCK；
任何"首次启动要建库建表"的需求都交给/docker-entrypoint-initdb.d，并理解它只在空数据目录或显式设置CLICKHOUSE_ALWAYS_RUN_INITDB_SCRIPTS时才会执行。

【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

ClickHouse 官方 Docker 镜像完全指南：启动、配置、用户管理与初始化脚本实战