Czego szukasz?

Wpisz temat, narzędzie lub problem do rozwiązania.

← Wszystkie artykuły

Uptime Kuma: własny monitoring stron i serwerów w Dockerze

Przyrząd obserwacyjny z zielonymi sygnałami i jednym czerwonym znacznikiem.

Działający kontener nie oznacza jeszcze działającej strony. Aplikacja może odpowiadać błędem, formularz przestać zapisywać dane, a certyfikat zbliżać się do końca ważności. Uptime Kuma pomaga zauważyć problemy z dostępnością, ale warto najpierw ustalić, co dokładnie ma sprawdzać i skąd wykonuje pomiar.

W tym poradniku uruchomisz własny monitoring w Docker Compose, zachowasz dane poza kontenerem i połączysz się z panelem przez tunel SSH. Następnie dodasz kontrolę strony, ustawisz powiadomienia i przygotujesz kopię danych przed aktualizacją. Przykład zakłada serwer Linux z aktualnym Docker Engine i wtyczką Compose.

Co sprawdza Uptime Kuma?

Uptime Kuma to aplikacja do samodzielnego hostowania monitoringu. Obsługuje między innymi żądania HTTP i HTTPS, sprawdzanie portów TCP, ping, rekordy DNS oraz monitory Push. Ma również powiadomienia, informacje o certyfikatach i strony statusu. Listę funkcji i podstawowe wymagania znajdziesz w oficjalnym repozytorium projektu.

Najważniejszy jest dobór kontroli do problemu. Odpowiedź HTTP 200 mówi, że konkretny adres zwrócił akceptowany kod. Nie potwierdza automatycznie, że klient może złożyć zamówienie, zalogować się lub pobrać dokument. Z kolei otwarty port bazy danych nie dowodzi, że aplikacja wykonuje prawidłowe zapytania.

Kontrola Na jakie pytanie odpowiada Czego sama nie potwierdza
HTTP/HTTPS Czy wskazany adres zwraca oczekiwaną odpowiedź? Poprawności wszystkich funkcji strony
HTTP z oczekiwanym tekstem Czy odpowiedź zawiera ustalony fragment? Poprawności treści poza sprawdzanym warunkiem
TCP Czy można nawiązać połączenie z portem? Poprawności operacji biznesowej
Push Czy zadanie zgłosiło się w oczekiwanym czasie? Sukcesu zadania, jeśli sygnał wysyłasz zbyt wcześnie

Nie zastępuj jednym zielonym wskaźnikiem całej diagnostyki. Do szukania przyczyny awarii nadal przydadzą się logi aplikacji, systemu i reverse proxy. Monitoring ma wskazać, że trzeba zareagować, oraz dostarczyć czas i rodzaj zaobserwowanego problemu.

Gdzie uruchomić monitoring?

Jeśli postawisz Uptime Kuma na tym samym VPS co obserwowaną stronę, wykryjesz część awarii aplikacji. Nie otrzymasz jednak wiarygodnego ostrzeżenia z tego monitora, kiedy cały VPS straci zasilanie lub połączenie z internetem. Monitor przestanie wtedy działać razem z usługą.

Do obserwowania publicznej dostępności wybierz oddzielny host, najlepiej z inną zależnością sieciową. Może to być drugi VPS lub niezależny system monitorujący. Domowy komputer też potrafi wykonywać pomiary, lecz wynik będzie zależał od jego zasilania i twojego łącza. Nie zakładaj, że dowolne drugie urządzenie automatycznie daje niezależny punkt obserwacyjny.

Rozdziel również kontrolę zewnętrzną od wewnętrznej. Publiczny adres strony sprawdza drogę podobną do tej, którą pokonuje odwiedzający. Adres wewnętrzny przydaje się do diagnostyki konkretnej usługi. Jeśli korzystasz z Cloudflare jako pośrednika, publiczny pomiar uwzględni także tę warstwę.

Dwa oddzielne stanowiska: monitor obserwuje usługę na drugim serwerze.
Monitoring na osobnym hoście może zauważyć awarię serwera aplikacji.

Instalacja Uptime Kuma w Docker Compose

Zacznij od sprawdzenia dostępnych narzędzi:

docker version
docker compose version

