Обновление ERPNext с v15 на v16: bench migrate, риски кастомизаций и откат

Обновление ERPNext с v15 на v16 делают после полной копии и пробного прогона на staging: переключают ветку (bench switch-to-branch), запускают migrate и build, проверяют сценарии. Откатиться можно только восстановлением из копии. Главное новое требование v16: Python 3.14+ и Node 24+.

Нужно ли переходить на v16 сейчас или можно подождать

Короткий ответ: срочности нет, но и откладывать «навсегда» нельзя. Мажорная версия ERPNext v16 вышла 12 января 2026 года (релиз v16.0.0 в репозиториях frappe и erpnext); на момент проверки 01.10.2026 актуальный тег v16.37.0, а у ветки v15 тег 15.121.6, то есть обе линии активно получают исправления. По плану поддержки из вики ERPNext, версия 15 поддерживается до конца 2027 года, версия 16 до конца 2029 (оба срока плановые, а не гарантированные). Если у вас стабильная v15 без острой нужды в новых функциях, переход можно запланировать на спокойный квартал.

Я бы переходил раньше в трёх случаях. Первый: вы только внедряетесь. Ставить сегодня v15 значит через год-два делать миграцию, которой можно избежать, поэтому новые установки по нашей схеме внедрения ERPNext под ключ мы планируем на актуальной линии. Второй: вам нужна функция v16, например резервирование материалов в Production Plan и Work Order, представления Master Production Schedule и MRP или резервирование сырья в Subcontracting Order (всё это перечислено в заметках к релизу v16.0.0). Третий: вы и так собираетесь обновлять сервер, а у вас на нём системный Python старше 3.14, который всё равно придётся менять.

И случаи, когда лучше подождать. Много доработок собственного приложения без тестов. Сторонние приложения, которые не заявили поддержку v16. Конец квартала или сезон закрытия периода. Если вы живёте на v15 и она вас устраивает, это нормальная позиция: бизнес-решение должно строиться на рисках, а не на номере версии. Про стоимость простоя при обновлениях мы писали в материале про стоимость простоя 1С и сайта, расчёт там применим и к ERP.

Что подготовить до первой команды: копия, staging и список доработок

Первое: полная копия, то есть база и файлы. bench --site <сайт> backup --with-files создаёт архив базы и файлы сайта (публичные и приватные). Копия считается копией только после пробного восстановления: об этом у нас отдельный материал про тест восстановления бэкапа. Копию храните вне сервера, на котором идёт обновление, иначе при поломке диска вы потеряете и систему, и страховку.

Второе: staging. Это отдельная копия продакшена, на которой вы сначала прогоняете то же обновление. Разворачиваем её из свежей резервной копии: bench restore с путями к файлам публичных и приватных данных (ключи --with-public-files и --with-private-files). На staging вы увидите всё то же, что увидите на боевой системе: падающие патчи, несовместимые приложения, потерянные доработки. Общий подход к тестовой среде описан в статье про staging для обновлений сайта и CRM, для ERPNext он тот же.

Третье: инвентаризация. Составьте таблицу: какие приложения стоят (bench list-apps), какие из них ваши, какие сторонние; какие DocType вы меняли через Customize Form; какие правки лежат в кастомном приложении и в fixtures; какие интеграции дёргают API. Последняя графа важна для v16: ряд служебных методов теперь принимает только POST, а один из методов выставления счетов по табелю потребовал отдельного вызова. Тот, кто строил интеграции (например, с 1С), должен знать о переходе заранее.

Четвёртое: окно и ответственные. Мы назначаем людей и даты, как показано на схеме после следующего раздела: за неделю инвентаризация, за три дня staging и пробный прогон, за сутки заморозка изменений и последняя копия, в день обновления сам переход и проверка, на следующий день наблюдение за очередями. Здесь подробности можно переставлять, но не пропускать этап staging.

Как выглядит обновление: ветка, migrate и build по шагам

Сначала требования. В ветке version-16 у frappe в pyproject указано requires-python = ">=3.14,<3.15", а в package.json node >=24. Для v15 было Python от 3.10 и Node от 18. В вики Frappe по миграции на v16 прямо написано: нужны Python 3.14+ и NodeJS 24+. В нашей базе знаний ещё стоит старый ориентир Python 3.11+ и Node 18+, он для v16 неверен. Если вы живёте на bare-metal установке с bench, сначала подготовьте окружение (новый Python и Node, пересоздание виртуального окружения), и только потом переключайте ветку.

Для установки через bench основная последовательность выглядит так (команды по справке bench и документации; перед боевым запуском прогоните их на staging):

