TgWitness / Dokumentation

Was wurde getestet? →

Referenz / Einrichtung

Telegram · Bereitstellung

Führen Sie TgWitness als Dienst unter Windows, Linux, macOS oder Docker hinter einer HTTPS-Verbindung aus, einschließlich Backups und Updates.

TgWitness / Dokumentation

Bereitstellung und Wiederherstellung

Englisch · Russisch · Ukrainisch · Español · Português (Brasil) · Türkçe · العربية · Farsi · Urdu · Hindi · Bahasa Indonesia · Tiếng Việt · Vereinfachtes Chinesisch

Wählen Sie eine Installationsvariante#

Für das portable Paket entpacken Sie bitte „TgWitness-<version>-windows-amd64-portable.zip“ von GitHub Releases. Für die anderen Methoden laden Sie bitte die Quell-ZIP-Datei herunter und entpacken Sie diese oder klonen Sie das Repository und führen Sie anschließend im Projektverzeichnis Folgendes aus:

Installation Start Läuft es im Hintergrund?
Portables Windows-Paket TgWitness.cmd Nein; lassen Sie das Fenster geöffnet.
Native Windows-Version Start.cmd Nein; nutzen Sie die optionale Anmeldeaufgabe für den Hintergrundbetrieb.
Native Linux-/macOS-Version sh start.sh Nein; verwenden Sie systemd/launchd für den Betrieb im Hintergrund.
Docker auf jedem unterstützten Host docker compose up -d --build --wait Ja, solange der Docker-Daemon läuft.
Docker-Hilfsprogramm unter Windows scripts\Docker.cmd Ja; der Helper wartet auf den Betriebszustand des Webservers.
Docker-Hilfsprogramm unter Linux/macOS sh scripts/docker-start.sh Ja; der Helper wartet auf den Betriebszustand des Webservers.

Für einen Cloud-Server, der von Dritten überprüft werden können sollte – erstellt über die API des Anbieters, ohne SSH, ausschließlich über einen Cloudflare-Tunnel erreichbar – siehe „High-Assurance-Bereitstellung“.

Beim nativen Start wird ein privates „.venv“ erstellt und die festgelegten Abhängigkeiten installiert. Docker erstellt diese innerhalb des Images, ohne dass Python auf dem Host erforderlich ist. Für die erstmalige Einrichtung ist ein Internetzugang erforderlich. Wird kein Python 3.11+ gefunden, fragt „Start.cmd“ vor der Installation von Python 3.12 für den aktuellen Windows-Benutzer nach (winget, andernfalls der python.org- Installer nach Überprüfung der Signatur der Python Software Foundation); es werden niemals Administratorrechte angefordert. Docker und Betriebssystemdienste bleiben weiterhin Voraussetzungen.

Native und portable Installationen verwenden „data/live“ innerhalb ihres Ordners. Docker verwendet das Volume mit dem Namen „tgwitness-data“ unter „/data“. Dabei handelt es sich um separate Installationen, bis Sie das gesamte Datenverzeichnis bewusst migrieren. Erwarten Sie nicht, dass ein neuer Docker-Container native Konten automatisch erkennt.

Installationsvoraussetzungen#

