Часть страницы пока на английском: английский оригинал изменился после перевода.
Справочник / Сбор
Эксплуатация TgWitness: мониторинг и восстановление
Ежедневная эксплуатация панели управления: режимы работы, категории мониторинга, параметры, уведомления, экспорт данных, резервное копирование и емкость хранилища.
TgWitness / Документация · Развертывание и восстановление
При первом подключении используйте учетные записи и форматы сеансов. Объяснение понятий «сохраненные версии», «политики событий» и «пробелы» см. в разделе «Как работает сбор данных». В данном руководстве рассматриваются вопросы повседневной эксплуатации и восстановления данных.
Управляемая установка включает файлы , START-HERE.html, и , а также файл START-HERE.txt и наряду с
её программой запуска, со ссылкой на репозиторий и командами, адаптированными к пути установки.
Запустите tgwitness guide --print через SSH или tgwitness paths, чтобы определить
фактический каталог данных. При установке с правами root через systemd частные данные хранятся в
/var/lib/tgwitness-…; /opt/tgwitness содержит саму программу.
Для управляемого временного туннеля Cloudflare код tgwitness tunnel off закрывает публичный
доступ, при этом локальная панель и сбор данных продолжают работать. Код tgwitness tunnel on
включает его; код tgwitness tunnel restart создает новое туннельное соединение. Используйте
код tgwitness open, чтобы увидеть его текущий адрес. Явное отключение сохраняется
после перезапуска службы. Код tgwitness stop останавливает как панель, так и сбор данных.
На этой странице
Рабочий процесс оператора#
Схема в текстовом формате
- Выберите тип хранения и способ защиты ключей → Откройте панель с помощью токена
- Откройте панель с помощью токена → Выберите рабочую область
- Выберите рабочую область → Настройка прямого или прокси-маршрута
- Настройка прямого или прокси-маршрута → Введите номер телефона или выберите файлы / QR-код
- Введите номер телефона или выберите файлы / QR-код → Проверьте личность владельца аккаунта и выберите доступные группы
- Проверьте личность владельца аккаунта и выберите доступные группы → Сохраните политики событий и вложений, после чего начните наблюдение
- Сохраните политики событий и вложений, после чего начните наблюдение → Мониторинг ошибок, доступа, очередей и дискового пространства
- Мониторинг ошибок, доступа, очередей и дискового пространства → Сохранение независимых контрольных точек
- Сохранение независимых контрольных точек → Экспорт и проверка материалов
Авторизация, транспортная связь, доступ к группе и полнота доставки являются разными свойствами. Зелёный статус соединения не означает, что все события были зафиксированы.
Делитесь результатами работы, не раскрывая главный ключ#
Откройте Дополнительные инструменты → Доступ, чтобы предоставить рецензенту или аналитику собственный токен. Выберите учетные записи и чаты, которые они могут открывать, а затем разрешите просмотр, экспорт или операционные действия. Оператору, запускающему/останавливающему сбор данных, требуется доступ ко всему рабочему пространству; рецензент может быть ограничен одним чатом. Ограничения сеансов, срок действия и правила IP-адресов не связаны с авторизацией учетной записи Telegram. См. раздел Доступ и разрешения.
Используйте функцию «Открытые сессии» для прекращения соединения или отзыва доступа, чтобы завершить все сессии. Консоль администратора объединяет данные о текущей активности процессов во всех рабочих пространствах. Закрытие сессии не прерывает работу системы сбора данных.
Режимы работы#
| Режим | Действие | Поведение |
|---|---|---|
| Демонстрационная версия | scripts\Demo.cmd или --demo |
Синтетические данные; подключение к реальным аккаунтам отключено |
| Замечание | Начать наблюдение | Регистрация обновлений по выбранным источникам |
| Снимок истории | Чаты → Действия в чате → Загрузить историю | До 500 текущих сообщений; реконструкция всех прошлых изменений не производится |
| Пауза | Наблюдение с паузой | Остановка сбора данных с сохранением имеющихся данных и заданий в очереди |
| Проверка/передача | Экспорт | Форматы ZIP, JSONL/CSV/HTML, контрольные точки, подтверждение обработки и запрос временных меток |
| Наличие нескольких учётных записей | Рабочие пространства или кнопка «+» вверху | Неограниченное количество отдельных рабочих пространств в рамках одного процесса |
Доступ к локальной демо-версии открывается автоматически без ручного ввода токена. Используется возможность, действующая на протяжении всего срока жизни процесса и действительная только для прямого доступа по лупбэку к изолированной синтетической демо-версии; токен главной панели не раскрывается. Реальные рабочие пространства, а также удалённый или проксированный доступ к демо-версии сохраняют аутентификацию по токену. Вход в демо-версию не предоставляет авторизации в Telegram.
Категории мониторинга#

