Mitināt Umami Managed VPS serverī: jūsu tīmekļa analītika jūsu serverī

Ko dara Umami

Umami ir atvērtā koda tīmekļa un produktu analītikas platforma. Tā dokumentācija apraksta rīku, kas vienuviet apvieno apmeklējumu, kampaņas, apmeklētāju uzvedību, konversijas, noturēšanu un ieņēmumus, no pirmā apmeklējuma līdz rezultātiem, kas svarīgi jūsu uzņēmumam. Tas ir uzrakstīts TypeScript valodā uz Next.js, un tā Docker attēls darbojas zem konta bez privilēģijām.

• Piesaiste: lapu skatījumi, apmeklētāji, novirzītāji, valstis, ierīces un aktivitāte reāllaikā, ar UTM kampaņām, īsajām saitēm un izsekošanas pikseļiem.
• Uzvedība: pielāgoti notikumi, ceļi, sesiju atskaņojumi, siltuma kartes, segmenti, kohortas un noturēšana.
• Konversija: mērķi, piltuves, attiecināšana un ieņēmumu izsekošana pa lapām un kampaņām.
• Koplietošana: paneļi, komandas, publiska koplietošanas adrese, API un tikai lasāms MCP serveris jūsu MI asistentam.
• Mūsdienīgas vietnes: FAQ norāda, ka Umami vienas lapas lietotnēs pats seko navigācijai starp lapām, bez papildu iestatījumiem.

Viena instance izseko vairākas vietnes: katra saņem savu identifikatoru un izsekošanas skriptu, un jūsu kolēģi orientējas, izmantojot kontus un komandas.

Ko atļauj MIT licence

Umami tiek publicēts ar MIT licenci, Umami Software, Inc. vārdā. Tā bez maksas piešķir tiesības programmatūru izmantot, kopēt, mainīt, apvienot, publicēt, izplatīt, apakšlicencēt un pārdot tās kopijas. Tāpēc jūs varat to darbināt savam uzņēmumam un savu klientu vietnēm, nepērkot nekādu licenci.

Tās vienīgais nosacījums: autortiesību paziņojums un atļaujas paziņojums pavada visas programmatūras kopijas vai būtiskas tās daļas. Kā jebkura MIT licence, tā nodrošina programmatūru «tādu, kāda tā ir», bez garantijas.

Sīkdatnes un personas dati: ko saka projekts

Dokumentācija pasniedz Umami kā analītiku bez sīkdatnēm, bez starpvietņu izsekošanas un bez automātiskas personas datu vākšanas. Mitināts savā serverī, tas glabā jūsu analītiku jūsu serverī: jūs izlemjat, kur tā atrodas un cik ilgi tā tiek glabāta.

Trīs izsekošanas skripta iestatījumi, ja vēlaties, iet tālāk: data-exclude-search noņem meklēšanas parametrus no ierakstītajām adresēm, data-exclude-hash noņem fragmentu aiz restītes, un data-do-not-track izslēdz izsekošanu pārlūkprogrammām, kas paziņo Do Not Track izvēli. Dokumentācija norāda, ka šis pēdējais iestatījums pats par sevi nav pilnīgs piekrišanas pārvaldības risinājums.

Ja identificējat pieteikušos apmeklētājus ar data-distinct-id vai umami.identify(), dokumentācija iesaka iekšēju lietotāja identifikatoru vai jaucējkodu, nevis e-pasta adresi: vērtību var izlasīt lapas HTML kodā.

Uzstādīšana ar Docker Compose un PostgreSQL

Repozitorijs piedāvā docker-compose.yml, kas palaiž Umami un tā PostgreSQL datubāzi. Kopš 3. versijas PostgreSQL ir vienīgā atbalstītā datubāze, vismaz 12.14 versija, un dokumentācija iesaka iestatīt tai UTC laika joslu. Serverī, kur uzstādīts Docker, izveidojiet mapi un sāciet ar tās noslēpumiem, kas nejauši ģenerēti ar openssl, kā iesaka dokumentācija:

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