Für die native Installation sind Python 3.11 oder höher mit „venv“ und „ensurepip“, ein Internetzugang für die Installation der ersten Abhängigkeiten sowie ein beschreibbares Projektverzeichnis für „ .venv“ erforderlich. Das mitgelieferte Panel benötigt weder Node.js noch eine Frontend-Erstellung. Führen Sie den Launcher von Ihrem normalen Betriebssystem-Konto aus; Administrator- oder Root-Rechte werden von TgWitness nicht benötigt.

  • Windows: Start.cmd überprüft zunächst py -3, dann python, anschließend die standardmäßigen benutzerspezifischen und „Program Files“-Installationsordner und erfordert Version 3.11 oder höher. Sollte keine dieser Optionen funktionieren, bietet das Programm die oben beschriebene automatische benutzerspezifische Installation an. py -3 start.py funktioniert ebenfalls. Das portable Paket benötigt überhaupt kein Python.
  • Linux: start.sh probiert python3.13, python3.12, python3.11, python3 und python aus und gibt den Installationsbefehl für apt, dnf, pacman, zypper, apk oder Homebrew aus, sofern keiner davon geeignet ist. Bei Debian-/Ubuntu-Installationen ist möglicherweise das python3-venv-Paket erforderlich, das zum ausgewählten Interpreter passt. Die ältere Standard-Python-Version einer Distribution muss durch Python 3.11+ ersetzt oder ergänzt werden.
  • macOS: Installieren Sie eine aktuelle Python-3.11-Distribution; gehen Sie nicht davon aus, dass ein vom Betriebssystem bereitgestellter Interpreter die Anforderungen erfüllt. Verwenden Sie „python3 start.py“ aus dem Projektverzeichnis.
  • Docker: Verwenden Sie Docker Engine/Desktop mit Compose v2.20 oder neuer. Docker Desktop muss unter Windows Linux-Container verwenden. Der Container installiert seine eigenen Python-Abhängigkeiten; auf dem Host ist keine separate Python-Installation erforderlich.

Lokaler Computer#

Verwenden Sie „Start.cmd“ unter Windows oder „sh start.sh“ unter Linux/macOS. „scripts\Setup.cmd“ oder „sh start.sh --setup-only“ bereitet die Umgebung vor. Der Launcher installiert bei der ersten Verwendung die erforderlichen Abhängigkeiten; bei späteren Starts wird die Umgebung wiederverwendet. Für die Einrichtung und die Telegram-Erfassung ist ein Internetzugang erforderlich, das Durchsuchen bestehender Datensätze und das Erstellen von Exporten funktionieren jedoch offline.

Führen Sie nach der Einrichtung „python start.py --check“ aus, um lokale Abhängigkeiten, Ed25519, den Speicher, die Schlüsselkonfiguration und die Empfangsadresse zu überprüfen, ohne einen Collector zu starten. Verwenden Sie „--json“ für eine strukturierte Ausgabe. Übergeben Sie die vorgesehenen Befehle „--data-dir“, „--host“ und „--port“. Die Überprüfung installiert keine Pakete, erstellt kein Protokoll und stellt keine Verbindung zu Telegram her; es handelt sich nicht um eine Integritäts- oder Abdeckungsprüfung. Der Startvorgang überprüft separat vorhandene Protokolle. „python start.py --help“ vermeidet ebenfalls eine Installation.

Führen Sie nach dem Ausführen von „start.py“ die Zusatzbefehle mit „.venv\Scripts\python.exe“ unter Windows oder „.venv/bin/python“ unter Linux/macOS aus, oder aktivieren Sie diese Umgebung zunächst. Die folgenden „python -m ...“-Beispiele setzen voraus, dass die Umgebung aktiv ist.

python -m tgwitness --data-dir /path/to/private/data --host 127.0.0.1 --port 8787

Umgebungsvariablen: TGWITNESS_DATA, TGWITNESS_HOST, TGWITNESS_PORT, TGWITNESS_TOKEN. TGWITNESS_VAULT_KEY_FILE wählt den Modus mit externem Schlüssel für eine Neuinstallation aus; siehe Externer Hauptschlüssel. TGWITNESS_TOKEN muss, falls angegeben, mindestens 24 Zeichen enthalten; verwenden Sie einen kryptografisch zufälligen Wert. Ohne diese Angabe generiert die App ein 256-Bit-Zufallstoken in der Datei panel-token.txt. Die Umgehung über die Umgebungsvariablen überschreibt diese Datei nicht. Starten Sie die Anwendung neu, um die Anmeldedaten zu rotieren.

Ein Datenverzeichnis darf genau einem Prozess gehören. Eine plattformübergreifende Dateisperre des Betriebssystems verhindert versehentliche gleichzeitige Schreibvorgänge. Verwenden Sie einen Uvicorn-Worker. Das Panel kann eine beliebige Anzahl von Arbeitsbereichen verwalten, wobei zusätzliche Arbeitsbereichsverzeichnisse unter „profiles/<id>/“ liegen. Verwenden Sie für separate Service-Instanzen separate Verzeichnisse und Ports. SQLite-WAL-Dateien gehören in einen lokalen persistenten Speicher, nicht in ein Netzwerkdateisystem. Teilen Sie kein Volume zwischen Replikaten.

