Umami majutamine Managed VPS-is: teie veebianalüütika teie enda serveris

Mida Umami teeb

Umami on avatud lähtekoodiga veebi- ja tooteanalüütika platvorm. Selle dokumentatsioon kirjeldab tööriista, mis toob kokku liikluse, kampaaniad, külastajate käitumise, konversioonid, püsimise ja tulu, alates esimesest külastusest kuni tulemusteni, mis teie ettevõttele olulised on. See on kirjutatud TypeScriptis Next.js-i peal ja selle Dockeri tõmmis töötab privileegideta kontoga.

• Hankimine: lehevaatamised, külastajad, viitajad, riigid, seadmed ja reaalajas tegevus, koos UTM-kampaaniate, lühilinkide ja jälgimispikslitega.
• Käitumine: kohandatud sündmused, teekonnad, seansside taasesitused, soojuskaardid, segmendid, kohordid ja püsimine.
• Konversioon: eesmärgid, lehtrid, omistamine ja tulu jälgimine lehe ja kampaania kaupa.
• Jagamine: tahvlid, meeskonnad, avalik jagamis-URL, API ja ainult lugemiseks mõeldud MCP-server teie tehisintellekti assistendile.
• Kaasaegsed saidid: KKK kinnitab, et Umami jälgib üheleherakendustes lehtedevahelist navigeerimist ise, ilma lisasätteta.

Üks instants jälgib mitut veebisaiti: igaüks saab oma ID ja jälgimisskripti ning teie kolleegid leiavad end kontode ja meeskondade kaudu üles.

Mida MIT-litsents lubab

Umami avaldatakse MIT-litsentsi all, ettevõtte Umami Software, Inc. nimel. See annab tasuta õiguse tarkvara koopiaid kasutada, kopeerida, muuta, ühendada, avaldada, levitada, all-litsentsida ja müüa. Seega võite seda käitada oma ettevõtte ja klientide veebisaitide jaoks, ilma et peaksite litsentsi ostma.

Selle ainus tingimus: autoriõiguse teade ja loa teade kaasnevad tarkvara kõigi koopiate või oluliste osadega. Nagu iga MIT-litsents, pakub see tarkvara «nagu on», ilma garantiita.

Küpsised ja isikuandmed: mida projekt ütleb

Dokumentatsioon tutvustab Umamit kui analüütikat ilma küpsisteta, ilma saitideülese jälgimiseta ja ilma isikuandmete automaatse kogumiseta. Ise majutatuna jääb teie analüütika teie enda serverisse: teie otsustate, kus see asub ja kui kaua seda hoitakse.

Soovi korral lähevad kolm jälgimisskripti sätet kaugemale: data-exclude-search eemaldab salvestatud URL-idest otsinguparameetrid, data-exclude-hash eemaldab räsiosa ja data-do-not-track lülitab jälgimise välja brauserites, mis edastavad eelistuse Do Not Track. Dokumentatsioon märgib, et see viimane säte ei ole üksi täielik nõusolekuhalduse lahendus.

Kui tuvastate sisselogitud külastajaid atribuudiga data-distinct-id või funktsiooniga umami.identify(), soovitab dokumentatsioon e-posti aadressi asemel sisemist kasutaja ID-d või räsi: väärtust saab lehe HTML-ist lugeda.

Paigaldus Docker Compose’i ja PostgreSQL-iga

Hoidlaga tuleb kaasa fail docker-compose.yml, mis käivitab Umami ja selle PostgreSQL-i andmebaasi. Alates versioonist 3 on PostgreSQL ainus toetatud andmebaas, vähemalt versioon 12.14, ja dokumentatsioon soovitab seada selle ajavööndiks UTC. Looge serveris, kuhu Docker on paigaldatud, kaust ja alustage selle saladustest, mis luuakse juhuslikult käsuga openssl, nagu dokumentatsioon soovitab:

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