Pēc tam blakus novietojiet šo compose.yaml. Tas seko projekta failam 3.4.1 versijā ar divām izmaiņām: noslēpumi nāk no faila .env, un ports ir publicēts tikai uz 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: vienīgais obligātais mainīgais, datubāzes savienojuma virkne. Heksadecimālā parole tajā tiek ievietota, kā ir; parole ar speciālajām rakstzīmēm būtu jāraksta procentu kodējumā.
• APP_SECRET: nejauša virkne, kas aizsargā autentifikācijas marķierus, katrai instalācijai sava. 3.4.1 versijas kodā tā piedalās arī sesiju identifikatoru aprēķinā: nemainiet to.
• TWO_FACTOR_ENCRYPTION_KEY: 64 heksadecimālas rakstzīmes, kas šifrē divfaktoru autentifikācijas noslēpumus. Bez tās neviens nevar ieslēgt divfaktoru autentifikāciju.
• Startējot konteiners pārbauda savienojumu ar datubāzi un tās versiju, pēc tam pats piemēro shēmas migrācijas. Pirmajā palaišanas reizē tas izveido tabulas un kontu admin. Pārbaude /api/heartbeat atbild {"ok":true}, tiklīdz Umami ir gatavs.
• Birka latest seko jaunākajai publicētajai versijai. Projekta reģistrs publicē arī versiju birkas, piemēram, 3.4.1, lai fiksētu to, ko darbināt.

Uzstādīšanas dokumentācija nenosauc ne atmiņas, ne procesora apjomu. Izmērs ir atkarīgs no izsekoto vietņu apmeklējuma un glabāto datu apjoma. Ar Managed VPS aprakstiet mums savu lietojumu, un mēs jums iesakām piemērotu izmēru.

HTTPS: reversais starpniekserveris

Umami klausās HTTP uz porta 3000, un dokumentācija iesaka to piedāvāt aiz jūsu tīmekļa servera, caur reverso starpniekserveri. Piešķiriet tam savu apakšdomēnu, piemēram, stats.example.com, kas ar A un AAAA ierakstiem norāda uz serveri. Lai Umami piedāvātu zem ceļa, izmanto BASE_PATH, mainīgo, ko nolasa lietojumprogrammas būvēšanas laikā: ar publicēto attēlu apakšdomēns ir tiešākais ceļš.

Starpniekserverim jānodod arī apmeklētāja adrese. Umami to nolasa no saņemtajām galvenēm, tostarp X-Real-IP un X-Forwarded-For: tas to izmanto, lai atšķirtu apmeklētājus un noteiktu viņu valsti. Ja jūsu starpniekserveris izmanto citu galveni, to nosauc CLIENT_IP_HEADER.

Ar Caddy

Caddy pats iegūst Let’s Encrypt sertifikātu un ieslēdz HTTPS. Tā direktīva reverse_proxy pēc noklusējuma iestata X-Forwarded-For: pietiek ar šīm trim rindām.

stats.example.com {
  reverse_proxy 127.0.0.1:3000
}

Ar Nginx un Certbot

Šis bloks seko Umami dokumentācijas Nginx piemēram un klausās uz porta 80, lai Certbot varētu ieslēgt 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;
  }
}

Pēc tam Certbot uzstāda sertifikātu un parūpējas par tā atjaunošanu:

sudo certbot --nginx

Pirmā pieteikšanās: administratora konts un divfaktoru autentifikācija

Izveidojot savu datubāzi, Umami atver administratora kontu: lietotājvārds admin, parole umami. Dokumentācija lūdz šo paroli nomainīt pirmajā pieteikšanās reizē.

1. Atveriet savu HTTPS adresi un piesakieties ar admin un umami.
2. Atveriet Settings no profila pogas sānjoslā, pēc tam Profile, un noklikšķiniet Change password.
3. Cilnē Security ieslēdziet divfaktoru autentifikāciju: noskenējiet QR kodu ar savu autentifikācijas lietotni, ievadiet sešu ciparu kodu un pēc tam drošā vietā noglabājiet desmit rezerves kodus, jo tie tiek parādīti tikai vienreiz.

• Obligāta divfaktoru autentifikācija: administrators var to pieprasīt visai instancei, vienam lietotājam vai vienai komandai, no administrēšanas lapām.
• Mēģinājumi: pēc pieciem nepareiziem kodiem nākamie mēģinājumi tiek bloķēti uz 15 minūtēm.
• Jūsu komandas konti: administrēšanas lapās pārvalda visas instances lietotājus, vietnes un komandas.

Glabājiet TWO_FACTOR_ENCRYPTION_KEY kopā ar savām rezerves kopijām: dokumentācija brīdina, ka šīs atslēgas zaudēšana vai maiņa padara saglabātos noslēpumus nelasāmus, un tad katram lietotājam divfaktoru autentifikācija jāiestata no jauna.

Vietnes un tās izsekošanas skripta pievienošana

1. Sadaļā Websites noklikšķiniet Add website.
2. Piešķiriet vietnei nosaukumu un pēc tam tās domēnu: Umami to izmanto, lai izslēgtu jūsu pašu lapas no novirzītāju saraksta.
3. Atveriet šai vietnei Edit un nokopējiet kodu no sadaļas Tracking code.
4. Ielīmējiet to savu lapu sadaļā <head> un pēc tam apmeklējiet savu vietni: dati uzreiz parādās panelī.

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

