5b260022f8
Replace default Laravel README with project overview and link detailed Plesk deployment steps. Co-authored-by: Cursor <cursoragent@cursor.com>
171 lines
4.2 KiB
Markdown
171 lines
4.2 KiB
Markdown
# HexaHost Panel
|
||
|
||
Web-Panel zur Steuerung von **Proxmox VE**-VMs, **Traefik**-Routen (File Provider), **Plesk DNS** und Anbindung an **WHMCS 9** für Bestellung und Abrechnung.
|
||
|
||
**Repository:** `ssh://git@git.hexahost.dev:8006/smueller/HexaHost-Panel.git`
|
||
|
||
Produktions-URL (Ziel): [https://panel.hexahost.de](https://panel.hexahost.de)
|
||
|
||
Ausführliche Server-Anleitung: [DEPLOY.md](DEPLOY.md)
|
||
|
||
---
|
||
|
||
## Funktionen
|
||
|
||
| Bereich | Beschreibung |
|
||
|--------|----------------|
|
||
| **VM-Verwaltung** | Anlegen, Start/Stop/Reboot, Live-Status, Konsole (noVNC) |
|
||
| **Provisioning** | Queue-basiert mit Rollback (Proxmox → DNS → Traefik) |
|
||
| **WHMCS API** | HMAC-gesicherte Endpoints: Provision, Suspend, Terminate, Status |
|
||
| **Netzwerk** | Private IP-Pools (10.32.0.0/24), optionale öffentliche IPs |
|
||
| **Traefik** | YAML-Merge, atomisches Schreiben, Reload |
|
||
| **Snapshots** | Manuell + automatisch vor kritischen Aktionen, 48h Retention |
|
||
| **ISO-Upload** | Kunden-ISO auf Proxmox-Storage (Limits konfigurierbar) |
|
||
| **Backups** | vzdump → PBS (wenn `BACKUPS_ENABLED=true`) |
|
||
| **Firewall** | Regeln pro VM, Sync zu Proxmox |
|
||
| **Sicherheit** | 2FA-Pflicht für Admins, Login-Throttle, Policies pro Rolle |
|
||
| **Admin** | VM-Templates, System-Health, Benutzer, IP-Pools |
|
||
|
||
---
|
||
|
||
## Architektur
|
||
|
||
```
|
||
WHMCS 9 ──HMAC API──► Laravel Panel ──► Proxmox VE (Hyperion)
|
||
├──► Plesk DNS (A-Records)
|
||
└──► Traefik dynamic YAML + Reload
|
||
```
|
||
|
||
---
|
||
|
||
## Tech-Stack
|
||
|
||
- **PHP** 8.3+, **Laravel** 13
|
||
- **SQLite** (Entwicklung) / **MariaDB** (Produktion empfohlen)
|
||
- **Tailwind CSS 4**, **Vite**
|
||
- **Queue:** `database` (Worker erforderlich)
|
||
- **WHMCS-Modul:** `whmcs-module/hexahost/`
|
||
|
||
---
|
||
|
||
## Lokale Entwicklung
|
||
|
||
### Voraussetzungen
|
||
|
||
- PHP 8.3+, Composer, Node.js 20+
|
||
- Optional: Proxmox API-Token in `.env`
|
||
|
||
### Installation
|
||
|
||
```bash
|
||
git clone ssh://git@git.hexahost.dev:8006/smueller/HexaHost-Panel.git
|
||
cd HexaHost-Panel
|
||
|
||
composer install
|
||
cp .env.example .env
|
||
php artisan key:generate
|
||
php artisan migrate
|
||
php artisan db:seed --class=HostingSeeder
|
||
|
||
npm install
|
||
npm run build
|
||
```
|
||
|
||
### Starten
|
||
|
||
```bash
|
||
# Terminal 1 – App
|
||
php artisan serve
|
||
|
||
# Terminal 2 – Queue (Provisioning)
|
||
php artisan queue:work
|
||
|
||
# Terminal 3 – optional Assets
|
||
npm run dev
|
||
```
|
||
|
||
Standard-Admin nach Seeder: `admin@hexahost.local` / `admin1234` — **in Produktion sofort ändern.**
|
||
|
||
### Tests
|
||
|
||
```bash
|
||
npm run build
|
||
php artisan test
|
||
```
|
||
|
||
---
|
||
|
||
## Konfiguration
|
||
|
||
Alle hosting-spezifischen Werte liegen in `config/hosting.php` und werden über `.env` gesetzt. Vorlage: `.env.example`.
|
||
|
||
Wichtige Gruppen:
|
||
|
||
| Präfix | Zweck |
|
||
|--------|--------|
|
||
| `PROXMOX_*` | API, Node, Storage, ISO, PBS |
|
||
| `HOSTING_*` / `HOSTING_PUBLIC_*` | IP-Pools, Gateways, CIDR |
|
||
| `TRAEFIK_*` | Pfad zur dynamic config, Reload |
|
||
| `PLESK_*` | DNS-API |
|
||
| `WHMCS_*` | API-Secret, IP-Allowlist |
|
||
| `CONSOLE_PROXY_*` | WebSocket-Proxy (optional) |
|
||
|
||
**Niemals** `.env` committen (enthält Secrets).
|
||
|
||
---
|
||
|
||
## Geplante Aufgaben (Cron)
|
||
|
||
Der Laravel Scheduler muss **jede Minute** laufen (`php artisan schedule:run`):
|
||
|
||
| Command | Intervall |
|
||
|---------|-----------|
|
||
| `hosting:release-vmids` | alle 15 Min. |
|
||
| `hosting:purge-iso-uploads` | stündlich |
|
||
| `hosting:prune-snapshots` | stündlich |
|
||
| `hosting:collect-metrics` | alle 5 Min. |
|
||
|
||
---
|
||
|
||
## WHMCS
|
||
|
||
Server-Modul-Skeleton: `whmcs-module/hexahost/hexahost.php`
|
||
|
||
API-Basis: `https://panel.hexahost.de/api/whmcs/` (nur HMAC, kein offenes Hosting-API mehr).
|
||
|
||
`WHMCS_API_SECRET` in Panel-`.env` und im WHMCS-Modul identisch setzen.
|
||
|
||
---
|
||
|
||
## Console-Proxy (optional)
|
||
|
||
Direkte Browser-Verbindung zu Proxmox-VNC ist unsicher und oft blockiert. Empfohlen:
|
||
|
||
1. `CONSOLE_PROXY_ENABLED=true` in `.env`
|
||
2. Node-Proxy starten: `scripts/console-ws-proxy.mjs`
|
||
3. Reverse-Proxy `/ws/vm` → lokaler Port (siehe [DEPLOY.md](DEPLOY.md))
|
||
|
||
---
|
||
|
||
## Projektstruktur (Auszug)
|
||
|
||
```
|
||
app/Services/Hosting/
|
||
Proxmox/ # API-Client, VM-Management
|
||
Provisioning/ # Provision, Deprovision, IP, VMID
|
||
Traefik/ # YAML-Generator
|
||
Plesk/ # DNS
|
||
Snapshots/ # Snapshot-Service
|
||
...
|
||
routes/
|
||
web.php # Panel-UI
|
||
api.php # WHMCS + Console-Validate
|
||
whmcs-module/ # WHMCS 9 Server Module
|
||
```
|
||
|
||
---
|
||
|
||
## Lizenz
|
||
|
||
MIT (Laravel-Basis). Siehe `composer.json`.
|