451 lines
14 KiB
Markdown
451 lines
14 KiB
Markdown
# KeyHelp Manager - WHMCS Provisioning Modul
|
|
|
|
Ein professionelles WHMCS-Provisioning-Modul für die automatische Verwaltung von KeyHelp-Webhosting-Accounts.
|
|
|
|
**Entwickelt von:** Kevin Feiler / AVVGO
|
|
**Website:** https://avvgo.de
|
|
**Version:** 2.0.0
|
|
|
|
## 🆕 NEU in Version 2.0.0
|
|
|
|
- 🎯 **Zentralisierte Server-Konfiguration** - API-Keys nur einmal in WHMCS Server-Einstellungen eintragen
|
|
- 📋 **Template/Vorlagen-System** - Automatische Synchronisation von KeyHelp-Plänen als Dropdown
|
|
- 🚀 **Template-basierte Provisionierung** - Domains werden automatisch mit gewählter Vorlage erstellt
|
|
- 🔗 **Admin-Panel-Link** - Direkter Zugriff zur Domain-Verwaltung im KeyHelp-Panel
|
|
- 📊 **Template-Anzeige** - Kunden sehen ihr verwendetes Template im Client Area
|
|
|
|
**[→ Update-Anleitung von v1.x auf v2.0](UPDATE.md)**
|
|
|
|
## 📋 Inhaltsverzeichnis
|
|
|
|
- [Features](#features)
|
|
- [Systemanforderungen](#systemanforderungen)
|
|
- [Installation](#installation)
|
|
- [Konfiguration](#konfiguration)
|
|
- [Verwendung](#verwendung)
|
|
- [API-Endpunkte](#api-endpunkte)
|
|
- [Fehlerbehebung](#fehlerbehebung)
|
|
- [Support](#support)
|
|
|
|
## ✨ Features
|
|
|
|
### Core Features
|
|
- ✅ **Automatische Account-Erstellung** - Erstellt KeyHelp-Accounts direkt nach der Bezahlung
|
|
- ✅ **Account-Verwaltung** - Sperren, Entsperren und Löschen von Accounts
|
|
- ✅ **Passwort-Management** - Sichere Passwortverwaltung und -änderung
|
|
- ✅ **Client-Area-Integration** - Übersichtliche Darstellung von Login-Daten und Statistiken
|
|
- ✅ **Single Sign-On** - Ein-Klick-Login für Admins direkt in den Kundenaccount
|
|
- ✅ **Live-Statistiken** - Echtzeit-Anzeige von Speicherplatz, Traffic, Domains, etc.
|
|
- ✅ **SSL-Unterstützung** - Sichere HTTPS-Verbindungen zur KeyHelp-API
|
|
- ✅ **Detailliertes Logging** - Alle API-Calls werden in WHMCS protokolliert
|
|
- ✅ **Fehlerbehandlung** - Robuste Error-Handling-Mechanismen
|
|
|
|
### Neue Features v2.0
|
|
- 🎯 **Zentralisierte API-Konfiguration** - API-Keys werden nur einmal in WHMCS Server-Einstellungen eingegeben
|
|
- 📋 **Template-Synchronisation** - KeyHelp-Pläne/Vorlagen werden automatisch als Dropdown geladen
|
|
- 🔄 **Sync Templates Button** - Manuelles Aktualisieren der verfügbaren Templates
|
|
- 🏷️ **Template-basierte Erstellung** - Accounts werden mit gewähltem Template/Plan erstellt
|
|
- 🔗 **Admin-Panel-Link** - Direkter Link zur Domain-Verwaltung im KeyHelp-Panel
|
|
- 📊 **Template-Anzeige** - Template-Name wird im Client Area angezeigt
|
|
- ⚡ **Template-Cache** - Bessere Performance durch 5-Minuten-Cache
|
|
- 🎨 **Verbessertes UI** - Übersichtlichere Button-Anordnung und Design
|
|
|
|
## 🔧 Systemanforderungen
|
|
|
|
### WHMCS-Server
|
|
- **WHMCS:** Version 8.13 oder höher
|
|
- **PHP:** Version 8.3 oder höher
|
|
- **Guzzle HTTP Client:** Wird von WHMCS mitgeliefert
|
|
- **MySQL/MariaDB:** Von WHMCS unterstützte Version
|
|
|
|
### KeyHelp-Server
|
|
- **KeyHelp:** Neueste stabile Version (mit API v2)
|
|
- **API-Zugang:** API-Key mit Admin-Rechten
|
|
- **SSL-Zertifikat:** Empfohlen für sichere API-Kommunikation
|
|
|
|
## 📦 Installation
|
|
|
|
### Schritt 1: Dateien hochladen
|
|
|
|
1. Laden Sie das komplette `keyhelpmanager`-Verzeichnis in Ihr WHMCS-Installationsverzeichnis hoch:
|
|
|
|
```
|
|
/pfad/zu/whmcs/modules/servers/keyhelpmanager/
|
|
```
|
|
|
|
Die Verzeichnisstruktur sollte wie folgt aussehen:
|
|
|
|
```
|
|
whmcs/
|
|
└── modules/
|
|
└── servers/
|
|
└── keyhelpmanager/
|
|
├── keyhelpmanager.php
|
|
└── templates/
|
|
└── clientarea.tpl
|
|
```
|
|
|
|
### Schritt 2: Dateirechte setzen
|
|
|
|
Stellen Sie sicher, dass die Dateien die korrekten Rechte haben:
|
|
|
|
```bash
|
|
chmod 644 modules/servers/keyhelpmanager/keyhelpmanager.php
|
|
chmod 644 modules/servers/keyhelpmanager/templates/clientarea.tpl
|
|
chmod 755 modules/servers/keyhelpmanager/
|
|
```
|
|
|
|
### Schritt 3: KeyHelp API-Key generieren
|
|
|
|
1. Loggen Sie sich in Ihr KeyHelp-Panel ein
|
|
2. Navigieren Sie zu **Einstellungen → API**
|
|
3. Erstellen Sie einen neuen API-Key mit **Admin-Rechten**
|
|
4. Kopieren Sie den generierten API-Key (wird nur einmal angezeigt!)
|
|
|
|
### Schritt 4: Server in WHMCS hinzufügen
|
|
|
|
1. Loggen Sie sich in den WHMCS-Admin-Bereich ein
|
|
2. Navigieren Sie zu **Setup → Products/Services → Servers**
|
|
3. Klicken Sie auf **Add New Server**
|
|
4. Füllen Sie die Felder aus:
|
|
- **Name:** z.B. "KeyHelp Server 1"
|
|
- **Hostname:** IP-Adresse oder FQDN Ihres KeyHelp-Servers (ohne http://)
|
|
- **Type:** Wählen Sie **KeyHelp Manager**
|
|
- **Username:** Kann leer bleiben
|
|
- **Password:** Tragen Sie hier Ihren **API-Key** ein
|
|
- **Accesshash:** Kann leer bleiben
|
|
- **Secure:** Aktivieren Sie dies, wenn Sie SSL verwenden
|
|
|
|
5. Klicken Sie auf **Test Connection** um die Verbindung zu prüfen
|
|
6. Speichern Sie die Konfiguration
|
|
|
|
### Schritt 5: Produkt/Service erstellen
|
|
|
|
1. Navigieren Sie zu **Setup → Products/Services → Products/Services**
|
|
2. Erstellen Sie ein neues Produkt oder bearbeiten Sie ein bestehendes
|
|
3. Im Tab **Module Settings**:
|
|
- **Module Name:** Wählen Sie **KeyHelp Manager**
|
|
- **Server:** Wählen Sie Ihren KeyHelp-Server
|
|
- Konfigurieren Sie die Modul-Einstellungen (siehe unten)
|
|
|
|
4. Speichern Sie das Produkt
|
|
|
|
## ⚙️ Konfiguration
|
|
|
|
### Server-Konfigurationsoptionen
|
|
|
|
Bei der Einrichtung des Servers in WHMCS können Sie folgende Optionen konfigurieren:
|
|
|
|
| Option | Typ | Beschreibung | Standard |
|
|
|--------|-----|--------------|----------|
|
|
| **Hostname (IP or FQDN)** | Text | Hostname oder IP-Adresse des KeyHelp-Servers | - |
|
|
| **API Key** | Password | Ihr KeyHelp API-Schlüssel | - |
|
|
| **Use SSL** | Yes/No | SSL für API-Verbindungen verwenden | On |
|
|
| **HTTP Prefix** | Text | Optional: "no-verify" für manuelles Deaktivieren der SSL-Verifizierung | - |
|
|
|
|
> **Hinweis zur SSL-Verifizierung:**
|
|
> - Bei Verwendung einer **IP-Adresse** wird die SSL-Verifizierung automatisch deaktiviert
|
|
> - Bei selbstsignierten SSL-Zertifikaten mit Domain-Namen: Tragen Sie "no-verify" im Feld "HTTP Prefix" ein
|
|
> - Für Produktivumgebungen wird immer ein gültiges SSL-Zertifikat empfohlen
|
|
|
|
### Produkt-Konfiguration
|
|
|
|
#### Automatische Werte
|
|
|
|
Das Modul verwendet automatisch folgende Werte aus WHMCS:
|
|
|
|
- **Domain:** Die vom Kunden gewählte Domain
|
|
- **Username:** Automatisch generiert aus der Domain (oder manuell festgelegt)
|
|
- **Password:** Automatisch generiert (sicheres 16-stelliges Passwort)
|
|
- **E-Mail:** Aus den Kundendaten
|
|
|
|
#### Konfigurierbare Optionen (Optional)
|
|
|
|
Sie können zusätzliche konfigurierbare Optionen für KeyHelp-Pläne erstellen:
|
|
|
|
1. Navigieren Sie zu **Setup → Products/Services → Configurable Options**
|
|
2. Erstellen Sie eine neue Konfigurationsgruppe
|
|
3. Fügen Sie eine Option hinzu:
|
|
- **Option Name:** "KeyHelp Plan"
|
|
- **Option Type:** Dropdown/Radio
|
|
- **Options:** Liste Ihrer KeyHelp-Pläne (z.B. "Basic", "Professional", "Enterprise")
|
|
|
|
4. Verknüpfen Sie die Konfigurationsgruppe mit Ihrem Produkt
|
|
|
|
### Custom Fields (Automatisch erstellt)
|
|
|
|
Das Modul erstellt automatisch folgendes Custom Field:
|
|
|
|
- **KeyHelp User ID** - Speichert die interne KeyHelp-User-ID (Admin-only)
|
|
|
|
## 🚀 Verwendung
|
|
|
|
### Für Kunden (Client Area)
|
|
|
|
Nachdem ein Kunde das Produkt bestellt und bezahlt hat:
|
|
|
|
1. Der Account wird automatisch in KeyHelp erstellt
|
|
2. Im **Services**-Bereich sieht der Kunde:
|
|
- KeyHelp Login-URL
|
|
- Benutzername und Passwort (mit Copy-Funktion)
|
|
- Domain-Name
|
|
- Live-Statistiken (Speicherplatz, Traffic, Anzahl Domains/DBs/E-Mails)
|
|
- "Jetzt zu KeyHelp einloggen"-Button
|
|
|
|
### Für Admins
|
|
|
|
Im WHMCS-Admin-Bereich haben Sie folgende Optionen:
|
|
|
|
#### Account-Verwaltung
|
|
|
|
- **Create** - Erstellt einen neuen KeyHelp-Account
|
|
- **Suspend** - Sperrt den Account (bei Zahlungsverzug)
|
|
- **Unsuspend** - Entsperrt einen gesperrten Account
|
|
- **Terminate** - Löscht den Account unwiderruflich
|
|
- **Change Password** - Ändert das Account-Passwort
|
|
|
|
#### Single Sign-On
|
|
|
|
Klicken Sie auf den "Login zu KeyHelp"-Button neben dem Service, um sich direkt als der jeweilige Kunde in KeyHelp einzuloggen (ohne Passwort).
|
|
|
|
## 🔌 API-Endpunkte
|
|
|
|
Das Modul verwendet folgende KeyHelp API v2 Endpunkte:
|
|
|
|
### Benutzer-Verwaltung
|
|
|
|
- `POST /api/v2/users` - Benutzer erstellen
|
|
- `GET /api/v2/users/{id}` - Benutzer-Details abrufen
|
|
- `PUT /api/v2/users/{id}` - Benutzer aktualisieren (Passwort, Status)
|
|
- `DELETE /api/v2/users/{id}` - Benutzer löschen
|
|
|
|
### Domain-Verwaltung
|
|
|
|
- `POST /api/v2/domains` - Domain hinzufügen
|
|
- `GET /api/v2/domains/{id}` - Domain-Details abrufen
|
|
|
|
### Statistiken
|
|
|
|
- `GET /api/v2/users/{id}/statistics` - Account-Statistiken abrufen
|
|
|
|
### Sessions (SSO)
|
|
|
|
- `POST /api/v2/sessions` - Login-Session erstellen
|
|
|
|
### Server-Informationen
|
|
|
|
- `GET /api/v2/server/version` - Server-Version abrufen (für Connection-Test)
|
|
|
|
## 🔍 Funktionsweise
|
|
|
|
### Account-Erstellung
|
|
|
|
```
|
|
Kunde bestellt → WHMCS aktiviert Service → keyhelpmanager_CreateAccount()
|
|
↓
|
|
1. Validiere Parameter (Domain, Username, etc.)
|
|
2. Generiere sicheres Passwort falls nicht vorhanden
|
|
3. API-Call: POST /users (Benutzer erstellen)
|
|
4. API-Call: POST /domains (Domain hinzufügen)
|
|
5. Speichere Credentials in WHMCS-Datenbank
|
|
6. Return "success"
|
|
↓
|
|
Kunde erhält Zugriff auf Service mit Login-Daten
|
|
```
|
|
|
|
### Account-Sperrung
|
|
|
|
```
|
|
Admin sperrt Account → keyhelpmanager_SuspendAccount()
|
|
↓
|
|
1. Hole User-ID aus WHMCS-Datenbank
|
|
2. API-Call: PUT /users/{id} mit {"is_locked": true}
|
|
3. Return "success"
|
|
↓
|
|
Kunde kann sich nicht mehr in KeyHelp einloggen
|
|
```
|
|
|
|
### Client Area
|
|
|
|
```
|
|
Kunde öffnet Service → keyhelpmanager_ClientArea()
|
|
↓
|
|
1. Lade Account-Details aus WHMCS-Datenbank
|
|
2. API-Call: GET /users/{id}/statistics (Live-Daten)
|
|
3. Formatiere Daten (Bytes → MB/GB, Prozentangaben)
|
|
4. Return Template-Variablen
|
|
↓
|
|
Smarty-Template rendert die Anzeige
|
|
```
|
|
|
|
### Single Sign-On
|
|
|
|
```
|
|
Admin klickt auf "Login" → keyhelpmanager_LoginLink()
|
|
↓
|
|
1. Hole User-ID aus WHMCS-Datenbank
|
|
2. API-Call: POST /sessions mit User-ID
|
|
3. Erhalte Session-Token
|
|
4. Erstelle Login-URL mit Token
|
|
5. Return Redirect-URL
|
|
↓
|
|
Admin wird direkt in KeyHelp eingeloggt
|
|
```
|
|
|
|
## 🐛 Fehlerbehebung
|
|
|
|
### "KeyHelp-Hostname ist nicht konfiguriert"
|
|
|
|
**Lösung:** Stellen Sie sicher, dass Sie den Hostname/IP in der Server-Konfiguration eingetragen haben (ohne `http://` oder `https://`).
|
|
|
|
### "KeyHelp API-Schlüssel ist nicht konfiguriert"
|
|
|
|
**Lösung:**
|
|
1. Generieren Sie einen neuen API-Key in KeyHelp
|
|
2. Tragen Sie ihn im **Password**-Feld der Server-Konfiguration ein
|
|
|
|
### "Verbindung zum KeyHelp-Server fehlgeschlagen"
|
|
|
|
**Mögliche Ursachen:**
|
|
- Firewall blockiert Verbindung
|
|
- Falscher Hostname/IP
|
|
- KeyHelp-Server ist nicht erreichbar
|
|
- SSL-Zertifikat-Problem bei selbstsigniertem Zertifikat
|
|
|
|
**Lösung:**
|
|
1. Prüfen Sie die Firewall-Einstellungen
|
|
2. Testen Sie die Verbindung manuell: `curl -k https://ihr-server.de/api/v2/server/version -H "X-API-Key: IHR_KEY"`
|
|
3. Bei selbstsigniertem Zertifikat: Tragen Sie "no-verify" im Feld "HTTP Prefix" ein
|
|
|
|
### "cURL error 60: SSL certificate problem"
|
|
|
|
**Ursache:** SSL-Zertifikat stimmt nicht mit dem Hostnamen überein (häufig bei IP-Adressen oder selbstsignierten Zertifikaten)
|
|
|
|
**Lösung:**
|
|
1. **Bei IP-Adresse:** Das Modul deaktiviert die SSL-Verifizierung automatisch
|
|
2. **Bei selbstsigniertem Zertifikat mit Domain:** Tragen Sie "no-verify" im Feld "HTTP Prefix" der Server-Konfiguration ein
|
|
3. **Empfohlen für Produktion:** Verwenden Sie ein gültiges SSL-Zertifikat von Let's Encrypt oder einem anderen CA
|
|
|
|
### "Domain konnte nicht hinzugefügt werden"
|
|
|
|
**Mögliche Ursachen:**
|
|
- Domain existiert bereits in KeyHelp
|
|
- Ungültiges Domain-Format
|
|
- DNS-Probleme
|
|
|
|
**Lösung:**
|
|
1. Prüfen Sie, ob die Domain bereits in KeyHelp existiert
|
|
2. Validieren Sie das Domain-Format (keine Leerzeichen, gültige TLD)
|
|
|
|
### "Benutzer-ID nicht gefunden"
|
|
|
|
**Ursache:** Der Account wurde nicht korrekt erstellt oder die Custom Fields fehlen.
|
|
|
|
**Lösung:**
|
|
1. Prüfen Sie das WHMCS Module Log: **Utilities → Logs → Module Log**
|
|
2. Erstellen Sie den Account manuell neu
|
|
3. Stellen Sie sicher, dass das Custom Field "KeyHelp User ID" existiert
|
|
|
|
### Logs prüfen
|
|
|
|
WHMCS protokolliert alle API-Calls:
|
|
|
|
1. Navigieren Sie zu **Utilities → Logs → Module Log**
|
|
2. Filtern Sie nach "keyhelpmanager"
|
|
3. Prüfen Sie Request und Response für Details
|
|
|
|
## 📊 Logging
|
|
|
|
Das Modul nutzt die integrierte WHMCS `logModuleCall()`-Funktion:
|
|
|
|
- **Modul-Name:** keyhelpmanager
|
|
- **Protokolliert:** Alle API-Requests und Responses
|
|
- **Maskiert:** API-Keys werden automatisch maskiert
|
|
- **Speicherort:** WHMCS → Utilities → Logs → Module Log
|
|
|
|
## 🔒 Sicherheit
|
|
|
|
### Best Practices
|
|
|
|
1. **Verwenden Sie immer SSL** für API-Verbindungen
|
|
2. **API-Key-Schutz:**
|
|
- Teilen Sie Ihren API-Key niemals mit Dritten
|
|
- Speichern Sie ihn nur im WHMCS-Server-Passwort-Feld
|
|
- WHMCS verschlüsselt dieses Feld automatisch
|
|
3. **Regelmäßige Updates:** Halten Sie WHMCS und KeyHelp auf dem neuesten Stand
|
|
4. **Firewall:** Beschränken Sie den API-Zugriff auf die IP Ihres WHMCS-Servers
|
|
5. **2FA:** Aktivieren Sie Zwei-Faktor-Authentifizierung für KeyHelp-Admin-Accounts
|
|
|
|
### Passwort-Generierung
|
|
|
|
Das Modul generiert sichere Passwörter:
|
|
- **Länge:** 16 Zeichen
|
|
- **Zeichensatz:** a-z, A-Z, 0-9, Sonderzeichen
|
|
- **Methode:** `random_int()` (kryptografisch sicher)
|
|
|
|
## 🆘 Support
|
|
|
|
### Dokumentation
|
|
|
|
- **KeyHelp Dokumentation:** https://www.keyhelp.de/dokumentation
|
|
- **WHMCS Developer Docs:** https://developers.whmcs.com/
|
|
|
|
### Debugging
|
|
|
|
Bei Problemen:
|
|
|
|
1. Aktivieren Sie das Debug-Logging in WHMCS
|
|
2. Prüfen Sie die Module Logs
|
|
3. Testen Sie die API-Verbindung manuell
|
|
4. Prüfen Sie die PHP-Error-Logs
|
|
|
|
### Community
|
|
|
|
- **KeyHelp Forum:** https://forum.keyhelp.de/
|
|
- **WHMCS Community:** https://whmcs.community/
|
|
|
|
## 📝 Changelog
|
|
|
|
### Version 1.0.0 (Initial Release)
|
|
|
|
- ✅ Basis-Funktionalität: Create, Suspend, Unsuspend, Terminate
|
|
- ✅ Client Area mit Login-Details und Statistiken
|
|
- ✅ Admin Single Sign-On
|
|
- ✅ Passwort-Management
|
|
- ✅ SSL-Unterstützung
|
|
- ✅ Umfassendes Error-Handling
|
|
- ✅ Smarty-Template für Client Area
|
|
- ✅ API v2 Unterstützung
|
|
|
|
## 👨💻 Entwickler
|
|
|
|
Dieses Modul wurde entwickelt von:
|
|
|
|
- **Name:** Kevin Feiler
|
|
- **Firma:** AVVGO
|
|
- **Website:** https://avvgo.de
|
|
- **E-Mail:** info@avvgo.de
|
|
|
|
## 📜 Lizenz
|
|
|
|
MIT License - Copyright (c) 2024 Kevin Feiler / AVVGO
|
|
|
|
Siehe LICENSE-Datei für vollständige Details.
|
|
|
|
## 🔧 Technische Anforderungen
|
|
|
|
- **PHP:** 8.3+
|
|
- **WHMCS:** 8.13+
|
|
- **KeyHelp:** Neueste stabile Version mit API v2
|
|
|
|
## 💬 Support & Kontakt
|
|
|
|
Bei Fragen, Problemen oder Feature-Wünschen:
|
|
|
|
- **E-Mail:** info@avvgo.de
|
|
- **Website:** https://avvgo.de
|
|
- **GitHub Issues:** Für Bug-Reports und Feature-Requests
|
|
|
|
---
|
|
|
|
**Hinweis:** Dieses Modul wurde mit Fokus auf Stabilität, Sicherheit und Benutzerfreundlichkeit entwickelt von Kevin Feiler / AVVGO. |