Gostovanje Umami na Managed VPS: vaša spletna analitika na vašem strežniku

Kaj počne Umami

Umami je odprtokodna platforma za spletno in produktno analitiko. Njegova dokumentacija opisuje orodje, ki združuje obisk, kampanje, vedenje obiskovalcev, konverzije, zadrževanje in prihodke, od prvega obiska do rezultatov, ki štejejo za vaše podjetje. Napisan je v TypeScriptu na Next.js, njegova slika Docker pa teče pod neprivilegiranim računom.

• Pridobivanje: ogledi strani, obiskovalci, napotitelji, države, naprave in dejavnost v realnem času, s kampanjami UTM, kratkimi povezavami in sledilnimi slikovnimi pikami.
• Vedenje: dogodki po meri, poti, posnetki sej, toplotni zemljevidi, segmenti, kohorte in zadrževanje.
• Konverzija: cilji, lijaki, pripisovanje in spremljanje prihodkov po straneh in kampanjah.
• Deljenje: nadzorne plošče, ekipe, javni URL za deljenje, API in strežnik MCP samo za branje za vašega AI pomočnika.
• Sodobna spletišča: pogosta vprašanja navajajo, da Umami premikanje po straneh v enostranskih aplikacijah spremlja sam, brez dodatne nastavitve.

Ena instanca spremlja več spletišč: vsako dobi svoj identifikator in sledilni skript, vaši sodelavci pa se znajdejo prek računov in ekip.

Kaj dovoljuje licenca MIT

Umami je objavljen pod licenco MIT, v imenu Umami Software, Inc. Ta brezplačno podeljuje pravico do uporabe, kopiranja, spreminjanja, združevanja, objave, razširjanja, podlicenciranja in prodaje kopij programske opreme. Poganjate ga torej lahko za svoje podjetje in za spletišča svojih strank, ne da bi morali kupiti licenco.

Njen edini pogoj: obvestilo o avtorskih pravicah in obvestilo o dovoljenju spremljata vse kopije ali bistvene dele programske opreme. Kot vsaka licenca MIT programsko opremo ponuja „takšno, kot je“, brez garancije.

Piškotki in osebni podatki: kaj pravi projekt

Dokumentacija Umami predstavlja kot analitiko brez piškotkov, brez sledenja med spletišči in brez samodejnega zbiranja osebnih podatkov. Ko ga gostite sami, vaša analitika ostane na vašem strežniku: vi odločate, kje živi in kako dolgo ostane.

Tri nastavitve sledilnega skripta gredo po želji še dlje: data-exclude-search iz zabeleženih URL-jev odstrani iskalne parametre, data-exclude-hash odstrani zgoščeni del (hash), data-do-not-track pa izklopi sledenje za brskalnike, ki izražajo nastavitev Do Not Track. Dokumentacija pripominja, da ta zadnja nastavitev sama po sebi ni celovita rešitev za upravljanje privolitev.

Če prijavljene obiskovalce prepoznavate z data-distinct-id ali umami.identify(), dokumentacija namesto e-poštnega naslova priporoča notranji identifikator uporabnika ali zgoščeno vrednost: vrednost je mogoče prebrati v HTML strani.

Namestitev z Docker Compose in PostgreSQL

Repozitorij vsebuje docker-compose.yml, ki zažene Umami in njegovo zbirko PostgreSQL. Od različice 3 je PostgreSQL edina podprta zbirka, najmanj v različici 12.14, dokumentacija pa priporoča, da jo nastavite na časovni pas UTC. Na strežniku z nameščenim Dockerjem ustvarite mapo in začnite z njenimi skrivnostmi, naključno ustvarjenimi z openssl, kot predlaga dokumentacija:

cat > .env <<EOF
POSTGRES_PASSWORD=$(openssl rand -hex 24)
APP_SECRET=$(openssl rand -hex 32)
TWO_FACTOR_ENCRYPTION_KEY=$(openssl rand -hex 32)
EOF
chmod 600 .env

Nato poleg nje postavite ta compose.yaml. Sledi datoteki projekta v različici 3.4.1, z dvema spremembama: skrivnosti prihajajo iz datoteke .env, vrata pa so objavljena le na 127.0.0.1.

services:
  umami:
    image: ghcr.io/umami-software/umami:latest
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:${POSTGRES_PASSWORD}@db:5432/umami
      APP_SECRET: ${APP_SECRET}
      TWO_FACTOR_ENCRYPTION_KEY: ${TWO_FACTOR_ENCRYPTION_KEY}
    depends_on:
      db:
        condition: service_healthy
    init: true
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
      interval: 5s
      timeout: 5s
      retries: 5
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
volumes:
  umami-db-data:

docker compose up -d
curl -s http://127.0.0.1:3000/api/heartbeat

