Skip to content

Плагины для RosPanel

English version

Плагин — это JavaScript, который работает внутри панели. Он реагирует на события, работает по расписанию, хранит свои данные, обращается к API панели и в интернет — ровно настолько, насколько оператор разрешил при установке. Плагины в бета-версии.

Что может плагин

Задача Как Пример
Реагировать на события: регистрация, оплата, конец подписки, падение сервера onEvent new-users, notify-discord
Делать что-то по расписанию cron users-csv
Добавить способ оплаты payment lava
Принимать запросы из интернета: магазин, форма, OAuth onHttp shop-webhook
Показать данные в карточке пользователя, кнопки, виджеты на обзоре userFields, onAction, widget email
Блоки и тема на странице подписки subBlocks, theme announcement, theme-night
Доставлять сообщения тем, кого не достаёт бот (почта, SMS) channel email
Решать, кого пускать к регистрации, какое устройство привязать, какую цену дать beforeSignup, beforeDeviceBind, quotePrice channel-gate
Кнопки и команды в пользовательском боте bot channel-gate
Менять конфиги подписки, которые получают клиенты transformSubscription —

Быстрый старт

Всё нужное встроено в rospanel, Node.js не нужен.

rospanel plugin new my-plugin   # рабочий плагин из шаблона
cd my-plugin
rospanel plugin test .          # тесты
rospanel plugin dev .           # консоль с перезагрузкой при сохранении
rospanel plugin pack .          # my-plugin-0.1.0.zip

Zip ставится в панели: Настройки → Плагины → Добавить. Или напишите плагин прямо в панели — см. редактор.

// main.js — панель вызывает то, что экспортировано
export function onEvent(e) {
  if (e.event === "user.created") panel.log.info("новый пользователь", e.data.name);
}

Документация

  1. Редактор плагинов в панели — конструктор правил, редактор кода, тесты и пробный запуск, не выходя из панели.
  2. Первый плагин: шаг за шагом — от plugin new до установки, на примере уведомлений в Telegram.
  3. Манифест и пакет — plugin.json целиком: права, хосты, настройки, точки, ресурсы.
  4. Точки расширения — каждый экспорт: когда вызывается, что получает, что вернуть, лимиты времени.
  5. API плагина — panel.config, log, kv, db, api, http.fetch, blob, crypto, t.
  6. Тесты и отладка — test.js, моки, dev, validate, лог в панели.
  7. Публикация и обновления — версии, миграции, откат, как поделиться плагином.
  8. Лимиты, безопасность и ошибки — песочница, лимиты, остановка плагина, разбор частых ошибок, вопросы.

Типы для редактора — rospanel.d.ts, его кладёт в папку plugin new. События и их поля — в docs/api.md, маршруты API — в /v1/docs вашей панели.

Главное, что нужно помнить

  • Синхронный код. Все вызовы panel.* синхронны. Таймеров нет.
  • Доставка «хотя бы один раз». Событие может прийти дважды, обрабатывайте его идемпотентно.
  • Состояние — в хранилище. Держите его в panel.kv/panel.db, а не в переменных: VM может перезапуститься между вызовами.
  • Ошибки и повторы. Исключение — это ошибка: событие доставят снова, а после 10 ошибок подряд плагин остановится, пока панель не запустит его снова.
  • Минимум прав. Просите только нужные права и хосты: оператор видит их до установки.