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

MAATRIX

SuiteCRM — открытый форк SugarCRM, и на бумаге это отличная self-hosted CRM: без лицензий, с полным контролем над данными клиентов. На практике же после установки на боевой сервер она регулярно преподносит сюрпризы — то белый экран после апдейта модуля, то cron не запускает workflow, то письма из CRM молча теряются. Ниже — конкретные ошибки, с которыми сталкиваются админы SuiteCRM на VPS, и рабочие решения без танцев с бубном.

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

SuiteCRM — тяжелее среднего PHP-приложения: движок workflow, отчёты, интеграции с почтой съедают память и CPU при каждом cron-тике. Минимум, с которого стоит начинать:

• 2 vCPU, 4 ГБ RAM — для команды до 15-20 пользователей с умеренной нагрузкой;
• 8+ ГБ RAM — если активно используете Process Definitions (workflow-движок) и отчёты по большим таблицам;
• PHP 8.1 или 8.2 (SuiteCRM 7.14+ поддерживает 8.1/8.2, более старые ветки требуют 7.4 — проверьте совместимость своей версии перед апгрейдом PHP);
• MySQL 8.0 или MariaDB 10.6+;
• SSD-диск — на HDD полнотекстовый поиск и генерация отчётов ползут заметно.

Частая ошибка на старте — ставить SuiteCRM на минимальный тариф 1 ГБ RAM «чтобы посмотреть». Установщик отработает, но при первом же импорте контактов или запуске workflow процесс упрётся в память и просто оборвётся без внятной ошибки в интерфейсе — придётся лезть в php-fpm или apache error log, чтобы понять, что произошло.

Второй промах — установка через git clone вместо официального релизного архива. В репозитории может не быть скомпилированных vendor-зависимостей или там будет ветка разработки с нестабильным кодом. Берите tar.gz с страницы релизов SuiteCRM и разворачивайте именно его.

cd /var/www
wget https://github.com/salesagility/SuiteCRM/releases/download/v7.14.4/SuiteCRM-7.14.4.zip
unzip SuiteCRM-7.14.4.zip -d suitecrm
chown -R www-data:www-data /var/www/suitecrm
find /var/www/suitecrm -type d -exec chmod 755 {} \;
find /var/www/suitecrm -type f -exec chmod 644 {} \;

Права здесь не формальность: неверные владелец/маска — источник половины «непонятных» ошибок SuiteCRM на этапе установки.

Белый экран (WSOD) и ошибки PHP

Белый экран без текста — классика SuiteCRM, потому что по умолчанию вывод ошибок в браузер отключён (и правильно — в проде их показывать нельзя). Диагностика начинается с логов, не с угадывания.

tail -f /var/log/php8.1-fpm.log
tail -f /var/www/suitecrm/suitecrm.log
tail -f /var/log/apache2/error.log   # или nginx error.log

Самые частые причины WSOD:

• Не хватает PHP-расширений. SuiteCRM требует mbstring, imap, zip, gd, curl, xml, intl, mysqli, soap. Если после апдейта PHP пропало расширение imap — модуль почты умирает молча, а иногда падает вся страница.

apt install php8.1-mbstring php8.1-imap php8.1-zip php8.1-gd php8.1-curl php8.1-xml php8.1-intl php8.1-mysql php8.1-soap
systemctl restart php8.1-fpm

• memory_limit слишком мал. SuiteCRM официально просит минимум 256 МБ, на импорте больших CSV или тяжёлых отчётах реально нужно 512 МБ.

; /etc/php/8.1/fpm/php.ini
memory_limit = 512M
max_execution_time = 300
upload_max_filesize = 100M
post_max_size = 100M

• Конфликт версии PHP с версией SuiteCRM. SuiteCRM 7.11 и старее ломается на PHP 8.0+ из-за устаревшего синтаксиса. Если вы на shared/облачном образе с «последней» PHP, а CRM старая — либо откатывайте PHP через update-alternatives, либо мигрируйте на актуальный релиз SuiteCRM.

Включить отображение ошибок временно, только для диагностики, можно через error_reporting(E_ALL); ini_set('display_errors', 1); в начале index.php — и обязательно откатить после того, как нашли причину, иначе стектрейсы с путями на сервере будут видны всем посетителям.

Ошибки подключения к базе данных и медленные запросы

