首页 技术发现 减压
🇬🇧 English 🇪🇸 Español 🇩🇪 Deutsch 🇫🇷 Français 🇵🇱 Polski 🇨🇿 Česky 🇨🇳 中文 🇰🇷 한국어
返回首页

在Ubuntu 22.04和Debian 12上安装ClickHouse：指南

从官方仓库在Ubuntu 22.04和Debian 12上安装ClickHouse的实用指南，包含签名验证。包括systemd设置、自动启动、版本检查、配置文件位置、开放端口以及解决典型问题（连接被拒绝、权限被拒绝、内存不足）。提供了带有内存限制和监听所有接口的最小开发配置。

By Sudonull Editorial Team • Published • Updated

ClickHouse在Ubuntu/Debian上：包含错误示例的完整指南
Advertisement 728x90

在 Ubuntu/Debian 上安装 ClickHouse：一份来自被权限问题坑过的人的详细指南

我第一次安装时犯的三个错误

第一次在生产环境安装 ClickHouse 时，我想：“这有什么难的——直接 apt install 就行了。”结果：端口关闭，日志无法写入，15 分钟后服务器崩溃，因为我忘了配置 max_server_memory_usage。第二次尝试：我把官方仓库和一个可疑的 PPA 搞混了。第三次：我没有设置 ulimit -n，ClickHouse 根本无法打开足够的文件描述符。

所以下面不仅仅是文档的复制，而是一份突出所有陷阱的指南。所有命令均在干净的 Ubuntu 22.04 LTS 和 Debian 12 上测试过。

步骤 1. 添加官方仓库（不要谷歌现成的脚本）

官方文档有一个脚本 curl https://clickhouse.com/ | sh。如果你不完全了解它的作用，我不建议在服务器上使用它。最好通过 apt 手动安装并验证密钥。在这种情况下，安全比速度更重要。

Google AdInline article slot
# 添加 ClickHouse GPG 密钥（包签名）
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg
curl -fsSL 'https://packages.clickhouse.com/rpm/latest/repodata/repomd.xml.key' | sudo gpg --dearmor -o /usr/share/keyrings/clickhouse-keyring.gpg

# 将仓库添加到 apt 源
echo "deb [signed-by=/usr/share/keyrings/clickhouse-keyring.gpg] https://packages.clickhouse.com/deb stable main" | sudo tee /etc/apt/sources.list.d/clickhouse.list

# 更新包列表
sudo apt-get update

为什么这么复杂？ 因为没有签名验证，你可能会从非官方仓库安装包。在生产环境中，我们遇到过开发人员运行 curl | sh 而安装了带有漏洞的旧版本。不要重蹈覆辙。

步骤 2. 安装服务器和客户端

# 安装包
sudo apt-get install -y clickhouse-server clickhouse-client

# 如果你想要基准测试工具
sudo apt-get install -y clickhouse-common-static

安装过程中，系统会要求你为 default 用户设置密码。重要提示： 如果留空，则不会设置任何密码。在生产环境中，这将是灾难。即使是开发环境，也设置一个简单密码如 clickhouse_dev——以后更容易记住。

安装后，你会看到：

Google AdInline article slot
ClickHouse server has been installed.
Configuration file: /etc/clickhouse-server/config.xml
Logs directory: /var/log/clickhouse-server/
Data directory: /var/lib/clickhouse/

步骤 3. 检查版本——文档未提及的实用技巧

clickhouse-server --version

预期输出（撰写本文时）：

ClickHouse server version 24.8.2.3 (official build).

个人经验： 更新 ClickHouse 版本后，磁盘上的数据存储格式有时会改变。如果你有旧版本并运行了 apt upgrade，系统可能因错误 Unknown data type 而无法启动。在更新前始终运行 clickhouse-server --version 并阅读更新日志。

步骤 4. 通过 systemd 启动——并检查你是否遗漏了什么

# 启用开机自启
sudo systemctl enable clickhouse-server

# 立即启动服务器
sudo systemctl start clickhouse-server

# 检查状态
sudo systemctl status clickhouse-server

如果一切正常，你会看到：