Portables Windows-Paket#

Jede GitHub-Veröffentlichung enthält TgWitness-<version>-windows-amd64-portable.zip und dessen .sha256. Sie umfasst die offizielle, einbettbare Python-3.12-Laufzeitumgebung von python.org (Prüfsumme in tools/build_portable.py festgehalten), TgWitness und dessen festgelegte Abhängigkeiten sowie drei Startprogramme:

Datei Zweck
TgWitness.cmd Starten Sie das Panel; zusätzliche Optionen werden weitergeleitet, z. B. TgWitness.cmd --port 8790
TgWitness-Demo.cmd Starten Sie die synthetische Demo unter data\demo
TgWitness-Check.cmd Führen Sie die Bereitschaftsprüfung durch, ohne das Programm zu starten

Das angeheftete russische Morphologie-Wörterbuch und die PDF-Farbprofile sind für die Offline-Nutzung gebündelt. Die Paketierung erlaubt nur ihre bekannten Dateipfade innerhalb der Verzeichnisse der Abhängigkeit data; unerwartete Dateien in diesen Verzeichnissen führen zum Fehlschlagen des Builds.

Entpacken Sie das gesamte Archiv in einen beschreibbaren Ordner wie beispielsweise „Documents\TgWitness“; führen Sie das Programm nicht direkt aus der ZIP-Datei oder aus dem Ordner „Programme“ aus. Die Laufzeitumgebung verwendet einen isolierten Modulpfad, sodass andere Python-Installationen und „PYTHONPATH“ keinen Einfluss darauf haben. Die Daten verbleiben im data-Ordner des Pakets. Um ein Update durchzuführen, beenden Sie TgWitness, entpacken Sie die neue Version in einen neuen Ordner und kopieren Sie den data-Ordner dorthin.

Stellen Sie es selbst unter 64-Bit-Windows mit Python 3.12 zusammen:

python tools/build_portable.py

Container#

docker compose up -d --build --wait

Dadurch wird ein benanntes persistentes Volume für /data erstellt. Der Web-Port wird auf 127.0.0.1:8787 abgebildet. Der Prozess läuft unter der UID 10001 mit eingeschränkten Rechten, einem schreibgeschützten Root-Dateisystem sowie beschreibbaren Verzeichnissen /data und /tmp. --wait überprüft den Zustand des Webservers, bevor die Rückgabe erfolgt; die Telegram-Autorisierung und -Zustellung werden im Panel angezeigt. Die bereitgestellten Hilfsprogramme verwenden nach dem Erstellen ein180-Sekunden-Timeout für die Betriebsbereitschaft . Das anfängliche Herunterladen von Abhängigkeiten kann länger dauern.

Beide Basis-„Compose“-Dateien verwenden den Projektnamen „tgwitness“, sodass beim Entpacken einer neuen Version in ein anderes Verzeichnis nicht automatisch ein neues Datenvolume ausgewählt wird. Halten Sie nur eine Bereitstellung für dieses Projekt aktiv. Verwenden Sie für unabhängige Installationen einen eindeutigen Namen „ docker compose -p NAME ...“ und einen anderen Host-Port und behalten Sie bei Updates beide bei. Bei einer älteren Bereitstellung mit einem anderen Projektnamen verwenden Sie weiterhin deren ursprünglichen Namen zusammen mit „-p“; „docker compose ls“ listet vorhandene Projekte auf.

Kopieren Sie deploy/env.example nach .env und ändern Sie TGWITNESS_PORT so, dass ein anderer Loopback-Port verwendet wird. Beispielsweise macht TGWITNESS_PORT=8788 das Panel unter http://127.0.0.1:8788 zugänglich; der Container lauscht weiterhin auf Port 8787. .env wird von Git ignoriert.

Das anfängliche Token abrufen:

docker compose exec tgwitness cat /data/panel-token.txt

