Plausible Analytics на сервере: частые ошибки и решения

MAATRIX

Plausible Analytics выглядит просто, пока не разворачиваете его сами: под капотом у него ClickHouse, PostgreSQL и набор переменных окружения, которые легко перепутать. В этой статье — конкретные ошибки, с которыми сталкиваются при self-hosted установке Plausible, и как их закрыть без пересборки всего стека с нуля.

Архитектура self-hosted Plausible и откуда берутся проблемы

Официальный self-hosted дистрибутив Plausible — это не одно приложение, а три контейнера, которые обязаны договориться друг с другом:

• plausible — сам Elixir/Phoenix-бэкенд и веб-интерфейс;
• plausible_db — PostgreSQL, хранит пользователей, сайты, настройки, цели;
• plausible_events_db — ClickHouse, хранит сами события трафика (это тяжёлая часть).

Официальный docker-compose.yml из репозитория plausible/hosting поднимает все три сервиса плюс mail (для локальной отправки писем через SMTP-релей, если свой не настроен) и geoip volume для страны/города посетителей.

Большинство проблем при установке Plausible укладываются в три категории:

1. Ресурсы — ClickHouse не стартует или падает под нагрузкой на маленьком VPS.
2. Сеть и SMTP — письма для подтверждения аккаунта не доходят.
3. Реверс-прокси и домен — трекинг-скрипт грузится, но события не долетают до бэкенда.

Ниже — по каждому пункту с конкретными командами.

ClickHouse не запускается или падает через несколько минут

Самая частая жалоба на форумах Plausible: контейнер plausible_events_db либо не стартует вовсе, либо падает с Killed в логах через некоторое время после старта. Причины почти всегда одни и те же.

1. Не хватает памяти. ClickHouse не любит работать на VPS с 1 ГБ RAM — минимум, с которым он стабилен, это 2 ГБ, комфортно — от 4 ГБ, если сайт с трафиком выше нескольких тысяч визитов в день. Проверьте, не сработал ли OOM killer:

dmesg -T | grep -i "killed process"
docker logs plausible_events_db --tail 100

Если видите clickhouse-server invoked oom-killer — либо добавляйте RAM, либо ограничивайте память ClickHouse через docker-compose.clickhouse.yml (в нём есть готовый пример) и добавляйте swap как временную подушку. Подробно про правильный размер файла подкачки под конкретный сервис — в статье про swap-файл: для ClickHouse под Plausible достаточно 1-2 ГБ, чтобы пережить пики без падения контейнера, но постоянно жить на swap ClickHouse не должен — это резко просаживает запись событий.

2. Не выставлен vm.max_map_count. ClickHouse активно использует memory-mapped файлы, и дефолтное ядерное значение (65530) ему часто мало на серверах с логами и большим числом партов. Симптом — падение сразу после старта с ошибкой вида Cannot mmap. Фикс:

sudo sysctl -w vm.max_map_count=262144
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

3. Диск заполнен. ClickHouse хранит события в партах по дням, и при активном трафике база растёт быстрее, чем ожидают. Проверьте место:

df -h /var/lib/docker
docker exec plausible_events_db du -sh /var/lib/clickhouse

Если диск забит, ClickHouse откажется писать новые данные и начнёт сыпать ошибками в логах plausible-контейнера про недоступность event store. Общие грабли с ClickHouse на сервере (в том числе не связанные с Plausible) разобраны отдельно в статье про ClickHouse на сервере — полезно, если стек уже разросся за пределы одного Plausible.

Не приходят письма: подтверждение регистрации и алерты

После первого запуска Plausible просит подтвердить e-mail — и часто письмо просто не приходит. По умолчанию self-hosted образ включает встроенный mail-контейнер (Postfix-обёртку), который отправляет письма напрямую, без внешнего SMTP-релея. Проблема в том, что прямая отправка с residential/VPS-IP без обратной DNS-записи (PTR) массово улетает в спам или блокируется получателем.

Что проверить:

1. PTR-запись для IP сервера. Без неё многие почтовые провайдеры (особенно Gmail и Mail.ru) режут письма молча.
2. Порт 25 исходящий не заблокирован хостером. Часть провайдеров блокирует 25-й порт по умолчанию — уточняйте у хостера или сразу берите тариф, где исходящая почта не режется.
3. Переключитесь на внешний SMTP. Это надёжнее, чем чинить встроенный релей. В .env файле Plausible пропишите:

SMTP_HOST_ADDR=smtp.yourprovider.com
SMTP_HOST_PORT=587
SMTP_USER_NAME=noreply@yourdomain.com
SMTP_USER_PWD=ваш_пароль_приложения
SMTP_HOST_SSL_ENABLED=true
MAILER_EMAIL="Plausible <noreply@yourdomain.com>"

После правки — пересоздайте контейнер plausible (не просто restart, а docker compose up -d --force-recreate plausible), иначе переменные окружения не подхватятся.

Общие проблемы с отправкой почты с VPS, включая настройку SPF/DKIM/DMARC, разобраны в статье ne-otpravlyaetsya-pochta-s-servera — там же объяснено, как проверить, не находится ли IP в чёрных списках.

Трекинг-скрипт загружается, но события не считаются