Google AdInline article slot
● clickhouse-server.service - ClickHouse Server (analytic DBMS)
     Loaded: loaded (/etc/systemd/system/clickhouse-server.service; enabled)
     Active: active (running) since ...

常见错误： 服务器因文件描述符不足而无法启动。检查：

# 查看服务的当前限制
cat /proc/$(pidof clickhouse-server)/limits | grep "open files"

# 如果小于 262144，添加到 /etc/systemd/system/clickhouse-server.service.d/override.conf
[Service]
LimitNOFILE=262144
LimitNPROC=32768

修改后，不要忘记：

sudo systemctl daemon-reload
sudo systemctl restart clickhouse-server

步骤 5. 首次通过 clickhouse-client 登录——以及我最喜欢的测试

clickhouse-client --password
# 输入你在步骤 2 中设置的密码

如果你没有设置密码，直接：

clickhouse-client

第一个查询总是版本检查：

SELECT version();

输出：

┌─version()─┐
│ 24.8.2.3  │
└───────────┘

现在你可以自豪了——ClickHouse 正在运行。

性能测试彩蛋： 运行这个查询——它会显示你的机器生成和处理数据的速度：

SELECT sum(number) FROM numbers(100000000);

在配置不错的服务器（4 核以上）上，它将在 0.3-0.5 秒内执行。在弱虚拟机上——最多 2 秒。如果超过 5 秒，说明存在 CPU 或限流问题。

步骤 6. 重要文件的位置——记住这些路径

文件/目录 用途 我最常修改的内容
/etc/clickhouse-server/config.xml 主配置 listen_host（监听非 localhost 地址）、max_server_memory_usage、http_port
/etc/clickhouse-server/users.xml 用户设置 password（default 用户）、readonly、quota
/var/log/clickhouse-server/clickhouse-server.log 主日志 当它无法启动时，先检查这里
/var/log/clickhouse-server/clickhouse-server.err.log 错误日志 我在这里捕获内存和磁盘错误
/var/lib/clickhouse/ 表数据 检查磁盘是否已满
/var/lib/clickhouse/status PID 和状态 用于监控脚本

真实案例： 有一次，ClickHouse 停止接受请求。一切都在运行，但控制台挂起了。结果发现日志文件增长到 80 GB，填满了根分区。在配置中添加日志轮转：

<logger>
    <size>1000M</size>
    <count>10</count>
</logger>

步骤 7. 开发环境的最小配置

对于本地机器或开发服务器，我使用这个 config.xml（我只修改关键部分）：

<!-- /etc/clickhouse-server/config.d/dev-override.xml -->
<clickhouse>
    <!-- 监听所有接口，而不仅仅是 localhost -->
    <listen_host>0.0.0.0</listen_host>
    
    <!-- 限制内存以避免拖垮笔记本电脑 -->
    <max_server_memory_usage>0.75</max_server_memory_usage>  <!-- 总 RAM 的 75% -->
    <max_memory_usage_for_all_queries>0</max_memory_usage_for_all_queries>
    
    <!-- 开发环境的超时设置 -->
    <keep_alive_timeout>3</keep_alive_timeout>
    
    <!-- 避免在磁盘上创建过多分区 -->
    <merge_tree>
        <max_parts_in_total>1000</max_parts_in_total>
    </merge_tree>
</clickhouse>

应用：

sudo systemctl restart clickhouse-server

为什么用单独文件而不是直接编辑 config.xml？ 当包更新时，config.xml 可能会被覆盖。将所有自定义修改放在 /etc/clickhouse-server/config.d/ 中。我是在一次失败更新后的降级中学会的——我丢失了一周的配置。

步骤 8. 打开外部连接的端口

ClickHouse 监听三个端口：

  • 8123 — HTTP（用于 REST API、Grafana，直观）
  • 9000 — 原生 TCP 协议（用于 clickhouse-client 和驱动程序）
  • 9009 — 服务器间通信（用于集群，非必要勿动）

在开发机器上，我至少打开 8123 以便从 TablePlus 或 DBeaver 连接：

# 检查进程是否在监听
sudo netstat -tulpn | grep clickhouse

# 如果没有，在 UFW 中允许
sudo ufw allow 8123/tcp
sudo ufw allow 9000/tcp