# 1. свежая полная копия
bench --site erp.example.com backup --with-files

# 2. переключение веток frappe и erpnext на v16
bench switch-to-branch version-16 frappe erpnext --upgrade

# 3. миграция базы и сборка ассетов
bench --site erp.example.com migrate
bench build

# 4. перезапуск процессов (supervisor или systemd)
bench restart

Если обновление упало на середине, у bench есть команда bench retry-upgrade --version <номер> для повторного прохода после исправления причины. Для обычных обновлений внутри версии применяют bench update; ключ --reset отбрасывает локальные изменения в коде приложений и поэтому опасен, если кто-то правил ядро.

Для Docker-установки ветку не переключают: собирают или скачивают образ нужной версии. Если вы используете официальные образы, меняете ERPNEXT_VERSION в env-файле на конкретный тег v16, пересоздаёте итоговый compose-файл и запускаете. Если у вас собственный образ (с кастомными приложениями), пересобираете его с FRAPPE_BRANCH=version-16 и ветками version-16 для всех приложений в apps.json. После запуска миграцию выполняют командой docker compose exec backend bench --site <сайт> migrate; в репозитории frappe_docker есть и оверрайд compose.migrator.yaml, который выполняет bench --site all migrate отдельным сервисом. Образы подробнее разобраны в нашем материале про установку ERPNext в Docker.

Проверка результата простая: после migrate команда bench version показывает v16 у frappe и erpnext (в v16 формат вывода по умолчанию сменился с legacy на plain и показывает ветку и коммит; старый вид даёт ключ -f legacy), вход под администратором работает, очереди обрабатывают задачи, а тестовое письмо уходит. Версии frappe и erpnext в одном окружении обязаны совпадать по мажорной ветке, иначе система не соберётся.

Что ломается чаще всего: зависимости, патчи и правки ядра

Из типичного: первое, конфликты зависимостей Python. Frappe v16 требует redis~=7.1.0, v15 требовал redis~=4.5.5. Сторонние приложения, которые закрепили старую версию библиотеки, не уживутся с новой, и pip выдаст конфликт. Лечение: обновить приложение до версии под v16 или убрать его до миграции. Второе: сообщения сообщества о падении на отсутствующей папке archived/envs (FileNotFoundError); лечится созданием каталога. Сверьте на своей установке, встретится ли это вам.

Третье: падение отдельного патча миграции. Причины разные: старые некорректные данные (скажем, дата окончания раньше даты начала) или ошибка в релизе. Сначала читайте лог. У bench migrate есть флаг --skip-failing, пропускающий упавшие патчи; он помогает завершить миграцию, но каждый пропуск нужно потом разобрать вручную, иначе вы получите систему с недоделанной схемой. Не включайте этот флаг «по умолчанию».

Четвёртое: правки ядра. Если кто-то правил файлы frappe или erpnext напрямую, обновление их перезапишет. Доработки должны жить в кастомном приложении, а настройки форм экспортироваться в fixtures; так их можно перенести на v16. Пятое: права. Если вы создавали Custom DocPerm, стандартные права для этого DocType перестают получать обновления, и после миграции матрицу ролей нужно перепроверить. | Симптом | Причина | Действие | |---|---|---| | Конфликт pip при обновлении | Старое приложение закрепило redis 4.5 | Обновить приложение или убрать до миграции | | FileNotFoundError при migrate-env | Нет каталога archived/envs | Создать каталог, повторить | | Падает патч миграции | Старые данные или ошибка релиза | Прочитать лог, исправить данные, при необходимости --skip-failing с разбором | | Доработки исчезли | Правки ядра или неэкспортированные настройки | Вернуть из копии, оформить в кастомное приложение и fixtures |

И несколько изменений v16, которые бьют по привычкам и интеграциям. Адрес интерфейса сменился с /app на /desk. Стандартные рабочие пространства (Workspace) вроде «Покупки» и «Продажи» при миграции перезаписываются, и ваши правки нужно заранее скопировать. Списки по умолчанию сортируются по дате создания, а не изменения. Методы logout, web_logout, upload_file и frappe.www.login.send_login_link теперь принимают только POST. Из ядра убран Transaction Log. В ERPNext налоговая раскладка по позициям (Item Wise Tax Detail) переехала из JSON-поля в дочернюю таблицу, а в BOM таблица Scrap заменена на Secondary Items. Если ваша доработка трогала эти места, её надо перепроверить.

Откат: почему назад нельзя и что делать вместо этого

