Příručka

Rychlý start

Tento průvodce vám pomůže zprovoznit kompletní monitorovací systém během několika minut.

Krok 1: Spuštění Serveru

Centrální server Blood Kings se nejjednodušeji spouští pomocí Docker Compose. Vytvořte si prázdnou složku a vložte do ní následující konfiguraci:

# docker-compose.yml
version: '3.8'
services:
  bloodkings:
    image: bkpepe/monitoring:latest
    ports:
      - "8080:80"
    volumes:
      - ./data:/var/www/html/data
    restart: always

Spusťte server příkazem:

docker compose up -d

Po dokončení stahování otevřete prohlížeč na adrese http://localhost:8080 a postupujte podle pokynů na obrazovce k vytvoření administrátorského účtu.

Krok 2: Přidání nového monitoru

Po přihlášení do administrace přejděte na záložku Monitors a klikněte na Add Monitor. Můžete přidat standardní HTTPS kontroly, ping na IP adresy, kontroly SSL certifikátů nebo heartbeat pro úlohy, které se hlásí samy.

Systémové požadavky

Blood Kings Monitoring je navržen tak, aby běžel na jakémkoliv hardwaru.

Centrální Server:

  • Procesor: 1 vCPU (x86_64 nebo ARM64)
  • Operační paměť: 128 MB RAM (doporučeno 256 MB)
  • Místo na disku: 50 MB pro aplikaci + místo pro historii databází (cca 100 MB na rok běžného provozu)
  • Software: Docker & Docker Compose nebo PHP 8.2+ s webovým serverem (Apache/Nginx) a MySQL databází

Vzdálený Agent:

  • OS: Linux (libovolná distribuce s Bash a Curl), Windows 10/11/Server, macOS, Raspberry Pi OS
  • Paměť: méně než 10 MB RAM
  • Síť: Odchozí HTTPS (port 443) přístup k centrálnímu serveru

Architektura systému

Blood Kings Monitoring využívá hybridní architekturu spojující aktivní piny a pasivní agenty.

Vzdálený Agent(Linux/Windows/Docker)↓ HTTPS POST (Metrics)
Centrální Server(PHP / SQLite nebo MySQL)↓ Render
Veřejná Status Stránka(HTML / cached JSON)

Pasivní monitoring (Agenti): Agenti běží na vašich cílových strojích. V pravidelných intervalech (např. 60 sekund) shromažďují lokální data (CPU, RAM, disky) a zasílají je pomocí HTTPS POST požadavků na centrální server. Tento přístup nevyžaduje otevírání žádných příchozích portů na monitorovaných serverech.

Aktivní monitoring (Pinger): Centrální server spouští cron skripty, které provádějí HTTP/HTTPS, TCP a ICMP ping požadavky na vámi zadané vzdálené cíle.

Konfigurace Databáze Serveru

Blood Kings Monitoring se připojuje k MySQL nebo MariaDB databázi pomocí PDO. Údaje nastavte v souboru status/config.php:

define('DB_HOST', '127.0.0.1');
define('DB_NAME', 'bloodkings_status');
define('DB_USER', 'bloodkings_user');
define('DB_PASS', 'VaseSilneHeslo123!');
define('TIMEZONE', 'Europe/Prague');

Proměnné Prostředí a Tokeny

Klíčové bezpečnostní tokeny se definují přímo v config.php nebo v prostředí serveru:

  • cron_key: Tajný klíč pro autorizaci spouštění cron.php z externích služeb a webhooků.
  • agent_registration_token: Sdílené heslo autorizující automatickou auto-registraci nově nainstalovaných agentů.
  • metrics_token: Bearer token chránící Prometheus endpoint metrics.php.

Veřejné Status Stránky a Branding

Vzhled veřejných status stránek upravíte v Administraci (Nastavení -> Branding). Můžete nahrát vlastní logo, nastavit barvy a konfiguraci 24h / 7d / 30d SLA agregační souborové cache.

Heartbeat monitory

Aktivní kontrola umí jen to, na co dosáhne ze sítě. Záloha, která se spustí ve tři ráno a tiše selže, je pro ni neviditelná - není co pingnout. Heartbeat obrací směr: úloha se hlásí sama a monitor spadne ve chvíli, kdy se neozve.

Založte monitor typu Heartbeat, nastavte, jak často se má úloha ozvat, a na její konec přidejte adresu, kterou dostanete:

curl -fsS -m 10 "https://vas-server/status/heartbeat.php?token=VAS_TOKEN"

Když úloha selže, ať to řekne rovnou - monitor pak spadne hned, ne až po vypršení intervalu:

curl -fsS -m 10 "https://vas-server/status/heartbeat.php?token=VAS_TOKEN&status=fail&msg=tar%20skoncil%20kodem%202"

Monitor, který ještě nikdy nedostal signál, hlásí neznámý stav, ne výpadek. Nic neselhalo - jen o něm zatím nic nevíme, a upozornění na výpadek, který se nestal, je svého druhu lež.

Token je jediné, co endpoint autorizuje. Nepouštějte ho do sdílených logů: kdo ho má, může se hlásit za vás a monitor bude svítit zeleně, i když záloha dávno neběží.

Hlídač: kdo hlídá sběr dat

Všechno sbírá jediná cron úloha. Když umře, aplikace se nerozbije - dál zobrazuje poslední známé stavy a vypadá naprosto zdravě. Ze všech způsobů, jak může monitoring selhat, je tenhle nejhorší, protože o sobě nedá vědět.

Server proto zaznamenává každý dokončený běh a vystavuje ho:

curl -s "https://vas-server/status/api.php?action=collection_health"

Odpověď má stale: true, jakmile je poslední běh starší než nastavený limit - a také tehdy, když cron neběžel ještě ani jednou, protože „žádná data" není totéž co „vše v pořádku".

Ten endpoint kontroluje Cloudflare Worker každých pět minut. Běží mimo hlídaný server záměrně: hlídač na stejném stroji umře spolu s tím, co hlídá. Stačí mu jednou nastavit Discord webhook a ozve se sám:

cd apps/worker && npx wrangler secret put WATCHDOG_DISCORD_WEBHOOK

Bez toho hlídač kontroluje dál, ale umí jen logovat - a přizná to na /api/watchdog, místo aby jen budil dojem, že něco hlídá.

Instalace a Registrace Agenta

Agenti jsou samostné telemetrické skripty dostupné pro Linux (Bash), Python, PowerShell a OpenWrt routery. Auto-registraci spustíte s tokenem serveru:

./agent.sh --register --token="VásRegistračníToken" --url="https://monitoring.bloodkings.eu/status/agent_api.php"

Intervaly Agenta a Vzdálené Akce

Agent spouští měření v nastavitelném intervalu (výchozí: 60 sekund). Na OpenWrt routerech lze zapnout opt-in HMAC podepsané Vzdálené akce nastavením REMOTE_ACTIONS_ENABLED=1 v konfiguraci agenta.

Řešení Problémů s Agenty

Pokud agent přestane hlásit data, zkontrolujte odchozí přístup na port 443 a nahlédněte do logů:

# Kontrola logů systemd služby agenta
journalctl -u bloodkings-agent -n 50 --no-pager