TgWitness / Документация

Что проверено →

Справочник / Установка

Установка TgWitness: Windows, Linux, macOS и Docker

Все способы установки и запуска TgWitness: пакет для Windows, Python, Docker и синтетическая демонстрационная версия с первыми проверками.

TgWitness / Документация

Начало работы

Английский язык · Русский · Украинский · Español · Португальский (Бразилия) · Türkçe · العربية · Фарси · Урду · Хинди · Индонезийский язык · Tiếng Việt · Упрощённый китайский

TgWitness — это автономное приложение для мониторинга групп и каналов Telegram, доступ к которым имеют ваши учетные записи. Оно работает локально с собственным каталогом данных.

Впервые на сайте? Ознакомьтесь с демо-версией, прежде чем подключить учётную запись. Выберите руководство по прокси, свидетелям, экспорту или настройке сервера. GitHub Actions capture (предварительный просмотр) запускает процесс сбора данных в вашем собственном форке GitHub вместо локальной установки.

Установка и запуск#

Установщик с пошаговыми инструкциями включает собственную версию Python и перед установкой проверяет хеши пакетов и подписи выпуска. Повторный запуск обновляет существующую установку.

Linux / macOS:

curl -fsSL https://get.destroy.tools/install.sh | bash

Windows (PowerShell или командная строка):

powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://get.destroy.tools/install.ps1 | iex"

На сервере Ubuntu запустите программу от имени root для установки фонового сервиса; на настольном компьютере запустите её от имени обычного пользователя. В Ubuntu установщик выводит адрес панели и ключ доступа; в macOS и Windows локальная панель открывается в браузере. Продолжите с раздела Подключение к Telegram ниже. Раздел Установка, проверка и обновление охватывает варианты доступа к серверу, проверку скрипта перед запуском, обновления и удаление.

Другие методы#

Релизы на GitHub, исходный код и Docker являются альтернативами установщику. Портативные версии для скачивания становятся доступны после публикации релизной сборки:

Хостинг Ничего не установлено Из исходного текста: Python 3.11+ Docker: Engine/Desktop с Compose версии 2.20 и выше
Windows Извлеките файл «TgWitness-<version>-windows-amd64-portable.zip» из релизов GitHub, дважды щелкните по файлу «TgWitness.cmd» Дважды щелкните по ссылке Start.cmd Дважды щелкните по ссылке scripts\Docker.cmd
Linux / macOS — sh start.sh sh scripts/docker-start.sh

Для запуска из исходного кода скачайте и распакуйте текущую ветку main или клонируйте репозиторий:

git clone https://github.com/phishdestroy/TgWitness.git
cd TgWitness

Start.cmd предложит установить Python 3.12 для вашего пользователя Windows, если подходящая версия Python не найдена (через winget или подписанный установщик с python.org). start.sh выведет точную команду установки для вашего дистрибутива Linux или macOS, если Python отсутствует. При первом запуске из исходного кода автоматически создается .venv и устанавливаются зависимости.

Docker собирает приложение и запускает его в фоновом режиме; установка Python на хосте не требуется. Команды «scripts\Docker.cmd» и «scripts/docker-start.sh» выводят адрес панели и токен, когда контейнер находится в рабочем состоянии. Соответствующие команды Docker для всех поддерживаемых хостов:

docker compose up -d --build --wait
docker compose exec tgwitness cat /data/panel-token.txt

Откройте страницу http://127.0.0.1:8787. Используйте токен, выведенный программой-помощником Docker или второй командой Docker, либо просмотрите файл data/live/panel-token.txt для переносимой или исходной установки. Продолжите на этапе «Подключение к Telegram» ниже. Нативные установки и установки через Docker используют отдельные хранилища; запуск Docker не приводит к импорту существующего нативного журнала.

Что касается сервера, развёртывание включает автоматическую настройку HTTPS, перезапуск, размещение изображений, обновления и резервное копирование.

Ознакомьтесь с интерфейсом#

  1. Запустите файл `TgWitness-Demo.cmd` в портативном пакете, файл `scripts\Demo.cmd` в исходной папке Windows или файл `sh start.sh --demo ` в Linux/macOS. При запуске из исходного кода сначала создаётся файл `.venv ` и устанавливаются зависимости.
  2. Откройте страницу http://127.0.0.1:8787.
  3. Локальная демо-версия автоматически открывает пример журнала. Для прямого локального доступа не требуется ввод токена.

Демонстрационные сообщения являются вымышленными. В демонстрационном режиме невозможно подключить реальный аккаунт Telegram.