• Nekas neparādās? Dokumentācija iesaka pārlūkprogrammas izstrādātāju rīku tīkla cilni: pieprasījumiem uz jūsu instanci jānotiek bez kļūdām.
• Next.js: pievienojiet kodu ar komponentu next/script, nevis ar vienkāršu tagu <script>.
• data-domains ierobežo izsekošanu ar jūsu produkcijas domēniem, tā jūsu testa vides nenonāk statistikā.
• Jūsu pašu apmeklējumi tiek izslēgti katrai vietnei atsevišķi no pārlūkprogrammas konsoles ar localStorage.setItem('umami.disabled', 1).

Savs skripta nosaukums

Daži reklāmu bloķētāji bloķē visu, kas izskatās pēc analītikas. Mitināts savā serverī, Umami jau tiek piedāvāts no jūsu paša domēna, un divi mainīgie iet vēl tālāk: TRACKER_SCRIPT_NAME piešķir skriptam citu nosaukumu, nevis script.js, un COLLECT_API_ENDPOINT pārdēvē datu vākšanas galapunktu, nevis /api/send. Pēc tam skripts pats izsauc jauno galapunktu; jūsu lapās mainās tikai izsekošanas koda avots.

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

Noderīgi iestatījumi

Šie vides mainīgie tiek ievietoti compose.yaml pakalpojumā umami, pēc tam docker compose up -d izveido konteineru no jauna, lai tos ņemtu vērā:

Rezerves kopijas

Viss, ko Umami glabā, atrodas tā PostgreSQL datubāzē: konti, vietnes, komandas un analītika. Eksportējiet to katru dienu un tieši pirms katra atjauninājuma: mitinot savā serverī, šie dati tiek glabāti bez termiņa. Blakus datubāzei fails .env glabā noslēpumus, bez kuriem to nevar izmantot:

Datubāzes eksports, tai darbojoties

pg_dump izveido konsekventu eksportu, kamēr datubāze tiek izmantota. Pielāgotais formāts -Fc ir saspiests, un to atjauno ar pg_restore:

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

Ieplānojiet šo komandu serverī vismaz reizi dienā, izkārtojiet eksportus, kas uzkrājas, un nosūtiet kopiju citur. Glabāti servera diskā, šie eksporti nonāk arī tā nakts rezerves kopijās.

Atjaunošana

1. Apturiet Umami, atstājot datubāzi darbojamies: docker compose stop umami.
2. Atjaunojiet eksportu datubāzē, aizvietojot esošos objektus.
3. Startējiet Umami no jauna, pēc tam pārbaudiet, vai jūsu vietnes un to analītika ir vietā.

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

Laiku pa laikam atkārtojiet šo vingrinājumu ar kopiju: tā jūs pārbaudāt, vai rezerves kopija darbojas.

Atjauninājumi

Dokumentācija dod divas komandas, kas jāpalaiž no mapes ar compose.yaml. Datubāze paliek savā sējumā:

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

Restartējot konteiners pats piemēro shēmas migrācijas. Versijā 3.4.0 no 2026. gada 17. septembra tādas bija divas, anotācijām un API atslēgām; versijā 3.4.1 no 2026. gada 23. oktobra to nav. Pēc lielas versijas maiņas, piemēram, pārejas uz 3. versiju, dokumentācija iesaka PostgreSQL palaist ANALYZE, lai paneļi atgūtu savu ātrumu:

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

• Laidiena piezīmes norāda, ko maina katra versija. Versija 3.4.1 ir steidzams drošības labojums, kas atjaunina Next.js un Node.js bāzes attēlu; tās piezīmes lūdz katru savā serverī mitinātu instanci atjaunināt, no jauna lejupielādējot attēlu.
• No 2. versijas ar MySQL: 3. versija vairs neatbalsta MySQL. Projekta migrācijas ceļvedis pārceļ datus uz PostgreSQL 2.19.0 versijā, pirms pārejas uz 3. versiju.
• Pati PostgreSQL: saglabājiet faila birku postgres:15-alpine. Pāreja uz jaunu PostgreSQL lielo versiju prasa eksportu un atjaunošanu vai pg_upgrade.

Kurš ko dara Managed VPS serverī

Mitināšana savā serverī prasa uzturēt serveri papildus lietojumprogrammai. Ar Managed VPS mūsu komandas uzņemas serveri un proaktīvi seko jūsu instancei; Umami paliek jūsu programmatūra ar saviem iestatījumiem un datiem.

Ja vēlaties, lai mūsu komandas iejaucas pašā lietojumprogrammā, šis pakalpojums tiek rēķināts par stundu vai par fiksētu summu, ar novērtējumu, kas paziņots pirms iejaukšanās.