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指向对应的具体 releasehead标签由默认分支的最新 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 4ARMv8.0-A与 Jetson AGX Xavier/OrinARMv8.2-A 但缺 RCpcDocker 版本要求自 ClickHouse 24.11 起Ubuntu 镜像改用ubuntu:22.04作为基础镜像要求 Docker 版本不低于20.10.10含对应 seccomp 补丁。若无法升级 Docker可用docker run --security-opt seccompunconfined作为临时规避方案但存在安全影响不推荐生产使用。2. 快速启动与连接2.1 启动一个服务实例docker run -d --name some-clickhouse-server --ulimit nofile262144:262144 clickhouse/clickhouse-server要点--ulimit nofile262144:262144将进程文件描述符上限提升到 262144ClickHouse 处理大量并发连接与文件时需要较宽的 fd 限制默认情况下ClickHouse 仅能通过 Docker 网络访问见下文网络一节默认使用无密码的default用户运行。2.2 使用原生客户端连接docker run -it --rm --networkcontainer:some-clickhouse-server --entrypoint clickhouse-client clickhouse/clickhouse-server # 或者 docker exec -it some-clickhouse-server clickhouse-client第一种方式复用服务容器的网络命名空间直接以clickhouse-client作为 entrypoint 进入交互式客户端第二种方式直接在已运行容器内 exec。两种方式本质都是走 9000 端口的 nativeTCP协议。2.3 使用 curl 通过 HTTP 接口连接echo SELECT Hello, ClickHouse! | docker run -i --rm --networkcontainer: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-server3. 网络模型端口映射与 default 用户的安全边界3.1 通过映射端口对外暴露docker run -d -p 18123:8123 -p 19000:9000 -e CLICKHOUSE_PASSWORDchangeme --name some-clickhouse-server --ulimit nofile262144:262144 clickhouse/clickhouse-server echo SELECT version() | curl http://localhost:18123/?passwordchangeme --data-binary -3.2 使用 host 网络docker run -d --networkhost --name some-clickhouse-server --ulimit nofile262144:262144 clickhouse/clickhouse-server echo SELECT version() | curl http://localhost:8123/ --data-binary ---networkhost让容器直接使用宿主机端口8123/9000同时可获得更好的网络性能。3.3default用户的网络访问控制重要文档中有一个关键安全约定预定义用户default默认不具备网络访问权限除非为其设置了密码。这一点在 entrypoint.sh 的manage_clickhouse_user函数中有完整实现若设置了CLICKHOUSE_USER非default、CLICKHOUSE_PASSWORD或CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENTentrypoint 会向/etc/clickhouse-server/users.d/default-user.xml写入配置删除内置default用户default removeremove创建新用户并授予networksip::/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_SETUP1 -p 9000:9000/tcp clickhouse/clickhouse-serverCLICKHOUSE_SKIP_USER_SETUP1会跳过 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 nofile262144: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-addSYS_NICE --cap-addNET_ADMIN --cap-addIPC_LOCK \ --name some-clickhouse-server --ulimit nofile262144:262144 clickhouse/clickhouse-server三个 capability 的典型用途SYS_NICE允许调整进程 nice value影响线程优先级策略IPC_LOCK允许mlock锁定内存页常用于避免内存被换出以稳定低延迟查询NET_ADMIN网络相关高级操作如绑定某些网络配置所需。6. 配置自定义 config、自定义用户、root 启动容器默认暴露 8123HTTP 接口与 9000native 客户端端口。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_host0.0.0.0/listen_host listen_try1/listen_try /clickhouse这正是容器内服务默认能接受跨容器连接的原因。6.1 使用自定义配置文件启动docker run -d --name some-clickhouse-server --ulimit nofile262144:262144 -v /path/to/your/config.xml:/etc/clickhouse-server/config.xml clickhouse/clickhouse-server6.2 以自定义用户运行本地目录挂载场景# $PWD/data/clickhouse should exist and be owned by current user docker run --rm --user ${UID}:${GID} --name some-clickhouse-server --ulimit nofile262144: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、跳过 chownentrypoint.sh。Dockerfile 特意以固定 uid/gid101 预创建clickhouse用户正是因为 rootless 容器无法 chown挂载卷的属主需要外部自行设置。6.3 以 root 身份启动用户命名空间场景docker run --rm -e CLICKHOUSE_RUN_AS_ROOT1 --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_ROOT1后entrypoint.sh 会令USER0 GROUP0以 root 运行服务端并跳过 chown。6.4 启动时创建默认数据库与用户使用环境变量CLICKHOUSE_DB、CLICKHOUSE_USER、CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT、CLICKHOUSE_PASSWORDdocker run --rm -e CLICKHOUSE_DBmy_database -e CLICKHOUSE_USERusername -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT1 -e CLICKHOUSE_PASSWORDpassword -p 9000:9000/tcp clickhouse/clickhouse-server从源码看各变量的具体行为变量默认值作用CLICKHOUSE_DB空初始化阶段执行CREATE DATABASE IF NOT EXISTS $CLICKHOUSE_DBentrypoint.shCLICKHOUSE_USERdefault自定义业务用户名非default时触发用户改写entrypoint.shCLICKHOUSE_PASSWORD空新用户的密码也可通过CLICKHOUSE_PASSWORD_FILE指向的文件读取entrypoint.shCLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT0写入新用户配置中的access_management置 1 表示允许 SQL 级访问管理CLICKHOUSE_SKIP_USER_SETUP0置 1 时完全跳过default用户的安全限制改写CLICKHOUSE_CONFIG/etc/clickhouse-server/config.xml主配置文件路径CLICKHOUSE_RUN_AS_ROOT0置 1 时以 root 运行并禁用 chownCLICKHOUSE_INIT_TIMEOUT1000初始化阶段等待服务端就绪的最大重试次数每次间隔 1 秒见 entrypoint.shCLICKHOUSE_ALWAYS_RUN_INITDB_SCRIPTS空非空时即使数据目录已存在数据库也强制重跑初始化脚本CLICKHOUSE_WATCHDOG_ENABLE0容器场景容器启动时默认关闭 watchdogentrypoint.sh7. 扩展镜像/docker-entrypoint-initdb.d初始化脚本要对基于该镜像的派生镜像做额外初始化在/docker-entrypoint-initdb.d下放置一个或多个*.sql、*.sql.gz或*.sh脚本即可。entrypoint 在调用initdb阶段会先临时以--listen_host127.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; EOSQL8. 镜像构建方式补充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/debstable通道通过 GPG key3a9ea1193a97b548be1457d48919f6bd2b48d754校验签名后安装Dockerfile。仓库中 README.sh 展示了文档的生成流程本文章的骨架来源content.md与 license 拼接后经sed替换%%IMAGE%%占位符为clickhouse/clickhouse-server生成最终 README.md。9. 小结日常启动牢记三要素--ulimit nofile262144: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），仅供参考
