# 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