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

MAATRIX

FreeScout — лёгкая self-hosted замена Help Scout: тикеты по почте, без ежемесячной платы за SaaS и без лишних мегабайт на сервере, как у более тяжёлых helpdesk-систем. Но именно из-за лёгкости FreeScout спотыкается о вещи, которые тяжёлые системы решают за вас автоматически: права на файлы, cron, IMAP-подключение, лимиты PHP. Ниже — частые ошибки после установки и в работе, с конкретными командами для диагностики и починки.

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

Ставите FreeScout, открываете домен — пустая белая страница либо «500 Internal Server Error» без деталей. Первым делом включите отображение ошибок, чтобы увидеть настоящую причину, а не гадать:

sudo nano /var/www/freescout/.env
# APP_DEBUG=true

Обновите страницу — Laravel (на нём построен FreeScout) покажет конкретное исключение. Три причины встречаются чаще всего. Первая — не сгенерирован APP_KEY:

cd /var/www/freescout
php artisan key:generate

Вторая — права на каталоги storage и bootstrap/cache: веб-сервер должен иметь возможность туда писать (логи, кэш, сессии, сгенерированные файлы). Если владелец файлов — root или ваш пользователь, а php-fpm работает от www-data, будет либо 500, либо тихо неработающие функции:

sudo chown -R www-data:www-data /var/www/freescout/storage /var/www/freescout/bootstrap/cache
sudo chmod -R 775 /var/www/freescout/storage /var/www/freescout/bootstrap/cache

Третья — не заданы параметры подключения к MySQL в .env (DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD) или база данных ещё не создана. Проверьте подключение отдельно: mysql -u пользователь -p -h 127.0.0.1 база_данных. Когда причина устранена, обязательно верните APP_DEBUG=false в проде — с включённым дебагом при ошибке в браузер утекают пути на сервере и куски конфига, а это лишняя информация для любого, кто наткнётся на страницу с исключением.

Письма не забираются с почтового ящика

Тикеты создаются вручную, но письма, которые клиенты шлют на support-адрес, в FreeScout не попадают. Первое, что нужно понять: FreeScout не слушает почту постоянно, он забирает её по расписанию через IMAP — команда php artisan freescout:fetch-emails должна выполняться регулярно через cron (об этом ниже). Если cron настроен, а письма всё равно не приходят, запустите забор вручную и смотрите вывод:

cd /var/www/freescout
php artisan freescout:fetch-emails -vvv

Вывод почти всегда называет причину прямо: неверный логин/пароль, TLS-ошибка, таймаут подключения к IMAP-серверу. Частый случай — почтовый провайдер (Gmail, Yandex) требует пароль приложения вместо обычного пароля аккаунта, если включена двухфакторная аутентификация. Ещё одна причина — неверные параметры порта и шифрования в настройках ящика: для IMAP с SSL обычно порт 993, для STARTTLS — 143. Проверить доступность сервера отдельно от FreeScout можно так:

openssl s_client -connect imap.example.com:993 -crlf

Если соединение устанавливается и запрашивает логин — сеть и TLS в порядке, проблема в учётных данных или настройках самого ящика в FreeScout (Manage → Mailboxes → нужный ящик → Incoming Email). Также проверьте, что на стороне почтового провайдера не стоит блокировка «менее безопасных приложений» — у некоторых сервисов IMAP-доступ для сторонних клиентов отключён по умолчанию и его нужно включить явно в настройках ящика.

Cron не выполняет задачи вовремя

Письма не забираются, уведомления не отправляются, автоматические действия по тикетам не срабатывают — при этом ручной запуск команд работает без ошибок. Это значит, что cron либо не настроен, либо настроен неверно. FreeScout, как и любое Laravel-приложение, ожидает одну запись в crontab, которая раз в минуту запускает планировщик, а он уже сам решает, каким внутренним задачам пора выполниться:

sudo crontab -u www-data -e

* * * * * cd /var/www/freescout && php artisan schedule:run >> /dev/null 2>&1

