本文基于 library/clickhouse:26.5.5.8 官方镜像LinuxUbuntu 24.04环境Compose 配置与验证命令可直接复用。旧 CPU / 虚拟机阉割指令集时会启动失败见文中 CPU 说明与 FAQ。业务日志、埋点、指标堆成山用传统行存库做聚合又慢又贵ClickHouse是开源列式 OLAP 数据库——专为实时分析设计单机即可扛住大规模写入与聚合查询数据落在你自己的服务器上。本文用 轩辕镜像 加速在 Linux 上以Docker Compose 单容器跑通 ClickHouse固定标签26.5.5.8、数据/日志持久化、设置密码以开放网络访问再用HTTP8123、内置Play页面与clickhouse-client9000验证最后建表示例。镜像页见 library/clickhouse。一、ClickHouse 是什么ClickHouse是开源的列式数据库管理系统DBMS面向联机分析处理OLAP可用 SQL 实时做聚合与报表。相对传统行存数据库分析类查询通常快一到三个数量级适合日志分析、业务监控、埋点与数仓场景。能力说明列式存储扫列不扫行聚合、过滤更省 IOSQL标准 SQL 风格查询生态驱动丰富吞吐单机可处理海量行级写入与查询自托管Docker 官方镜像即可单节点跑通典型使用场景应用 / 访问日志集中查询与统计实时指标与漏斗、留存类分析与 Grafana 等可视化工具对接HTTP 或原生协议架构示意本文单节点curl / SDK ──HTTP:8123──▶ ClickHouse 容器 clickhouse-client ──Native:9000──▶ 同上 ./data ──▶ /var/lib/clickhouse数据 ./logs ──▶ /var/log/clickhouse-server日志部署前必看 CPU官方 amd64 镜像依赖较新的 CPU 指令集。宿主机或虚拟机若没有 SSE4.2较新版本还倾向要求x86-64-v3 / AVX2容器会不断重启。详见§二与§七 FAQ。二、环境要求项目建议操作系统Linux x86_64本文以Ubuntu 24.04为例DockerDocker Engine Compose V2docker compose内存建议 ≥2 GB可用分析负载再加CPU必须支持 SSE4.2当前官方 amd64 发行更偏向x86-64-v3含 AVX2 等磁盘≥ 2 GB镜像约数百 MB1 GB 级 数据增长端口8123HTTP、9000原生协议工作目录/data/clickhouse独立目录可与/data/elk等并列验证 Dockerdocker--versiondockercompose version若尚未安装 Docker可使用轩辕镜像一键脚本bash(wget-qO- https://xuanyuan.cloud/docker.sh)更多见 轩辕镜像使用手册。2.1 部署前自检 CPU强烈建议grep-osse4_2/proc/cpuinfo|head-1||echoSSE4.2 NOT foundgrep-oavx2/proc/cpuinfo|head-1||echoAVX2 NOT foundlscpu|grep-EModel name|Flags|Hypervisor结果说明有sse4_2最好还有avx2可继续拉取与启动本文 ComposeSSE4.2 NOT found不要硬启动官方镜像会报指令集检查失败并Restarting。请换支持 SSE4.2 的机器或把虚拟机 CPU 改为host / 透传后再试实测对照在一台无 SSE4.2的 Ubuntu 24.04 上docker compose up -d后容器状态为Restarting (1)日志反复出现Instruction check fail. The CPU does not support SSE4.2 instruction set.此时改密码、改端口、加cap_add均无效。官方 Docker Hub 的library/clickhouse没有面向老 CPU 的amd64compat类标签可降级只能换机或打开虚拟机指令集透传。三、拉取镜像本文固定标签26.5.5.8版本可复现。生产环境也可按 标签列表 锁定其它小版本不建议生产长期用裸latest。dockerpull docker.xuanyuan.run/library/clickhouse:26.5.5.8完整输出示例26.5.5.8: Pulling from library/clickhouse d6834b4a794c: Pull complete e157edf0dcc9: Pull complete 4abec04979fc: Pull complete ddeb76a8062c: Pull complete 430f5f983823: Pull complete 999829a9d4af: Pull complete a2c9618c1f0b: Pull complete 761bc9ffbe9f: Pull complete Digest: sha256:709afe0ea57d8ae72d44c272ecd61b507e1aea476f657016fc0d94f2a6da449d Status: Downloaded newer image for docker.xuanyuan.run/library/clickhouse:26.5.5.8 docker.xuanyuan.run/library/clickhouse:26.5.5.8国内建议全程使用docker.xuanyuan.run。需登录轩辕仓库时见 登录认证说明。四、Docker Compose 部署4.1 创建目录与监听配置mkdir-p/data/clickhouse/{data,logs,config.d,users.d}cd/data/clickhouse容器内常默认尝试监听 IPv6 的[::1]许多 Docker 环境未启用 IPv6日志会出现Listen [::1]:8123 failed结果HTTP 8123 从宿主机访问被 Connection reset而docker exec里的 client走容器回环 9000仍可能正常。部署前写入监听配置cat/data/clickhouse/config.d/listen.xmlEOF ?xml version1.0? clickhouse !-- 仅 IPv4Docker 端口映射需监听 0.0.0.0勿只绑 127.0.0.1 -- listen_host0.0.0.0/listen_host /clickhouse EOF4.2 编写 docker-compose.ymlvimdocker-compose.yml内容services:clickhouse:image:docker.xuanyuan.run/library/clickhouse:26.5.5.8container_name:clickhouserestart:unless-stoppedports:-8123:8123-9000:9000environment:CLICKHOUSE_DB:analyticsCLICKHOUSE_USER:defaultCLICKHOUSE_PASSWORD:Changeme_CH_2026CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT:1ulimits:nofile:soft:262144hard:262144volumes:-./data:/var/lib/clickhouse-./logs:/var/log/clickhouse-server-./config.d:/etc/clickhouse-server/config.d-./users.d:/etc/clickhouse-server/users.d配置项说明CLICKHOUSE_PASSWORD必填若要从网络访问。未设密码时default用户默认禁止网络访问CLICKHOUSE_DBanalytics启动时创建业务库CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT1启用访问控制相关初始化ulimits.nofile官方建议的文件描述符上限./data→/var/lib/clickhouse数据持久化./logs→/var/log/clickhouse-server日志持久化config.d/listen.xmllisten_host0.0.0.0避免 IPv6/::1监听失败导致宿主机 HTTP 重置请将Changeme_CH_2026换成你自己的强密码下文验证命令中的密码需同步修改。勿将弱口令暴露到公网。4.3 启动dockercompose up-ddockercomposepsdockerlogs clickhouse--tail50期望STATUS为Up不是Restarting。日志中可见创建用户、创建库analytics一类提示例如/entrypoint.sh: create new user default instead default ... /entrypoint.sh: create database analytics可用下面确认错误日志里不再刷Listen [::1]:8123 faileddockerexecclickhousegrep-EListen \[::1\]|Application: Ready/var/log/clickhouse-server/clickhouse-server.err.log|tail-20若一上来就是Restarting且日志刷 SSE4.2先docker compose down回到§2.1处理 CPU不要空耗磁盘写日志。五、验证与使用5.1 HTTP 接口8123在系统 Shell中执行不要在clickhouse-client交互提示符里粘贴 curlechoSELECT version()|curl-sS\http://127.0.0.1:8123/?userdefaultpasswordChangeme_CH_2026\--data-binary -期望输出类似26.5.5.8指定业务库echoSHOW TABLES|curl-sS\http://127.0.0.1:8123/?databaseanalyticsuserdefaultpasswordChangeme_CH_2026\--data-binary -局域网其它机器访问时把127.0.0.1换成服务器 IP并放行防火墙8123/9000。5.2 浏览器 Play推荐容器就绪后浏览器打开把 IP 换成你的服务器http://服务器IP:8123/play首次进入为深色 SQL 编辑器右上角填写user/password中间空白处写 SQL点黄色Run或Ctrl/CmdEnter。图 1Play 初始页http://服务器IP:8123/play右上角填写账号密码务必使用与 Compose 中CLICKHOUSE_PASSWORD完全一致的密码。密码错误或未填时会出现Code: 516/AUTHENTICATION_FAILED图 2密码不正确时的 Code 516 报错核对docker-compose.yml中的CLICKHOUSE_PASSWORD后重试填写正确后右上角会显示版本如v26.5.5.8与用户default。先跑连通性查询SELECTversion(),currentDatabase();图 3认证成功后查询版本与当前库结果为26.5.5.8/default再确认业务库是否已由环境变量创建SHOWDATABASES;列表中应能看到analytics以及default、system等图 4SHOW DATABASES可见analytics与CLICKHOUSE_DB对应5.3 原生客户端容器内单条查询dockerexec-itclickhouse clickhouse-client\--userdefault--passwordChangeme_CH_2026\-qSELECT version(), currentDatabase()期望类似26.5.5.8 default交互进入dockerexec-itclickhouse clickhouse-client\--userdefault--passwordChangeme_CH_2026进入后提示符类似容器短ID :)只输入 SQL例如SELECTversion();退出输入exit或按CtrlD回到系统 Shell 后再跑curl/docker命令。5.4 建表冒烟可用 client 批量执行dockerexec-itclickhouse clickhouse-client\--userdefault--passwordChangeme_CH_2026-n-EOSQL CREATE TABLE IF NOT EXISTS analytics.events ( ts DateTime, msg String ) ENGINE MergeTree ORDER BY ts; INSERT INTO analytics.events VALUES (now(), hello clickhouse); SELECT * FROM analytics.events; EOSQL也可在Play中分步执行适合跟截图对照CREATETABLEIFNOTEXISTSanalytics.events(tsDateTime,msg String)ENGINEMergeTreeORDERBYts;INSERTINTOanalytics.eventsVALUES(now(),hello from play);SELECT*FROManalytics.eventsORDERBYtsDESCLIMIT10;查询成功时可见写入的行例如msg hello from play图 5查询analytics.events确认建表与插入成功5.5 连接信息一览项值HTTP / Playhttp://服务器IP:8123·http://服务器IP:8123/playNative服务器IP:9000用户default密码与 Compose 中CLICKHOUSE_PASSWORD一致库analytics已创建或default数据目录/data/clickhouse/data日志目录/data/clickhouse/logsPlay 为内置简易 SQL 页若打不开仍可用 curl 与clickhouse-client。认证失败时优先核对密码勿与空密码或其它服务口令混用。六、日常运维cd/data/clickhousedockercomposepsdockercompose logs-f--tail100dockercompose restartdockercompose down# 停止保留 ./data ./logsdockercompose up-d# 再启动升级小版本改image标签 →docker compose pull docker compose up -d。升级前建议备份/data/clickhouse/data。等价docker run无 Compose 时可用参数与上文一致dockerrun-d\--nameclickhouse\--restartunless-stopped\--ulimitnofile262144:262144\-p8123:8123-p9000:9000\-eCLICKHOUSE_DBanalytics\-eCLICKHOUSE_USERdefault\-eCLICKHOUSE_PASSWORDChangeme_CH_2026\-eCLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT1\-v/data/clickhouse/data:/var/lib/clickhouse\-v/data/clickhouse/logs:/var/log/clickhouse-server\docker.xuanyuan.run/library/clickhouse:26.5.5.8七、FAQQ容器一直Restarting日志里是Instruction check fail. The CPU does not support SSE4.2A宿主机/虚拟机未暴露 SSE4.2。官方library/clickhouse无法在这种 CPU 上运行。请grep sse4_2 /proc/cpuinfo确认虚拟机把 CPU 类型改为host / passthrough后重启系统再up或换一台支持 SSE4.2更好有 AVX2的机器。不要指望换镜像小版本标签绕过——Docker Official Image 侧没有面向「无 SSE4.2」的兼容标签。Q为何必须设置CLICKHOUSE_PASSWORDA官方镜像在未配置用户密码等相关变量时default用户禁止网络访问。只映射8123/9000而不设密码外连会失败。CLICKHOUSE_SKIP_USER_SETUP1仅适合本地极不安全的试验生产勿用。QPlay 报Code: 516/Authentication failedA右上角password与CLICKHOUSE_PASSWORD不一致或未填。见图 2。用grep CLICKHOUSE_PASSWORD docker-compose.yml核对后重填也可用clickhouse-client --password … -q SELECT 1交叉验证。Qcurl粘贴后报Syntax error: failed at position 1 (echo)A你还在clickhouse-client交互里提示符带:)。先exit回到系统 Shell再执行 curl。QHTTP 刚启动时curl无输出A等几秒后再试或先看docker logs clickhouse是否已完成初始化也可用clickhouse-client -q SELECT version()交叉验证。Q8123 和 9000 有什么区别A8123是 HTTP 接口curl、多数 SDK、部分 BI9000是原生协议官方clickhouse-client、部分驱动。单节点两个都映射即可。Q本机curl 127.0.0.1:8123报Connection reset by peer但docker exec … clickhouse-client正常A看错误日志是否有Listen [::1]:8123 failed: … Cannot assign requested address容器未启用 IPv6 时默认去绑[::1]会失败HTTP 未正确监听在0.0.0.0Docker 端口映射进来的连接会被重置而容器内走127.0.0.1:9000的 client 仍可用。处理catconfig.d/listen.xmlEOF ?xml version1.0? clickhouse listen_host0.0.0.0/listen_host /clickhouse EOFdockercompose restart然后再测curl -sS http://127.0.0.1:8123/play与带密码的SELECT version()。Q本机 curl 已通局域网浏览器访问http://服务器IP:8123/play却「连接已重置」A按下面顺序查多数是防火墙或端口未对外宿主机确认容器Up且映射为0.0.0.0:8123-8123docker compose ps/docker port clickhouse。在跑 ClickHouse 的机器上先确认本机curl http://127.0.0.1:8123/play成功再用局域网 IP 自测。放行防火墙Ubuntu 示例sudo ufw allow 8123/tcp sudo ufw reload云主机还需在安全组放行 8123。从访问端先测通端口curl -v http://服务器IP:8123/若这里就 RESET/超时与/play无关。Compose 不要写成127.0.0.1:8123:8123只绑回环则外网不可达。Q数据会丢吗A挂载了./data→/var/lib/clickhouse后docker compose down不会删数据。只有手工清空./data或换空目录才会丢。Q和 Elastic / MySQL 怎么选AClickHouse 擅长分析型聚合与宽表扫描全文检索与业务事务型负载仍更适合 Elasticsearch / 传统 OLTP。可按场景并存。八、命令速查# 拉取dockerpull docker.xuanyuan.run/library/clickhouse:26.5.5.8# 启动 / 状态 / 日志cd/data/clickhousedockercompose up-ddockercomposepsdockerlogs clickhouse--tail50# HTTP 验证echoSELECT version()|curl-sS\http://127.0.0.1:8123/?userdefaultpasswordChangeme_CH_2026--data-binary -# 客户端验证dockerexec-itclickhouse clickhouse-client\--userdefault--passwordChangeme_CH_2026\-qSELECT version(), currentDatabase()# 停止dockercompose down九、延伸阅读轩辕镜像页library/clickhouseDocker Hub 官方说明clickhouse项目仓库ClickHouse/ClickHouse官方文档clickhouse.com/docs轩辕使用手册xuanyuan.cloud/usage
)
