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

Canonical page: https://phishdestroy.github.io/TgWitness/ru/docs/reference/quickstart/

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

**Английский язык** · [Русский](https://github.com/phishdestroy/TgWitness/blob/main/docs/ru/QUICKSTART.md) · [Украинский](https://github.com/phishdestroy/TgWitness/blob/main/docs/uk/QUICKSTART.md) · [Español](https://github.com/phishdestroy/TgWitness/blob/main/docs/es/QUICKSTART.md) · [Португальский (Бразилия)](https://github.com/phishdestroy/TgWitness/blob/main/docs/pt/QUICKSTART.md) · [Türkçe](https://github.com/phishdestroy/TgWitness/blob/main/docs/tr/QUICKSTART.md) · [العربية](https://github.com/phishdestroy/TgWitness/blob/main/docs/ar/QUICKSTART.md) · [Фарси](https://github.com/phishdestroy/TgWitness/blob/main/docs/fa/QUICKSTART.md) · [Урду](https://github.com/phishdestroy/TgWitness/blob/main/docs/ur/QUICKSTART.md) · [Хинди](https://github.com/phishdestroy/TgWitness/blob/main/docs/hi/QUICKSTART.md) · [Индонезийский язык](https://github.com/phishdestroy/TgWitness/blob/main/docs/id/QUICKSTART.md) · [Tiếng Việt](https://github.com/phishdestroy/TgWitness/blob/main/docs/vi/QUICKSTART.md) · [Упрощённый китайский](https://github.com/phishdestroy/TgWitness/blob/main/docs/zh/QUICKSTART.md)

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

**Впервые на сайте?** [Ознакомьтесь с демо-версией,](https://phishdestroy.github.io/TgWitness/ru/docs/reference/quickstart/#explore-the-interface) прежде чем подключить учётную запись. [Выберите руководство](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) по прокси-серверам, свидетелям, экспорту данных или настройке сервера.

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

[Выгрузка через GitHub Actions (предварительная версия)](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md)

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

| Хостинг | Ничего не установлено | Из исходного текста: 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`](https://github.com/phishdestroy/TgWitness/archive/refs/heads/main.zip) или клонируйте репозиторий:

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

Текущий исходный код включает массовый импорт аккаунтов, панель управления MTProxy и возобновляемую загрузку истории. Портативная предварительная версия 0.7.0 и ее архив исходного кода релиза вышли до этих нововведений. Границы версий см. в [журнале изменений](https://phishdestroy.github.io/TgWitness/ru/docs/reference/changelog/).

`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://phishdestroy.github.io/TgWitness/ru/docs/reference/deployment/) включает автоматическую настройку 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 идентифицируют ваше приложение; сами по себе они не предоставляют авторизацию учетной записи. Для закрытых групп не требуется публичное имя пользователя, однако ваша учетная запись должна иметь доступ к ним.

Для существующих аккаунтов см. [аккаунты и форматы сессий](https://phishdestroy.github.io/TgWitness/ru/docs/reference/accounts/): панель принимает Telethon StringSession, SQLite от Telethon/Pyrogram, ZIP-архивы TData для одного аккаунта и поддерживаемые JSON-файлы аккаунтов. Выберите файл сессии вместе с сопутствующим JSON-файлом и нажмите **Подключить аккаунт**. Вход по QR-коду также доступен с теми же необязательными настройками API. Сессии TDLib, ботов, а также реестры аккаунтов в форматах CSV/JSON не поддерживаются.

Для добавления нескольких аккаунтов используйте **Аккаунты → Импорт учетных записей** и выберите поддерживаемые файлы сессий. Сопутствующие JSON-файлы сопоставляются по базовому имени файла; каждый импортированный аккаунт получает собственное рабочее пространство. См. [массовый импорт и группы аккаунтов](https://phishdestroy.github.io/TgWitness/ru/docs/reference/accounts/#bulk-import-and-account-groups).

Чтобы добавить ещё одну учётную запись, нажмите **кнопку «+»** рядом с выбором учётной записи или откройте **«Учётные записи» → «Настройки» → «Настройки подключения» → «Рабочие пространства»**, либо воспользуйтесь **разделом «Учётные записи**». Рабочие пространства имеют отдельные сессии, журналы, ключи, источники и очереди. При переключении между видами остальные сборщики данных продолжают работать. Одна и та же учётная запись 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](https://phishdestroy.github.io/TgWitness/ru/docs/reference/timestamp/) для получения и проверки ответа.
- **Проверка журнала:** проверьте подписи событий и звенья цепочки. При экспорте в формат 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](https://phishdestroy.github.io/TgWitness/ru/docs/reference/connection/) для ознакомления с форматами входа, SOCKS5, HTTP CONNECT, MTProxy и внешними мастер-ключами.

**Приостановка наблюдения** останавливает сбор данных. **Блокировка** закрывает доступ только через браузер. Закрытие вкладки не останавливает процесс сбора данных. Остановка процесса прерывает сбор данных; моментальный снимок истории не позволяет восстановить все пропущенные изменения или удаления. Ознакомьтесь [с принципами работы сбора данных](https://phishdestroy.github.io/TgWitness/ru/docs/reference/collection/) в отношении политик событий, очередей вложений, изоляции учетных записей и поведения при перезапуске.

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

Ознакомьтесь с [файлом OPERATIONS.md](https://phishdestroy.github.io/TgWitness/ru/docs/reference/operations/) для получения информации о резервном копировании и восстановлении, с [файлом DEPLOYMENT.md](https://phishdestroy.github.io/TgWitness/ru/docs/reference/deployment/) — о размещении, а также с [каталогом deploy/](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md) для примеров использования сервиса. Установленная панель управления также содержит руководство по автономной настройке по адресу `/guide.html`.

Фактические результаты проверки и существующие ограничения изложены в файлах [VERIFICATION.md](https://phishdestroy.github.io/TgWitness/ru/docs/reference/verification/) и [READINESS.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/READINESS.md).