Автоматизація білінгу та провізіювання HestiaCP

Автоматизований хостинговий продукт має рівно три моменти, коли гроші й машини стикаються одне з одним:

1. 01Замовлення оплачено: обліковий запис має існувати, з правильним пакетом, протягом кількох секунд.
2. 02Рахунок прострочено: обліковий запис має згаснути й повернутися щойно його оплачено.
3. 03Підписка завершується: обліковий запис треба видалити, по-справжньому, разом з даними.

У HestiaCP є команда для кожного з них. Чого в ньому немає, так це чогось, що вирішує, коли їх запускати. Ця сторінка про те, як зʼєднати ці дві половини, і про конкретні місця, де API HestiaCP відповідає так, що це нишком зламає першу спробу.

Три моменти та команди, що стоять за ними

Зверніть увагу на стовпчик відповідей. Успішною мутацією в HestiaCP є HTTP 204 з порожнім тілом. Не 200. Клієнт, написаний із припущенням, що успіхом є 200, відхиляє кожен виклик, який спрацював, а потім зазвичай повторює його, і саме так робоча інтеграція перетворюється на заблоковану (див. нижче).

Справжня відповідь живе в заголовку відповіді, Hestia-Exit-Code, який несе число з фіксованої таблиці. HTTP-статус виводиться з нього і згортає близько двадцяти кодів на чотири статуси. Читайте заголовок; статус вважайте лише підказкою.

Призупинення не симетричне, і тут це важить більше, ніж будь-де

Це пастка, яка вражає саме інтеграцію білінгу, бо інтеграція білінгу є єдиним, що призупиняє той самий обліковий запис двічі.

Виміряно, на одному й тому самому обліковому записі:

v-suspend-user   on an active account     → 204, exit 0
v-suspend-user   on a suspended account   → 401, exit 5   ("user X is suspended")
v-unsuspend-user on a suspended account   → 204, exit 0
v-unsuspend-user on an active account     → 204, exit 0

Зняття призупинення ідемпотентне. Призупинення ідемпотентним не є. І помилкою, яку воно дає, є HTTP 401, той самий статус, який ви отримуєте за неправильний секрет, за ключ поза межами дозволів і за заблоковану адресу.

Тож прогін нагадувань, який призупиняє все прострочене, зокрема те, що вже призупинив учора, повідомлятиме про збої автентифікації для облікових записів, які перебувають рівно в тому стані, якого ви й хотіли. Код виходу 5 на v-suspend-user означає «уже в цьому стані» і має читатися як успіх.

Ніколи не повторюйте спробу за помилкою автентифікації

HestiaCP блокує адресу після пʼяти відмовлених входів, за допомогою fail2ban із maxretry = 5 та iptables DROP. Щойно це спрацьовує, виклики перестають вичерпувати час на рівні застосунку й починають вичерпувати його на рівні мережі: ваш моніторинг каже, що панель недосяжна, і ніщо у ваших журналах не вказує на проблему з обліковими даними.

Для інтеграції білінгу це важить більше, ніж для будь-чого іншого, бо саме інтеграція білінгу працює без нагляду вночі. Два наслідки:

• Коди виходу 9, 10 і 21 ніколи не мають запускати автоматичну повторну спробу. Це відповідно неправильний секрет, відмова в дозволі та вимкнений API. Жоден із них не є тимчасовим збоєм, і всі три враховуються до блокування.
• Команда поза межами дозволів ключа теж рахується як невдалий вхід. Це неочевидно: той самий рядок журналу пишеться і для неправильного секрету, і для дійсного ключа, що тягнеться до команди, яку йому не дозволено виконувати. Ключ, обмежений вбудованим у HestiaCP набором дозволів billing, не має v-list-user-packages і v-list-web-domains, тож цикл опитування, який читає пакети й домени, за розкладом випалює лічильник блокування. Використовуйте необмежений ключ для користувача-адміністратора.

Щоб зняти блокування, потрібна оболонка на хості панелі: v-delete-firewall-ban <address> HESTIA. Якщо збудоване вами ПЗ не може сказати це речення, той, хто чергує о третій ночі, проведе ніч не над тією проблемою.

Оплачене замовлення потребує двох викликів, тож потрібен відкат

У HestiaCP немає команди, яка створює користувача й приєднує домен за один раз. Це лишає вікно:

v-add-user       provibrtest1 …                        → 204, exit 0
v-add-web-domain provibrtest1 "not a valid domain"      → 422, exit 2
v-list-user      provibrtest1                           → the account exists, with zero domains

