Ubuntu 22.04 및 Debian 12에 ClickHouse 설치: 가이드

서명 확인과 함께 공식 저장소에서 Ubuntu 22.04 및 Debian 12에 ClickHouse를 설치하는 실용 가이드. systemd 설정, 자동 시작, 버전 확인, 구성 파일 위치, 포트 열기, 일반적인 문제 해결(Connection refused, Permission denied, Out of memory) 포함. 메모리 제한 및 모든 인터페이스 수신을 위한 최소 개발 구성 제공.

By Sudonull Editorial Team • Published 2026-06-08 • Updated 2026-06-08

Ubuntu/Debian에서 ClickHouse: 오류 예제가 포함된 완벽 가이드

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를 통한 수동 설치가 더 안전합니다. 보안이 속도보다 중요한 경우입니다.

# 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 같은 간단한 비밀번호를 설정하세요. 나중에 기억하기 더 쉽습니다.

설치 후 다음과 같은 메시지가 표시됩니다:

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

모든 것이 정상이면 다음과 같이 표시됩니다:

● 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`	사용자 설정	`default`의 `password`, `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가 요청을 받지 못했습니다. 모든 것이 실행 중이었지만 콘솔이 멈췄습니다. 로그 파일이 80GB로 커져 루트 파티션을 가득 채운 것이 원인이었습니다. 설정에 로테이션을 추가하세요:

<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 — 서버 간 통신 (클러스터용, 불필요하게 건드리지 마세요)

개발 머신에서는 TablePlus나 DBeaver에서 연결할 수 있도록 최소 8123을 엽니다:

# 프로세스가 수신 중인지 확인
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
# 처음부터 설치 반복

상태 점검 — 개인 체크리스트

설치 후 항상 세 가지 테스트를 실행합니다:

로컬 연결

clickhouse-client -q "SELECT 1"
# 1을 반환해야 함

원격 HTTP 연결 (다른 머신에서)

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

데이터 쓰기

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로 래핑하고 복제가 있는 3노드 클러스터를 설정하는 방법을 배우는 것입니다.

➡️ 다음 글: [Docker로 ClickHouse 설치: 10분 만에 프로덕션 클러스터] (링크 예정)

⬅️ 이전 글: [ClickHouse란 무엇인가: 컬럼 기반 DBMS가 분석을 압도하는 이유] (링크 예정)

설치에 행운이 있기를 바랍니다. 막히면 먼저 /var/log/clickhouse-server/clickhouse-server.err.log를 확인하세요. 그 오류는 월요일 아침 커피보다 더 자주 저를 구해줬습니다.

← 이전 글: ClickHouse: 컬럼 기반 DBMS가 분석을 압도하는 이유
→ 다음 글: Docker에서 ClickHouse: 걱정을 접고 2분 만에 분석 시작하기

— Editorial Team

커뮤니티

아직 댓글이 없습니다.

다음 읽기

주제

데이터베이스 DevOps

FAQ

Ubuntu 22.04에 apt를 통해 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 연결 시 Connection refused 오류가 발생하면 어떻게 해야 하나요?

systemctl status로 서버 상태를 확인하고, 로그를 살펴본 후 config.xml에서 <listen_host>0.0.0.0</listen_host>의 주석을 해제하여 외부 연결을 허용합니다.

Ubuntu 22.04 및 Debian 12에 ClickHouse 설치: 가이드

Ubuntu/Debian에 ClickHouse 설치하기: 잘못된 권한으로 고생한 사람이 알려주는 단계별 가이드

처음 설치할 때 저지른 세 가지 실수

1단계. 공식 저장소 추가하기 (레디메이드 스크립트를 구글링하지 마세요)

2단계. 서버와 클라이언트 설치하기

3단계. 버전 확인 — 문서에 없는 꿀팁

4단계. systemd로 시작 — 잊은 것이 없는지 확인

5단계. clickhouse-client로 첫 로그인 — 제가 가장 좋아하는 테스트

6단계. 중요한 파일 위치 — 이 경로를 기억하세요

7단계. 개발을 위한 최소 설정

8단계. 외부 연결을 위한 포트 열기

일반적인 설치 문제와 해결 방법

문제 1: `Code: 210. DB::NetException: Connection refused`

문제 2: `cannot create directory '/var/lib/clickhouse/' Permission denied`

문제 3: 서버가 시작되지만 30초 후 `Out of memory`로 다운됨

문제 4: `clickhouse-common-static`과의 충돌로 설치 실패

상태 점검 — 개인 체크리스트

다음 단계는?

커뮤니티

다음 읽기

최근 본 글

태그

주제

FAQ

Ubuntu/Debian에 ClickHouse 설치하기: 잘못된 권한으로 고생한 사람이 알려주는 단계별 가이드

처음 설치할 때 저지른 세 가지 실수

1단계. 공식 저장소 추가하기 (레디메이드 스크립트를 구글링하지 마세요)

2단계. 서버와 클라이언트 설치하기

3단계. 버전 확인 — 문서에 없는 꿀팁

4단계. systemd로 시작 — 잊은 것이 없는지 확인

5단계. clickhouse-client로 첫 로그인 — 제가 가장 좋아하는 테스트

6단계. 중요한 파일 위치 — 이 경로를 기억하세요

7단계. 개발을 위한 최소 설정

8단계. 외부 연결을 위한 포트 열기

일반적인 설치 문제와 해결 방법

문제 1: Code: 210. DB::NetException: Connection refused

문제 2: cannot create directory '/var/lib/clickhouse/' Permission denied

문제 3: 서버가 시작되지만 30초 후 Out of memory로 다운됨

문제 4: clickhouse-common-static과의 충돌로 설치 실패

상태 점검 — 개인 체크리스트

다음 단계는?

커뮤니티

다음 읽기

ClickHouse: 컬럼형 DBMS가 분석을 100배 가속화하는 이유

적응형 액체 트랜스포머: AI 에너지 효율성의 혁신

알파벳, 850억 달러 조달: AI 경쟁의 SOS 신호인가, 기업 구제인가?

xAI, 미국 정부와 계약 체결 — 머스크의 0.42달러 패닉

AI 회사 Suno, 40억 달러 조달: 자동차 시장 추월

Google Gemini 기반 Siri: WWDC 2026 데뷔, 거래 분석

지수 제공업체들이 AI 거대 기업 주식의 편입을 가속화할 것입니다

SpaceX IPO 기록적 상장 2026 위험 분석

기술주 폭락: 나스닥 하락 이유

AI-음악: Spotify와 Universal Music이 유료 모델 도입

최근 본 글

태그

주제

FAQ

이 기사 공유

문제 1: `Code: 210. DB::NetException: Connection refused`

문제 2: `cannot create directory '/var/lib/clickhouse/' Permission denied`

문제 3: 서버가 시작되지만 30초 후 `Out of memory`로 다운됨

문제 4: `clickhouse-common-static`과의 충돌로 설치 실패