reptil1990/Ninjaserver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Ninjaserver/wiki/FAQ.md
Carsten Graf 58b5e6b074 Update
2025-09-23 14:13:24 +02:00

9.7 KiB
Raw Permalink Blame History

❓ FAQ - Häufige Fragen

Antworten auf häufig gestellte Fragen zum Ninja Cross Parkour System.

🚀 Installation und Setup

Wie installiere ich das System?

Siehe Schnellstart für eine detaillierte Anleitung. Kurz gesagt:

  1. Repository klonen
  2. npm install ausführen
  3. .env-Datei konfigurieren
  4. npm run init-db ausführen
  5. npm start starten

Welche Voraussetzungen benötige ich?

  • Node.js v16 oder höher
  • PostgreSQL 12 oder höher
  • npm oder yarn
  • Git für die Installation

Wie konfiguriere ich die Datenbank?

Bearbeiten Sie die .env-Datei mit Ihren Datenbankdaten:

DB_HOST=localhost
DB_PORT=5432
DB_NAME=ninjaserver
DB_USER=your_username
DB_PASSWORD=your_password

Wie erstelle ich den ersten Admin-Benutzer?

npm run create-user

Standard-Anmeldedaten: admin / admin123

🔐 Authentifizierung

Wie funktioniert die API-Authentifizierung?

Das System verwendet API-Keys für die Authentifizierung. Generieren Sie einen Key:

curl -X POST http://localhost:3000/api/v1/web/generate-api-key \
  -H "Content-Type: application/json" \
  -d '{"description": "Mein API Key"}'

Wie verwende ich den API-Key?

Fügen Sie den Key in den Authorization Header ein:

Authorization: Bearer YOUR_API_KEY_HERE

Wie lange sind API-Keys gültig?

API-Keys sind standardmäßig unbegrenzt gültig, können aber mit einem Ablaufdatum versehen werden.

Kann ich mehrere API-Keys haben?

Ja, Sie können beliebig viele API-Keys erstellen, z.B. für verschiedene Anwendungen oder Benutzer.

🏃‍♂️ Spieler und Zeiten

Wie registriere ich einen neuen Spieler?

curl -X POST http://localhost:3000/api/v1/public/players \
  -H "Content-Type: application/json" \
  -d '{"firstname": "Max", "lastname": "Mustermann", "birthdate": "1990-01-01", "rfiduid": "AA:BB:CC:DD"}'

Wie verknüpfe ich eine RFID-Karte mit einem Spieler?

curl -X POST http://localhost:3000/api/v1/public/link-by-rfid \
  -H "Content-Type: application/json" \
  -d '{"rfiduid": "AA:BB:CC:DD", "supabase_user_id": "uuid-here"}'

Wie messe ich eine Zeit?

curl -X POST http://localhost:3000/api/v1/private/create-time \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id": "AA:BB:CC:DD", "location_id": "Standort-Name", "recorded_time": "01:23.456"}'

Welches Zeitformat wird verwendet?

Zeiten werden im Format MM:SS.mmm gespeichert:

  • Minuten:Sekunden.Millisekunden
  • Beispiel: 01:23.456 = 1 Minute, 23 Sekunden, 456 Millisekunden

Was ist eine gültige Zeit?

  • Minimum: 30 Sekunden
  • Maximum: 10 Minuten
  • Schwelle: Konfigurierbar pro Standort (Standard: 120 Sekunden)

🏆 Achievements

Wie funktioniert das Achievement-System?

Das System überprüft automatisch täglich alle Spieler auf neue Achievements. Siehe Achievement System für Details.

Wann werden Achievements vergeben?

  • Automatisch: Täglich um 23:59 Uhr
  • Manuell: Über API-Endpoints
  • Sofort: Bei bestimmten Aktionen

Wie viele Achievements gibt es?

Das System hat 32 verschiedene Achievements in 4 Kategorien:

  • Konsistenz-basierte (8)
  • Verbesserungs-basierte (4)
  • Saisonale (4)
  • Monatliche (12)
  • Jahreszeiten (4)

Wie rufe ich Achievements ab?

# Alle Achievements
curl http://localhost:3000/api/achievements

# Spieler-Achievements
curl http://localhost:3000/api/achievements/player/{playerId}

# Spieler-Statistiken
curl http://localhost:3000/api/achievements/player/{playerId}/stats

📍 Standorte

Wie erstelle ich einen neuen Standort?

curl -X POST http://localhost:3000/api/v1/private/create-location \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "München", "latitude": 48.1351, "longitude": 11.5820}'

Wie ändere ich die Zeit-Schwelle eines Standorts?

curl -X PUT http://localhost:3000/api/v1/private/locations/{id}/threshold \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"threshold_seconds": 120}'

Wie viele Standorte kann ich haben?

Es gibt keine Begrenzung der Anzahl der Standorte.

🔧 Technische Fragen

Wie starte ich den Server?

# Entwicklung
npm run dev

# Produktion
npm start

Wie überwache ich den Server?

# Logs anzeigen
tail -f logs/server.log

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

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

Wie teste ich die API?

# Test-Skript ausführen
node test-api.js

# Einzelne Endpoints testen
curl http://localhost:3000/api/v1/public/locations

Wie sichere ich die Datenbank?

# Vollständiges Backup
pg_dump -h localhost -U username -d ninjaserver > backup.sql

# Wiederherstellung
psql -h localhost -U username -d ninjaserver < backup.sql

🐛 Fehlerbehebung