Nützliche Befehle:

docker compose ps
docker compose logs --tail 100 -f
docker compose stop
docker compose up -d --wait

restart: unless-stopped startet den Collector nach einem Absturz oder einem Neustart des Docker-Daemons neu. Aktivieren Sie auf einem Linux-Server Docker beim Systemstart über den Dienstmanager Ihrer Distribution, in der Regel sudo systemctl enable --now docker. Unter Windows/macOS aktivieren Sie die Einstellung „Beim Anmelden starten“ in Docker Desktop. Das Abmelden vom Desktop, der Ruhezustand oder ein angehaltener Docker-Daemon die Datenerfassung unterbrechen. Ein explizit angehaltener Container bleibt angehalten, bis Sie ihn erneut starten.

Das /tmp-Volume ist in der Beispielkonfiguration auf 512 MiB begrenzt. Die Export-Konstruktion nutzt stattdessen den Ordner temporary-exports/ jedes Arbeitsbereichs auf dem persistenten Verzeichnis /data. Reservieren Sie dort Speicherplatz für gleichzeitige Exporte, das Wachstum von Journal/WAL, Medien und Backups. Der Launcher verwendet die Datei „deploy/constraints.txt“, um qualifizierte Versionen von Laufzeitabhängigkeiten festzulegen. Docker- und High-Assurance-Server werden anhand von `deploy/requirements.lock` und `deploy/build.lock` mit `pip --require-hashes` installiert: Jede Paketdatei muss mit einem im Commit gespeicherten SHA-256-Hash übereinstimmen, sodass eine auf PyPI oder einem Mirror ersetzte Datei abgelehnt wird. Pakete, die nur Quellcode enthalten (jieba, pyaes), werden mit den in „deploy/build.lock“ festgelegten setuptools (--no-build-isolation) vom Launcher, dem portablen Windows-Builder und der Dockerfile erstellt, sodass pip keine separate, nicht festgelegte Build-Umgebung auflöst. Das Python-Basis-Image und die Betriebssystempakete erfordern weiterhin eine unabhängige Release-Qualifizierung.

Verwenden Sie den Befehl „docker compose down -v“ nur, wenn Sie beabsichtigen, das Protokoll und die Schlüssel zu löschen. Der Container-Statusbericht gibt Auskunft über die Verfügbarkeit des Webservers, nicht über die erfolgreiche Erfassung von Telegram-Nachrichten. Überprüfen Sie den Status des Collectors, den Heartbeat, Fehler und Abdeckungsereignisse im Dashboard.

Profil eines unabhängigen Zeugen#

Der optionale Dienst witness führt einen unabhängigen Witness in einem eigenen Container aus, mit eigenem Schlüssel und eigenem Journal im Volume witness-data sowie einem ausschließlich schreibgeschützten Witness-Token für den Collector. Erstellen Sie das Token im Panel unter Weitere Tools → Extras → Unabhängiger Witness, fügen Sie es zusammen mit einem Bot-Token und einem Kanal zu .env hinzu und starten Sie dann das Profil:

docker compose --profile witness up -d          # deploy/compose/compose.image.yaml: same flag
docker compose logs witness                     # witness key fingerprint

Der Dienst erreicht den Collector innerhalb des Compose-Netzwerks unter http://tgwitness:8787 (TGWITNESS_WITNESS_COLLECTOR überschreibt diesen, beispielsweise /profiles/<workspace ID> für einen anderen Arbeitsbereich). Für einen Witness auf einem separaten Server, der von einer anderen Person betrieben wird, verwenden Sie dort deploy/compose/compose.witness.yaml , wobei TGWITNESS_WITNESS_COLLECTOR auf die HTTPS-Adresse des Collectors gesetzt ist; diese Datei enthält ausschließlich den Witness.

Installieren Sie ein veröffentlichtes Image#

Kopieren Sie deploy/env.example nach .env. Setzen Sie TGWITNESS_IMAGE auf die veröffentlichte Version, wobei Sie den Repository-Pfad in Kleinbuchstaben verwenden, zum Beispiel:

TGWITNESS_IMAGE=ghcr.io/your-owner/your-repository:0.9.3
TGWITNESS_PORT=8787

Führen Sie diese Datei separat aus, anstelle von „compose.yaml“:

docker compose --project-directory . -f deploy/compose/compose.image.yaml pull
docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait
docker compose --project-directory . -f deploy/compose/compose.image.yaml exec tgwitness cat /data/panel-token.txt

Auf dem Host sind weder eine Quellcode-Kompilierung noch Python oder ein Compiler erforderlich. Der Release-Workflow ist auf Linux-AMD64- und ARM64-Container ausgerichtet, einschließlich der Linux-VM von Docker Desktop. Verwenden Sie ein Versions-Tag oder „ghcr.io/owner/repository@sha256:...“ aus der Workflow-Zusammenfassung. Es ist weder ein bewegliches „latest“-Tag noch ein unbeaufsichtigtes Anwendungs-Upgrade konfiguriert. Die Image- und Quellvarianten nutzen dasselbe Datenvolumen, sofern ihre Projektnamen übereinstimmen.

Automatisches HTTPS auf einem Server#

Verwenden Sie einen Server mit Docker, eine von Ihnen verwaltete Domain und einen dauerhaften lokalen Speicher. Richten Sie die A-/AAAA-Einträge der Domain auf den Server aus; veröffentlichen Sie AAAA nur, wenn der Server über IPv6 erreichbar ist. Erlauben Sie eingehenden TCP-Verkehr auf den Ports 80 und 443 sowie ausgehenden DNS-/HTTPS-Verkehr für die Zertifikatsausstellung. Diese Ports dürfen nicht bereits von anderen Diensten belegt sein.

Kopieren Sie deploy/env.example nach .env und legen Sie einen Hostnamen fest, ohne Schema oder Pfad:

TGWITNESS_DOMAIN=watch.your-domain.org

Starten Sie den Quellcode-Build mit dem HTTPS-Overlay:

docker compose -f compose.yaml -f deploy/compose/compose.https.yaml up -d --build --wait
docker compose -f compose.yaml -f deploy/compose/compose.https.yaml exec tgwitness cat /data/panel-token.txt
docker compose --project-directory . -f deploy/compose/compose.image.yaml -f deploy/compose/compose.https.yaml up -d --wait

Verwenden Sie für ein veröffentlichtes Bild stattdessen „deploy/compose/compose.image.yaml“ als erste Datei. Behalten Sie beide „-f“-Argumente für spätere Status-, Protokoll-, Aktualisierungs- und Stoppbefehle bei.

Caddy bezieht und erneuert ein Zertifikat, leitet HTTP-Anfragen auf HTTPS um und leitet Anfragen an den Collector im privaten Compose-Netzwerk weiter. Der Zertifikatsstatus verfügt über ein eigenes persistentes Volume. Der direkte Host-Port des Collectors bleibt ausschließlich für Loopback-Verbindungen reserviert. Die bereitgestellte Caddy-Konfiguration aktiviert keine Zugriffsprotokollierung.

Öffnen Sie https://watch.your-domain.org und geben Sie das Panel-Token ein. Die Bereitschaftsprüfung umfasst die Container; die Zertifikatsausstellung und die Erreichbarkeit von externen Systemen hängen vom DNS und der Firewall ab. Wenn HTTPS nicht bereit ist, überprüfen Sie DNS, Firewall-Regeln und:

docker compose -f compose.yaml -f deploy/compose/compose.https.yaml logs --tail 100 caddy

Das bereitgestellte Caddy-Image folgt dem Tag „2-alpine“. Durch einen „Pull“ wird dieses Image aktualisiert; binden Sie einen getesteten Digest in Ihre Bereitstellung ein, falls Sie feste Infrastrukturversionen benötigen.

Aktualisierungen und Sicherungen#

Behalten Sie den Namen des „Compose“-Projekts und das Datenvolumen bei allen Aktualisierungen bei. Stoppen Sie zunächst den Collector und erstellen Sie eine vollständige Sicherung. Für die standardmäßige, quellbasierte Bereitstellung:

docker compose stop
docker compose cp tgwitness:/data ../tgwitness-backup-before-update

Verwenden Sie jedes Mal ein neues Sicherungsziel außerhalb des Repositorys und schützen Sie dieses als Material mit Kontozugriff. Der Beispielpfad dient nur zur Veranschaulichung; verwenden Sie Ihren privaten Speicherort für die Sicherung. Kopieren Sie das gesamte Verzeichnis, einschließlich versteckter Dateien, aller Arbeitsbereiche, Schlüssel, Protokolle und Medien. Sichern Sie einen externen Tresor-Hauptschlüssel separat, falls dieser konfiguriert ist. Eine ZIP-Datei mit Beweismaterial ist kein wiederherstellbares Anwendungs-Backup. Bei HTTPS bewahren Sie bitte auch die Caddy-Volumes auf, falls Sie den Status des Zertifikats bzw. des Kontos beibehalten müssen.

Für eine Installation aus dem Quellcode laden Sie bitte die Dateien der neuen Version herunter und führen Sie folgenden Befehl aus:

docker compose up -d --build --wait

Für die Installation der Image-Version ändern Sie bitte „TGWITNESS_IMAGE“ in die gewünschte Version und führen Sie anschließend folgenden Befehl aus:

docker compose --project-directory . -f deploy/compose/compose.image.yaml pull
docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait

Verwenden Sie die „Compose“-Datei(en) Ihrer Installation auch für die vorangehenden „stop“- und „copy“-Befehle. Behalten Sie „.env“, die benutzerdefinierte Konfiguration und denselben Projektnamen bei. „down“ behält benannte Volumes bei; „down -v“ löscht diese. Kopieren Sie „.venv“ nicht zwischen Betriebssystemen oder Python-Versionen. Für native Updates stoppen Sie TgWitness, sichern Sie das gesamte Datenverzeichnis, ersetzen Sie die Quelldateien und führen Sie „python start.py --setup-only“ vor dem Start aus.

Überprüfen Sie nach einem Update den Zugriff auf das Panel, die Kontoidentität, den Beobachtungsstatus und die Abdeckung. Nach dem Neustart setzt TgWitness die gespeicherte Telegram-Update-Position fort und fordert die während des Updates verpassten Updates an. Ein Rollback erfordert möglicherweise die Sicherung vor dem Update, falls eine zukünftige Version die Speicherformate ändert.

Entfernungsserver#

Beschränken Sie den Dienst auf Loopback und verwenden Sie einen SSH-Tunnel oder lassen Sie HTTPS an einem Reverse-Proxy enden. Die Basis-„Compose“-Datei ist ausschließlich lokal; das optionale „ deploy/compose/compose.https.yaml“-Overlay stellt Caddy für eine konfigurierte Domain bereit. Vermeiden Sie es, das Bearer-Token in URLs und Proxy-Protokollen offenzulegen. Ein Reverse-Proxy sollte die Anforderungsgröße und die Verbindungsraten begrenzen. Setzen Sie das Internet keinem unverschlüsselten HTTP aus.

Beispiele für systemd, eine Windows-Anmeldeaufgabe, einen macOS-User-Agent und Caddy finden Sie im Verzeichnis „deploy/“. Überprüfen und passen Sie deren Pfade vor der Installation an. Es handelt sich hierbei um bereitgestellte Vorlagen, nicht um lokal ausgeführte Plattformkonfigurationen. Es wird kein Hintergrunddienst oder keine Hintergrundaufgabe durch den normalen Launcher registriert.

Unter Windows speichert ein fensterloser pythonw.exe-Startvorgang die Start- und Serverdiagnosedaten in logs/server.log im Datenverzeichnis (5 MiB pro Datei, zwei rotierende Sicherungskopien). Bei Konsolenstarts werden die Konsolenprotokolle beibehalten. Die Protokollierung des HTTP-Zugriffs ist in beiden Modi deaktiviert. Schützen Sie die Protokolle zusammen mit dem Datenverzeichnis und überprüfen Sie diese, bevor Sie sie weitergeben.

Neustart und Lücken#

