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

MAATRIX

Matomo (бывший Piwik) — самый популярный self-hosted аналог Google Analytics: данные посетителей остаются на вашем сервере, а не утекают третьей стороне. Но именно потому, что это полноценное PHP-приложение с MySQL под капотом, а не облачный скрипт, оно ломается по-своему. В статье — самые частые проблемы при установке и эксплуатации Matomo на своём сервере и рабочие способы их решить.

Требования к серверу и типичные промахи на старте

Matomo — это PHP-приложение поверх MySQL/MariaDB, и большинство проблем начинается ещё на этапе выбора окружения. Актуальные на конец августа 2026 года минимальные требования:

• PHP 8.1+ (Matomo 5.x официально поддерживает линейку 8.1–8.3, новые минорные версии стоит проверять по таблице совместимости перед обновлением);
• MySQL 5.7+/8.0+ или MariaDB 10.4+;
• модули PHP: mysqli или PDO_MYSQL, mbstring, gd или imagick, curl, zip, xml, intl (без intl не будет корректной локализации и часовых поясов);
• минимум 2 ГБ RAM для небольшого проекта, от 4 ГБ и отдельный диск под БД — при трафике от нескольких сотен тысяч визитов в месяц.

Частая ошибка — ставить Matomo на минимальный VPS с 512 МБ–1 ГБ RAM «на попробовать». Установщик проходит, первые дни всё работает, а через пару недель, когда база визитов подрастает, начинаются зависания при архивации отчётов (cron-archiving съедает всю память) и MySQL периодически падает по OOM. Если планируете собирать данные хотя бы с одного среднего сайта — берите сервер с запасом по RAM, а не «впритык под установщик».

Вторая типичная промашка — забыть про intl и gd: без них графики и геолокация в отчётах не работают. Проверить набор модулей:

php -m | grep -E 'mysqli|mbstring|gd|curl|zip|xml|intl'

Если чего-то не хватает — на Ubuntu/Debian с PHP-FPM:

apt install php8.2-mysql php8.2-mbstring php8.2-gd php8.2-curl php8.2-zip php8.2-xml php8.2-intl
systemctl restart php8.2-fpm

Белый экран и ошибки PHP при установке

Самая частая жалоба новичков — «открываю Matomo, а там белый экран или голая ошибка PHP вместо интерфейса». Причины почти всегда одни и те же.

1. Не хватает памяти для PHP. Matomo рекомендует memory_limit не ниже 256M, а для больших инсталляций — 512M и выше. Смотрим:

php -i | grep memory_limit

Правим в /etc/php/8.2/fpm/php.ini (путь зависит от версии PHP):

memory_limit = 512M
max_execution_time = 300
upload_max_filesize = 64M
post_max_size = 64M

После правки — обязательно systemctl restart php8.2-fpm, простой reload конфиг PHP-FPM подхватывает не всегда.

2. Права на директории tmp/ и config/. Веб-сервер должен иметь право писать в tmp/, tmp/cache, tmp/sessions, tmp/templates_c и в config/config.ini.php. Если Matomo распакован от root, а PHP-FPM работает от www-data, установщик падает с ошибкой прав или молча не сохраняет конфиг:

chown -R www-data:www-data /var/www/matomo
find /var/www/matomo/tmp -type d -exec chmod 755 {} \;

3. Отладка белого экрана. Включите вывод ошибок временно (не забудьте выключить после диагностики) — добавьте в config/config.ini.php секцию:

[Development]
enabled = 1

или посмотрите лог PHP-FPM и веб-сервера напрямую:

tail -n 50 /var/log/nginx/error.log
tail -n 50 /var/log/php8.2-fpm.log

Почти всегда в логе виден точный класс ошибки — недостающее расширение, проблема с правами или несовместимая версия PHP.

Настройка веб-сервера: nginx и Apache

