# Независимый свидетель и непрерывность журнала

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

Запустите Witness с собственным ключом и ботом, публикуйте подписанные контрольные точки в канале и сверяйте экспортированные данные с ними.

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

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

Запустите Witness с собственным ключом и ботом, публикуйте подписанные контрольные точки в канале и сверяйте экспортированные данные с ними.

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Документация](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Доказательства и верификация](https://phishdestroy.io/tgwitness/ru/docs/reference/evidence/)

![Доказательства и верификация](https://phishdestroy.io/tgwitness/assets/chapter-evidence.svg?v=e49c65feab6c)

[Экспорт и проверка](https://phishdestroy.io/tgwitness/ru/docs/reference/evidence/) · [Высокая степень надежности](https://phishdestroy.io/tgwitness/ru/docs/reference/high-assurance/) · [Руководство по панелям](https://phishdestroy.io/tgwitness/ru/docs/reference/panel/#extras)

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

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

Блок-схема · Коллектор → Свидетель (подписанный контрольный пункт: количество записей + хеш заголовка); Свидетель → Журнал Witness, собственный ключ; Свидетель → Канал в Telegram (подписанное сообщение, отправленное через собственного бота); Архив доказательств в формате ZIP → verify.py; Журнал Witness, собственный ключ → verify.py; Канал в Telegram → verify.py (t.me/s — просмотр страницы в режиме реального времени или экспорт на рабочий стол) · Коллектор · Свидетель · Журнал Witness,собственный ключ · Канал в Telegram · Архив доказательств вформате ZIP · verify.py · подписанный контрольный · пункт: количество записей + · хеш заголовка · подписанное сообщение, · отправленное через · собственного бота · t.me/s — просмотр страницы в · режиме реального времени или · экспорт на рабочий стол

**Схема в текстовом формате**

1. Коллектор → Свидетель (подписанный контрольный пункт: количество записей + хеш заголовка)
2. Свидетель → Журнал Witness, собственный ключ
3. Свидетель → Канал в Telegram (подписанное сообщение, отправленное через собственного бота)
4. Архив доказательств в формате ZIP → verify.py
5. Журнал Witness, собственный ключ → verify.py
6. Канал в Telegram → verify.py (t.me/s — просмотр страницы в режиме реального времени или экспорт на рабочий стол)

**На этой странице**

- [Что хранит свидетель](https://phishdestroy.io/tgwitness/ru/docs/reference/witness/#what-the-witness-holds)
- [Что проверяется и регистрируется](https://phishdestroy.io/tgwitness/ru/docs/reference/witness/#what-it-checks-and-records)
- [Запустить свидетеля](https://phishdestroy.io/tgwitness/ru/docs/reference/witness/#run-a-witness)
- [Публичная страница с доказательствами для нескольких рабочих пространств](https://phishdestroy.io/tgwitness/ru/docs/reference/witness/#public-proof-page-for-several-workspaces)
- [Проверить](https://phishdestroy.io/tgwitness/ru/docs/reference/witness/#verify)

## Что хранит свидетель

| У TgWitness есть | Свидетель никогда не имеет |
| --- | --- |
| **Токен-свидетель** только для чтения для одного рабочего пространства | Сессия Telegram сборщика данных или учетные данные для доступа к API |
| Собственный ключ Ed25519 и журнал | Хранилище сборщика, ключ подписи или токен панели |
| Собственный токен бота в Telegram | Содержание сообщения: в заголовке указано количество записей и хеш |

Токен создаётся в разделе **Дополнительные инструменты → Экстра → Независимый свидетель**, отображается один раз и хранится только в виде SHA-256. Он открывает ровно одну конечную точку, `GET /api/witness/head`, которая возвращает свежеподписанную контрольную точку, а также подписанные счетчики сбора данных без содержимого и информацию о работоспособности системы. Он не может открывать панель, читать содержимое сообщений или изменять настройки, и токен панели там не принимается. Отменить токен можно на той же странице. Коллектор фиксирует момент начала проверки новым ключом свидетеля (`witness.seen`) и отображает последнюю проверку для каждого токена; свидетель, который не проводил проверку в течение 2.5 интервалов, помечается как просроченный.

Новые свидетели отправляют случайный контрольный запрос при каждом опросе; оператор фиксации повторяет его под подписью сборщика. Счётчики привязаны к конкретной контрольной точке и включаются в подписанные сообщения свидетелей. Старые заголовки по-прежнему принимаются автономным свидетелем. Сам по себе рост объёма журнала никогда не учитывается как новое сообщение.

## Что проверяется и фиксируется

Каждый интервал (по умолчанию — 10 минут) TgWitness:

1. самостоятельно извлекает заголовок (коллектор не может его добавлять или пропускать);
2. проверяет подпись сборщика, закреплённый ключ сборщика (`--collector-fingerprint`, или первый обнаруженный ключ), неубывающий счётчик и неизменную головку при неизменном счётчике. Доказательства включения и согласованности по Меркле подтверждают, что растущий журнал расширяет сохраненную контрольную точку. После использования доказательств непрерывности их удаление отклоняется;
3. добавляет подписанную запись в свой собственный журнал: `witness.anchor` со статусом `ok`, `key_changed`, `rollback` (меньше записей, чем ранее), `fork` (та же длина, другой заголовок) или `invalid` (ответ не прошел проверку), либо `witness.no_response`, если коллектор не ответил;
4. Результат публикуется в канале с подписью, включая ответ «no answer», пока TgWitness работает и имеет доступ к Bot API. Идентификатор публикации фиксируется (`witness.posted`), также фиксируется неудачная публикация (`witness.post_failed`).

Запись выглядит следующим образом; в последней строке приводится подписанное заявление:

```
TgWitness witness #42 · journal head
Collector 3fa9c2d1e0b4a7f6: 18234 records
Head 9b1f…c07e
2026-10-28T19:40:00.123+00:00
TGW1.eyJhdCI6…<statement>.<signature>
```

## Запустить Witness

Вам потребуется бот Telegram (создайте его с помощью @BotFather), канал, в котором этот бот является администратором, а также адрес сборщика, доступный для свидетеля — через HTTPS за пределами частной сети (см. раздел «HTTPS» в разделе [«Развертывание»](https://phishdestroy.io/tgwitness/ru/docs/reference/deployment/)).

Откройте **Дополнительные инструменты → Дополнительные функции → Независимый свидетель → Настроить** на панели. Три шага охватывают доступ только для чтения, ваш канал и интервал, а затем запуск свидетеля. Политика публикации, опциональный прокси HTTP/SOCKS5 и пользовательский адрес Bot API находятся в разделе **Расширенные настройки** . Форма загружает файл `witness.json` с закреплённым ключом коллектора данной рабочей области. Загрузите вновь созданный токен только для чтения, **сохранив файл доступа** как `witness-token.txt` ; поместите его и файл `bot-token.txt` , созданный на хосте свидетеля, рядом с этим JSON-файлом. Коллектор никогда не получает токен бота. Загрузка не запускает службу и не публикует сообщение. Ни один свидетель размещённого проекта не регистрируется неявно.

```
python -m tgwitness.witness run --config witness.json --check-config
python -m tgwitness.witness run --config witness.json
python -m tgwitness.witness fingerprint --config witness.json
```

Первая команда проверяет файлы конфигурации и секретные файлы без сетевых запросов и создания ключей. Пути в JSON являются относительными по отношению к данному файлу; пути CLI/окружения являются относительными по отношению к рабочему каталогу. Сохраняйте отпечаток свидетеля за пределами его хоста. Индикатор последнего опроса коллектора подтверждает лишь наличие запроса; о публикации сообщается через Proof или проверяется в журнале свидетеля и на канале.

Если панель находится за SSH-туннелем, открывайте доступ только к конечной точке Witness с ограниченным доступом на отдельном HTTPS-хосте, как показано в [этом примере использования Caddy](https://github.com/phishdestroy/TgWitness/blob/main/deploy/Caddyfile.witness.example). Рабочая область по умолчанию использует `https://witness.example.org`, остальные рабочие области — `https://witness.example.org/profiles/ID`. Токены по-прежнему требуются; панель и её другие маршруты API не перенаправляются этим виртуальным хостом.

Выберите `all` для регулярно публикуемых контрольных точек. Пятиминутный интервал означает около 288 записей на рабочую область в день. `changes`/`problems` намеренно оставляют некоторые проверки неопубликованными. MTProxy предназначен для клиента Telegram сборщика данных. HTTP-опрос Witness и HTTPS-интерфейс Bot API Telegram используют собственные маршруты: прямой, HTTP и SOCKS5 ([Bot API](https://core.telegram.org/bots/api)).

**Рядом с коллектором, с использованием Docker** (на том же хосте — независимый процесс и ключ, но тот же оператор): введите значения в поле «`.env`» и запустите профиль.

```
TGWITNESS_WITNESS_TOKEN=tgww_...
TGWITNESS_WITNESS_BOT_TOKEN=123456:ABC...
TGWITNESS_WITNESS_CHANNEL=@your_witness_channel
# another workspace: TGWITNESS_WITNESS_COLLECTOR=http://tgwitness:8787/profiles/<workspace ID>

docker compose --profile witness up -d
docker compose logs witness     # prints the witness key fingerprint
```

При использовании опубликованного изображения указывайте код `docker compose --project-directory . -f deploy/compose/compose.image.yaml --profile witness up -d`.

**На чужом сервере** (отдельное хранение): скопируйте туда репозиторий, установите `TGWITNESS_WITNESS_COLLECTOR=https://your-collector.example.org` плюс три вышеуказанных значения в файле `.env`, затем

```
docker compose --project-directory . -f deploy/compose/compose.witness.yaml up -d
```

или без использования Docker:

```
python -m tgwitness.witness run --collector https://your-collector.example.org \
    --token-file witness-token.txt --bot-token-file bot-token.txt --channel @your_witness_channel
```

### Опубликовать в Discord

Свидетель может публиковать сообщения в канале Discord вместо Telegram. В Discord откройте **«Редактировать канал» → «Интеграции» → «Веб-хуки»**, создайте веб-хук и скопируйте его URL. В панели на шаге 2 выберите **«Веб-хук Discord» · ваш канал**. На хосте свидетеля сохраните URL как `discord-webhook.txt` рядом с `witness.json`; он никогда не попадает в коллектор.

```
python -m tgwitness.witness run --collector https://your-collector.example.org \
    --token-file witness-token.txt --discord-webhook-file discord-webhook.txt
```

У свидетеля есть один издатель: канал Telegram или веб-хук Discord, но не оба одновременно. Сообщения содержат одно и то же подписанное заявление и не могут отправлять пинги никому. Сообщение, превышающее ограничение Discord в 2,000 символов, заменяется короткой строкой с полной проверкой, прикреплённой как `witness-check.txt` . Каждый идентификатор сообщения записывается как `witness.posted` . `verify.py --channel` считывает только каналы Telegram, поэтому для Discord ведите журнал свидетеля: в нём хранятся все проверки. Сообщения Discord не дают верификатору внешнего времени.

### Параметры

| Вариант | Среда | По умолчанию | Значение |
| --- | --- | --- | --- |
| `--interval` | `TGWITNESS_WITNESS_INTERVAL` | 10 | Интервал между проверками: от 1 до 1440 минут |
| `--timeout` | `_TIMEOUT` | 30 | Время ожидания запуска сборщика данных и API-интерфейса бота: от нескольких секунд до 5–600 |
| `--post` | `_POST` | `all` | `all`: все в порядке; `changes`: новая проблема; `problems`: одни проблемы и отсутствующие ответы |
| `--title` | `_TITLE` | `TgWitness witness` | Первые слова каждого сообщения в канале |
| `--collector-fingerprint` | `_COLLECTOR_FINGERPRINT` | – | Зафиксируйте ключ сборщика, а не полагайтесь на первый ответ |
| `--proxy` | `_PROXY` | прямой | `socks5://host:port` или `http://host:port` |
| `--bot-api` | `_BOT_API` | `https://api.telegram.org` | Адрес API бота, например, локальный сервер API бота |
| `--data-dir` | `_DATA` | `witness-data` | Ключ Witness и журнал |
| `--config` | `_CONFIG` | – | Файл JSON с любым из перечисленных выше вариантов |

Адрес коллектора, токены и канал берутся из `--collector`, `--token` или `--token-file`, `--bot-token` или `--bot-token-file`, `--discord-webhook-file` и `--channel`, или `_COLLECTOR`, `_TOKEN`, `_TOKEN_FILE`, `_BOT_TOKEN`, `_BOT_TOKEN_FILE`, `_DISCORD_WEBHOOK_FILE` и `_CHANNEL`, что позволяет скрыть секретные процессы из списка процессов.

В файле конфигурации используются названия параметров с подчеркиваниями, а также `texts`, который заменяет слова в сообщениях канала:

```
{"collector": "https://your-collector.example.org", "token_file": "witness-token.txt",
 "bot_token_file": "bot-token.txt", "channel": "@your_witness_channel",
 "interval": 5, "timeout": 30, "post": "changes", "title": "Partner witness",
 "texts": {"ok": "journal head", "no_response": "no answer from the collector", "records": "records"}}
```

Ключи `texts`: `ok`, `key_changed`, `rollback`, `fork`, `invalid`, `no_response`, `collector`, `records`, `head`. Командная строка имеет приоритет над переменными среды, а переменные среды — над файлом. Неизвестные опции или текстовые ключи приводят к остановке работы свидетеля с выводом сообщения, а не игнорируются. Формулировка никогда не влияет на проверку: verify.py проверяет подписанный токен в конце каждого поста. При использовании `--post changes` или `problems` проверки, которые не были опубликованы, по-прежнему находятся в журнале свидетелей, и `verify.py` перечисляет их как никогда не опубликованные; начальная запись указывает политику. Каждая проверка по-прежнему появляется в журнале, поэтому меньшее количество постов означает меньшее количество дат, указанных Telegram, а не меньшее количество проверок.

Даже без канала «Witness» продолжает вести свой журнал. Храните отпечаток ключа «Witness» (`python -m tgwitness.witness fingerprint`) в другом месте.

## Публичная страница с доказательствами для нескольких рабочих пространств

`python -m tgwitness.proof` TgWitness одновременно поддерживает до 32 рабочих пространств и предоставляет страницу только для чтения с последней подписанной проверкой каждого из них. Каждое рабочее пространство получает собственный ключ свидетеля и журнал в папке data, а также закреплённый ключ сборщика; публикация в канале Telegram является опциональной для каждого рабочего пространства. Начните с файла [proof.config.example](https://github.com/phishdestroy/TgWitness/blob/main/deploy/proof.config.example):

| Область применения | Значение |
| --- | --- |
| `title` | Заголовок страницы, 1–100 символов |
| `data_dir` | Ключи и журналы Witness, относящиеся к файлу; по умолчанию `proof-data` |
| `interval`, `timeout` | Интервал между проверками в минутах (1–1440, по умолчанию 5); время ожидания в секундах (5–600, по умолчанию 20) |
| `workspaces[].id`, `label` | Краткий псевдоним в нижнем регистре и отображаемое имя |
| `workspaces[].collector` | Адрес коллектора; адреса других рабочих пространств заканчиваются на `/profiles/<workspace ID>` |
| `workspaces[].collector_fingerprint` | Обязательно, отличается для каждой рабочей области |
| `workspaces[].token_file` | Файл с токеном-свидетелем данного рабочего пространства, доступным только для чтения |
| `workspaces[].channel`, `bot_token_file` | Дополнительно, в совокупности: публиковать каждую проверку в канале |
| `workspaces[].proxy`, `bot_api` | Дополнительный маршрут и адрес API бота |

```
python -m tgwitness.proof --config proof.json --check-config
python -m tgwitness.proof --config proof.json --host 127.0.0.1 --port 8790
```

Первая команда проверяет файл и файлы токенов, не устанавливая соединение. Страница отвечает только на запросы GET и HEAD:

- `/` Отображает все рабочие пространства; рабочее пространство, в котором в течение 2,5 интервалов не было отмечено ни одного элемента, помечается как устаревшее.
- `/api/proof` Возвращает то же самое, что и JSON.
- `/api/proof/<id>` загружает последнюю подписанную отчётную запись (`tgwitness-public-proof-v1`): номер и хэш записи свидетеля, статус, закрепленный ключ сборщика, контрольная точка, счетчики сбора и информация об успешности публикации в канале, подписанная ключом свидетеля данной рабочей области.
- `/healthz` Выдает ошибку 503, если монитор рабочего пространства перестал работать.

Присвойте странице собственное имя хоста, например [Caddyfile.proof.example](https://github.com/phishdestroy/TgWitness/blob/main/deploy/Caddyfile.proof.example). Для проверки экспортируйте журнал свидетельств рабочей области с помощью `python -m tgwitness.witness export --data-dir proof-data/<id> --out witness.zip` и используйте его , как описано ниже.

## Проверить

Со стороны свидетеля экспортируйте его журнал:

```
python -m tgwitness.witness export --out witness.zip
# Docker (add -f deploy/compose/compose.witness.yaml on a witness server):
docker compose exec witness python -m tgwitness.witness export --out /witness/witness.zip
docker compose cp witness:/witness/witness.zip .
```

Затем, в любом месте, с помощью подписанного ZIP-архива сборщика и адреса общедоступного канала:

```
python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \
    --witness witness.zip --witness-fingerprint WITNESS_SHA256 --channel https://t.me/s/your_witness_channel
```

`--channel` также принимает экспорт из Telegram Desktop (*Экспорт истории чата* → JSON даёт `result.json`) или сохраненную копию страницы; они проверяют содержание сообщения, но не предоставляют внешнее время.

`verify.py` проверяет журнал свидетеля (цепочку и подписи), а затем — что **каждая головка, которую увидел свидетель, входит в экспортированный журнал**: запись с этим номером должна иметь именно этот хеш. Головка, которая не совпадает, не проходит проверку — журнал был изменен после того, как свидетель его увидел. Также сообщаются головки, увиденные после экспорта, аномалии, зафиксированные свидетелем, ответы, которые не прошли проверку, периоды, соответствующие контрольные точки которых присутствуют в данном экспорте («Свидетельствовано от X до Y»), и пробелы. Более поздние контрольные точки не продлевают эти периоды. Результат включает номер последней совпавшей записи и количество последующих записей без соответствующей контрольной точки. Учитываются только ответы, подписанные собственным ключом экспорта: экспорт, подписанный ключом, который свидетель никогда не видел, указывается как не засвидетельствованный, и без параметра `--fingerprint` его подписант остаётся незакреплённым. С параметром `--channel` каждая подписанная запись должна совпадать с журналом свидетеля запись за записью: изменённые записи не проходят проверку, отсутствующие записи перечисляются. Совпадение токена подтверждает подлинность содержимого; дата не входит в состав подписанного токена.

Имея активный адрес `https://t.me/s/…` или `https://telegram.me/s/…`, верификатор считывает дату каждого поста со страницы на момент проверки. Telegram устанавливает эту дату; даты отредактированных постов не используются. Самая ранняя такая дата поста в начале экспорта является внешним временем для последней записи, которая удовлетворяет условию минимума для доказательства. Даты из любого другого источника, такого как предоставленный файл `result.json`, сохраненная страница или другой веб- адрес, являются предоставленными метаданными, а не независимым временем; результат указывает, откуда взяты даты постов (`post_date_verification`).

### Требуется граница экспорта с подтверждением

Для передачи, которая должна включать заверенную окончательную запись, добавьте `--require-witness`:

```
python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \
    --witness witness.zip --witness-fingerprint WITNESS_SHA256 --require-witness
```

Для этого требуется независимо сохраненный отпечаток свидетеля, ключ, отличный от ключа сборщика, и соответствующая контрольная точка, расположенная точно в конце данного экспорта. Контрольная точка, охватывающая только более ранний префикс, является недостаточной. Приостановите сбор, позвольте свидетелю наблюдать за конечным состоянием и выполните экспорт до дальнейших записей в журнал; если журнал изменится, сохраните другую контрольную точку и экспортируйте это состояние. Одной только более поздней контрольной точки недостаточно для проверки конечного хеша более короткого экспорта. Если также указан флаг `--channel`, отсутствие заявленных записей или пустой набор совпадений приводят к сбою этой строгой проверки. Без этого флага обычные проверки целостности по-прежнему сообщают о записях, не подтверждённых свидетелем, не отклоняя при этом архив, который в остальном является целостным.

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

### Ежедневные печати и недоступные календари временных меток

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

Если все календари дают сбой, подписанная печать и неудачная попытка остаются в журнале. Ежечасный цикл обслуживания повторно обрабатывает эту исходную запись, в том числе после перезапуска или смены даты. Он сканирует не более 32 печатей, отправляет не более двух пропущенных отправлений и тратит не более 60 секунд на повторные попытки за один проход. Постоянный курсор циклически проходит по старым печатям. Сохраненные отправления следуют по существующему пути обновления доказательств.

Повторная попытка не перезаписывает печать, не изменяет её исходную дату и не утверждает, что календарь получил её раньше. Более позднее обязательство Bitcoin остаётся более поздним внешним подтверждением. Отсутствующие доказательства остаются `none`; ожидающие доказательства остаются `pending` до тех пор, пока верификатор не проверит их независимо.
