# Telegram · Швидкий старт

Canonical page: https://phishdestroy.io/tgwitness/uk/docs/reference/quickstart/

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

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/uk/llms.txt)

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

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Документація](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md)

![Початок роботи](https://phishdestroy.io/tgwitness/assets/chapter-start.svg?v=443547f9bcd2)

**Англійська** · [Русский](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.io/tgwitness/uk/docs/reference/quickstart/#explore-the-interface) перш ніж підключити обліковий запис. [Оберіть посібник](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) щодо проксі-серверів, свідків, експорту або налаштування сервера. [GitHub Actions capture](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md) (попередній перегляд) запускає процес збору даних у вашому власному форку 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** нижче. [Розділ Встановлення, перевірка та оновлення](https://phishdestroy.io/tgwitness/uk/docs/reference/installation/) охоплює варіанти доступу до сервера, перевірку скрипта перед його запуском, оновлення та видалення.

### Інші методи

Випуски на GitHub, вихідний код та Docker є альтернативами інсталятору. Портативні версії для завантаження стають доступними після публікації релізної збірки:

| Хостинг | Нічого не встановлено | З джерела: Python 3.11+ | Docker: Engine/Desktop із Compose 2.20+ |
| --- | --- | --- | --- |
| Windows | Витягніть `TgWitness-<version>-windows-amd64-portable.zip` з GitHub Releases, двічі клацніть на `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
```

`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.io/tgwitness/uk/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

> [!ПОПЕРЕДЖЕННЯ] **Використовуйте спеціальні облікові записи.** Telegram може обмежити або назавжди заблокувати облікові записи за обсяги запитів, які він вважає надмірними, незалежно від клієнта. Підключайте облікові записи, підготовлені для спостереження, а не особисті чи цінні, та створюйте API-ідентифікатор / хеш на спеціальному обліковому записі.

1. Якщо запущено вбудовану демо-версію, зупиніть її та запустіть **Start.cmd** або `sh start.sh`. В іншому випадку залиште запущеною інсталяцію, яку було запущено вище.
2. Використовуйте токен панелі для входу. Відкриється новий робочий простір [для початкового налаштування](https://phishdestroy.io/tgwitness/uk/docs/reference/settings/). Оберіть **Просто завантажити**, **Стежити за чатами** або **Докази для справи**.
3. Перевірте налаштування з’єднання. За потреби налаштуйте власний проксі; налаштування з’єднання залишаються доступними після налаштування.
4. У **Connect Telegram** виберіть номер телефону, QR-код, файли облікового запису (TData, `.session`, StringSession, JSON-файл облікового запису) або повний ключ авторизації. За запитом введіть підтвердження Telegram, код та пароль двоступеневої аутентифікації.
5. Перевірте відображений обліковий запис, виберіть чати та перегляньте налаштування. Завершіть на останньому екрані. У разі вибору **Просто завантажити** **кнопка Почати експорт** запускає одноразовий експорт і відкриває вікно Експорти, щоб показати його хід; це не вмикає безперервне спостереження.

Після налаштування пункт **Чати → Вибрати** змінює вибрані чати. **У розділі Налаштування** керують збиранням та файлами; **Додаткові інструменти → Джерела** надає детальний список джерел на стандартному або експертному рівні. [Посібник із панелі](https://phishdestroy.io/tgwitness/uk/docs/reference/panel/) описує шість основних розділів та їхні контекстні елементи керування.

**API ID + Hash** є необов’язковими: робоча область використовує свою збережену або імпортовану пару, або робочу пару з вбудованого пулу. Щоб використовувати власний додаток, вставте одну пару `API ID:API Hash` у поле API ID. У поле **Auth key** вставте всі 512 шістнадцяткових символів та виберіть наданий DC ID. User ID є необов’язковим і перевіряється, якщо введено.

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

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

Для кількох облікових записів використовуйте **Облікові записи → Імпорт облікових записів** і виберіть підтримувані файли сесій. Супровідні JSON-файли зіставляються за базовим ім'ям файлу; кожен імпортований обліковий запис отримує власний робочий простір. Див. [масовий імпорт і групи облікових записів](https://phishdestroy.io/tgwitness/uk/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.io/tgwitness/uk/docs/reference/timestamp/) для отримання та перевірки відповіді.
- **Перевірка журналу:** перевірка підписів подій та ланцюжків. Експорт у форматі ZIP також перевіряє мультимедійні файли.

Підтримувані браузери зберігають великі експортні файли безпосередньо у вибраний файл. Інші браузери буферизують не більше 128 МіБ. Поки сервер працює, 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`). Перевіряйте архів за допомогою надійної копії верифікатора, незалежно збереженого відбитка ключа та, як мінімум для підтвердження, кореневого сертифіката служби міток часу (`--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-коду. Формати входу, SOCKS5, HTTP CONNECT, MTProxy та зовнішні головні ключі див. у файлі [CONNECTION-SECURITY.md](https://phishdestroy.io/tgwitness/uk/docs/reference/connection/).

**Призупинення спостереження** зупиняє збір даних. **Блокування** лише закриває доступ через браузер. Закриття вкладки не зупиняє процес збору даних. Зупинка процесу перериває збір; знімок історії не дозволяє відтворити всі пропущені редагування чи видалення. Дізнайтеся, [як працює збір даних](https://phishdestroy.io/tgwitness/uk/docs/reference/collection/) у контексті політик подій, черг вкладень, ізоляції облікових записів та поведінки при перезапуску.

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

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

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