Pange seejärel selle kõrvale see compose.yaml. See järgib projekti faili versioonis 3.4.1, kahe muudatusega: saladused tulevad failist .env ja port avaldatakse ainult aadressil 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: ainus kohustuslik muutuja, andmebaasi ühendusstring. Kuueteistkümnendsüsteemis parool läheb sinna nii, nagu on; erimärkidega parool vajaks protsendikodeeringut.
• APP_SECRET: juhuslik string, mis kaitseb autentimismärke, iga paigalduse jaoks ainulaadne. Versiooni 3.4.1 koodis osaleb see ka seansi ID-de arvutamises: hoidke see muutumatuna.
• TWO_FACTOR_ENCRYPTION_KEY: 64 kuueteistkümnendmärki, mis krüpteerivad kaksikautentimise saladused. Ilma selleta ei saa keegi kaksikautentimist lubada.
• Käivitamisel kontrollib konteiner andmebaasi ühendust ja versiooni ning rakendab seejärel skeemi migratsioonid ise. Esimesel käivitamisel loob see tabelid ja konto admin. Sond /api/heartbeat vastab {"ok":true}, kui Umami on valmis.
• Silt latest järgib viimati avaldatud väljalaset. Projekti register avaldab ka versioonisilte, näiteks 3.4.1, et fikseerida käitatav versioon.

Paigaldusdokumentatsioon ei too välja mälu ega protsessori mahtu. Suurus sõltub jälgitavate veebisaitide liiklusest ja säilitatavate andmete mahust. Managed VPS-is rääkige meile oma kasutusest ja soovitame sobiva suuruse.

HTTPS: pöördproksi

Umami kuulab HTTP kaudu pordil 3000 ja dokumentatsioon soovitab teenindada seda teie veebiserveri taga, pöördproksi kaudu. Andke sellele oma alamdomeen, näiteks stats.example.com, mis viitab serverile A- ja AAAA-kirjetega. Umami teenindamine teel käib muutujaga BASE_PATH, mida loetakse rakenduse ehitamisel: avaldatud tõmmisega on alamdomeen otsetee.

Proksi peab edastama ka külastaja aadressi. Umami loeb selle saadud päistest, sealhulgas X-Real-IP ja X-Forwarded-For: see kasutab seda külastajate eristamiseks ja nende riigi määramiseks. Kui teie proksi kasutab muud päist, nimetab selle CLIENT_IP_HEADER.

Caddy-ga

Caddy hangib Let’s Encrypti sertifikaadi ja lubab HTTPS-i ise. Selle direktiiv reverse_proxy seab vaikimisi päise X-Forwarded-For: neist kolmest reast piisab.

stats.example.com {
  reverse_proxy 127.0.0.1:3000
}

Nginxi ja Certbotiga

See plokk järgib Umami dokumentatsiooni Nginxi näidet ja kuulab pordil 80, et Certbot saaks HTTPS-i paigaldada:

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 paigaldab seejärel sertifikaadi ja hoolitseb selle uuendamise eest:

sudo certbot --nginx

Esimene sisselogimine: administraatori konto ja kaksikautentimine

Andmebaasi loomisel avab Umami administraatori konto: kasutajanimi admin, parool umami. Dokumentatsioon palub seda parooli esimesel sisselogimisel muuta.

1. Avage oma HTTPS-aadress ja logige sisse andmetega admin ja umami.
2. Avage külgriba profiilinupust Settings, seejärel Profile, ja klõpsake Change password.
3. Lubage vahekaardil Security kaksikautentimine: skannige QR-kood oma autentimisrakendusega, sisestage kuuekohaline kood ja hoidke seejärel kümme varukoodi turvalises kohas, sest neid näidatakse ainult üks kord.

• Kaksikautentimise nõudmine: administraator saab seda nõuda kogu instantsi, ühe kasutaja või ühe meeskonna jaoks, halduslehtedelt.
• Katsed: viis valet koodi lukustavad edasised katsed 15 minutiks.
• Teie meeskonna kontod: halduslehed haldavad kogu instantsi kasutajaid, veebisaite ja meeskondi.

Hoidke TWO_FACTOR_ENCRYPTION_KEY koos oma varukoopiatega: dokumentatsioon hoiatab, et selle võtme kaotamine või muutmine muudab salvestatud saladused loetamatuks ja iga kasutaja peab siis kaksikautentimise uuesti seadistama.

Veebisaidi ja selle jälgimisskripti lisamine

1. Klõpsake jaotises Websites nuppu Add website.
2. Andke veebisaidile nimi ja seejärel selle domeen: Umami kasutab seda teie enda lehtede väljajätmiseks viitajate loendist.
3. Avage selle veebisaidi juures Edit ja kopeerige kood jaotisest Tracking code.
4. Kleepige see oma lehtede jaotisse <head> ja külastage seejärel oma veebisaiti: andmed ilmuvad töölauale kohe.

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

