Abrechnungs-Automatisierung für Pelican Panel

Pelican hat an jedem Server ein suspended-Flag. Nichts in Pelican setzt es jemals. Dieser eine Satz ist der ganze Grund für diese Seite: Das Panel kann den Server eines Kunden anhalten, aber es hat keine Ahnung, ob dieser Kunde bezahlt hat.

Diese Seite beschreibt, wie eine funktionierende Automatisierung aussieht: der Bestellweg, der Mahnweg und die Teile, die schwieriger sind, als sie aussehen.

Zwei Abrechnungsebenen, und das ist nicht dasselbe

Trennen Sie sie zuerst. Diese beiden werden ständig verwechselt, und dann wird über das falsche Problem diskutiert.

Was Sie Ihren eigenen Kunden berechnen und wie, bleibt vollständig in Ihrem Abrechnungssystem. Provibr sieht nie eine Kundenrechnung, legt nie einen Preis für Sie fest und spricht nie mit Ihren Kunden; es rechnet mit Ihnen reservierte Kapazität je Ressourcenart ab, zu einem Stückpreis, der mit steigender Anzahl in Stufen sinkt.

Diese Trennung macht die Automatisierung überhaupt handhabbar. Ihr Abrechnungssystem besitzt die Entscheidung, die Provisionierungsschicht die Ausführung.

Der Lebenszyklus, abgebildet

Das ist die Zuordnung, die jede Gameserver-Automatisierung braucht, welche Werkzeuge Sie auch nutzen:

Pelican ist hier bequem, und das gehört deutlich gesagt, denn nicht jedes Gamepanel ist das. Pelican hat ein echtes Sperr-Primitiv. Ein gesperrter Server ist im Panel gesperrt: Wer direkten Zugang zu Pelican hat, kann ihn nicht einfach wieder starten. Wenn die Durchsetzung zählt (und beim Mahnwesen tut sie das), ist das der Unterschied zwischen einer Regel und einem Wunsch.

(Zum Vergleich: PufferPanel hat keine eigene Sperre, dort ist eine Sperre also ein Plattformbegriff, den das Panel nicht durchsetzt.)

Die Regel, die alles prägt: nichts ist sofort fertig

Das ist der Teil, den man falsch macht, wenn man eine API selbst zusammensteckt.

Ihr Panel steht in Ihrem eigenen Netz, und eine vernünftige Plattform erreicht es über einen Agenten, der sich nach außen verbindet: kein eingehender Port, kein Loch in der Firewall. Die Folge ist unausweichlich: Ein Endpunkt, der eine Maschine verändert, kann nicht mit dem Ergebnis antworten. Er antwortet, dass der Auftrag angenommen wurde, und gibt Ihnen etwas zum Nachverfolgen:

POST /v1/servers/{serverId}/actions/suspend
Authorization: Bearer pvk_...
Idempotency-Key: dunning-inv-10482

{
  "command": {
    "id": "cmd_...",
    "kind": "game.suspend",
    "status": "pending"
  }
}

Sie bekommen 202 Accepted, kein 200. Danach lesen Sie diesen Befehl, bis sein Status endgültig ist: done, failed, timed_out oder cancelled. Ein fehlgeschlagener Befehl trägt den Fehlercode des Agenten selbst, mit seinen Argumenten.

Lesen funktioniert nie so: Ein Inventar, eine Adresse oder eine Rechnung antwortet sofort, denn diese Antwort kommt aus einer Datenbank und nicht von Ihrem Host.

Entwerfen Sie Ihre Abrechnungs-Hooks danach. Ein Hook, der „die API hat geantwortet“ als „die Arbeit ist getan“ liest, meldet Erfolg für eine Sperre, die nie stattgefunden hat, genau an dem Tag, an dem es darauf ankam.

Eine Anfrage sicher wiederholen

Alles, was etwas anlegt, akzeptiert einen selbst gewählten Idempotency-Key-Header. Wiederholen Sie dieselbe Anfrage mit demselben Wert, bekommen Sie das erste Ergebnis zurück statt eines zweiten Servers, eines zweiten Befehls oder einer zweiten Abbuchung.

Fürs Mahnwesen ist das kein Luxus. Ein Cron, der viertelstündlich läuft, ein erneut zugestellter Webhook, ein Administrator, der zweimal klickt: Alle drei sind normal, und alle drei sollen harmlos sein. Schlüsseln Sie die Anfrage auf etwas Stabiles Ihrerseits: die Rechnungsnummer, die Dienst-ID, die Mahnstufe. Denselben Wert für eine andere Anfrage zu verwenden, wird bewusst abgelehnt: Ein Schlüssel, der zwei Dinge bedeutet, bedeutet nichts.

Die Verben, und wann sie erlaubt sind

Ein Gameserver akzeptiert sechs Aktionen über die API:

start · stop · restart · kill · suspend · resume

Sie werden vom aktuellen Status des Servers bewacht, und das strenger, als es aussieht:

Die Zeile zu suspend ist die interessante, und sie ist Absicht: Sie können einen Server sperren, der bereits gestoppt ist. Würde Sperren nur bei laufenden Servern funktionieren, könnte ein Kunde seinen eigenen Server stoppen, das Zahlen einstellen und wäre immun: Das Panel würde die Sperre ablehnen, weil nichts lief. Eine Durchsetzung, die man mit einem Druck auf „Stopp“ umgeht, ist keine Durchsetzung.