Это, пожалуй, самая обидная ошибка — сайт подключён, скрипт plausible.js виден в исходном коде и грузится без 404, а в дашборде — ноль визитов. Причины по убыванию частоты:

1. Домен в настройках сайта не совпадает с реальным. Plausible матчит события по полю data-domain в скрипте и домену, зарегистрированному в UI. Проверьте, что они идентичны включая www. — example.com и www.example.com для Plausible это разные сайты.

<script defer data-domain="example.com" src="https://analytics.example.com/js/script.js"></script>

2. CSP (Content-Security-Policy) блокирует запрос. Если на сайте настроен строгий CSP-заголовок, добавьте домен аналитики в script-src и connect-src:

Content-Security-Policy: script-src 'self' https://analytics.example.com; connect-src 'self' https://analytics.example.com;

3. Адблокеры и privacy-расширения режут сам скрипт. Это не баг Plausible, а его же плюс — многие блокировщики банят по имени файла plausible.js даже у self-hosted инсталляций. Если хотите снизить процент потерь, переименуйте путь к скрипту через DISABLE_REGISTRATION и кастомный alias в nginx-конфиге (proxy_pass на /js/script.js под другим именем) — это разрешённый Plausible способ обхода блокировок по паттерну имени файла, а не подмена функциональности.

4. Реверс-прокси не пробрасывает заголовки. Если Plausible стоит за nginx или Traefik, и события не долетают именно оттуда — проверьте, что прокси не режет X-Forwarded-For (он нужен для геолокации и подсчёта уникальных посетителей по IP+User-Agent хэшу без cookies). Пример рабочего блока nginx:

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

Если общая логика настройки nginx как прокси вызывает вопросы — базовый разбор с частыми ошибками есть в статье nginx-kak-revers-proksi-na-servere-chastye-oshibki-i-resheniya.

SSL, домен и переменная BASE_URL

Отдельный источник боли — несовпадение BASE_URL в .env с реальным адресом, по которому доступна панель. Если вы поставили Plausible на http:// для теста, а потом навесили SSL через Let's Encrypt, но забыли поменять BASE_URL, получите либо бесконечный редирект (redirect loop), либо предупреждения о "insecure cookie" и слетающие сессии входа.

Правильная последовательность:

# в .env
BASE_URL=https://analytics.example.com
SECRET_KEY_BASE=$(openssl rand -base64 64 | tr -d '\n')

SECRET_KEY_BASE генерируется один раз при установке — если вы меняете его на уже работающем инстансе, все активные сессии слетят, это нормально.

Если сертификат не выпускается вовсе (Let's Encrypt не может пройти HTTP-01 challenge, потому что домен ещё смотрит не туда, или порт 80 занят другим виртуальным хостом) — по симптомам и разбору кейсов ближе всего статья nginx-ne-primenyaet-ssl-prichiny-i-reshenie, логика диагностики та же независимо от того, что именно вы проксируете.

Обновление версии: миграции падают или дашборд не открывается

Plausible активно развивается, и между минорными версиями иногда меняется схема ClickHouse или PostgreSQL. Обновление "на живую" через docker compose pull && docker compose up -d обычно проходит гладко, но есть нюансы:

• Всегда снимайте бэкап перед обновлением — миграции ClickHouse необратимы штатными средствами, откатить версию назад без бэкапа вы не сможете.
• Смотрите changelog релиза перед обновлением через несколько версий сразу (например, с 2.0 на 2.1+) — иногда там прямо указано, что нужен промежуточный шаг.
• Если после апдейта контейнер plausible падает в рестарт-луп с ошибкой миграции в логах, откатите образ на предыдущий тег версии в docker-compose.yml, восстановите бэкап и обновляйтесь по одной минорной версии за раз, а не через несколько релизов скопом.

Бэкап делается штатными средствами обеих БД:

# PostgreSQL
docker exec plausible_db pg_dump -U postgres plausible_db > plausible_pg_backup.sql

# ClickHouse (структура + данные через встроенный backup)
docker exec plausible_events_db clickhouse-client \
  --query "BACKUP DATABASE plausible_events_db TO Disk('backups', 'plausible_ch_backup')"

Общие приёмы автоматизации бэкапов и cron-расписания для регулярного снятия копий разобраны в статье cron-zadachi-na-servere-chastye-oshibki-i-resheniya — то же самое расписание легко применить и для дампов Plausible.

Ресурсы сервера: сколько реально нужно

Ориентировочные требования (это именно ориентир — точная нагрузка зависит от числа сайтов, событий и глубины хранения истории):

ClickHouse — основной потребитель RAM в этом стеке, PostgreSQL под Plausible обычно лёгкий (хранит только метаданные, не сырые события). Если параллельно на том же сервере крутится ещё и сайт с базой, закладывайте память отдельно на каждый компонент — не рассчитывайте, что ClickHouse "подожмётся" под нагрузкой соседних сервисов, он скорее упадёт по OOM, чем сам ограничит аппетит.

Общий подход к продакшен-развёртыванию через docker-compose, включая лимиты ресурсов на контейнеры, описан в статье docker-compose-dlya-prodakshena-na-servere-chastye-oshibki-i-resheniya — те же приёмы (memory limits, restart policy, healthcheck) применимы и к стеку Plausible.

Частые вопросы