Подключить Telegram#

[!ПРЕДУПРЕЖДЕНИЕ] Используйте специальные аккаунты. Telegram может ограничить или навсегда заблокировать аккаунты за объем запросов, который он считает чрезмерным, независимо от клиента. Подключайте аккаунты, подготовленные для наблюдения, а не личные или ценные, и создавайте API-ID / хэш на специальном аккаунте.

  1. Если запущена встроенная демонстрационная версия, остановите её и запустите файл Start.cmd или sh start.sh. В противном случае оставьте запущенной установку, созданную выше.
  2. Войдите в систему с помощью токена панели. Откроется новое рабочее пространство для первоначальной настройки. Выберите Просто скачать, Следить за чатами или Доказательства по делу.
  3. Проверьте настройки подключения. При необходимости настройте собственный прокси; настройки подключения остаются доступными после настройки.
  4. В приложении Connect Telegram выберите номер телефона, QR-код, файлы учетной записи (TData, .session, StringSession, JSON-файл учетной записи) либо полный ключ авторизации. При появлении запроса введите подтверждение Telegram, код и пароль двухэтапной аутентификации.
  5. Проверьте отображаемую учетную запись, выберите чаты и проверьте настройки. Завершите на последнем экране. В случае выбора Просто скачать кнопка Начать экспорт запускает однократный экспорт и открывает страницу Экспорты, чтобы отобразить его ход; она не включает непрерывное наблюдение.

После настройки пункт Чаты → Выбрать изменяет выбранные чаты. В разделе Настройки управляются сбор данных и файлы; пункт Дополнительные инструменты → Источники предоставляет подробный список источников на стандартном или экспертном уровне. Руководство по панели описывает шесть основных разделов и их контекстные элементы управления.

API ID + Hash не являются обязательными: рабочая область использует свою сохраненную или импортированную пару, либо рабочую пару из встроенного пула. Чтобы использовать собственное приложение, вставьте одну пару API ID:API Hash в поле API ID. В поле Auth key вставьте все 512 шестнадцатеричных символов и выберите предоставленный DC ID. User ID не является обязательным и проверяется при вводе.

Учетные данные API идентифицируют ваше приложение; сами по себе они не предоставляют авторизацию учетной записи. Для закрытых групп не требуется публичное имя пользователя, однако ваша учетная запись должна иметь доступ к ним.

Для существующих учетных записей см. форматы учетных записей и сеансов: панель поддерживает Telethon StringSession, Telethon/Pyrogram SQLite, TData ZIP для одной учетной записи и поддерживаемый JSON-файл учетной записи. Выберите сеанс и сопутствующий ему JSON-файл одновременно, нажмите Проверить файлы, а затем Подключить учетную запись. Также доступен вход по QR-коду с теми же опциональными настройками API. TDLib, сессии ботов и списки учетных записей в формате CSV/JSON не поддерживаются.

Для добавления нескольких аккаунтов используйте Аккаунты → Импорт учетных записей и выберите поддерживаемые файлы сессий. Сопутствующие JSON-файлы сопоставляются по базовому имени файла; каждый импортированный аккаунт получает собственное рабочее пространство. См. массовый импорт и группы аккаунтов.

Чтобы добавить ещё одну учётную запись, нажмите + рядом с выбором учётной записи или воспользуйтесь меню Учётные записи → Добавить учётную запись. Рабочие пространства имеют отдельные сессии, журналы, ключи, источники и очереди. При переключении между видами остальные коллекторы продолжают работать. Одна и та же учётная запись Telegram не может быть назначена двум рабочим пространствам в данной установке. Фиксированного количества рабочих пространств нет; они используют один процесс, поэтому пропускная способность зависит от мощности компьютера.

Токен панели в режиме реального времени защищает доступ к вашим авторизациям в Telegram и сохраненным материалам; он не связан с учетными данными API Telegram. Автоматическая регистрация происходит только для явно запущенной локальной демонстрационной версии, к которой осуществляется прямой доступ. Удаленная или прокси-версия по-прежнему использует data/demo/panel-token.txt.

