Umami на Debian 12 — установка и настройка

Что такое Umami

Umami — это лёгкое open-source решение для веб-аналитики с фокусом на приватность. Однострочное определение: Umami собирает базовые метрики посещений без установки cookies и без отправки персональных данных по умолчанию.

Ключевые преимущества: простота, отсутствие cookie по умолчанию, возможность self-hosting (самостоятельного размещения) и быстрая интеграция на сайты.

В этой статье мы пройдём пошаговую установку на Debian 12 и добавим разделы по безопасности, соответствию требованиям конфиденциальности и процедурам обновления.

Предпосылки

Сервер с Debian 12.
Ненулевой пользователь с sudo-привилегиями.
Полностью квалифицированный домен (FQDN), например umami.example.com, указывающий на сервер.
UFW (Uncomplicated Firewall) включён и настроен.
Обновите систему и установите базовые пакеты:

$ sudo apt update && sudo apt upgrade

$ sudo apt install wget curl nano ufw software-properties-common dirmngr apt-transport-https gnupg2 ca-certificates lsb-release debian-archive-keyring unzip -y

Важно: в командах ниже заменяйте примерные значения (пароли, домены, имена пользователей) на свои реальные.

Шаг 1 — Настройка брандмауэра (UFW)

Проверьте статус UFW:

$ sudo ufw status

Ожидаемый вывод при выключенном UFW:

Status: inactive

Разрешите SSH, HTTP и HTTPS до включения UFW, чтобы не потерять доступ:

$ sudo ufw allow OpenSSH
$ sudo ufw allow http
$ sudo ufw allow https

Включите UFW:

$ sudo ufw enable

Проверьте статус снова:

$ sudo ufw status

Примечание: по желанию сузьте правила, указав IP-адреса админов и добавив логирование.

Шаг 2 — Установка Git

$ sudo apt install git

Проверьте версию:

$ git --version

Настройте имя и email для коммитов (при необходимости):

$ git config --global user.name "Your Name"
$ git config --global user.email "[email protected]"

Шаг 3 — Установка Node.js

Umami — Node.js-приложение. В примере используется Node.js 18.x.

Добавим ключ Nodesource и репозиторий:

$ curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/nodesource.gpg
$ NODE_MAJOR=18
$ echo "deb [signed-by=/usr/share/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
$ sudo apt update
$ sudo apt install nodejs

Проверка:

$ node --version
v18.x.x

Совет: для продакшена используйте LTS-версию, указанную в документации Umami.

Шаг 4 — Установка MariaDB

Debian 12 идёт с MariaDB (в примере 10.11). Установим и настроим базу данных:

$ sudo apt install mariadb-server

Проверка версии:

$ mysql --version

Запустите безопасную настройку MariaDB:

$ sudo mariadb-secure-installation

В интерактивном режиме ответьте на вопросы по удалению анонимных пользователей, отключению удалённого логина root и удалению тестовой базы.

Важно: на Debian root для MariaDB часто использует unix_socket; при настройке базы данных для Umami создавайте отдельного пользователя с паролем и минимальными правами.

Шаг 5 — Скачивание Umami

Установим Yarn и клонируем репозиторий Umami:

$ sudo npm install -g yarn
$ git clone https://github.com/mikecao/umami.git
$ cd umami
$ yarn install

Umami — Node.js-приложение, у него нет публичного webroot в /var/www по умолчанию.

Шаг 6 — Конфигурация Umami

Создание пользователя базы данных и заполнение схемы

$ sudo mysql

В MySQL-консоли выполните:

mysql> CREATE USER 'umamiuser'@'localhost' IDENTIFIED BY 'YourPassword';
mysql> CREATE DATABASE umami;
mysql> GRANT ALL PRIVILEGES ON umami.* TO 'umamiuser'@'localhost';
mysql> FLUSH PRIVILEGES;
mysql> exit

Рекомендация безопасности: используйте уникальный и сильный пароль; давайте минимальные права только на нужную БД.

Переменные окружения Umami

Сгенерируйте секрет приложения:

$ openssl rand 30 | openssl base64 -A

Создайте файл .env в каталоге umami и вставьте значения. Пример:

DATABASE_URL=mysql://umamiuser:YourPassword@localhost:3306/umami
APP_SECRET=ваш_сильный_секрет
DISABLE_TELEMETRY=1
TRACKER_SCRIPT_NAME=custom