Важный нюанс — запись должна быть именно от пользователя, от которого работает веб-сервер (www-data в большинстве конфигураций Ubuntu/Debian), иначе задачи выполнятся с чужими правами и упрутся в те же проблемы доступа к storage, что и в первом разделе. Проверить, что crontab вообще подхватился, можно командой sudo crontab -u www-data -l. Если запись есть, а задачи всё равно не выполняются, проверьте, что системный cron-демон вообще запущен: systemctl status cron. Отдельная деталь для тех, кто переносит FreeScout между серверами: часовой пояс сервера должен совпадать с тем, что задан в .env (APP_TIMEZONE) — иначе «раз в минуту» будет работать корректно, а вот задачи, привязанные к конкретному времени суток (например, ежедневные напоминания), поедут. Подробнее о типичных граблях cron на сервере — в статье про частые ошибки cron-задач.

Модули не устанавливаются или ломают интерфейс

FreeScout распространяется по модели open-core: базовая часть бесплатна, часть функций — платные модули из официального маркетплейса. При попытке установить модуль через интерфейс возникает ошибка записи файлов либо после установки страница модуля выдаёт 500. Причина в девяти случаях из десяти — те же права на запись, что и при установке: модуль распаковывается во внутренние каталоги Modules/ и storage, и если веб-сервер не может туда писать, установка обрывается на середине, оставляя приложение в неконсистентном состоянии.

sudo chown -R www-data:www-data /var/www/freescout/Modules
sudo chmod -R 775 /var/www/freescout/Modules

Вторая частая причина — отсутствует PHP-расширение zip, без которого сервер не может распаковать архив модуля:

php -m | grep zip
sudo apt install php8.3-zip
sudo systemctl restart php8.3-fpm

(версию PHP подставьте свою — уточнить можно командой php -v). После неудачной установки модуля стоит явно почистить кэш конфигурации и представлений, иначе Laravel может продолжать отдавать закэшированную версию с ошибкой даже после того, как файлы поправлены:

php artisan cache:clear
php artisan config:clear
php artisan view:clear

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

Большие вложения не загружаются

Клиент прикрепляет к письму файл, а в FreeScout он либо не появляется, либо интерфейс молча обрывает загрузку. Здесь ограничение почти всегда стоит не в самом FreeScout, а в PHP или в веб-сервере перед ним. Проверьте актуальные лимиты PHP:

php -i | grep -E 'upload_max_filesize|post_max_size|memory_limit'

Если значения по умолчанию (обычно 2M или 8M), поднимите их в php.ini того пула, который обслуживает FreeScout:

upload_max_filesize = 25M
post_max_size = 30M
memory_limit = 256M

post_max_size должен быть больше upload_max_filesize, иначе PHP отбросит запрос ещё до того, как разберёт, что там за файл. После правки — перезапуск php-fpm: sudo systemctl restart php8.3-fpm. Если FreeScout стоит за nginx, проверьте отдельно директиву client_max_body_size в конфиге сайта — по умолчанию nginx режет тело запроса на 1 МБ, и даже правильные лимиты PHP не помогут, если nginx обрежет запрос раньше:

server {
    client_max_body_size 30M;
    ...
}

Про типовые ошибки конфигурации nginx как обратного прокси перед PHP-приложениями — отдельная статья про частые ошибки nginx как обратного прокси. Отдельно стоит проверить max_execution_time для php-fpm — на медленном канале загрузка крупного файла может просто не успеть выполниться до таймаута, и тогда лечится это уже не увеличением лимита размера, а увеличением времени.

Обновление ломает установку

После composer update или обновления через интерфейс FreeScout перестаёт открываться, либо часть функций пропадает. Первое правило — перед любым обновлением делать бэкап базы данных и каталога проекта целиком, потому что откат вручную дольше и рискованнее, чем восстановление из бэкапа. Если обновление всё же прошло и что-то сломалось, порядок действий такой:

cd /var/www/freescout
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan cache:clear
php artisan config:clear
php artisan view:clear

Частая причина проблем после обновления — не выполненные миграции базы данных: код ожидает новые поля или таблицы, которых ещё нет. php artisan migrate --force их применяет (флаг --force нужен, потому что по умолчанию Laravel просит подтверждения на проде). Вторая причина — закэшированная старая конфигурация: Laravel умеет кэшировать .env и роуты для скорости, и если вы обновили .env, а старый кэш конфигурации остался, приложение продолжит жить по старым настройкам. Команды cache:clear и config:clear выше как раз снимают этот кэш. Если после всего этого сайт всё равно не открывается — временно включите APP_DEBUG=true, как в первом разделе, чтобы увидеть точный текст исключения, а не «500» без подробностей.

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