Публикация и обновления

English version · Оглавление

Как плагин попадает в панель

Способ	Как
Файл	rospanel plugin pack . → zip → Настройки → Плагины → Добавить → выбрать файл
Ссылка	там же, вставить https-ссылку на zip (например, на релиз GitHub)

В обоих случаях оператор видит экран согласия: права, хосты, что плагин делает, экспериментальные точки. Устанавливает он с паролем и только если у него есть все права, которые просит плагин; плагин ставится выключенным. Включает его оператор, когда заполнит настройки.

Версии

version — X.Y.Z. Новое число нужно при любом изменении пакета: панель различает версии по нему.

• panel: ">=X.Y.Z" — самая старая версия панели, на которой плагин работает. Если вы используете точку или поле, появившееся позже, поднимите её: старая панель откажется ставить плагин и объяснит почему, а не сломается во время работы.
• api: 1 — контракт плагинов. Внутри одной версии API в нём только добавляют: новые поля, вызовы, точки. Существующее не меняют и не переименовывают. Исключение — точки из experimental.

Обновление

Новая версия ставится кнопкой Обновить на карточке плагина (zip или ссылка). Что происходит:

1. Панель проверяет, что это тот же id, и показывает экран согласия. Новые права, хосты и точки расширения отмечены отдельно, их нужно одобрить заново — админу, у которого есть все права, которые просит плагин.
2. Останавливает плагин и снимает копию его базы (если базы ещё нет, копия пустая). Если копия не удалась, продолжает работать старая версия.
3. Применяет новые миграции и запускает новый код, вызывая onEnable.
4. Если что-то из этого не удалось, возвращает прежнюю версию и базу сама.

Настройки сохраняются. Новые поля получают значения по умолчанию, а удалённые из манифеста — пропадают.

Откатить на карточке возвращает предыдущий пакет вместе с копией базы, снятой перед обновлением. Хранится одна предыдущая версия. Откат невозможен, если файла копии нет; нужен админ с правами предыдущей версии и его пароль.

Миграции

• Выпущенную миграцию не меняют. Панель хранит её хэш и откажется ставить обновление, в котором она изменилась. Изменения схемы — только новыми файлами: 0002_add_email.sql, 0003_index.sql.
• Порядок — по имени, поэтому номера с ведущими нулями.
• Проверка перед выпуском:

rospanel plugin pack . --prev my-plugin-1.1.0.zip

--prev сравнивает миграции с прошлым пакетом и отказывается собирать, если выпущенная миграция изменилась или пропала. - Миграция выполняется целиком или не выполняется. Если она упала, обновление не ставится, а база остаётся прежней.

Совместимость данных

Ваша база переживает обновления, а иногда и откаты. Поэтому:

• новые столбцы добавляйте с DEFAULT или как допускающие NULL;
• код новой версии должен понимать старые записи в kv;
• не удаляйте таблицы, которые читает предыдущая версия, в той же версии, где перестали их использовать, — иначе откат вернёт код без его данных.

Как поделиться плагином

1. Выложите исходники в открытый репозиторий: оператор должен иметь возможность прочитать код.
2. Соберите пакет: rospanel plugin pack . (и --prev для новой версии).
3. Приложите zip к релизу (например, GitHub Releases). Оператор ставит его по ссылке на файл.

Выпущенный zip не меняйте: новая версия — новый файл и новое число в version.

Перед тем как делиться

• Права. Плагин просит только то, что использует; net — только нужные хосты.
• Данные пользователей не уходят туда, о чём не сказано в описании.
• Секреты. Не попадают в лог и в ответы onHttp.
• Вебхуки и onHttp проверяют подпись или токен; платёжный webhook не верит телу без подписи и перепроверяет оплату через status.
• Повторы. События обрабатываются идемпотентно: повтор доставки ничего не дублирует.
• Без обхода песочницы. Нет обфускации и кода, загружаемого извне (eval того, что пришло из сети).
• Миграции не ломают откат на предыдущую версию.

Лицензия

Укажите license в манифесте и положите LICENSE в пакет. Открытая лицензия (MIT, Apache-2.0, GPL и т. п.) позволяет операторам читать и исправлять код.