Откат версии базы в ERPNext не предусмотрен. Миграция выполняет патчи, которые необратимо меняют схему и данные, и в документации Frappe я не нашёл штатного способа вернуть базу на предыдущую мажорную версию. Это не недостаток конкретного релиза, так устроены практически все системы с миграциями. Поэтому «откат» это не команда, а запасной план: восстановление из копии, сделанной до обновления.

План такой. До обновления полная копия базы и файлов, проверенная восстановлением. Обновление на продакшене. Проверка сценариев. Если проверка не прошла и исправить быстро нельзя, останавливаем пользователей, возвращаем окружение на v15 (ветка кода и образ) и восстанавливаем копию командой bench restore на этой версии; затем идём разбирать причину на staging. Потеряются данные, введённые после копии, поэтому на время окна вводить документы нельзя, а ответственный за решение должен быть назначен заранее.

Важное ограничение этого плана: он работает, только если откат укладывается в окно. Если на третий день работы в v16 пользователи уже внесли сотни документов, возврат на копию их стирает. Поэтому окно проверки я делаю коротким (один-два рабочих дня с усиленным наблюдением), а решение «остаёмся на v16 и исправляем вперёд» принимаю до того, как накопились новые данные. Это называется roll forward, и оно возможно только при исправимой причине.

Отдельный совет про Docker. Образ предыдущей версии нужно сохранить: в реестре или локально, с тегом. Если образ хранится как latest или удалён, возврат превращается в археологию.

Что поменяется для пользователей и какие сценарии проверить после апдейта

Пользователи заметят интерфейс. В v16 у системы появились постоянная боковая панель (Workspace Sidebar) и экран рабочего стола с иконками, а адрес сменился на /desk: закладки в браузерах нужно обновить. Списки сортируются по дате создания, и пользователи, привыкшие видеть наверху «последнее изменённое», решат, что что-то пропало. Предупредите их до обновления одним коротким письмом и приложите скриншот новой панели.

Сценарии для проверки я формулирую от роли. Прораб: создаёт заявку на материалы с телефона (PWA), видит перебор. Снабженец: заказывает по согласованной заявке, получает счёт. Руководитель: согласует, смотрит отчёт по объекту. Бухгалтер: выгрузка в 1С, статусы оплат (если интеграция идёт через REST, проверьте методы, которые теперь только POST). Администратор: резервная копия, очереди, письма. Проверку проходим по списку, и каждый пункт получает отметку «норма» или «ошибка с описанием».

Отдельный блок: доработки. Если вы настраивали Budget, помните, что в v16 структура этого документа изменилась (один бюджет на один счёт, ревизии, периодичность распределения), поэтому лимиты по объектам проверьте вручную. Производственные спецификации в части учёта побочной продукции (Scrap заменён на Secondary Items) проверьте тоже, если вы их используете. И проверьте печатные формы УПД и КС-2: их обычно делают доработкой, и они чаще всего ломаются именно при смене версии.

Как «Грунт и Сваи» на 12 рабочих мест планировали окно обновления

Условный пример, цифры вымышленные. Строительная фирма «Грунт и Сваи», 12 рабочих мест: два прораба, снабженец, главный инженер, бухгалтерия и бригады. ERPNext v15 стоит на одном сервере в Docker, собственное приложение с печатными формами, интеграция выгрузки счетов в 1С по REST. Продавать и закупать нужно круглый год, но с пятницы вечера по воскресенье работает только дежурный. Окно выбрали с пятницы 19:00 до воскресенья 18:00.

План по неделям: за 7 дней инвентаризация приложений и доработок, за 3 дня staging из свежей копии и пробный переход, за сутки заморозка изменений и последняя копия, в пятницу вечером переход, в субботу проверка сценариев, в воскресенье запасное время и наблюдение. На staging проверка нашла три проблемы: сторонний модуль отчётности закрепил старую версию redis и не собирался; печатная форма УПД использовала поле, которое в v16 переименовано; интеграционный скрипт с 1С вызывал загрузку файла запросом GET, а теперь это только POST. Все три исправили до боевого перехода.

Итог условного окна. Переход выполнили за 2 часа 40 минут, из них большую часть заняла миграция, проверка заняла ещё два часа. Один патч упал на старой записи с некорректными датами; запись исправили, миграцию повторили без флага пропуска. Пользователям заранее разослали письмо про новый интерфейс и адрес /desk. Откат не понадобился, но образ v15 и последняя копия лежали наготове до вторника.

Это иллюстрация подхода, а не обещание сроков для вашей системы: время миграции зависит от объёма базы и числа доработок. Как выглядит staging-стенд и сам переход, покажем на демостенде erp-demo.itfresh.ru по запросу.

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