Matomo одинаково хорошо работает и за nginx с PHP-FPM, и за Apache с mod_php — выбор зависит от того, что уже крутится на сервере (если поднимаете инфраструктуру с нуля, нюансы разобраны в статье Apache с mod_php: частые ошибки и решения). Для новой установки чаще берут nginx, минимальный рабочий конфиг:

server {
    listen 443 ssl http2;
    server_name analytics.example.com;

    root /var/www/matomo;
    index index.php;

    ssl_certificate     /etc/letsencrypt/live/analytics.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/analytics.example.com/privkey.pem;

    client_max_body_size 64M;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_read_timeout 300;
    }

    # закрываем служебные файлы от прямого доступа
    location ~ ^/(config|tmp|core|lang)/.*\.(php|ini)$ {
        deny all;
        return 403;
    }

    location ~ /\.ht {
        deny all;
    }
}

Частая ошибка — забыть fastcgi_read_timeout: без увеличенного таймаута браузер получает 504 при первом заходе в «Посетители в реальном времени» или при ручном запуске архивации через UI.

Настройку SSL-сертификата для домена аналитики удобнее всего сделать через Let's Encrypt — если раньше не настраивали, пригодится статья Let's Encrypt SSL: частые ошибки и решения.

MySQL/MariaDB: подключение, кодировка, производительность

Matomo хранит данные в MySQL/MariaDB, и большая часть «загадочных» ошибок интерфейса на самом деле упирается в базу данных.

Неверная кодировка. Если база создана не в utf8mb4, вы получите ошибки вида Incorrect string value на кириллице или эмодзи в URL/заголовках страниц. Создавайте базу сразу правильно:

CREATE DATABASE matomo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'matomo'@'localhost' IDENTIFIED BY 'сложный_пароль';
GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost';
FLUSH PRIVILEGES;

max_allowed_packet слишком маленький. При активном сборе событий с крупных сайтов можно упереться в ограничение размера пакета MySQL — симптом виден как ошибки записи в tmp/logs/errors.log с упоминанием packet size. Правим в /etc/mysql/mariadb.conf.d/50-server.cnf или в my.cnf:

[mysqld]
max_allowed_packet = 64M
innodb_buffer_pool_size = 1G

innodb_buffer_pool_size стоит выставлять исходя из объёма RAM — ориентировочно 50–70% доступной памяти на выделенной под БД машине, но не в ущерб PHP-FPM и веб-серверу, если всё крутится на одном хосте.

Таблица log_visit растёт и запросы тормозят. Это нормально для активно посещаемых сайтов — Matomo хранит «сырые» визиты постоянно, если не настроено удаление старых логов. Общие принципы диагностики медленных запросов применимы и к Matomo: MySQL: медленные запросы, причины и решение. У самой Matomo есть встроенный механизм очистки — [Deletelogs] в config.ini.php, о нём ниже.

Если база вообще не поднимается после установки или перезагрузки сервера — общий чек-лист диагностики MySQL пригодится вне зависимости от того, что на нём крутится: MySQL на сервере: частые ошибки и решения.

Архивация отчётов и cron: почему данные «не обновляются»

Это, пожалуй, главный источник недоумения у новых пользователей Matomo: счётчик посещений где-то тикает, а на дашборде цифры не меняются или показывают вчерашний день. Причина — архивация (archiving).

По умолчанию Matomo может архивировать отчёты «на лету», когда кто-то открывает дашборд — удобно для маленьких сайтов, но на среднем и большом трафике каждое открытие отчёта превращается в тяжёлый пересчёт, и интерфейс подвисает на 10–30 секунд, а иногда падает по таймауту. Правильная практика — отключить архивацию в браузере и включить её по cron.

В config/config.ini.php:

[General]
enable_browser_archiving_triggering = 0

И добавить задание в crontab (обычно от имени www-data):

crontab -u www-data -e

*/15 * * * * /usr/bin/php8.2 /var/www/matomo/console core:archive --url=https://analytics.example.com/ >> /var/www/matomo/tmp/logs/archive.log 2>&1

