# Впровадження

Canonical page: https://phishdestroy.github.io/TgWitness/uk/docs/reference/deployment/

Запускайте TgWitness як службу на Windows, Linux, macOS або в Docker, через HTTPS, із резервним копіюванням та оновленнями.

**Англійська** · [Русский](https://github.com/phishdestroy/TgWitness/blob/main/docs/ru/DEPLOYMENT.md) · [Українська](https://github.com/phishdestroy/TgWitness/blob/main/docs/uk/DEPLOYMENT.md) · [Español](https://github.com/phishdestroy/TgWitness/blob/main/docs/es/DEPLOYMENT.md) · [Португальська (Бразилія)](https://github.com/phishdestroy/TgWitness/blob/main/docs/pt/DEPLOYMENT.md) · [Türkçe](https://github.com/phishdestroy/TgWitness/blob/main/docs/tr/DEPLOYMENT.md) · [العربية](https://github.com/phishdestroy/TgWitness/blob/main/docs/ar/DEPLOYMENT.md) · [فارсі](https://github.com/phishdestroy/TgWitness/blob/main/docs/fa/DEPLOYMENT.md) · [урду](https://github.com/phishdestroy/TgWitness/blob/main/docs/ur/DEPLOYMENT.md) · [हिन्दी](https://github.com/phishdestroy/TgWitness/blob/main/docs/hi/DEPLOYMENT.md) · [Індонезійська](https://github.com/phishdestroy/TgWitness/blob/main/docs/id/DEPLOYMENT.md) · [Tiếng Việt](https://github.com/phishdestroy/TgWitness/blob/main/docs/vi/DEPLOYMENT.md) · [简体中文](https://github.com/phishdestroy/TgWitness/blob/main/docs/zh/DEPLOYMENT.md)

## Оберіть варіант встановлення

Для отримання портативного пакета розпакуйте файл `TgWitness-<version>-windows-amd64-portable.zip` з GitHub Releases. Для інших методів завантажте та розпакуйте ZIP-архів з вихідним кодом або клонуйте репозиторій, а потім виконайте наступну команду з каталогу проєкту:

| Встановлення | Початок | Працює у фоновому режимі? |
| --- | --- | --- |
| Портативний пакет для Windows | `TgWitness.cmd` | Ні; залиште вікно відкритим. |
| Вбудована у Windows | `Start.cmd` | Ні; для роботи у фоновому режимі використовуйте додаткове завдання входу в систему. |
| Вбудована підтримка Linux/macOS | `sh start.sh` | Ні; для роботи у фоновому режимі використовуйте systemd/launchd. |
| Docker на будь-якому підтримуваному хості | `docker compose up -d --build --wait` | Так, поки працює демон Docker. |
| Допоміжний інструмент для Docker у Windows | `scripts\Docker.cmd` | Так; допоміжна програма очікує на стан працездатності веб-сервера. |
| Допоміжний інструмент для Docker на Linux/macOS | `sh scripts/docker-start.sh` | Так; допоміжна програма очікує на стан працездатності веб-сервера. |

Щодо хмарного сервера, який має бути доступним для перевірки третьою стороною — створеного за допомогою API провайдера, без SSH, доступ до якого здійснюється виключно через Cloudflare Tunnel — див. [розділ «Розгортання з високим рівнем надійності](https://github.com/phishdestroy/TgWitness/blob/main/docs/HIGH-ASSURANCE.md)».

Вбудований запуск створює приватний файл `.venv` та встановлює закріплені залежності. Docker компілює їх усередині образу, не потребуючи Python на хості. Для первинного налаштування потрібен доступ до Інтернету. Якщо Python 3.11+ не знайдено, `Start.cmd` запитує до встановлення Python 3.12 для поточного користувача Windows (winget, інакше — інсталятор з python.org після перевірки підпису Python Software Foundation); він ніколи не вимагає прав адміністратора. Docker та служби ОС залишаються обов’язковими вимогами.

Нативні та портативні інсталяції використовують `data/live` у своїй папці. Docker використовує том із назвою `tgwitness-data`, розташований за адресою `/data`. Це окремі інсталяції, доки ви свідомо не перенесете весь каталог даних. Не очікуйте, що новий контейнер Docker автоматично виявить нативні облікові записи.

## Вимоги до встановлення

Для нативна інсталяція потрібні Python 3.11 або новішої версії з `venv` та `ensurepip`, доступ до Інтернету для інсталяції першої залежності, а також каталог проєкту з правом запису для `.venv`. Для панелі, що входить до комплекту, не потрібні Node.js чи фронтенд-збірка. Запустіть програму-запускач зі свого звичайного облікового запису в ОС; TgWitness не вимагає прав адміністратора/root.

- **Windows:** `Start.cmd` перевіряє `py -3`, потім `python`, потім стандартні папки для кожного користувача та папку «Program Files», і вимагає версії 3.11 або пізнішої. Якщо жодна з них не працює, пропонується автоматична інсталяція для кожного користувача, описана вище. `py -3 start.py` також працює. Портативний пакет взагалі не потребує Python.
- **Linux:** `start.sh` перевіряє `python3.13`, `python3.12`, `python3.11`, `python3` та `python` і виводить команду встановлення для apt, dnf, pacman, zypper, apk або Homebrew, якщо жодна з них не підходить. Для встановлення в Debian/Ubuntu може знадобитися пакет `python3-venv`, що відповідає обраному інтерпретатору. Стару версію Python, встановлену за замовчуванням у дистрибутиві, необхідно замінити або доповнити Python 3.11+.
- **macOS:** встановіть актуальну дистрибуцію Python 3.11+; не вважайте, що інтерпретатор, наданий ОС, відповідає вимогам. Використовуйте файл `python3 start.py` із каталогу проєкту.
- **Docker:** використовуйте Docker Engine/Desktop із Compose v2.20 або новішою версією. Docker Desktop повинен використовувати контейнери Linux у Windows. Контейнер встановлює свої власні залежності Python; на хості не потрібно окремо встановлювати Python.

Використовуйте постійне локальне сховище для каталогу даних. Плануйте ємність з урахуванням обсягу повідомлень, медіафайлів, зростання WAL, експорту та резервних копій; не існує універсальних мінімальних вимог до дискового простору та оперативної пам’яті, що ґрунтуються на фактичних даних, для кожного навантаження. Архітектури процесорів та версії Python, для яких відсутні сумісні колеса залежностей, можуть вимагати додаткових інструментів збірки та їх власної кваліфікації. «Портативний» не означає універсальної підтримки будь-яких ОС чи апаратного забезпечення.

Windows 11/Python 3.12 перевірено локально. Описи для Linux/macOS/контейнерів та CI надано, але на цьому хості розробки вони не виконувалися. Точний обсяг перевірки див. у файлі [VERIFICATION.md](https://phishdestroy.github.io/TgWitness/uk/docs/reference/verification/).

## Локальний комп’ютер

Використовуйте `Start.cmd` у Windows або `sh start.sh` у Linux/macOS. `scripts\Setup.cmd` або `sh start.sh --setup-only` готує середовище. Програма запуску встановлює залежності під час першого використання; подальші запуски використовують уже готове середовище. Для налаштування та збору даних Telegram потрібен доступ до Інтернету, але перегляд існуючих записів та створення експортних файлів працюють в автономному режимі.

Після налаштування запустіть `python start.py --check`, щоб перевірити локальні залежності, Ed25519, сховище, конфігурацію ключів та адресу прослуховування без запуску колектора. Використовуйте `--json` для структурованого виводу. Передайте потрібні `--data-dir`, `--host` та `--port`. Ця перевірка не встановлює пакети, не створює журнал і не підключається до Telegram; вона не є перевіркою цілісності чи повноти охоплення. Під час запуску окремо перевіряються існуючі журнали. `python start.py --help` також дозволяє уникнути інсталяції.

Варіанти:

Після запуску start.py виконайте допоміжні команди з `.venv\Scripts\python.exe` у Windows або `.venv/bin/python` у Linux/macOS, або спочатку активуйте це середовище. Наведені нижче приклади `python -m ...` передбачають, що середовище вже активне.

```
python -m tgwitness --data-dir /path/to/private/data --host 127.0.0.1 --port 8787
```

Змінні середовища: TGWITNESS_DATA, TGWITNESS_HOST, TGWITNESS_PORT, TGWITNESS_TOKEN. TGWITNESS_VAULT_KEY_FILE вибирає режим зовнішнього ключа для нової інсталяції; див. нижче. TGWITNESS_TOKEN, якщо вказано, має містити щонайменше 24 символи; використовуйте криптографічно випадкове значення. Без нього програма генерує 256-бітний випадковий токен у файлі panel-token.txt. Перезапис змінних середовища не змінює цей файл. Перезапустіть програму, щоб змінити облікові дані.

Каталог даних може належати лише одному процесу. Міжплатформова блокування файлів ОС запобігає випадковим одночасним операціям запису. Використовуйте один робочий процес Uvicorn. Панель може керувати будь-якою кількістю робочих просторів, з додатковими каталогами робочих просторів у профілях profiles/<id>/. Для окремих екземплярів служби використовуйте окремі каталоги та порти. Файли WAL SQLite мають зберігатися у локальному постійному сховищі, а не в мережевій файловій системі. Не використовуйте один том для декількох реплік.

## Портативний пакет для Windows

Кожен реліз на GitHub містить `TgWitness-<version>-windows-amd64-portable.zip` та його `.sha256`. Він містить офіційне вбудовуване середовище виконання Python 3.12 з python.org (контрольна сума зафіксована в `tools/build_portable.py`), TgWitness та його зафіксовані залежності, а також три програми запуску:

| Файл | Мета |
| --- | --- |
| `TgWitness.cmd` | Запустіть панель; додаткові параметри передаються, наприклад, `TgWitness.cmd --port 8790` |
| `TgWitness-Demo.cmd` | Запустіть синтетичну демонстрацію за посиланням `data\demo` |
| `TgWitness-Check.cmd` | Виконайте перевірку готовності, не запускаючи програму |

Розпакуйте весь архів у папку з правами на запис, наприклад `Documents\TgWitness`; не запускайте програму зсередини ZIP-архіву або з папки «Program Files». Середовище виконання використовує ізольований шлях до модулів, тому інші інсталяції Python та `PYTHONPATH` не впливають на нього. Дані зберігаються у папці `data` цього пакету. Для оновлення зупиніть TgWitness, розпакуйте нову версію в нову папку та скопіюйте туди папку `data`.

Створіть його самостійно на 64-бітній Windows із Python 3.12:

```
python tools/build_portable.py
```

Конфігуратор перевіряє контрольну суму під час виконання, встановлює обмежені залежності в пакет, запускає перевірку готовності за допомогою вбудованого інтерпретатора та записує ZIP-файл і контрольну суму в `dist/`.

## Контейнер

```
docker compose up -d --build --wait
```

Це створює іменований постійний том для /data. Веб-порт прив’язано до 127.0.0.1:8787. Процес працює під UID 10001 із обмеженими правами, кореневою файловою системою, доступною лише для читання, та каталогами /data та /tmp, доступними для запису. `--wait` перевіряє працездатність веб-сервера перед поверненням; він не встановлює авторизацію чи доставку Telegram. Надані допоміжні програми використовують 180-секундний тайм-аут готовності після збірки. Початкове завантаження залежностей може зайняти більше часу.

Обидва базові файли Compose використовують назву проєкту `tgwitness`, тому розпакування нового релізу в інший каталог не призведе до автоматичного вибору нового тома даних. Залишайте активним лише одне розгортання для цього проєкту. Для незалежних інсталяцій використовуйте унікальний `docker compose -p NAME ...` та інший порт хосту, і зберігайте обидва під час оновлень. Для старішого розгортання, що використовує іншу назву проєкту, продовжуйте використовувати його оригінальну назву разом із `-p`; `docker compose ls` перелічує існуючі проєкти.

Скопіюйте `deploy/env.example` до `.env` та змініть `TGWITNESS_PORT`, щоб використовувати інший порт зворотного зв’язку. Наприклад, `TGWITNESS_PORT=8788` відкриває доступ до панелі за адресою `http://127.0.0.1:8788`; контейнер як і раніше прослуховує порт 8787. `.env` ігнорується Git.

Отримати початковий токен:

```
docker compose exec tgwitness cat /data/panel-token.txt
```

Корисні команди:

```
docker compose ps
docker compose logs --tail 100 -f
docker compose stop
docker compose up -d --wait
```

`restart: unless-stopped` перезапускає колектор після збою або перезапуску демона Docker. На сервері під управлінням Linux увімкніть Docker під час завантаження за допомогою менеджера служб вашого дистрибутива, зазвичай `sudo systemctl enable --now docker`. У Windows/macOS увімкніть параметр «запускати під час входу» у Docker Desktop. Вихід із системи, перехід у режим сну або зупинка демона Docker можуть перервати збір даних. Явно зупинений контейнер залишається зупиненим, доки ви його знову не запустите.

У наведеному прикладі конфігурації обсяг тома /tmp обмежено 512 MiB. Структура експорту замість цього використовує `temporary-exports/` кожного робочого простору на постійному томі /data. Зарезервуйте там місце для одночасних експортів, зростання журналу/WAL, мультимедіа та резервних копій. Програма запуску використовує файл deploy/constraints.txt для фіксації відповідних версій залежностей середовища виконання. Docker та сервери з високим рівнем безпеки встановлюються з файлів deploy/requirements.lock та deploy/build.lock за допомогою pip --require-hashes: кожен файл пакета повинен відповідати SHA-256, зафіксованому у коміті, тому файл, замінений на PyPI або дзеркалі, відхиляється. Базовий образ Python та пакети операційної системи все ще потребують незалежної кваліфікації випуску.

Не використовуйте команду `docker compose down -v`, якщо ви не маєте наміру знищити журнал та ключі. Звіт про стан контейнера відображає доступність веб-сервера, а не успішність збору даних Telegram. Перевіряйте стан колектора панелі, сигнал активності, помилки та події покриття.

### Профіль незалежного свідка

Опціональний сервіс `witness` запускає [незалежний «witness»](https://phishdestroy.github.io/TgWitness/uk/docs/reference/witness/) у власному контейнері, з власним ключем та журналом у томі `witness-data` і лише токеном «witness» лише для читання для колектора. Створіть токен на сторінці **«Witness»** панелі, додайте його разом із токеном бота та каналом до `.env`, а потім запустіть профіль:

```
docker compose --profile witness up -d          # deploy/compose/compose.image.yaml: same flag
docker compose logs witness                     # witness key fingerprint
```

Сервіс підключається до колектора в мережі Compose за адресою `http://tgwitness:8787` (`TGWITNESS_WITNESS_COLLECTOR` замінює її, наприклад, `/profiles/<workspace ID>` для іншого робочого простору). Для свідка на окремому сервері, яким керує хтось інший, використовуйте `deploy/compose/compose.witness.yaml` , встановивши для `TGWITNESS_WITNESS_COLLECTOR` HTTPS-адресу колектора; цей файл містить лише свідка.

## Встановити опублікований образ

Доступ до нього надається після успішного проходження [робочого процесу випуску](https://phishdestroy.github.io/TgWitness/uk/docs/reference/deployment/#automated-github-releases) та публічної конфігурації пакета GHCR. Ім’я власника репозиторію не вбудовано у це дерево вихідного коду. Використовуйте зображення, показане у підсумку робочого процесу цього випуску.

Скопіюйте `deploy/env.example` у `.env`. Встановіть `TGWITNESS_IMAGE` на опубліковану версію, використовуючи шлях до репозиторію **з малими літерами**, наприклад:

```
TGWITNESS_IMAGE=ghcr.io/your-owner/your-repository:0.7.0
TGWITNESS_PORT=8787
```

Запустіть цей файл окремо, замість `compose.yaml`:

```
docker compose --project-directory . -f deploy/compose/compose.image.yaml pull
docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait
docker compose --project-directory . -f deploy/compose/compose.image.yaml exec tgwitness cat /data/panel-token.txt
```

На хості не потрібні збірка з вихідного коду, Python чи компілятор. Процес випуску орієнтований на контейнери Linux AMD64 та ARM64, включаючи віртуальну машину Linux у Docker Desktop. Використовуйте тег версії або `ghcr.io/owner/repository@sha256:...` із підсумку робочого процесу. Не налаштовано переміщення тегу `latest` або автоматичне оновлення додатка. Образ та варіанти вихідного коду використовують один і той самий том даних, якщо назви їхніх проєктів збігаються.

## Автоматичне ввімкнення HTTPS на сервері

Використовуйте сервер із Docker, домен, який ви контролюєте, та постійне локальне сховище. Направте записи A/AAAA домену на сервер; публікуйте AAAA лише в тому випадку, якщо до нього досягає IPv6. Дозвольте вхідний трафік по TCP 80 та 443, а також вихідний трафік DNS/HTTPS для видачі сертифікатів. Ці порти не повинні бути зайняті іншими службами.

Скопіюйте `deploy/env.example` у `.env` та вкажіть ім’я хосту без схеми та шляху:

```
TGWITNESS_DOMAIN=watch.your-domain.org
```

Запустіть збірку вихідного коду з накладенням HTTPS:

```
docker compose -f compose.yaml -f deploy/compose/compose.https.yaml up -d --build --wait
docker compose -f compose.yaml -f deploy/compose/compose.https.yaml exec tgwitness cat /data/panel-token.txt
```

```
docker compose --project-directory . -f deploy/compose/compose.image.yaml -f deploy/compose/compose.https.yaml up -d --wait
```

Для опублікованого зображення замість цього використовуйте `deploy/compose/compose.image.yaml` як перший файл. Збережіть обидва аргументи `-f` для подальших команд status, logs, update та stop.

Caddy отримує та поновлює сертифікат, перенаправляє HTTP на HTTPS та пересилає запити до колектора у приватній мережі Compose. Стан сертифіката зберігається у власному постійному томі. Порт прямого хосту колектора залишається лише для локального з’єднання. Надана конфігурація Caddy не вмикає реєстрацію доступу.

Відкрийте `https://watch.your-domain.org` та введіть токен панелі. Готовність до створення не підтверджує видачу сертифіката або зовнішню доступність. Якщо HTTPS не готовий, перевірте DNS, правила брандмауера та:

```
docker compose -f compose.yaml -f deploy/compose/compose.https.yaml logs --tail 100 caddy
```

Наданий образ Caddy відповідає тегу `2-alpine`. Виконання команди pull оновлює цей образ; якщо вам потрібні фіксовані версії інфраструктури, закріпіть перевірений дайджест у вашому розгортанні.

## Оновлення та резервні копії

Зберігайте назву проєкту Compose та обсяг даних під час оновлень. Спочатку зупиніть колектор і створіть повну резервну копію. Для розгортання за замовчуванням на основі вихідного коду:

```
docker compose stop
docker compose cp tgwitness:/data ../tgwitness-backup-before-update
```

Кожного разу використовуйте нове місце для резервного копіювання, поза межами репозиторію, та захищайте його як матеріал, що вимагає доступу до облікового запису. Наведений приклад шляху є ілюстративним; використовуйте своє власне місце для резервного копіювання. Скопіюйте весь каталог, включаючи приховані файли, усі робочі простори, ключі, журнали та мультимедійні файли. Окремо створіть резервну копію головного ключа зовнішнього сховища, якщо він налаштований. ZIP-архів з доказами не є резервною копією програми, яку можна відновити. Для HTTPS також збережіть томи Caddy, якщо вам потрібно зберегти стан його сертифіката/облікового запису.

Для розгортання з вихідного коду завантажте файли нової версії та виконайте:

```
docker compose up -d --build --wait
```

Для розгортання образу змініть `TGWITNESS_IMAGE` на бажану версію, а потім виконайте:

```
docker compose --project-directory . -f deploy/compose/compose.image.yaml pull
docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait
```

Використовуйте файли Compose вашої інсталяції також для наведених вище команд stop/copy. Збережіть `.env`, власні налаштування та ту саму назву проєкту. `down` зберігає іменовані томи; **`down -v` видаляє їх**. Не копіюйте `.venv` між операційними системами або версіями Python. Для оновлення з вихідного коду зупиніть TgWitness, створіть резервну копію всього каталогу даних , замініть вихідні файли та запустіть `python start.py --setup-only` перед запуском програми.

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

## Автоматизовані релізи на GitHub

[Процес випуску](https://github.com/phishdestroy/TgWitness/blob/main/.github/workflows/release.yml) готовий до використання після того, як цей проєкт буде відправлено до репозиторію GitHub із увімкненою функцією Actions. Він запускається, коли **публікується** випуск на GitHub, включаючи попередній випуск. Самі лише чернетки та відправлення тегів не призводять до публікації пакетів.

1. Встановіть версію пакета та журнал змін, а потім опублікуйте реліз із тегом `v` та точним позначенням версії `pyproject.toml`, наприклад `v0.7.0`.
2. Робочий процес перевіряє тег і запускає спільні для Windows/Linux/macOS перевірки Python, general/account-import/QR-браузера, вихідного пакету та Docker. Також проводиться нова нативна інсталяція на всіх трьох операційних системах із використанням Python 3.12.
3. Після успішного проходження цих перевірок виконується тестування образу ARM64 у середовищі QEMU, публікуються образи AMD64/ARM64 на `ghcr.io/<lowercase-owner>/<lowercase-repository>:<version>`, а також до релізу додаються ZIP-архів із вихідним кодом, контрольна сума та пакет Python wheel. Окреме завдання для Windows збирає та додає портативний ZIP-архів та його контрольну суму.
4. Після першої публікації відкрийте налаштування пакета GHCR і встановіть видимість на **«Публічна»**, якщо передбачається анонімне завантаження зображень. Сам по собі публічний репозиторій не гарантує публічності контейнерного пакета. Політика організації повинна дозволяти публікацію пакетів. У робочому процесі використовується `GITHUB_TOKEN`; у репозиторії не повинні міститися паролі до реєстру або облікові дані VPS.

Ця локальна підготовка не гарантує успішної роботи в віддаленому режимі. Емуляція ARM64 є лише попередньою перевіркою, а не кваліфікацією на нативному апаратному забезпеченні чи в реальному середовищі Telegram. Це автоматизує пакування релізу; для запуску сервера все ще потрібна команда Compose та відповідні вимоги до домену/хосту. Існуючі сервери не оновлюються і не перезапускаються автоматично після публікації релізу.

## Віддалений сервер

Забезпечте, щоб сервіс працював у режимі loopback та використовував SSH-тунель, або завершуйте HTTPS на зворотному проксі. Базовий файл Compose доступний лише локально; опціональний оверлей `deploy/compose/compose.https.yaml` надає Caddy для налаштованого домену. Не допускайте появи токена носія в URL-адресах та журналах проксі-сервера. Зворотний проксі-сервер повинен обмежувати розмір запитів та частоту з’єднань. Не відкривайте доступ до простого HTTP в Інтернеті.

Приклади для systemd, завдання входу в систему Windows, агента користувача macOS та Caddy наведено у [папці deploy/](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md). Перегляньте та адаптуйте їхні шляхи перед встановленням. Це лише шаблони, а не локально виконувані налаштування платформи. Звичайний запускач не реєструє жодних фонових служб чи завдань.

У Windows безвіконний запуск `pythonw.exe` зберігає діагностичні дані запуску/сервера у файлі `logs/server.log` у каталозі даних (5 МіБ на файл, дві чергові резервні копії). Запуск у консолі зберігає консольні журнали. Реєстрація доступу по HTTP вимкнена в обох режимах. Захищайте журнали разом із каталогом даних та перевіряйте їх перед тим, як надавати доступ.

## Перезапуск та прогалини

Останній запитуваний стан спостереження зберігається. Якщо спостереження було активним, під час запуску програма намагається відновити з’єднання та продовжити моніторинг вибраних джерел. Ручна пауза скасовує цю дію. Невдалий перезапуск фіксується та відображається на панелі.

StringSession зберігає авторизацію, але не зберігає стійкий стан оновлень/об’єктів Telethon. Діалоги перезавантажуються під час запуску. Telegram/Telethon можуть відновлювати деякі переривання передачі даних під час роботи, але TgWitness не гарантує стійкого відтворення даних після перезапуску процесу. При кожному запуску записується попередня головка журналу та межа офлайн-режиму. Монітор перевіряє підключення кожні 10 секунд і додає сигнал активності щохвилини (**Параметри → Запис активності кожні**). Короткочасні переривання можуть бути пропущені; підключений канал передачі даних не гарантує повної доставки оновлень. Знімки — це явні спостереження поточної історії, а не відновлення пропусків.

Черга мультимедіа зберігається в базі даних SQLite кожного робочого простору. Повідомлення та відповідне завдання фіксуються атомарно. Перервані завдання відновлюються для повторної спроби під час запуску. Кожне завантаження має базовий тайм-аут у 120 секунд плюс час, необхідний для завантаження файлу розміром 256 Кбайт/с, а також обмеження від 1 до 2 000 Мбайт на тип вкладення; тайм-аут, швидкість та кількість повторних спроб налаштовуються в розділі **«Параметри**». Колектор пропускає файли, розмір яких невідомий. При паузі роботи завдання в черзі зберігаються. Повторна спроба використовує оригінальний спостережуваний дескриптор файлу, а не останню версію повідомлення, яке було згодом відредаговано. Тимчасові збої мають обмежену кількість повторних спроб; паузи FloodWait для медіа зберігаються після перезапуску. Відновлення медіа є окремим від відновлення оновлень Telegram і не може відтворити зниклі файли.

## Резервне копіювання, відновлення та ємність

Зупиніть процес перед копіюванням **усього каталогу даних**, включаючи файли vault.key, signing.enc, credentials.enc, базу даних SQLite/файли WAL, мультимедіа, токен, контрольні точки, а також усі профілі та підкаталоги. Відновіть повну копію, поки служба призначення зупинена. Відсутність ключів сховища або невідповідність ключів підпису призведе до збою запуску; не генеруйте ключі заново, щоб примусово отримати доступ.

Зберігайте секретні резервні копії у зашифрованому вигляді з контролем доступу. ZIP-архіви з доказами є портативними артефактами для перегляду, а не резервними копіями додатків чи сеансів Telegram. Автоматичного видалення після закінчення терміну зберігання не відбувається. Заплануйте місце на диску для всіх повідомлень, необроблених метаданих, мультимедіа, тимчасових експортів та резервних копій.

Перевірка запуску та експорт записів потоку замість завантаження всього журналу. Експорт фіксує знімок стану на момент зчитування, тоді як запис нових даних у WAL може продовжуватися; тривалі експорті можуть зберігати сторінки WAL, тому ємність диска все ще має значення. Розмір ZIP-архівів обмежено 4 ГіБ у нестисненому вигляді, щоб відповідати стандартним налаштуванням незалежного верифікатора; **Параметри → Найбільший підписаний ZIP-архів** підвищує обмеження, і такі архіви перевіряються за допомогою `verify.py --max-gib N`. Інші формати не мають обмеження на кількість подій. Підтримувані браузери передають фрагменти відповіді у потоковому режимі до файлу, обраного користувачем. Інші браузери буферизують не більше 128 MiB і перенаправляють більші передачі до автентифікованого CLI:

```
python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip
```

Використовуйте `--profile ID` з **меню «Експорт» → «Ідентифікатор робочого простору»** для іншого робочого простору, `--format zip|jsonl|csv|html`, `--url https://your-server` для віддаленого сервера або `--max-mib`, щоб змінити обмеження на передачу даних у 5 ГіБ. Простий HTTP дозволено лише для петлевого з’єднання. Токени передаються в заголовках, перенаправлення відхиляються, існуючі файли не перезаписуються, а незавершені завантаження не публікуються як завершені файли. Якщо TGWITNESS_TOKEN замінює згенерований токен, використовуйте окремо захищений файл, що містить це активне значення: файл panel-token.txt не перезаписується при заміщенні. SHA-256 команди є лише контрольною сумою передачі; незалежно перевірте підписаний ZIP-файл.

Файли експорту сервера зберігаються у приватному каталозі `temporary-exports/` кожного робочого простору. У разі успішного виконання запиту файли видаляються. Перервані експорті видаляються під час наступного запуску робочого простору з утриманням ексклюзивної блокування екземпляра. Цей каталог є частиною моделі загроз/ємності сховища; використовуйте зашифрований том даних. Передача даних обсягом у кілька гігабайтів у виробничих умовах все ще вимагає перевірки на вашій цільовій системі.

Панель відображає медіафайли в черзі/з помилками, найстаріші медіафайли в очікуванні, вільне місце на диску, паузи у запитах до Telegram та джерела, доступ до яких не підтверджено. Ці діагностичні дані не є повноцінним монітором доставки «від кінця до кінця». Робочі простори використовують спільний процес; обліковий запис із великим трафіком може все одно впливати на інші. Залишаються окремі робочі процеси, зберігання/ротація, відновлення стійких оновлень та повна кваліфікація розгортання. Доступ до панелі з обмеженим обсягом повноважень задокументовано у розділі [«Доступ та дозволи»](https://phishdestroy.github.io/TgWitness/uk/docs/reference/access/); незалежні контрольні точки висвітлено у [посібнику для свідків](https://phishdestroy.github.io/TgWitness/uk/docs/reference/witness/).

## Параметри підключення та захисту

Маршрути підключення визначаються для кожного робочого простору окремо і повинні бути налаштовані до авторизації. SOCKS5/HTTP CONNECT використовують закріплену залежність python-socks. MTProxy використовує експериментальний рандомізований проміжний транспорт Telethon; підроблені секретні ключі TLS не підтримуються. Прямий резервний маршрут залежить від обраного [режиму IP](https://phishdestroy.github.io/TgWitness/uk/docs/reference/connection/#ip-modes): «Hide IP» відхиляє його; режим явного резервного маршруту дозволяє його після певної затримки. Режим «Tunnel/VPN» дозволяє прямі маршрути, але не створює VPN. Це не є загальносистемною мережевою політикою.

Для нових інсталяцій змінна TGWITNESS_VAULT_KEY_FILE вказує на окремо захищений файл із випадковим головним ключем. Змонтуйте його у режимі «тільки для читання» поза каталогом /data у контейнері. Зберігайте відкриті метадані salt у файлі vault.external.json окремо для кожної робочої області та головного ключа. Існуючі локальні сховища потребують планової міграції; встановлення цієї змінної не призводить до їх автоматичного перетворення. Зберігання та експорт повідомлень/медіафайлів не шифруються на рівні додатка. За необхідності використовуйте зашифровані томи та достатній обсяг приватного тимчасового сховища.

Детальні інструкції: [підключення/безпека](https://phishdestroy.github.io/TgWitness/uk/docs/reference/connection/) та [режими роботи](https://phishdestroy.github.io/TgWitness/uk/docs/reference/operations/).