• DATABASE_URL: edina obvezna spremenljivka, povezovalni niz zbirke. Šestnajstiško geslo gre vanjo tako, kot je; geslo s posebnimi znaki bi zahtevalo odstotno kodiranje.
• APP_SECRET: naključen niz, ki ščiti žetone za overjanje, edinstven za vsako namestitev. V kodi različice 3.4.1 vstopa tudi v izračun identifikatorjev sej: ohranite ga nespremenjenega.
• TWO_FACTOR_ENCRYPTION_KEY: 64 šestnajstiških znakov, ki šifrirajo skrivnosti dvostopenjskega preverjanja pristnosti. Brez njega nihče ne more vključiti dvostopenjskega preverjanja pristnosti.
• Ob zagonu vsebnik preveri povezavo z zbirko in njeno različico, nato sam izvede migracije sheme. Ob prvem zagonu ustvari tabele in račun admin. Sonda /api/heartbeat odgovori {"ok":true}, ko je Umami pripravljen.
• Oznaka latest sledi zadnji objavljeni izdaji. Register projekta objavlja tudi oznake različic, kot je 3.4.1, s katerimi določite tisto, ki jo poganjate.

Dokumentacija o namestitvi ne navaja potrebnega pomnilnika ali procesorja. Velikost je odvisna od obiska spremljanih spletišč in obsega podatkov, ki jih hranite. Na Managed VPS nam opišite svojo rabo in priporočimo vam ustrezno velikost.

HTTPS: obratni posredniški strežnik

Umami posluša prek HTTP na vratih 3000, dokumentacija pa predlaga, da ga strežete za svojim spletnim strežnikom, prek obratnega posredniškega strežnika. Dajte mu lastno poddomeno, kot je stats.example.com, ki z zapisoma A in AAAA kaže na strežnik. Streženje programa Umami pod potjo poteka prek BASE_PATH, spremenljivke, ki se prebere ob gradnji aplikacije: z objavljeno sliko je poddomena neposredna pot.

Posredniški strežnik mora posredovati tudi naslov obiskovalca. Umami ga prebere iz glav, ki jih prejme, med njimi X-Real-IP in X-Forwarded-For: z njim razlikuje obiskovalce in ugotovi njihovo državo. Če vaš posredniški strežnik uporablja drugo glavo, jo poimenuje CLIENT_IP_HEADER.

S Caddyjem

Caddy sam pridobi potrdilo Let’s Encrypt in vključi HTTPS. Njegova direktiva reverse_proxy privzeto nastavi X-Forwarded-For: te tri vrstice so vse, kar potrebujete.

stats.example.com {
  reverse_proxy 127.0.0.1:3000
}

Z Nginxom in Certbotom

Ta blok sledi primeru Nginx iz dokumentacije Umami in posluša na vratih 80, da lahko Certbot vzpostavi HTTPS:

