Blood Kings Monitoring
ENCS
Instalace
Na této stránce

Dokumentace

Instalace serveru, přidání monitorů a připojení agentů.

Příručka

Rychlý start

Takhle nainstalujete centrální server na běžný PHP webhosting. Je to stejný návod jako na stránce ke stažení.

Změřená doba instalace: 1 min (od ZIPu vydání po první běh sběru dat na čistém serveru s PHP 8.2 a MySQL, podle tohoto návodu; nahrávání přes FTP a klikání v administraci hostingu jde navíc)

  1. Ověřte, co hosting nabízí

    • PHP 8.2 nebo novější s rozšířeními PDO MySQL, cURL, mbstring a OpenSSL
    • Databáze MySQL nebo MariaDB
    • Cron každou minutu (stačí Cron Jobs v cPanelu)
    • Apache s .htaccess a mod_rewrite, jako na většině sdílených hostingů
    • Jedna doména nebo subdoména, v jejímž kořeni leží /status i /app: aplikace mluví s /status na stejném hostu
    • Odchozí HTTP a HTTPS z hostingu, pro kontroly

    Umístěte ho mimo síť, kterou hlídáte. Server doma spadne s domácí linkou a pak už vám to nemá kdo říct.

  2. Stáhněte a nahrajte

    Stáhnout bloodkings-monitoring.zipSHA256SUMS

    Poslední vydání: —

    Rozbalte ho a nahrajte status/ do public_html/status/ a app/ do public_html/app/. Soubor app/.htaccess nevynechávejte: bez něj skončí obnovení stránky uvnitř aplikace chybou 404. Stažený soubor ověříte proti zveřejněnému kontrolnímu součtu tak, že SHA256SUMS uložíte vedle ZIPu a spustíte:

    sha256sum -c SHA256SUMS --ignore-missing

    Ještě žádné vydání? Sestavte obě složky ze zdrojů

    S gitem a Node.js 22 na svém počítači:

    git clone --recursive https://github.com/BKPepe/monitoring.git
cd monitoring
npm ci
npm run build -w apps/monitor
cp agents/vps-agent/agent.sh agents/vps-agent/agent.py agents/vps-agent/agent.ps1 \
   agents/vps-agent/agent_openwrt.sh agents/vps-agent/docker-compose.agent.yml apps/status/

    Pak nahrajte apps/status/ (bez složky tests/) jako status/ a apps/monitor/dist/ (i s jeho .htaccess) jako app/. Agenti patří vedle agent_api.php: odtud se stahují a odtud se i sami aktualizují.

  3. Založte prázdnou databázi

    Založte databázi MySQL nebo MariaDB a uživatele se všemi právy k ní (v cPanelu: MySQL Databases) a poznamenejte si název, uživatele a heslo. Nechte ji prázdnou: tabulky založí instalátor. Jen když chcete všechno udělat ručně, naimportujte status/schema.sql sami:

    mysql -u YOUR_DB_USER -p YOUR_DB_NAME < schema.sql

  4. Spusťte instalátor

    Otevřete https://YOUR-DOMAIN/app/setup. Zkontroluje PHP, vyzkouší přihlášení k databázi, zapíše status/config.php (nebo soubor ukáže k nahrání, když do složky PHP zapisovat nesmí), založí tabulky a pak prvního správce. Žádný výchozí účet ani heslo neexistuje a jakmile účet je, instalátor se znovu nespustí. Do té doby ho může spustit kdokoli, kdo adresu najde, proto databázi založte ještě před nahráním a instalátor spusťte hned po něm. Ručně místo toho: ve složce status/ zkopírujte config.sample.php na config.php a vyplňte připojení:

    define('DB_HOST', 'localhost');
