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

MAATRIX

ERPNext подкупает тем, что закрывает бухгалтерию, склад, CRM и HR одним open-source продуктом без лицензионных платежей. Но за простотой внедрения прячется довольно капризный стек: Frappe framework, MariaDB, Redis, supervisor и nginx должны работать слаженно, и любое звено может подвести. Если вы уже развернули ERPNext на своём сервере и получаете странные ошибки при установке, бэкапе или в работе — ниже разобраны самые частые случаи с конкретными командами для диагностики и исправления.

Bench setup завершается с ошибкой на этапе установки

Самая частая точка отказа — установка через bench. Обычно всё падает на bench new-site или bench install-app erpnext, и причины почти всегда одни и те же.

Если видите MySQL root password not found или ошибку доступа к MariaDB:

sudo mysql_secure_installation
# затем проверьте, что root может логиниться с паролем, а не через unix_socket
sudo mysql -u root -p -e "SELECT plugin FROM mysql.user WHERE User='root';"

Если плагин auth_socket вместо mysql_native_password, поменяйте:

ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'ваш_пароль';
FLUSH PRIVILEGES;

Ещё частая причина — несовпадение версии Node.js с тем, что ожидает bench. ERPNext v15 требует Node 18, более старые версии фреймворка — Node 16. Проверяйте:

node -v
bench --version

Если версии разъехались, ставьте нужный Node через nvm, а не через системный пакетный менеджер — так проще держать несколько версий и переключаться при апгрейде.

И третья типичная причина сбоя установки — нехватка памяти. bench build и сборка фронтенда на Node легко съедают 2-3 ГБ RAM, и на сервере с 2 ГБ процесс просто убивается OOM killer'ом. Если у вас минимальная конфигурация, сначала настройте swap-файл — это решает добрую половину загадочных зависаний на этапе сборки assets.

MariaDB: ошибки подключения и производительности

ERPNext хранит все данные в MariaDB, и это самое требовательное к настройке звено стека. Дефолтная конфигурация MariaDB на VPS с 2-4 ГБ памяти почти всегда нуждается в правке.

Типичная ошибка в логах bench: pymysql.err.OperationalError: (2003, "Can't connect to MySQL server"). Причины по порядку проверки:

sudo systemctl status mariadb
sudo mysqladmin -u root -p ping
sudo ss -tlnp | grep 3306

Если сервис живой, но подключения рвутся под нагрузкой — смотрите на max_connections и буферы. Для ERPNext в /etc/mysql/mariadb.conf.d/50-server.cnf (или в /etc/mysql/conf.d/mariadb.cnf в зависимости от дистрибутива) рекомендуется задать параметры из официальной документации Frappe:

[mysqld]
innodb-buffer-pool-size = 512M
innodb-log-file-size = 256M
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
max_connections = 150

innodb-buffer-pool-size подбирайте под объём оперативной памяти сервера — ориентировочно 40-60% от общего RAM, если сервер выделен под ERPNext целиком. Точную цифру для вашей нагрузки стоит подбирать по факту, глядя на SHOW ENGINE INNODB STATUS.

Ошибка Row size too large при импорте данных или создании DocType с большим числом полей лечится включением innodb_file_per_table (в современных версиях MariaDB он уже включён по умолчанию) и ROW_FORMAT=DYNAMIC для таблиц.

Отдельная категория проблем — общие подходы к диагностике MariaDB на сервере разобраны в статье MariaDB на сервере: частые ошибки и решения, если хотите глубже разобраться в самой СУБД отдельно от ERPNext.

Redis не отвечает, очереди зависают

ERPNext использует три Redis-инстанса по умолчанию: для кеша, очередей (RQ) и сокетов реального времени. Если фоновые задачи (отправка email, генерация отчётов, автоматизации) перестали выполняться, но веб-интерфейс работает — почти всегда дело в Redis или в воркерах.

Проверка живости всех инстансов:

redis-cli -p 13000 ping   # cache
redis-cli -p 11000 ping   # queue
redis-cli -p 13001 ping   # socketio

Если порты не совпадают — посмотрите актуальные значения в sites/common_site_config.json, они могут отличаться от дефолтных на разных установках.

Если Redis отвечает, но задачи всё равно не обрабатываются — проверьте supervisor-воркеры:

sudo supervisorctl status

Ожидаете увидеть процессы вида frappe-bench-workers:frappe-bench-worker-default, -short, -long в состоянии RUNNING. Если они в FATAL или постоянно перезапускаются — смотрите логи в logs/worker.error.log внутри директории bench. Частая причина — воркер упал по памяти при обработке тяжёлого отчёта, тогда помогает либо оптимизация самого отчёта, либо увеличение памяти сервера.

Общие паттерны диагностики Redis, актуальные и для ERPNext, есть в статье Redis на сервере: частые ошибки и решения.

Nginx отдаёт 502 Bad Gateway или не видит статику

