Update
This commit is contained in:
687
wiki/Troubleshooting.md
Normal file
687
wiki/Troubleshooting.md
Normal file
@@ -0,0 +1,687 @@
|
||||
# 🐛 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.
|
||||
Reference in New Issue
Block a user