Хостване на Umami на Managed VPS: уеб анализите ви на ваш сървър

Какво прави Umami

Umami е платформа с отворен код за уеб и продуктови анализи. Документацията му описва инструмент, който събира на едно място трафика, кампаниите, поведението на посетителите, конверсиите, задържането и приходите, от първото посещение до резултатите, които са важни за вашата дейност. Той е написан на TypeScript върху Next.js, а Docker образът му работи под акаунт без привилегии.

• Привличането: прегледи на страници, посетители, източници на препращане, държави, устройства и активност в реално време, с UTM кампании, кратки връзки и проследяващи пиксели.
• Поведението: персонализирани събития, пътища на посетителите, записи на сесии, топлинни карти, сегменти, кохорти и задържане.
• Конверсията: цели, фунии, атрибуция и проследяване на приходите по страница и по кампания.
• Споделянето: табла, екипи, публичен адрес за споделяне, API и MCP сървър само за четене за вашия AI асистент.
• Модерните сайтове: FAQ посочва, че Umami сам проследява навигацията между страниците в едностраничните приложения, без допълнителна настройка.

Една инстанция проследява няколко сайта: всеки получава собствен идентификатор и скрипт за проследяване, а колегите ви се ориентират чрез акаунти и екипи.

Какво позволява лицензът MIT

Umami е публикуван с лиценза MIT, от името на Umami Software, Inc. Той дава безплатно правото да използвате, копирате, променяте, сливате, публикувате, разпространявате, преотстъпвате и продавате копия на софтуера. Можете следователно да го пускате за фирмата си и за сайтовете на клиентите си, без да купувате лиценз.

Единственото му условие: бележката за авторските права и бележката за разрешението придружават всички копия или съществени части на софтуера. Като всеки лиценз MIT, той предоставя софтуера „такъв, какъвто е“, без гаранция.

Бисквитки и лични данни: какво казва проектът

Документацията представя Umami като анализи без бисквитки, без проследяване между сайтове и без автоматично събиране на лични данни. Самостоятелно хостван, той пази анализите ви на вашия собствен сървър: вие решавате къде се намират и колко дълго остават.

Три настройки на скрипта за проследяване отиват по-далеч, ако желаете: data-exclude-search премахва параметрите на търсене от записаните адреси, data-exclude-hash премахва хеша, а data-do-not-track изключва проследяването за браузърите, които изразяват предпочитанието Do Not Track. Документацията отбелязва, че тази последна настройка сама по себе си не е пълно решение за управление на съгласието.

Ако идентифицирате влезлите посетители с data-distinct-id или umami.identify(), документацията препоръчва вътрешен идентификатор на потребителя или хеш, а не имейл адрес: стойността може да се прочете в HTML кода на страницата.

Инсталиране с Docker Compose и PostgreSQL

Хранилището съдържа docker-compose.yml, който стартира Umami и неговата база PostgreSQL. От версия 3 PostgreSQL е единствената поддържана база, минимум версия 12.14, а документацията препоръчва да я настроите на часова зона UTC. На сървър с инсталиран Docker създайте папка и започнете с тайните ѝ, генерирани на случаен принцип с openssl, както предлага документацията:

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

После поставете до него този compose.yaml. Той следва файла на проекта във версия 3.4.1, с две промени: тайните идват от файла .env, а портът се публикува само на 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: единствената задължителна променлива, низът за връзка с базата. Шестнадесетичната парола се поставя такава, каквато е; парола със специални знаци би изисквала процентно кодиране.
• APP_SECRET: случаен низ, който защитава токените за удостоверяване, уникален за всяка инсталация. В кода на версия 3.4.1 той участва и в изчисляването на идентификаторите на сесиите: дръжте го непроменен.
• TWO_FACTOR_ENCRYPTION_KEY: 64 шестнадесетични знака, които шифроват тайните на двуфакторното удостоверяване. Без него никой не може да включи двуфакторно удостоверяване.
• При стартиране контейнерът проверява връзката с базата и версията ѝ, после сам прилага миграциите на схемата. При първото пускане той създава таблиците и акаунта admin. Проверката /api/heartbeat отговаря {"ok":true}, щом Umami е готов.
• Етикетът latest следва последната публикувана версия. Регистърът на проекта публикува и етикети с номер на версия, като 3.4.1, за да фиксирате тази, която пускате.

Документацията за инсталиране не дава числа за паметта и процесора. Размерът зависи от трафика на проследяваните сайтове и от обема на данните, които пазите. На Managed VPS ни опишете как го използвате и ще ви препоръчаме подходящия размер.

HTTPS: обратният прокси

Umami слуша през HTTP на порт 3000, а документацията предлага да го предоставяте зад вашия уеб сървър, чрез обратен прокси. Дайте му собствен поддомейн, като stats.example.com, насочен към сървъра със записи A и AAAA. Предоставянето на Umami под път минава през BASE_PATH, променлива, която се чете при изграждането на приложението: с публикувания образ поддомейнът е прекият път.

Проксито трябва и да предава адреса на посетителя. Umami го чете от заглавките, които получава, сред които X-Real-IP и X-Forwarded-For: той го използва, за да различава посетителите и да определя държавата им. Ако проксито ви използва друга заглавка, CLIENT_IP_HEADER я посочва.

С Caddy

Caddy сам получава сертификата Let’s Encrypt и включва HTTPS. Директивата му reverse_proxy поставя X-Forwarded-For по подразбиране: тези три реда са всичко, което ви трябва.

stats.example.com {
  reverse_proxy 127.0.0.1:3000
}

С Nginx и Certbot

