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

MAATRIX

Flarum — один из немногих форумных движков, которые действительно легко ставятся и быстро летают, пока не начинаются мелочи: белый экран после установки, 500-я на форуме сразу после первого поста, разъехавшиеся права на storage/, битые пути в nginx или расширения, вокруг которых Composer отказывается работать. Ниже — конкретные причины и рабочие решения, которые снимают 90% проблем на чистом VPS с Ubuntu 24.04.

Требования к серверу: PHP, расширения, версии

Flarum написан на PHP и требует конкретный набор версий и расширений — большинство «непонятных» ошибок при установке вылезают именно здесь. На конец августа 2026 актуальная стабильная линия Flarum работает на PHP 8.2–8.3; более старый PHP 8.0/8.1 может частично работать, но лучше не рисковать — устанавливайте актуальную ветку.

Проверьте версию и набор расширений:

php -v
php -m | grep -Ei 'mbstring|dom|curl|gd|zip|json|openssl|tokenizer|fileinfo|intl'

Если чего-то не хватает (обычно intl, gd, zip или dom), ставим на Ubuntu/Debian:

sudo apt update
sudo apt install php8.3-cli php8.3-fpm php8.3-mbstring php8.3-curl \
  php8.3-gd php8.3-zip php8.3-xml php8.3-intl php8.3-mysql php8.3-bcmath
sudo systemctl restart php8.3-fpm

Отдельная частая грабля — на сервере стоит сразу несколько версий PHP (например, остался PHP 7.4 от старого проекта), и CLI-версия php, которой пользуется Composer, отличается от версии, которую использует nginx через php-fpm. Проверьте явно:

sudo update-alternatives --config php
php -v

и убедитесь, что в конфиге nginx fastcgi_pass смотрит на тот же сокет, что и активная версия PHP-FPM (/run/php/php8.3-fpm.sock, а не php7.4-fpm.sock).

Установка через Composer: типичные сбои

Flarum ставится не архивом, а через Composer — это осознанный выбор разработчиков движка, и он же источник половины вопросов у новичков. Базовая команда:

composer create-project flarum/flarum my-forum --stability=beta

Частые ошибки на этом шаге:

• composer: command not found — Composer не установлен глобально. Ставим:

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

• Your requirements could not be resolved — не хватает PHP-расширения (обычно ext-intl или ext-dom). Composer прямо пишет, чего не хватает — доустановите пакет и повторите.
• Таймаут или обрыв на Installing dependencies — на слабом VPS с 512 МБ–1 ГБ RAM Composer может упираться в память при разрешении зависимостей. Временно увеличьте лимит:

php -d memory_limit=-1 /usr/local/bin/composer create-project flarum/flarum my-forum --stability=beta

• Composer работает от root, а Flarum — от www-data — установка проходит, но потом веб-сервер не может писать в storage/. Правильнее сразу ставить от имени пользователя, под которым работает сайт, либо после установки поправить владельца (см. следующий раздел).

Если composer create-project зависает на загрузке пакетов с packagist.org — проверьте исходящий доступ к интернету с сервера и при необходимости настройте прокси в ~/.composer/config.json, либо используйте зеркало Composer.

Права на storage/ и public/assets — источник белого экрана и 500-й

Это самая частая причина «белого экрана» и 500 Internal Server Error сразу после установки или при попытке загрузить аватар/файл. Flarum активно пишет в несколько директорий: кеш, логи, загрузки, ассеты.

Веб-сервер (обычно www-data для nginx+php-fpm) должен иметь права на запись в:

sudo chown -R www-data:www-data /var/www/my-forum
sudo find /var/www/my-forum -type d -exec chmod 755 {} \;
sudo find /var/www/my-forum -type f -exec chmod 644 {} \;
sudo chmod -R 775 /var/www/my-forum/storage
sudo chmod -R 775 /var/www/my-forum/public/assets

Если форум установлен от вашего пользователя (например, deploy), а php-fpm пул настроен на www-data, то либо смените пользователя в пуле:

# /etc/php/8.3/fpm/pool.d/www.conf
user = deploy
group = deploy

либо просто добавьте www-data в группу владельца и дайте групповые права на запись — это чуть безопаснее, чем менять пользователя пула.

Проверить, что именно упало, можно в логах Flarum:

tail -n 50 /var/www/my-forum/storage/logs/flarum-*.log

Если файла лога вообще нет — значит, PHP не смог даже создать его, и дело почти всегда в правах на storage/.

Nginx: чистые URL, try_files, размер загрузок

Flarum использует чистые URL (без index.php в адресе) и один входной файл public/index.php, на который nginx должен направлять все запросы, которых нет на диске. Рабочий минимальный конфиг:

server {
    listen 80;
    server_name forum.example.ru;
    root /var/www/my-forum/public;
    index index.php;

    client_max_body_size 20M;

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

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

    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
        expires 30d;
        access_log off;
    }

    location ~ /\.(?!well-known) {
        deny all;
    }
}

Типичные проблемы этого шага:

