diff --git a/Readme.md b/Readme.md index a64a944..7102102 100644 --- a/Readme.md +++ b/Readme.md @@ -1,25 +1,77 @@ -# UniFi Voucher Management System +
-Webbasiertes System zur Verwaltung von WLAN-Vouchers für UniFi OS mit Multi-Site-Unterstützung, Benutzerverwaltung und Microsoft 365 Integration. +# 🎫 UniFi Voucher Management System -## Features +**Webbasiertes WLAN-Voucher-Management für UniFi OS** – mit Multi-Site-Support, Benutzerverwaltung, Microsoft-365-Login und integriertem Auto-Updater. -- **Voucher-Erstellung** mit QR-Code-Anzeige und E-Mail-Versand -- **Multi-Site-Support** – mehrere UniFi-Standorte verwalten -- **Benutzerverwaltung** mit granularer Site-Zugriffskontrolle -- **Authentifizierung** via lokale Accounts oder Microsoft 365 OAuth -- **CSV-Export** aller Vouchers pro Site -- **Admin-Dashboard** mit Live-Statistiken und Sync-Funktion -- **Öffentlicher Zugriff** – optional ohne Login nutzbar -- CSRF-Schutz, bcrypt-Passwörter, Prepared Statements, Login-Rate-Limiting +![PHP](https://img.shields.io/badge/PHP-7.4%2B-777BB4?logo=php&logoColor=white) +![MySQL](https://img.shields.io/badge/MySQL-5.7%2B%20%2F%20MariaDB-4479A1?logo=mysql&logoColor=white) +![UniFi OS](https://img.shields.io/badge/UniFi%20OS-7.0%2B-0559C9?logo=ubiquiti&logoColor=white) +![License](https://img.shields.io/badge/Lizenz-MIT-green) +![Version](https://img.shields.io/badge/Version-2.1.0-blueviolet) -## Anforderungen +
-- PHP 7.4+, MySQL 5.7+ / MariaDB 10.2+, Apache/Nginx -- PHP-Extensions: PDO, PDO_MySQL, cURL, mbstring, JSON -- **UniFi Network Application 7.0+ mit UniFi OS** (z.B. UDM, UDR, UniFi OS Server) +--- -## Installation +
+ Erstellter Voucher mit QR-Code + Admin Dashboard +
+ +--- + +## ✨ 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 + +
+ Login mit Microsoft 365 + Voucher erstellen + Voucher-Ergebnis +
+ +### Administration & Updater + +
+ Dashboard + Auto-Updater +
+ +
+ Updater – Ausgangszustand + Wartungsmodus +
+ +--- + +## 📋 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 @@ -27,136 +79,210 @@ cd unifi-voucher-tool ``` 1. Dateien auf den Webserver hochladen -2. `http://ihre-domain.de/install.php` öffnen -3. Den 5-Schritte-Assistenten durchlaufen: - - **Schritt 1:** Datenbank-Verbindungsdaten - - **Schritt 2:** Administrator-Account (Name, E-Mail, Passwort) - - **Schritt 3:** Allgemeine Einstellungen (Titel, Logo, öffentlicher Zugriff) - - **Schritt 4:** Microsoft 365 Integration (optional) - - **Schritt 5:** Installation abschließen -4. `install.php` nach erfolgreicher Installation löschen +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** -## Sites konfigurieren +> 🔒 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") + - **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 +### 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 -## Konfiguration +--- + +## 🔄 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: + +
+ Wartungsmodus +
+ +> 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` -### config.php Wird automatisch durch den Installer erstellt: + ```php - Order Allow,Deny - Deny from all +# .htaccess – sensible Dateien sperren (wird vom Installer erzeugt) + + Require all denied ``` ```sql --- Dedizierter Datenbank-Benutzer +-- 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 +--- + +## 🩺 Problembehandlung + +
+Login funktioniert nicht -**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 -**UniFi-Verbindung schlägt fehl:** - Controller-URL im Browser testen -- Port 11443 für UniFi OS verwenden (nicht 8443) +- 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 -**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 +
-**Voucher werden nicht erstellt:** -- UniFi Controller Logs prüfen -- API-Berechtigungen des Admin-Accounts prüfen -- Site ID korrekt? (zu finden in der UniFi Controller URL) +
+Microsoft 365 Login funktioniert nicht -**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 +--- -**Login (UniFi OS):** -``` +## 📡 API-Dokumentation (UniFi OS) + +```http +# Login POST /api/auth/login Body: {"username": "admin", "password": "password"} Response-Header: X-CSRF-Token: -``` -**Voucher erstellen:** -``` +# 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:** -``` +# Vouchers abrufen GET /proxy/network/api/s/{site_id}/stat/voucher -``` -**Voucher löschen:** -``` +# Voucher löschen POST /proxy/network/api/s/{site_id}/cmd/hotspot -X-CSRF-Token: Body: {"cmd": "delete-voucher", "_id": ""} ``` -## Roadmap +--- + +## 🗺️ 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 | **Letztes Update:** April 2026 +
+ +**Version 2.1.0** · Autor: **Friederich Loheide** · Lizenz: **MIT** + +
diff --git a/docs/screenshots/admin-dashboard.png b/docs/screenshots/admin-dashboard.png new file mode 100644 index 0000000..dd421dc Binary files /dev/null and b/docs/screenshots/admin-dashboard.png differ diff --git a/docs/screenshots/login.png b/docs/screenshots/login.png new file mode 100644 index 0000000..7bcae7d Binary files /dev/null and b/docs/screenshots/login.png differ diff --git a/docs/screenshots/maintenance.png b/docs/screenshots/maintenance.png new file mode 100644 index 0000000..b467448 Binary files /dev/null and b/docs/screenshots/maintenance.png differ diff --git a/docs/screenshots/updater-available.png b/docs/screenshots/updater-available.png new file mode 100644 index 0000000..59a084b Binary files /dev/null and b/docs/screenshots/updater-available.png differ diff --git a/docs/screenshots/updater.png b/docs/screenshots/updater.png new file mode 100644 index 0000000..992acb8 Binary files /dev/null and b/docs/screenshots/updater.png differ diff --git a/docs/screenshots/voucher-form.png b/docs/screenshots/voucher-form.png new file mode 100644 index 0000000..dc26ee4 Binary files /dev/null and b/docs/screenshots/voucher-form.png differ diff --git a/docs/screenshots/voucher-result.png b/docs/screenshots/voucher-result.png new file mode 100644 index 0000000..ac7bf73 Binary files /dev/null and b/docs/screenshots/voucher-result.png differ