Справжній unix-користувач, з домашнім каталогом, без вебсайту, і рядок у кожному підрахунку. Якщо домен клієнта вже було зайнято на вашій панелі (а таке трапляється, бо клієнти переїжджають), замовлення зазнає невдачі, і у вас лишається половина облікового запису, якої ніхто ніколи не помітить.

Правило просте, і його треба закласти всередину: якщо другий крок зазнає невдачі, видаліть користувача й повідомте початкову помилку. Відхилений домен ніколи не має лишати по собі половину облікового запису.

Provibr робить саме це, і клієнт бачить ту помилку, яку HestiaCP видав за домен, а не вторинну помилку про очищення.

Де насправді живе рахунок

Варто сказати прямо, бо це найпоширеніше непорозуміння: Provibr не виставляє рахунки вашим клієнтам. Він не надсилає їм рахунок, не переслідує їх і не знає, скільки ви з них берете. Ці стосунки належать вам.

Provibr виставляє рахунок за потужність, яку резервуєте ви: скільки хостингових облікових записів вам дозволено запускати одночасно, за місяць, за ціною за одиницю з рівнями. Те, що ви берете з власних клієнтів за обліковий запис HestiaCP, і як, лишається цілком усередині вашої власної системи білінгу.

Зʼєднати ці дві половини можна двома способами:

Модуль WHMCS. Якщо ви вже користуєтеся WHMCS, встановіть модуль провізіювання Provibr і вкажіть одному продукту WHMCS один вебплан Provibr. Оплачене замовлення створює обліковий запис; призупинення у WHMCS призупиняє його; припинення видаляє його. Ваш клієнт має один обліковий запис, один рахунок і один вхід. Модуль є звичайним zip-архівом, який ви встановлюєте самі, і він працює всередині вашого WHMCS. З нашого боку нічого вмикати не треба.

REST API. Якщо ви користуєтеся FOSSBilling, Blesta, чимось власним чи таблицею й cron-завданням, керуйте ним напряму. Один ключ, одна базова URL і рівно ті дозволи, які вже має учасник за цим ключем.

Єдине правило для керування ним із власного коду

Все, що торкається машини, є асинхронним, і так має бути. Ваша інфраструктура доступна лише через агента всередині вашої власної мережі, а той агент дзвонить назовні. Тож кінцева точка, яка змінює обліковий запис, не може відповісти результатом. Вона відповідає, що замовлення прийнято, і віддає вам команду, за якою треба стежити: ви читаєте її, доки її статус не стане остаточним (виконано, не вдалося, вичерпано час або скасовано). Невдала команда несе власний код помилки агента з його аргументами, той самий, що панель показує на екрані.

Читання так не працює ніколи. Інвентар, адреса чи рахунок відповідають одразу, бо ця відповідь надходить із бази даних, а не з вашого хоста.

Практичний наслідок для гачка білінгу: не позначайте замовлення завершеним за відповіддю про прийняття. У HestiaCP v-add-user триває близько секунди, а v-delete-user триває близько трьох, тож чекати недовго, але перша відповідь, яку ви отримуєте, означає «ми надіслали», а не «спрацювало».

Призупинення є також вашим власним контролем витрат

Один звʼязок, який легко пропустити. У Provibr призупинений сервер не враховується у вашу потужність, а для хостингового облікового запису немає «зупинено»: є активний і призупинений.

Тож дія нагадування, яку ви вже хотіли виконувати з комерційних причин, водночас звільняє слот, за який ви платите. Призупиніть прострочений обліковий запис, і він одразу перестає враховуватися; видаліть його, і він теж перестає враховуватися; лишіть його працювати неоплаченим, і ви за нього платите.

Чого це не автоматизує

Provibr керує обліковими записами, а не панеллю. Він не встановлює HestiaCP, не оновлює його, не змінює налаштування сервера й не торкається DNS, поштових скриньок чи баз даних. Клієнт, який видаляє власну поштову скриньку через HestiaCP, робить це без того, щоб щось над ним про це знало чи цим переймалося. Для хостингового облікового запису немає консолі. І немає часткового призупинення: обліковий запис або активний, або ні.

Якщо ви також продаєте VPS, ігрові сервери чи облікові записи cPanel, ті самі три моменти стосуються всіх їх, і вони можуть жити в одному інвентарі. Provibr сьогодні тримає свої панелі керування, гіпервізори та ігрові панелі пліч-о-пліч, з одним набором прав і одним журналом активності на всіх.