Some checks failed
CI / PHP Lint (push) Successful in 41s
CI / PHP Lint-1 (push) Successful in 40s
CI / Unit Tests & Static Analysis (push) Failing after 39s
CI / PHP Lint (pull_request) Successful in 41s
CI / PHP Lint-1 (pull_request) Successful in 41s
CI / Unit Tests & Static Analysis (pull_request) Failing after 41s
Wurde die Vorschau gekürzt, zeigt die Oberfläche einen Verweis auf das vollständige Änderungsprotokoll. Der zeigte fest auf den stabilen Kanal, auch wenn die Installation auf dem Entwicklungskanal läuft. Aufgefallen beim ersten echten Durchlauf mit Vorschau: der Dienst kennt jetzt 3.0.0 und liefert die Abschnitte samt "complete": false. Freigabe nach dem dokumentierten Ablauf: Changelog ergänzt, VERSION und Version::RELEASE auf 3.0.1 angehoben. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
786 lines
32 KiB
Markdown
786 lines
32 KiB
Markdown
<div align="center">
|
||
|
||
# 🎫 UniFi Voucher Management System
|
||
|
||
**Webbasiertes WLAN-Voucher-Management für UniFi OS** – mit Multi-Site-Support, Benutzerverwaltung, Microsoft-365-Login und integriertem Auto-Updater.
|
||
|
||
Entwickelt von **[Loheide.eu](https://loheide.eu)**
|
||
|
||

|
||

|
||

|
||

|
||

|
||
[](https://git.loheide.cloud/friloo/Unifi-Voucher-Tool/actions)
|
||
[](https://git.loheide.cloud/friloo/Unifi-Voucher-Tool)
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
<img src="docs/screenshots/voucher-result.png" alt="Erstellter Voucher mit QR-Code" width="48%">
|
||
<img src="docs/screenshots/admin-dashboard.png" alt="Admin Dashboard" width="48%">
|
||
</div>
|
||
|
||
---
|
||
|
||
## ✨ Features
|
||
|
||
- 🎟️ **Voucher-Erstellung** mit sofortiger QR-Code-Anzeige, Druckvorlage und E-Mail-Versand
|
||
- 🖥️ **Display-Seiten (Kiosk)** – öffentliche Seite je Site, an der Gäste sich mit einem Klick selbst einen Zugang holen
|
||
- 🎨 **Jede Display-Seite eigenständig gestaltbar** – Logo, Hintergrundbild, Akzentfarbe, helle oder dunkle Karte
|
||
- 📦 **Bulk-Erstellung** – bis zu 20 Vouchers auf einmal, inkl. Sammeldruck-Layout
|
||
- 🧩 **Voucher-Profile/Templates** – vordefinierte Laufzeiten & Gerätelimits per Schnellauswahl
|
||
- 🏢 **Multi-Site-Support** – beliebig viele UniFi-Standorte zentral verwalten
|
||
- 👥 **Benutzerverwaltung** mit granularer Site-Zugriffskontrolle
|
||
- 🔐 **Authentifizierung** via lokale Accounts **oder** Microsoft 365 OAuth
|
||
- 🔒 **2FA (TOTP)** – optional, mit Recovery-Codes & erzwingbarer Admin-Pflicht
|
||
- 📈 **Reporting** – Auswertungen mit Charts und CSV-/PDF-Export
|
||
- 🩺 **Health-Endpoint** (`/health.php`) für Monitoring/Uptime
|
||
- 🔑 **Passwort-Reset** per E-Mail (token-basiert, zeitlich begrenzt)
|
||
- 🚦 **Bandbreiten- & Datenlimits** pro Voucher/Profil (UniFi QoS)
|
||
- 🧰 **REST-API mit API-Schlüsseln** – Scopes (read/write), Rate-Limit, OpenAPI-Spec
|
||
- 🪪 **Single Sign-On** via generisches OpenID Connect (zusätzlich zu M365)
|
||
- 📲 **SMS-Versand** der Codes (Twilio) · **CSV-Batch-Import** von Vouchern
|
||
- 🤖 **CAPTCHA** (Rechenaufgabe oder hCaptcha) im öffentlichen Modus
|
||
- 🗄️ **DB-gestützte Sessions** (opt-in) mit „überall abmelden"
|
||
- 🔔 **Webhooks** (Slack / Teams / generisch) für Erstellung, Ausfälle, neue Login-IP
|
||
- 🧹 **Auto-Cleanup & DSGVO** – Aufbewahrungsfristen per Cron
|
||
- 💾 **Config-Backup & -Restore** (JSON Export/Import)
|
||
- 🐳 **Docker** – Dockerfile + docker-compose (MariaDB)
|
||
- 🌍 **Öffentlicher Modus** – optional ohne Login nutzbar (mit CSRF-Schutz & Throttle)
|
||
- 🎨 **Einheitliches Design-System** – ein Stylesheet für Frontend, Login und Backend (Tokens, Komponenten, Light/Dark)
|
||
- 🏷️ **Login-Seite individualisierbar** – Firmenname, Logo, Texte, Hintergrundbild bzw. Farbverlauf
|
||
- 🖌️ **Eigene Markenfarben** – Akzentfarbe, Verlauf und Eckenradius wirken auf die gesamte Oberfläche
|
||
- ⬆️ **Bild-Upload** für Logo, Favicon und Login-Hintergrund (kein externes Hosting nötig)
|
||
- 🔒 **Keine externen CDNs** – Schrift, Icons, Diagramme und Editor werden lokal ausgeliefert (DSGVO, Offline-Netze)
|
||
- ♿ **Barrierearm** – Kontraste nach WCAG AA, Sprungmarke, aria-Beschriftungen, `prefers-reduced-motion`
|
||
- 📱 **Mobil nutzbar** – Tabellen werden auf schmalen Geräten zu Karten
|
||
- 🌗 **Dark Mode** – umschaltbar, Einstellung wird im Browser gespeichert
|
||
- 🌐 **Mehrsprachig** – Deutsch / Englisch per Umschalter (`lang/`)
|
||
- 📱 **Responsive Admin-Layout** mit Hamburger-Menü & Sidebar-Overlay
|
||
- 📊 **Admin-Dashboard** mit Live-Statistiken und Sync-Funktion
|
||
- 📝 **Audit-Log** – nachvollziehbare Protokollierung von Login & Änderungen (mit Filter)
|
||
- 📥 **CSV-Export** aller Vouchers pro Site
|
||
- 🔄 **Integrierter Auto-Updater** – Updates & DB-Migrationen 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
|
||
|
||
> Alle Screenshots stammen aus der Oberfläche in Version 2.5.0 (neues Design-System).
|
||
|
||
### Anmeldung & Voucher-Erstellung
|
||
|
||
<div align="center">
|
||
<img src="docs/screenshots/login.png" alt="Anmeldung" width="48%">
|
||
<img src="docs/screenshots/login-branding.png" alt="Anmeldung mit eigenem Branding" width="48%">
|
||
</div>
|
||
|
||
<div align="center">
|
||
<img src="docs/screenshots/voucher-form.png" alt="Voucher erstellen" width="48%">
|
||
<img src="docs/screenshots/settings-login.png" alt="Einstellungen der Login-Seite" width="48%">
|
||
</div>
|
||
|
||
### Display-Seite für Gäste
|
||
|
||
<div align="center">
|
||
<img src="docs/screenshots/kiosk-display.png" alt="Display-Seite im Ruhezustand" width="48%">
|
||
<img src="docs/screenshots/kiosk-branded.png" alt="Display-Seite mit eigenem Bild und Farben" width="48%">
|
||
</div>
|
||
|
||
<div align="center">
|
||
<img src="docs/screenshots/kiosk-code.png" alt="Ausgegebener Zugangscode auf dem Display" width="48%">
|
||
<img src="docs/screenshots/kiosks-form.png" alt="Display-Seite einrichten" width="48%">
|
||
</div>
|
||
|
||
<div align="center">
|
||
<img src="docs/screenshots/voucher-result.png" alt="Voucher-Ergebnis mit QR-Code" width="48%">
|
||
<img src="docs/screenshots/bulk-vouchers.png" alt="Bulk-Voucher-Erstellung" width="48%">
|
||
</div>
|
||
|
||
### Administration
|
||
|
||
<div align="center">
|
||
<img src="docs/screenshots/admin-dashboard.png" alt="Dashboard" width="48%">
|
||
<img src="docs/screenshots/admin-dashboard-dark.png" alt="Dashboard im Dark Mode" width="48%">
|
||
</div>
|
||
|
||
<div align="center">
|
||
<img src="docs/screenshots/vouchers.png" alt="Live-Voucher-Verwaltung" width="48%">
|
||
<img src="docs/screenshots/settings.png" alt="Einstellungen" width="48%">
|
||
</div>
|
||
|
||
<div align="center">
|
||
<img src="docs/screenshots/settings-branding.png" alt="Markenfarben einstellen" width="48%">
|
||
<img src="docs/screenshots/mobile-vouchers.png" alt="Ansicht auf dem Smartphone" width="22%">
|
||
</div>
|
||
|
||
### REST-API, 2FA & Integrationen
|
||
|
||
<div align="center">
|
||
<img src="docs/screenshots/api-keys.png" alt="API-Schlüssel-Verwaltung" width="48%">
|
||
<img src="docs/screenshots/integrations.png" alt="Integration & Wartung" width="48%">
|
||
</div>
|
||
|
||
<div align="center">
|
||
<img src="docs/screenshots/two-factor.png" alt="Zwei-Faktor-Authentifizierung" width="60%">
|
||
</div>
|
||
|
||
### Updater & Wartungsmodus
|
||
|
||
<div align="center">
|
||
<img src="docs/screenshots/updater.png" alt="Updater – Ausgangszustand" width="48%">
|
||
<img src="docs/screenshots/updater-available.png" alt="Auto-Updater mit verfügbarem Update" width="48%">
|
||
</div>
|
||
|
||
<div align="center">
|
||
<img src="docs/screenshots/maintenance.png" alt="Wartungsmodus" width="60%">
|
||
</div>
|
||
|
||
---
|
||
|
||
## 📋 Anforderungen
|
||
|
||
| Komponente | Version |
|
||
|---|---|
|
||
| PHP | 8.1+ (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://git.loheide.cloud/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
|
||
- **Zertifikat des Controllers prüfen:** optional, siehe unten
|
||
3. **Verbindung testen** klicken, dann speichern
|
||
|
||
> **Zertifikatsprüfung:** UniFi-Geräte liefern ab Werk ein selbst signiertes
|
||
> Zertifikat, deshalb ist die Prüfung standardmäßig **aus** – sonst käme keine
|
||
> Verbindung zustande. Läuft der Controller unter seinem echten Namen mit einem
|
||
> gültigen Zertifikat (eigene CA oder Let's Encrypt), schalten Sie die Prüfung
|
||
> pro Site ein; die Verbindung ist dann gegen Man-in-the-Middle abgesichert.
|
||
> Für den Mailversand gibt es denselben Schalter unter **Einstellungen → SMTP**.
|
||
|
||
### 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
|
||
|
||
---
|
||
|
||
## 🔄 Selbst-Updater
|
||
|
||
Eine laufende Installation aktualisiert sich per Klick im Administrationsbereich
|
||
– **ohne SSH und ohne `git pull` auf dem Server**. Quellcode und
|
||
Datenbank-Migrationen kommen über einen Update-Dienst, der den aktuellen Stand
|
||
des Branches als ZIP bereitstellt.
|
||
|
||
```
|
||
[diese Installation] ←HTTPS→ [Update-Dienst] ←pull→ [Git-Repository]
|
||
```
|
||
|
||
**Aufruf:** Administration → **Aktualisierung** (`/admin/update.php`)
|
||
|
||
- 🔍 **„Nach Updates suchen"** zeigt, ob eine neue Fassung da ist, welche Version
|
||
sie trägt und – sofern der Dienst etwas liefert – die Abschnitte aus dem
|
||
Änderungsprotokoll. Gibt es dazu nichts, bleibt es bei der schlichten Aussage
|
||
„neue Fassung verfügbar"
|
||
- ⬇️ **„Jetzt aktualisieren"** spielt sie ein: Wartungsseite, Prüfsumme, gesichertes
|
||
Entpacken, geschützte Pfade, Migrationen, Bytecode-Cache. Der Fortschritt wird
|
||
alle zwei Sekunden abgefragt; der Ablauf läuft serverseitig weiter, auch wenn
|
||
der Browser die Verbindung kappt
|
||
- 🔀 **Kanal** zwischen `stable` und `development` umschaltbar
|
||
- 📊 **Migrationen** mit Status je Datei und Schaltfläche zum Nachziehen
|
||
- 📜 **Änderungsprotokoll** aus der mitgelieferten `CHANGELOG.md`
|
||
|
||
Während eines Updates antwortet die Anwendung mit einer **Wartungsseite** (HTTP
|
||
503 samt `Retry-After`) – ausgenommen die Update-Endpunkte selbst, die
|
||
Anmeldeseite und der Health-Check, damit der Fortschritt sichtbar bleibt:
|
||
|
||
<div align="center">
|
||
<img src="docs/screenshots/maintenance.png" alt="Wartungsmodus" width="60%">
|
||
</div>
|
||
|
||
**Was dabei geschützt ist:** `config.php`, `uploads/`, `vendor/`,
|
||
`updater/storage/` und weitere Pfade werden nie überschrieben. Dateien werden
|
||
einzeln erst daneben geschrieben und dann umbenannt, damit ein Abbruch keine
|
||
halbe PHP-Datei hinterlässt. Gelöscht wird nichts. Das Paket wird gegen die vom
|
||
Dienst genannte SHA-256 geprüft, und beim Entpacken verhindern zwei
|
||
unabhängige Prüfungen, dass ein Archiv aus seinem Verzeichnis ausbricht.
|
||
|
||
> **Datenschutz:** Die Update-Prüfung überträgt den installierten Stand sowie
|
||
> technisch bedingt IP-Adresse und Zeitpunkt an `update.loheide.cloud`. Inhalte
|
||
> aus dem Programm werden nicht übertragen. Der vollständige Hinweis steht
|
||
> dauerhaft auf der Seite „Aktualisierung", direkt neben der Schaltfläche.
|
||
|
||
Architektur, Sicherheitseigenschaften und eine Rückbau-Anleitung stehen in
|
||
[`updater/README.md`](updater/README.md).
|
||
|
||
### Eine neue Fassung veröffentlichen
|
||
|
||
1. `CHANGELOG.md`: Abschnitt `## MAJOR.MINOR.PATCH – Datum` ergänzen
|
||
2. `Updater\Version::RELEASE` und die Datei `VERSION` anheben (Patch =
|
||
Fehlerbehebung, Minor = Funktion) – ein Test prüft, dass beide übereinstimmen
|
||
3. `composer test` und `composer stan` grün, kompilierte Assets mitversionieren
|
||
(beim Anwender läuft kein Build)
|
||
4. Merge nach `main` – sobald der Dienst den Stand gespiegelt hat, bieten ihn
|
||
alle Installationen an
|
||
|
||
---
|
||
|
||
## 🖥️ Display-Seiten für Gäste
|
||
|
||
Für Empfang, Lobby oder Tagungsraum lässt sich je Site eine **öffentliche Seite**
|
||
anlegen, die auf einem Bildschirm oder Tablet läuft. Gäste tippen auf einen
|
||
Knopf und bekommen sofort einen eigenen Zugangscode – ohne Anmeldung, ohne
|
||
Personal am Tresen.
|
||
|
||
**Anlegen:** Administration → **Display-Seiten** → *Display-Seite anlegen*
|
||
|
||
<div align="center">
|
||
<img src="docs/screenshots/kiosks-admin.png" alt="Verwaltung der Display-Seiten" width="80%">
|
||
</div>
|
||
|
||
| Einstellung | Wirkung |
|
||
|---|---|
|
||
| Site | für welchen Standort die Codes erzeugt werden |
|
||
| Voucher-Profil | Laufzeit, Geräteanzahl und Bandbreite der Codes (leer = Standardwerte) |
|
||
| Überschrift / Text | was auf dem Bildschirm steht |
|
||
| Codes pro Tag | Obergrenze je Kalendertag (0 = unbegrenzt) |
|
||
| Wartezeit | Abstand zwischen zwei Codes an diesem Display |
|
||
| Wartezeit je Gerät | zusätzliche Sperre pro Browser (Cookie) – gegen das Leerziehen durch eine Person |
|
||
| Servicezeiten | z. B. 06:00–23:00; außerhalb erscheint ein Hinweis statt des Knopfes. Fenster über Mitternacht möglich |
|
||
| PIN | optionale Eingabe, sinnvoll bei frei zugänglichen Bildschirmen |
|
||
| Sprache | feste Sprache des Displays oder automatisch nach Browsersprache |
|
||
| Anzeigedauer | danach springt der Bildschirm automatisch zurück |
|
||
|
||
Jede Seite hat einen **eigenen, geheimen Link** (`kiosk.php?k=…`). Er lässt sich
|
||
kopieren, als QR-Code anzeigen (praktisch, um ihn am Tablet zu öffnen) und
|
||
jederzeit erneuern – der alte Link ist dann sofort ungültig. Den Link nicht
|
||
öffentlich verbreiten: wer ihn hat, kann im Rahmen der Limits Codes ziehen.
|
||
|
||
Auf dem Startbildschirm steht zusätzlich ein QR-Code, der auf dieselbe Seite
|
||
zeigt. Gäste können sie damit **am eigenen Handy** öffnen – praktisch bei
|
||
Bildschirmen ohne Touch.
|
||
|
||
### Jede Seite eigenständig gestalten
|
||
|
||
Jede Display-Seite bringt ihr eigenes Erscheinungsbild mit – das Hotel am
|
||
Empfang sieht anders aus als der Tagungsraum nebenan:
|
||
|
||
| Einstellung | Wirkung |
|
||
|---|---|
|
||
| Logo | eigenes Logo auf der Karte (leer = Logo aus den Einstellungen) |
|
||
| Hintergrundbild | formatfüllend hinter der Karte, z. B. ein Foto des Hauses |
|
||
| Abdunklung | 0–90 % dunkle Ebene über dem Bild, damit die Karte lesbar bleibt |
|
||
| Akzentfarbe | färbt den Knopf dieser Seite (leer = Farbe aus dem Design-Tab) |
|
||
| Karte | hell oder dunkel – auf Fotos wirkt die dunkle Karte meist ruhiger |
|
||
|
||
Logo und Hintergrund lassen sich direkt hochladen (PNG, JPG, WEBP, GIF, SVG bis
|
||
3 MB) oder als URL hinterlegen; beim Löschen einer Display-Seite verschwinden
|
||
die hochgeladenen Dateien mit.
|
||
|
||
Die ausgegebenen Codes erscheinen normal in *Live Vouchers*, im *Reporting* –
|
||
dort gibt es eine eigene Auswertung **„Pro Display-Seite"** – und im *Audit-Log*
|
||
(Aktion „Voucher am Display geholt"), sodass jederzeit nachvollziehbar bleibt,
|
||
woher ein Zugang stammt.
|
||
|
||
In der Verwaltung zeigt **„Vorschau"** die Seite direkt im Admin-Bereich, ohne
|
||
den Tab zu wechseln. Gäste können die Sprache unten auf dem Display selbst
|
||
umschalten.
|
||
|
||
> Display-Seiten funktionieren unabhängig vom globalen öffentlichen Modus – der
|
||
> geheime Link ist der Zugang. Webhook-Benachrichtigungen werden für diese Codes
|
||
> bewusst **nicht** ausgelöst, sonst wäre der Slack-Kanal voll.
|
||
|
||
---
|
||
|
||
## ⚙️ Konfiguration
|
||
|
||
### `config.php`
|
||
|
||
Wird automatisch durch den Installer erstellt:
|
||
|
||
```php
|
||
<?php
|
||
define('DB_HOST', 'localhost');
|
||
define('DB_NAME', 'unifi_voucher');
|
||
define('DB_USER', 'username');
|
||
define('DB_PASS', 'password');
|
||
define('APP_KEY', '...'); // Schlüssel für Verschlüsselung-at-rest
|
||
define('SESSION_LIFETIME', 3600); // Session-Timeout in Sekunden
|
||
date_default_timezone_set('Europe/Berlin');
|
||
```
|
||
|
||
### Microsoft 365 OAuth (optional)
|
||
|
||
1. Im [Azure Portal](https://portal.azure.com) eine App-Registrierung anlegen
|
||
2. Umleitungs-URI: `https://ihre-domain.de/m365_callback.php`
|
||
3. API-Berechtigungen: `openid`, `profile`, `email`, `User.Read`
|
||
4. Client ID, Client Secret und Tenant ID in **Administration → Einstellungen** eintragen
|
||
|
||
### Cron-Job (empfohlen)
|
||
|
||
Automatische Synchronisation alle 30 Minuten:
|
||
|
||
```bash
|
||
*/30 * * * * curl -s "https://ihre-domain.de/cron_sync.php?token=IHR_CRON_TOKEN"
|
||
```
|
||
|
||
Den Token finden Sie unter **Administration → Einstellungen → Cron**.
|
||
|
||
---
|
||
|
||
## 🎨 Design-System
|
||
|
||
Frontend, Login-Seiten, Installer, Updater und der gesamte Admin-Bereich nutzen ein
|
||
gemeinsames Stylesheet: **`assets/global.css`**.
|
||
|
||
- **Design-Tokens** (`:root` bzw. `[data-theme="dark"]`) für Flächen, Text, Linien,
|
||
Markenfarbe, Statusfarben, Radien, Schatten und Layout-Maße
|
||
- **Komponenten** darauf aufgebaut: Buttons, Formularfelder, Cards, Tabellen, Badges,
|
||
Alerts, Tabs, Pagination, Modals, Toasts, Statistik-Kacheln, Sidebar/Topbar
|
||
- **Dark Mode** ausschließlich über Tokens – keine `!important`-Overrides mehr
|
||
- **Schriftart** Inter (via Google Fonts) mit System-Font-Fallback
|
||
|
||
### Markenfarben ohne Code
|
||
|
||
Unter **Administration → Einstellungen → Design** lassen sich Akzentfarbe
|
||
(hell und dunkel), Markenverlauf und Eckenradius setzen. Abgeleitete Töne –
|
||
Hover, weiche Flächen, Rahmen, Fokusring – berechnet das System per `color-mix`
|
||
aus der Grundfarbe; eine Farbe genügt also. Eine Live-Vorschau zeigt Button,
|
||
Badge, Chip und Logo-Kachel sofort im neuen Ton.
|
||
|
||
Die Werte landen als schlanker `:root`-Override im Seitenkopf und gelten überall,
|
||
auch auf Login-Seite, Installer und Updater. Wer lieber in CSS arbeitet, kann
|
||
dieselben Variablen weiterhin in `assets/global.css` überschreiben:
|
||
|
||
```css
|
||
:root {
|
||
--accent: #0f766e; /* Primärfarbe (Buttons, aktive Navigation) */
|
||
--brand-gradient: linear-gradient(135deg, #0f766e 0%, #0ea5e9 100%);
|
||
--r-lg: 14px; /* Eckenradius für Cards */
|
||
}
|
||
```
|
||
|
||
### Bilder hochladen
|
||
|
||
Logo, Favicon, Login-Logo und Login-Hintergrund lassen sich direkt hochladen –
|
||
alternativ bleibt das URL-Feld bestehen. Die Dateien landen unter `uploads/`
|
||
(Docker: eigenes Volume, siehe unten). Erlaubt sind PNG, JPG, WEBP, GIF und SVG
|
||
bis 3 MB; SVGs werden vor dem Speichern von Skripten und externen Verweisen
|
||
befreit, und im Upload-Ordner sperrt eine `.htaccess` die PHP-Ausführung.
|
||
|
||
### Assets ohne Drittanbieter
|
||
|
||
Schrift (Inter), Icons (Font Awesome), Diagramme (Chart.js), QR-Codes und der
|
||
WYSIWYG-Editor (TinyMCE) liegen unter `assets/vendor/` und kommen vom eigenen
|
||
Server. Das hält Besucher-IPs bei Ihnen – und die Oberfläche funktioniert auch
|
||
dort, wo das Netz keinen Weg nach außen hat. Details und Aktualisierungs-Hinweise:
|
||
[`assets/vendor/README.md`](assets/vendor/README.md).
|
||
|
||
Alle Asset-URLs tragen einen Versionsstempel (`?v=…`), damit Browser nach einem
|
||
Update nicht die alten Dateien aus dem Cache verwenden.
|
||
|
||
### Login-Seite individualisieren
|
||
|
||
Unter **Administration → Einstellungen → Login-Seite** lässt sich die Anmeldeseite
|
||
ohne Code-Änderung an das eigene Haus anpassen. Leere Felder verwenden jeweils den
|
||
Standardwert – eine frische Installation sieht also unverändert aus.
|
||
|
||
| Einstellung | Wirkung |
|
||
|---|---|
|
||
| Linke Bildspalte anzeigen | Split-Screen an/aus. Aus = zentrierte Anmeldekarte |
|
||
| Firmenname | Name neben dem Logo bzw. in der Fußzeile (leer = Anwendungstitel) |
|
||
| Logo (URL) | Eigenes Logo in der Bildspalte (leer = allgemeines Logo) |
|
||
| Überschrift / Beschreibungstext | Claim in der Bildspalte |
|
||
| Stichpunkte | Liste mit Haken – ein Stichpunkt pro Zeile, leer = keine Liste |
|
||
| Fußzeile | z. B. `© 2026 Muster GmbH · Datenschutz · Impressum` |
|
||
| Hintergrundbild (URL) | Formatfüllendes Bild der Bildspalte |
|
||
| Verlauf Start-/Endfarbe | Farbverlauf, wenn kein Bild gesetzt ist |
|
||
| Abdunklung (%) | Dunkle Ebene über dem Bild, damit der Text lesbar bleibt |
|
||
|
||
Über **„Vorschau öffnen"** lässt sich die Login-Seite als angemeldeter Administrator
|
||
ansehen (`login.php?preview=1`), ohne sich abzumelden.
|
||
|
||
---
|
||
|
||
## 🛡️ Sicherheit
|
||
|
||
Das Tool ist auf einen sicheren Standardbetrieb ausgelegt:
|
||
|
||
| Schutz | Umsetzung |
|
||
|---|---|
|
||
| **Passwörter** | bcrypt (`password_hash`) für Accounts |
|
||
| **UniFi-Passwörter** | Verschlüsselt-at-rest (AES-256-GCM / libsodium) über `APP_KEY` |
|
||
| **SQL-Injection** | Durchgängig Prepared Statements (PDO) |
|
||
| **CSRF** | Token für alle schreibenden Aktionen – auch im öffentlichen Modus |
|
||
| **OAuth** | `state`-Validierung gegen Login-CSRF |
|
||
| **Brute-Force** | Login-Rate-Limiting + Throttle der öffentlichen Voucher-Erstellung |
|
||
| **Sessions** | HttpOnly, SameSite, strict mode + absolutes Timeout |
|
||
| **TLS zum Controller** | Zertifikatsprüfung pro Site einschaltbar (aus, solange der Controller self-signed ist) |
|
||
| **Fehler** | `display_errors` aus, `log_errors` an (kein Info-Leak) |
|
||
|
||
Mitgeliefert wird eine `.htaccess` im Projektstamm mit Sicherheits-Headern
|
||
(`X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`,
|
||
`Permissions-Policy` und einer Content-Security-Policy). Da alle Assets lokal
|
||
liegen, erlaubt die CSP nur noch die eigene Herkunft – externe Verbindungen
|
||
bleiben lediglich für hCaptcha offen, falls es aktiviert wird. Ordner wie
|
||
`includes/`, `tools/`, `tests/` und `uploads/` schützen sich über eigene
|
||
`.htaccess`-Dateien.
|
||
|
||
> **Apache:** `AllowOverride All` muss für das Verzeichnis gesetzt sein, sonst
|
||
> werden die `.htaccess`-Dateien ignoriert. Das mitgelieferte Docker-Image
|
||
> erledigt das bereits.
|
||
|
||
> **Caddy liest keine `.htaccess`.** Läuft das Tool hinter Caddy, müssen die
|
||
> Regeln in den Caddyfile – eine fertige Vorlage liegt unter
|
||
> [`docs/Caddyfile.example`](docs/Caddyfile.example). Besonders wichtig ist
|
||
> dort die Sperre, die PHP-Dateien unterhalb von `uploads/` nicht ausführt.
|
||
|
||
Für **Nginx** entspricht das:
|
||
|
||
```nginx
|
||
add_header X-Content-Type-Options "nosniff" always;
|
||
add_header X-Frame-Options "SAMEORIGIN" always;
|
||
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
|
||
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; frame-ancestors 'self'" always;
|
||
|
||
location ~ ^/(includes|tools|tests)/ { deny all; }
|
||
location ~ ^/updater/(storage|migrations)/ { deny all; }
|
||
location ~ ^/(config\.php|database\.sql)$ { deny all; }
|
||
location ^~ /uploads/ { location ~ \.php$ { deny all; } }
|
||
```
|
||
|
||
```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
|
||
|
||
<details>
|
||
<summary><b>Login funktioniert nicht</b></summary>
|
||
|
||
- Datenbankverbindung und PHP-Session-Konfiguration prüfen
|
||
- Fehler werden ins PHP-Error-Log geschrieben (nicht mehr in den Browser)
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>UniFi-Verbindung schlägt fehl</b></summary>
|
||
|
||
- 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
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>UniFi OS: HTTP 404 oder 401</b></summary>
|
||
|
||
- 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
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>Microsoft 365 Login funktioniert nicht</b></summary>
|
||
|
||
- Redirect URI in Azure AD prüfen
|
||
- Client ID, Secret und Tenant ID kontrollieren
|
||
</details>
|
||
|
||
---
|
||
|
||
## 📡 API-Dokumentation (UniFi OS)
|
||
|
||
```http
|
||
# Login
|
||
POST /api/auth/login
|
||
Body: {"username": "admin", "password": "password"}
|
||
Response-Header: X-CSRF-Token: <token>
|
||
|
||
# Voucher erstellen
|
||
POST /proxy/network/api/s/{site_id}/cmd/hotspot
|
||
X-CSRF-Token: <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": "<voucher_id>"}
|
||
```
|
||
|
||
---
|
||
|
||
## 🧰 REST-API
|
||
|
||
Voucher lassen sich programmatisch erstellen (z. B. aus Buchungssystemen oder
|
||
Self-Service-Terminals). Schlüssel werden unter **Administration → API-Schlüssel**
|
||
verwaltet. Authentifizierung per `Authorization: Bearer <key>` oder `X-API-Key`.
|
||
|
||
```bash
|
||
# Voucher erstellen
|
||
curl -X POST https://ihre-domain.de/api/vouchers.php \
|
||
-H "Authorization: Bearer uvt_…" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"site_id":1,"name":"API Gast","max_uses":1,"expire_minutes":480,
|
||
"qos":{"down":10000,"up":2000,"quota_mb":500}}'
|
||
|
||
# Sites auflisten
|
||
curl https://ihre-domain.de/api/sites.php -H "X-API-Key: uvt_…"
|
||
|
||
# Voucher einer Site abrufen
|
||
curl "https://ihre-domain.de/api/vouchers.php?site_id=1" -H "X-API-Key: uvt_…"
|
||
```
|
||
|
||
| Methode | Endpunkt | Zweck |
|
||
|---|---|---|
|
||
| `POST` | `/api/vouchers.php` | Voucher erstellen (optional mit QoS-Limits) |
|
||
| `GET` | `/api/vouchers.php?site_id=<id>` | Voucher einer Site auflisten |
|
||
| `GET` | `/api/sites.php` | Aktive Sites auflisten |
|
||
|
||
## 🔒 2FA, Webhooks & Wartung
|
||
|
||
- **2FA:** Unter **Administration → Sicherheit (2FA)** aktivierbar – QR-Code
|
||
scannen, Code bestätigen. Danach wird bei jeder Anmeldung ein Authenticator-
|
||
Code abgefragt.
|
||
- **Webhooks & Trusted-Proxy & Datenhaltung:** unter **Administration →
|
||
Integration & Wartung** konfigurierbar.
|
||
- **Auto-Cleanup (DSGVO):** täglicher Cron, löscht abgelaufene Voucher,
|
||
Audit-Log, Login-Versuche nach einstellbaren Fristen:
|
||
```bash
|
||
0 3 * * * curl -s "https://ihre-domain.de/cron_cleanup.php?token=IHR_CRON_TOKEN"
|
||
```
|
||
|
||
## 🐳 Docker
|
||
|
||
```bash
|
||
# APP_KEY erzeugen und in docker-compose.yml eintragen:
|
||
php -r 'echo base64_encode(random_bytes(32))."\n";'
|
||
|
||
docker compose up -d # App auf http://localhost:8080
|
||
```
|
||
|
||
Das Schema wird beim ersten Start automatisch in MariaDB geladen; danach den
|
||
Installer (`/install.php`) für den Admin-Account aufrufen oder Config per ENV
|
||
setzen (`DB_*`, `APP_KEY`).
|
||
|
||
Hochgeladene Logos und Hintergründe liegen im Volume `uploads` und überstehen
|
||
damit ein Image-Update. Bei eigener Apache-/Nginx-Installation muss `uploads/`
|
||
für den Webserver beschreibbar sein:
|
||
|
||
```bash
|
||
chown -R www-data:www-data uploads updater/storage
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 Entwicklung
|
||
|
||
Für Screenshots und einen schnellen Durchlauf aller Seiten gibt es eine
|
||
Demo-Instanz **ohne Datenbank** – `Database` und `Auth` werden durch Stubs mit
|
||
festen Beispieldaten ersetzt:
|
||
|
||
```bash
|
||
python3 tools/demo/build.py /tmp/uvt-demo
|
||
php -S 127.0.0.1:8123 -t /tmp/uvt-demo &
|
||
|
||
# Bilder in docs/screenshots neu erzeugen (benötigt headless Chromium)
|
||
CHROME_BIN=/usr/bin/chromium python3 tools/screenshots.py
|
||
```
|
||
|
||
Details und die verfügbaren Demo-Zustände: [`tools/README.md`](tools/README.md).
|
||
|
||
Tests und statische Analyse:
|
||
|
||
```bash
|
||
composer install
|
||
vendor/bin/phpunit # 62 Tests
|
||
vendor/bin/phpstan analyse # Level 5
|
||
```
|
||
|
||
Die Tests decken die Stellen ab, an denen Fehler teuer werden:
|
||
|
||
| Bereich | Was geprüft wird |
|
||
|---|---|
|
||
| `AuthTest` | Anmeldung, Rate-Limit, 2FA-Zwischenschritt, CSRF, Client-IP hinter Proxy |
|
||
| `UniFiControllerTest` | Auswahl des eigenen Vouchers bei parallelen Anfragen, QoS-Payload, Fehlerfälle |
|
||
| `KioskTest` | Token-Prüfung, Wartezeit, Tageslimit, Gestaltung |
|
||
| `UploadTest` | SVG-Filter und Pfad-Prüfung |
|
||
| `UiTest` | Versionsstempel, Media-Pfade, Branding-Overrides |
|
||
| `CryptoTest`, `TotpTest`, `ApiKeyTest` | Verschlüsselung, Einmalcodes, Schlüssel-Hashing |
|
||
|
||
`AuthTest` und `UniFiControllerTest` kommen ohne Datenbank und ohne erreichbaren
|
||
Controller aus: `Auth` nimmt die Datenbank über den Konstruktor entgegen, beim
|
||
Controller spielen die Tests aufgezeichnete API-Antworten ein.
|
||
|
||
Die Versionsnummer steht in der Datei **`VERSION`** im Projektstamm. Sie wird
|
||
im Admin-Bereich unten in der Seitenleiste angezeigt und benennt das
|
||
Release-Paket – für eine neue Version also dort (und im Badge oben) anheben.
|
||
|
||
Die Pipeline (`.github/workflows/ci.yml`) führt zusätzlich einen
|
||
Syntax-Check über alle PHP-Dateien aus und prüft, ob `lang/de.php` und
|
||
`lang/en.php` dieselben Schlüssel enthalten und jeder im Code verwendete
|
||
Schlüssel existiert. Dieselben Schritte lassen sich lokal ausführen.
|
||
|
||
---
|
||
|
||
## 📦 Repository & Mitwirken
|
||
|
||
Der Quellcode liegt auf der eigenen Forgejo-Instanz – **nicht** auf GitHub:
|
||
|
||
**<https://git.loheide.cloud/friloo/Unifi-Voucher-Tool>**
|
||
|
||
```bash
|
||
# HTTPS
|
||
git clone https://git.loheide.cloud/friloo/Unifi-Voucher-Tool.git
|
||
|
||
# SSH (Port 2222)
|
||
git clone ssh://git@git.loheide.cloud:2222/friloo/Unifi-Voucher-Tool.git
|
||
```
|
||
|
||
### Fertige Pakete
|
||
|
||
Jeder Merge nach `main` erzeugt automatisch ein installierbares ZIP
|
||
(`.github/workflows/release.yml`) und hängt es an das rollende Vorab-Release
|
||
**`latest-main`**:
|
||
|
||
**<https://git.loheide.cloud/friloo/Unifi-Voucher-Tool/releases>**
|
||
|
||
Das Paket enthält nur die Laufzeit-Dateien – `docs/`, `tests/`, `tools/` und die
|
||
CI-Konfiguration bleiben draußen (rund 1,4 MB). Wird ein Tag `v*` gepusht,
|
||
entsteht daraus ein reguläres Release mit derselben Mechanik.
|
||
|
||
> Beim **Update einer bestehenden Installation** `config.php`, `uploads/` und
|
||
> `updater/storage/` nicht überschreiben – oder gleich den eingebauten Updater
|
||
> verwenden, der genau diese Pfade schützt.
|
||
|
||
Gebaut wird das von einem **Forgejo-Actions-Runner**, der auf dem Server läuft.
|
||
Compose-Datei und Einrichtungsanleitung liegen in
|
||
[`tools/runner/`](tools/runner/README.md) – nötig für eine Neuinstallation oder
|
||
wenn der Runner ersetzt wird.
|
||
|
||
### Mitwirken
|
||
|
||
Fehlerberichte und Änderungsvorschläge laufen über die **Issues** und **Pull
|
||
Requests** dort. Für die Kommandozeile eignet sich [`tea`](https://gitea.com/gitea/tea),
|
||
die Gitea-/Forgejo-CLI:
|
||
|
||
```bash
|
||
tea pr create # Pull Request öffnen
|
||
tea issues ls # offene Tickets ansehen
|
||
```
|
||
|
||
> Die Workflows unter `.github/workflows/` werden von Forgejo Actions
|
||
> mitgelesen – geblieben sind `ci.yml` (Lint, Tests, statische Analyse) und
|
||
> `release.yml` (Release-ZIP). Das frühere `docker-publish.yml` veröffentlichte
|
||
> nach `ghcr.io` und stammte noch aus der GitHub-Zeit; es ist entfernt. Das
|
||
> Image wird stattdessen lokal gebaut (siehe Abschnitt **Docker**).
|
||
|
||
Der **Auto-Updater** ist davon unabhängig: er zieht seine Pakete über
|
||
`update.loheide.eu` (Channels `stable` und `development`) und nicht direkt aus
|
||
dem Git-Hoster.
|
||
|
||
---
|
||
|
||
## 📄 Lizenz
|
||
|
||
Der eigene Code steht unter der **MIT-Lizenz** – siehe [`LICENSE`](LICENSE).
|
||
Kurz gefasst: verwenden, ändern und weitergeben ist erlaubt, auch kommerziell,
|
||
solange Copyright- und Lizenzhinweis erhalten bleiben; eine Gewährleistung gibt
|
||
es nicht.
|
||
|
||
Mitgeliefert werden außerdem Bibliotheken Dritter unter ihren eigenen Lizenzen.
|
||
Die Übersicht mit allen Copyright-Angaben steht in
|
||
[`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md), die vollständigen
|
||
Lizenztexte liegen jeweils im zugehörigen Ordner unter `assets/vendor/`:
|
||
|
||
| Komponente | Version | Lizenz |
|
||
|---|---|---|
|
||
| Inter | 4.0 | SIL OFL 1.1 |
|
||
| Font Awesome Free | 6.4.0 | Icons CC BY 4.0 · Schriften SIL OFL 1.1 · Code MIT |
|
||
| Chart.js | 4.4.0 | MIT |
|
||
| qrcodejs | 1.0.0 | MIT |
|
||
| TinyMCE | 6.8.3 | MIT |
|
||
|
||
`LICENSE`, `THIRD-PARTY-NOTICES.md` und die Lizenzdateien der Bibliotheken sind
|
||
Teil jedes Release-ZIPs – wer die Anwendung weitergibt, gibt die Hinweise also
|
||
automatisch mit.
|
||
|
||
Dieselbe Übersicht steht in der laufenden Installation unter
|
||
**Administration → Integration & Wartung → Über diese Installation**, dort
|
||
zusammen mit Version und PHP-Version und mit Links auf die ausgelieferten
|
||
Lizenztexte.
|
||
|
||
---
|
||
|
||
## 🗺️ Roadmap
|
||
|
||
- [x] Voucher-Templates (vordefinierte Laufzeiten)
|
||
- [x] Bulk-Voucher-Erstellung
|
||
- [x] Mehrsprachigkeit (DE/EN)
|
||
- [x] Dark Mode
|
||
- [x] Passwort-Reset
|
||
- [x] Audit-Log
|
||
- [x] Auto-Updater mit DB-Migrationen
|
||
- [x] REST-API mit API-Schlüsseln
|
||
- [x] 2FA (TOTP), Webhooks, Bandbreitenlimits
|
||
- [x] Docker-Container
|
||
- [x] Erweiterte Reporting-Funktionen (CSV/PDF) + Health-Endpoint
|
||
- [x] 2FA-Recovery-Codes, API-Scopes/Rate-Limit/OpenAPI, Test-Suite (PHPUnit/PHPStan)
|
||
- [x] Gemeinsames Design-System für Frontend, Login und Backend
|
||
- [x] Branding über die Oberfläche (Farben, Logo, Login-Seite)
|
||
- [x] Assets lokal ausliefern (keine Drittanbieter-CDNs)
|
||
- [x] Vollständige englische Übersetzung des Admin-Bereichs
|
||
- [x] Display-Seiten: Selbstbedienung für Gäste am Bildschirm
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**Version 3.0.1** · Autor: **Friederich Loheide** · Lizenz: **MIT**
|
||
|
||
Entwickelt von **[Loheide.eu](https://loheide.eu)**
|
||
|
||
</div>
|