Частые ошибки здесь:

• Cron не от того пользователя. Если archiving запускается от root, а файлы Matomo принадлежат www-data, скрипт создаёт кэш-файлы с правами root, и веб-сервер потом не может их читать — начинаются странные 500-е ошибки именно на страницах с отчётами.
• Не указан правильный путь к PHP. На сервере может быть несколько версий PHP (CLI по умолчанию — одна, FPM для сайта — другая). Проверяйте явно: which php8.2.
• Слишком частый или слишком редкий запуск. Раз в 15 минут — разумный компромисс для большинства сайтов; дашборд «Посетители в реальном времени» на частоту cron не влияет — он работает по логам напрямую.

Общие принципы диагностики cron-задач, которые падают тихо, разобраны в статье Cron-задачи на сервере: частые ошибки и решения — первым делом смотрите archive.log и системный /var/log/syslog на предмет запуска самого cron-демона.

Учёт визитов: adblock, JS-трекер и первый визит не засчитан

Вторая по частоте жалоба — «Matomo не считает визиты» или считает меньше, чем реально заходят.

Блокировщики рекламы. Стандартный путь /matomo.js и /matomo.php многие блокировщики распознают по имени и режут — это касается даже self-hosted установки, списки блокировки часто ловят слово matomo/piwik напрямую, а не по домену. Решение — включить встроенный прокси-трекер Matomo (Tracker Proxy), который отдаёт JS-файл и принимает данные через путь без сигнатур блокировщиков (раздел «Отслеживание → Трекер JavaScript» в админке).

Неправильный siteId в коде трекера. Частая невнимательность при копировании кода — вставили код от одного сайта (idSite=1) на домен, заведённый под другим ID. Визиты в этом случае улетают, но в другой сайт внутри той же установки, и кажется, что трекинг вообще не работает.

CORS и смешанный контент. Если сайт на HTTPS, а Matomo отдаётся по HTTP, браузер молча блокирует запрос к трекеру с ошибкой Mixed Content или CORS. Проверяйте вкладку Network в devtools — запрос к matomo.php должен возвращать 200 или 204, а не падать до отправки.

GeoIP и точность геолокации. Из коробки Matomo использует встроенную (менее точную) базу геолокации по IP. Для точных данных по странам/городам нужно подключить внешнюю базу (например, DB-IP или MaxMind GeoLite2 через плагин) и обновлять её отдельным cron-заданием — автоматически Matomo это не делает.

Хранение данных, приватность и очистка старых логов

Одно из главных преимуществ self-hosted аналитики — контроль над тем, где и сколько хранятся данные, что важно с учётом требований GDPR/152-ФЗ. Но за это приходится платить местом на диске: без настройки очистки таблица log_visit растёт бессрочно.

Включить автоматическое удаление старых «сырых» визитов (агрегированные отчёты при этом остаются) — в config/config.ini.php:

[Deletelogs]
delete_logs_enable = 1
delete_logs_schedule_lowest_interval = 7
delete_logs_older_than = 180

Здесь delete_logs_older_than — сколько дней хранить детальные логи визитов; агрегированные отчёты хранятся отдельно и этим механизмом не удаляются (управляются в разделе «Приватность» админки, там же настраивается анонимизация IP).

Отдельно стоит настроить резервное копирование самой базы Matomo — потеря исторической аналитики за годы обычно куда болезненнее, чем потеря конфигов. Общий подход к бэкапу MySQL разобран в статье Бэкап MySQL: частые ошибки и решения — для Matomo дополнительно стоит бэкапить директорию config/ с настройками и токенами API.

Если ориентируетесь на объём диска — точную оценку лучше делать по фактическому приросту таблицы log_visit за первую неделю работы и экстраполировать: трафик и глубина хранимых логов у всех разные, общие цифры тут ориентир, а не норма.

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