diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md new file mode 100644 index 0000000..97d4ede --- /dev/null +++ b/TROUBLESHOOTING.md @@ -0,0 +1,508 @@ +# Troubleshooting Guide - KeyHelp Manager WHMCS Modul + +Dieser Guide hilft bei der Fehlersuche und Behebung häufiger Probleme mit dem KeyHelp Manager Modul. + +## 📋 Inhaltsverzeichnis + +- [Fehler beim Server hinzufügen](#fehler-beim-server-hinzufügen) +- [SSL-Zertifikat-Probleme](#ssl-zertifikat-probleme) +- [API-Endpunkt-Fehler](#api-endpunkt-fehler) +- [Account-Erstellung schlägt fehl](#account-erstellung-schlägt-fehl) +- [Client Area zeigt keine Daten](#client-area-zeigt-keine-daten) +- [Template-Probleme](#template-probleme) +- [Allgemeine Debugging-Tipps](#allgemeine-debugging-tipps) + +--- + +## Fehler beim Server hinzufügen + +### Problem: "Oops! Something went wrong" beim Öffnen der Server-Konfiguration + +**Symptom:** +``` +Oops! +Something went wrong and we couldn't process your request. +Please go back to the previous page and try again. +``` + +**Ursachen:** +1. PHP-Fehler beim Laden der ConfigOptions +2. Template-Loader versucht API-Call ohne vollständige Server-Daten +3. Fehlende oder ungültige Server-Einstellungen + +**Lösung:** + +1. **WHMCS Display Errors aktivieren:** + - Gehe zu: **Setup → General Settings → Other** + - Aktiviere: **Display Errors** + - Versuche erneut, die Server-Seite zu laden + - Notiere die genaue Fehlermeldung + +2. **PHP Error Log prüfen:** + ```bash + tail -f /var/log/php/error.log + # oder + tail -f /var/www/whmcs/storage/logs/laravel.log + ``` + +3. **Modul-Datei ersetzen:** + - Stelle sicher, dass du die neueste Version verwendest + - Die Datei muss die korrigierten Template-Loader-Funktionen enthalten + +4. **Temporärer Fix - Module deaktivieren:** + ```sql + -- In phpMyAdmin oder MySQL Console + UPDATE tblservers SET type = '' WHERE id = 10; + ``` + Dann kannst du die Seite öffnen und den Server neu konfigurieren. + +--- + +## SSL-Zertifikat-Probleme + +### Problem: "cURL error 60: SSL certificate problem" + +**Vollständige Fehlermeldung:** +``` +cURL error 60: SSL: no alternative certificate subject name matches target host name '5.83.148.129' +``` + +**Ursache:** +SSL-Zertifikat wurde für einen Domain-Namen ausgestellt, aber du verwendest eine IP-Adresse. + +**Lösung:** + +✅ **Automatisch gelöst ab v2.0.1:** +Das Modul erkennt IP-Adressen automatisch und deaktiviert die SSL-Verifizierung. + +**Manuelle Lösung bei älteren Versionen:** +1. Gehe zu: **Setup → Products/Services → Servers** +2. Bearbeite deinen KeyHelp-Server +3. Füge im Feld **NOC** oder einer Custom-Option ein: `no-verify` +4. Speichern + +**Beste Lösung für Produktion:** +``` +1. Erstelle einen A-Record in DNS: + keyhelp.example.com → 5.83.148.129 + +2. Installiere Let's Encrypt auf dem KeyHelp-Server + +3. Verwende den Domain-Namen in WHMCS: + Hostname: keyhelp.example.com (statt 5.83.148.129) +``` + +➡️ Siehe [SSL_TROUBLESHOOTING.md](SSL_TROUBLESHOOTING.md) für Details + +--- + +## API-Endpunkt-Fehler + +### Problem: "KeyHelp API Error: Endpoint not found" + +**Ursache:** +Das Modul verwendet falsche API-Endpunkte. KeyHelp verwendet `/clients`, nicht `/users`. + +**Lösung:** + +✅ **Behoben ab v2.0.1:** +- Alle Endpunkte wurden auf `/clients` korrigiert +- Parameter wurden angepasst (`id_client` statt `user_id`) + +**Prüfen:** +1. Stelle sicher, dass du die neueste Modul-Version verwendest +2. Prüfe die Datei: `keyhelpmanager.php` sollte `/clients` verwenden + +**Manueller Test:** +```bash +# Teste ob der API-Endpunkt funktioniert +curl -X GET https://DEINE-IP/api/v2/clients \ + -H "X-API-Key: DEIN-API-KEY" \ + -H "Accept: application/json" \ + -k + +# Sollte eine Liste oder leeres Array zurückgeben, nicht "Endpoint not found" +``` + +➡️ Siehe [KEYHELP_API_REFERENCE.md](KEYHELP_API_REFERENCE.md) für korrekte Endpunkte + +--- + +## Account-Erstellung schlägt fehl + +### Problem: "Failed to create account in KeyHelp" + +**Mögliche Ursachen:** + +#### 1. API-Key ist falsch oder hat keine Rechte + +**Prüfung:** +```bash +curl -X GET https://DEINE-IP/api/v2/server/version \ + -H "X-API-Key: DEIN-API-KEY" \ + -H "Accept: application/json" \ + -k +``` + +**Erwartete Antwort:** +```json +{"version":"24.3.1","build":"3456"} +``` + +**Bei Fehler:** +- Erstelle einen neuen API-Key in KeyHelp +- Stelle sicher, dass der Key **Admin-Rechte** hat +- Trage ihn im **Password**-Feld der WHMCS Server-Konfiguration ein + +#### 2. Domain existiert bereits + +**Fehlermeldung:** +``` +Domain creation failed: Domain already exists +``` + +**Lösung:** +- Lösche die Domain in KeyHelp manuell +- Oder verwende eine andere Test-Domain + +#### 3. Ungültige Parameter + +**Häufige Fehler:** +``` +- Leere Domain +- Ungültiges E-Mail-Format +- Domain enthält ungültige Zeichen +- Username zu kurz/lang +``` + +**Prüfung:** +1. Gehe zu: **Utilities → Logs → Module Log** +2. Suche nach: `keyhelpmanager` +3. Prüfe Request und Response + +**Beispiel eines korrekten Requests:** +```json +{ + "login_name": "example_com", + "password": "SecurePass123!", + "email": "user@example.com", + "display_name": "Max Mustermann" +} +``` + +#### 4. Template/Hosting-Plan existiert nicht + +**Fehlermeldung:** +``` +Invalid hosting plan ID +``` + +**Lösung:** +- Wähle "Manual Configuration (No Template)" im Produkt +- Oder erstelle den Hosting-Plan in KeyHelp + +--- + +## Client Area zeigt keine Daten + +### Problem: Statistiken werden nicht angezeigt + +**Symptom:** +- Client Area lädt, aber zeigt keine Speicher-/Traffic-Statistiken +- Fortschrittsbalken fehlen + +**Ursachen:** + +#### 1. User-ID wurde nicht gespeichert + +**Prüfung:** +```sql +SELECT * FROM tblcustomfieldsvalues +WHERE relid = DEINE_SERVICE_ID; +``` + +Sollte eine Zeile mit `userid` enthalten. + +**Lösung:** +- Account neu erstellen +- Oder User-ID manuell in Custom Fields eintragen + +#### 2. API-Endpunkt /clients/{id}/statistics nicht verfügbar + +**Test:** +```bash +curl -X GET https://DEINE-IP/api/v2/clients/1/statistics \ + -H "X-API-Key: DEIN-API-KEY" \ + -H "Accept: application/json" \ + -k +``` + +**Bei Fehler:** +- Prüfe KeyHelp-Version (benötigt API v2) +- Update KeyHelp auf die neueste Version + +#### 3. Template wird nicht angezeigt + +**Ursache:** +Template-ID ist "manual" oder leer. + +**Lösung:** +Das ist normal bei "Manual Configuration" - keine Templates verfügbar. + +--- + +## Template-Probleme + +### Problem: "Error loading templates" oder Dropdown ist leer + +**Symptom:** +Bei Produktkonfiguration zeigt das Template-Dropdown: +``` +-- Error loading templates -- +``` +oder +``` +-- Select Template -- +Manual Configuration (No Template) +``` + +**Ursachen:** + +#### 1. API-Endpunkt /plans existiert nicht (KeyHelp Free) + +**Das ist normal!** KeyHelp Free hat keine Hosting-Pläne. + +**Lösung:** +- Wähle "Manual Configuration (No Template)" +- Konfiguriere Limits manuell in KeyHelp + +#### 2. Server ist nicht konfiguriert + +**Lösung:** +1. Gehe zu: **Setup → Products/Services → Servers** +2. Stelle sicher, dass der KeyHelp-Server konfiguriert ist +3. Test Connection muss erfolgreich sein + +#### 3. API-Key hat keine Rechte zum Abrufen von Plänen + +**Lösung:** +- API-Key benötigt **Admin-Rechte** +- Erstelle einen neuen Key mit vollen Rechten + +### Problem: Templates synchronisieren nicht + +**Symptom:** +Nach Erstellen neuer Hosting-Pläne in KeyHelp erscheinen diese nicht in WHMCS. + +**Lösung:** +1. Gehe zum Produkt in WHMCS +2. Tab: **Module Settings** +3. Klicke: **Sync Templates** (falls verfügbar) +4. Oder warte 5 Minuten (Cache-Zeit) + +--- + +## Allgemeine Debugging-Tipps + +### 1. WHMCS Module Log aktivieren + +``` +Setup → General Settings → Logging +✓ Enable Module Log +``` + +Dann prüfen: +``` +Utilities → Logs → Module Log +Filter: keyhelpmanager +``` + +### 2. Activity Log prüfen + +``` +System Settings → Activity Log +Suche nach: "KeyHelp" oder "SSL verification" +``` + +### 3. PHP Error Log + +**Linux:** +```bash +tail -f /var/log/php/error.log +tail -f /var/log/apache2/error.log +tail -f /var/log/nginx/error.log +``` + +**WHMCS Laravel Log:** +```bash +tail -f /var/www/whmcs/storage/logs/laravel.log +``` + +### 4. Debugging-Modus aktivieren + +In `keyhelpmanager.php` temporär hinzufügen: +```php +// Am Anfang der _keyhelpmanager_APIRequest Funktion +error_log("KeyHelp API Request: " . $method . " " . $endpoint); +error_log("KeyHelp API Data: " . json_encode($data)); +``` + +### 5. API direkt testen + +**Connection Test:** +```bash +curl -k https://5.83.148.129/api/v2/server/version \ + -H "X-API-Key: DEIN_KEY" \ + -v +``` + +**Client erstellen:** +```bash +curl -k -X POST https://5.83.148.129/api/v2/clients \ + -H "X-API-Key: DEIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "login_name": "testuser", + "password": "TestPass123!", + "email": "test@example.com", + "display_name": "Test User" + }' +``` + +### 6. Datenbank prüfen + +**Server-Konfiguration:** +```sql +SELECT * FROM tblservers WHERE id = 10; +``` + +**Custom Fields:** +```sql +SELECT * FROM tblcustomfields +WHERE type = 'product' +AND fieldname LIKE '%keyhelp%'; +``` + +**Service-Details:** +```sql +SELECT * FROM tblhosting WHERE id = SERVICE_ID; +``` + +### 7. Modul neu laden + +Nach Änderungen: +```bash +# Cache leeren +rm -rf /var/www/whmcs/storage/cache/* +rm -rf /var/www/whmcs/bootstrap/cache/* + +# Oder im WHMCS Admin +Setup → General Settings → Other → Clear Cache +``` + +--- + +## Häufige Fehlermeldungen + +| Fehlermeldung | Ursache | Lösung | +|---------------|---------|--------| +| "KeyHelp server not configured" | Server-Einstellungen fehlen | Server in WHMCS konfigurieren | +| "Endpoint not found" | Falsche API-Endpunkte | Modul auf v2.0.1+ aktualisieren | +| "Invalid API key" | API-Key falsch oder abgelaufen | Neuen API-Key in KeyHelp erstellen | +| "cURL error 60" | SSL-Zertifikat-Problem | Siehe SSL_TROUBLESHOOTING.md | +| "User created but no ID returned" | API-Response ungültig | KeyHelp-Version prüfen | +| "Domain already exists" | Domain ist schon vorhanden | Domain in KeyHelp löschen | +| "Connection timeout" | Server nicht erreichbar | Firewall/Netzwerk prüfen | + +--- + +## Checkliste zur Fehlersuche + +Arbeite diese Liste systematisch ab: + +- [ ] WHMCS Version 8.13+ installiert? +- [ ] PHP Version 8.3+ aktiv? +- [ ] Modul-Dateien korrekt hochgeladen? +- [ ] Server in WHMCS konfiguriert? +- [ ] Hostname/IP korrekt eingetragen? +- [ ] API-Key im Password-Feld eingetragen? +- [ ] Test Connection erfolgreich? +- [ ] SSL-Konfiguration korrekt? +- [ ] Produkt mit Server verknüpft? +- [ ] Module Log aktiviert? +- [ ] Display Errors aktiviert (für Entwicklung)? +- [ ] KeyHelp-Version aktuell? +- [ ] API v2 in KeyHelp aktiviert? +- [ ] Firewall lässt WHMCS-Server zu? + +--- + +## Support erhalten + +### 1. Informationen sammeln + +Bereite folgende Informationen vor: + +``` +WHMCS Version: _____ +PHP Version: _____ +KeyHelp Version: _____ +Modul Version: _____ +Fehlermeldung: _____ +Module Log: (kopiere relevante Zeilen) +Verwendete IP oder Domain: _____ +SSL aktiviert: Ja/Nein +``` + +### 2. Logs exportieren + +**Module Log:** +``` +Utilities → Logs → Module Log +Export → CSV +``` + +**Activity Log:** +``` +System Settings → Activity Log +Filter nach "KeyHelp" +``` + +### 3. API-Test durchführen + +```bash +# Test 1: Version abrufen +curl -k https://DEINE-IP/api/v2/server/version \ + -H "X-API-Key: DEIN_KEY" + +# Test 2: Clients auflisten +curl -k https://DEINE-IP/api/v2/clients \ + -H "X-API-Key: DEIN_KEY" +``` + +### 4. Kontakt + +**Für WHMCS-Modul:** +- E-Mail: info@avvgo.de +- Website: https://avvgo.de + +**Für KeyHelp API:** +- Forum: https://community.keyhelp.de/ +- Support: support@keyhelp.de +- Wiki: https://wiki.keyhelp.de/ + +--- + +## Weitere Ressourcen + +- [README.md](README.md) - Allgemeine Dokumentation +- [INSTALLATION.md](INSTALLATION.md) - Installations-Anleitung +- [SSL_TROUBLESHOOTING.md](SSL_TROUBLESHOOTING.md) - SSL-spezifische Probleme +- [KEYHELP_API_REFERENCE.md](KEYHELP_API_REFERENCE.md) - API-Dokumentation +- [QUICKSTART.md](QUICKSTART.md) - Schnelleinstieg + +--- + +**Version:** 2.0.1 +**Letzte Aktualisierung:** 2024 +**Entwickelt von:** Kevin Feiler / AVVGO \ No newline at end of file diff --git a/modules/servers/keyhelpmanager.zip b/modules/servers/keyhelpmanager.zip new file mode 100644 index 0000000..4378f63 Binary files /dev/null and b/modules/servers/keyhelpmanager.zip differ