Frappe Bench для администратора: команды, которые нужны каждый день

Frappe Bench — консольная утилита, через которую администратор ставит приложения, делает бэкапы, мигрирует и обновляет ERPNext. На каждый день нужно около десятка команд: backup, restore, migrate, build, clear-cache, doctor, restart. Ниже чек-лист с критерием готовности и отдельно про Docker, где часть команд не работает.

Что такое bench и где в нём лежат сайты, приложения и конфиги

Bench — командная строка для окружения Frappe. Команда bench init создаёт каталог с виртуальным окружением Python, скачивает фреймворк Frappe, ставит Node-модули и собирает ассеты. Приложения (frappe, erpnext и другие) и сайты живут внутри одного каталога, который по традиции называют frappe-bench. Один bench может содержать несколько сайтов, и у каждого своя база данных. Если вы ставите ERPNext на сервер впервые и не хотите разбираться, наш вариант описан на странице ERPNext под ключ, а ниже я разбираю то, что нужно знать администратору, который эксплуатирует систему сам.

Что лежит в каталоге bench. Каталог env с окружением Python. apps с исходным кодом приложений, каждое со своим git-репозиторием. sites с сайтами: у каждого сайта своя папка, внутри site_config.json с параметрами и подкаталоги public и private с файлами; рядом common_site_config.json с общими настройками и apps.txt со списком приложений. config с конфигурациями, logs с журналами и Procfile для режима разработки. Эту раскладку стоит выучить, потому что почти любая авария лечится чтением журналов и конфигов именно здесь.

Важное правило: bench разворачивают под отдельным непривилегированным пользователем с правом sudo, а не под root. Часть команд сама просит повышение прав (например, перезагрузка веб-сервера), и когда всё запущено от root, права на файлы потом перемешиваются, а приложение отказывается читать собственные каталоги. Эту ошибку я встречаю чаще любой другой на чужих серверах.

Команда bench start поднимает веб-сервер на порту 8000, сервер сокетов, Redis и фоновые воркеры, но она предназначена для разработки: так запущенный процесс умирает вместе с терминалом. Для рабочего сервера используется bench setup production для нужного пользователя, которая генерирует конфигурации nginx и supervisor. Если вы запускаете ERPNext в Docker, то ничего из этого не нужно: контейнеры устроены иначе, о них раздел 6.

Команды первого дня: init, start и вход под администратором

Минимальный набор для чистой установки выглядит так (имена и версии подставьте свои):

bench init --frappe-branch version-15 frappe-bench
cd frappe-bench
bench new-site site1.local
bench get-app erpnext --branch version-15
bench --site site1.local install-app erpnext
bench start

Ветка в init и в get-app должна совпадать: версию ERPNext и версию Frappe смешивать нельзя. Если вы ставите ветку develop «посмотреть», делайте это на отдельной машине, а не на сервере с данными.

Для входа под Administrator из консоли есть bench --site имя browse --user Administrator: она открывает сайт в браузере с автоматической авторизацией. Используйте её на машине администратора и только там, где это допустимо политикой безопасности компании, потому что команда по сути выдаёт сеанс без пароля. На боевом сервере я пользуюсь ею редко: мне чаще нужен пароль пользователя, а не вход от его имени, и я не люблю, когда в журналах не видно, кто пришёл.

Параметры, которые дают наибольший эффект при установке. --python в bench init выбирает интерпретатор: версия Python должна подходить под версию Frappe, иначе сборка упадёт на зависимостях. --skip-assets пропускает сборку ассетов, что полезно при отладке. --install-app ставит приложение сразу после инициализации. Для каждой версии ERPNext в документации указаны свои требования к Python и Node, и их я сверяю до установки, а не после первой ошибки.

Критерий готовности первого дня: сайт открывается, под Administrator вы входите, мастер первоначальной настройки пройден, а в bench --site имя doctor не видно ошибок планировщика и воркеров. Если письма и уведомления не уходят, начинайте поиск с bench doctor, а не с настроек почты.

Что выполняют каждый день: backup, restore, migrate и build

Четыре команды составляют ежедневный минимум. Первая — резервная копия: bench --site имя backup. Без флагов она делает дамп базы. Флаг --with-files добавляет публичные и приватные файлы, --compress сжимает архивы файлов, --backup-path задаёт каталог для результата. По умолчанию копии кладутся в каталог sites/имя/private/backups. Для всех сайтов сразу есть bench backup-all-sites. При инициализации bench по умолчанию добавляет в cron периодическое создание копий (опция --no-backups это отключает), а команда bench setup backups добавляет такое задание отдельно. Сколько копий хранится и как они чистятся, проверьте на своей версии.

Вторая — восстановление: bench --site имя restore путь-к-дампу.sql.gz. К ней добавляют --with-public-files и --with-private-files с путями к архивам файлов. Флаг --force отключает проверки и предупреждения о понижении версии, и документация прямо называет такое действие нерекомендуемым. Если команда просит пароль root базы, добавьте --db-root-password. Правило, которое я держу как закон: сначала восстанавливаю на отдельный тестовый сайт и проверяю, а на боевой возвращаю только после этого.

