ZMB Webui: Complete Project – Rebrand & Initial Clean Commit
ARCHITECTURE ============ Backend: FastAPI + uvicorn (port 8000) - JWT authentication with PAM system users - ZFS CLI wrapper with caching (30-60s TTL) - WebSocket pool status broadcaster (30s interval) - Services: auth, zfs_runner, file_manager, shares, identities, system_info - Routers: pools, datasets, snapshots, shares, identities, navigator, system Frontend: Next.js 15 + TypeScript (static export) - Incremental Static Regeneration (ISR) for weak hardware - Type-safe API client (lib/api.ts) - Dark mode + custom Tailwind theme - Pages: Dashboard, Login, Snapshots, Datasets, Shares, etc. DEPLOYMENT ========== Test Target: 192.168.1.179:8090 (Debian LXC) Production: 10.66.120.3:9090 (Raspberry Pi 4GB ARM64) Updater: Automated Gitea-based deployment (update-test.sh, update-pi.sh) FEATURES COMPLETED ================== Phase 3a: Dashboard Quick Stats (System, CPU, Memory, Storage) - Real-time stats with color-coded progress bars - Responsive grid layout (mobile: 1, tablet: 2, desktop: 4 columns) - ISR-optimized for fast loads on weak hardware REBRANDING ========== Renamed throughout: - Project: 'ZFS Manager' → 'ZMB Webui' - Services: 'zfs-manager' → 'zmb-webui' - Systemd units: zfs-manager-backend → zmb-webui-backend - Configuration files and documentation Co-Authored-By: Patrick <patrick@perlbach24.de>
This commit is contained in:
Claude Code
@@ -0,0 +1,219 @@
|
||||
# Phase 1: FastAPI Backend – Abgeschlossen ✓
|
||||
|
||||
## Was wurde gebaut
|
||||
|
||||
Komplettes FastAPI-Backend für ZMB Webui mit:
|
||||
- ✅ Alle ZFS-Operationen (Pool, Dataset, Snapshot)
|
||||
- ✅ File Manager (Browse, Upload, Download) wie cockpit-files
|
||||
- ✅ JWT Authentication mit bcrypt
|
||||
- ✅ Caching (30s-300s TTL)
|
||||
- ✅ Production-ready Systemd Service
|
||||
- ✅ User Management CLI Tool
|
||||
- ✅ Comprehensive Documentation
|
||||
|
||||
## Dateistruktur
|
||||
|
||||
```
|
||||
backend/
|
||||
├── main.py # FastAPI App (1-Click Run)
|
||||
├── requirements.txt # Python Dependencies
|
||||
├── install.sh # Auto-Installation für Pi
|
||||
├── manage_users.py # User Management CLI
|
||||
├── README.md # API Documentation
|
||||
│
|
||||
├── services/
|
||||
│ ├── zfs_runner.py # ZFS Subprocess Wrapper + Caching
|
||||
│ ├── auth.py # JWT Token Generation/Verification
|
||||
│ └── file_manager.py # File Browser, Upload, Download
|
||||
│
|
||||
├── routers/
|
||||
│ ├── auth.py # POST /api/auth/login
|
||||
│ ├── pools.py # GET/POST Pool Operations
|
||||
│ ├── datasets.py # GET/POST/DELETE Dataset CRUD
|
||||
│ ├── snapshots.py # GET/POST/DELETE Snapshot CRUD
|
||||
│ └── files.py # GET/POST/DELETE File Manager
|
||||
│
|
||||
├── models/
|
||||
│ ├── pool.py # Pool, PoolStatus, PoolHealth
|
||||
│ ├── dataset.py # Dataset, DatasetType
|
||||
│ ├── snapshot.py # Snapshot
|
||||
│ └── auth.py # User, Token, TokenData
|
||||
│
|
||||
└── config/
|
||||
└── users.json # Default Admin User
|
||||
|
||||
deploy/
|
||||
└── zmb-webui-backend.service # Systemd Service (2 Workers, 512MB RAM limit)
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Authentication
|
||||
```
|
||||
POST /api/auth/login # Login mit Username/Passwort
|
||||
POST /api/auth/verify # Token Verifikation
|
||||
```
|
||||
|
||||
### Pools
|
||||
```
|
||||
GET /api/pools # List aller Pools
|
||||
GET /api/pools/{name} # Pool Status + VDEV-Baum
|
||||
POST /api/pools/{name}/scrub # Start Scrub
|
||||
```
|
||||
|
||||
### Datasets
|
||||
```
|
||||
GET /api/datasets # List Datasets (max depth 2)
|
||||
POST /api/datasets # Create Dataset
|
||||
DELETE /api/datasets/{name} # Delete Dataset
|
||||
```
|
||||
|
||||
### Snapshots
|
||||
```
|
||||
GET /api/snapshots # List Snapshots (limit 50)
|
||||
POST /api/snapshots # Create Snapshot
|
||||
DELETE /api/snapshots/{name} # Delete Snapshot
|
||||
POST /api/snapshots/rollback # Rollback to Snapshot
|
||||
```
|
||||
|
||||
## Performance-Features (für 4GB RAM Pi)
|
||||
|
||||
✅ **Caching Layer:**
|
||||
- Pool Status: 30s TTL
|
||||
- Snapshots/Datasets: 60-120s TTL
|
||||
- In-Memory Cache (kein Redis nötig)
|
||||
|
||||
✅ **Resource Limits:**
|
||||
- gunicorn: 2 Worker
|
||||
- Memory: 512M soft / 768M hard
|
||||
- Timeout: 30s
|
||||
- Max Requests per Worker: 500 (Memory-Leak Prevention)
|
||||
|
||||
✅ **ZFS Optimization:**
|
||||
- Queries mit Depth-Limit (max 2 Ebenen)
|
||||
- Snapshots limitiert auf 50 (konfigurierbar)
|
||||
- Subprocess Timeout: 5s
|
||||
- Lazy Parsing (streaming output)
|
||||
|
||||
## Installation auf dem Pi
|
||||
|
||||
```bash
|
||||
# 1. Backend kopieren
|
||||
scp -r backend root@10.66.120.3:/tmp/zmb-webui-backend
|
||||
|
||||
# 2. Installation durchführen
|
||||
ssh root@10.66.120.3
|
||||
cd /tmp/zmb-webui-backend
|
||||
sudo bash install.sh
|
||||
|
||||
# 3. Service starten
|
||||
sudo systemctl start zmb-webui-backend
|
||||
sudo systemctl enable zmb-webui-backend
|
||||
|
||||
# 4. Test
|
||||
curl http://10.66.120.3:8000/health
|
||||
```
|
||||
|
||||
## Default Credentials
|
||||
|
||||
**Admin User (nach Installation):**
|
||||
- Username: `admin`
|
||||
- Password: `admin123`
|
||||
- ⚠️ SOFORT ÄNDERN!
|
||||
|
||||
```bash
|
||||
# Passwort ändern auf dem Pi:
|
||||
python3 /opt/zmb-webui/backend/manage_users.py change-password admin <newpassword>
|
||||
```
|
||||
|
||||
## Login-Flow
|
||||
|
||||
```bash
|
||||
# 1. Login
|
||||
curl -X POST http://10.66.120.3:8000/api/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"admin123"}'
|
||||
|
||||
# Response:
|
||||
# {"access_token":"eyJhbGc...","token_type":"bearer"}
|
||||
|
||||
# 2. API Request mit Token
|
||||
TOKEN="eyJhbGc..."
|
||||
curl http://10.66.120.3:8000/api/pools \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Lokal testen (ohne ZFS nötig)
|
||||
```bash
|
||||
# Nur Python-Syntax checken
|
||||
python3 -m py_compile main.py models/*.py routers/*.py services/*.py
|
||||
```
|
||||
|
||||
### Auf dem Pi testen
|
||||
```bash
|
||||
# Health Check
|
||||
curl http://10.66.120.3:8000/health
|
||||
|
||||
# Login
|
||||
curl -X POST http://10.66.120.3:8000/api/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"admin123"}'
|
||||
|
||||
# List Pools
|
||||
TOKEN="<token from login>"
|
||||
curl http://10.66.120.3:8000/api/pools \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# List Snapshots
|
||||
curl "http://10.66.120.3:8000/api/snapshots?limit=10" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Backend startet nicht
|
||||
```bash
|
||||
# Logs anschauen
|
||||
journalctl -u zmb-webui-backend -f
|
||||
|
||||
# Service Status
|
||||
systemctl status zmb-webui-backend
|
||||
```
|
||||
|
||||
### Memory-Probleme
|
||||
```bash
|
||||
# Memory Usage checken
|
||||
ps aux | grep uvicorn
|
||||
|
||||
# Service neustarten
|
||||
systemctl restart zmb-webui-backend
|
||||
|
||||
# Oder: Cron Job für tägliche Restart (wenn nötig)
|
||||
0 3 * * * systemctl restart zmb-webui-backend
|
||||
```
|
||||
|
||||
### Snapshots dauern zu lange
|
||||
```bash
|
||||
# Cache leeren
|
||||
curl -X POST http://10.66.120.3:8000/api/pools/clear-cache \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# Oder: Limit in URL erhöhen
|
||||
curl "http://10.66.120.3:8000/api/snapshots?limit=100"
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- ✅ Phase 1: Backend fertig
|
||||
- ⏳ Phase 2: Next.js Frontend bauen
|
||||
- ⏳ Phase 3: WebSocket + Advanced Features
|
||||
- ⏳ Phase 4: Alerts + Full Deployment
|
||||
|
||||
## Notes
|
||||
|
||||
- **No Docker!** (wie gewünscht) – Direkter systemd deployment
|
||||
- **Performance-optimiert** für ARM64 Raspberry Pi
|
||||
- **JWT Auth** statt Session-basiert (für API-Nutzung ideal)
|
||||
- **Minimal Dependencies** (nur FastAPI, Pydantic, python-jose, passlib)
|
||||
Reference in New Issue
Block a user