Вторая по частоте категория проблем — MySQL/MariaDB. SuiteCRM создаёт заметно больше таблиц и индексов, чем среднее CRM-приложение, и база быстро становится узким местом.

Типичная ошибка при установке:

Could not connect to database. SQLSTATE[HY000] [2002] Connection refused

Проверьте, что MySQL слушает нужный сокет/порт и что пользователь БД имеет права именно на нужную базу:

mysql -u suitecrm_user -p -e "SHOW GRANTS;"
systemctl status mysql

Если SuiteCRM и MySQL на разных серверах — убедитесь, что bind-address в /etc/mysql/mysql.conf.d/mysqld.cnf не заперт на 127.0.0.1, и что фаервол пропускает порт 3306 только с IP приложения (открывать 3306 наружу всем — плохая идея).

Отдельная головная боль — sql_mode. SuiteCRM плохо дружит со строгим STRICT_TRANS_TABLES в некоторых версиях: вставки с пустыми датами или нулевыми внешними ключами падают с ошибкой на ровном месте. Если видите в логе Incorrect date value при сохранении записи, которая явно валидна с точки зрения пользователя, — смотрите в сторону sql_mode:

SET GLOBAL sql_mode = 'NO_ENGINE_SUBSTITUTION';

Меняйте sql_mode осознанно и только если это официально рекомендовано для вашей версии — полное отключение строгого режима навсегда не лучшая практика, это скорее временный костыль на время перехода на актуальную версию CRM.

Медленные запросы на списках лидов и отчётах почти всегда решаются индексами на кастомных полях (SuiteCRM их не создаёт автоматически при добавлении полей через Studio) и включённым slow_query_log для диагностики:

SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 2;

Если тема MySQL на сервере интересна отдельно — есть разбор частых проблем в статье про типовые ошибки MySQL на сервере.

Cron, Scheduler и workflow, которые не запускаются

SuiteCRM не работает без правильно настроенного cron — через него крутится очередь email, напоминания, workflow-процессы и запланированные отчёты. Если в интерфейсе виден статус «Scheduler» с зелёной галкой, но задачи фактически не выполняются — почти всегда дело в системном cron, а не в самой CRM.

Правильная запись в crontab пользователя, от которого работает веб-сервер (обычно www-data):

crontab -u www-data -e

* * * * * cd /var/www/suitecrm; php -f cron.php > /dev/null 2>&1

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

• cron.php запускается от root, а файлы приложения принадлежат www-data — в итоге создаются файлы с неверными правами, и веб-сервер потом не может их читать/перезаписывать. Всегда указывайте -u www-data (или того пользователя, от кого работает PHP-FPM пул).
• Путь до PHP не тот. На сервере может стоять несколько версий PHP, и cron по умолчанию берёт системный php, который не совпадает с версией для сайта. Проверяйте явно: which php8.1 и используйте полный путь в crontab.
• cron.php падает по memory_limit, потому что CLI-конфигурация PHP (/etc/php/8.1/cli/php.ini) отдельная от FPM и может иметь другие лимиты. Их надо выставлять отдельно.

Проверить, что джобы реально выполняются, можно через админку SuiteCRM: Admin → Scheduler → Job Queue — там видно последний запуск и статус каждой задачи. Если время последнего запуска «зависло» несколько часов назад — cron не тикает вообще, если задачи есть, но статус «failed» — проблема в самом коде задачи или в памяти.

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

Проблемы с отправкой и получением почты

Почтовая интеграция — самая нестабильная часть SuiteCRM для новых внедрений, потому что она завязана сразу на PHP-расширение imap, внешний SMTP и права на системные вызовы.

Симптом: письма из CRM (уведомления, кампании) не доходят или зависают в очереди. Проверка по шагам:

1. Убедитесь, что SMTP настроен в Admin → Email Settings с реальными учётными данными, а не заглушкой из коробки.
2. Проверьте, что порт исходящего SMTP (обычно 587 или 465) не заблокирован фаерволом или хостером. Некоторые провайдеры блокируют исходящий 25-й порт по умолчанию — это нормально, но 587/465 должны быть открыты.
3. Посмотрите suitecrm.log на предмет ошибок аутентификации SMTP — часто это банально устаревший пароль приложения или отключённый 2FA-бypass для SMTP на стороне почтового провайдера.

