Справочник / Установка
Установка TgWitness: Windows, Linux, macOS и Docker
Все способы установки и запуска TgWitness: пакет для Windows, Python, Docker и синтетическая демонстрационная версия с первыми проверками.
Английский язык · Русский · Украинский · 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, перезапуск, размещение изображений, обновления и резервное копирование.
Ознакомьтесь с интерфейсом#
- Запустите файл `TgWitness-Demo.cmd`
в портативном пакете, файл `scripts\Demo.cmd`
в исходной папке Windows
или файл `
sh start.sh --demo` в Linux/macOS. При запуске из исходного кода сначала создаётся файл `.venv` и устанавливаются зависимости. - Откройте страницу http://127.0.0.1:8787.
- Локальная демо-версия автоматически открывает пример журнала. Для прямого локального доступа не требуется ввод токена.
Демонстрационные сообщения являются вымышленными. В демонстрационном режиме невозможно подключить реальный аккаунт Telegram.
Подключить Telegram#
[!ПРЕДУПРЕЖДЕНИЕ] Используйте специальные аккаунты. Telegram может ограничить или навсегда заблокировать аккаунты за объем запросов, который он считает чрезмерным, независимо от клиента. Подключайте аккаунты, подготовленные для наблюдения, а не личные или ценные, и создавайте API-ID / хэш на специальном аккаунте.
- Если запущена встроенная демонстрационная версия, остановите её и запустите файл Start.cmd или
sh start.sh. В противном случае оставьте запущенной установку, созданную выше. - Войдите в систему с помощью токена панели. Откроется новое рабочее пространство для первоначальной настройки. Выберите Просто скачать, Следить за чатами или Доказательства по делу.
- Проверьте настройки подключения. При необходимости настройте собственный прокси; настройки подключения остаются доступными после настройки.
- В приложении Connect Telegram выберите номер телефона, QR-код, файлы учетной записи (TData,
.session, StringSession, JSON-файл учетной записи) либо полный ключ авторизации. При появлении запроса введите подтверждение Telegram, код и пароль двухэтапной аутентификации. - Проверьте отображаемую учетную запись, выберите чаты и проверьте настройки. Завершите на последнем экране. В случае выбора Просто скачать кнопка Начать экспорт запускает однократный экспорт и открывает страницу Экспорты, чтобы отобразить его ход; она не включает непрерывное наблюдение.
После настройки пункт Чаты → Выбрать изменяет выбранные чаты. В разделе Настройки управляются сбор данных и файлы; пункт Дополнительные инструменты → Источники предоставляет подробный список источников на стандартном или экспертном уровне. Руководство по панели описывает шесть основных разделов и их контекстные элементы управления.
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.