Третья — bench --site имя migrate: применяет патчи, синхронизирует схему базы и пересобирает файлы и переводы. Её запускают после смены версии или приложения и при добавлении полей в DocType из кода. Флаг --skip-failing пропускает патчи, которые падают, но это обезболивающее, а не лекарство: пропущенный патч оставляет данные в неочевидном состоянии, и я использую флаг только на тестовой копии, чтобы понять масштаб проблемы.

Четвёртая — bench build: собирает JS и CSS. Нужна, когда интерфейс загружается без стилей или в консоли браузера 404 на файлы ассетов, что бывает после обновления. У команды есть параметры --app и --apps для сборки только нужных приложений и --force, чтобы собрать вместо скачивания готовых. Рядом живёт bench --site имя clear-cache для очистки кэша и bench restart, которая перезапускает процессы под supervisor или systemd. Для проверки здоровья фоновой части есть bench doctor: она выводит диагностическую информацию о воркерах.

Сводная таблица «команда, когда, риск»: | Команда | Когда | Риск | |---|---|---| | bench --site имя backup --with-files | ночью, по расписанию | на большой базе нагружает процессор и диск | | bench --site имя restore путь | при восстановлении | --force отключает проверки | | bench --site имя migrate | после смены версии или приложения | сначала на тестовой копии | | bench build | когда не грузятся CSS и JS | кратковременная нагрузка | | bench --site имя clear-cache | после правок, странное поведение интерфейса | сессии и кэш сбрасываются | | bench doctor | письма и уведомления не уходят | риска нет, только чтение | Синтаксис сверяйте с документацией своей версии: параметры меняются между релизами.

Ветки и обновление: switch-to-branch, update и чем опасен --reset

Есть два способа сменить версию. Обновление внутри ветки делает bench update: без флагов она делает резервную копию, подтягивает изменения, ставит зависимости, собирает ассеты, выполняет патчи и перезапускает bench. Можно запускать только отдельные шаги: --pull, --patch, --build, --requirements. Флаг --no-backup отключает копию перед обновлением, и справка к нему честно оговаривает, что на production так делать не рекомендуется.

Переход на другую версию делает bench switch-to-branch:

bench switch-to-branch version-16 frappe erpnext --upgrade
bench restart

По исходному коду bench при смене мажорной версии с флагом --upgrade команда сама ставит зависимости, делает копию всех сайтов, выполняет патчи (аналог migrate) и собирает ассеты; без --upgrade она откажется переключать мажорную версию, а при простом переключении ветки попросит выполнить bench update --patch.Перед ним читаю замечания к релизу и обязательно делаю копию. Переход между мажорными версиями проверяю на копии базы на отдельном стенде: что-то обязательно окажется несовместимым, например кастомное приложение или собственные скрипты.

Опаснее всего флаг --reset у bench update: по справке он жёстко сбрасывает ветки git к новому состоянию, перезаписывая любые изменения и отменяя перебазирование при получении обновлений. Если кто-то правил код ядра прямо на сервере, эти правки исчезнут без следа. Правило простое: код ядра не правим вообще. Свои доработки оформляем отдельным приложением или через стандартные механизмы настройки, а версии приложений фиксируем в git. Тогда --reset не страшен.

Две типичные ошибки при обновлении, которые я запомнил. Первая: команда bench migrate без указания сайта падает с требованием указать сайт, если в common_site_config.json не задан default_site; поэтому в скриптах я всегда пишу bench --site all migrate или имя конкретного сайта. Вторая: конфликт версий pip, когда одно из приложений тянет несовместимую зависимость; приложение обновляют до ветки той же версии или временно убирают из bench. Смену версии Python делает bench migrate-env: в актуальном коде bench она сама архивирует старое окружение в каталог archived/envs, но на старых версиях bench эту операцию тоже проверяйте на копии.

Несколько сайтов на одном сервере: DNS-мультитенантность и Let's Encrypt

Один bench умеет обслуживать несколько сайтов. Есть два режима: на разных портах и по DNS, когда сайт выбирается по имени домена. На практике нужен второй. Порядок действий важен, потому что команда выпуска сертификата проверяет, что режим DNS-мультитенантности включён, и без этого не работает. Вот пять шагов:

bench config dns_multitenant on
bench setup add-domain домен --site имя-сайта
bench setup nginx
sudo service nginx reload
sudo -H bench setup lets-encrypt имя-сайта --custom-domain домен

К каждому шагу несколько пояснений. Включение режима записывает параметр в общие настройки. add-domain привязывает домен к сайту и при желании принимает пути к сертификату и ключу. setup nginx пересоздаёт конфигурацию, а перезагрузка nginx её применяет. Последний шаг запрашивает сертификат Let's Encrypt через certbot и требует, чтобы домен уже указывал на сервер, а порты 80 и 443 были открыты. Новый сайт создаётся командой bench new-site, и каждый сайт привязывается к своей базе через параметр db_name в site_config.json.