Konto wykonujące następne polecenia musi mieć dostęp do demona Dockera. Sam dostęp do grupy docker daje duże uprawnienia do hosta, więc nie przydzielaj go przypadkowym użytkownikom. Jeśli dopiero poznajesz ten sposób uruchamiania usług, zacznij od wyjaśnienia jak działa projekt Docker Compose.

Utwórz osobny katalog i plik compose.yaml:

mkdir -p "$HOME/uptime-kuma"
cd "$HOME/uptime-kuma"
nano compose.yaml

Wklej konfigurację:

name: uptime-kuma

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - kuma-data:/app/data
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  kuma-data:

Przykład korzysta z głównej linii obrazu :2, wskazanej w konfiguracji Compose projektu. Jest to tag ruchomy: kolejne pobranie może wskazać nowsze wydanie tej linii. Przy wdrożeniu wymagającym pełnej powtarzalności zapisz wybrany tag wydania albo digest obrazu. Nie traktuj ponownego pobrania jako neutralnej operacji.

Wolumen kuma-data jest montowany w /app/data, czyli miejscu przechowywania danych aplikacji. Korzystaj z lokalnego systemu plików; projekt ostrzega przed użyciem NFS. Limity logów w przykładzie ograniczają rozrost plików sterownika json-file, ale nie zastępują kontroli wielkości bazy i historii monitoringu.

Mapowanie portu celowo rozpoczyna się od 127.0.0.1. Panel będzie dostępny przez loopback serwera, zamiast od razu nasłuchiwać na jego publicznym adresie. Używaj aktualnego Dockera: dokumentacja opisuje wyjątek dotyczący dostępu z tego samego segmentu L2 w wydaniach starszych niż 28.0.0. Szczegóły wyjaśnia dokumentacja publikowania portów.

Sprawdź plik i uruchom usługę:

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 uptime-kuma

Nie przechodź dalej, jeśli kontener stale się restartuje. Odczytaj komunikat z logów: problemem może być zajęty port, uprawnienie do danych lub błąd uruchamiania aplikacji. Po poprawnym starcie sprawdź odpowiedź na samym VPS:

curl -I http://127.0.0.1:3001/

Przekierowanie do ekranu konfiguracji lub logowania może być prawidłowe. Na tym etapie interesuje cię, czy aplikacja odpowiada; nie oczekuj konkretnego wyglądu panelu w wyniku curl -I.

Pierwsze logowanie przez tunel SSH

Na swoim komputerze, a nie wewnątrz sesji serwera, uruchom:

ssh -N -o ExitOnForwardFailure=yes \
  -L 127.0.0.1:13001:127.0.0.1:3001 \
  uzytkownik@ADRES_VPS

Zastąp login i adres danymi własnego serwera. Otwórz następnie http://127.0.0.1:13001 w lokalnej przeglądarce. Port 13001 należy do twojego komputera, a port 3001 do serwera. Opcja -N nie uruchamia zdalnego polecenia, tylko utrzymuje przekierowanie. Jego znaczenie opisuje podręcznik OpenSSH.

Pozostaw terminal z tunelem otwarty na czas pracy. Jeśli lokalny port jest zajęty, zmień 13001 na inny wolny numer w poleceniu i adresie przeglądarki. Błąd tworzenia przekierowania nie oznacza automatycznie awarii kontenera.

W świeżej instalacji wersji 2 najpierw może pojawić się konfiguracja bazy danych. Dla tego samodzielnego, niewielkiego wdrożenia wybierz SQLite. Dane pozostaną w podłączonym katalogu /app/data; nie potrzebujesz osobnego kontenera bazy. Wariant z zewnętrzną MariaDB wymaga dodatkowej konfiguracji i osobnego planu kopii bazy, którego ten przykład nie obejmuje.

Po przygotowaniu bazy utwórz konto administratora z osobnym hasłem. Skonfiguruj drugi składnik logowania, jeśli korzystasz z niego w swoim procesie dostępu, i zachowaj dane odzyskiwania w bezpiecznym miejscu. Nie wyłączaj uwierzytelniania tylko dlatego, że panel na razie jest dostępny przez tunel.

Laptop łączy się tunelem SSH z lokalnym portem panelu na VPS.
Tunel SSH pozwala korzystać z panelu bez publicznego otwierania portu 3001.

Dodaj pierwszy monitor i przetestuj alarm

