SaviorBill SaviorBill
EN
SaviorBill / Блог / Архитектура биллинга без монолитов: почему изоляция логики на Lua побеждает спагетти-плагины

Архитектура биллинга без монолитов: почему изоляция логики на Lua побеждает спагетти-плагины

Архитектура биллинга без монолитов: почему изоляция логики на Lua побеждает спагетти-плагины

Когда встает задача продавать цифровые товары, подписки или доступ к инфраструктуре, разработчик почти всегда оказывается перед не самым приятным выбором:

  1. Классические монолитные биллинги: громоздкие монолиты с прямым доступом сторонних плагинов к базе данных, сложная кодовая база и постоянный риск нарушить стабильность ядра из-за ошибки в одном стороннем модуле.
  2. Закрытые зарубежные SaaS (Stripe, Paddle, LemonSqueezy): высокие комиссии (5–10%), недоступность во многих юрисдикциях, отсутствие поддержки локальных платежек (СБП, ЮKassa, крипта) и полная зависимость от внешнего сервиса.
  3. Самописные боты «на коленке»: работают до первой тысячи пользователей, после чего превращаются в хаос без учета, мультивалютности и централизованной аналитики.

Именно поэтому родился SaviorBill — современная, событийно-ориентированная self-hosted платформа с изолированной логикой на Lua и Server-Driven интерфейсом.


Архитектурное разделение: Core vs Workers

Главная инженерная идея SaviorBill — нулевой код интеграций в ядре биллинга.

Ядро платформы (BillingCore) написано на Python 3.12 + FastAPI + PostgreSQL 16. Оно отвечает исключительно за финансовую целостность, мультивалютный баланс, транзакции, права доступа и учет пользователей.

Вся внешняя деятельность — создание серверов, генерация VPN-конфигов, проверка платежей эквайрингов — вынесена в изолированный сервис LuaWorker (Lua 5.4). Связь между ними происходит асинхронно через шину задач Valkey Streams.

[Клиентский запрос]
       │
       ▼
 [BillingCore (FastAPI)] ──(Транзакции & Баланс)──► [PostgreSQL]
       │
       ▼ (Valkey Streams: задача с контрактом ctx)
 [LuaWorker (Lua 5.4 Sandbox)]
       │
       ├─► Запрос к внешнему API (WireGuard / Proxmox / ЮKassa)
       └─► Возврат: { public, private, state, expires_at }

Если внешний сервис зависнет, вернет 500 ошибку или упадет — ядро биллинга продолжит работать стабильно и штатно обработает ретрай.


Контракты задач в Lua: строгость без лишней сложности

Каждый Lua-скрипт работает только с объектом ctx — изолированным контекстом своей задачи. Скрипту не нужно знать внутреннее устройство базы данных или таблиц.

Встроенный редактор Lua-скриптов прямо в админке

Пример: Скрипт выдачи VPN-подписки

-- scripts/services/marzban-vless.lua
local M = {}

function M.create(ctx)
  local s = (ctx.lua or {}).settings or {}
  -- Запрос к REST API панели через изолированный HTTP-клиент
  local resp = http({
    url = "https://" .. s.panel_domain .. "/api/user",
    method = "POST",
    headers = { 
      ["Authorization"] = "Bearer " .. s.jwt_token,
      ["Content-Type"] = "application/json" 
    },
    body = json.encode({ 
      username = "sb_" .. tostring(ctx.user.id) .. "_" .. crypto.random_hex(4),
      expire = os.time() + (tonumber(ctx.service.duration) or 2592000)
    })
  })
  local u = json.decode(resp.body) or {}

  return {
    public = {
      subscription_url = u.subscription_url,
      node_type = "VLESS"
    },
    private = {
      external_user_id = u.id
    },
    state = "active",
    expires_at = os.time() + (30 * 86400)
  }
end

function M.freeze(ctx)
  -- Временная заморозка доступа при нехватке баланса
  return { state = "frozen" }
end

return M

Что здесь происходит:

  • public: данные, которые автоматически передаются клиенту;
  • private: внутренние идентификаторы, доступные только ядру;
  • state и expires_at: параметры, по которым биллинг автоматически управляет жизненным циклом услуги.

Server-Driven UI: sbuiSDK

В классических биллингах добавление нового типа услуги требует правок шаблонов фронтенда (Smarty, Blade, React).

В SaviorBill используется концепция Server-Driven UI (sbuiSDK): Lua-скрипт или манифест услуги сами описывают, как услуга должна отображаться у покупателя.

Витрина каталога и карточка товара в клиентском кабинете

Клиентский кабинет SBPersonalAccountClient парсит этот JSON и автоматически рендерит:

  • Векторные QR-коды для быстрого импорта мобильными устройствами;
  • Поля копирования токенов и ключей в 1 клик;
  • Кастомные формы настроек и ползунки ресурсов;
  • Инструкции в Markdown.

Фронтенд не нужно пересобирать — новый сервис готов к продаже сразу после сохранения Lua-манифеста в админ-панели.


Каталог услуг и гибкие модели тарификации

В SaviorBill поддерживаются четыре фундаментальные модели продажи:

  1. fixed: разовая покупка с фиксированной ценой;
  2. custom: произвольная сумма в заданных пределах (пополнение балансов, донаты);
  3. tiered: тарифная сетка с разбивкой по длительностям (месяц, квартал, год);
  4. configurable: интерактивный конструктор ресурсов (vCPU, RAM, диск) с пересчетом стоимости в реальном времени.

Каталог услуг в панели администратора


Заключение и запуск

SaviorBill задумывался как инструмент, который дает разработчику полную свободу: данные на вашем сервере, логика в понятном изолированном Lua, а покупатели получают быстрый и отзывчивый интерфейс.

Запустить инстанс можно буквально за две минуты:

curl -fsSL https://get.saviorbill.com | bash

Делитесь отзывами и присоединяйтесь к развитию проекта на GitHub!

Часто задаваемые вопросы (FAQ)

В чем ключевое отличие SaviorBill от классических биллинг-панелей?

SaviorBill полностью разделяет ядро и бизнес-логику. Вся интеграция с внешними сервисами, эквайрингами и выдачей товаров изолирована в легковесной песочнице Lua 5.4 с жестким контрактом ctx.

Что такое Server-Driven UI (sbuiSDK)?

Это декларативный подход, при котором Lua-скрипт выдачи услуги сам возвращает JSON-манифест интерфейса (QR-коды, поля копирования, конфигураторы), а клиентский кабинет мгновенно рендерит их без пересборки фронтенда.

Как быстро развернуть SaviorBill?

С помощью официального скрипта быстрой установки: curl -fsSL https://get.saviorbill.com | bash