Что я проверяю после настройки. Открываю каждый домен и убеждаюсь, что он показывает именно свой сайт, а не соседний. Смотрю срок действия сертификата и наличие автоматического продления: для этого у bench есть bench renew-lets-encrypt, которая настраивает cron и обновляет сертификат. Общие приёмы автоматизации сертификатов я описывал в материалах про Let's Encrypt для nginx и IIS и про автоматизацию SSL-сертификатов.

Ограничение, о котором стоит помнить: все сайты одного bench делят одно окружение и один набор приложений, а обновление приложения затрагивает все сайты сразу. Если одному клиенту нужна старая версия, а другому новая, это два разных bench. Я не складываю в один bench сайты с разным ритмом обновлений: проще завести второй каталог, чем объяснять, почему обновление остановило чужой сайт.

Bench в Docker: что работает внутри контейнера, а что нет

В Docker bench присутствует внутри контейнеров, но часть привычных действий там не работает. По документации frappe_docker, контейнеры неизменяемы: после сборки вы меняете только переменные окружения, подключённые тома и сам образ, пересобирая его. Постоянно хранятся данные сайтов (каталог sites) и база. Установка приложений в работающий контейнер не поддерживается: bench get-app и bench build как раз такие действия. Приложения и ассеты входят в образ, а изменения внутри контейнера пропадают при его пересоздании.

Правильный путь для нового приложения: добавить его в конфигурацию сборки образа, пересобрать образ и перевыкатить стек. В актуальной документации перечень приложений описывается файлом apps.json, и он передаётся в сборку как секрет BuildKit, чтобы токены частных репозиториев не оставались в слоях образа; --build-arg для этого файла не используется. Более старые инструкции передавали его в переменной APPS_JSON_BASE64, поэтому, если вы натыкаетесь на неё в чужой статье, сверьте с документацией своей версии. Сборка требует Docker Engine 23.0 и выше с BuildKit.

Рабочие команды в Docker выполняются через сервис backend: docker compose exec backend bench --site имя migrate для миграции, docker compose exec backend bench --site all backup --with-files для копий. Документация предлагает запись в cron хоста, например каждые шесть часов, и отдельное задание резервного копирования с отправкой снимков во внешнее хранилище; скрипт push_backup.py отправляет последнюю копию в S3-совместимое хранилище, а восстановление из такой копии делается только вручную. Если у вас нестандартное имя проекта compose, добавьте параметр -p.

Если вы после экспериментов через docker exec что-то поменяли внутри контейнера, делайте полный перезапуск и считайте изменения потерянными. Подробнее об основах контейнеров есть материал для начинающих про Docker на Linux, а о промышленной эксплуатации связки Compose в статье про Docker Compose в production.

Шпаргалка «Умного Подъезда» на 18 рабочих мест: команды на стене админа

Условный пример: компания по автоматизации зданий «Умный Подъезд», 18 рабочих мест: проектировщики, монтажники, сервисная служба и снабжение. ERPNext у них стоит на одном сервере, админ по совместительству один человек. Цифры и состав придуманы для иллюстрации, это не реальный клиент. Задача: чтобы любой, кто подменяет администратора, мог выполнить ежедневный минимум без звонка коллеге.

Что у них висит в виде карточки. В колонке «каждый день»: проверка, что ночная копия создана (смотрим файл с датой в каталоге копий), и bench doctor, если жалуются на письма. В колонке «раз в неделю»: проверка свободного места на диске и срока сертификата. В колонке «при обновлении»: копия, затем switch-to-branch или update на тестовом сайте, migrate, build, restart, проверка входа и одного документа. В колонке «аварии»: 404 на CSS и JS означает bench build; ошибка миграции из-за зависимостей означает смотреть версии pip; просьба указать сайт при migrate означает добавить --site all; пропавшие доработки после --reset означает вернуть из копии и оформить отдельным приложением.

Каждая команда имеет критерий готовности. Копия: файл создан сегодня, его размер сопоставим со вчерашним. Восстановление: на тестовом сайте открывается последний документ. Миграция: нет ошибок, под Administrator открывается главная. Сборка: интерфейс грузится со стилями. Перезапуск: фоновые задачи идут, bench doctor не показывает отставания. Это всё, что нужно запомнить, чтобы не бояться bench.

Чего в шпаргалке нет, и это осознанно. Нет команд правки данных напрямую в базе: для этого есть интерфейс и Server Script. Нет --force и --reset: их применяют только по решению ответственного и только после копии. Нет bench get-app на боевом сервере без предварительной проверки на тестовом. Если вам нужна такая шпаргалка под вашу версию и ваш способ развёртывания, мы её соберём вместе с проверкой каждой команды на вашем стенде.

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