• Midagi ei ilmu? Dokumentatsioon soovitab brauseri arendustööriistade võrgulehte: päringud teie instantsi peavad minema välja vigadeta.
• Next.js: lisage kood komponendiga next/script, mitte lihtsa sildiga <script>.
• data-domains piirab jälgimise teie tootmisdomeenidega, mis hoiab teie testkeskkonnad statistikast väljas.
• Teie enda külastused jäetakse välja veebisaidi kaupa, brauseri konsoolist, käsuga localStorage.setItem('umami.disabled', 1).

Teie oma skriptinimi

Mõned reklaamiblokeerijad blokeerivad kõike, mis meenutab analüütikat. Ise majutatuna serveeritakse Umamit juba teie enda domeenilt ja kaks muutujat lähevad kaugemale: TRACKER_SCRIPT_NAME annab skriptile muu nime kui script.js ja COLLECT_API_ENDPOINT nimetab kogumise lõpp-punkti ümber, aadressi /api/send asemel. Skript kutsub siis uut lõpp-punkti ise; teie lehtedel muutub ainult jälgimiskoodi allikas.

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

Kasulikud sätted

Need keskkonnamuutujad lähevad faili compose.yaml teenusesse umami ja seejärel loob docker compose up -d konteineri uuesti, et neid arvestada:

Varukoopiad

Kõik, mida Umami hoiab, asub selle PostgreSQL-i andmebaasis: kontod, veebisaidid, meeskonnad ja analüütika. Eksportige see iga päev ja vahetult enne iga uuendust: ise majutatuna hoitakse neid andmeid ajapiiranguta. Andmebaasi kõrval hoiab fail .env saladusi, mis muudavad selle kasutatavaks:

Andmebaasi eksport töö ajal

pg_dump teeb järjepideva ekspordi ka siis, kui andmebaas on kasutusel. Kohandatud vorming -Fc on tihendatud ja taastatakse käsuga pg_restore:

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

Ajastage see käsk serveris vähemalt kord päevas, sorteerige ekspordid, mis kuhjuvad, ja saatke koopia mujale. Serveri kettal hoituna jõuavad need ekspordid ka selle öistesse varukoopiatesse.

Taastamine

1. Peatage Umami, jättes andmebaasi tööle: docker compose stop umami.
2. Taastage eksport andmebaasi, asendades olemasolevad objektid.
3. Käivitage Umami uuesti ja kontrollige, et teie veebisaidid ja nende analüütika on alles.

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

Korrake seda harjutust aeg-ajalt koopia peal: nii veendute, et varukoopia toimib.

Uuendused

Dokumentatsioon annab kaks käsku, mida käivitatakse kaustast, kus asub compose.yaml. Andmebaas jääb oma köitesse:

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

Taaskäivitamisel rakendab konteiner skeemi migratsioonid ise. 17. septembri 2026 versioon 3.4.0 tõi neist kaks, annotatsioonide ja API-võtmete jaoks; 23. oktoobri 2026 versioon 3.4.1 ei too ühtegi. Pärast suurt uuendust, nagu üleminek versioonile 3, soovitab dokumentatsioon käivitada PostgreSQL-is ANALYZE, et töölauad saaksid oma kiiruse tagasi:

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

• Väljalaskemärkmed ütlevad, mida iga versioon muudab. Versioon 3.4.1 on kiire turvaparandus, mis uuendab Next.js-i ja Node.js-i baastõmmist; selle märkmed paluvad igal ise majutatud instantsil uuendada, tõmmates tõmmise uuesti.
• Versioonilt 2 MySQL-il: versioon 3 ei toeta enam MySQL-i. Projekti üleviimisjuhend viib andmed PostgreSQL-i versioonil 2.19.0, enne uuendamist versioonile 3.
• PostgreSQL ise: säilitage faili silt postgres:15-alpine. Üleminek PostgreSQL-i uuele peaversioonile nõuab eksporti ja taastamist või käsku pg_upgrade.

Kes mida teeb Managed VPS-is

Ise majutamine nõuab lisaks rakendusele ka serveri hoidmist. Managed VPS-is võtavad meie meeskonnad serveri enda hoole alla ja jälgivad teie instantsi proaktiivselt; Umami jääb teie tarkvaraks oma sätete ja andmetega.

Kui eelistate, et meie meeskonnad sekkuksid rakendusse endasse, arveldatakse see teenus tunni- või kindlahinnaga, hinnapakkumine edastatakse enne sekkumist.