Zum Inhalt

Telefonie — Architektur-Uebersicht

Einleitung

Die xynap-Telefonieanlage basiert auf FreeSwitch v1.10.10 als zentrale SIP-Engine und bietet zwei parallele Signalpfade: eine klassische PBX für interne und externe Telefonie sowie eine KI-gestützte Voice-Pipeline über LiveKit.

Alle Konfigurationsdaten (Extensions, Trunks, DIDs, Ring Groups) werden dynamisch über die Platform API bereitgestellt — FreeSwitch selbst hält keine statischen XML-Dateien für Rufnummern oder Routing.

Dual-Path Architektur

SIP Provider (1&1 / Plusnet)
    │ SIP (UDP 5060)
    ▼
┌──────────────────────────────────────────────────┐
│  FreeSwitch (Container: voicebot-fs)             │
│  network_mode: host                              │
│                                                  │
│  ┌─────────────────────┐ ┌─────────────────────┐ │
│  │  Path A: PBX        │ │  Path B: LiveKit    │ │
│  │  mod_xml_curl       │ │  livekit-sip :5070  │ │
│  │  → Platform API     │ │                     │ │
│  │    :8001             │ │  ┌───────────────┐  │ │
│  │                     │ │  │ AI Voice Bot  │  │ │
│  │  ┌───────────────┐  │ │  │ Dolmetscher   │  │ │
│  │  │ Extensions    │  │ │  │ LiveKit Rooms  │  │ │
│  │  │ Ring Groups   │  │ │  │ Agent Workers │  │ │
│  │  │ IVR Menues    │  │ │  └───────────────┘  │ │
│  │  │ WebRTC (WSS)  │  │ │                     │ │
│  │  │ Outbound      │  │ │                     │ │
│  │  └───────────────┘  │ └─────────────────────┘ │
│  └─────────────────────┘                         │
└──────────────────────────────────────────────────┘

Path A — Interne PBX

Der klassische Telefoniepfad nutzt mod_xml_curl, um bei jedem SIP-Event (Registrierung, eingehender Anruf, Directory-Lookup) die Platform API auf Port 8001 per HTTP POST zu befragen. Die API liefert dynamisch generiertes XML zurück.

Leistungsumfang:

  • Interne Extensions (1000–1099)
  • Ring Groups für Abteilungen
  • IVR-Menüs mit DTMF und Sprach-Navigation
  • WebRTC Softphone über WSS (Port 7443, JsSIP)
  • Outbound-Calls über Provider-Trunks
  • Call Filters (Blacklist / Whitelist)

Path B — LiveKit Agent

Für KI-gestützte Anwendungen werden Calls an den LiveKit SIP Bridge (Port 5070) weitergeleitet. Der LiveKit-Server verwaltet Räume, in denen Python-basierte Agent Workers laufen.

Anwendungen:

  • AI Voice Bot — Interaktives IVR mit Spracherkennung
  • Dolmetscher — Bidirektionale Echtzeit-Übersetzung (Whisper → LibreTranslate → Piper TTS)
  • LiveKit Rooms — Konferenz- und Medienräume

Container-Architektur

Container Image Netzwerk Ports Aufgabe
voicebot-fs Custom (drachtio-freeswitch-mrf + mod_xml_curl) host 5060, 5061, 7443, RTP SIP-Engine
livekit livekit/livekit-server v1.7 host 7880 Medienserver
livekit-sip livekit/sip host 5070 SIP-Bridge für LiveKit
livekit-agent Custom (Python, livekit-agents 1.4) host — KI-Agent Worker
interpreter-bridge Custom host 9001 Dolmetscher-Service

Dateisystem-Referenz

Pfad Beschreibung
/usr/local/xynap/voicebot/freeswitch/Dockerfile FreeSwitch Container-Image
/usr/local/xynap/voicebot/docker-compose.yml Compose-Datei für Voicebot-Stack
/etc/xynap/voicebot/freeswitch/ FreeSwitch-Konfiguration (Volume Mount)
/etc/xynap/livekit/livekit.yaml LiveKit-Server-Config
/etc/xynap/livekit-sip/sip.yaml LiveKit SIP-Bridge-Config
/usr/local/xynap/platform/backend/app/modules/sip/ Platform API SIP-Modul
/usr/local/xynap/interpreter/ Dolmetscher-Service Quellcode
/var/lib/xynap/voicebot/tts-audio/ TTS Audio-Cache

Sofia Profiles

FreeSwitch nutzt zwei Sofia-Profile für unterschiedliche Provider-Anbindungen:

external-ipv4

  • Bind: Port 5060 auf 46.4.96.105 (nur IPv4)
  • Zweck: Plusnet-Gateway (IP-Auth, kein REGISTER)
  • RTP-IP: IPv4

internal

  • Bind: Port 5060 auf :: (Dual-Stack, IPv4 + IPv6)
  • Zweck: 1&1-Gateways (REGISTER), interne Extensions, WebRTC
  • ext-sip-ip / ext-rtp-ip: 2a01:4f8:140:829d::2 (IPv6)
  • TLS: Port 5061
  • WSS: Port 7443 (WebRTC)
  • ACL: sip-gateways (default deny)

IPv6 ist Pflicht für 1&1

1&1 blockiert Hetzner-IPv4-Adressen. Alle 1&1-Gateways müssen über das internal-Profil mit IPv6 registriert werden. Siehe Provider-Konfiguration für Details.

Platform API — SIP-Modul

Die dynamische Konfiguration läuft über einen einzigen Endpoint:

POST /api/v1/sip/xml-curl

Dieser Endpoint wird nur von localhost (FreeSwitch selbst) aufgerufen und benötigt kein JWT. Je nach section-Parameter liefert er:

Section Funktion
directory User-Authentifizierung + Gateway-Discovery
dialplan DID-Routing im public Context

Zusätzlich bietet die API vollständige CRUD-Endpoints:

/api/v1/sip/trunks          — Provider-Gateways
/api/v1/sip/extensions       — SIP-Extensions
/api/v1/sip/dids             — Rufnummern (DIDs)
/api/v1/sip/lines            — Line-Zuordnungen
/api/v1/sip/ring-groups      — Gruppenrufe
/api/v1/sip/ivr-menus        — IVR-Menüs
/api/v1/sip/call-filters     — Black-/Whitelists

Live-Status der Anlage (Registrierungen, Gateway-Status):

GET /api/v1/sip/live-status

ESL-Integration: Die Platform API hält eine asynchrone TCP-Verbindung zum FreeSwitch Event Socket. Bei Änderungen (z.B. neuer Trunk, geänderte Extension) wird automatisch ein Reload ausgelöst.

Netzwerk-Ports

Port Protokoll Richtung Beschreibung
5060 UDP Inbound/Outbound SIP Signaling (Provider + Intern)
5061 TCP/TLS Inbound SIP über TLS
5070 UDP Intern LiveKit SIP-Bridge
7443 TCP/WSS Inbound WebRTC Softphone
7880 TCP Intern LiveKit Server API
8001 TCP Intern Platform API (xml-curl)
9001 TCP Intern Interpreter WebSocket
10000–10060 UDP Inbound/Outbound RTP Media
16384–16484 UDP Inbound/Outbound RTP Media (erweiterter Bereich)

Host-Netzwerk

Alle Telefonie-Container laufen mit network_mode: host. Das ist zwingend für korrektes RTP-Handling und SIP-NAT-Traversal auf Bare-Metal.

Weiterführende Dokumentation