Заметьте: если в пароле есть специальные символы (#, @ и т. п.), кодируйте их в URL (например, %23 вместо #).

Шаг 7 — Запуск Umami

Сборка приложения:

$ yarn build

Для фонового запуска используем PM2:

$ sudo yarn global add pm2
$ pm2 start yarn --name umami -- start
$ pm2 save
$ pm2 startup

Команда pm2 startup выдаст команду, которую нужно выполнить с sudo. Выполните её, чтобы PM2 запускался при старте системы (в примере пользователь navjot):

$ sudo env PATH=$PATH:/usr/bin /usr/local/share/.config/yarn/global/node_modules/pm2/bin/pm2 startup systemd -u youruser --hp /home/youruser

Проверьте статус процесса:

$ pm2 list

Шаг 8 — Установка Nginx

Для проксирования трафика и TLS используем Nginx. Добавим официальный репозиторий и установим nginx:

$ curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
$ echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] http://nginx.org/packages/debian `lsb_release -cs` nginx" | sudo tee /etc/apt/sources.list.d/nginx.list
$ sudo apt update
$ sudo apt install nginx
$ sudo nginx -v
$ sudo systemctl start nginx
$ sudo systemctl enable nginx

Шаг 9 — Установка SSL через Let’s Encrypt (Certbot)

Установим snapd и certbot через snap, затем получим сертификат:

$ sudo apt install snapd
$ sudo snap install core
$ sudo snap refresh core
$ sudo snap install --classic certbot
$ sudo ln -s /snap/bin/certbot /usr/bin/certbot
$ certbot --version
$ sudo certbot certonly --nginx --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m [email protected] -d umami.example.com

Создайте сильную группу Diffie-Hellman:

$ sudo openssl dhparam -dsaparam -out /etc/ssl/certs/dhparam.pem 4096

Проверьте периодичность обновления сертификатов и сделайте тест продления:

$ sudo systemctl list-timers
$ sudo certbot renew --dry-run

Шаг 10 — Конфигурация Nginx для Umami

Создайте файл /etc/nginx/conf.d/umami.conf и вставьте конфигурацию прокси и TLS (пример):

server {
    listen       443 ssl http2;
    listen       [::]:443 ssl http2;
    server_name  umami.example.com;

    access_log  /var/log/nginx/umami.access.log;
    error_log   /var/log/nginx/umami.error.log;
    
    # SSL
    ssl_certificate      /etc/letsencrypt/live/umami.example.com/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/umami.example.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/umami.example.com/chain.pem;
    ssl_session_timeout  5m;
    ssl_session_cache shared:MozSSL:10m;
    ssl_session_tickets off;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
    ssl_ecdh_curve X25519:prime256v1:secp384r1:secp521r1;
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;
    resolver 8.8.8.8;

    location / {
      proxy_pass http://localhost: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;
  }
}
# enforce HTTPS
server {
    listen       80;
    listen       [::]:80;
    server_name  umami.example.com;
    return 301   https://$host$request_uri;
}

Добавьте в /etc/nginx/nginx.conf строку:

server_names_hash_bucket_size  64;

Проверьте синтаксис и перезапустите nginx:

$ sudo nginx -t
$ sudo systemctl restart nginx

Шаг 11 — Первичная настройка сайта и проверка

Откройте https://umami.example.com. По умолчанию Umami создаёт администратора (admin / umami) — поменяйте сразу пароль.

Страница входа Umami

После входа вы попадёте в панель управления.

Панель управления Umami

Добавьте сайт в настройках (Add website), затем получите код трекера на вкладке Tracking code и вставьте его в или перед закрывающим на ваших страницах.

Добавление сайта в Umami

Код трекера Umami

Через несколько минут начнут появляться данные по посещениям.

Статистика Umami

Шаг 12 — Обновление Umami

Процедура безопасного обновления:

$ cd ~/umami
$ pm2 stop umami
$ git pull origin main
$ yarn install
$ yarn build
$ pm2 start umami

Если вы используете PM2 ecosystem файл или systemd шаблон — адаптируйте команды под вашу среду.

Безопасность и жёсткие настройки (Security hardening)

Разделяйте привилегии: пользователь БД должен иметь доступ только к базе umami.
MariaDB: запретите удалённый доступ к root, в /etc/mysql/mariadb.conf.d/50-server.cnf установите bind-address = 127.0.0.1.
Брандмауэр: ограничьте доступ к SSH по IP, включите fail2ban для защиты SSH и панели админов.
Nginx: добавьте заголовки безопасности, например:

add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options "nosniff";
add_header Referrer-Policy "no-referrer-when-downgrade";
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload";

Минимизируйте данные: храните логи отдельно, ограничьте время хранения (retention) и регулярно удаляйте устаревшие записи.
Резервные копии: автоматизируйте бэкап БД (например, mysqldump + off-site хранение) и архивацию конфигураций.

Соответствие конфиденциальности и GDPR (Примечания)

По умолчанию Umami стремится к минимизации данных (no cookies). Тем не менее правила в вашей юрисдикции могут требовать согласия пользователя или дополнительных настроек.
Советы:
- Анонимизируйте IP-адреса (если поддерживается вашей версией Umami) или не храните их в явном виде.
- Не собирайте PII (e-mail, имена) через трекер.
- Документируйте данные, которые вы собираете, и опишите их в политике конфиденциальности.
- При необходимости добавьте механизмы удаления данных по запросу (право на удаление).