W panelu dodaj monitor HTTP/HTTPS. Jako adres wybierz rzeczywistą stronę, której dostępność chcesz obserwować. Nazwa powinna mówić, co sprawdzasz, na przykład „Strona publiczna - strona główna”, zamiast ogólnego „Serwer”.

Ustal akceptowane kody odpowiedzi i sprawdź zachowanie przekierowań. Jeśli adres prowadzi do logowania, zielony wynik może oznaczać wyłącznie dostępność ekranu logowania. Dla ważnej aplikacji lepszy bywa osobny, niewrażliwy endpoint kontroli stanu. Nie powinien ujawniać haseł, konfiguracji ani szczegółów infrastruktury.

Interwał dobierz do oczekiwanego czasu reakcji i kosztu żądania. Na początek możesz rozważyć 60 sekund dla prostej strony. To przykład ustawienia, nie gwarancja alarmu po minucie: dochodzą timeouty, ponowienia i dostarczenie wiadomości. Częste odpytywanie ciężkiego raportu będzie obciążało aplikację bardziej niż lekki endpoint stanu.

Następnie skonfiguruj kanał powiadomień, użyj jego testu i przypisz go do monitora. Sam zapis danych kanału nie wystarczy. Sprawdź, czy wiadomość trafiła do właściwego odbiorcy i czy nie została wyciszona przez ustawienia urządzenia.

Do próby awarii użyj osobnej, kontrolowanej usługi testowej. Zatrzymaj ją, poczekaj na zmianę stanu i sprawdź wiadomość. Potem uruchom ją ponownie i zweryfikuj informację o odzyskaniu dostępności. Nie zatrzymuj produkcyjnego sklepu tylko po to, żeby obejrzeć czerwony wskaźnik.

Trzy etapy: pomiar stanu, wykrycie problemu i wiadomość alarmowa.
Skuteczny monitoring obejmuje również dostarczenie i sprawdzenie alertu.

Co zrobić z fałszywymi alarmami?

Zacznij od treści błędu. Timeout, nieprawidłowy kod HTTP, problem DNS i odrzucenie certyfikatu to różne sytuacje. Jeśli przeglądarka działa, a monitor zgłasza błąd, wykonaj próbę z hosta monitorującego i sprawdź jego rozwiązywanie nazw oraz połączenie z usługą.

Weź pod uwagę reguły WAF, ograniczenia częstotliwości i blokady ruchu automatycznego. Nie wyłączaj globalnie zabezpieczeń strony, żeby uzyskać zielony wynik. Dobierz kontrolę lub wąską regułę pasującą do jej źródła. Zwiększanie timeoutu też nie naprawi błędnej konfiguracji DNS.

Przy planowanych pracach użyj odpowiedniego mechanizmu wyciszenia lub okna serwisowego. Zachowaj rozróżnienie między świadomie zaplanowaną przerwą a nieoczekiwaną awarią, aby później móc zinterpretować historię dostępności.

Własna domena, HTTPS i strona statusu

Tunel wystarcza do prywatnej administracji. Jeżeli panel ma działać pod domeną, dodaj reverse proxy z HTTPS i obsługą WebSocket. Projekt zaleca osobną domenę lub subdomenę, zamiast instalacji w podkatalogu typu /monitoring/. Gotowe warianty konfiguracji opisuje oficjalna instrukcja reverse proxy.

Zwróć uwagę na miejsce działania proxy. Nginx uruchomiony bezpośrednio na hoście może łączyć się z 127.0.0.1:3001. Nginx w osobnym kontenerze widzi pod 127.0.0.1 samego siebie. W takim wariancie potrzebujesz wspólnej sieci kontenerów i właściwej nazwy usługi.

Publiczna strona statusu pełni inną funkcję niż panel administratora. Pokazuj na niej tylko informacje przeznaczone dla odwiedzających. Nie publikuj nazw wewnętrznych hostów, prywatnych adresów ani opisów zdradzających strukturę infrastruktury. Publiczny status nie jest też kanałem alarmowania osoby utrzymującej usługę.

Kopia danych i aktualizacja

Przed zmianą obrazu wykonaj kopię danych i zapisz używaną wersję. Dla pokazanego projektu możesz zrobić krótką kopię przy zatrzymanej aplikacji. Zatrzymanie ogranicza ryzyko skopiowania plików bazy w trakcie zapisu.

