# 🎫 UniFi Voucher Management System
**Webbasiertes WLAN-Voucher-Management für UniFi OS** – mit Multi-Site-Support, Benutzerverwaltung, Microsoft-365-Login und integriertem Auto-Updater.
---
---
## ✨ Features
- 🎟️ **Voucher-Erstellung** mit sofortiger QR-Code-Anzeige, Druckvorlage und E-Mail-Versand
- 🏢 **Multi-Site-Support** – beliebig viele UniFi-Standorte zentral verwalten
- 👥 **Benutzerverwaltung** mit granularer Site-Zugriffskontrolle
- 🔐 **Authentifizierung** via lokale Accounts **oder** Microsoft 365 OAuth
- 🌍 **Öffentlicher Modus** – optional ohne Login nutzbar (mit CSRF-Schutz & Throttle)
- 📊 **Admin-Dashboard** mit Live-Statistiken und Sync-Funktion
- 📥 **CSV-Export** aller Vouchers pro Site
- 🔄 **Integrierter Auto-Updater** – Updates per Klick aus dem Admin-Bereich
- 🛡️ **Security-by-default**: CSRF-Schutz, bcrypt-Passwörter, Prepared Statements,
Login-Rate-Limiting, OAuth-State-Validierung, Verschlüsselung sensibler Daten
---
## 📸 Screenshots
### Anmeldung & Voucher-Erstellung
### Administration & Updater
---
## 📋 Anforderungen
| Komponente | Version |
|---|---|
| PHP | 7.4+ (mit PDO, PDO_MySQL, cURL, mbstring, JSON; empfohlen: OpenSSL/libsodium, Zip) |
| Datenbank | MySQL 5.7+ / MariaDB 10.2+ |
| Webserver | Apache / Nginx |
| UniFi | **Network Application 7.0+ mit UniFi OS** (z. B. UDM, UDR, UniFi OS Server) |
---
## 🚀 Installation
```bash
git clone https://github.com/friloo/unifi-voucher-tool.git
cd unifi-voucher-tool
```
1. Dateien auf den Webserver hochladen
2. `https://ihre-domain.de/install.php` öffnen
3. Den **5-Schritte-Assistenten** durchlaufen:
1. Datenbank-Verbindungsdaten
2. Administrator-Account
3. Allgemeine Einstellungen (Titel, Logo, öffentlicher Zugriff)
4. Microsoft 365 Integration (optional)
5. Installation abschließen
4. `install.php` nach erfolgreicher Installation **löschen**
> 🔒 Der Installer erzeugt automatisch einen zufälligen `APP_KEY` (für die
> Verschlüsselung der UniFi-Passwörter) und eine `.htaccess`, die sensible
> Dateien sperrt. Ein erneuter Aufruf von `install.php?reinstall=1` ist nur
> für **angemeldete Administratoren** möglich.
### Sites konfigurieren
1. **Administration → Sites verwalten → Neue Site hinzufügen**
2. Felder ausfüllen:
- **Name:** Anzeigename (z. B. „Hauptgebäude")
- **Site ID:** UniFi Site ID (meist `default`)
- **Controller URL:** `https://unifi.example.com:11443`
- **Benutzername / Passwort:** UniFi Admin-Zugangsdaten
3. **Verbindung testen** klicken, dann speichern
### Voucher erstellen
1. Startseite öffnen (Login je nach Konfiguration optional)
2. Voucher-Name, Anzahl Geräte und Standort wählen
3. **Voucher erstellen** – Code und QR-Code werden sofort angezeigt
4. Code per E-Mail senden oder ausdrucken
---
## 🔄 Auto-Updater
Das System bringt einen vollständig integrierten Updater mit, der Quellcode und
Datenbank-Migrationen über einen zentralen Update-Proxy nachzieht – ganz ohne
SSH oder manuelles `git pull`.
```
[diese Instanz] ←HTTPS→ [Update-Proxy] ←pull→ [Git-Repo]
```
**Aufruf:** Administration → **System-Update** (`/admin/update.php`)
- 🔍 **„Auf Updates prüfen"** zeigt verfügbare Versionen inkl. Changelog
- ⬇️ **„Update installieren"** spielt das Update ein – mit Wartungsseite,
geschützten Pfaden (`config.php`, Uploads, …), automatischen DB-Migrationen
und OPcache-Reset
- 🔀 **Channel-Auswahl** zwischen `stable` und `development`
- 📊 **Migrations-Status** in einem eigenen Tab
Während eines Updates wird die Anwendung kurz in den **Wartungsmodus** versetzt:
> Der Updater ist vollständig isoliert im Ordner [`updater/`](updater/) gekapselt.
> Details zur Architektur und eine Rückbau-Anleitung stehen in
> [`updater/README.md`](updater/README.md).
---
## ⚙️ Konfiguration
### `config.php`
Wird automatisch durch den Installer erstellt:
```php
Require all denied
```
```sql
-- Dedizierter Datenbank-Benutzer mit minimalen Rechten
CREATE USER 'unifi_voucher'@'localhost' IDENTIFIED BY 'sicheres_passwort';
GRANT SELECT, INSERT, UPDATE, DELETE ON unifi_voucher.* TO 'unifi_voucher'@'localhost';
```
---
## 🩺 Problembehandlung
Login funktioniert nicht
- Datenbankverbindung und PHP-Session-Konfiguration prüfen
- Fehler werden ins PHP-Error-Log geschrieben (nicht mehr in den Browser)
UniFi-Verbindung schlägt fehl
- Controller-URL im Browser testen
- Port **11443** für UniFi OS verwenden (nicht 8443)
- Benutzername, Passwort und Site ID prüfen
- cURL-Extension muss aktiviert sein
UniFi OS: HTTP 404 oder 401
- Login-Endpunkt ist `/api/auth/login` (nicht `/api/login`)
- API-Pfade benötigen Präfix `/proxy/network/api/s/{site}/...`
- Älterer UniFi Network Controller (ohne UniFi OS) wird ab Version 2.1.0 nicht mehr unterstützt
Microsoft 365 Login funktioniert nicht
- Redirect URI in Azure AD prüfen
- Client ID, Secret und Tenant ID kontrollieren
- Diagnose unter `m365_debug.php` (nur als Admin erreichbar)
---
## 📡 API-Dokumentation (UniFi OS)
```http
# Login
POST /api/auth/login
Body: {"username": "admin", "password": "password"}
Response-Header: X-CSRF-Token:
# Voucher erstellen
POST /proxy/network/api/s/{site_id}/cmd/hotspot
X-CSRF-Token:
Body: {"cmd": "create-voucher", "expire": 480, "n": 1, "note": "Name", "quota": 1}
# Vouchers abrufen
GET /proxy/network/api/s/{site_id}/stat/voucher
# Voucher löschen
POST /proxy/network/api/s/{site_id}/cmd/hotspot
Body: {"cmd": "delete-voucher", "_id": ""}
```
---
## 🗺️ Roadmap
- [ ] Voucher-Templates (vordefinierte Laufzeiten)
- [ ] Bulk-Voucher-Erstellung
- [ ] Erweiterte Reporting-Funktionen
- [ ] Docker-Container
- [ ] Mehrsprachigkeit
- [x] Auto-Updater mit DB-Migrationen
---
**Version 2.1.0** · Autor: **Friederich Loheide** · Lizenz: **MIT**
