Ninjaserver/wiki/Troubleshooting.md

# 🐛 Troubleshooting

Problembehandlung und Lösungen für häufige Probleme im Ninja Cross Parkour System.

## 📋 Inhaltsverzeichnis

- [🚨 Kritische Probleme](#-kritische-probleme)
- [🔧 Installation](#-installation)
- [🗄️ Datenbank](#️-datenbank)
- [🌐 API](#-api)
- [🏆 Achievements](#-achievements)
- [📊 Performance](#-performance)
- [🔒 Sicherheit](#-sicherheit)
- [📱 Frontend](#-frontend)

## 🚨 Kritische Probleme

### Server startet nicht

**Symptome:**
- `npm start` schlägt fehl
- Port-Fehler
- Abhängigkeitsfehler

**Lösungen:**
```bash
# Port freigeben
sudo lsof -ti:3000 | xargs kill -9

# Abhängigkeiten neu installieren
rm -rf node_modules package-lock.json
npm install

# Anderen Port verwenden
PORT=3001 npm start

# Logs prüfen
tail -f logs/server.log
```

### Datenbank-Verbindung fehlgeschlagen

**Symptome:**
- `ECONNREFUSED` Fehler
- `database connection failed`
- Timeout-Fehler

**Lösungen:**
```bash
# PostgreSQL-Status prüfen
sudo systemctl status postgresql

# PostgreSQL starten
sudo systemctl start postgresql

# Verbindung testen
psql -h localhost -U username -d ninjaserver

# .env-Datei prüfen
cat .env | grep DB_
```

### API antwortet nicht

**Symptome:**
- 500 Internal Server Error
- Timeout-Fehler
- Leere Antworten

**Lösungen:**
```bash
# Server-Status prüfen
curl http://localhost:3000/health

# Logs analysieren
tail -f logs/server.log

# Datenbank-Verbindung prüfen
psql -d ninjaserver -c "SELECT NOW();"

# Speicher prüfen
free -h
df -h
```

## 🔧 Installation

### Node.js-Version inkompatibel

**Symptom:**
```
Error: Node.js version 14.x is not supported. Please use Node.js 16 or higher.
```

**Lösung:**
```bash
# Node.js-Version prüfen
node --version

# Node.js aktualisieren (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Node.js aktualisieren (macOS)
brew install node@18

# Node.js aktualisieren (Windows)
# Download von https://nodejs.org/
```

### npm install schlägt fehl

**Symptome:**
- Permission denied
- ENOENT Fehler
- Network timeout

**Lösungen:**
```bash
# Berechtigungen prüfen
sudo chown -R $(whoami) ~/.npm

# Cache leeren
npm cache clean --force

# Registry wechseln
npm config set registry https://registry.npmjs.org/

# Mit sudo installieren (nicht empfohlen)
sudo npm install
```

### PostgreSQL nicht installiert

**Symptom:**
```
Error: connect ECONNREFUSED 127.0.0.1:5432
```

**Lösung:**
```bash
# PostgreSQL installieren (Ubuntu/Debian)
sudo apt update
sudo apt install postgresql postgresql-contrib

# PostgreSQL starten
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Benutzer erstellen
sudo -u postgres createuser --interactive
sudo -u postgres createdb ninjaserver
```

### Umgebungsvariablen fehlen

**Symptom:**
```
Error: Missing required environment variable: DB_HOST
```

**Lösung:**
```bash
# .env-Datei erstellen
cp .env.example .env

# .env-Datei bearbeiten
nano .env

# Beispiel-Inhalt:
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ninjaserver
DB_USER=username
DB_PASSWORD=password
JWT_SECRET=your-secret-key
```

## 🗄️ Datenbank

### Datenbank existiert nicht

**Symptom:**
```
Error: database "ninjaserver" does not exist
```

**Lösung:**
```bash
# Datenbank erstellen
sudo -u postgres createdb ninjaserver

# Oder mit psql
psql -U postgres -c "CREATE DATABASE ninjaserver;"
```

### Tabellen fehlen

**Symptom:**
```
Error: relation "players" does not exist
```

**Lösung:**
```bash
# Datenbank initialisieren
npm run init-db

# Oder manuell
psql -d ninjaserver -f scripts/init-db.js
```

### Verbindungslimit erreicht

**Symptom:**
```
Error: too many connections
```

**Lösung:**
```sql
-- Aktive Verbindungen prüfen
SELECT count(*) FROM pg_stat_activity;

-- Verbindungen beenden
SELECT pg_terminate_backend(pid) 
FROM pg_stat_activity 
WHERE state = 'idle' AND query_start < NOW() - INTERVAL '5 minutes';

-- Verbindungslimit erhöhen
ALTER SYSTEM SET max_connections = 200;
SELECT pg_reload_conf();
```

### Datenbank-Corruption

**Symptom:**
```
Error: database is not accepting commands
```

**Lösung:**
```bash
# Datenbank reparieren
pg_ctl stop
pg_ctl start -D /var/lib/postgresql/data

# Vakuum durchführen
psql -d ninjaserver -c "VACUUM FULL;"

# Backup wiederherstellen
psql -d ninjaserver < backup.sql
```

## 🌐 API

### 401 Unauthorized

**Symptom:**
```
{"success": false, "message": "API-Key erforderlich"}
```

**Lösung:**
```bash
# API-Key generieren
curl -X POST http://localhost:3000/api/v1/web/generate-api-key \
  -H "Content-Type: application/json" \
  -d '{"description": "Test Key"}'

# API-Key verwenden
curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:3000/api/v1/private/locations
```

### 403 Forbidden

**Symptom:**
```
{"success": false, "message": "Keine Berechtigung"}
```

**Lösung:**
```bash
# Admin-Token verwenden
curl -H "Authorization: Bearer ADMIN_TOKEN" \
  http://localhost:3000/api/v1/admin/players

# Oder API-Key mit Admin-Rechten generieren
```

### 404 Not Found

**Symptom:**
```
{"success": false, "message": "Ressource nicht gefunden"}
```

**Lösung:**
```bash
# Korrekte URL verwenden
curl http://localhost:3000/api/v1/public/locations

# Endpoint-Liste prüfen
curl http://localhost:3000/api-docs
```

### 500 Internal Server Error

**Symptom:**
```
{"success": false, "message": "Internal Server Error"}
```

**Lösung:**
```bash
# Logs prüfen
tail -f logs/server.log

# Datenbank-Verbindung prüfen
psql -d ninjaserver -c "SELECT NOW();"

# Server neu starten
npm restart
```

### CORS-Fehler

**Symptom:**
```
Access to fetch at 'http://localhost:3000/api' from origin 'http://localhost:8080' has been blocked by CORS policy
```

**Lösung:**
```javascript
// CORS-Middleware konfigurieren
app.use(cors({
  origin: ['http://localhost:8080', 'https://yourdomain.com'],
  credentials: true
}));
```

## 🏆 Achievements

### Achievements werden nicht vergeben

**Symptom:**
- Spieler erfüllt Bedingungen, aber erhält kein Achievement
- Tägliche Prüfung läuft nicht

**Lösung:**
```bash
# Tägliche Prüfung manuell ausführen
node scripts/daily_achievements.js

# Cron-Job prüfen
node scripts/setup_cron.js status

# Cron-Job einrichten
node scripts/setup_cron.js setup

# Logs prüfen
tail -f /var/log/ninjaserver_achievements.log
```

### Achievement-Daten korrupt

**Symptom:**
- Achievements werden mehrfach vergeben
- Falsche Fortschrittswerte

**Lösung:**
```sql
-- Doppelte Achievements entfernen
DELETE FROM player_achievements 
WHERE id NOT IN (
  SELECT MIN(id) 
  FROM player_achievements 
  GROUP BY player_id, achievement_id
);

-- Fortschritt zurücksetzen
UPDATE player_achievements 
SET progress = 0, is_completed = false 
WHERE is_completed = false;
```

### Tägliche Prüfung schlägt fehl

**Symptom:**
```
Error: Daily achievement check failed
```

**Lösung:**
```bash
# Logs analysieren
grep "ERROR" /var/log/ninjaserver_achievements.log

# Datenbank-Verbindung prüfen
psql -d ninjaserver -c "SELECT NOW();"

# Berechtigungen prüfen
ls -la /var/log/ninjaserver_achievements.log

# Script manuell ausführen
node scripts/daily_achievements.js
```

## 📊 Performance

### Langsame API-Antworten

**Symptom:**
- API-Antworten dauern > 5 Sekunden
- Timeout-Fehler

**Lösung:**
```sql
-- Indizes prüfen
SELECT schemaname, tablename, indexname, idx_scan
FROM pg_stat_user_indexes 
ORDER BY idx_scan DESC;

-- Langsame Queries identifizieren
SELECT query, calls, total_time, mean_time
FROM pg_stat_statements 
ORDER BY mean_time DESC LIMIT 10;

-- Indizes hinzufügen
CREATE INDEX CONCURRENTLY idx_times_player_created 
ON times(player_id, created_at DESC);
```

### Hohe CPU-Last

**Symptom:**
- Server verbraucht > 80% CPU
- Langsame Antwortzeiten

**Lösung:**
```bash
# Prozesse prüfen
top -p $(pgrep node)

# Speicher prüfen
free -h

# Datenbank-Verbindungen prüfen
psql -d ninjaserver -c "SELECT count(*) FROM pg_stat_activity;"

# Vakuum durchführen
psql -d ninjaserver -c "VACUUM ANALYZE;"
```

### Speicher-Leaks

**Symptom:**
- Speicherverbrauch steigt kontinuierlich
- Server stürzt ab

**Lösung:**
```bash
# Speicher-Usage prüfen
ps aux | grep node

# Server neu starten
pm2 restart ninjaserver

# Oder mit systemd
sudo systemctl restart ninjaserver
```

## 🔒 Sicherheit

### Schwache Passwörter

**Symptom:**
- Standardpasswörter in Produktion
- Sicherheitswarnungen

**Lösung:**
```bash
# Admin-Passwort ändern
npm run create-user

# Oder direkt in der Datenbank
psql -d ninjaserver -c "UPDATE adminusers SET password_hash = '\$2b\$10\$...' WHERE username = 'admin';"
```

### API-Key kompromittiert

**Symptom:**
- Unerwartete API-Aufrufe
- Unbekannte Aktivitäten

**Lösung:**
```sql
-- API-Key deaktivieren
UPDATE api_tokens SET is_active = false WHERE token = 'COMPROMISED_TOKEN';

-- Neuen API-Key generieren
-- (über API oder direkt in der Datenbank)
```

### SQL-Injection

**Symptom:**
- Unerwartete Datenbank-Abfragen
- Fehlerhafte API-Antworten

**Lösung:**
```javascript
// Parametrisierte Queries verwenden
const result = await db.query(
  'SELECT * FROM players WHERE id = $1',
  [playerId]
);

// Input-Validierung
if (!isValidUUID(playerId)) {
  throw new Error('Invalid player ID');
}
```

## 📱 Frontend

### JavaScript-Fehler

**Symptom:**
- Konsole zeigt Fehler
- Funktionen funktionieren nicht

**Lösung:**
```javascript
// Browser-Konsole prüfen
console.error('Error details:', error);

// API-Verbindung testen
fetch('/api/v1/public/locations')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('API Error:', error));
```

### CORS-Probleme

**Symptom:**
```
Access to fetch at 'http://localhost:3000/api' from origin 'http://localhost:8080' has been blocked by CORS policy
```

**Lösung:**
```javascript
// CORS-Header setzen
fetch('/api/v1/public/locations', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
  },
  mode: 'cors'
});
```

### Session-Probleme

**Symptom:**
- Login funktioniert nicht
- Session wird nicht gespeichert

**Lösung:**
```javascript
// Session-Cookie prüfen
document.cookie

// Login-Request prüfen
fetch('/api/v1/public/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include',
  body: JSON.stringify({
    username: 'admin',
    password: 'admin123'
  })
});
```

## 🔧 Allgemeine Lösungen

### Logs analysieren

```bash
# Server-Logs
tail -f logs/server.log

# Error-Logs
grep "ERROR" logs/server.log

# Achievement-Logs
tail -f /var/log/ninjaserver_achievements.log

# System-Logs
journalctl -u ninjaserver -f
```

### System-Status prüfen

```bash
# Server-Status
curl http://localhost:3000/health

# Datenbank-Status
psql -d ninjaserver -c "SELECT NOW();"

# Speicher-Status
free -h
df -h

# Prozess-Status
ps aux | grep node
```

### Backup wiederherstellen

```bash
# Vollständiges Backup
psql -d ninjaserver < backup.sql

# Nur Daten
psql -d ninjaserver < data_backup.sql

# Nur Schema
psql -d ninjaserver < schema_backup.sql
```

### System neu starten

```bash
# Mit npm
npm restart

# Mit pm2
pm2 restart ninjaserver

# Mit systemd
sudo systemctl restart ninjaserver

# Mit Docker
docker restart ninjaserver
```

## 📞 Support kontaktieren

Wenn diese Lösungen nicht helfen:

1. **Logs sammeln:**
   ```bash
   # Alle relevanten Logs
   tail -n 100 logs/server.log > error_log.txt
   tail -n 100 /var/log/ninjaserver_achievements.log >> error_log.txt
   ```

2. **System-Info sammeln:**
   ```bash
   # System-Informationen
   uname -a > system_info.txt
   node --version >> system_info.txt
   npm --version >> system_info.txt
   psql --version >> system_info.txt
   ```

3. **Problem beschreiben:**
   - Was passiert ist
   - Wann es passiert ist
   - Welche Schritte Sie unternommen haben
   - Fehlermeldungen

4. **Support kontaktieren:**
   - E-Mail: support@ninjaparkour.de
   - Issue-System verwenden
   - Logs und System-Info anhängen

---

**Hinweis:** Diese Anleitung wird regelmäßig aktualisiert. Bei neuen Problemen wenden Sie sich an den Support.