Poniższe polecenia wykonuj z katalogu zawierającego compose.yaml. Obraz pomocniczy pobierz przed zatrzymaniem monitoringu:

mkdir -p backups
chmod 700 backups
docker pull alpine:3.22
docker compose stop uptime-kuma
docker run --rm \
  --mount type=volume,source=uptime-kuma_kuma-data,target=/data,readonly \
  --mount type=bind,source="$PWD/backups",target=/backup \
  alpine:3.22 sh -c 'umask 077; tar czf /backup/kuma-$(date -u +%Y%m%dT%H%M%SZ).tgz -C /data .'
docker compose start uptime-kuma

Nazwa wolumenu wynika z name: uptime-kuma i klucza kuma-data. Jeśli zmienisz nazwę projektu, sprawdź rzeczywisty wolumen przed kopiowaniem. Po błędzie archiwizacji również przywróć działanie usługi i wyjaśnij przyczynę. W pracy automatycznej warto obsłużyć wznowienie w procedurze kończącej skrypt.

Przenieś kopię poza monitorowany VPS i sprawdź odtworzenie w odizolowanej instancji. Archiwum może zawierać dane kont i ustawienia powiadomień, więc nie wystawiaj katalogu kopii przez serwer WWW. Trwały wolumen i backup rozwiązują różne problemy; opis cyklu życia danych znajdziesz w dokumentacji wolumenów Dockera.

Po przeczytaniu informacji o wybranym wydaniu aktualizacja obrazu w tej samej linii wygląda tak:

docker compose pull
docker compose up -d
docker compose logs --tail=100 uptime-kuma

Ponownie sprawdź monitory i kanał alarmów. Cofnięcie samego tagu obrazu może nie wystarczyć po migracji bazy, dlatego zachowuj zestaw: poprzednia wersja oraz odpowiadająca jej kopia danych. Przy przejściu między głównymi wersjami korzystaj z osobnej instrukcji migracji, a nie z założenia, że każde pull jest bezproblemowe.

Najczęstsze pytania

Czy Uptime Kuma działa, gdy zamknę przeglądarkę?

Tak, pomiary wykonuje działająca aplikacja na serwerze. Zamknięcie panelu lub tunelu SSH odbiera ci dostęp do interfejsu, ale nie zatrzymuje kontenera. Wyłączenie hosta zatrzyma natomiast również monitoring.

Dlaczego kontener działa, ale strona ma status DOWN?

Status kontenera i wynik kontroli URL dotyczą różnych warstw. Odczytaj błąd monitora, sprawdź adres, DNS, certyfikat i odpowiedź aplikacji. Sam proces uruchomiony w kontenerze może nie obsługiwać żądań poprawnie.

Czy muszę otwierać port 3001 w internecie?

Nie. W pokazanej konfiguracji panel jest dostępny przez tunel SSH. Możesz też udostępnić go przez poprawnie skonfigurowane reverse proxy albo prywatną sieć, bez publicznego wystawiania portu aplikacji.

Jak sprawdzić zadanie wykonywane raz dziennie?

Rozważ monitor Push z oknem czasowym pasującym do harmonogramu. Sygnał sukcesu wysyłaj dopiero po poprawnym zakończeniu zadania. Jeśli skrypt zgłasza sukces przed wykonaniem kopii danych, monitor będzie potwierdzał start skryptu, a nie gotowy backup.

Czy usunięcie kontenera usunie konfigurację?

Przy poprawnym montowaniu nazwanego wolumenu dane pozostają poza kontenerem. Można jednak usunąć sam wolumen, na przykład poleceniem obejmującym jego kasowanie. Nie używaj docker compose down -v jako zwykłego sposobu restartowania tego projektu.

Źródła

Data publikacji: 06.10.2026.

KP
O AUTORZE

Krystian Proć

Tworzę narzędzia do pracy z danymi, systemy backendowe i automatyzacje. Pracuję z SQL, PHP, TypeScriptem i Dockerem; rozwijam m.in. dragon-island.com. AI pomaga mi przyspieszać pracę, a architekturę, weryfikację i decyzje techniczne biorę na siebie. Na Trybie Technicznym dzielę się doświadczeniami z budowania i utrzymywania własnych projektów.

Dyskusja

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Wymagane pola są oznaczone *