Docs

Русский

English
Türkçe

Русский

English
Türkçe

Оформление

Выпуск ​

Shoutbox работает на вашей машине: таблица, API, виджет, страница панели и переводы. Пора превратить его в настоящий, устанавливаемый аддон — и представить его миру. Это финишная черта.

Справочные страницы для глубины: Сборка и публикация и Премиум-аддоны и лицензирование.

Вся работа, по порядку ​

Большая часть этого — одноразовая настройка. После неё каждый будущий выпуск — это просто последний шаг: закоммитить и запушить.

  1. Соберите один раз локально, чтобы убедиться, что jar создаётся.
  2. Создайте свой ресурс на Marketplace на panomc.com.
  3. Добавьте два секрета GitHub — PANO_PROD_TOKEN и TOKEN_GITHUB.
  4. Добавьте .releaserc.json с плагином публикации Pano.
  5. Добавьте один шаг установки в workflow выпуска.
  6. Закоммитьте с сообщением в формате conventional-commit и запушьте в main.

Шаг 1 — релизная сборка ​

Релизная сборка компилирует ваш бэкенд на Kotlin и собирает и встраивает UI на Svelte в один самодостаточный jar. Это обычный:

sh
./gradlew build

Вы должны увидеть BUILD SUCCESSFUL и jar по пути build/libs/pano-plugin-shoutbox-local-build.jar. Локально версия всегда local-build; настоящие номера версий приходят из CI.

Релизным jar нужен UI — никогда не используйте -Pnoui

-Pnoui пропускает сборку UI. Для выпуска это отгружает сломанный аддон: либо вообще без UI (если вы его никогда не собирали), либо устаревший UI (если старая сборка оставила plugin-ui.zip). -Pnoui — только для быстрого цикла разработки с одним бэкендом. Чтобы точно не переиспользовать старый UI, выполните ./gradlew clean build.

Шаг 2 — версионирование автоматическое ​

У каждого выпуска есть версия вроде 1.0.0. Вы не повышаете её вручную. Версии приходят из ваших Conventional Commits — каждый коммит начинается со слова вроде feat: (возможность), fix: (исправление бага) или chore: (рутина):

  • fix: → повышает patch (1.0.0 → 1.0.1)
  • feat: → повышает minor (1.0.0 → 1.1.0)
  • feat: с футером BREAKING CHANGE: → повышает major (1.0.0 → 2.0.0)

Оставьте version в gradle.properties равным local-build — CI вставляет настоящий номер из истории ваших коммитов. Ручное редактирование ломает автоматизацию.

Два канала выпуска, выбираемые веткой

Шаблон публикует предрелиз (1.1.0-dev.3), когда вы пушите в dev, и стабильный выпуск (1.1.0), когда вы пушите в main. Владельцы серверов всегда видят только стабильные. Публикуете свой первый аддон? Оставьте всё простым и публикуйте только в main.

Шаг 3 — создайте ресурс на Marketplace ​

Marketplace на panomc.com — это место, где владельцы серверов находят и устанавливают аддоны из своей панели.

  1. Зарегистрируйтесь (или войдите) на panomc.com.
  2. Откройте Create Resource и выберите тип Plugin.
  3. Выберите категорию, заполните заголовок и описание.
  4. Выберите цену: бесплатно или платно (платный добавляет премиум-шаг в конце).

Теперь вы должны увидеть страницу вашего аддона с пустым списком версий — автоматизация заполнит его, когда вы запушите.

Ваш ID ресурса и есть ваш plugin ID

Для аддонов resourceId на Marketplace — это в точности ваш pluginId — pano-plugin-shoutbox. (Темы используют случайный UUID; аддоны — нет.) Вот почему в конфигурации ниже используется "resourceId": "pano-plugin-shoutbox".

Шаг 4 — добавьте два обязательных секрета ​

В вашем GitHub-репозитории перейдите в Settings → Secrets and variables → Actions и добавьте:

  • PANO_PROD_TOKEN — API-токен с panomc.com (Profile → Settings → API Tokens → Create). Он показывается только один раз; скопируйте его сразу.
  • TOKEN_GITHUB — Personal Access Token (classic, с областью repo), который вы генерируете в GitHub под Settings → Developer settings. Workflow шаблона читает его в нескольких местах, включая пробный прогон версии.

Пропустите TOKEN_GITHUB — и каждый выпуск падает на самом первом шаге

Встроенный GITHUB_TOKEN от GitHub не доступен под этим именем, так что вы должны создать PAT сами. И никогда не коммитьте API-токен — храните его только как секрет GitHub.

Шаг 5 — настройте .releaserc.json ​

.releaserc.json — это место, где настраивается инструмент выпуска (semantic-release). Шаблон поставляет один, который создаёт выпуск на GitHub; чтобы также публиковать на Marketplace, добавьте плагин @PanoMC/semantic-release-pano. Вот полный файл для Shoutbox:

json
{
  "branches": [{ "name": "dev", "prerelease": true }, "main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@semantic-release/github", {
      "assets": [
        { "path": "build/libs/*.jar", "label": false },
        { "path": "LICENSE", "label": false }
      ]
    }],
    ["@PanoMC/semantic-release-pano", {
      "file": "build/libs/pano-plugin-shoutbox-${version}.jar",
      "panoVersion": "1.0.0",
      "useGitHubLink": true,
      "repositoryUrl": "https://github.com/YourName/pano-plugin-shoutbox.git",
      "configs": [
        {
          "resourceId": "pano-plugin-shoutbox",
          "panoUrl": "https://api.panomc.com",
          "tokenVar": "PANO_PROD_TOKEN",
          "branches": ["main"]
        }
      ]
    }]
  ],
  "repositoryUrl": "https://github.com/YourName/pano-plugin-shoutbox.git"
}

Замените заполнители

Замените YourName (в обеих строках repositoryUrl) на своё имя пользователя GitHub и убедитесь, что pano-plugin-shoutbox (путь file и resourceId) — это ваш собственный pluginId. Держите плагины в этом порядке — плагин GitHub должен выполниться до плагина Pano, чтобы jar уже был прикреплён, когда useGitHubLink его затребует. useGitHubLink: true указывает Marketplace на jar, уже находящийся на вашем выпуске GitHub, вместо повторной загрузки — идеально для бесплатного аддона.

Полный разбор поле-за-полем, плюс как добавить необязательный песочный канал dev, — в Сборке и публикации.

Шаг 6 — установите плагин Pano в workflow ​

@PanoMC/semantic-release-pano нет в npm, так что перечислить его в .releaserc.json недостаточно — semantic-release падает с «Cannot find module @PanoMC/semantic-release-pano», пока вы его не установите.

Добавьте эту одну строку в обе задачи в .github/workflows/release.yml (задачу пробного прогона версии и задачу выпуска), перед шагом semantic-release каждой задачи:

yaml
- run: npm install -D git+https://github.com/PanoMC/semantic-release-pano.git

Обе задачи, иначе падает на той, что вы пропустили

Если вы добавите её только в одну задачу, прогон упадёт на другой с той же ошибкой «Cannot find module». Это единственная обязательная правка workflow — всё остальное в workflow шаблона оставьте как есть.

Шаг 7 — запушьте и наблюдайте, как он публикуется ​

Когда ресурс создан, оба секрета добавлены, а .releaserc.json и шаг workflow на месте, публикация — это просто conventional-commit и push:

sh
git push origin main

Откройте вкладку Actions вашего репозитория. Прогон с именем Pano Plugin Build появляется в течение минуты и завершается за несколько минут.

  • Зелёная галочка = выпущено. Откройте свой ресурс на panomc.com — новая версия в списке, а владельцы серверов видят обновление в Панель → Аддоны.
  • Красный крестик = кликните в упавший шаг. Две самые частые ошибки — та самая «Cannot find module» (вы пропустили шаг установки в одной задаче) и сбой авторизации на первом шаге (отсутствующий или неверный TOKEN_GITHUB).

Вы также можете распространять вручную

Поскольку jar полностью самодостаточен, вы можете прикрепить его к выпуску GitHub или передать владельцу сервера, чтобы тот загрузил его через Панель → Аддоны → Загрузить. Аддоны с Marketplace получают значок проверенного и автоматическую доставку обновлений; ручные jar — нет, так что для публичного аддона Marketplace настоятельно предпочтительнее.

Необязательно — продавайте Shoutbox как премиум-аддон ​

Хотите брать за него плату? Процесс выпуска тот же, плюс два маленьких кусочка: соберите jar с лицензионным ключом и сохраните встроенную в шаблон проверку лицензии во время работы. Коротко:

  • Соберите с ./gradlew build -PlicenseServer=prod (или задайте PANO_LICENSE_SERVER в CI), чтобы публичный ключ верификации panomc.com был зашит в jar.
  • Держите licenseClient.requireValidLicense() в начале onStart() — свежий шаблон уже содержит его, и на бесплатных сборках это no-op.
  • Установите цену ресурса платно и задайте useGitHubLink: false, чтобы Marketplace держал мастер-jar и записывал его SHA-256.

Полное пошаговое руководство — встраивание ключа, проверка во время работы и её тестирование против вашего собственного аккаунта — в Премиум-аддонах и лицензировании.

Никакая система лицензирования не абсолютна

Никакая DRM не защищает код на 100% — любой код, попадающий к конечному пользователю, может быть разобран достаточно решительным человеком. Цель — сделать несанкционированное использование трудным для подавляющего большинства, а не невозможным. Устанавливайте цену и поддерживайте свой аддон с учётом этой реальности.

Вы это сделали ​

Shoutbox прошёл путь от клонированного шаблона до работающего аддона — таблица базы данных, JSON-API, право доступа, виджет на главной странице, страница панели, переводы — установленного на вашем собственном Pano и опубликованного на Marketplace. Это всё путешествие.

Куда двигаться дальше, в справочной документации:

Приятной сборки. 🚀

Далее: Справочник аддонов: С чего начать →

Copyright © 2026 Pano