Този блок следва примера за Nginx от документацията на Umami и слуша на порт 80, за да остави на Certbot да постави 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 поставя сертификата и се грижи да го подновява:

sudo certbot --nginx

Първото влизане: администраторският акаунт и двуфакторното удостоверяване

Когато създава базата си, Umami отваря администраторски акаунт: потребителско име admin, парола umami. Документацията моли да смените тази парола при първото си влизане.

1. Отворете своя HTTPS адрес и влезте с admin и umami.
2. Отворете Settings от бутона на профила в страничната лента, после Profile, и щракнете върху Change password.
3. В раздела Security включете двуфакторното удостоверяване: сканирайте QR кода с приложението си за удостоверяване, въведете шестцифрения код, после запазете десетте резервни кода на сигурно място, защото се показват само веднъж.

• Задължително двуфакторно удостоверяване: администратор може да го изиска за цялата инстанция, за един потребител или за един екип, от администраторските страници.
• Опитите: пет грешни кода блокират следващите опити за 15 минути.
• Акаунтите на екипа ви: администраторските страници управляват потребителите, сайтовете и екипите на цялата инстанция.

Пазете TWO_FACTOR_ENCRYPTION_KEY заедно с резервните си копия: документацията предупреждава, че загубата или смяната на този ключ прави записаните тайни нечетими, а всеки потребител трябва тогава да настрои отново двуфакторното удостоверяване.

Добавяне на сайт и неговия скрипт за проследяване

1. В Websites щракнете върху Add website.
2. Дайте име на сайта, после неговия домейн: Umami го използва, за да изключи вашите собствени страници от списъка с източници на препращане.
3. Отворете Edit за този сайт и копирайте кода от раздела Tracking code.
4. Поставете го в <head> на страниците си, после посетете сайта си: данните се появяват веднага в таблото.

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

• Нищо не се появява? Документацията предлага раздела за мрежата в инструментите за разработчици на браузъра: заявките към вашата инстанция трябва да излизат без грешки.
• Next.js: добавете кода с компонента next/script, а не с обикновен таг <script>.
• data-domains ограничава проследяването до работните ви домейни, което държи тестовите ви среди извън статистиката.
• Собствените ви посещения се изключват сайт по сайт, от конзолата на браузъра, с localStorage.setItem('umami.disabled', 1).

Собствено име на скрипта

Някои блокери на реклами блокират всичко, което прилича на анализи. При самостоятелно хостване Umami вече се предоставя от вашия собствен домейн, а две променливи отиват по-далеч: TRACKER_SCRIPT_NAME дава на скрипта име, различно от script.js, а COLLECT_API_ENDPOINT преименува крайната точка за събиране, вместо /api/send. После скриптът сам извиква новата крайна точка; на страниците ви се сменя само източникът на кода за проследяване.

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

Полезните настройки

Тези променливи на средата отиват в услугата umami на compose.yaml, после docker compose up -d създава контейнера наново, за да ги вземе предвид:

Резервните копия

Всичко, което Umami пази, се намира в неговата база PostgreSQL: акаунти, сайтове, екипи и анализи. Експортирайте я всеки ден и непосредствено преди всяко обновяване: при самостоятелно хостване тези данни се пазят без ограничение във времето. До базата файлът .env съдържа тайните, които я правят използваема:

Експорт на базата, докато работи

pg_dump прави съгласуван експорт, докато базата се използва. Персонализираният формат, -Fc, е компресиран и се възстановява с pg_restore:

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

Планирайте тази команда на сървъра поне веднъж дневно, подреждайте експортите, които се трупат, и изпращайте копие другаде. Пазени на диска на сървъра, тези експорти влизат и в нощните му резервни копия.

Възстановяване

1. Спрете Umami, като оставите базата да работи: docker compose stop umami.
2. Възстановете експорта в базата, като замените съществуващите обекти.
3. Стартирайте отново Umami, после проверете, че сайтовете ви и техните анализи са налице.

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

Повтаряйте това упражнение от време на време, върху копие: така проверявате, че резервното копие работи.

Обновленията

Документацията дава две команди, от папката на compose.yaml. Базата остава в своя том:

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

При рестартиране контейнерът сам прилага миграциите на схемата. Версия 3.4.0 от 17 септември 2026 г. носеше две такива, за анотациите и за API ключовете; версия 3.4.1 от 23 октомври 2026 г. не носи нито една. След голямо обновяване, като преминаването към версия 3, документацията предлага да изпълните ANALYZE в PostgreSQL, за да си върнат таблата скоростта:

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

• Бележките към версиите казват какво променя всяка версия. Версия 3.4.1 е спешна поправка за сигурността, която обновява Next.js и основния образ Node.js; бележките ѝ молят всяка самостоятелно хоствана инстанция да се обнови, като изтегли отново образа.
• От версия 2 с MySQL: версия 3 вече не поддържа MySQL. Ръководството за миграция на проекта премества данните в PostgreSQL на версия 2.19.0, преди обновяването към версия 3.
• Самият PostgreSQL: запазете етикета postgres:15-alpine от файла. Преминаването към нова основна версия на PostgreSQL изисква експорт и възстановяване или pg_upgrade.

Кой какво прави на Managed VPS

Самостоятелното хостване изисква да поддържате сървъра освен приложението. На Managed VPS нашите екипи поемат сървъра и следят проактивно вашата инстанция; Umami остава ваш софтуер, с неговите настройки и данни.

Ако предпочитате нашите екипи да се намесват в самото приложение, тази услуга се фактурира на час или на фиксирана цена, с оферта, съобщена преди намесата.