В разделе Дополнительные инструменты → Источники → Запись → Выбрать, какие изменения сохранять выберите по отдельности новые сообщения, правки, уведомления об удалении, обновления реакций и события, связанные с членством. По умолчанию сохраняются все категории. Параметр Сообщения, правки и удаления сохраняет исходный контекст, отключая при этом отдельные обновления реакций и членства. Параметр Вся видимая активность восстанавливает все пять категорий. Предустановки изменяют форму; нажмите Сохранить настройки записи, чтобы применить изменения.
Сохраненная политика применяется ко всем выбранным источникам в данном рабочем пространстве. Другие рабочие пространства сохраняют свои собственные настройки. Каждое фактическое изменение фиксируется с указанием подписанных значений «до» и «после» ; текущая политика также включается в подтверждения процессов и записи о начале наблюдения . Отключение категории не приводит к удалению ранее зафиксированных наблюдений. Повторное включение не позволяет восстановить пропущенные изменения. В данной версии отсутствует возможность переопределения категорий на уровне отдельных групп.
Оставьте функцию «Новые сообщения» включённой, если важно сохранить предыдущее содержимое: уведомление об удалении не позволяет восстановить текст, который никогда не был зафиксирован. Оперативные записи, записи об охвате и другие события, связанные с работой групп, всегда сохраняются. Откровенные моментальные снимки истории отделены от выбора категорий в режиме реального времени и могут включать служебные сообщения. Эти настройки не удаляют метаданные о реакциях/участниках, встроенные в иначе зафиксированный объект Telegram.
При приостановке создания моментального снимка истории в очереди могут оставаться вложения. Начните наблюдение, чтобы обработать их. Нахождение в очереди не означает, что файл загружен. Недоступный исходный файл не заменяется более новой отредактированной версией; результаты фиксируются отдельно.
Функция «Lock» очищает доступ к браузеру и скрытые поля, но оставляет процесс сбора данных запущенным. Закрытие вкладки также оставляет процесс запущенным. Остановка процесса Python или службы прекращает сбор данных независимо от состояния браузера.
Дополнительное рабочее пространство можно удалить после того, как подписанный ZIP-архив или контейнер ASiC-E, содержащий его журнал и заметки на доске дела, будет полностью загружен. Одной только подготовки архива недостаточно: если в записи присутствуют события, не относящиеся к настройке, или если после загрузки была добавлена заметка, функция Удалить останется недоступной.
Когда панель получает сам файл, она учитывает экспорт только после получения каждого
байта, а затем сообщает размер по запросу POST /api/exports/{id}/received; прерванная загрузка
не учитывается. При использовании диалога выбора файла в браузере (доступ к файловой системе) панель сообщает об этом после того, как
файл записан и закрыт. Без него панель передаёт полученный файл в список
загрузок браузера и не может определить, сохранил ли его браузер, например, если диалоговое окно сохранения было
отменено; в этом случае панель сообщает, что загрузка началась, а не о том, что файл был сохранен. Файл,
загружаемый браузером самостоятельно (экспорт, размер которого превышает буфер браузера панели), а также
загрузка другим HTTP-клиентом учитываются после того, как сервер отправил весь ответ.
Операционная система и обратный прокси-сервер буферизуют несколько мегабайт ответа, поэтому в случае таких
загрузок сервер не может определить прерывание в конце. Если панель не сообщила, что файл был сохранен,
проверьте загруженный файл перед удалением. Групповой экспорт учитывается для соответствующих учетных записей, если он
загружен сразу после подготовки; повторная загрузка из раздела Подготовленные экспорты не учитывается.
Перед удалением на панели отображаются формат, размер, время подготовки и SHA-256 последнего загруженного
подписанного архива, а также запрашивается подтверждение того, что этот архив сохранен за пределами рабочей области. Сервер отклоняет запрос `
DELETE /api/profiles/{id}`, если для этого SHA-256 не установлен параметр `kept_copy` (или не установлен параметр `confirmed` для архива,
загруженного до того, как был записан отпечаток).
Удаление дополнительного рабочего пространства останавливает работу его сборщика и удаляет локальные данные. Если
удаление прерывается из-за заблокированного файла или ошибки файловой системы, панель сообщает об ошибке и
сохраняет рабочее пространство в списке как недоступное (DeletionPending). Закройте программы, в которых открыты его
файлы, и повторите попытку удаления. Перезапуск TgWitness оставляет данную рабочую область в остановленном состоянии и
не восстанавливает её частично удалённый журнал или ключи. Успешное удаление фиксируется
только после удаления каталога; отдельно экспортированные или резервные копии остаются
в соответствии с собственной политикой хранения.
Уведомления#
Откройте Настройки → Уведомления и внешняя копия → Пункты назначения уведомлений или Дополнительные инструменты → Дополнительные функции → Уведомления → Настроить. TgWitness использует Apprise для отправки оповещений в Matrix, Telegram, Discord, Slack, ntfy, по электронной почте и в другие поддерживаемые сервисы. К одному рабочему пространству можно добавить несколько пунктов назначения.
- Введите по одному адресу Apprise в каждой строке. Формат адреса для своего сервиса найдите в каталоге сервисов и форматов URL.
- Включите Отправлять уведомления и выберите оповещения о проблемах, изменениях в наблюдаемых чатах и ежедневный отчёт. Время ежедневного отчёта задаётся по часовому поясу сервера.
- Включите Добавлять короткие выдержки, если хотите получать в уведомлениях сохранённый текст удалённых и отредактированных сообщений.
- Нажмите Сохранить уведомления, затем Отправить тест, чтобы проверить доставку.
Для собственного сервера используйте JSON-вебхук Apprise. Например, jsons://notify.example.org/tgwitness отправляет JSON по HTTPS на указанный адрес. Это вымышленный пример — замените его адресом своего получателя.
Получатели и настройки относятся к выбранному рабочему пространству. Уведомления об изменениях охватывают его наблюдаемые источники, включая новые чаты. Колокольчик на верхней панели также показывает недавние проблемы и изменения в чатах.
В демо настройки уведомлений видны, но отправка отключена. Настройте доставку в рабочем пространстве вне демо. Уведомления используют его прямое соединение, SOCKS5 или HTTP; MTProxy для них не подходит. Получателям без HTTP, например SMTP, требуется прямое соединение.
Структура панели#

