Wdrożenie

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:

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.cmd sprawdza lokalizację py -3, następnie python, 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.sh próbuje python3.13, python3.12, python3.11, python3 oraz python i 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ć pakietu python3-venv odpowiadają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.py z 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.

Proszę wykorzystać trwałą pamięć lokalną jako katalog danych. Należy zaplanować pojemność, uwzględniając liczbę wiadomości, pliki multimedialne, wzrost rozmiaru pliku WAL, eksporty oraz kopie zapasowe; nie istnieje oparta na dowodach, uniwersalna minimalna specyfikacja dotycząca dysku lub pamięci RAM dla każdego obciążenia. Architektury procesorów oraz wersje języka Python bez kompatybilnych zestawów zależności mogą wymagać dodatkowych narzędzi kompilacyjnych oraz ich własnej kwalifikacji. Termin „przenośny” nie oznacza uniwersalnej obsługi wszystkich systemów operacyjnych ani sprzętu.

Działanie na systemie Windows 11 z Pythonem 3.12 zostało zweryfikowane lokalnie. Definicje dla systemów Linux, macOS oraz kontenerów, a także środowisko CI zostały dostarczone, ale nie zostały uruchomione na tym serwerze deweloperskim. Dokładny zakres weryfikacji znajduje się w pliku VERIFICATION.md.

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.

Opcje:

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; patrz poniżej. TGWITNESS_TOKEN, o ile zostanie podany, musi zawierać co najmniej 24 znaki; należy użyć wartości losowej wygenerowanej kryptograficznie. W przypadku braku tego parametru aplikacja generuje losowy token 256-bitowy w pliku panel-token.txt. Nadpisanie zmiennej środowiskowej nie powoduje ponownego zapisania tego pliku. Należy ponownie uruchomić aplikację, aby zmienić dane uwierzytelniające.

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:

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

Kompilator weryfikuje sumę kontrolną środowiska uruchomieniowego, instaluje ograniczone zależności w pakiecie, przeprowadza kontrolę gotowości za pomocą wbudowanego interpretera oraz zapisuje plik ZIP wraz z sumą kontrolną w pliku dist/.

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 internetowego przed zakończeniem działania; nie nawiązuje połączenia w celu autoryzacji ani dostarczenia wiadomości w Telegramie. Dostarczone narzędzia pomocnicze stosują 180-sekundowy limit czasu gotowości po zakończeniu kompilacji. Początkowe pobieranie zależności może trwać 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. Konstrukcja eksportu wykorzystuje zamiast tego identyfikator temporary-exports/ każdego obszaru roboczego w trwałym katalogu /data. Należy zarezerwować tam miejsce na równoczesne eksporty, wzrost rozmiaru dziennika/WAL, pliki multimedialne oraz kopie zapasowe. Program uruchamiający wykorzystuje plik deploy/constraints.txt do ustalenia kwalifikowanych wersji zależności środowiska uruchomieniowego. Serwery Docker oraz 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, w związku z czym plik zastąpiony w serwisie PyPI lub na serwerze lustrzanym zostanie odrzucony. Obraz bazowy języka Python oraz pakiety systemu operacyjnego nadal wymagają niezależnej kwalifikacji 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. Należy utworzyć token na stronie „Witness” w panelu, dodać go wraz z tokenem bota i kanałem do .env, a następnie uruchomić 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#

Zostanie to udostępnione po pomyślnym zakończeniu procesu wydania oraz publicznej konfiguracji pakietu GHCR. Nazwa lub właściciel repozytorium nie są na stałe zakodowane w tym drzewie źródłowym. Proszę skorzystać z obrazka przedstawionego w podsumowaniu procesu wydania.

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.7.0
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.

Proszę otworzyć https://watch.your-domain.org i wprowadzić token panelu. Gotowość do tworzenia nie potwierdza wydania certyfikatu ani dostępności zewnętrznej. Jeśli protokół HTTPS nie jest gotowy, proszę sprawdzić 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.