server {
  listen 80;
  listen [::]:80;
  server_name stats.example.com;

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

Certbot nato namesti potrdilo in poskrbi za njegovo obnavljanje:

sudo certbot --nginx

Prva prijava: skrbniški račun in dvostopenjsko preverjanje pristnosti

Ko ustvari svojo zbirko, Umami odpre skrbniški račun: uporabniško ime admin, geslo umami. Dokumentacija prosi, naj to geslo spremenite ob prvi prijavi.

1. Odprite svoj naslov HTTPS in se prijavite z admin in umami.
2. Z gumbom profila v stranski vrstici odprite Settings, nato Profile, in kliknite Change password.
3. V zavihku Security vključite dvostopenjsko preverjanje pristnosti: kodo QR skenirajte s svojo aplikacijo za preverjanje pristnosti, vpišite šestmestno kodo, nato deset rezervnih kod shranite na varno, saj se pokažejo le enkrat.

• Obvezno dvostopenjsko preverjanje pristnosti: skrbnik ga lahko zahteva za vso instanco, za enega uporabnika ali za eno ekipo, s skrbniških strani.
• Poskusi: pet napačnih kod nadaljnje poskuse zaklene za 15 minut.
• Računi vaše ekipe: skrbniške strani upravljajo uporabnike, spletišča in ekipe vse instance.

TWO_FACTOR_ENCRYPTION_KEY hranite skupaj s svojimi varnostnimi kopijami: dokumentacija opozarja, da izguba ali sprememba tega ključa naredi shranjene skrivnosti neberljive, vsak uporabnik pa se mora nato znova vpisati v dvostopenjsko preverjanje pristnosti.

Dodajanje spletišča in njegovega sledilnega skripta

1. V Websites kliknite Add website.
2. Spletišču dajte ime, nato njegovo domeno: Umami z njo iz seznama napotiteljev izloči vaše lastne strani.
3. Pri tem spletišču odprite Edit in kopirajte kodo iz razdelka Tracking code.
4. Prilepite jo v <head> svojih strani, nato obiščite svoje spletišče: podatki se takoj pojavijo na nadzorni plošči.

<script defer src="https://stats.example.com/script.js" data-website-id="your-website-id"></script>

• Se nič ne pokaže? Dokumentacija predlaga zavihek omrežje v razvijalskih orodjih brskalnika: zahteve na vašo instanco morajo oditi brez napak.
• Next.js: kodo dodajte s komponento next/script namesto z navadno oznako <script>.
• data-domains sledenje omeji na vaše produkcijske domene, kar vaša preizkusna okolja ohrani zunaj statistike.
• Vaši lastni obiski se izločijo spletišče za spletiščem, iz konzole brskalnika, z localStorage.setItem('umami.disabled', 1).

Lastno ime skripta

Nekateri zaviralci oglasov blokirajo vse, kar je videti kot analitika. Pri samostojnem gostovanju se Umami že streže z vaše lastne domene, dve spremenljivki pa gresta še dlje: TRACKER_SCRIPT_NAME skriptu da drugo ime kot script.js, COLLECT_API_ENDPOINT pa preimenuje končno točko za zbiranje, namesto /api/send. Skript nato sam kliče novo končno točko; na vaših straneh se spremeni le vir sledilne kode.

TRACKER_SCRIPT_NAME: "stats.js"
COLLECT_API_ENDPOINT: "/api/collect"

Koristne nastavitve

Te spremenljivke okolja gredo v storitev umami datoteke compose.yaml, nato docker compose up -d znova ustvari vsebnik, da jih upošteva:

Varnostne kopije

Vse, kar Umami hrani, živi v njegovi zbirki PostgreSQL: računi, spletišča, ekipe in analitika. Izvozite jo vsak dan in tik pred vsako posodobitvijo: pri samostojnem gostovanju se ti podatki hranijo brez časovne omejitve. Poleg zbirke datoteka .env hrani skrivnosti, ki jo naredijo uporabno:

Izvoz zbirke med delovanjem

pg_dump naredi dosleden izvoz, medtem ko je zbirka v uporabi. Format po meri, -Fc, je stisnjen in se obnovi s pg_restore:

docker compose exec -T db pg_dump -U umami -d umami -Fc > umami-$(date +%F).dump

Ta ukaz na strežniku načrtujte vsaj enkrat na dan, med izvozi, ki se kopičijo, redno delajte red in kopijo pošljite drugam. Shranjeni na disku strežnika ti izvozi vstopijo tudi v njegove nočne varnostne kopije.

Obnova

1. Ustavite Umami, zbirka pa naj teče naprej: docker compose stop umami.
2. Izvoz obnovite v zbirko, z zamenjavo obstoječih objektov.
3. Znova zaženite Umami, nato preverite, da so vaša spletišča in njihova analitika na mestu.

docker compose stop umami
docker compose exec -T db pg_restore -U umami -d umami --clean --if-exists < umami-YYYY-MM-DD.dump
docker compose start umami

To vajo občasno ponovite, na kopiji: tako preverite, da varnostna kopija deluje.

Posodobitve

Dokumentacija navaja dva ukaza, ki ju zaženete v mapi datoteke compose.yaml. Zbirka ostane v svojem nosilcu:

docker compose pull
docker compose up --force-recreate -d

Ob ponovnem zagonu vsebnik sam izvede migracije sheme. Različica 3.4.0 s 17. septembra 2026 jih je prinesla dve, za opombe in ključe API; različica 3.4.1 s 23. oktobra 2026 ne prinaša nobene. Po veliki nadgradnji, kot je prehod na različico 3, dokumentacija predlaga, da v PostgreSQL zaženete ANALYZE, da nadzorne plošče znova dobijo svojo hitrost:

docker compose exec db psql -U umami -d umami -c "ANALYZE;"

• Opombe k izdajam povedo, kaj spremeni vsaka različica. Različica 3.4.1 je nujen varnostni popravek, ki posodobi Next.js in osnovno sliko Node.js; njene opombe prosijo vse samostojno gostovane instance, naj nadgradijo s ponovnim prenosom slike.
• Z različice 2 na MySQL: različica 3 MySQL ne podpira več. Vodnik za selitev projekta podatke prenese v PostgreSQL na različici 2.19.0, pred nadgradnjo na različico 3.
• PostgreSQL sam: ohranite oznako postgres:15-alpine iz datoteke. Prehod na novo glavno različico PostgreSQL zahteva izvoz in obnovo ali pg_upgrade.

Kdo kaj dela na Managed VPS

Samostojno gostovanje poleg aplikacije zahteva tudi vzdrževanje strežnika. Na Managed VPS naše ekipe prevzamejo strežnik in proaktivno spremljajo vašo instanco; Umami ostaja vaša programska oprema, z vašimi nastavitvami in podatki.

Če želite, da naše ekipe posežejo v samo aplikacijo, se ta storitev zaračuna po urah ali pavšalno, z oceno stroškov, sporočeno pred posegom.