Der zuletzt angeforderte Beobachtungsstatus wird beibehalten. War die Beobachtung aktiv, versucht das Programm beim Start, die Verbindung wiederherzustellen und ausgewählte Quellen fortzusetzen. Durch manuelles Anhalten wird diese Absicht aufgehoben. Ein fehlgeschlagener Neustart wird protokolliert und im Bedienfeld angezeigt.

TgWitness speichert die Aktualisierungsposition von Telegram für das Konto und für jeden Kanal (pts, qts, seq und date) im Workspace-Tresor und stellt sie beim nächsten Start wieder her. Der Client fordert dann die Aktualisierungen an, die während des Stillstands des Prozesses verpasst wurden, und die regelmäßige Nachprüfung stellt verpasste Nachrichten wieder her und protokolliert gespeicherte Nachrichten, die Telegram nicht mehr zurückgibt. Dialoge werden beim Start neu geladen. Bei jedem Start werden der vorherige Journal-Anfang, die Offline-Grenze und die Aktualisierungsposition, an der die Wiederaufnahme erfolgte, aufgezeichnet. Der Monitor überprüft alle 10 Sekunden die Konnektivität und fügt jede Minute einen Heartbeat hinzu (Weitere Tools → Parameter → Liveness-Aufzeichnung alle). Verbindungsabbrüche und stillstehende Zeiträume werden als Abdeckungslücken mit Angabe des Grundes aufgezeichnet. Verlaufs-Snapshots werden als separate Beobachtungen des aktuellen Verlaufs neben den Live-Aufzeichnungen gespeichert.

Die Medienwarteschlange wird in der SQLite-Datenbank jedes Arbeitsbereichs gespeichert. Eine Nachricht und ihr Auftrag werden atomar festgeschrieben. Unterbrochene laufende Aufträge werden wiederhergestellt und beim Start erneut versucht. Jeder Download hat ein Basis-Timeout von 120 Sekunden zuzüglich der Zeit bei 256 KiB/s, die für seine Größe benötigt wird, sowie eine 1–2,000 MiB-Limit pro Anhangstyp; Timeout, Geschwindigkeit und Wiederholungsversuche sind unter Weitere Tools → Parameter einstellbar. Der Collector überspringt Dateien, deren Größe unbekannt ist. Beim Anhalten bleiben die in der Warteschlange befindlichen Aufgaben erhalten. Bei Wiederholungsversuchen wird der ursprüngliche beobachtete Dateideskriptor verwendet, niemals die neueste Version einer nachträglich bearbeiteten Nachricht. Vorübergehende Fehler haben eine begrenzte Anzahl von Wiederholungsversuchen; Pausen bei Media FloodWait bleiben nach einem Neustart erhalten. Die Medienwiederherstellung ist unabhängig von der Telegram-Update-Wiederherstellung und kann verschwundene Dateien nicht wiederherstellen.

Sicherung, Wiederherstellung und Speicherkapazität#

tgwitness backup FOLDER kopiert das Datenverzeichnis, während das Panel weiterläuft: zuerst die Checkpoints, dann die SQLite-Dateien über die Online-Backup-API, anschließend Schlüssel, Medien und Profile, sodass kein kopierter Checkpoint neuer ist als das kopierte Journal. backup-manifest.json listet den SHA-256-Hash jeder Datei sowie die Journal-Header auf. Zur Wiederherstellung stoppen Sie TgWitness und ersetzen Sie das gesamte Datenverzeichnis durch diesen Ordner. Beim nächsten Start wird protokolliert, dass das Journal aus einer älteren Kopie wiederhergestellt wurde. Dieser Eintrag vergleicht das Journal mit dem Kopf, der in TGWITNESS_STATE_DIR gespeichert ist, einem Ordner außerhalb des Datenverzeichnisses: dem tgwitness-state -Volume in Compose, unter /var/lib/tgwitness-state in den systemd-Einheiten und ansonsten im lokalen Statusordner des Benutzers . Ohne einen beschreibbaren Statusordner wird die Wiederherstellung nicht erkannt und dies wird einmalig im Protokoll vermerkt.