Proszę sprawdzić dostęp do panelu, tożsamość konta, stan obserwacji oraz zakres działania po aktualizacji. Ponowne uruchomienie nie odtwarza pominiętych aktualizacji serwisu Telegram. Cofnięcie zmian może wymagać kopii zapasowej sprzed aktualizacji, jeśli przyszła wersja zmieni formaty przechowywania danych.

Zautomatyzowane wydania na GitHubie#

Proces wydawania jest gotowy do użycia po umieszczeniu tego projektu w repozytorium GitHub z włączoną funkcją Actions. Uruchamia się on w momencie opublikowania wydania na GitHubie, w tym również wersji przedpremierowej. Same wersje robocze i operacje dodawania tagów nie powodują publikacji pakietów.

1. Należy ustawić wersję pakietu oraz dziennik zmian, a następnie opublikować wydanie oznaczone tagiem „v” wraz z dokładną wersją „pyproject.toml”, np. „v0.7.0”.
2. Proces ten weryfikuje tag i uruchamia wspólne dla systemów Windows/Linux/macOS sprawdzanie środowiska Python, ogólne/import konta/QR w przeglądarce, pakietu źródłowego oraz Docker. Przeprowadzana jest również nowa instalacja natywna na wszystkich trzech systemach operacyjnych z wykorzystaniem języka Python 3.12.
3. Po pomyślnym przejściu tych kontroli przeprowadzane są testy wstępne obrazu ARM64 w środowisku QEMU, publikowane są obrazy AMD64/ARM64 na serwerze ghcr.io/<lowercase-owner>/<lowercase-repository>:<version>, a do wydania dołączany jest plik ZIP ze źródłami, suma kontrolna oraz pakiet Python wheel. Oddzielne zadanie w systemie Windows kompiluje i dołącza przenośny plik ZIP wraz z jego sumą kontrolną.
4. Po pierwszej publikacji należy otworzyć ustawienia pakietu GHCR i ustawić widoczność na „Publiczna”, jeśli planowane jest anonimowe pobieranie obrazów. Samo publiczne repozytorium źródłowe nie gwarantuje, że pakiet kontenerowy będzie publiczny. Polityka organizacji musi zezwalać na publikację pakietów. W procesie tym wykorzystywany jest GITHUB_TOKEN; w repozytorium nie należy umieszczać hasła do rejestru ani danych uwierzytelniających do serwera VPS.

Powyższe przygotowania lokalne nie gwarantują powodzenia pracy zdalnej. Emulacja ARM64 stanowi jedynie test wstępny, a nie kwalifikację na sprzęcie natywnym ani w rzeczywistym środowisku Telegramu. Funkcja ta automatyzuje pakowanie wydania; uruchomienie serwera nadal wymaga polecenia Compose oraz spełnienia związanych z nim wymagań dotyczących domeny i hosta. Istniejące serwery nie są automatycznie aktualizowane ani restartowane po opublikowaniu nowego wydania.

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.

StringSession zachowuje autoryzację, ale nie przechowuje trwałego stanu aktualizacji/entności z Telethon. Okna dialogowe są ponownie ładowane przy uruchomieniu. Telegram/Telethon może odtworzyć niektóre przerwy w transmisji podczas działania, jednak TgWitness nie gwarantuje trwałego odtworzenia danych po ponownym uruchomieniu procesu. Przy każdym uruchomieniu rejestrowany jest poprzedni początek dziennika oraz granica trybu offline. Monitor sprawdza łączność co 10 sekund i dodaje sygnał kontrolny co minutę (Parametry → Częstotliwość rejestrowania aktywności). Krótkie przerwy mogą zostać pominięte; połączenie transportowe nie gwarantuje pełnego dostarczenia aktualizacji. Migawki są wyraźnymi obserwacjami bieżącej historii, a nie uzupełnianiem luk.