"Port 3000 bereits belegt"

# Port freigeben
sudo lsof -ti:3000 | xargs kill -9

# Oder anderen Port verwenden
PORT=3001 npm start

"Datenbank-Verbindung fehlgeschlagen"

  1. PostgreSQL-Service prüfen: sudo systemctl status postgresql
  2. Datenbank-Credentials in .env prüfen
  3. Firewall-Einstellungen prüfen

"API-Key funktioniert nicht"

  1. API-Key neu generieren
  2. Authorization Header prüfen: Bearer YOUR_API_KEY
  3. Token-Ablaufzeit prüfen

"Zeit wird nicht gespeichert"

  1. Gültige Zeit prüfen (innerhalb der Schwelle)
  2. Standort korrekt ausgewählt
  3. Internetverbindung prüfen
  4. Seite neu laden

"Achievements werden nicht vergeben"

  1. Tägliche Prüfung abwarten
  2. Bedingungen erfüllt prüfen
  3. System-Status prüfen
  4. Administrator kontaktieren

📊 Statistiken und Monitoring

Wie rufe ich Statistiken ab?

# Admin-Statistiken
curl -H "Authorization: Bearer ADMIN_TOKEN" http://localhost:3000/api/v1/admin/stats

# Seiten-Statistiken
curl -H "Authorization: Bearer ADMIN_TOKEN" http://localhost:3000/api/v1/admin/page-stats

Wie überwache ich die Performance?

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

-- Index-Nutzung
SELECT schemaname, tablename, indexname, idx_scan
FROM pg_stat_user_indexes 
ORDER BY idx_scan DESC;

Wie prüfe ich die Datenbank-Größe?

-- Gesamtgröße
SELECT pg_size_pretty(pg_database_size('ninjaserver'));

-- Tabellen-Größen
SELECT tablename, pg_size_pretty(pg_total_relation_size(tablename)) as size
FROM pg_tables WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(tablename) DESC;

🔒 Sicherheit

Wie sichere ich das System?

  • Standardpasswörter ändern
  • HTTPS in der Produktion verwenden
  • Regelmäßige Backups
  • API-Keys regelmäßig rotieren
  • Firewall konfigurieren

Wie ändere ich das Admin-Passwort?

# Neuen Admin-Benutzer erstellen
npm run create-user

# Oder direkt in der Datenbank
UPDATE adminusers SET password_hash = '$2b$10$...' WHERE username = 'admin';

Wie deaktiviere ich einen API-Key?

UPDATE api_tokens SET is_active = false WHERE token = 'YOUR_TOKEN';

🌐 Deployment

Wie deploye ich in die Produktion?

  1. Server vorbereiten (Node.js, PostgreSQL)
  2. Code deployen
  3. Umgebungsvariablen setzen
  4. Datenbank initialisieren
  5. Nginx konfigurieren
  6. SSL-Zertifikat einrichten

Wie konfiguriere ich Nginx?

server {
    listen 80;
    server_name ninja.reptilfpv.de;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Wie richte ich SSL ein?

# Let's Encrypt
certbot --nginx -d ninja.reptilfpv.de

📱 Frontend

Wie integriere ich das System in meine Website?

Verwenden Sie die REST API oder das Web-Interface. Siehe API Referenz für Details.

Gibt es eine mobile App?

Eine native mobile App ist geplant, aber noch nicht verfügbar. Das Web-Interface ist responsive und funktioniert auf allen Geräten.

Wie passe ich das Design an?

Bearbeiten Sie die CSS-Dateien im public/css/ Verzeichnis oder erstellen Sie ein eigenes Frontend mit der API.

🔄 Updates und Wartung

Wie aktualisiere ich das System?

# Code aktualisieren
git pull origin main

# Abhängigkeiten aktualisieren
npm install

# Datenbank-Migrationen (falls vorhanden)
npm run migrate

# Server neu starten
npm restart

Wie führe ich Wartungsaufgaben durch?

-- Tabellen analysieren
ANALYZE;

-- Indizes neu aufbauen
REINDEX DATABASE ninjaserver;

-- Vakuum durchführen
VACUUM ANALYZE;

Wie lösche ich alte Daten?

-- Alte Zeiten löschen (älter als 1 Jahr)
DELETE FROM times WHERE created_at < NOW() - INTERVAL '1 year';

-- Alte Seitenaufrufe löschen (älter als 6 Monate)
DELETE FROM page_views WHERE created_at < NOW() - INTERVAL '6 months';

📞 Support

Wo bekomme ich Hilfe?

  • 📖 Konsultieren Sie diese Dokumentation
  • 🔍 Schauen Sie in Troubleshooting
  • 📧 Kontaktieren Sie den Systemadministrator
  • 🐛 Melden Sie Bugs über das Issue-System

Wie melde ich einen Bug?

  1. Beschreiben Sie das Problem
  2. Fügen Sie Logs hinzu
  3. Geben Sie Schritte zur Reproduktion an
  4. Erwähnen Sie Ihre Systemkonfiguration

Wie schlage ich eine Verbesserung vor?

  1. Beschreiben Sie die gewünschte Funktion
  2. Erklären Sie den Nutzen
  3. Geben Sie Beispiele an
  4. Erwähnen Sie mögliche Implementierung

Hinweis: Diese FAQ wird regelmäßig aktualisiert. Bei Fragen, die hier nicht beantwortet werden, wenden Sie sich an den Support.

Reference in New Issue View Git Blame Copy Permalink