Справочник / Установка
Токены, области доступа и разрешения TgWitness
Устанавливайте ограниченный доступ к аккаунтам и чатам, выбирайте права доступа, ограничивайте количество сеансов и IP-адресов, а также отзывайте доступ.
TgWitness / Документация · Начало работы
Предоставьте рецензенту доступ к одному чату, аналитику — право на экспорт дела, а оператору — контроль над выбранными аккаунтами. Каждый пользователь получает собственный токен. Главный токен панели управления остается у администратора.
Настройка учетной записи · Маршруты подключения · Модель безопасности
Две области применения, две разные задачи#
Объём сбора данных определяет, что именно записывается в учётной записи: выбранные чаты, папка Telegram или вся учётная запись. Объём доступа определяет, какие из этих записанных учётных записей и чатов может просматривать и использовать другое лицо. Предоставление доступа не означает вступление в чат Telegram, начало сбора данных или предоставление прав доступа к учётной записи Telegram.
Право доступа может открывать доступ к выбранным рабочим пространствам, выбранным чатам в них, ко всем рабочим пространствам или ко всем аккаунтам в группе аккаунтов. Доступ ко всем рабочим пространствам, включая добавленные позже, также распространяется на будущие аккаунты. Групповой доступ также распространяется на аккаунты, добавленные в эту группу позже. Выбирайте рабочие пространства явно, если работа над делом должна ограничиваться только ими.
Предоставить кому-либо доступ#
- Войдите в систему как главный администратор и откройте Дополнительные инструменты → Доступ.
- В разделе «Предоставить кому-либо доступ» введите имя, которое вы сможете распознать в журнале.
- Выберите рабочие пространства и, при необходимости, отдельные чаты.
- Выберите, что может сделать данный человек. Глагол «просматривать» всегда указывается.
- Установите срок действия, ограничения на вход в систему/сессию и разрешённые адреса в соответствии с вашими потребностями.
- Нажмите «Создать доступ». Скопируйте токен сейчас: он отображается только один раз.
- Отправьте адрес панели и токен в личных сообщениях. Получатель вводит этот токен на обычной странице входа; ему не потребуется ваш основной токен панели или сессия Telegram.
Откройте панель с выданным токеном в отдельном сеансе браузера и проверьте доступные чаты и разрешённые действия, прежде чем передать её.
Имена доступа остаются в зашифрованном локальном хранилище и разрешаются через панель администратора. Имена опускаются в новых записях аудита доступа и создания рабочих пространств; существующие подписанные записи сохраняют свои исходные поля.
Выберите права доступа#
Для публичной демонстрации, содержащей только текст, используйте «Публичную витрину» вместо обычного доступа рецензента. В ней отображаются явно выбранные публичные каналы, сохраненные правки и удаления, а также подписанная статистика, при этом поля авторов замазаны, а файлы закрыты на границе API. Создайте и проверьте витрину.
| Разрешение | Возможности инструмента |
|---|---|
view |
Просмотр разрешённых чатов, сохраненных сообщений, профилей, файлов и отфильтрованных записей журнала. Все это всегда доступно. |
export |
Разрешен экспорт истории чатов и досье. Для экспорта доказательств из всего рабочего пространства требуется доступ ко всему рабочему пространству. |
sources |
Управление источниками, моментальными снимками и захватом профилей. Доступ, ограниченный чатами, действует только в разрешённых чатах; поиск источников по всей учётной записи и настройки области действия остаются закрытыми. |
collect |
Запустить или остановить сборщик данных. Требуется доступ ко всему рабочему пространству, поскольку сбор данных затрагивает учетную запись. |
interact |
Выполняйте поддерживаемые взаимодействия с Telegram в пределах предоставленных прав доступа. При доступе, ограниченном чатами, невозможно использовать предварительный просмотр ссылок для всего аккаунта. |
settings |
Изменение настроек сбора данных, временных меток, уведомлений, внешних копий и параметров. Требуется доступ ко всему рабочему пространству. |
account |
Входите в Telegram или выходите из него, а также управляйте маршрутами подключения. Требуется доступ ко всему рабочему пространству. |
board.read |
Читать заметки на доске дел только в пределах разрешённого рабочего пространства и чатов. |
board.write |
Добавляйте закладки, выделения, фрагменты, комментарии и статусы «открыто»/«просмотрено». Также требуется функция `board.read`. |
board.manage |
Управляйте коллекциями, окончательными статусами команды и карточками других участников. Также требуется доступ к доске для чтения и записи. |
Только главный администратор может загрузить ключ восстановления внешней реплики.
Делегированный доступ к settings или account не предоставляет этот ключ.
Права доступа и их сфера действия проверяются одновременно. Установка флажка напротив права доступа не приводит к открытию других чатов и не разблокирует операции в масштабе рабочего пространства в случае доступа, ограниченного конкретным чатом. Для параллельного экспорта доступ должен охватывать экспортируемый чат во всех выбранных учётных записях. Выданный доступ не позволяет создавать новые права доступа, управлять сессиями других пользователей или открывать консоль администратора.
Три полезных настройки#
| Лицо | Объём работ | Разрешения |
|---|---|---|
| Рецензент | Записанные чаты по одному из дел | view |
| Аналитик, готовящий передачу дел | Чаты для расследования и экспорта | view, export; добавьте interact только в том случае, если им необходимо действовать через Telegram |
| Оператор сбора данных | Выбранные полные рабочие пространства | view, sources, collect; добавляйте settings или account только при необходимости |
Начальные настройки формы «Доступ» также включают «Доску дел»: рецензент может читать, аналитик может читать и писать, а оператор может управлять ею. Настройки остаются редактируемыми, а существующие права доступа не расширяются автоматически. См. раздел «Доска дел» для получения информации о наследуемых областях охвата чатов и конфиденциальности экспорта.
Ограничения и сеансы#
| Настройки | Как это работает |
|---|---|
| Параллельные сессии | Ограничьте количество одновременных сеансов от 1 до 100. При достижении предела отклоните следующий вход в систему или завершите самый старый сеанс. |
| Вход в систему разрешён | Ограничьте количество успешных использований токена для запуска сеансов. Существующие сеансы не завершаются только по той причине, что был использован последний разрешённый вход в систему. |
| Срок действия до | Срок действия доступа окончательно истек. Пользователь с истекшим доступом не может войти в систему или продолжать отправлять запросы. |
| Протоколы без активности | Таймаут бездействия сеанса — от 5 минут до 30 дней. Успешные запросы продлевают его; открытая панель может поддерживать активность посредством опроса. |
| Допустимые адреса | Укажите конкретные IP-адреса или подсети CIDR. Оставьте поле пустым, чтобы разрешить доступ с любого адреса, если не включена привязка к первому входу в систему. |
| Привязать к первому входу в систему | При первом успешном входе в систему фиксируется разрешённый адрес для данного доступа. |
IP-адрес — это адрес клиента, видимый приложению. При использовании обратного прокси-сервера или туннеля проверьте адрес, указанный в разделе «Открытые сессии», прежде чем полагаться на правила, основанные на IP-адресах: в противном случае может показаться, что несколько пользователей используют один и тот же адрес прокси-сервера.
Изменить или отменить доступ#
Отредактируйте запись в разделе «Предоставленный доступ», чтобы изменить её область действия, разрешения или ограничения. Изменения области действия и разрешений проверяются при последующих запросах, включая запросы из уже открытых сеансов. Отзыв доступа приводит к завершению всех сеансов и делает выданный токен непригодным для использования. Функция «Открытые сеансы» также позволяет администратору завершить отдельный сеанс без отзыва всего доступа.
Сохраненные экспортные копии сохраняют информацию о создателе, рабочей области, области действия чата и необходимых разрешениях.
Пользователь с предоставленным доступом может просматривать или скачивать свои собственные копии только до тех пор, пока эти разрешения остаются в силе;
для копий, содержащих Case Board, также требуется разрешение board.read. Администратор может получить доступ ко всем копиям.
Старые копии без этих метаданных и групповые пакеты доступны только администратору. Билеты на загрузку
и подготовленные файловые ответы повторно проверяют доступ после подготовки файла, перед отправкой его байтов.
Каждый пользователь, включая администратора, может иметь десять ожидающих билетов на загрузку на каждое рабочее пространство;
общий лимит для всего рабочего пространства составляет 1,000. Срок действия билетов истекает через 120 секунд, и они предназначены для однократного использования.
Отзыв не позволяет восстановить файлы, которые кто-либо уже скачал. Выход из системы, блокировка панели или завершение сеанса не останавливают работу запущенного сборщика данных.
Что видит администратор#
Рецензенты и аналитики получают отчеты о ходе сбора данных без указания прокси-конечных точек,
диагностики пулов, путей к серверам или исходных ошибок подключения. Для диагностики подключения
требуется разрешение account для всего рабочего пространства. Для чтения уведомлений,
внешних копий и настроек параметров требуется разрешение settings.
Полные строки User-Agent из браузера не сохраняются в сессиях доступа. При обновлении они также удаляются из изменяемого кэша сеансов. Журнал процессов панели маскирует литералы IP-адресов, учетные данные URL и помеченные секреты. Локальные журналы служб и ранее подписанные записи журнала не перезаписываются. Правила доступа и подписанные записи входа по-прежнему используют адрес клиента.
Заменить главный ключ#
Воспользуйтесь меню Дополнительные инструменты → Доступ → Мои ограничения → Перевыпустить ключ администратора или запустите команду
tgwitness token rotate из управляемой установки во время работы панели.
Все существующие сеансы браузера завершаются, включая сеансы, открытые с помощью токенов коллег.
Запрашивающий браузер получает новый сеанс; сохраните новый ключ администратора,
прежде чем скрыть его. Выданные токены коллег остаются действительными до тех пор, пока их не отзовут отдельно.
Установка, использующая TGWITNESS_TOKEN, должна изменить этот параметр среды и перезапуститься.
Границы запросов и прокси#
API допускает до 600
запросов в минуту на одного клиента и группу учетных данных:
panel, archive/MCP или witness. Периоды ожидания после аутентификации устанавливаются отдельно для каждой из этих групп.
Десять отклоненных попыток аутентификации в течение минуты запускают экспоненциальный период ожидания, продолжительность которого составляет от одной секунды
до пяти минут. Неудачная попытка после окончания периода ожидания увеличивает его продолжительность; десять минут
без неудачных попыток сбрасывают эскалацию. При отклонении возвращаются HTTP 429
и
Retry-After
. Ограничения хранятся в памяти и совместно используются рабочими пространствами в одном процессе панели;
перезапуск сбрасывает их. Количество потоков в реальном времени ограничено четырьмя на один токен-носитель и 32
для процесса панели. Открытие потока также расходует лимит запросов API.
Тела запросов имеют 60-секундный срок получения, сокращённый до 10 секунд для входа в систему, демо-доступа,
архивного API и путей witness-head, или до 8 секунд для транспорта MCP. Каждое приложение допускает
четыре незавершённых тела на один клиентский адрес, с общими ограничениями в 32 и 64 MiB зарезервированных
маршрутных квот. Запросы без тел не расходуют эти слоты. Тела, превышающие размер, возвращают
413, тела с истекшим временем ожидания возвращают 408, а превышение клиентской ёмкости возвращает 429 с Retry-After: 1.
При исчерпании общей ёмкости тел возвращается код 503 с Retry-After.
Перенаправленные IP-заголовки игнорируются, если фактический TCP-узел не принадлежит к
TGWITNESS_TRUSTED_PROXIES (IP-адреса, разделенные запятыми, или CIDR-блоки). Установите
TGWITNESS_PROXY_HEADER в x-forwarded-for или cf-connecting-ip. XFF просматривается
от ближайшего прокси к первому ненадежному узлу. Неправильно сформированные или дублирующиеся
метаданные доверенных адресов отклоняются, поэтому они не могут унаследовать прокси-адрес из списка разрешенных
адресов. Управляемый быстрый туннель
доверяет локальному коннектору Cloudflare; настройка в собственном домене доверяет локальному Caddy.
Прямые развертывания по умолчанию не доверяют никаким прокси-серверам. Если вы запускаете Uvicorn самостоятельно,
отключите обработку прокси-заголовков, чтобы этот пограничный узел получал данные от реального узла.
TGWITNESS_PANEL_ALLOWED_IPS ограничивает доступ ко всем панелям, включая панель администратора,
только перечисленными IP-адресами или CIDR-блоками. Проба маршрутизационной идентичности установщика остается общедоступной и
не возвращает данные учетной записи. Добавьте необходимый локальный административный маршрут перед
включением списка разрешенных адресов. Руководство по управляемой установке START-HERE содержит
инструкции по настройке службы и восстановлению.
Селектор запроса API ws должен идентифицировать рабочую область в пути запроса;
неизвестные, несоответствующие и дублирующиеся селекторы отклоняются с кодом ошибки 404.
Скрипты и стили панели содержат метаданные целостности SHA-384. Карта импорта также охватывает локально импортированные модули JS в браузерах, поддерживающих целостность import-map. Динамически сгенерированный языковой ответ находится отдельно. Эти проверки обнаруживают замену ресурсов по отношению к доставленной странице; сама страница и её хеши поступают с сервера панели, поэтому необходимо защитить этот сервер и его путь доставки.
Журнал с момента запуска объединяет системные журналы процесса с записями активности из каждого рабочего пространства: входы в систему, отказы, изменения маршрута и действия оператора. Это консоль в оперативной памяти для текущего процесса, а не постоянная копия каждого сообщения. Часто повторяющиеся события, связанные с сообщениями, сохраняются в журнале, а не заполняют консоль.
Предоставление, изменение и отзыв доступа, а также начало или завершение сеансов также приводят к созданию
подписанных записей в журнале access.*. Токены не включаются в эти записи.
Выданные токены и учетные данные сеансов хранятся в виде хэшей в зашифрованном хранилище.
Ожидающий вход по QR-коду принадлежит сеансу панели, который его инициировал. Завершение или отзыв этой сессии, либо ротация токена главной панели приводят к отмене ожидающего QR- клиента на сервере. Это также применяется в случае, когда браузер не может отправить собственный запрос на отмену. Ротация токена также отменяет входы с помощью QR-кода, запущенные напрямую с использованием токена главной панели. Запрос QR, ожидающий выполнения другой операции, повторно проверяет доступ перед началом. Завершённые авторизации в Telegram и ожидающие входы, запущенные другой сессией панели, сохраняются.
Главный администратор и граница доверия
Основной токен панели остается неограниченным. Вход в браузере с его использованием создаёт сессии, подпадающие под ограничения сеансов, настроенные администратором. Скрипты, отправляющие основной токен напрямую, сохраняют полный доступ и не учитываются как сеансы браузера.
Это контроль доступа на уровне приложения в рамках одной установки. Все рабочие пространства используют общий серверный процесс; это не означает изоляции от администратора хоста. Обеспечьте конфиденциальность основного токена, сеансов Telegram, ключей подписи и каталога данных. Токен-свидетель представляет собой отдельный контрольный точка/удостоверение работоспособности, а не токен доступа к панели.