Instalacja ClickHouse na Ubuntu/Debian: instrukcja krok po kroku od kogoś, kto sparzył się na nieprawidłowych uprawnieniach
Za pierwszym razem instalowałem ClickHouse na produkcji, myśląc „co tam trudnego – apt install”. Efekt: porty zamknięte, logi się nie zapisują, a po 15 minutach serwer padł, bo zapomniałem skonfigurować max_server_memory_usage. Druga próba – pomyliłem oficjalne repozytorium z podejrzanym PPA. Trzecia – nie ustawiłem ulimit -n, i ClickHouse po prostu nie mógł otworzyć wystarczającej liczby deskryptorów plików.
Dlatego poniżej – nie tylko kopia dokumentacji, ale instrukcja, w której zaznaczę wszystkie pułapki. Wszystkie polecenia sprawdzone na czystym Ubuntu 22.04 LTS i Debianie 12.
Krok 1. Dodajemy oficjalne repozytorium (nie googluj gotowych skryptów)
W oficjalnej dokumentacji jest skrypt curl https://clickhouse.com/ | sh. Nie radzę go używać na serwerze, jeśli nie do końca rozumiesz, co robi. Lepiej – ręczna instalacja przez apt z weryfikacją klucza. To przypadek, gdzie bezpieczeństwo jest ważniejsze niż szybkość.
# Dodajemy klucz GPG ClickHouse (podpis pakietów)
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
# Dodajemy repozytorium do źródeł 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
# Aktualizujemy listę pakietów
sudo apt-get updateDlaczego tak skomplikowanie? Ponieważ bez weryfikacji podpisu ryzykujesz instalację pakietu z nieoficjalnego repozytorium. Na produkcji mieliśmy przypadek, gdy programista uruchomił curl | sh i dostał starą wersję z luką. Nie powtarzaj tego.
Krok 2. Instalujemy serwer i klienta
# Instalacja pakietów
sudo apt-get install -y clickhouse-server clickhouse-client
# Jeśli chcesz narzędzia do benchmarków
sudo apt-get install -y clickhouse-common-staticPodczas instalacji zostaniesz zapytany o hasło dla użytkownika default. Ważna uwaga: jeśli pozostawisz puste, hasło nie zostanie ustawione w ogóle. W środowisku produkcyjnym to katastrofa. Nawet dla deva ustaw proste hasło, np. clickhouse_dev – potem łatwiej będzie je zapamiętać.
Po instalacji zobaczysz:
ClickHouse server has been installed.
Configuration file: /etc/clickhouse-server/config.xml
Logs directory: /var/log/clickhouse-server/
Data directory: /var/lib/clickhouse/Krok 3. Sprawdzamy wersję – lifehack, o którym dokumentacja milczy
clickhouse-server --versionOczekiwany wynik (w momencie pisania artykułu):
ClickHouse server version 24.8.2.3 (official build).Osobiste doświadczenie: Po aktualizacji wersji ClickHouse czasami zmienia format przechowywania danych na dysku. Jeśli miałeś już starą wersję i zrobiłeś apt upgrade, system może nie uruchomić się z błędem Unknown data type. Zawsze sprawdzaj clickhouse-server --version przed aktualizacją i czytaj changelog.
Krok 4. Uruchamiamy przez systemd – i sprawdzamy, czy o niczym nie zapomnieliśmy
# Włączamy autostart przy bootowaniu
sudo systemctl enable clickhouse-server
# Uruchamiamy serwer teraz
sudo systemctl start clickhouse-server
# Sprawdzamy status
sudo systemctl status clickhouse-serverJeśli wszystko OK, zobaczysz:
● clickhouse-server.service - ClickHouse Server (analytic DBMS)
Loaded: loaded (/etc/systemd/system/clickhouse-server.service; enabled)
Active: active (running) since ... Częsty błąd: Serwer nie uruchamia się z powodu braku deskryptorów plików. Sprawdź:
# Zobacz aktualny limit dla serwisu
cat /proc/$(pidof clickhouse-server)/limits | grep "open files"
# Jeśli mniej niż 262144, dodaj w /etc/systemd/system/clickhouse-server.service.d/override.conf
[Service]
LimitNOFILE=262144
LimitNPROC=32768Po zmianie nie zapomnij:
sudo systemctl daemon-reload
sudo systemctl restart clickhouse-serverKrok 5. Pierwsze logowanie przez clickhouse-client – i mój ulubiony test
clickhouse-client --password
# Wprowadź hasło, które ustawiłeś w kroku 2Jeśli nie ustawiłeś hasła, po prostu:
clickhouse-clientPierwsze zapytanie – zawsze sprawdzenie wersji:
SELECT version();Wynik:
┌─version()─┐
│ 24.8.2.3 │
└───────────┘Teraz możesz być dumny – ClickHouse działa.
Bonusowy test wydajności: Wykonaj to zapytanie – pokaże, jak szybko twoja maszyna może generować i przetwarzać dane:
SELECT sum(number) FROM numbers(100000000);Na normalnym serwerze (4+ rdzenie) wykona się w 0.3-0.5 sekundy. Na słabej wirtualce – do 2 sekund. Jeśli więcej niż 5 sekund – masz problemy z CPU lub throttlingiem.
Krok 6. Gdzie leżą ważne pliki – zapamiętaj te ścieżki
| Plik/katalog | Przeznaczenie | Co tam zmieniałem najczęściej |
|---|---|---|
/etc/clickhouse-server/config.xml |
Główna konfiguracja | listen_host (aby nasłuchiwać nie tylko localhost), max_server_memory_usage, http_port |
/etc/clickhouse-server/users.xml |
Ustawienia użytkowników | password dla default, readonly, quota |
/var/log/clickhouse-server/clickhouse-server.log |
Główny log | Gdy nie startuje – najpierw tutaj |
/var/log/clickhouse-server/clickhouse-server.err.log |
Log błędów | Tu łapię błędy z pamięcią i dyskiem |
/var/lib/clickhouse/ |
Dane tabel | Sprawdzić, czy dysk się nie zapchał |
/var/lib/clickhouse/status |
PID i status | Do skryptów monitorujących |
Praktyczna uwaga: U nas kiedyś ClickHouse przestał przyjmować zapytania. Wszystko działało, ale konsola wisiała. Okazało się, że plik logu urósł do 80 GB i zapełnił partycję root. Dodaj do konfiguracji rotację:
<logger>
<size>1000M</size>
<count>10</count>
</logger>Krok 7. Minimalna konfiguracja dla rozwoju
Dla lokalnej maszyny lub serwera dev używam takiego config.xml (edytuję tylko to, co krytyczne):
<!-- /etc/clickhouse-server/config.d/dev-override.xml -->
<clickhouse>
<!-- Nasłuchujemy na wszystkich interfejsach, nie tylko localhost -->
<listen_host>0.0.0.0</listen_host>
<!-- Ograniczamy pamięć, aby nie zabić laptopa -->
<max_server_memory_usage>0.75</max_server_memory_usage> <!-- 75% całego RAM -->
<max_memory_usage_for_all_queries>0</max_memory_usage_for_all_queries>
<!-- Timeouty dla środowiska dev -->
<keep_alive_timeout>3</keep_alive_timeout>
<!-- Aby nie mnożyć partycji na dysku -->
<merge_tree>
<max_parts_in_total>1000</max_parts_in_total>
</merge_tree>
</clickhouse>Stosujemy:
sudo systemctl restart clickhouse-serverDlaczego osobny plik, a nie edycja config.xml? Przy aktualizacji pakietu config.xml może zostać nadpisany. Wszystkie własne zmiany umieszczaj w /etc/clickhouse-server/config.d/. Tego nauczył mnie downgrade po nieudanej aktualizacji – straciłem tydzień ustawień.
Krok 8. Otwieramy porty dla połączeń zewnętrznych
ClickHouse nasłuchuje na trzech portach:
- 8123 – HTTP (dla REST API, Grafana, intuicyjny)
- 9000 – natywny protokół TCP (dla clickhouse-client i sterowników)
- 9009 – komunikacja między serwerami (dla klastrów, nie ruszaj bez potrzeby)
Na maszynie dev otwieram przynajmniej 8123, aby łączyć się z TablePlus lub DBeaver:
# Sprawdź, czy proces nasłuchuje
sudo netstat -tulpn | grep clickhouse
# Jeśli nie – zezwól w UFW
sudo ufw allow 8123/tcp
sudo ufw allow 9000/tcpCzęsty błąd: Na Ubuntu 22.04 domyślnie firewall może blokować, nawet jeśli ClickHouse nasłuchuje na 0.0.0.0. Zawsze sprawdzaj przez telnet localhost 8123 i telnet $(hostname -I) 8123.
Typowe problemy przy instalacji i jak je rozwiązywałem
Problem 1: Code: 210. DB::NetException: Connection refused
Przyczyna: Serwer nie uruchomił się lub nasłuchuje tylko na 127.0.0.1.
Rozwiązanie:
# Sprawdź status
systemctl status clickhouse-server
# Zobacz log
tail -n 50 /var/log/clickhouse-server/clickhouse-server.log
# Edytuj konfig
sudo nano /etc/clickhouse-server/config.xml
# Znajdź <listen_host>0.0.0.0</listen_host> i odkomentujProblem 2: cannot create directory '/var/lib/clickhouse/' Permission denied
Przyczyna: Uprawnienia do katalogu danych zostały uszkodzone po ręcznej ingerencji.
Rozwiązanie:
sudo chown -R clickhouse:clickhouse /var/lib/clickhouse
sudo chmod 755 /var/lib/clickhouseProblem 3: Serwer startuje, ale pada po 30 sekundach z Out of memory
Przyczyna: ClickHouse domyślnie chce użyć prawie całego RAM.
Rozwiązanie: W środowisku dev ostro ogranicz pamięć:
# W /etc/clickhouse-server/config.xml dodaj
<max_server_memory_usage>2147483648</max_server_memory_usage> # 2 GBLub przez limit systemowy:
sudo systemctl edit clickhouse-server
# Dodaj:
[Service]
MemoryMax=2GProblem 4: Nie instaluje się z powodu konfliktu z clickhouse-common-static
Przyczyna: Pozostałości poprzedniej wersji lub uszkodzony cache apt.
Rozwiązanie:
sudo apt-get remove --purge clickhouse-*
sudo rm -rf /etc/clickhouse-server /var/lib/clickhouse
sudo apt-get clean
# Powtórz instalację od początkuSprawdzenie działania – mój osobisty checklist
Po instalacji zawsze wykonuję trzy testy:
Połączenie lokalne
clickhouse-client -q "SELECT 1" # Powinno zwrócić 1Połączenie zdalne przez HTTP (z innej maszyny)
curl "http://TWOJ_IP_SERWERA:8123/?query=SELECT+version()"Zapis danych
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;
Jeśli wszystko przejdzie – instalacja udana.
Co dalej?
Teraz masz działający ClickHouse na Ubuntu/Debian. Następny krok – nauczyć się go opakowywać w Docker i podnieść klaster z trzech nodów z replikacją.
➡️ Następny artykuł: [Instalacja ClickHouse przez Docker: klaster produkcyjny w 10 minut] (link będzie)
⬅️ Poprzedni artykuł: [Co to jest ClickHouse: dlaczego kolumnowe bazy danych rozrywają analitykę na strzępy] (link będzie)
Powodzenia w instalacji. Jeśli utkniesz – najpierw zajrzyj do /var/log/clickhouse-server/clickhouse-server.err.log. Ten błąd uratował mnie więcej razy niż kawa w poniedziałek rano.
← Poprzedni: ClickHouse: Dlaczego kolumnowe SZBD rozrywają analitykę na strzępy
→ Następny: ClickHouse w Docker: jak przestałem się bać i uruchomiłem analitykę w 2 minuty
— Editorial Team
Brak komentarzy.