Odniesienie / Konfiguracja
Telegram · Wdrożenie
Proszę uruchomić TgWitness jako usługę w systemach Windows, Linux, macOS lub Docker, za protokołem HTTPS, z kopiami zapasowymi i aktualizacjami.
Język angielski · Русский · Ukraiński · Español · Português (Brasil) · Türkçe · العربية · فارسی · Urdu · हिन्दी · Bahasa Indonesia · Tiếng Việt · Chiński uproszczony
Proszę wybrać opcję instalacji#
W przypadku pakietu przenośnego należy rozpakować plik TgWitness-<version>-windows-amd64-portable.zip z
sekcji „GitHub Releases”. W przypadku pozostałych metod należy pobrać i rozpakować plik ZIP ze źródłami lub sklonować
repozytorium, a następnie uruchomić następujące polecenie z katalogu projektu:
| Instalacja | Rozpocznij | Czy działa w tle? |
|---|---|---|
| Pakiet przenośny dla systemu Windows | TgWitness.cmd |
Nie; proszę pozostawić okno otwarte. |
| Wersja natywna dla systemu Windows | Start.cmd |
Nie; w przypadku działania w tle należy skorzystać z opcjonalnego zadania logowania. |
| Wersja natywna dla systemów Linux/macOS | sh start.sh |
Nie; w celu działania w tle należy używać systemd/launchd. |
| Docker na dowolnym obsługiwanym serwerze | docker compose up -d --build --wait |
Tak, o ile działa demon Docker. |
| Narzędzie pomocnicze Docker w systemie Windows | scripts\Docker.cmd |
Tak; moduł pomocniczy oczekuje na informacje o stanie serwera internetowego. |
| Narzędzie pomocnicze Docker na systemach Linux/macOS | sh scripts/docker-start.sh |
Tak; moduł pomocniczy oczekuje na informacje o stanie serwera internetowego. |
W przypadku serwera w chmurze, który powinien być dostępny do weryfikacji przez stronę trzecią — utworzonego za pośrednictwem interfejsu API dostawcy, bez korzystania z SSH, dostępnego wyłącznie poprzez tunel Cloudflare — proszę zapoznać się z opisem wdrożenia o wysokim poziomie bezpieczeństwa.
Podczas uruchomienia natywnego programu tworzony jest prywatny plik .venv oraz instalowane są przypisane zależności.
Docker kompiluje je wewnątrz obrazu, bez konieczności korzystania z środowiska Python na hoście. Pierwsza
konfiguracja wymaga dostępu do Internetu. W przypadku braku Pythona w wersji 3.11 lub nowszej, Start.cmd wyświetla zapytanie przed
zainstalowaniem Pythona 3.12 dla bieżącego użytkownika systemu Windows (za pomocą winget, w przeciwnym razie za pomocą instalatora z python.org
po sprawdzeniu podpisu Python Software Foundation); nigdy nie wymaga
uprawnień administratora. Docker i usługi systemu operacyjnego pozostają wymaganiami wstępnymi.
Instalacje natywne i przenośne wykorzystują wolumin o nazwie „data/live” w obrębie swojego folderu. Docker korzysta z woluminu o nazwie „tgwitness-data”
w lokalizacji „/data”. Są to odrębne instalacje do momentu celowej migracji
całego katalogu danych. Nie należy oczekiwać, że nowy kontener Docker automatycznie wykryje natywne
konta.
Wymagania instalacyjne#
Instalacja natywna wymaga środowiska Python 3.11 lub nowszego wraz z modułami venv i ensurepip, dostępu do Internetu
w celu zainstalowania pierwszej zależności oraz katalogu projektu z uprawnieniami do zapisu dla modułu
.venv. Dołączony panel nie wymaga środowiska Node.js ani kompilacji interfejsu użytkownika. Proszę uruchomić program uruchamiający z
zwykłego konta użytkownika systemu operacyjnego; narzędzie TgWitness nie wymaga uprawnień administratora ani root.
- System Windows:
Start.cmdsprawdza lokalizacjępy -3, następniepython, a następnie domyślne foldery instalacyjne dla poszczególnych użytkowników oraz folder „Program Files” i wymaga wersji 3.11 lub nowszej. Jeśli żadna z tych opcji nie zadziała, narzędzie proponuje automatyczną instalację dla poszczególnych użytkowników, opisaną powyżej. Działa równieżpy -3 start.py. Pakiet przenośny nie wymaga w ogóle środowiska Python. - Linux:
start.shpróbujepython3.13,python3.12,python3.11,python3orazpythoni wyświetla polecenie instalacyjne dla apt, dnf, pacman, zypper, apk lub Homebrew, gdy żadna z opcji nie jest odpowiednia. Instalacje w systemach Debian/Ubuntu mogą wymagać pakietupython3-venvodpowiadającego wybranemu interpreterowi. Starszą domyślną wersję języka Python w danej dystrybucji należy zastąpić lub uzupełnić o Python 3.11+. - macOS: zainstaluj aktualną dystrybucję języka Python 3.11 lub nowszą; nie należy zakładać, że
interpreter dostarczony wraz z systemem operacyjnym spełnia wymagania. Należy użyć pliku
python3 start.pyz katalogu projektu. - Docker: należy korzystać z Docker Engine/Desktop wraz z Compose w wersji 2.20 lub nowszej. W systemie Windows program Docker Desktop musi korzystać z kontenerów Linux. Kontener instaluje swoje własne zależności języka Python; na komputerze hosta nie jest wymagana oddzielna instalacja języka Python.
Komputer lokalny#
W systemie Windows należy użyć kodu Start.cmd, a w systemach Linux/macOS – sh start.sh. Kod scripts\Setup.cmd lub
sh start.sh --setup-only służy do
przygotowania środowiska. Program uruchamiający instaluje zależności przy pierwszym uruchomieniu; kolejne uruchomienia
wykorzystują już przygotowane środowisko. Dostęp do Internetu jest wymagany podczas konfiguracji oraz gromadzenia danych z Telegrama,
jednak przeglądanie istniejących zapisów i tworzenie eksportów odbywa się w trybie offline.
Po zakończeniu konfiguracji proszę uruchomić polecenie „python start.py --check”, aby sprawdzić lokalne zależności, algorytm Ed25519,
pamięć masową, konfigurację kluczy oraz adres nasłuchowy bez uruchamiania modułu zbierającego dane.
Proszę użyć polecenia --json, aby uzyskać uporządkowany wynik. Proszę przekazać zamierzone polecenia --data-dir, --host oraz
--port. Sprawdzanie to nie powoduje instalacji pakietów, nie tworzy dziennika ani nie łączy się z aplikacją Telegram;
nie stanowi ono kwalifikacji pod kątem integralności ani zakresu. Podczas uruchamiania następuje oddzielna weryfikacja
istniejących dzienników. Polecenie python start.py --help również pozwala uniknąć instalacji.
Po uruchomieniu pliku start.py należy wykonać polecenia pomocnicze za pomocą .venv\Scripts\python.exe w systemie
Windows lub .venv/bin/python w systemach Linux/macOS, albo najpierw aktywować to środowisko.
Poniższe przykłady dotyczące python -m ... zakładają, że środowisko jest aktywne.
python -m tgwitness --data-dir /path/to/private/data --host 127.0.0.1 --port 8787
Zmienne środowiskowe: TGWITNESS_DATA, TGWITNESS_HOST, TGWITNESS_PORT, TGWITNESS_TOKEN. TGWITNESS_VAULT_KEY_FILE wybiera tryb klucza zewnętrznego dla nowej instalacji; zobacz Klucz główny zewnętrzny. TGWITNESS_TOKEN, jeśli zostanie podany, musi zawierać co najmniej 24 znaków; należy użyć wartości losowej wygenerowanej kryptograficznie. W przypadku braku tego parametru aplikacja generuje losowy token o długości 256 bitów w pliku panel-token.txt. Nadpisanie zmiennej środowiskowej nie powoduje ponownego zapisania tego pliku. Aby zmienić poświadczenia, należy ponownie uruchomić aplikację.
Katalog danych może być zarządzany wyłącznie przez jeden proces. Międzyplatformowa blokada plików systemu operacyjnego zapobiega przypadkowym równoczesnym zapisom. Należy używać jednego procesa roboczego Uvicorn. Panel może zarządzać dowolną liczbą obszarów roboczych, przy czym dodatkowe katalogi obszarów roboczych znajdują się w ścieżce profiles/<id>/. W przypadku oddzielnych instancji usługi należy stosować oddzielne katalogi i porty. Pliki WAL bazy SQLite powinny znajdować się w lokalnej pamięci trwałej, a nie w sieciowym systemie plików. Nie należy współdzielić jednego woluminu między replikami.
Pakiet przenośny dla systemu Windows#
Każda wersja opublikowana na GitHubie zawiera plik TgWitness-<version>-windows-amd64-portable.zip oraz jego
odpowiednik .sha256. Zawiera ona oficjalne środowisko uruchomieniowe Python 3.12 z serwisu python.org,
które można osadzić w innych aplikacjach (suma kontrolna zapisana w pliku tools/build_portable.py), program TgWitness wraz z jego stałymi zależnościami,
oraz trzy programy uruchamiające:
| Plik | Cel |
|---|---|
TgWitness.cmd |
Uruchom panel; dodatkowe opcje są przekazywane dalej, np. TgWitness.cmd --port 8790 |
TgWitness-Demo.cmd |
Uruchom demonstrację syntetyczną pod adresem data\demo |
TgWitness-Check.cmd |
Proszę uruchomić sprawdzanie gotowości bez uruchamiania |
Przypięty słownik morfologii języka rosyjskiego oraz profile kolorów w formacie PDF są dołączone do pakietu w celu
korzystania w trybie offline. Pakiet dopuszcza wyłącznie znane ścieżki do tych plików w katalogach zależności oznaczonych jako
data; obecność nieoczekiwanych plików w tych katalogach powoduje niepowodzenie kompilacji.
Rozpakuj całe archiwum do folderu z uprawnieniami do zapisu, np. Documents\TgWitness; nie uruchamiaj
programu z poziomu pliku ZIP ani z folderu Program Files. Środowisko uruchomieniowe korzysta z izolowanej ścieżki modułów,
więc inne instalacje języka Python oraz folder PYTHONPATH nie mają na nie wpływu. Dane pozostają w
folderze data pakietu. Aby zaktualizować oprogramowanie, należy zatrzymać TgWitness, rozpakować nową wersję do nowego
folderu, a następnie skopiować do niego folder data.
Zainstaluj samodzielnie na 64-bitowym systemie Windows z wykorzystaniem języka Python 3.12:
python tools/build_portable.py
Kontener#
docker compose up -d --build --wait
Powoduje to utworzenie nazwanego woluminu trwałego dla katalogu /data.
Port sieciowy jest mapowany na adres 127.0.0.1:8787. Proces działa pod identyfikatorem UID 10001 z ograniczonymi
uprawnieniami, z systemem plików root tylko do odczytu oraz katalogami /data i /tmp z prawem do zapisu.
--wait sprawdza stan serwera WWW przed zwróceniem wyniku; autoryzacja i
dostarczenie wiadomości w Telegramie pojawiają się w panelu. Dostarczone narzędzia pomocnicze stosują 180-sekundowy limit czasu gotowości
po kompilacji. Początkowe pobieranie zależności może potrwać dłużej.
Oba podstawowe pliki Compose wykorzystują nazwę projektu tgwitness, więc rozpakowanie nowej wersji
do innego katalogu nie powoduje automatycznego wyboru nowego woluminu danych. Należy utrzymywać tylko jedno
aktywne wdrożenie dla danego projektu. W przypadku niezależnych instalacji należy użyć unikalnej nazwy
docker compose -p NAME ... oraz innego portu hosta, a podczas aktualizacji zachować oba wdrożenia.
W przypadku starszego wdrożenia wykorzystującego inną nazwę projektu należy nadal używać jego pierwotnej
nazwy wraz z -p; docker compose ls wyświetla listę istniejących projektów.
Skopiuj deploy/env.example do .env i zmień TGWITNESS_PORT, aby używać innego portu pętli zwrotnej.
Na przykład TGWITNESS_PORT=8788 udostępnia panel pod adresem
http://127.0.0.1:8788; kontener nadal nasłuchuje na porcie 8787. .env jest pomijany przez Git.
Pobierz token początkowy:
docker compose exec tgwitness cat /data/panel-token.txt
Przydatne polecenia:
docker compose ps
docker compose logs --tail 100 -f
docker compose stop
docker compose up -d --wait
restart: unless-stopped uruchamia ponownie moduł zbierający dane po awarii lub ponownym uruchomieniu demona Docker.
Na serwerze z systemem Linux należy włączyć uruchamianie Docker przy starcie systemu za pomocą menedżera usług danej dystrybucji,
zwykle sudo systemctl enable --now docker. W systemach Windows/macOS należy włączyć
ustawienie „uruchom przy logowaniu” w programie Docker Desktop. Wylogowanie z komputera, przejście w stan uśpienia lub zatrzymanie
demona Docker mogą przerwać gromadzenie danych. Wyraźnie zatrzymany kontener pozostaje
w stanie zatrzymania do momentu jego ponownego uruchomienia.
W przykładowej konfiguracji rozmiar woluminu /tmp jest ograniczony do 512 MiB. Mechanizm eksportowania
wykorzystuje zamiast tego katalog temporary-exports/ w każdym obszarze roboczym, umieszczony na trwałym woluminie /data. Należy zarezerwować tam miejsce
na równoczesne eksporty, wzrost rozmiaru dziennika/WAL, nośniki danych i kopie zapasowe.
Program uruchamiający wykorzystuje plik deploy/constraints.txt do ustalenia kwalifikowanych wersji zależności środowiska uruchomieniowego.
Serwery Docker i serwery o wysokim poziomie bezpieczeństwa są instalowane na podstawie plików deploy/requirements.lock oraz
deploy/build.lock przy użyciu polecenia pip --require-hashes: każdy plik pakietu musi odpowiadać wartości SHA-256
zarejestrowanej w commitcie, więc plik zastąpiony na PyPI lub w serwerze lustrzanym zostanie odrzucony. Pakiety, które
zawierają wyłącznie kod źródłowy (jieba, pyaes), są kompilowane przy użyciu narzędzi setuptools przypisanych w pliku deploy/build.lock
(opcja --no-build-isolation) przez program uruchamiający, przenośny kompilator dla systemu Windows oraz plik Dockerfile,
dzięki czemu pip nie tworzy oddzielnego, nieprzypisanego środowiska kompilacji. Obraz bazowy Pythona
oraz pakiety systemu operacyjnego nadal wymagają niezależnej kwalifikacji do wydania.
Nie należy używać polecenia `docker compose down -v`, chyba że zamierza się zniszczyć dziennik i klucze. Raporty o stanie kontenera informują o dostępności serwera internetowego, a nie o pomyślnym przechwyceniu wiadomości z Telegrama. Należy sprawdzić stan kolektora panelu, sygnał kontrolny, błędy oraz zdarzenia związane z zasięgiem.
Profil niezależnego świadka#
Opcjonalna usługa witness uruchamia niezależnego świadka we własnym
kontenerze, z własnym kluczem i dziennikiem w woluminie witness-data oraz wyłącznie tokenem świadka tylko do odczytu
dla kolektora. Utwórz token w panelu w sekcji Więcej narzędzi → Dodatki → Niezależny świadek, dodaj go
wraz z tokenem bota i kanałem do pliku .env, a następnie uruchom profil:
docker compose --profile witness up -d # deploy/compose/compose.image.yaml: same flag
docker compose logs witness # witness key fingerprint
Usługa łączy się z modułem zbierającym w sieci Compose pod adresem http://tgwitness:8787
(adres TGWITNESS_WITNESS_COLLECTOR
ma pierwszeństwo, na przykład /profiles/<workspace ID>
dla
innego obszaru roboczego). W przypadku modułu świadczącego na oddzielnym serwerze, zarządzanym przez inną osobę, należy użyć
tam adresu deploy/compose/compose.witness.yaml
, ustawiając TGWITNESS_WITNESS_COLLECTOR
na adres HTTPS
modułu zbierającego; plik ten zawiera wyłącznie moduł świadczący.
Zainstaluj opublikowany obraz#
Skopiuj deploy/env.example do .env. Ustaw TGWITNESS_IMAGE na opublikowaną wersję, używając
ścieżki do repozytorium zapisanej małymi literami, na przykład:
TGWITNESS_IMAGE=ghcr.io/your-owner/your-repository:0.9.3
TGWITNESS_PORT=8787
Proszę uruchomić ten plik samodzielnie, zamiast pliku 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
Na serwerze nie jest wymagana kompilacja kodu źródłowego, język Python ani kompilator. Proces wydawania aktualizacji
jest przeznaczony dla kontenerów Linux AMD64 i ARM64, w tym dla maszyny wirtualnej Linux w programie Docker Desktop.
Należy użyć tagu wersji lub oznaczenia „ghcr.io/owner/repository@sha256:...” z podsumowania procesu.
Nie skonfigurowano przenoszenia tagu „latest” ani automatycznej aktualizacji aplikacji.
Obraz i warianty źródłowe korzystają z tego samego woluminu danych, o ile nazwa projektu jest identyczna.
Automatyczne włączenie protokołu HTTPS na serwerze#
Należy skorzystać z serwera z oprogramowaniem Docker, domeny, nad którą sprawują Państwo kontrolę, oraz trwałej pamięci lokalnej. Proszę skierować rekordy A/AAAA domeny na serwer; opublikuj rekord AAAA tylko wtedy, gdy serwer jest dostępny w sieci IPv6. Proszę zezwolić na ruch przychodzący na portach TCP 80 i 443 oraz ruch wychodzący przez DNS/HTTPS w celu wydania certyfikatu. Porty te nie mogą być już zajęte przez inne usługi.
Skopiuj deploy/env.example do .env i ustaw nazwę hosta, bez schematu ani ścieżki:
TGWITNESS_DOMAIN=watch.your-domain.org
Rozpocznij kompilację kodu źródłowego z nakładką HTTPS:
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
W przypadku opublikowanego obrazu należy zamiast tego użyć pliku deploy/compose/compose.image.yaml jako pierwszego. Należy zachować
oba argumenty -f na potrzeby późniejszych poleceń dotyczących statusu, logów, aktualizacji oraz zatrzymania.
Caddy pobiera i odnawia certyfikat, przekierowuje połączenia HTTP na HTTPS oraz przekazuje żądania do kolektora w prywatnej sieci Compose. Stan certyfikatu jest przechowywany na osobnym woluminie trwałym. Port hosta kolektora pozostaje przeznaczony wyłącznie do pętli zwrotnej. Dostarczona konfiguracja Caddy nie włącza rejestrowania dostępu.
Otwórz https://watch.your-domain.org i wprowadź token panelu. Przygotowanie
obejmuje kontenery; wydawanie certyfikatów i dostępność zewnętrzna zależą od DNS
i zapory sieciowej. Jeśli HTTPS nie jest gotowy, sprawdź DNS, reguły zapory sieciowej oraz:
docker compose -f compose.yaml -f deploy/compose/compose.https.yaml logs --tail 100 caddy
Dostarczony obraz Caddy jest oznaczony tagiem 2-alpine. Wykonanie polecenia „pull” powoduje odświeżenie tego obrazu;
w razie potrzeby zastosowania stałych wersji infrastruktury proszę przypiąć sprawdzony skrót do Państwa wdrożenia.
Aktualizacje i kopie zapasowe#
Należy zachować nazwę projektu Compose oraz objętość danych podczas aktualizacji. Najpierw należy zatrzymać moduł zbierający dane i wykonać pełną kopię zapasową. W przypadku domyślnego wdrożenia opartego na źródłach:
docker compose stop
docker compose cp tgwitness:/data ../tgwitness-backup-before-update
Za każdym razem należy korzystać z nowej lokalizacji kopii zapasowej, znajdującej się poza repozytorium, i chronić ją jako materiał wymagający dostępu do konta. Podana ścieżka ma charakter poglądowy; należy skorzystać z własnej prywatnej lokalizacji kopii zapasowej. Należy skopiować cały katalog, w tym pliki ukryte, wszystkie obszary robocze, klucze, dzienniki oraz pliki multimedialne. Jeśli został skonfigurowany, należy osobno wykonać kopię zapasową zewnętrznego klucza głównego skarbca. Plik ZIP z dowodami nie jest kopią zapasową aplikacji umożliwiającą przywrócenie danych. W przypadku protokołu HTTPS należy również zachować woluminy Caddy, jeśli konieczne jest zachowanie stanu certyfikatu/konta.
Aby przeprowadzić wdrożenie z kodu źródłowego, należy pobrać pliki nowej wersji i uruchomić:
docker compose up -d --build --wait
W przypadku wdrożenia obrazu należy zmienić TGWITNESS_IMAGE na żądaną wersję, a następnie uruchomić:
docker compose --project-directory . -f deploy/compose/compose.image.yaml pull
docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait
W przypadku powyższych poleceń stop/copy należy również skorzystać z plików Compose swojej instalacji.
Zachowaj plik .env, niestandardową konfigurację oraz tę samą nazwę projektu. Plik down zachowuje nazwane
woluminy; plik down -v je usuwa. Nie należy kopiować pliku .venv między systemami operacyjnymi
ani wersjami języka Python. W przypadku aktualizacji natywnych należy zatrzymać działanie TgWitness, wykonać kopię zapasową całego katalogu danych
, zastąpić pliki źródłowe, a przed uruchomieniem wykonać polecenie python start.py --setup-only.
Sprawdź dostęp do panelu, tożsamość konta, stan obserwacji oraz zakres pokrycia po aktualizacji. Po ponownym uruchomieniu TgWitness wznawia zapisany punkt aktualizacji Telegramu i żąda aktualizacji pominiętych podczas procesu. Cofnięcie zmian może wymagać kopii zapasowej sprzed aktualizacji, jeśli przyszła wersja zmieni formaty przechowywania danych.
Serwer zdalny#
Należy ograniczyć działanie usługi do pętli zwrotnej i korzystać z tunelu SSH lub zakończyć połączenie HTTPS na
proksie odwrotnym. Podstawowy plik Compose jest przeznaczony wyłącznie do użytku lokalnego; opcjonalna nakładka
deploy/compose/compose.https.yaml udostępnia serwer Caddy dla skonfigurowanej domeny.
Należy unikać umieszczania tokenu bearer w adresach URL i logach serwera proxy. Serwer proxy odwrotny powinien ograniczać
rozmiar żądań oraz częstotliwość połączeń. Nie należy udostępniać zwykłego protokołu HTTP w Internecie.
Przykłady dotyczące systemu systemd, zadania logowania w systemie Windows, agenta użytkownika w systemie macOS oraz serwera Caddy znajdują się w katalogu deploy/. Prosimy o sprawdzenie i dostosowanie ścieżek dostępu przed instalacją. Są to dostarczone szablony, a nie lokalnie wykonywane konfiguracje platformowe. Żadna usługa działająca w tle ani żadne zadanie nie są rejestrowane przez standardowy program uruchamiający.
W systemie Windows uruchomienie pythonw.exe bez okna powoduje zapisywanie diagnostyki uruchomienia/serwera w pliku
logs/server.log w katalogu danych (5 MiB na plik, dwie rotowane kopie zapasowe).
Uruchomienia z konsoli zachowują logi konsoli. Rejestrowanie dostępu HTTP jest wyłączone w obu
trybach. Należy zabezpieczyć logi wraz z katalogiem danych i przejrzeć je przed udostępnieniem.
Ponowne uruchomienie i luki#
Ostatni żądany stan obserwacji jest zachowywany. Jeśli obserwacja była aktywna, program podczas uruchamiania podejmuje próbę ponownego połączenia się i wznowienia wybranych źródeł. Ręczne wstrzymanie usuwa ten zamiar. Nieudane ponowne uruchomienie jest rejestrowane i wyświetlane w panelu.
TgWitness przechowuje pozycję aktualizacji Telegrama dla konta i dla każdego kanału (pts, qts, seq i data) w skarbcu obszaru roboczego i przywraca ją przy następnym uruchomieniu. Następnie klient żąda aktualizacji pominiętych podczas zatrzymania procesu, a okresowe ponowne sprawdzanie odzyskuje pominięte wiadomości i rejestruje te zapisane, których Telegram już nie zwraca. Okna dialogowe są ponownie ładowane przy uruchomieniu. Każde uruchomienie rejestruje poprzedni początek dziennika, granicę trybu offline oraz pozycję aktualizacji, od której nastąpiło wznowienie. Monitor sprawdza łączność co 10 sekund i dodaje sygnał kontrolny co minutę (Więcej narzędzi → Parametry → Rejestruj aktywność co). Rozłączenia i okresy ciszy są rejestrowane jako luki w pokryciu wraz z ich przyczyną. Migawki historii są przechowywane jako oddzielne obserwacje bieżącej historii obok zapisów na żywo.
Kolejka multimediów jest przechowywana w bazie danych SQLite każdego obszaru roboczego. Komunikat i związane z nim zadanie są zatwierdzane atomowo. Przerwane zadania są odzyskiwane w celu ponownej próby przy uruchomieniu. Każde pobieranie ma podstawowy limit czasu wynoszący 120 sekund plus czas obliczony przy prędkości 256 KiB/s w zależności od rozmiaru pliku oraz 1–2,000 MiB na typ załącznika; limit czasu, prędkość i liczba ponownych prób znajdują się w sekcji Więcej narzędzi → Parametry. Kolektor pomija pliki o nieznanym rozmiarze. Wstrzymanie zachowuje zadania w kolejce. Ponowna próba wykorzystuje oryginalny zaobserwowany deskryptor pliku, nigdy najnowszą wersję wiadomości edytowanej później. Tymczasowe awarie mają ograniczoną liczbę ponownych prób; wstrzymania FloodWait w zakresie multimediów są zachowywane po ponownym uruchomieniu. Odzyskiwanie multimediów jest oddzielone od odzyskiwania aktualizacji Telegramu i nie pozwala na odtworzenie znikniętych plików.
Tworzenie kopii zapasowych, przywracanie danych i pojemność#
tgwitness backup FOLDER
kopiuje katalog danych, podczas gdy panel nadal działa:
najpierw punkty kontrolne, następnie pliki SQLite za pośrednictwem interfejsu API kopii zapasowej online, a potem klucze, multimedia i
profile, dzięki czemu żaden skopiowany punkt kontrolny nie jest nowszy od skopiowanego dziennika. Plik backup-manifest.json
zawiera listę skrótów SHA-256 wszystkich plików oraz nagłówki dzienników. Aby przywrócić dane, należy zatrzymać TgWitness i zastąpić
cały katalog danych tym folderem. Przy następnym uruchomieniu zostanie odnotowane, że dziennik został przywrócony
ze starszej kopii. Zapis ten porównuje dziennik z nagłówkiem przechowywanym w
TGWITNESS_STATE_DIR
, folderze poza katalogiem danych: woluminie tgwitness-state
w
Compose, /var/lib/tgwitness-state
w jednostkach systemd, a w pozostałych przypadkach w lokalnym folderze stanu użytkownika
. Bez folderu stanu z uprawnieniami do zapisu przywrócenie nie zostanie wykryte, a dziennik wyświetli jednorazowy komunikat o tym fakcie.
Jeśli polecenie to nie zostanie wydane, należy zatrzymać proces przed skopiowaniem całego katalogu danych, w tym plików vault.key, signing.enc, credentials.enc, bazy danych SQLite i plików WAL, multimediów, tokenów, punktów kontrolnych oraz wszystkich podkatalogów profiles/. Przywróć kompletną kopię, gdy usługa docelowa jest zatrzymana. Brakujące klucze do skarbca lub niezgodność kluczy podpisujących spowodują niepowodzenie uruchomienia; nie należy regenerować kluczy w celu wymuszenia dostępu.
Tajne kopie zapasowe należy przechowywać w postaci zaszyfrowanej i z kontrolowanym dostępem. Pliki ZIP z dowodami są przenośnymi artefaktami do przeglądu, a nie kopiami zapasowymi aplikacji ani sesji Telegramu. Nie ma automatycznego usuwania danych po upływie okresu przechowywania. Należy zaplanować miejsce na dysku na wszystkie wiadomości, surowe metadane, pliki multimedialne, tymczasowe eksporty oraz kopie zapasowe.
Weryfikacja przy uruchomieniu i eksport rekordów strumienia zamiast ładowania całego dziennika.
Eksport przypinają odczytany migawkę, podczas gdy nowe zapisy WAL mogą być kontynuowane; długotrwałe eksporty
mogą zachowywać strony WAL, więc pojemność dysku nadal ma znaczenie. Pliki ZIP mają limit 4 GiB
po rozpakowaniu, aby odpowiadać domyślnym ustawieniom niezależnego weryfikatora; Więcej narzędzi → Parametry → Największy podpisany plik ZIP
zwiększa ten limit, a takie archiwa są weryfikowane za pomocą verify.py --max-gib N. Inne formaty nie mają limitu liczby zdarzeń.
Obsługiwane przeglądarki przesyłają strumieniowo fragmenty odpowiedzi do pliku wybranego przez użytkownika. Inne przeglądarki
buforują maksymalnie 128 MiB, a większe transfery kierują do uwierzytelnionego interfejsu CLI:
python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip
Proszę użyć --profile ID z menu Eksportuj → Identyfikator obszaru roboczego dla innego obszaru roboczego,
--format zip|jsonl|csv|html, --url https://your-server dla serwera zdalnego lub
--max-mib, aby zmienić limit transferu wynoszący 5 GiB. Zwykły protokół HTTP jest dozwolony wyłącznie w przypadku
pętli zwrotnej. Tokeny są przesyłane w nagłówkach, przekierowania są odrzucane, istniejące pliki
nie są nadpisywane, a niekompletne pliki do pobrania nie są publikowane jako pliki ukończone.
Jeśli zmienna TGWITNESS_TOKEN zastępuje wygenerowany token, należy użyć oddzielnie zabezpieczonego pliku
zawierającego tę aktywną wartość: plik panel-token.txt nie jest nadpisywany przez tę zmianę.
Wartość SHA-256 polecenia stanowi jedynie sumę kontrolną transferu; należy niezależnie zweryfikować podpisany plik ZIP.
Panel wyświetla multimedia oczekujące w kolejce lub, których przesłanie nie powiodło się, najstarsze multimedia oczekujące, wolne miejsce na dysku, przerwy w żądaniach serwisu Telegram oraz źródła, do których dostęp nie został potwierdzony. Te dane diagnostyczne nie stanowią kompletnego monitoringu dostarczania danych od początku do końca. Obszary robocze współdzielą ten sam proces; konto generujące nadmierną aktywność może nadal wpływać na pozostałe. Nadal obowiązują oddzielne procesy robocze, zasady przechowywania i rotacji danych, trwałe odzyskiwanie aktualizacji oraz pełna kwalifikacja wdrożenia. Dostęp do panelu w określonym zakresie jest udokumentowany w sekcji „Dostęp i uprawnienia”; niezależne punkty kontrolne są omówione w przewodniku dla świadków.
Szczegółowe procedury: połączenie/bezpieczeństwo oraz tryby działania.