Быстрый старт

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

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

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

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

Выгрузка через GitHub Actions (предварительная версия)

Выберите один из способов. Портативные версии для скачивания становятся доступны после публикации релизной сборки:

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

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

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

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#

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

1. Если запущена встроенная демонстрационная версия, остановите её и запустите файл Start.cmd или sh start.sh. В противном случае оставьте запущенной установку, созданную выше.
2. Используйте токен панели, соответствующий вашему способу установки, чтобы открыть панель.
3. Если вам требуется прокси-сервер, сохраните его в разделе «Аккаунт» → «Настройки» → «Настройки подключения» → «Изменить маршрут подключения».
4. В разделе «Учётная запись» введите свой номер телефона и нажмите «Продолжить», выберите «QR-код» → «Показать QR-код» или выберите файлы и нажмите «Подключить учётную запись». Указание «API ID + Hash» не является обязательным: рабочая область использует сохранённую или импортированную пару, либо рабочую пару из встроенного пула. Чтобы использовать собственное приложение, вставьте одну пару API ID:API Hash в поле «API ID». Для получения полного ключа авторизации выберите «Ключ авторизации», вставьте все 512 шестнадцатеричных символов и выберите предоставленный DC ID. Идентификатор пользователя является необязательным полем и проверяется при вводе.
5. Завершите выбранный вами способ входа: по телефону/коду/двухфакторной аутентификации (2FA), подтверждение из приложения Telegram с авторизованной учётной записью для сканирования QR-кода или импорт поддерживаемой авторизованной сессии.
6. Проверьте отображаемый идентификатор учётной записи. Открытые источники: ваши чаты загружаются автоматически; добавьте свои группы.
7. В разделе «Выберите, какие изменения сохранять» выберите категории событий или предустановку «Сообщения, правки и удаления», а затем сохраните настройки мониторинга.
8. Выберите настройки вложений отдельно, затем нажмите «Начать наблюдение».

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

Для существующих аккаунтов см. аккаунты и форматы сессий: панель принимает Telethon StringSession, SQLite от Telethon/Pyrogram, ZIP-архивы TData для одного аккаунта и поддерживаемые 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, воспользовавшись меню «Экспорт» → «Идентификатор рабочего пространства». Для удалённого сервера добавьте --url https://your-server. По умолчанию лимит передачи данных составляет 5 ГиБ; --max-mib позволяет изменить его. Для подписанного ZIP-содержимого по умолчанию установлен отдельный лимит проверки в 4 ГиБ в несжатом виде (параметры позволяют его увеличить; проверку таких архивов осуществляйте с помощью verify.py --max-gib N). Проверьте архив с помощью надёжной копии программы проверки и независимо сохраненного отпечатка ключа/контрольной точки.

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

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, а затем загрузить в Account. Также доступны прямой импорт файлов и вход с помощью QR-кода. См. файл CONNECTION-SECURITY.md для ознакомления с форматами входа, SOCKS5, HTTP CONNECT, MTProxy и внешними мастер-ключами.

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

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

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

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