Важно: проконсультируйтесь с юристом по защите данных для соответствия GDPR/локальным требованиям.

Тестирование и Критерии приёмки

Критерии для подтверждения корректной установки:

Доступность веб-интерфейса по HTTPS.
Трекер загружается на публикуемых страницах (проверьте Network в DevTools).
События и просмотры страниц отображаются в панели Umami в течение нескольких минут.
PM2 показывает процесс как online, и pm2 startup настроен для автозапуска.
Certbot успешно прошёл –dry-run для автоматического обновления сертификатов.

Тестовые кейсы:

Вставьте трекер на тестовую страницу и откройте её — ожидается появление сессии в интерфейсе.
Проверьте работу HTTPS и редиректа с HTTP.
Имитируйте перезапуск системы и убедитесь, что PM2 поднимает Umami автоматически.

Руководство по реагированию на инциденты (Runbook)

Симптом: панель недоступна (ошибка 502 от nginx).
- Проверьте статусы: sudo systemctl status nginx, pm2 list.
- Логи Nginx: sudo tail -n 200 /var/log/nginx/umami.error.log.
- Логи приложения: pm2 logs umami.
- Если БД недоступна: sudo systemctl status mariadb и sudo journalctl -u mariadb -n 200.
Симптом: сертификат просрочен.
- Выполните sudo certbot renew --dry-run и проверьте ошибки.
Симптом: чрезмерная нагрузка.
- Проверьте число запросов, CPU и память: top, pm2 monit, sudo ss -tulpn.
- Увеличьте ресурсы VM или настройте rate-limiting на nginx.

Альтернативные подходы и сравнение

Google Analytics: мощный, бесплатный облачный сервис с продвинутой аналитикой, но менее приватный.
Matomo: более крупный self-hosted продукт с расширенным функционалом и хранением данных.
Plausible: минималистичный и приватный SaaS/self-hosted вариант — проще, но платный для SaaS.

Выбор зависит от требований: если нужна максимальная приватность и простота — Umami; если нужны расширенные отчёты и сегментация — Matomo/GA.

Чек-лист по ролям

Администратор:

Настроить резервное копирование базы данных.
Настроить PM2 и автозапуск.
Проверить брандмауэр и fail2ban.

Разработчик:

Интегрировать трекер на тестовом сайте.
Проверить события и цели.
Настроить сбор ошибок и логирование.

Безопасность/Compliance:

Аудит данных, которые собираются.
Обновление зависимостей Node и системных пакетов.
Обновление сертификатов и тест продления.

Быстрая методика отката при обновлении

До обновления: снимите snapshot VM или сделайте полный бэкап БД.
Выполните git pull, yarn install, yarn build в тестовой среде.
Если после pm2 restart наблюдаются ошибки, вернитесь к предыдущему коммиту:

$ git checkout -- .
$ git reset --hard <предыдущий-коммит-hash>
$ yarn install
$ yarn build
$ pm2 restart umami

Небольшая галерея исключений — когда Umami может не подойти

Нужна сложная сегментация и отчёты уровня enterprise — лучше Matomo или платные решения.
Необходима глубокая интеграция с рекламными платформами и ремаркетинг — Umami не заменит GA в этих сценариях.
Если требуется хранение необработанных HTTP-логов для доступа аналитиков — может потребоваться дополнительный сбор логов.

Совет эксперта (одна строка)

Отдавайте приоритет минимальному сбору данных и автоматическим бэкапам — это снизит риски и упростит восстановление.

Короткое руководство для анонса (100–200 слов)

Umami — лёгкая приватная платформа для веб-аналитики, которую можно быстро развернуть на Debian 12. Эта инструкция шаг за шагом проведёт вас через настройку UFW, установку Node.js и MariaDB, получение SSL-сертификатов через Let’s Encrypt и развёртывание приложения через PM2 и Nginx. В руководстве также приведены рекомендации по безопасности, соответствию требованиям конфиденциальности, процедурам обновления и отката, а также чек-листы для администраторов и разработчиков. Umami отлично подходит проектам, где важна приватность пользователей и простота управления — вы получите трекинг без cookies и полный контроль над данными.

Итог

Umami — удобный выбор для self-hosted аналитики с фокусом на приватности.
Основные шаги: подготовка сервера, Node/MariaDB/Nginx, Certbot, настройка .env, запуск через PM2.
Обязательно настройте бэкапы, обновления и базовые меры безопасности.

Если у вас есть специфические требования по масштабированию, интеграции или соответствию правовым нормам — опишите их, и я помогу адаптировать инструкцию под конкретный сценарий.

Установка Umami Analytics на Debian 12 и настройка