После настройки production-режима (bench setup production) фронт отдаёт nginx, а он проксирует запросы к gunicorn/socketio через supervisor. Ошибка 502 здесь означает, что nginx поднялся, а бэкенд за ним — нет.

Порядок диагностики:

sudo systemctl status nginx
sudo supervisorctl status
tail -50 logs/gunicorn.error.log
sudo nginx -t

Часто причина в том, что конфиг nginx не перегенерировался после смены сайта или порта:

bench setup nginx
sudo systemctl reload nginx

Если статика (CSS/JS/иконки) не подгружается после деплоя новой версии — почти всегда забыли пересобрать assets:

bench build --app erpnext
bench clear-cache
sudo supervisorctl restart all

Общий разбор причин 502 в nginx, применимый не только к ERPNext, есть в статье Ошибка 502 Bad Gateway в nginx — полезно, если проблема не специфична для Frappe.

Медленная работа интерфейса и таймауты при импорте данных

ERPNext заметно тормозит при трёх типичных сценариях: массовый импорт данных через Data Import Tool, генерация тяжёлых отчётов (например, консолидированный Stock Ledger на большой номенклатуре) и работа с большим количеством одновременных пользователей.

Для импорта — увеличьте таймаут gunicorn workers в config/gunicorn.conf.py (или через переменные, в зависимости от версии bench):

timeout = 300
workers = 4

Число workers по формуле Frappe — 2 * CPU cores + 1, но на слабых VPS лучше начинать с 2-3 и смотреть на потребление памяти — каждый gunicorn worker держит собственную копию приложения в памяти.

Для тяжёлых отчётов помогает включение длинных очередей вместо синхронного выполнения — часть отчётов и в целом фоновые задачи в ERPNext можно явно направить в очередь long через параметр queue='long' в коде автоматизации, если вы пишете кастомные скрипты.

Если тормозит именно база — почти всегда это отсутствующие индексы на кастомных полях или разросшийся tabError Log. Периодическая очистка старых логов ошибок и версий документов через bench --site вашсайт trim-database (доступно с определённых версий) или ручной DELETE FROM \tabVersion\ WHERE creation < DATE_SUB(NOW(), INTERVAL 90 DAY) заметно облегчает базу — но перед такими операциями обязательно снимите бэкап.

Бэкапы: настройка и частые ошибки восстановления

Встроенный bench backup создаёт дамп базы и архив с файлами, но по умолчанию он не автоматизирован и не выгружается за пределы сервера — а это единственная точка отказа, если диск умрёт целиком.

Базовый cron для регулярного бэкапа с загрузкой в S3-совместимое хранилище (в sites/common_site_config.json должны быть заданы ключи s3_bucket, aws_access_key_id, aws_secret_access_key):

# crontab -e
0 2 * * * cd /home/frappe/frappe-bench && bench --site вашсайт backup --with-files --upload

Частая ошибка при восстановлении — bench --site вашсайт restore падает с несовпадением версии MariaDB между дампом и текущим сервером, либо с ошибкой кодировки, если дамп снят на сервере с другим character-set-server. Перед восстановлением на новый сервер сверьте версии MariaDB и убедитесь, что в конфиге стоит utf8mb4 — иначе часть данных с эмодзи или кириллицей в комментариях побьётся при импорте.

Ещё одна практическая деталь — файлы вложений (private/files, public/files) бэкапятся отдельным архивом от базы. Если восстанавливаете сайт вручную без --with-files, документы будут ссылаться на несуществующие файлы, и это не сразу заметно, пока пользователь не откроет старое вложение. Общие принципы настройки регулярных бэкапов на сервере, применимые и здесь, разобраны в статье Бэкап MySQL на сервере: частые ошибки и решения.

Если держите ERPNext в Docker-окружении, а не через классический bench-manager, часть проблем с volumes и персистентностью данных пересекается с общими граблями Docker Compose в продакшене — см. Docker Compose для продакшена на сервере: частые ошибки и решения.

Обновление ERPNext ломает сайт

bench update — операция, которую стоит бояться на проде без предварительной подготовки. Типичные сбои после обновления:

• Миграция базы падает на середине — обычно из-за кастомных полей или отчётов, конфликтующих со схемой новой версии. Смотрите logs/bench.log за точным traceback и не запускайте bench migrate повторно вслепую — сначала восстановите бэкап, снятый до обновления.
• После обновления сайт грузится, но часть модулей выдаёт permission error — обычно нужно перегенерировать роли и права: bench --site вашсайт set-config developer_mode 0 и bench --site вашсайт clear-cache.
• Версии Python-зависимостей конфликтуют — Frappe v15 требует Python 3.10+, и на старых серверах, где стоит система с Python 3.8, обновление до новой мажорной версии ERPNext вообще не пройдёт без апгрейда ОС.

Практическое правило: перед любым bench update на проде — снимок диска или как минимум полный bench backup --with-files, и тестовый прогон обновления на копии сервера. Разворачивать копию для теста на отдельном VPS дешевле, чем чинить прод в 2 часа ночи.

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