Leopoldadmin/leocrm
1
0
Fork 0
Code Issues 363 Pull Requests Actions 7 Packages Projects Releases 1 Wiki Activity

docs: punkt 11 (documentation) — README, infrastructure, monitoring, admin-guide, deploy-guide, api-docs, PROGRESS, ENTERPRISE_READINESS_PLAN all updated

Browse Source
This commit is contained in:
Agent Zero
2026-08-20 14:03:35 +02:00
parent e6790d9b81
commit f79eb9354a
8 changed files with 853 additions and 242 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin-guide.md
+242 -19
View File
@@ -1,16 +1,20 @@
# LeoCRM Admin Guide
> Operations manual for LeoCRM administrators: deployment, backup, restore, environment configuration, and troubleshooting.
> Operations manual for LeoCRM administrators: deployment, backup, restore, environment configuration, monitoring, and troubleshooting.
## Table of Contents
1. [Deployment](#deployment)
2. [Environment Configuration](#environment-configuration)
3. [Environment Profiles](#environment-profiles)
4. [Backup](#backup)
5. [Restore](#restore)
6. [Monitoring](#monitoring)
7. [Troubleshooting](#troubleshooting)
4. [System Dashboard](#system-dashboard)
5. [Backup](#backup)
6. [Restore](#restore)
7. [Audit Log](#audit-log)
8. [Trash Cleanup](#trash-cleanup)
9. [Monitoring](#monitoring)
10. [Incident Response](#incident-response)
11. [Troubleshooting](#troubleshooting)
---
@@ -19,7 +23,7 @@
### Prerequisites
- Docker 24+ and Docker Compose v2
- PostgreSQL 15+ (or use the included Docker container)
- PostgreSQL 16+ (or use the included Docker container with pgvector)
- Redis 7+ (or use the included Docker container)
- A Coolify instance (for managed deployment) or a VPS with Docker
@@ -67,11 +71,11 @@
### Coolify Deployment
See [COOLIFY_SETUP.md](../COOLIFY_SETUP.md) for detailed Coolify deployment instructions.
See [deploy-guide.md](deploy-guide.md) for detailed Coolify deployment instructions.
### Manual Deployment (without Docker)
1. Install Python 3.11+ and PostgreSQL 15+
1. Install Python 3.12+ and PostgreSQL 16+
2. Create a virtual environment: `python3 -m venv .venv && source .venv/bin/activate`
3. Install dependencies: `pip install -r requirements.txt`
4. Configure `.env` (see [Environment Configuration](#environment-configuration))
@@ -183,9 +187,92 @@ LeoCRM supports three environment profiles via the `ENVIRONMENT` variable.
---
## System Dashboard
Das System Dashboard ist die zentrale Monitoring-Oberfläche für Administratoren.
### Zugriff
- **Frontend:** `/system-dashboard` (Admin-only, Sidebar-Eintrag nur für Admins sichtbar)
- **API:** `GET /api/v1/system/dashboard` (Admin-only)
- **Alerts:** `GET /api/v1/system/alerts` (Admin-only)
### Dashboard-Inhalte
| Bereich | Metriken |
|---------|----------|
| **System Health** | Overall status (healthy/degraded/down) |
| **Database** | Connections, Table Count, DB Size |
| **Redis** | Connected Clients, Used Memory, Peak Memory, Uptime |
| **Worker** | Queue Length, Active Workers, Status |
| **API Stats** | Total Requests, Error Count, Error Rate, Avg Response Time |
| **Plugins** | Total Discovered, Active Plugins |
| **Storage** | Disk Usage, File Count, Status |
| **Alert Feed** | System Messages aus Communication-System |
### Alert-Dispatch
Bei Problemen (DB down, Redis down, Worker down, High Error Rate) sendet das System Dashboard automatisch eine System-Message an das Communication-System. Diese erscheint im Alert-Feed und in den Benachrichtigungen der Admins.
```bash
# Dashboard abfragen
curl -b "leocrm_session=<session>" https://crm.media-on.de/api/v1/system/dashboard | jq .
# Aktive Alerts abfragen
curl -b "leocrm_session=<session>" https://crm.media-on.de/api/v1/system/alerts | jq .
```
Siehe auch [monitoring.md](monitoring.md) für Details zu Health Endpoints und Metrics.
---
## Backup
### Database Backup
### Backup-Konfiguration (Settings → Backup)
Die Backup-Konfiguration erfolgt über die System-Settings API oder das Settings-UI.
| Einstellung | Default | Beschreibung |
|-------------|---------|-------------|
| `backup_enabled` | `false` | Backup Automation aktivieren |
| `backup_interval` | `24h` | Backup-Intervall (Cron-Schedule) |
| `backup_retention_days` | `7` | Aufbewahrung in Tagen |
| `backup_destination` | `local` | Backup-Ziel (local, s3, nextcloud) |
#### API-Endpunkte
| Method | Path | Beschreibung |
|--------|------|-------------|
| GET | `/api/v1/system-settings/backup-config` | Backup-Konfiguration abfragen |
| PUT | `/api/v1/system-settings/backup-config` | Backup-Konfiguration aktualisieren |
| POST | `/api/v1/system-settings/backup-now` | Sofortiges Backup auslösen (ARQ-Job) |
| GET | `/api/v1/system-settings/backup-history` | Letzte 10 Backup-Ergebnisse (Audit Log) |
```bash
# Backup-Konfiguration abfragen
curl -b "leocrm_session=<session>" https://crm.media-on.de/api/v1/system-settings/backup-config | jq .
# Backup aktivieren und konfigurieren
curl -X PUT -b "leocrm_session=<session>" \
-H "Content-Type: application/json" \
-d '{"backup_enabled": true, "backup_interval": "24h", "backup_retention_days": 7, "backup_destination": "local"}' \
https://crm.media-on.de/api/v1/system-settings/backup-config
# Sofortiges Backup auslösen
curl -X POST -b "leocrm_session=<session>" https://crm.media-on.de/api/v1/system-settings/backup-now
# Backup-Historie abfragen
curl -b "leocrm_session=<session>" https://crm.media-on.de/api/v1/system-settings/backup-history | jq .
```
### Automated Backup (ARQ Cron-Job)
- **Job:** `auto_backup_job` (täglich 03:00 Uhr, einstellbar)
- **Script:** `scripts/backup.py` (pg_dump + files)
- **Bei Fehler:** System-Message an Communication-System + Audit Log Eintrag
- **Bei Erfolg:** Audit Log Eintrag (`backup_success`)
### Manual Database Backup
```bash
# Full database dump (recommended daily)
@@ -195,14 +282,6 @@ pg_dump -U leocrm -h localhost leocrm > backup_$(date +%Y%m%d).sql
pg_dump -U leocrm -h localhost leocrm | gzip > backup_$(date +%Y%m%d).sql.gz
```
### Automated Backup (Cron)
Add to crontab for daily backup at 2 AM:
```cron
0 2 * * * pg_dump -U leocrm -h localhost leocrm | gzip > /backups/leocrm_$(date +\%Y\%m\%d).sql.gz
```
### File Storage Backup
```bash
@@ -248,14 +327,120 @@ cp /backups/redis_20260101.rdb /var/lib/redis/dump.rdb
systemctl start redis
```
See `scripts/restore.py` for the automated restore solution and `scripts/restore_test.sh` for restore testing.
---
## Audit Log
### Audit Log Export (CSV/JSON)
Audit-Logs können als CSV oder JSON exportiert werden. Der Export erfolgt als Streaming-Response (max. 10.000 Einträge).
```bash
# CSV Export
curl -b "leocrm_session=<session>" \
"https://crm.media-on.de/api/v1/audit-log/export?format=csv" \
-o audit_log_export.csv
# JSON Export
curl -b "leocrm_session=<session>" \
"https://crm.media-on.de/api/v1/audit-log/export?format=json" \
-o audit_log_export.json
# Gefilterter Export (nach Entity-Type und Datum)
curl -b "leocrm_session=<session>" \
"https://crm.media-on.de/api/v1/audit-log/export?format=csv&entity_type=contact&date_from=2026-01-01&date_to=2026-12-31" \
-o audit_log_contacts_2026.csv
```
### Audit Log Retention (365 Tage)
Audit-Logs werden standardmäßig nach 365 Tagen archiviert/gelöscht. Die Retention ist einstellbar.
- **Default:** 365 Tage
- **ARQ-Cron-Job:** `audit_retention_cleanup` (täglich 04:00 Uhr)
- **API:** `DELETE /api/v1/audit-log/retention?retention_days=365`
```bash
# Manuelle Retention-Bereinigung (Admin-only)
curl -X DELETE -b "leocrm_session=<session>" \
"https://crm.media-on.de/api/v1/audit-log/retention?retention_days=365"
# → {"deleted": 1234, "retention_days": 365, "cutoff": "2025-08-20T00:00:00"}
```
### Audit Log Abfrage
```bash
# Audit-Logs abfragen (mit Filter und Pagination)
curl -b "leocrm_session=<session>" \
"https://crm.media-on.de/api/v1/audit-log?entity_type=contact&action=create&page=1&page_size=50" | jq .
```
**Filter-Parameter:**
- `entity_type` — Filter nach Entity-Typ
- `user_id` — Filter nach User-ID
- `action` — Filter nach Action (create/update/delete/login)
- `date_from` — ISO Datum-Start (inklusive)
- `date_to` — ISO Datum-Ende (inklusive)
- `page` / `page_size` — Pagination (max. 200 pro Seite)
### Tamper-Proof
- DELETE auf AuditLog nur mit `?gdpr=true` + Admin-Berechtigung
- Audit-Logs können nicht modifiziert werden (nur erstellen und lesen)
---
## Trash Cleanup
Soft-deleted Entitäten werden nach Ablauf der Retention-Periode endgültig gelöscht.
- **Default:** 90 Tage (`trash_retention_days`)
- **ARQ-Cron-Job:** `cleanup_expired_trash` (täglich 05:00 Uhr)
- **Kriterium:** `deleted_at < now() - retention_days`
- **Bei Löschung:** Audit-Log Eintrag
### Konfiguration
Die Retention-Periode ist über die System-Settings einstellbar:
```bash
# Trash-Retention konfigurieren
curl -X PUT -b "leocrm_session=<session>" \
-H "Content-Type: application/json" \
-d '{"trash_retention_days": 90}' \
https://crm.media-on.de/api/v1/system-settings
```
### Hard-Delete (GDPR)
Einzelne Entitäten können sofort endgültig gelöscht werden (Admin-only):
```bash
# Hard-Delete mit GDPR-Flag
curl -X DELETE -b "leocrm_session=<session>" \
"https://crm.media-on.de/api/v1/contacts/{id}?gdpr=true"
```
---
## Monitoring
### Health Endpoint
### Health Endpoints
```bash
# Liveness
curl http://localhost:8000/health/live
# → {"status":"alive"}
# Readiness
curl http://localhost:8000/health/ready
# → {"status":"ready","checks":{"database":"ok","redis":"ok","storage":"ok"}}
# Full health
curl http://localhost:8000/api/v1/health
# → {"status":"healthy","version":"1.0.0","checks":{...}}
```
Returns JSON with overall status and individual checks:
@@ -305,6 +490,33 @@ python scripts/seed_perf_data.py --count 200000
python scripts/check_indexes.py
```
Siehe [monitoring.md](monitoring.md) für vollständige Monitoring-Dokumentation.
---
## Incident Response
Siehe `docs/incident-response-runbook.md` für detaillierte Notfall-Prozeduren.
### Schnell-Referenz
| Incident | Erste Maßnahme | Eskalation |
|----------|---------------|-----------|
| **Server-Ausfall** | Coolify Restart → Health-Check → System-Message | Hetzner Support |
| **DB-Crash** | PostgreSQL Restart → Migration-Check → Backup-Restore | Coolify DB Restart |
| **Redis-Crash** | Redis Restart → Session-Check | Coolify Service Restart |
| **Security-Breach** | Logs prüfen → Password-Reset → Audit-Log Export | Incident Response Team |
| **Backup Failed** | Backup-Log prüfen → Manueller Retry → Storage prüfen | Admin |
| **Worker Down** | Worker-Container Restart → Queue prüfen | Coolify Service Restart |
### Incident Response Schritte
1. **Erkennen** — Alert im System Dashboard oder externes Monitoring
2. **Eingrenzen** — Health-Checks, Logs, Metrics prüfen
3. **Beheben** — Restart, Restore, Konfiguration anpassen
4. **Verifizieren** — Health-Check grün, System Dashboard ok
5. **Dokumentieren** — Audit Log Eintrag, Post-Mortem bei Critical
---
## Troubleshooting
@@ -340,7 +552,8 @@ python scripts/check_indexes.py
1. Verify ARQ worker is running: `ps aux | grep arq`
2. Start worker: `arq app.core.jobs.WorkerSettings`
3. Check Redis queue: `redis-cli LLEN arq:queue`
3. Check Redis queue: `redis-cli ZCARD arq:queue`
4. Check System Dashboard: `GET /api/v1/system/dashboard` → `.worker`
### Performance Issues
@@ -378,3 +591,13 @@ python scripts/check_indexes.py
3. Review migration files in `alembic/versions/`
4. Check current revision: `alembic current`
5. Reset (DESTRUCTIVE): `alembic downgrade base && alembic upgrade head`
### Backup Issues
**Symptom**: Backup job fails, no backup history
1. Check System Dashboard for backup alerts
2. Check Audit Log for `backup_failed` entries: `GET /api/v1/audit-log?action=backup_failed`
3. Verify storage path has enough disk space
4. Try manual backup: `POST /api/v1/system-settings/backup-now`
5. Check `scripts/backup.py` logs