常见错误： 在 Ubuntu 22.04 上，即使 ClickHouse 监听 0.0.0.0，防火墙也可能默认阻止。始终用 telnet localhost 8123 和 telnet $(hostname -I) 8123 检查。

典型安装问题及我的解决方法

问题 1：Code: 210. DB::NetException: Connection refused

原因： 服务器未启动或仅监听 127.0.0.1。

解决方法：

# 检查状态
systemctl status clickhouse-server

# 查看日志
tail -n 50 /var/log/clickhouse-server/clickhouse-server.log

# 编辑配置
sudo nano /etc/clickhouse-server/config.xml
# 找到 <listen_host>0.0.0.0</listen_host> 并取消注释

问题 2：cannot create directory '/var/lib/clickhouse/' Permission denied

原因： 手动干预后数据目录权限混乱。

解决方法：

sudo chown -R clickhouse:clickhouse /var/lib/clickhouse
sudo chmod 755 /var/lib/clickhouse

问题 3：服务器启动但 30 秒后因 Out of memory 崩溃

原因： ClickHouse 默认想使用几乎所有 RAM。

解决方法： 在开发环境中严格限制内存：

# 在 /etc/clickhouse-server/config.xml 中添加
<max_server_memory_usage>2147483648</max_server_memory_usage>  # 2 GB

或通过系统限制：

sudo systemctl edit clickhouse-server
# 添加：
[Service]
MemoryMax=2G

问题 4：安装因与 clickhouse-common-static 冲突而失败

原因： 先前版本的残留或 apt 缓存损坏。

解决方法：

sudo apt-get remove --purge clickhouse-*
sudo rm -rf /etc/clickhouse-server /var/lib/clickhouse
sudo apt-get clean
# 从头开始重新安装

健康检查——我的个人清单

安装后，我总是运行三个测试：

  1. 本地连接

    clickhouse-client -q "SELECT 1"
# 应返回 1

  2. 远程 HTTP 连接（从另一台机器）

    curl "http://YOUR_SERVER_IP:8123/?query=SELECT+version()"

  3. 数据写入

    CREATE DATABASE test;
CREATE TABLE test.t (id UInt64) ENGINE = MergeTree ORDER BY id;
INSERT INTO test.t SELECT number FROM numbers(1000);
SELECT count() FROM test.t;

如果全部通过，安装成功。

下一步是什么？

现在你已经在 Ubuntu/Debian 上拥有了一个可用的 ClickHouse。下一步是学习如何将其封装在 Docker 中并设置一个三节点集群并配置复制。

➡️ 下一篇文章：[通过 Docker 安装 ClickHouse：10 分钟搭建生产集群]（链接即将推出）

⬅️ 上一篇文章：[什么是 ClickHouse：为什么列式数据库管理系统能碾压分析任务]（链接即将推出）

祝安装顺利。如果遇到问题，首先检查 /var/log/clickhouse-server/clickhouse-server.err.log。那个错误日志救我的次数比周一早晨的咖啡还多。

← 上一篇:
→ 下一篇: Docker中的ClickHouse：如何不再担忧，两分钟启动分析

— Editorial Team

Advertisement 728x90

继续阅读

标签

#clickhouse-installation #ubuntu-setup #debian-guide #database-deployment #devops-tutorial

主题

数据库 DevOps

常见问题

如何通过apt在Ubuntu 22.04上安装ClickHouse？

添加ClickHouse GPG密钥，将仓库添加到/etc/apt/sources.list.d/，运行apt-get update并安装clickhouse-server和clickhouse-client包。

如何将ClickHouse作为systemd服务启动？

运行sudo systemctl enable clickhouse-server和sudo systemctl start clickhouse-server。使用sudo systemctl status clickhouse-server检查状态。

安装后ClickHouse的配置和日志位于何处？

配置：/etc/clickhouse-server/config.xml和users.xml。日志：/var/log/clickhouse-server/。数据：/var/lib/clickhouse/。

连接ClickHouse时遇到连接被拒绝错误怎么办？

使用systemctl status检查服务器状态，查看日志，并在config.xml中取消注释<listen_host>0.0.0.0</listen_host>以接受外部连接。