# Развёртывание TgWitness: Docker, HTTPS, бэкапы

Canonical page: https://phishdestroy.io/tgwitness/ru/docs/reference/deployment/

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

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

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

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

[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-operate.svg?v=7039a376d47f)

**Английский язык** · [Русский](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://phishdestroy.io/tgwitness/ru/docs/reference/high-assurance/)».

При запуске создаётся частный файл `.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 версии 2.20 или более поздней. Docker Desktop должен использовать контейнеры Linux в среде Windows. Контейнер устанавливает свои собственные зависимости Python; на хосте не требуется отдельная установка Python.

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

Используйте `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 выбирает режим внешнего ключа для новой установки; см. раздел [Внешний главный ключ](https://phishdestroy.io/tgwitness/ru/docs/reference/security/#external-master-key). 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` | Запустите проверку готовности, не запуская программу |

Закреплённый словарь русской морфологии и цветовые профили PDF включены в пакет для офлайн-использования. Упаковка допускает только известные пути к файлам внутри каталогов зависимости `data`; наличие неожиданных файлов в этих каталогах приводит к сбою сборки.

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

Скомпилируйте его самостоятельно на 64-разрядной версии Windows с использованием Python 3.12:

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

## Контейнер

```
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 или в зеркале, отклоняется. Пакеты, которые поставляются только с исходным кодом (jieba, pyaes), собираются с использованием версий setuptools, зафиксированных в файле deploy/build.lock (с параметром `--no-build-isolation`) программой запуска, портативным сборщиком для Windows и файлом Dockerfile, поэтому pip не создаёт отдельную, незафиксированную среду сборки. Базовый образ Python и пакеты операционной системы по-прежнему требуют независимой квалификации выпуска.

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

### Профиль независимого свидетеля

Дополнительный сервис `witness` запускает [независимый свидетельский](https://phishdestroy.io/tgwitness/ru/docs/reference/witness/) сервер в собственном контейнере, с собственным ключом и журналом в томе `witness-data` и только токеном свидетеля, доступным только для чтения, для коллектора. Создайте токен в панели управления в **разделе Дополнительные инструменты → Дополнения → Независимый свидетель**, добавьте его вместе с токеном бота и каналом в файл `.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-адрес сборщика; этот файл содержит только свидетель.

## Установите опубликованный образ

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

```
TGWITNESS_IMAGE=ghcr.io/your-owner/your-repository:0.9.3
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` и введите токен панели. Готовность к составлению зависит от контейнеров; выдача сертификатов и доступность извне зависят от DNS и брандмауэра. Если 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` перед запуском.

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

## Удалённый сервер

Обеспечьте, чтобы сервис работал в режиме loopback и использовал SSH-туннель, либо завершайте соединение HTTPS на обратном прокси-сервере. Базовый файл Compose предназначен исключительно для локального использования; дополнительный оверлей `deploy/compose/compose.https.yaml` предоставляет Caddy для настроенного домена. Не допускайте появления токена bearer в 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 отключена в обоих режимах. Защищайте журналы вместе с каталогом данных и проверяйте их перед передачей.

## Перезапуск и пробелы

Сохраняется последнее запрошенное состояние наблюдения. Если наблюдение было активным, при запуске происходит попытка повторного подключения и возобновления работы с выбранными источниками. Ручная пауза отменяет это намерение. Неудачная попытка перезапуска регистрируется и отображается на панели.

TgWitness хранит позицию обновления Telegram для аккаунта и для каждого канала (pts, qts, seq и date) в хранилище рабочей области и восстанавливает её при следующем запуске. Затем клиент запрашивает обновления, пропущенные во время остановки процесса, а периодическая повторная проверка восстанавливает пропущенные сообщения и фиксирует сохраненные, которые Telegram больше не возвращает. Диалоги перезагружаются при запуске. При каждом запуске фиксируются предыдущая начальная точка журнала, граница автономного режима и позиция обновления, с которой возобновилась работа. Монитор проверяет подключение каждые 10 секунд и добавляет сигнал о работоспособности каждую минуту (**Дополнительные инструменты → Параметры → Запись работоспособности каждые**). Обрывы связи и периоды без активности регистрируются как пробелы в охвате с указанием причины. Снимки истории хранятся в виде отдельных наблюдений текущей истории рядом с записями в реальном времени.

Очередь мультимедиа хранится в базе данных SQLite каждой рабочей области. Сообщение и его задание фиксируются атомарно. Прерванные выполняющиеся задания восстанавливаются для повторной попытки при запуске. Каждая загрузка имеет базовый таймаут в 120 секунд плюс время, рассчитанное исходя из скорости 256 КиБ/с в зависимости от её размера, а также 1–2,000 MiB на тип вложения; таймаут, скорость и количество попыток настраиваются в разделе **Дополнительные инструменты → Параметры**. Коллектор пропускает файлы с неизвестным размером. При приостановке работы задачи в очереди сохраняются. При повторной попытке используется исходный наблюдаемый дескриптор файла, а не последняя версия сообщения, отредактированного впоследствии. Временные сбои имеют ограниченное количество попыток; паузы FloodWait для мультимедиа сохраняются после перезапуска. Восстановление мультимедиа осуществляется отдельно от восстановления обновлений Telegram и не может воссоздать исчезнувшие файлы.

## Резервное копирование, восстановление и емкость

Команда `tgwitness backup FOLDER` копирует каталог данных, пока панель продолжает работать: сначала контрольные точки, затем файлы SQLite через API онлайн-резервного копирования, далее ключи, медиафайлы и профили, так что ни одна скопированная контрольная точка не может быть более поздней, чем скопированный журнал. В файле `backup-manifest.json` перечислены SHA-256-хэши всех файлов и заголовки журналов. Для восстановления остановите TgWitness и замените весь каталог данных этой папкой. При следующем запуске будет зафиксировано, что журнал был восстановлен из более старой копии. Эта запись сравнивает журнал с началом, хранящимся в `TGWITNESS_STATE_DIR` — папке, расположенной вне каталога данных: том `tgwitness-state` в Compose, `/var/lib/tgwitness-state` в модулях systemd, а в остальных случаях — в локальной папке состояния пользователя . Если папка состояния не доступна для записи, восстановление не обнаруживается, и об этом один раз сообщается в журнале.

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

Храните секретные резервные копии в зашифрованном виде с контролем доступа. ZIP-архивы с доказательствами представляют собой переносимые артефакты для анализа, а не резервные копии приложения или сеансов Telegram. Автоматического удаления данных по истечении срока хранения не предусмотрено. Запланируйте дисковое пространство для всех сообщений, исходных метаданных, мультимедиа, временных экспортов и резервных копий.

Проверка при запуске и экспорт записей потока вместо загрузки всего журнала. Экспорт фиксирует моментальный снимок прочитанных данных, в то время как новые записи в WAL могут продолжаться; длительные экспорты могут сохранять страницы WAL, поэтому объём дискового пространства по-прежнему имеет значение. Размер ZIP-архивов ограничен 4 ГиБ в несжатом виде, что соответствует значению по умолчанию для независимого верификатора; **Дополнительные инструменты → Параметры → Наибольший подписанный ZIP** повышает этот предел, и такие архивы проверяются с помощью `verify.py --max-gib N`. У других форматов нет ограничения на количество событий. Поддерживаемые браузеры передают фрагменты ответа в файл, выбранный пользователем. Другие браузеры буферизуют не более 128 МиБ и направляют более крупные передачи в аутентифицированный 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-архив.

На панели отображаются медиафайлы в очереди или с ошибками, самые старые медиафайлы в ожидании, свободное место на диске, паузы в запросах Telegram, а также источники, доступ к которым не подтверждён. Данные диагностические показатели не являются полноценным средством сквозного мониторинга доставки. Рабочие пространства используют общий процесс; активность одного аккаунта может всё же повлиять на работу других. Сохраняются отдельные рабочие процессы, хранение/ротация данных, надежное восстановление обновлений и полная квалификация развертывания. Доступ к панели с ограниченным охватом задокументирован в разделе [«Доступ и разрешения»](https://phishdestroy.io/tgwitness/ru/docs/reference/access/); независимые контрольные точки описаны в [руководстве для свидетелей](https://phishdestroy.io/tgwitness/ru/docs/reference/witness/).

Подробные инструкции: [подключение/безопасность](https://phishdestroy.io/tgwitness/ru/docs/reference/connection/) и [режимы работы](https://phishdestroy.io/tgwitness/ru/docs/reference/operations/).