Журнал отображает наблюдения, функции поиска и фильтры. При редактировании открываются сохраненные версии; при удалении — предыдущее содержание, если оно доступно. Неизвестные источники указываются явно. Статистика доступна в разделе «Обзор»; подробности о сборе данных приводятся в локальном руководстве.
Откройте отредактированное сообщение, чтобы сравнить его версии в режиме Изменения в тексте или Рядом; вкладка Исходные данные показывает сохраненные поля. Изменения скрытых ссылок и кнопок ботов отображаются отдельно. Откройте предпросмотр вложения для просмотра сохраненных изображений, аудио или видео; кнопка скачивания позволяет получить сохраненный оригинал.
Режим Live обновляет журнал и чаты по мере поступления записей. Приостановите его на время проверки или используйте кнопку новых событий, когда будете готовы; сбор данных при этом продолжает работать. Сочетание Ctrl/Cmd+K находит действия панели и выполняет поиск по журналу.
Дополнительные инструменты → Источники содержат область наблюдения (выбранные чаты, папку Telegram или весь аккаунт), доступные чаты всех типов, выбранные источники с звездочками приоритета, настройки вложений и повторной проверки, а также снимки истории. Частные источники выбираются по диалогу/ID без публичной ссылки. Статус доступа описывает последнюю проверку, а не постоянные разрешения.
Отфильтруйте источники, отметьте их флажками, а затем одновременно включите, приостановите или отметьте их как приоритетные. В списке доступных чатов кнопка Добавить выбранные использует ваш выбор; Добавить все найденные использует текущий поисковый запрос и фильтр по типу.
В разделе «Чаты» → «Участники» перечислены все пользователи, сообщения которых сохранены; если для данного чата включена функция отображения профилей участников, один клик открывает профиль данного пользователя со ссылками на записи в журнале.
Дополнительные инструменты → Дополнительные функции → Независимый свидетель создаёт токены свидетеля, доступные только для чтения, показывает, когда каждый свидетель проводил последнюю проверку, и предоставляет команды и параметры для запуска одного из них (независимого свидетеля).
Дополнительные инструменты → В разделе Параметры содержатся все ограничения и темпы работы рабочей среды, которые не указаны на других страницах:
количество прочитанных диалогов, частота перечитывания списка чатов, интервалы пульсации и контрольных точек
, стартовый буфер, способ распределения запросов при повторной проверке (первая задержка, количество чатов за
прохода, пауза между чатами, восстановленные и повторно запрошенные сообщения), резерв дискового пространства, таймауты и
повторные попытки загрузки, критерии поиска профилей пользователей (включая ваши собственные регулярные выражения),
размер и частота уведомлений, ограничения на создание снимков, ZIP-архивы и загрузку в браузере, а также таймауты и повторные попытки
клиента Telegram. В каждом поле отображается диапазон значений и значение по умолчанию; изменённые поля
отмечаются и могут быть восстановлены по отдельности или все сразу. Каждое изменение фиксируется как
`parameters.changed` с указанием значений до и после, а записи о начале наблюдения
указывают действующие значения. Значения вступают в силу при следующем использовании; таймауты и повторные попытки клиента — при
следующем подключении. Интервалы повторной проверки, типы и размеры вложений, интервалы сохранения доказательств и копирования вне сервера
остаются на отдельных страницах и могут принимать любые значения в пределах своего диапазона, а не только предустановленные значения.
Звоночек в верхней панели отображает список недавних проблем и изменений в отслеживаемых чатах; непрочитанные сообщения подсчитываются до тех пор, пока не будут помечены как прочитанные. Изменения сгруппированы по чатам и часам («12 удалено, 1 отредактировано, 0 не найдено»), а такие проблемы, как выход из системы или переполнение диска, остаются в списке независимо от интенсивности активности в чатах.
Дополнительные инструменты → Регистрация аккаунта начинается с поля для ввода номера телефона. Нажатие Продолжить ведёт непосредственно к вводу кода, при этом учетные данные API запрашиваются только в случае их отсутствия. QR-код и импорт файлов — это альтернативные вкладки. Сохраненные учетные данные API повторно используются только в пределах собственной рабочей области. На экране ввода данных нет боковой панели, статистики или разделов настроек. Значок Настройки открывает управление API, прокси, хранилищем и дополнительными учётными записями. Новая рабочая область открывает начальную настройку ; после входа в систему рабочая область с сохраненными источниками и записями открывает раздел Чаты . Смена маршрута требует приостановки наблюдения и отменяет незавершённый вход в систему. Существующий журнал нельзя автоматически перепривязать к другой учётной записи Telegram.
Функция экспорта проверяет целостность журнала и создаёт переносимые файлы. Идентификатор рабочей области можно передать в командную строку загрузки. Каждый экспорт фиксирует префикс полного журнала; последующие события попадают в следующий экспорт. Фильтры поиска не изменяют область действия пакета. Подробная информация о подписи и охвате приведена в разделе Верификация и доказательства.
На панели отображается состояние коллектора, медиафайлы в очереди/с ошибками, самые старые медиафайлы в ожидании, свободное место на диске, паузы в запросах и источники, доступ к которым не подтверждён, в разделе «Состояние коллектора» . Изначально эти сведения свернуты и скрыты на вкладке «Учётная запись». На карточке настроек отображается следующий шаг: подключить учётную запись, выбрать источники или начать мониторинг. Список учётных записей представляет собой моментальный снимок на момент загрузки; выбранная рабочая область обновляется периодически. Это не многопроцессный монитор SLA.
Интерфейс использует локальные ресурсы и текстовую отрисовку исходного содержимого. Протестированы настольная и узкая раскладки в Chromium.
Среды развертывания#
| Среда | Установка | Статус проверки |
|---|---|---|
| ПК/сервер под управлением Windows | Python 3.11+, scripts\Setup.cmd/Start.cmd, каталог с конфиденциальными данными | Проверено локально на Windows/Python 3.12 |
| Сервер Linux/VPS | Python venv, выделенный сервер, HTTPS/SSH | Приведены примеры кода, CI и systemd; на данном хосте не выполняются |
| macOS | Python venv, процесс в фоновом режиме или пользовательский агент | Приведён пример с использованием launchd; требуется отдельная проверка установки |
| Docker/Compose | Постоянный объём данных, один рабочий узел | Предоставляются определение и проверка работоспособности CI; Docker недоступен локально |
| Мобильный браузер | Войдите в защищённую панель управления на работающем сервере | Проверена версия с узким макетом на базе Chromium; сборщик данных не работает на iOS/Android |
Переносимость означает отсутствие обязательного использования облачного сервиса или сборки интерфейса. Каждому целевому компьютеру по-прежнему требуются совместимые зависимости Python/crypto, а также доступ к локальному диску и сети. См. файл DEPLOYMENT.md и шаблоны сервисов.
Рабочие пространства совместно используют ЦП, память и цикл событий. Для изоляции процессов используйте отдельные экземпляры, порты, каталоги данных и авторизации учетных записей. Единой панели управления для отдельных экземпляров не существует. Ни в коем случае не направляйте несколько рабочих процессов на одну базу данных.
Проверка и экспорт данных#
Перед запуском подготовленной среды выполните команду python start.py --check. Добавьте параметр --json
для проверок в машиночитаемом формате или передайте нужные параметры --data-dir, --host и --port.
Команда проверяет наличие необходимых условий без входа в Telegram или создания журнала.
Проверка журнала выполняется во время запуска приложения, а готовность к сбору данных отображается
на панели. Занятый порт может просто означать наличие существующего экземпляра.
Браузеры, поддерживающие API доступа к файловой системе, сохраняют экспортированные данные через поток с правом записи. Другие браузеры буферизуют не более 128 MiB. Для экспорта больших объемов данных или при использовании браузеров без поддержки потоковой передачи файлов воспользуйтесь командной строкой потоковой передачи:
python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip
Добавьте --profile ID
из раздела «Экспорт» для дочернего рабочего пространства. Для удалённого доступа используйте --url https://server
. Простой HTTP допускается только для адресатов с обратной связью. Токен
считывается из файла и отправляется в заголовке, а не выводится на экран или включается в URL-адрес. Перенаправления
не допускаются. Существующие адресаты не перезаписываются. При сбое передачи удаляется
её временный фрагмент файла. Указанный SHA-256 представляет собой контрольную сумму передачи; проверьте подписанный
архив ZIP отдельно с помощью надёжного отпечатка/контрольной точки.
Резервное копирование, восстановление и сбои в работе#
- Приостановите наблюдение и аккуратно завершите процесс.
- Скопируйте весь каталог данных: базы данных, файлы WAL/SHM (если имеются), мультимедиа, файлы
credentials.enc,signing.enc,network.enc, ключи хранилища/метаданные, токен, контрольные точки и каждый каталогprofiles/. - В режиме внешнего ключа следует отдельно хранить мастер-ключ и сохранять каждый ключ
vault.external.json. Генерирование нового ключа не позволяет восстановить старые секретные данные. - Выполните восстановление при остановленном целевом устройстве; настройте исходный ключ, ограничьте доступ и проверьте целостность данных перед возобновлением работы.
- Записывайте время простоя и результаты проверки. Время простоя остаётся зафиксированным промежутком; моментальный снимок истории добавляет состояние после него.
Evidence ZIPs exclude sessions/private keys and are not full service backups.
tgwitness backup FOLDER makes the same copy while the panel keeps running and leaves out the
search index, which rebuilds itself; see Updates and backups.
Four things are protected differently:
| Что | Защита |
|---|---|
| Файлы экспорта без пароля (по умолчанию) | Подписано, поэтому изменения обнаружимы; чтобы зашифровать экспорт, задайте пароль |
| Файлы экспорта с паролем | Если вы установите пароль, готовый экспортный файл без изменений сохраняется в формате ZIP с шифрованием AES-256, который можно открыть с помощью программ 7-Zip и WinRAR; пароль не сохраняется (в целях обеспечения сохранности доказательств) |
| База данных журнала и сохраненные вложения на диске | Зашифрованный диск или том и права доступа к папке |
| Сессии Telegram и ключи подписи | Зашифровано в каталоге данных (credentials.enc, signing.enc, network.enc) |
Полная резервная копия представляет собой описанный выше каталог остановленных данных, а не экспорт.
Для обоих процессов следует использовать защищённое хранилище и специальный механизм передачи данных. Временные серверные экспорты хранятся в папке
temporary-exports/ каждого рабочего пространства; завершённые ответы очищаются, а прерванные файлы экспорта
удаляются при следующем запуске, пока удерживается блокировка экземпляра данного рабочего пространства.
После события восстановления соединения сборщик запрашивает пропущенные обновления, начиная с сохраненной позиции обновления. Постоянные задания на носителях и позиция обновления Telegram сохраняются после перезапуска; см. формат доказательств.
Вместимость и срок хранения#
Ограничения по умолчанию, все изменяемые в разделе Дополнительные инструменты → Параметры: первые 1,000 диалогов, 500 сообщений
на каждый снимок, 4 ГиБ несжатого подписанного ZIP-содержимого (для архивов большего размера требуется
verify.py --max-gib N) и 128 МиБ для резервного варианта браузера. Вложения занимают от 1 до 2,000 МиБ на
тип в разделе Дополнительные инструменты → Источники → Запись → Вложения. По умолчанию CLI-загрузчик передает 5 ГиБ. Доступное дисковое пространство может быть
нижним пределом. Зарезервируйте место для журналов, мультимедиа, WAL, временных экспортов и резервных копий.
При экспорте используется объем данных, а не каталог 512 МБ /tmp в Compose.
Измеряйте количество событий в секунду, возраст очереди, объем мультимедиа в байтах и задержку диска, а не просто подсчитывайте количество групп. Скорость доставки в реальном времени измеряется на работающем коллекторе. Автоматического удаления сохраненных данных не происходит. Удаление конца журнала аннулирует его связь с сохраненными контрольными точками.
Приоритетные перепроверки уже есть: отмеченные звёздочкой источники по умолчанию перепроверяются каждые 15 минут, остальные — каждые 6 часов (см. уровни перепроверки). Экспорт с паролем работает, как описано выше. Ограниченный доступ описан в разделе доступ и права. См. READINESS.md, LIVE_ACCEPTANCE.md и VERIFICATION.md.