grep -i "smtp\|mail" /var/www/suitecrm/suitecrm.log | tail -50

Если письма из CRM не приходят получателям вообще (а не просто зависают в очереди SuiteCRM), проблема часто на уровне почтового сервера, а не CRM — например, отсутствует SPF/DKIM для домена отправителя, и письма улетают в спам или отбрасываются. Если вы держите свой почтовый сервер на том же VPS, стоит свериться со статьёй про типовые проблемы Postfix на сервере — там разобраны похожие кейсы с недоставкой и очередями.

Для входящей почты (IMAP-инбоксы группового email-модуля) частая ошибка — расширение imap собрано без поддержки SSL, тогда подключение к Gmail/Yandex по 993 порту падает с Can not authenticate to IMAP server. Проверить наличие модуля:

php -i | grep -i imap

Если модуля нет вовсе — на Ubuntu/Debian ставится php8.1-imap, но он тянет системную библиотеку libc-client, которая на некоторых минимальных образах отсутствует и требует отдельной установки libc-client2007e.

HTTPS, редиректы и ошибки после переезда домена

SuiteCRM хранит абсолютный URL сайта прямо в базе данных (таблица config), и это источник классической проблемы: после смены домена, переезда на HTTPS или переноса на новый сервер интерфейс либо редиректит не туда, либо статика (CSS/JS) не грузится, хотя сама CRM «жива».

Проверить и поправить текущий сохранённый URL:

SELECT * FROM config WHERE category = 'info' AND name = 'server_url';
UPDATE config SET value = 'https://crm.example.com' WHERE category = 'info' AND name = 'server_url';

После правки обязательно очистите кэш SuiteCRM — иначе изменения не подхватятся:

rm -rf /var/www/suitecrm/cache/*

Если вы переходите на HTTPS через Let's Encrypt и видите mixed-content предупреждения (часть ресурсов грузится по http:// даже при рабочем сертификате) — почти всегда это тот же server_url в конфиге, оставшийся на http-варианте, плюс возможные жёстко прописанные http-ссылки в кастомных темах или письмах-шаблонах. Общий процесс настройки Let's Encrypt и типовые грабли с сертификатами на VPS разобраны в статье про частые ошибки Let's Encrypt на сервере — пригодится, если сертификат не выпускается или не обновляется автоматически.

Отдельно про Apache — если вы разворачиваете SuiteCRM на классической связке Apache + mod_php (а не FPM), проверьте .htaccess в корне SuiteCRM: он должен быть доступен модулю mod_rewrite, иначе часть URL (в первую очередь REST API и портал) вернёт 404 вместо ожидаемого ответа. Общие настройки и грабли этой связки — в статье про Apache с mod_php на сервере.

Ошибки при апдейте и повреждённый кэш

Обновление SuiteCRM через встроенный Module Loader или через Upgrade Wizard — второй по частоте источник аварий. Симптомы после неудачного апдейта: белый экран, «Fatal error: class not found», или интерфейс частично рендерится без стилей.

Первое, что стоит сделать при любой странности после апдейта — полностью очистить кэш и пересобрать его:

rm -rf /var/www/suitecrm/cache/*
php /var/www/suitecrm/repair.php 2>/dev/null || true

Второе — зайти в Admin → Repair, там есть набор инструментов:

• Quick Repair and Rebuild — пересобирает vardefs, кэш метаданных модулей. Решает 80% визуальных багов после апдейта.
• Rebuild Relationships — если сломались связи между модулями (например, после кастомизации через Studio).

Третье и самое важное — всегда снимайте бэкап базы и файлов перед апдейтом. SuiteCRM не имеет надёжного механизма отката, и если апдейт упал на середине (часто из-за нехватки памяти или таймаута на больших инсталляциях), единственный быстрый путь назад — восстановление из бэкапа, а не попытка «долечить» частично применённую миграцию.

mysqldump -u suitecrm_user -p suitecrm_db > /backup/suitecrm_db_$(date +%F).sql
tar -czf /backup/suitecrm_files_$(date +%F).tar.gz /var/www/suitecrm

Держите минимум 2-3 последние копии на отдельном диске или удалённом хранилище — восстановление CRM с клиентской базой из недельной давности бэкапа обычно куда болезненнее, чем лишние гигабайты на хранение.

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