Kolejka multimediów jest przechowywana w bazie danych SQLite każdego obszaru roboczego. Wiadomość i związane z nią zadanie są zatwierdzane atomowo. Przerwane zadania są odzyskiwane w celu ponownej próby po 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 limit 1–2 000 MiB na typ załącznika; limit czasu, prędkość i liczba ponownych prób są konfigurowane w sekcji „Parametry”. Moduł zbierający pomija pliki o nieznanym rozmiarze. Wstrzymanie zachowuje zadania w kolejce. Ponowna próba wykorzystuje oryginalny zarejestrowany deskryptor pliku, a nie najnowszą wersję wiadomości edytowanej później. W przypadku tymczasowych awarii liczba ponownych prób jest ograniczona; wstrzymania typu „FloodWait” dotyczą plików multimedialnych są zachowywane po ponownym uruchomieniu. Odzyskiwanie plików multimedialnych jest odrębne od odzyskiwania aktualizacji Telegramu i nie pozwala na odtworzenie utraconych plików.

Tworzenie kopii zapasowych, przywracanie danych i pojemność#

Należy zatrzymać proces przed skopiowaniem całego katalogu danych, w tym plików vault.key, signing.enc, credentials.enc, bazy danych SQLite/plików WAL, multimediów, tokenu, punktów kontrolnych oraz wszystkich profili i podkatalogów. Przywróć kompletną kopię, gdy usługa docelowa jest zatrzymana. Brakujące klucze do skarbca lub niezgodność kluczy podpisujących powodują 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 uruchomienia oraz eksport rekordów strumienia zamiast ładowania całego dziennika. Eksport utrwala odczytany migawkę, podczas gdy nowe zapisy do dziennika WAL mogą być kontynuowane; długotrwałe eksporty mogą zachowywać strony dziennika WAL, dlatego pojemność dysku nadal ma znaczenie. Pliki ZIP są ograniczone do 4 GiB po rozpakowaniu, aby odpowiadały domyślnym ustawieniom niezależnego weryfikatora; Parametry → Największy podpisany plik ZIP zwiększa ten limit, a archiwa tego typu są weryfikowane za pomocą verify.py --max-gib N. Inne formaty nie mają ograniczeń dotyczących 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.

Pliki eksportowe serwera pozostają w prywatnym katalogu temporary-exports/ każdego obszaru roboczego. Pomyślnie zakończone operacje usuwają swoje pliki. Przerwane eksporty są usuwane przy następnym uruchomieniu obszaru roboczego, gdy utrzymywana jest jego wyłączna blokada instancji. Katalog ten stanowi część modelu zagrożeń związanych z pamięcią masową oraz jej pojemnością; należy stosować zaszyfrowany wolumin danych. Transfery na skalę produkcyjną, o wielkości wielu gigabajtów, nadal wymagają weryfikacji w systemie docelowym.

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.

Opcje połączeń i zabezpieczeń#

Trasy połączeń są przypisane do poszczególnych obszarów roboczych i należy je skonfigurować przed autoryzacją. Protokół SOCKS5/HTTP CONNECT wykorzystuje przypisaną zależność python-socks. MTProxy korzysta z eksperymentalnego, losowego transportu pośredniego firmy Telethon; fałszywe sekrety TLS ee nie są obsługiwane. Bezpośrednie przełączanie awaryjne zależy od wybranego trybu IP: tryb „Ukryj adres IP” odrzuca tę opcję; tryb jawnego przełączania awaryjnego zezwala na to po upływie określonego opóźnienia. Tryb tunelu/VPN zezwala na bezpośrednie trasy, ale nie tworzy sieci VPN. Nie jest to polityka sieciowa obowiązująca w całym systemie.

W przypadku nowych instalacji zmienna TGWITNESS_VAULT_KEY_FILE wskazuje na oddzielnie zabezpieczony plik zawierający losowy klucz główny. Należy zamontować go w trybie tylko do odczytu poza katalogiem /data w kontenerze. Należy zachować publiczne metadane salt z pliku vault.external.json osobno dla każdego obszaru roboczego oraz dla klucza głównego. Istniejące lokalne skarbce wymagają zaplanowanej migracji; ustawienie tej zmiennej nie powoduje ich automatycznej konwersji. Przechowywanie wiadomości i multimediów oraz ich eksport nie są szyfrowane na poziomie aplikacji. W razie potrzeby należy stosować zaszyfrowane woluminy oraz zapewnić wystarczającą ilość prywatnej pamięci tymczasowej.

Szczegółowe procedury: połączenie/bezpieczeństwo oraz tryby działania.