define('DB_PORT', 3306);
define('DB_NAME', 'YOUR_DB_NAME');
define('DB_USER', 'YOUR_DB_USER');
define('DB_PASS', 'YOUR_DB_PASSWORD');

    Volitelné klíče patří do stejného souboru jako konstanty velkými písmeny, nebo později do aplikace v Nastavení: CRON_KEY, AGENT_REGISTRATION_TOKEN a METRICS_TOKEN. Instalátor dá každé nové instalaci vlastní CRON_KEY. Při ruční cestě zůstane prázdný, dokud ho nenastavíte, a dokud je prázdný, spustí sběr dat kdokoli, kdo zná adresu cron.php.

    config.php obsahuje heslo k databázi. V ZIPu není a nahrání nového vydání ho nepřepíše.

  5. Spouštějte sběr dat každou minutu

    Všechny kontroly spouští jeden cron. Poslední krok instalátoru ukáže tenhle řádek se skutečnou cestou k PHP a k cron.php na vašem serveru. V cPanelu otevřete Cron Jobs, zvolte Once Per Minute (* * * * *) a příkaz vložte do pole Command. USER je váš účet na hostingu; domovskou složku ukazuje cPanel na hlavní stránce.

    php -q /home/USER/public_html/status/cron.php >/dev/null 2>&1

    Bez cPanelu je to stejná úloha jako řádek pro crontab -e:

    * * * * * php -q /home/USER/public_html/status/cron.php >/dev/null 2>&1

  6. Přihlaste se

    Přihlaste se na https://YOUR-DOMAIN/app/ účtem, který založil instalátor. Po ruční cestě ten první účet místo toho založí /app/setup.

  7. Ověřte, že běží

    Instalátor na první běh sběru dat počká a po něm zezelená, do minuty od přidání cronu. Později, nebo po ruční cestě, to ověříte takhle (adresa se dá otevřít i v prohlížeči):

    curl -s "https://YOUR-DOMAIN/status/api.php?action=collection_health"

    Hledejte čas v lastRunAt a "stale": false. "stale": true s lastRunAt null znamená, že sběr ještě nikdy neběžel: zkontrolujte řádek cronu a cestu v něm.

    Dál: v aplikaci přidejte monitory a na stroje a routery, do kterých chcete vidět, agenty. Instalace agenta →

Pak: první monitor

V aplikaci otevřete Infrastruktura → Přidat nový monitor. Hlídat můžete weby (HTTP/HTTPS), TCP porty, servery Minecraft, TeamSpeak a Discord, servery a routery OpenWrt s agentem, nebo heartbeaty úloh, které se hlásí samy. Starší PHP administrace (admin.php) je převážně česky; přehled na /app mluví česky i anglicky.

Systémové požadavky

Centrální server je čisté PHP a běží na běžném sdíleném webhostingu, VPS stačí také. Co musí hosting nabízet, je první krok Rychlého startu.

Centrální Server:

  • Místo na disku: aplikace a databáze MySQL/MariaDB, která roste s historií kontrol
  • Software: PHP 8.2+ (CI běží na 8.4), Apache s .htaccess a mod_rewrite a MySQL nebo MariaDB. Server běží bez Dockeru; možnost Dockeru má jen Python agent.

Vzdálený Agent:

  • OS: Linux (libovolná distribuce s Bashem, nebo s Pythonem 3), Windows 10/11/Server, OpenWrt/Turris OS, Raspberry Pi OS
  • Síť: odchozí HTTPS (port 443) k centrálnímu serveru; nic příchozího

Architektura systému

Blood Kings Monitoring spojuje aktivní kontroly, které spouští server, a hlášení, která mu posílají agenti.

Vzdálený Agent(Linux, OpenWrt, Windows, Docker)↓ HTTPS POST (Metrics)
Centrální Server(PHP / MySQL nebo MariaDB)↓ JSON API
Veřejná Status Stránka(aplikace na /app/public)

Pasivní monitoring (Agenti): Agenta na hlídaném stroji spouští cron (nebo Plánovač úloh): na OpenWrt každou minutu, jinde standardně každých 5 minut. Každý běh přečte lokální data (CPU, RAM, disky, síť) 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): Cron centrálního serveru kontroluje cíle přímo: požadavky HTTP/HTTPS (s volitelným klíčovým slovem a expirací certifikátu) a TCP spojení. ICMP ping ani kontroly UDP neumí; „ping“ je TCP spojení.