Ohne diesen Befehl müssen Sie den Prozess anhalten, bevor Sie das gesamte Datenverzeichnis kopieren, einschließlich „vault.key“, „signing.enc“, „credentials.enc“, der SQLite-Datenbank- und WAL-Dateien, der Medien, des Tokens, der Checkpoints sowie aller Unterverzeichnisse von „profiles/“. Stellen Sie die vollständige Kopie wieder her, während der Zieldienst angehalten ist. Fehlende Vault-Schlüssel oder eine Nichtübereinstimmung der Signaturschlüssel führen zu einem Fehlschlag beim Start; generieren Sie keine Schlüssel neu, um den Zugriff zu erzwingen.

Bewahren Sie geheime Backups verschlüsselt und mit Zugriffskontrolle auf. Die ZIP-Dateien mit den Beweismitteln sind portable Prüfartefakte, keine Anwendungs-Backups oder Backups von Telegram-Sitzungen. Es erfolgt keine automatische Löschung nach einer bestimmten Aufbewahrungsfrist. Planen Sie Speicherplatz für alle Nachrichten, Rohdaten, Metadaten, Medien, temporäre Exporte und Backups ein.

Starten Sie die Verifizierung und exportieren Sie Stream-Datensätze, anstatt das gesamte Journal zu laden. Ein Export fixiert einen Lese-Snapshot, während neue WAL-Schreibvorgänge fortgesetzt werden können; lang andauernde Exporte können WAL-Seiten zurückhalten, sodass die Festplattenkapazität weiterhin eine Rolle spielt. ZIP-Dateien sind auf 4 GiB (unkomprimiert) begrenzt, um der Standardeinstellung des unabhängigen Verifizierers zu entsprechen; Weitere Tools → Parameter → Größte signierte ZIP-Datei erhöht die Obergrenze, und solche Archive werden mit verify.py --max-gib N verifiziert. Andere Formate haben keine Begrenzung der Ereignisanzahl. Unterstützte Browser streamen Antwortblöcke in eine vom Benutzer ausgewählte Datei. Andere Browser puffern höchstens 128 MiB und leiten größere Übertragungen an die authentifizierte CLI weiter:

python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip

Verwenden Sie --profile ID aus „Exports“ → „Workspace ID“ für einen anderen Arbeitsbereich, --format zip|jsonl|csv|html oder --url https://your-server für einen Remote-Server oder --max-mib, um das Übertragungslimit von 5 GiB zu ändern. Einfaches HTTP ist nur für Loopback zulässig. Token werden in Headern übertragen, Weiterleitungen werden abgelehnt, vorhandene Dateien werden nicht überschrieben und unvollständige Downloads werden nicht als abgeschlossene Dateien veröffentlicht. Falls TGWITNESS_TOKEN das generierte Token überschreibt, verwenden Sie eine separat geschützte Datei, die diesen aktiven Wert enthält: panel-token.txt wird durch die Überschreibung nicht überschrieben. Der SHA-256-Wert des Befehls dient lediglich als Übertragungsprüfsumme; überprüfen Sie die signierte ZIP-Datei unabhängig davon.

Das Dashboard zeigt Medien in der Warteschlange bzw. fehlgeschlagene Medien, die ältesten ausstehenden Medien, freien Speicherplatz, Pausen bei Telegram- Anfragen sowie Quellen an, deren Zugriff noch nicht bestätigt ist. Diese Diagnosedaten stellen keine vollständige End-to-End-Überwachung der Datenübertragung dar. Arbeitsbereiche teilen sich einen Prozess; ein „lautes“ Konto kann daher dennoch andere beeinträchtigen. Separate Arbeitsprozesse, Aufbewahrung/Rotation, dauerhafte Wiederherstellung von Aktualisierungen sowie die vollständige Qualifizierung der Bereitstellung bleiben bestehen. Der bereichsbezogene Zugriff auf das Dashboard ist unter „Zugriff und Berechtigungen“ dokumentiert; unabhängige Kontrollpunkte werden im Zeugenleitfaden behandelt.

Detaillierte Anleitungen: Verbindung/Sicherheit und Betriebsmodi.