Просмотр и экспорт#

  • Журнал: поиск и фильтрация записей по источнику и типу события.
  • Выберите событие, чтобы просмотреть его исходную запись, информацию об авторе и сохраненные версии.
  • В сведениях о редактировании отображается доступное содержание до и после изменения. В сведениях об удалении отображается последнее зафиксированное содержание, если таковое имеется; неизвестный участник остается неизвестным.
  • Форматы экспорта: подписанные файлы ZIP, JSONL, CSV и автономный HTML.
  • Полный экспорт чата (Чаты → Экспорт чата или Экспорт → Захват или экспорт одного чата): загрузите всю видимую историю одного чата в виде подписанного пакета с файлом chat.json (в стиле Telegram-export) и читаемым файлом chat.html. Частные чаты доступны, если аккаунт является участником. Это текущий снимок, а не реконструкция удалённых или ранее отредактированных сообщений. Проверьте копию с помощью команды python verify.py chat-export.zip --fingerprint TRUSTED_SHA256.
  • Контрольная точка сохранения: граница подписанного журнала должна находиться за пределами сборщика данных.
  • Скачать подписанную квитанцию о запуске: сохраните запись о программе и версии сборщика.
  • Подготовка запроса на получение временной метки: подготовьте автономный запрос к сервису выдачи временных меток; следуйте инструкциям в файле TIMESTAMP.md для получения и проверки ответа.
  • Проверка журнала: проверьте подписи событий и звенья цепочки. При экспорте в формат ZIP также проверяются мультимедийные файлы.

Поддерживаемые браузеры сохраняют объёмные экспортированные данные непосредственно в выбранный файл. Другие браузеры буферизуют не более 128 MiB. При работающем сервере интерфейс командной строки (CLI) для потоковой передачи данных поддерживает загрузку более объёмных файлов без буферизации всего ответа:

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

Для другого рабочего пространства добавьте --profile ID, используя Экспорт → ID рабочего пространства. Для удалённого сервера добавьте --url https://your-server. По умолчанию ограничение на передачу данных составляет 5 ГиБ; его можно изменить с помощью --max-mib. Для подписанного содержимого ZIP по умолчанию установлен отдельный лимит проверки в 4 ГБ в несжатом виде (пункт Дополнительные инструменты → Параметры позволяет увеличить его; проверку таких архивов выполняйте с помощью verify.py --max-gib N). Проверяйте архив с помощью доверенной копии средства проверки, независимо сохраненного отпечатка ключа и, как минимум для обеспечения доказательной силы, корневого сертификата службы меток времени (--tsa-ca).

Ознакомьтесь с инструкцией по установке#

python start.py --setup-only
python start.py --check
python start.py --check --json

--check проверяет локальные зависимости, поддержку подписи, хранилище, настройки ключей и адрес прослушивания. Он ничего не устанавливает и не подключается к Telegram. Занятый порт может означать, что запущен другой экземпляр. Используйте другой --port или сначала остановите его.

Программа запуска устанавливается в папку «.venv». Вспомогательные команды «python -m tgwitness...» должны использовать «.venv\Scripts\python.exe» в Windows или «.venv/bin/python» в Linux/macOS, если данная среда ещё не активирована.

Сеансы, защита и эксплуатация#

Закрытый, согласованный файл Telethon SQLite .session можно преобразовать локально с помощью python -m tgwitness.sessions account.session --out account.tgwitness-session, а затем загрузить в разделе Дополнительные инструменты → Учётная запись → Файлы. Также доступны прямой импорт файлов и вход по QR-коду. См. файл CONNECTION-SECURITY.md для ознакомления с форматами входа, SOCKS5, HTTP CONNECT, MTProxy и внешними мастер-ключами.

Приостановка наблюдения останавливает сбор данных. Блокировка закрывает доступ только через браузер. Закрытие вкладки не останавливает процесс сбора данных. Остановка процесса прерывает сбор данных; моментальный снимок истории не позволяет восстановить все пропущенные изменения или удаления. Ознакомьтесь с принципами работы сбора данных в отношении политик событий, очередей вложений, изоляции учетных записей и поведения при перезапуске.

Сеансы и секретные данные зашифрованы. Для хранения содержимого сообщений, мультимедиа и экспортированных данных требуется зашифрованный диск или том. Проверяйте подписи журнала по доверенному ключу и храните контрольные точки отдельно. Проверяйте записи захвата, внешние подтверждения времени и аттестаты среды для выбранного режима сбора данных.

Ознакомьтесь с файлом OPERATIONS.md для получения информации о резервном копировании и восстановлении, с файлом DEPLOYMENT.md — о размещении, а также с каталогом deploy/ для примеров использования сервиса. Установленная панель управления также содержит руководство по автономной настройке по адресу /guide.html.

Фактические результаты проверки и существующие ограничения изложены в файлах VERIFICATION.md и READINESS.md.