feat: Initial commit of KeyHelp Manager module

This commit is contained in:
Kevin Feiler
2025-10-15 22:29:11 +02:00
parent 4df2eddc6a
commit 351da5fe19
8 changed files with 2584 additions and 0 deletions

631
INSTALLATION.md Normal file
View File

@@ -0,0 +1,631 @@
# KeyHelp Manager - Detaillierte Installationsanleitung
Diese Anleitung führt Sie Schritt für Schritt durch die Installation und Konfiguration des KeyHelp Manager WHMCS-Moduls.
## 📋 Voraussetzungen prüfen
Bevor Sie mit der Installation beginnen, stellen Sie sicher, dass folgende Anforderungen erfüllt sind:
### WHMCS-System
- [ ] WHMCS Version 8.13 oder höher installiert
- [ ] PHP Version 8.3 oder höher
- [ ] Guzzle HTTP Client verfügbar (normalerweise in WHMCS integriert)
- [ ] MySQL/MariaDB Datenbank
- [ ] SSL-Zertifikat für WHMCS (empfohlen)
- [ ] Admin-Zugriff auf WHMCS
### KeyHelp-Server
- [ ] KeyHelp installiert und erreichbar
- [ ] KeyHelp API v2 aktiviert
- [ ] Admin-Zugang zu KeyHelp
- [ ] SSL-Zertifikat für KeyHelp (empfohlen)
- [ ] Firewall-Regeln erlauben Zugriff von WHMCS-Server
### Netzwerk
- [ ] WHMCS-Server kann KeyHelp-Server über HTTP/HTTPS erreichen
- [ ] Port 80/443 ist offen (je nach Konfiguration)
- [ ] DNS-Auflösung funktioniert korrekt
## 🚀 Schritt 1: KeyHelp API vorbereiten
### 1.1 API-Key in KeyHelp erstellen
1. Loggen Sie sich als Administrator in Ihr KeyHelp-Panel ein:
```
https://ihr-keyhelp-server.de
```
2. Navigieren Sie zu **Einstellungen** (Zahnrad-Symbol oben rechts)
3. Klicken Sie auf **API** im linken Menü
4. Klicken Sie auf **Neuen API-Schlüssel erstellen**
5. Konfigurieren Sie den API-Key:
- **Name:** `WHMCS Provisioning`
- **Berechtigungen:** Wählen Sie **Administrator** oder erteilen Sie folgende spezifische Rechte:
- Benutzer erstellen/bearbeiten/löschen
- Domains erstellen/bearbeiten/löschen
- Statistiken abrufen
- Sessions erstellen
- **IP-Whitelist:** (Optional aber empfohlen) Tragen Sie die IP-Adresse Ihres WHMCS-Servers ein
6. Klicken Sie auf **Erstellen**
7. **WICHTIG:** Kopieren Sie den generierten API-Key sofort und speichern Sie ihn sicher!
```
Beispiel: kh_live_1234567890abcdefghijklmnopqrstuvwxyz
```
⚠️ **Der Key wird nur einmal angezeigt!**
### 1.2 API testen (Optional)
Testen Sie den API-Zugriff vom WHMCS-Server aus:
```bash
# Mit SSL (empfohlen)
curl -X GET "https://ihr-keyhelp-server.de/api/v2/server/version" \
-H "X-API-Key: IHR_API_KEY" \
-H "Accept: application/json"
# Ohne SSL (nur für Tests)
curl -X GET "http://ihr-keyhelp-server.de/api/v2/server/version" \
-H "X-API-Key: IHR_API_KEY" \
-H "Accept: application/json"
```
Erwartete Antwort:
```json
{
"version": "24.1.0",
"api_version": "2.0"
}
```
## 🔧 Schritt 2: Modul-Dateien installieren
### 2.1 Dateien hochladen
#### Option A: Via FTP/SFTP
1. Verbinden Sie sich mit Ihrem WHMCS-Server via FTP/SFTP
2. Navigieren Sie zum WHMCS-Installationsverzeichnis:
```
/var/www/whmcs/
```
3. Laden Sie das komplette `keyhelpmanager`-Verzeichnis in folgenden Pfad hoch:
```
/var/www/whmcs/modules/servers/keyhelpmanager/
```
4. Stellen Sie sicher, dass folgende Struktur existiert:
```
modules/
└── servers/
└── keyhelpmanager/
├── keyhelpmanager.php
└── templates/
└── clientarea.tpl
```
#### Option B: Via SSH
```bash
# Zum WHMCS-Verzeichnis navigieren
cd /var/www/whmcs/modules/servers/
# Repository klonen (falls Git verwendet wird)
git clone https://github.com/ihr-repo/keyhelpmanager.git
# Oder Dateien aus ZIP extrahieren
unzip keyhelpmanager.zip
# Dateien verschieben falls nötig
mv keyhelpmanager-main keyhelpmanager
```
### 2.2 Dateirechte setzen
Setzen Sie die korrekten Berechtigungen:
```bash
# Zum Modul-Verzeichnis
cd /var/www/whmcs/modules/servers/keyhelpmanager/
# Dateien: 644 (rw-r--r--)
find . -type f -exec chmod 644 {} \;
# Verzeichnisse: 755 (rwxr-xr-x)
find . -type d -exec chmod 755 {} \;
# Owner setzen (Apache/Nginx User)
chown -R www-data:www-data .
# Oder für andere Systeme
chown -R apache:apache .
chown -R nginx:nginx .
```
### 2.3 Installation verifizieren
Prüfen Sie, ob die Dateien korrekt hochgeladen wurden:
```bash
ls -la /var/www/whmcs/modules/servers/keyhelpmanager/
```
Erwartete Ausgabe:
```
drwxr-xr-x 3 www-data www-data 4096 Jan 15 10:00 .
drwxr-xr-x 8 www-data www-data 4096 Jan 15 09:55 ..
-rw-r--r-- 1 www-data www-data xxxxx Jan 15 10:00 keyhelpmanager.php
drwxr-xr-x 2 www-data www-data 4096 Jan 15 10:00 templates
```
## ⚙️ Schritt 3: Server in WHMCS konfigurieren
### 3.1 Server hinzufügen
1. Loggen Sie sich in den **WHMCS Admin-Bereich** ein:
```
https://ihr-whmcs.de/admin/
```
2. Navigieren Sie zu:
```
Setup → Products/Services → Servers
```
3. Klicken Sie auf **Add New Server**
### 3.2 Server-Details eintragen
Füllen Sie das Formular aus:
#### Tab: Details
| Feld | Wert | Beschreibung |
|------|------|--------------|
| **Name** | `KeyHelp Server 1` | Interner Name (frei wählbar) |
| **Hostname** | `keyhelp.ihredomain.de` | Hostname ODER IP-Adresse **OHNE** `http://` oder `https://` |
| **IP Address** | `123.45.67.89` | IP-Adresse (optional, falls Hostname verwendet wird) |
| **Type** | `KeyHelp Manager` | Wählen Sie aus dem Dropdown |
| **Username** | _(leer lassen)_ | Nicht benötigt |
| **Password** | `kh_live_123...` | **IHR KEYHELP API-KEY** |
| **Accesshash** | _(leer lassen)_ | Nicht benötigt |
#### Checkboxes
- ✅ **Active** - Server ist aktiv
- ✅ **Secure** - Verwenden Sie SSL (HTTPS) für die Verbindung
- ⬜ **Disable Accounts Automatically** - (optional)
#### Tab: Module Settings
Wenn verfügbar, konfigurieren Sie hier:
| Option | Empfohlener Wert | Beschreibung |
|--------|------------------|--------------|
| **Use SSL** | ✅ On | SSL für API-Verbindung verwenden |
| **Verify SSL Certificate** | ✅ On | SSL-Zertifikat prüfen (bei selbstsigniert: Off) |
### 3.3 Verbindung testen
1. Klicken Sie auf **Test Connection**
2. Erwartete Meldung:
```
✅ Verbindung erfolgreich! KeyHelp Version: 24.1.0
```
3. Bei Fehlermeldungen siehe [Fehlerbehebung](#fehlerbehebung)
4. Klicken Sie auf **Save Changes**
## 📦 Schritt 4: Produkt/Service erstellen
### 4.1 Neues Produkt anlegen
1. Navigieren Sie zu:
```
Setup → Products/Services → Products/Services
```
2. Klicken Sie auf **Create a New Group** (falls noch keine Gruppe existiert):
- **Name:** `Webhosting`
- **Description:** `KeyHelp Webhosting Pakete`
3. Klicken Sie auf **Create a New Product**
### 4.2 Produkt-Details
#### Tab: Details
| Feld | Beispielwert |
|------|--------------|
| **Product Type** | `Hosting Account` |
| **Product Group** | `Webhosting` |
| **Product Name** | `Basic Webhosting` |
| **Description** | Beschreibung des Pakets |
| **Welcome Email** | `Hosting Account Welcome Email` |
#### Tab: Pricing
Konfigurieren Sie Ihre Preise:
- **Currency:** EUR
- **Payment Type:** Recurring
- **Monthly:** 5.00 EUR
- **Quarterly:** 13.50 EUR
- **Semi-Annually:** 27.00 EUR
- **Annually:** 50.00 EUR
#### Tab: Module Settings
**WICHTIG:** Dies ist der entscheidende Teil!
| Feld | Wert | Beschreibung |
|------|------|--------------|
| **Module Name** | `KeyHelp Manager` | Wählen Sie aus dem Dropdown |
| **Server Group** | `Default` | Oder wählen Sie Ihre Server-Gruppe |
| **Username** | `Domain` | Automatisch aus Domain generieren |
| **Password** | `Generate` | Automatisch generieren |
**Konfigurationsoptionen:**
1. **Hostname (IP or FQDN)**
- Type: Dropdown
- Options: Wählen Sie Ihren KeyHelp-Server
2. **API Key**
- Wird automatisch vom Server übernommen
3. **Use SSL**
- Default: On
**Aktivierte Funktionen:** (Checkboxes)
- ✅ Create Account
- ✅ Suspend Account
- ✅ Unsuspend Account
- ✅ Terminate Account
- ✅ Change Password
- ✅ Login Link (Single Sign-On)
### 4.3 Konfigurierbare Optionen (Optional)
#### KeyHelp-Pläne als Dropdown
1. Navigieren Sie zu:
```
Setup → Products/Services → Configurable Options
```
2. Klicken Sie auf **Create a New Group**:
- **Group Name:** `KeyHelp Optionen`
3. Klicken Sie auf **Add New Configurable Option**:
- **Option Name:** `KeyHelp Plan`
- **Option Type:** `Dropdown`
- **Options:**
```
Basic|basic
Professional|professional
Enterprise|enterprise
```
4. Verknüpfen Sie die Gruppe mit Ihrem Produkt:
- Products/Services → Ihr Produkt → Configurable Options
- Wählen Sie `KeyHelp Optionen`
### 4.4 Custom Fields anlegen (Optional aber empfohlen)
Diese Felder werden zwar automatisch erstellt, können aber manuell vorbereitet werden:
1. Navigieren Sie zu:
```
Setup → Custom Fields
```
2. Wählen Sie **Products/Services** und Ihr Produkt
3. Klicken Sie auf **Add New Custom Field**:
- **Field Name:** `KeyHelp User ID`
- **Field Type:** `Text Box`
- **Description:** `Interne KeyHelp Benutzer-ID`
- ✅ **Admin Only**
- Sortierung: `1`
## ✅ Schritt 5: Testen der Installation
### 5.1 Test-Bestellung durchführen
1. Öffnen Sie Ihr WHMCS Frontend als Kunde (im Inkognito-Modus):
```
https://ihr-whmcs.de/
```
2. Navigieren Sie zu **Order → Hosting**
3. Wählen Sie Ihr neues Produkt
4. Geben Sie eine Test-Domain ein:
```
test123.de
```
5. Schließen Sie die Bestellung ab (nutzen Sie ein Test-Gateway oder manuelle Zahlung)
### 5.2 Account-Erstellung prüfen
1. Als Admin: Navigieren Sie zu **Clients → View/Search Clients**
2. Öffnen Sie den Test-Kunden
3. Klicken Sie auf das neue Service/Produkt
4. Im Tab **Information** sollten Sie sehen:
- ✅ Username: automatisch generiert
- ✅ Password: automatisch generiert
- ✅ Status: Active
5. Prüfen Sie die **Module Commands**:
- Buttons sollten verfügbar sein: Suspend, Unsuspend, Terminate, Change Password
### 5.3 Client Area testen
1. Loggen Sie sich als Test-Kunde ein
2. Navigieren Sie zu **Services → My Services**
3. Klicken Sie auf das neue Hosting-Paket
4. Sie sollten sehen:
- ✅ KeyHelp Login-URL (klickbar)
- ✅ Benutzername (mit Copy-Button)
- ✅ Passwort (mit Show/Hide und Copy-Button)
- ✅ Domain-Name
- ✅ Statistiken (wenn Account erstellt wurde):
- Speicherplatz-Fortschrittsbalken
- Traffic-Fortschrittsbalken
- Anzahl Domains/Datenbanken/E-Mail-Konten
### 5.4 In KeyHelp prüfen
1. Loggen Sie sich in Ihr KeyHelp-Panel ein
2. Navigieren Sie zu **Benutzer**
3. Sie sollten den neu erstellten Benutzer sehen:
- Username wie in WHMCS
- Domain zugewiesen
- Status: Aktiv
### 5.5 Single Sign-On testen
1. Als Admin in WHMCS: Öffnen Sie das Test-Service
2. Klicken Sie auf **Login to KeyHelp** (oder ähnlicher Button)
3. Sie sollten automatisch in KeyHelp eingeloggt werden:
- Als der jeweilige Benutzer
- Ohne Passwort-Eingabe
## 🔧 Schritt 6: Produktiv-Konfiguration
### 6.1 Mehrere Server einrichten
Falls Sie mehrere KeyHelp-Server haben:
1. Wiederholen Sie Schritt 3 für jeden Server
2. Erstellen Sie eine **Server Group**:
```
Setup → Products/Services → Servers → Server Groups
```
3. Fügen Sie alle KeyHelp-Server zur Gruppe hinzu
4. Konfigurieren Sie Ihre Produkte, um die Server-Gruppe zu nutzen:
- Automatische Lastverteilung
- Failover-Funktion
### 6.2 Automatisierung einrichten
#### A) Automatische Provisioning
In WHMCS: **Setup → Automation Settings**
- ✅ Enable Automatic Provisioning
- ✅ Process After: Payment Cleared
- Stellen Sie sicher, dass Cron-Jobs aktiv sind
#### B) Automatische Sperrung
- ✅ Enable Automatic Suspension
- Days Past Due Before Suspension: `7`
#### C) Automatische Kündigung
- ✅ Enable Automatic Termination
- Days Past Due Before Termination: `30`
### 6.3 E-Mail-Templates anpassen
Passen Sie die E-Mail-Templates an:
1. **Setup → Email Templates**
2. Suchen Sie nach:
- `Hosting Account Welcome Email`
3. Fügen Sie KeyHelp-spezifische Variablen hinzu:
```
KeyHelp Login: https://{$service_server_hostname}
Benutzername: {$service_username}
Passwort: {$service_password}
Domain: {$service_domain}
```
### 6.4 Sicherheit härten
1. **IP-Whitelist in KeyHelp**:
- Beschränken Sie API-Zugriff auf WHMCS-Server-IP
2. **WHMCS Admin-IP-Whitelist**:
```
Setup → General Settings → Security
```
- Tragen Sie erlaubte Admin-IPs ein
3. **Zwei-Faktor-Authentifizierung**:
- Aktivieren Sie 2FA für alle Admin-Accounts (WHMCS und KeyHelp)
4. **SSL-Zertifikate**:
- Verwenden Sie gültige SSL-Zertifikate
- Keine selbstsignierten Zertifikate in Produktion
## 🐛 Fehlerbehebung
### Problem: "Module Not Found"
**Ursache:** Dateien nicht korrekt hochgeladen
**Lösung:**
```bash
# Prüfen Sie den Pfad
ls -la /var/www/whmcs/modules/servers/keyhelpmanager/keyhelpmanager.php
# Wenn nicht gefunden, Dateien neu hochladen
```
### Problem: "Connection Failed"
**Ursachen & Lösungen:**
1. **Firewall blockiert**:
```bash
# Auf WHMCS-Server testen
telnet keyhelp-server.de 443
```
2. **Falscher Hostname**:
- Verwenden Sie FQDN ODER IP
- OHNE `http://` oder `https://`
3. **SSL-Problem**:
- Bei selbstsigniertem Zertifikat: "Verify SSL" deaktivieren
4. **API-Key falsch**:
- Generieren Sie einen neuen Key in KeyHelp
- Kopieren Sie ihn exakt (keine Leerzeichen!)
### Problem: "Account Creation Failed"
**Debug-Schritte:**
1. Prüfen Sie Module Log:
```
Utilities → Logs → Module Log
Filter: keyhelpmanager
```
2. Prüfen Sie die API-Response in den Logs
3. Häufige Ursachen:
- Domain existiert bereits
- Ungültiger Username
- Unzureichende API-Berechtigungen
- KeyHelp-Lizenz-Limit erreicht
### Problem: "Statistics Not Showing"
**Ursache:** API-Endpunkt nicht erreichbar oder User-ID fehlt
**Lösung:**
```bash
# API manuell testen
curl -X GET "https://keyhelp-server.de/api/v2/users/123/statistics" \
-H "X-API-Key: IHR_KEY"
```
Prüfen Sie, ob `KeyHelp User ID` Custom Field existiert und gefüllt ist.
## 📊 Monitoring
### 6.5 Logging aktivieren
In WHMCS:
```
Setup → General Settings → Other
```
- ✅ Enable Module Debug Logging
Logs finden Sie unter:
```
Utilities → Logs → Module Log
```
### 6.6 Gesundheits-Check einrichten
Erstellen Sie ein Cron-Script für regelmäßige API-Tests:
```bash
#!/bin/bash
# /root/keyhelp-health-check.sh
KEYHELP_HOST="keyhelp.ihredomain.de"
API_KEY="ihr_api_key"
RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" \
"https://${KEYHELP_HOST}/api/v2/server/version" \
-H "X-API-Key: ${API_KEY}")
if [ "$RESPONSE" != "200" ]; then
echo "KeyHelp API nicht erreichbar! HTTP Status: $RESPONSE"
# Optional: Benachrichtigung senden
echo "KeyHelp API Down" | mail -s "ALERT: KeyHelp" admin@ihredomain.de
fi
```
Cron-Job:
```bash
# Alle 15 Minuten prüfen
*/15 * * * * /root/keyhelp-health-check.sh
```
## ✨ Fertig!
Herzlichen Glückwunsch! Ihr KeyHelp Manager WHMCS-Modul ist jetzt vollständig installiert und konfiguriert.
### Nächste Schritte
- [ ] Produktiv-Server konfigurieren
- [ ] Mehrere Hosting-Pakete anlegen
- [ ] Preise festlegen
- [ ] Marketing-Material vorbereiten
- [ ] Support-Team schulen
### Wichtige Hinweise
- 🔒 **Sicherheit:** Ändern Sie Ihre API-Keys regelmäßig
- 📝 **Backups:** Sichern Sie regelmäßig WHMCS und KeyHelp
- 🔄 **Updates:** Halten Sie alle Systeme aktuell
- 📞 **Support:** Dokumentieren Sie Ihre Konfiguration für Ihr Team
### Nützliche Links
- KeyHelp Dokumentation: https://www.keyhelp.de/dokumentation
- WHMCS Docs: https://docs.whmcs.com/
- KeyHelp Forum: https://forum.keyhelp.de/
---
**Bei Problemen oder Fragen:** Prüfen Sie die README.md und die Fehlerbehebungssektion. Für weitere Hilfe konsultieren Sie die Community-Foren.