Konfigurace Databáze Serveru

Server se k MySQL nebo MariaDB připojuje přes PDO. Připojení zapíše do status/config.php instalátor na /app/setup (4. krok Rychlého startu, kde je i ruční cesta). Ostatní konstanty vysvětluje config.sample.php; nejčastěji se mění časové pásmo, které pak sdílí PHP i databázové spojení:

define('TIMEZONE', 'Europe/Prague');

Klíče a tokeny

Tři volitelné klíče. Každý se čte jako konstanta v config.php (velkými písmeny), pak jako proměnná prostředí a pak z Nastavení aplikace; platí první nalezený.

  • CRON_KEY: klíč, který cron.php chce při volání přes HTTP (?key=...). Dokud je prázdný, spustí sběr dat kdokoli, kdo zná adresu; cron z příkazové řádky klíč nepotřebuje. Instalátor dá každé nové instalaci vlastní.
  • AGENT_REGISTRATION_TOKEN: dovolí agentům pro Bash a OpenWrt, aby se zaregistrovali sami (--register). Dokud je prázdný, server místo něj přijme CRON_KEY.
  • METRICS_TOKEN: bearer token pro endpoint Promethea metrics.php. Dokud je prázdný, endpoint je vypnutý.
define('CRON_KEY', 'dlouhy-nahodny-retezec');

Veřejné Status Stránky

Status stránky založíte v aplikaci v části Status Stránky: každá má vlastní název, adresu (/app/public?page=…) a výběr monitorů a dá se před veřejností skrýt. Návštěvníci se tam mohou přihlásit k e-mailům o incidentech. SVG odznak veřejného stavu nebo jednoho monitoru (api.php?action=badge&monitor_id=…) lze vložit kamkoli.

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á.

Worker v release ZIPu není: leží v apps/worker v repozitáři a nasadíte ho do vlastního účtu Cloudflare. Bez cíle hlídá bloodkings.eu, server autora, takže mu nejdřív dejte ten svůj:

cd apps/worker && npx wrangler deploy
npx wrangler secret put WATCHDOG_TARGET_URL   # https://vas-server/status/api.php?action=collection_health

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 samostatné skripty pro Bash, Python, PowerShell a routery s OpenWrt. Postup pro každou platformu je na stránce ke stažení: tytéž kroky, které aplikace vypíše při přidání monitoru, tam s vaší adresou a klíčem.

Pro víc strojů se agenti pro Bash a OpenWrt umí zaregistrovat sami registračním tokenem (viz Klíče a tokeny). Oba argumenty jsou poziční a druhý je agent_api.php vašeho serveru:

/opt/bk-agent/agent.sh --register YOUR_REGISTRATION_TOKEN https://YOUR-DOMAIN/status/agent_api.php

Bez adresy se agent registruje proti výchozímu localhost. Klíč, který dostane, uloží do agent.cfg vedle skriptu (na routeru do agent_openwrt.cfg). Agenti pro Python a PowerShell registrační příkaz nemají: API_URL a AGENT_KEY z nastavení monitoru berou z agent.cfg. Víc o registraci.

Intervaly Agenta a Vzdálené Akce

Agenty spouští cron: na serverech každých 5 minut, na OpenWrt routerech každou minutu. Na OpenWrt routerech lze zapnout opt-in HMAC podepsané Vzdálené akce nastavením REMOTE_ACTIONS_ENABLED=1 v agent_openwrt.cfg vedle skriptu.

Řešení Problémů s Agenty

Pokud agent přestane hlásit data, zkontrolujte odchozí přístup na port 443, pak ho spusťte ručně a přečtěte jeho log (leží vedle skriptu):

/opt/bk-agent/agent.sh --verbose
tail -n 50 /opt/bk-agent/agent.log

Stejné kontroly pro OpenWrt, Windows a Docker jsou na stránce ke stažení.