• 404 на всех страницах, кроме главной — забыли try_files с ?$query_string, либо root указывает не на public/, а на корень проекта (тогда видны исходники и .env, что ещё и небезопасно).
• Ошибка 413 при загрузке аватара или картинки — client_max_body_size в nginx меньше, чем upload_max_filesize/post_max_size в php.ini. Синхронизируйте оба значения.
• 502 Bad Gateway — сокет php-fpm не совпадает с тем, что указано в fastcgi_pass, либо сам php-fpm не запущен: sudo systemctl status php8.3-fpm.

Если у вас на этом же сервере крутится несколько сайтов, полезно свериться со статьёй про настройку nginx как reverse proxy — те же принципы try_files и fastcgi_pass там разобраны подробнее.

SSL, forceHttps и «смешанный контент»

После выпуска сертификата (например, через Certbot) часто вылезает специфичная для Flarum проблема: сайт открывается по HTTPS, но часть ресурсов (аватары, иконки, вебсокет-уведомления) продолжает грузиться по HTTP, браузер ругается на mixed content, а иногда форум вообще редиректит в бесконечный цикл https → http → https.

Причина обычно в одном из двух мест:

1. base_url в конфиге Flarum не совпадает со схемой сайта. Проверьте config.php в корне установки — там должен быть чистый https://forum.example.ru, без завершающего слэша и без микса протоколов.
2. Nginx (или CDN/Cloudflare перед сервером) терминирует SSL, а Flarum об этом не знает и генерирует ссылки на http. В этом случае в конфиг nginx добавьте передачу схемы:

location ~ \.php$ {
    fastcgi_param HTTPS on;
    fastcgi_param HTTP_X_FORWARDED_PROTO https;
    # остальные fastcgi_param как обычно
}

Для получения самого сертификата на чистом VPS обычно достаточно стандартного Certbot-флоу — если раньше не настраивали, посмотрите статью про Let's Encrypt SSL на сервере: типовые грабли там пересекаются процентов на 70.

Бесконечный редирект-луп чаще всего лечится одной строкой — уберите принудительный return 301 https://... из блока server для порта 80, если такой же редирект уже делает Certbot/Cloudflare, иначе получаете два наложенных редиректа.

База данных, очереди и cron: чтобы форум не тормозил и не «забывал» письма

Flarum поддерживает MySQL и MariaDB. На новых VPS чаще ставят MariaDB — она чуть легче по памяти при том же SQL-диалекте. Минимальная настройка:

sudo apt install mariadb-server
sudo mysql_secure_installation
sudo mysql -e "CREATE DATABASE flarum CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
sudo mysql -e "CREATE USER 'flarum'@'localhost' IDENTIFIED BY 'СЛОЖНЫЙ_ПАРОЛЬ';"
sudo mysql -e "GRANT ALL PRIVILEGES ON flarum.* TO 'flarum'@'localhost';"

Важный нюанс: кодировка базы должна быть именно utf8mb4, а не utf8 — иначе форум упадёт с ошибкой при попытке сохранить пост с эмодзи или редкими символами Unicode (это одна из самых частых жалоб на форумах поддержки Flarum).

Второй момент, который многие пропускают — очередь задач. Flarum использует очередь для отправки email-уведомлений, генерации превью и других фоновых операций. Без настроенной очереди письма могут либо не отправляться вовсе, либо отправляться с задержкой при каждом заходе случайного пользователя (когда очередь синхронная и «размазана» по обычным HTTP-запросам). Рекомендуемый вариант — запуск воркера через systemd:

# /etc/systemd/system/flarum-queue.service
[Unit]
Description=Flarum Queue Worker
After=network.target mysql.service

[Service]
User=www-data
WorkingDirectory=/var/www/my-forum
ExecStart=/usr/bin/php flarum queue:work
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now flarum-queue

Если предпочитаете cron вместо постоянного воркера, добавьте:

* * * * * cd /var/www/my-forum && php flarum schedule:run >> /dev/null 2>&1

Логика cron-задач в Flarum похожа на Laravel (движок построен поверх него) — если раньше настраивали cron для других PHP-проектов, принципы из статьи про cron-задачи на сервере применимы и здесь один в один.

Расширения, конфликты и производительность

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

Практические правила, которые экономят часы отладки:

• Обновляйте по одному расширению за раз и проверяйте форум после каждого — так конфликт сразу видно.
• Держите staging-копию форума на том же VPS (отдельная база + отдельная директория) для проверки обновлений перед продакшеном.
• Очищайте кеш после любых изменений конфигурации:

php flarum cache:clear

• Если форум начал тормозить после установки десятка расширений — проверьте storage/logs на предмет PHP warning/deprecated от конкретных расширений и включите OPcache в php.ini (opcache.enable=1, opcache.memory_consumption=128), если он ещё не включён — для Flarum это ощутимая разница в отклике.

Если тормозит не сам Flarum, а сервер в целом (диск, память, конкурентная нагрузка от других сайтов на том же VPS), общая методология из статьи сайт тормозит на VPS: диагностика поможет быстро понять, где узкое место — до того как начинать разбираться в расширениях форума.

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