Платформа дополнений
Дополнение — это отдельная программа: свой процесс или контейнер, своя база данных и свой интерфейс. Панель никогда не запускает его код, никогда не показывает его страницы внутри своих и не хранит его данные. Панель регистрирует дополнение, выдаёт ему ровно тот доступ, который вы одобрили, и следит за ним. Эта страница объясняет, как это устроено. Установка описана в Установка дополнения и Страница дополнений, разработка — в Создание дополнения.
Что можно выдать дополнению
Две вещи, и ничего больше:
- API-токен с набором прав (областей), к каждому из которых дополнение указывает причину. Дополнение читает и меняет панель через тот же API, что и все остальные.
- Вебхук, который получает названные им события. Для каждого события нужно право, которое позволило бы дополнению прочитать то, о чём событие, и манифест отклоняется, если этого права нет среди запрошенных.
Основные сведения о пользователе, например контактные данные, хранятся в собственных столбцах панели, которые дополнение читает и пишет своим токеном. Всё остальное, что дополнению нужно хранить, например заказы и платежи магазина, остаётся в собственной базе данных дополнения.
Манифест
Каждое дополнение описывает себя в манифесте: идентификатор, название и версия, запрашиваемые права с причиной для каждого, нужные события, пути настройки, вебхука и проверки состояния, лимит запросов для его токена и способ установки. Тот же файл лежит в публичном репозитории дополнения, где его читают каталог и форма установки, и отдаётся работающим дополнением, где его читает регистрация. Полный формат описан в Манифест дополнения.
Подписи и доверие
Манифесту доверяют только по подписи:
| Вид | Кем подписан | Как регистрируется |
|---|---|---|
| Официальное | ключом Nexora | по коду привязки |
| Проверенное | ключом своего разработчика, за который ручается каталог дополнений | по коду привязки; экран согласия называет разработчика |
| Неподписанное или неофициальное | никем, кому доверяет панель | вручную, как ваше собственное дополнение |
Подпись покрывает каждое поле, поэтому изменение любого из них её ломает. Контрольные суммы выпуска подписываются тем же ключом, и панель сама устанавливает дополнение на сервер, только если файлы им соответствуют.
Регистрация по коду привязки
- Дополнение запускается с одноразовым кодом привязки, который оно показывает в своём журнале или на своей странице. Когда дополнение устанавливает панель, она сама создаёт код и уже его знает.
- Панель читает манифест по адресу дополнения, проверяет подпись и показывает экран согласия: каждое право с причиной, каждое событие, лимит запросов и кто подписал манифест.
- Вы одобряете. Панель снова читает манифест и проверяет, что это тот самый документ, который показывал экран, затем создаёт ровно этот токен и этот вебхук и передаёт их на путь настройки дополнения вместе с кодом привязки.
- Дополнение принимает их только со своим кодом. Если оно отвечает чем-либо, кроме успеха (например, код неверный), панель удаляет только что созданное. Неудавшаяся регистрация ничего после себя не оставляет.
Панель отправляет дополнению действующий токен, поэтому говорит с ним по обычному http://, только когда каждый адрес, в который оно разрешается, находится на этом сервере, в частной сети или в сети контейнеров. В любом другом случае дополнение должно работать на https://.
Выданные права принадлежат строке дополнения
После регистрации токен и вебхук принадлежат строке дополнения на странице Сервисы → Дополнения:
- Они видны в Токены API и Вебхуки с пометкой названия дополнения, и там их нельзя изменить, заменить или удалить.
- Токен привязан к владельцу панели, а не к тому, кто нажал одобрение, поэтому он продолжает работать, когда этот администратор уходит, и переходит вместе с правом владения, если вы его передадите.
- Удалить сначала сообщает дополнению, затем удаляет его токен и вебхук. То, что дополнение хранило о ваших пользователях в своей базе, остаётся там, поэтому повторная регистрация это найдёт.
Проверка состояния
Если манифест указывает путь проверки состояния, панель обращается к нему каждую минуту. Ответ 200 означает, что всё в порядке.
- Две неудачные проверки подряд помечают дополнение как неисправное с последней ошибкой и один раз создают
panel.addon_unhealthy. - Следующий ответ 200 возвращает его и создаёт
panel.addon_recovered.
Состояние хранится в базе, поэтому перезапуск панели не повторяет ни одно из событий. Дополнение без пути проверки состояния не опрашивается.
Приостановка
Приостановить останавливает дополнение, не удаляя его: его токен сразу перестаёт работать, а вебхук перестаёт получать события. События, созданные, пока оно приостановлено, для него не сохраняются. Приостановленное дополнение не опрашивается о состоянии. Возобновить включает и то и другое обратно.
Обновления никогда сами не расширяют права
Панель заново читает манифест подписанного дополнения каждый час и когда вы нажимаете Проверить обновление.
- Версия, которая не просит ничего сверх того, что у дополнения уже есть, применяется сама.
- Версия, которая просит больше прав, событий или более высокий лимит запросов, ждёт. Дополнение сохраняет ровно то, что у него есть, его строка показывает Ждёт обновление, один раз создаётся
panel.addon_update_waiting, а при просмотре перечисляется только то, что добавляет обновление, с причиной для каждого пункта, чтобы вы его одобрили. - Версию, которая просит токен или вебхук, которых у дополнения никогда не было, нельзя одобрить на месте: для этих учётных данных нужен код привязки, который дополнение уже израсходовало. Удалите дополнение и зарегистрируйте его заново.
Сертификаты от панели
Дополнение, которое обслуживает HTTPS, может брать сертификат из хранилища панели, а не получать его само. Панель выпускает и продлевает его; дополнение забирает его каждые несколько минут, до регистрации по коду привязки, а после — по своему токену, и хранит копию, чтобы подниматься с HTTPS, даже пока панель недоступна. Тогда ему не нужны свои порты 80 и 443, и несколько дополнений могут делить сервер с панелью.
Дополнению на другом сервере предлагаются только сертификаты, которые сервер панели не подтверждал: выпущенные через проверку DNS, самоподписанные или загруженные. Собственный HTTPS-сертификат панели никогда не передаётся дополнению на другом сервере, потому что его ключ позволил бы этому серверу выдать себя за панель. Это проверяется заново при каждом получении. См. Выпуск и продление сертификатов.
Установка на собственный сервер панели
Когда панель работает прямо на Linux-сервере (не в контейнере), она может установить дополнение рядом с собой без SSH: она запускает скрипт установки дополнения от root, предварительно сверив выпуск с его подписанными контрольными суммами, а дополнение берёт сертификат у панели. При установке по SSH на другой сервер действуют те же проверки; ключ хоста сервера запоминается при первом подключении, а пароль или ключ SSH никогда не сохраняется.
Связанные страницы
- Шина событий: как события доходят до вебхука дополнения.
- Модель безопасности: API-токены и области.
- Каталог дополнений: каталог и его уровни.