suspend aus installing zählt ebenfalls: Eine Kündigung, die mitten in der Installation eintrifft, soll nicht warten müssen, bis diese fertig ist.

Aus einem Abrechnungspanel statt aus Code

Betreiben Sie bereits WHMCS, müssen Sie nichts davon schreiben. Provibr liefert ein Provisionierungsmodul für WHMCS als einfaches Zip, das Sie selbst installieren: Ein WHMCS-Produkt zeigt auf einen Provibr-Plan, und der normale Bestellablauf von WHMCS erledigt Anlegen, Sperren, Freigeben und Beenden.

Zwei Entwurfsentscheidungen in diesem Modul lohnen sich, auch wenn Sie Ihre eigene Brücke schreiben:

Eine noch laufende Lieferung gilt als erfolgreich. Läuft das Wartebudget ab, während der Installer noch arbeitet, meldet das Modul Erfolg. Die Bestellung ist angenommen (die Server-Zeile existiert, die Adresse ist zugewiesen, der Befehl liegt beim Agenten), und WHMCS kennt keinen Status „wird installiert“ (Pending bedeutet dort es ist noch nichts geschehen, und das ist nachweislich falsch). Ein Befehl, der wirklich fehlschlägt, ist etwas anderes: Dann bleibt der Dienst Pending, der Administrator sieht warum, und ein erneuter Klick ist dank des Idempotency-Keys harmlos.

Ein Server, den es schon nicht mehr gibt, ist eine erfolgreiche Beendigung. Ein 404 beim Löschen bedeutet vier Dinge zugleich (unbekannte ID, andere Organisation, diesem Mitglied nicht zugewiesen oder bereits gelöscht), und für einen Beendigungs-Hook ist die richtige Handlung in allen vier Fällen dieselbe: Es gibt nichts mehr aufzuräumen. Als Fehler behandelt, hängt ein Dienst für immer in „terminating“.

Was bewusst nicht automatisiert ist

Ehrliche Grenzen, denn das sind die Fragen, die kommen, nachdem Sie schon etwas verkauft haben:

• Keine verbrauchsbasierte Abrechnung. Messwerte je Server werden erfasst und im Panel gezeigt, aber noch nicht über die API angeboten. Ohne Endpunkt keine verbrauchsbasierte Abrechnung. Ist Ihr Produkt „zahlen Sie für das RAM, das Sie genutzt haben“, kann das hier das heute nicht.
• Kein Planwechsel in einem Aufruf. Einen Plan zu wechseln ist auch auf Pelican-Ebene kein einzelner API-Aufruf: Es ist eine Neuinstallation oder eine Ressourcenänderung, mit unterschiedlichen Folgen für die Daten des Kunden.
• Kein Passwort-Reset über die API. Zugangsdaten reisen transient mit und werden nirgends gespeichert, es gibt also nichts, was man erneut senden könnte.
• Kein Single Sign-on von Ihrem Abrechnungspanel ins Provibr-Panel.
• Kein Inventarabgleich: eine Absage, keine Lücke. Der _ListAccounts-Sync von WHMCS beendet jeden Dienst, der in der Antwort fehlt, und „fehlt“ hat harmlose Ursachen: ein schmalerer API-Scope, ein Mitglied, das auf einen Teil des Inventars beschränkt ist, eine Ratenbegrenzung, eine kurze Seite, deren Cursor nicht verfolgt wurde. Jede davon würde Kundenmaschinen löschen. Stattdessen liest der Kundenbereich bei jedem Seitenaufruf den echten Status, und das ist keine Synchronisation und gibt auch nicht vor, eine zu sein.

Kapazität zählen, und wie das zum Mahnwesen passt

Die Plattform-Abrechnung zählt Kapazität, nicht Verbrauch, mit einer Regel, die alle im ersten Monat überrascht: Jeder Server zählt, ob er läuft oder nicht. Nur ein gesperrter Server zählt nicht, und ein gelöschter ebenso wenig. Eine Maschine zu stoppen macht keinen Platz frei.

Das passt sauber zum Mahnwesen. Ein Kunde, den Sie wegen Nichtzahlung sperren, zählt während der Sperre nicht gegen Ihre Kapazität und zählt wieder, sobald er zahlt und Sie freigeben. Sie zahlen also keine Plattformkapazität für einen Kunden, der Sie nicht bezahlt.

Über Ihr Limit zu gehen, wird nicht in dem Moment blockiert, in dem Sie es tun. Es wird erkannt, Ihnen gesagt, und Sie bekommen einen vollen Werktag. Läuft diese Schonfrist ab, werden die neuesten Server oberhalb Ihres Limits gesperrt, die neuesten zuerst, damit das zuerst Gebaute überlebt.

Pelican neben allem anderen

Ein wachsender Gamehoster bleibt selten bei einem Panel. Provibr deckt seine Controlpanels, Hypervisoren und Gamepanels in einem Dashboard ab, mit einer API und einer Kapazitätszahl über alles hinweg.

POST /v1/servers/{id}/actions/suspend tut dasselbe, ob darunter ein Pelican-Server, ein Pterodactyl-Server oder ein DirectAdmin-Hostingkonto liegt. Die Unterschiede wohnen im Provider, nicht in Ihrem Integrationscode.