Update changes
Dieser Commit ist enthalten in:
Claude Project Manager
503
docs/production-architecture.md
Normale Datei
503
docs/production-architecture.md
Normale Datei
@ -0,0 +1,503 @@
|
||||
# AccountForger - Produktionsarchitektur
|
||||
|
||||
## Konfiguration
|
||||
|
||||
| Aspekt | Entscheidung |
|
||||
|--------|--------------|
|
||||
| **Hosting** | Eigener VPS/Root-Server (Docker Compose) |
|
||||
| **Multi-Tenant** | Ja - mehrere Clients mit eigenen API-Keys |
|
||||
| **eSIM-Strategie** | Pool mit Rotation (mehrere Nummern pro Kunde) |
|
||||
| **Router-Standort** | Beim Kunden (dezentral) |
|
||||
| **eSIM-Verwaltung** | Zentral durch Anbieter |
|
||||
|
||||
---
|
||||
|
||||
## Business-Modell
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ VERKAUF AN KUNDEN │
|
||||
│ │
|
||||
│ Paket beinhaltet: │
|
||||
│ ├── Software-Lizenz (AccountForger Desktop) │
|
||||
│ ├── Vorkonfigurierter RUTX11 Router │
|
||||
│ │ ├── Webhook bereits eingerichtet │
|
||||
│ │ ├── Auth-Token basierend auf Lizenz │
|
||||
│ │ └── eSIMs bereits eingelegt │
|
||||
│ └── Telefonnummern im System registriert │
|
||||
│ │
|
||||
│ Kunde muss nur: │
|
||||
│ ├── Router mit Strom + Internet verbinden │
|
||||
│ └── Software installieren + Lizenz aktivieren │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Übersicht
|
||||
|
||||
Dezentrale Router beim Kunden, zentraler Server für Verifikation.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ KUNDE A │
|
||||
│ ┌─────────────────┐ ┌──────────────────┐ │
|
||||
│ │ Desktop Client │ │ RUTX11 Router │ │
|
||||
│ │ (Lizenz: A123) │ │ (Token: A123) │ │
|
||||
│ └────────┬────────┘ └────────┬─────────┘ │
|
||||
└───────────┼────────────────────────────────┼────────────────────┘
|
||||
│ │
|
||||
┌───────────┼────────────────────────────────┼────────────────────┐
|
||||
│ KUNDE B │
|
||||
│ ┌─────────────────┐ ┌──────────────────┐ │
|
||||
│ │ Desktop Client │ │ RUTX11 Router │ │
|
||||
│ │ (Lizenz: B456) │ │ (Token: B456) │ │
|
||||
│ └────────┬────────┘ └────────┬─────────┘ │
|
||||
└───────────┼────────────────────────────────┼────────────────────┘
|
||||
│ │
|
||||
│ HTTPS (API) │ HTTPS (Webhook)
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ZENTRALER SERVER (VPS) │
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
|
||||
│ │ Email │ │ SMS │ │ Client/Router │ │
|
||||
│ │ Service │ │ Service │ │ Registry │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ IMAP Polling│ │ Webhook │ │ Lizenz → Router → Tel. │ │
|
||||
│ └─────────────┘ │ Empfänger │ └─────────────────────────┘ │
|
||||
│ └─────────────┘ │
|
||||
│ │
|
||||
│ PostgreSQL FastAPI │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. Server-Komponenten
|
||||
|
||||
### Technologie-Stack
|
||||
| Komponente | Technologie |
|
||||
|------------|-------------|
|
||||
| Framework | FastAPI (Python) |
|
||||
| Datenbank | PostgreSQL |
|
||||
| ORM | SQLAlchemy 2.0 |
|
||||
| Background Jobs | Celery + Redis |
|
||||
| Cache | Redis |
|
||||
| Auth | API-Keys (JWT optional) |
|
||||
|
||||
### API-Endpunkte
|
||||
|
||||
| Endpunkt | Methode | Beschreibung |
|
||||
|----------|---------|--------------|
|
||||
| `/api/v1/verification/email/request` | POST | Email-Adresse anfordern |
|
||||
| `/api/v1/verification/email/code/{id}` | GET | Email-Code abfragen |
|
||||
| `/api/v1/verification/sms/request` | POST | Telefonnummer anfordern |
|
||||
| `/api/v1/verification/sms/code/{id}` | GET | SMS-Code abfragen |
|
||||
| `/api/v1/webhook/rutx11/sms` | POST | SMS-Webhook vom Router |
|
||||
| `/api/v1/phone/available` | GET | Verfügbare Nummern |
|
||||
|
||||
### Datenbank-Schema
|
||||
|
||||
```sql
|
||||
-- Clients (Lizenznehmer)
|
||||
CREATE TABLE clients (
|
||||
id UUID PRIMARY KEY,
|
||||
license_key VARCHAR(50) UNIQUE NOT NULL,
|
||||
name VARCHAR(255),
|
||||
api_key_hash VARCHAR(255) NOT NULL,
|
||||
tier VARCHAR(20) DEFAULT 'standard',
|
||||
is_active BOOLEAN DEFAULT true,
|
||||
created_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
|
||||
-- Router (dezentral beim Kunden)
|
||||
CREATE TABLE routers (
|
||||
id UUID PRIMARY KEY,
|
||||
client_id UUID NOT NULL REFERENCES clients(id),
|
||||
router_token VARCHAR(100) UNIQUE NOT NULL, -- = Lizenzschlüssel oder abgeleitet
|
||||
model VARCHAR(50) DEFAULT 'RUTX11',
|
||||
serial_number VARCHAR(100),
|
||||
is_online BOOLEAN DEFAULT false,
|
||||
last_seen_at TIMESTAMP,
|
||||
created_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
|
||||
-- Telefonnummern (pro Router/Kunde)
|
||||
CREATE TABLE phone_numbers (
|
||||
id UUID PRIMARY KEY,
|
||||
router_id UUID NOT NULL REFERENCES routers(id),
|
||||
phone_number VARCHAR(20) UNIQUE NOT NULL,
|
||||
esim_slot INTEGER NOT NULL, -- 1 oder 2
|
||||
carrier VARCHAR(100),
|
||||
is_active BOOLEAN DEFAULT true,
|
||||
cooldown_until TIMESTAMP,
|
||||
usage_count INTEGER DEFAULT 0,
|
||||
last_used_at TIMESTAMP
|
||||
);
|
||||
|
||||
-- Verifikations-Anfragen
|
||||
CREATE TABLE verification_requests (
|
||||
id UUID PRIMARY KEY,
|
||||
client_id UUID NOT NULL REFERENCES clients(id),
|
||||
platform VARCHAR(50) NOT NULL,
|
||||
verification_type VARCHAR(20) NOT NULL, -- 'email' / 'sms'
|
||||
email_address VARCHAR(255),
|
||||
phone_number_id UUID REFERENCES phone_numbers(id),
|
||||
status VARCHAR(20) DEFAULT 'pending',
|
||||
verification_code VARCHAR(20),
|
||||
created_at TIMESTAMP DEFAULT NOW(),
|
||||
expires_at TIMESTAMP
|
||||
);
|
||||
|
||||
-- Email-Konten (zentral Server-verwaltet)
|
||||
CREATE TABLE email_accounts (
|
||||
id UUID PRIMARY KEY,
|
||||
email_address VARCHAR(255) UNIQUE NOT NULL,
|
||||
imap_server VARCHAR(255) NOT NULL,
|
||||
imap_port INTEGER DEFAULT 993,
|
||||
password_encrypted BYTEA NOT NULL,
|
||||
domain VARCHAR(255) NOT NULL,
|
||||
is_active BOOLEAN DEFAULT true
|
||||
);
|
||||
|
||||
-- Empfangene SMS
|
||||
CREATE TABLE sms_messages (
|
||||
id UUID PRIMARY KEY,
|
||||
router_id UUID NOT NULL REFERENCES routers(id),
|
||||
phone_number VARCHAR(20) NOT NULL,
|
||||
sender VARCHAR(50),
|
||||
message_body TEXT NOT NULL,
|
||||
received_at TIMESTAMP DEFAULT NOW(),
|
||||
processed BOOLEAN DEFAULT false,
|
||||
matched_request_id UUID REFERENCES verification_requests(id)
|
||||
);
|
||||
```
|
||||
|
||||
### Entity-Relationship
|
||||
|
||||
```
|
||||
clients (1) ──────< routers (1) ──────< phone_numbers (n)
|
||||
│ │
|
||||
│ └──────< sms_messages (n)
|
||||
│
|
||||
└──────< verification_requests (n)
|
||||
```
|
||||
|
||||
### Server-Projektstruktur
|
||||
|
||||
```
|
||||
accountforger-server/
|
||||
├── app/
|
||||
│ ├── main.py # FastAPI Entry
|
||||
│ ├── config.py # Konfiguration
|
||||
│ ├── api/v1/
|
||||
│ │ ├── verification.py # Verifikations-Endpunkte
|
||||
│ │ ├── webhooks.py # RUTX11 Webhook
|
||||
│ │ └── auth.py # Authentifizierung
|
||||
│ ├── services/
|
||||
│ │ ├── email_service.py # IMAP-Polling
|
||||
│ │ ├── sms_service.py # SMS-Verarbeitung
|
||||
│ │ └── phone_rotation.py # eSIM-Rotation
|
||||
│ └── infrastructure/
|
||||
│ ├── database.py
|
||||
│ └── imap_client.py
|
||||
├── docker-compose.yml
|
||||
└── requirements.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. RUTX11 Integration
|
||||
|
||||
### SMS-Forwarding Konfiguration
|
||||
|
||||
1. **Im RUTX11 WebUI:**
|
||||
- Services → Mobile Utilities → SMS Gateway → SMS Forwarding
|
||||
- Neue Regel: HTTP POST an `https://server.domain/api/v1/webhook/rutx11/sms`
|
||||
|
||||
2. **Webhook-Payload vom Router:**
|
||||
```json
|
||||
{
|
||||
"sender": "+49123456789",
|
||||
"message": "123456 is your verification code",
|
||||
"timestamp": "2026-01-17T10:30:00Z",
|
||||
"sim_slot": 1
|
||||
}
|
||||
```
|
||||
|
||||
### Dezentrale Router-Architektur
|
||||
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ Verification Server │
|
||||
│ │
|
||||
│ ┌─────────────────────────┐ │
|
||||
│ │ Router Registry │ │
|
||||
│ │ │ │
|
||||
│ │ - Client ↔ Router Map │ │
|
||||
│ │ - Telefonnummern/Client│ │
|
||||
│ │ - Health Monitoring │ │
|
||||
│ └───────────┬─────────────┘ │
|
||||
└──────────────┼─────────────────┘
|
||||
│
|
||||
┌────────────────────┼────────────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
|
||||
│ Kunde A Router │ │ Kunde B Router │ │ Kunde C Router │
|
||||
│ Token: A123 │ │ Token: B456 │ │ Token: C789 │
|
||||
│ Tel: +49... │ │ Tel: +49... │ │ Tel: +49... │
|
||||
└────────────────┘ └────────────────┘ └────────────────┘
|
||||
│ │ │
|
||||
└────────────────────┴────────────────────┘
|
||||
│
|
||||
Webhooks an zentralen Server
|
||||
```
|
||||
|
||||
### Router-Vorkonfiguration (vor Versand)
|
||||
|
||||
```bash
|
||||
# RUTX11 SMS Forwarding Konfiguration
|
||||
# Services → Mobile Utilities → SMS Gateway → SMS Forwarding
|
||||
|
||||
Webhook URL: https://verify.domain.com/api/v1/webhook/sms
|
||||
HTTP Method: POST
|
||||
Headers: X-Router-Token: {LIZENZ_TOKEN}
|
||||
Payload Format: JSON
|
||||
```
|
||||
|
||||
### eSIM-Rotationsstrategie
|
||||
|
||||
| Strategie | Beschreibung |
|
||||
|-----------|--------------|
|
||||
| Cooldown | 30 Min. Pause nach Nutzung pro Nummer |
|
||||
| Round Robin | Abwechselnd durch alle verfügbaren Nummern |
|
||||
| Platform-Aware | Tracken welche Nummer für welche Platform verwendet wurde |
|
||||
| Load Balancing | Gleichmäßige Verteilung über alle Router/SIM-Banks |
|
||||
| Health Check | Automatische Deaktivierung bei Problemen |
|
||||
|
||||
---
|
||||
|
||||
## 3. Client-Änderungen
|
||||
|
||||
### Was bleibt im Client
|
||||
- PyQt5 UI
|
||||
- Playwright Browser-Automation
|
||||
- Fingerprint-Management
|
||||
- Lokale SQLite-Datenbank
|
||||
|
||||
### Was entfernt wird
|
||||
- `utils/email_handler.py` → ersetzt durch API-Calls
|
||||
- `config/email_config.json` → keine Credentials mehr im Client
|
||||
- Hardcoded `"123456"` SMS-Placeholder
|
||||
|
||||
### Neuer VerificationClient
|
||||
|
||||
**Datei:** `utils/verification_client.py`
|
||||
|
||||
```python
|
||||
class VerificationClient:
|
||||
def __init__(self, server_url: str, api_key: str):
|
||||
self.server_url = server_url
|
||||
self.api_key = api_key
|
||||
|
||||
def request_email(self, platform: str) -> dict:
|
||||
"""Fordert Email-Adresse vom Server an."""
|
||||
response = requests.post(
|
||||
f"{self.server_url}/api/v1/verification/email/request",
|
||||
json={"platform": platform},
|
||||
headers={"X-API-Key": self.api_key}
|
||||
)
|
||||
return response.json() # {"request_id": "...", "email_address": "..."}
|
||||
|
||||
def request_sms(self, platform: str) -> dict:
|
||||
"""Fordert Telefonnummer vom Server an."""
|
||||
response = requests.post(
|
||||
f"{self.server_url}/api/v1/verification/sms/request",
|
||||
json={"platform": platform},
|
||||
headers={"X-API-Key": self.api_key}
|
||||
)
|
||||
return response.json() # {"request_id": "...", "phone_number": "..."}
|
||||
|
||||
def poll_for_code(self, request_id: str, type: str, timeout: int = 120) -> str:
|
||||
"""Pollt Server bis Code empfangen wurde."""
|
||||
# ...
|
||||
```
|
||||
|
||||
### Zu ändernde Dateien
|
||||
|
||||
| Datei | Änderung |
|
||||
|-------|----------|
|
||||
| `social_networks/base_automation.py` | `verification_client` Parameter hinzufügen |
|
||||
| `social_networks/*/verification.py` | API-Calls statt direktem IMAP |
|
||||
| `controllers/platform_controllers/base_worker_thread.py` | VerificationClient initialisieren |
|
||||
| `config/server_config.json` (NEU) | Server-URL und API-Key |
|
||||
|
||||
---
|
||||
|
||||
## 4. Multi-Tenant Architektur
|
||||
|
||||
### Client-Verwaltung
|
||||
|
||||
```sql
|
||||
-- Clients (Tenants)
|
||||
CREATE TABLE clients (
|
||||
id UUID PRIMARY KEY,
|
||||
name VARCHAR(255) NOT NULL,
|
||||
license_key VARCHAR(50) UNIQUE NOT NULL,
|
||||
api_key_hash VARCHAR(255) NOT NULL,
|
||||
is_active BOOLEAN DEFAULT true,
|
||||
tier VARCHAR(20) DEFAULT 'standard', -- standard, premium, enterprise
|
||||
created_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
|
||||
-- Rate Limits pro Tier
|
||||
CREATE TABLE tier_limits (
|
||||
tier VARCHAR(20) PRIMARY KEY,
|
||||
email_requests_per_hour INTEGER,
|
||||
sms_requests_per_hour INTEGER,
|
||||
max_concurrent_verifications INTEGER
|
||||
);
|
||||
|
||||
INSERT INTO tier_limits VALUES
|
||||
('standard', 50, 20, 5),
|
||||
('premium', 200, 100, 20),
|
||||
('enterprise', 1000, 500, 100);
|
||||
```
|
||||
|
||||
### Tenant-Isolation
|
||||
|
||||
| Aspekt | Implementierung |
|
||||
|--------|-----------------|
|
||||
| API-Keys | Eindeutig pro Client |
|
||||
| Rate Limits | Per-Tenant basierend auf Tier |
|
||||
| Logging | Client-ID in allen Logs |
|
||||
| Ressourcen | Shared Pool mit Fair-Use |
|
||||
| Abrechnung | Usage-Tracking pro Client |
|
||||
|
||||
---
|
||||
|
||||
## 5. Sicherheit
|
||||
|
||||
### Authentifizierung
|
||||
- API-Key pro Client-Installation
|
||||
- Gehashed in Server-DB (bcrypt)
|
||||
- Gebunden an Lizenzschlüssel
|
||||
|
||||
### Credentials-Management
|
||||
| Credential | Speicherort | Schutz |
|
||||
|------------|-------------|--------|
|
||||
| IMAP-Passwörter | Server DB | AES-256 verschlüsselt |
|
||||
| API-Keys | Server DB | bcrypt Hash |
|
||||
| RUTX11 Webhook | Server .env | Umgebungsvariable |
|
||||
| Client API-Key | Client Config | Verschlüsselt lokal |
|
||||
|
||||
### Netzwerk
|
||||
- HTTPS-Only (TLS 1.3)
|
||||
- IP-Whitelist für RUTX11 Webhook
|
||||
- Rate Limiting (10 Email-Requests/Min, 5 SMS-Requests/Min)
|
||||
|
||||
---
|
||||
|
||||
## 6. Deployment
|
||||
|
||||
### Docker Compose (empfohlen)
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
api:
|
||||
build: .
|
||||
ports:
|
||||
- "8000:8000"
|
||||
environment:
|
||||
- DATABASE_URL=postgresql://user:pass@db:5432/verify
|
||||
- REDIS_URL=redis://redis:6379
|
||||
depends_on:
|
||||
- db
|
||||
- redis
|
||||
|
||||
db:
|
||||
image: postgres:15
|
||||
volumes:
|
||||
- pgdata:/var/lib/postgresql/data
|
||||
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
|
||||
celery:
|
||||
build: .
|
||||
command: celery -A app.worker worker -l info
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Verifikation / Testing
|
||||
|
||||
1. **Server starten:** `docker-compose up`
|
||||
2. **Email-Test:**
|
||||
- POST `/api/v1/verification/email/request` mit `{"platform": "instagram"}`
|
||||
- GET `/api/v1/verification/email/code/{id}` → Code erhalten
|
||||
3. **SMS-Test:**
|
||||
- Webhook simulieren: POST an `/api/v1/webhook/rutx11/sms`
|
||||
- Prüfen ob SMS in DB landet und Request gematcht wird
|
||||
4. **Client-Integration:**
|
||||
- `VerificationClient` instanziieren
|
||||
- Account-Erstellung mit Server-Verifikation testen
|
||||
|
||||
---
|
||||
|
||||
## 8. Onboarding-Prozess (Neuer Kunde)
|
||||
|
||||
### Admin-Workflow
|
||||
|
||||
```
|
||||
1. Neue Lizenz generieren
|
||||
└── license_key: "AF-2026-XXXXX"
|
||||
|
||||
2. Client in DB anlegen
|
||||
└── INSERT INTO clients (license_key, name, api_key_hash, tier)
|
||||
|
||||
3. Router vorkonfigurieren
|
||||
├── RUTX11 Webhook URL setzen
|
||||
├── X-Router-Token Header = license_key
|
||||
└── eSIMs einlegen
|
||||
|
||||
4. Telefonnummern registrieren
|
||||
├── INSERT INTO routers (client_id, router_token)
|
||||
└── INSERT INTO phone_numbers (router_id, phone_number, esim_slot)
|
||||
|
||||
5. Paket versenden
|
||||
├── Router (Plug & Play ready)
|
||||
└── Software-Download Link + Lizenzschlüssel
|
||||
```
|
||||
|
||||
### Kunde-Workflow
|
||||
|
||||
```
|
||||
1. Router auspacken und anschließen
|
||||
└── Strom + Ethernet/WLAN
|
||||
|
||||
2. Software installieren
|
||||
└── AccountForger.exe
|
||||
|
||||
3. Lizenz aktivieren
|
||||
└── Lizenzschlüssel eingeben → Server validiert
|
||||
|
||||
4. Fertig!
|
||||
└── SMS-Verifikation funktioniert automatisch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Implementierungsreihenfolge
|
||||
|
||||
1. **Server Basis** - FastAPI Setup, DB-Schema, Email-Service
|
||||
2. **Router Registry** - Client/Router/Telefonnummer Verwaltung
|
||||
3. **RUTX11 Webhook** - SMS empfangen, Router-Token validieren, Request matchen
|
||||
4. **Client Integration** - VerificationClient implementieren
|
||||
5. **Plattform-Migration** - Alle verification.py Dateien umstellen
|
||||
6. **Admin-Panel** - Kunden/Router/Nummern verwalten (optional)
|
||||
7. **Security & Monitoring** - Rate Limiting, Logging, Health Checks
|
||||
In neuem Issue referenzieren
Einen Benutzer sperren