Деякі частини цієї сторінки досі залишаються англійською мовою: англійський оригінал зазнав змін після перекладу.
Довідка / Зібрати
Telegram · Робочі процеси та операції
Щоденна робота панелі: режими, категорії моніторингу, параметри, сповіщення, експорт даних, резервне копіювання та ємність.
TgWitness / Документація · Розгортання та відновлення
Для першого підключення використовуйте облікові записи та формати сеансів. Пояснення щодо збережених версій, політик подій та пропусків див. у розділі «Як працює збір даних». Цей посібник охоплює щоденну експлуатацію та відновлення.
Управлінська інсталяція включає файли , START-HERE.html, та , а також файл START-HERE.txt, окрім
програми запуску, з посиланням на репозиторій та командами, адаптованими до шляху
інсталяції. Запустіть файл tgwitness guide --print через SSH або tgwitness paths, щоб визначити
фактичний каталог даних. Системна інсталяція з правами root зберігає приватні дані у
файлі /var/lib/tgwitness-…; файл /opt/tgwitness містить саму програму.
Для керованого тимчасового тунелю Cloudflare код tgwitness tunnel off закриває публічний
доступ, тоді як локальна панель та збір даних продовжують працювати. Код tgwitness tunnel on
увімкне його; код tgwitness tunnel restart створює нове тунельне з’єднання. Використовуйте
код tgwitness open, щоб переглянути його поточну адресу. Явне вимкнення зберігається
після перезапуску служби. Код tgwitness stop зупиняє як панель, так і збір даних.
На цій сторінці
Робочий процес оператора#
Діаграма у вигляді тексту
- Виберіть спосіб зберігання та захист ключів → Відкрити панель за допомогою її токена
- Відкрити панель за допомогою її токена → Виберіть робочу область
- Виберіть робочу область → Налаштування прямого або проксі-маршруту
- Налаштування прямого або проксі-маршруту → Введіть номер телефону або виберіть файли / QR-код
- Введіть номер телефону або виберіть файли / QR-код → Перевірте ідентифікацію облікового запису та виберіть доступні групи
- Перевірте ідентифікацію облікового запису та виберіть доступні групи → Збережіть правила щодо подій та вкладень, а потім розпочніть спостереження
- Збережіть правила щодо подій та вкладень, а потім розпочніть спостереження → Моніторинг помилок, доступу, черг та дискового простору
- Моніторинг помилок, доступу, черг та дискового простору → Збереження незалежних контрольних точок
- Збереження незалежних контрольних точок → Експорт та перевірка матеріалів
Авторизація, транспортне з’єднання, доступ до групи та повнота доставки — це різні властивості. Зелений статус з’єднання не означає, що всі події було зафіксовано.
Поділіться результатами роботи, не розкриваючи головного ключа#
Відкрийте Більше інструментів → Доступ, щоб надати рецензенту або аналітику власний токен. Виберіть облікові записи та чати, які вони можуть відкривати, а потім надайте дозвіл на перегляд, експорт або операційні дії. Оператор, який запускає/зупиняє збір даних, потребує доступу до всього робочого простору; рецензент може мати доступ лише до одного чату. Обмеження сеансів, термін дії та правила щодо IP-адрес не пов’язані з авторизацією облікового запису Telegram. Див. Доступ та дозволи.
Використовуйте «Відкриті сесії», щоб завершити з’єднання, або скасуйте доступ, щоб закрити всі його сесії. Консоль адміністратора об’єднує інформацію про активність поточних процесів у всіх робочих просторах. Закриття сесії не зупиняє збір даних.
Режими роботи#
| Режим | Дія | Поведінка |
|---|---|---|
| Демо | scripts\Demo.cmd або --demo |
Синтетичні дані; підключення до реальних акаунтів вимкнено |
| Спостереження | Почати спостереження | Запис оновлень для вибраних джерел |
| Знімок історії | Чати → Дії в чаті → Завантажити історію | До 500 поточних повідомлень; реконструкція всіх минулих змін не здійснюється |
| Пауза | Призупинити спостереження | Припинення збору даних із збереженням даних та завдань у черзі |
| Перегляд/передача | Експорт | ZIP, JSONL/CSV/HTML, контрольна точка, підтвердження обробки та запит на часовий штамп |
| Кілька облікових записів | Робочі простори або верхня кнопка «+» | Необмежена кількість окремих робочих просторів у рамках одного процесу |
Доступ до локальної демо-версії відкривається автоматично без ручного введення токена. Використовується можливість, обмежена терміном дії процесу, яка діє лише для прямого доступу через лупбек до ізольованої синтетичної демо-версії; токен головної панелі не розкривається. Реальні робочі простори та віддалений або проксі-доступ до демо-версії зберігають аутентифікацію за допомогою токена. Вхід у демо-версію не надає жодних повноважень у Telegram.
Категорії моніторингу#

У розділі Додаткові інструменти → Джерела → Запис → Вибрати, які зміни зберегти окремо виберіть нові повідомлення, редагування, повідомлення про видалення, оновлення реакцій та події членства. За замовчуванням зберігаються всі категорії. Параметр Повідомлення, редагування та видалення зберігає оригінальний контекст, водночас вимикаючи окремі оновлення реакцій/членства. Параметр Уся видима активність відновлює всі п’ять категорій. Пресети змінюють форму; натисніть Зберегти налаштування запису, щоб застосувати зміни.
Збережена політика застосовується до всіх вибраних джерел у цій робочій області. Інші робочі області зберігають власні налаштування. Кожна фактична зміна фіксує підписані значення «до» та «після» ; поточна політика також включається до квитанцій про обробку та записів про початок спостереження . Вимкнення категорії не призводить до видалення попередніх спостережень. Повторне ввімкнення не відновлює пропущені зміни. У цій версії немає можливості перевизначення категорій на рівні груп.
Залишайте функцію запису нових повідомлень увімкненою, якщо попередній вміст має значення: повідомлення про видалення не дозволяє відновити текст, який ніколи не було зафіксовано. Оперативні записи, записи про охоплення та інші події, пов’язані з роботою групи, завжди зберігаються. Знімки історії з явною інформацією відокремлені від вибору категорій у режимі реального часу та можуть містити службові повідомлення. Ці параметри не видаляють метадані реакцій/учасників, вбудовані в об’єкт Telegram, який було зафіксовано іншим чином.
Знімок історії може ставити вкладення в чергу під час паузи. Почніть спостереження, щоб обробити їх. Наявність у черзі не означає, що файл завантажено. Недоступний оригінальний файл не замінюється на новішу відредаговану версію; результати фіксуються окремо.
Натискання кнопки «Заблокувати» очищає доступ браузера та секретні поля, але залишає збір даних у дії. Закриття вкладки також залишає процес у дії. Зупинка процесу Python або служби припиняє збір даних незалежно від стану браузера.
Додаткову робочу область можна видалити лише після повного завантаження підписаного контейнера у форматі ZIP або ASiC-E, що містить її журнал та нотатки з Case Board. Підготовки архіву недостатньо: якщо запис не стосується подій налаштування або нотатка була додана після завантаження, функція Видалити залишається недоступною.
Коли панель отримує сам файл, вона враховує експорт лише після отримання кожного
байта, а потім повідомляє розмір за допомогою запиту POST /api/exports/{id}/received; завантаження, яке було перервано,
не враховується. У разі використання браузерного діалогового вікна вибору файлу (доступ до файлової системи) панель повідомляє про це після того, як
файл записано та закрито. Без нього панель передає отриманий файл у список
завантажень браузера і не може визначити, чи зберіг його браузер, наприклад, коли діалогове вікно збереження
було скасовано; у такому разі панель повідомляє, що завантаження розпочалося, а не що файл було збережено. Файл,
який браузер завантажує самостійно (експорт, розмір якого перевищує буфер браузера панелі), та
завантаження іншим HTTP-клієнтом враховуються, коли сервер надіслав повну відповідь.
Операційна система та зворотний проксі-сервер буферизують кілька мегабайтів відповіді, тому для цих
завантажень сервер не може виявити переривання ближче до кінця. Якщо панель не вказала, що файл було збережено,
перевірте завантажений файл перед видаленням. Експорт групи враховується для відповідних облікових записів, коли його
завантажують одразу після підготовки; повторне завантаження з розділу Підготовлені експорти не враховується.
Перед видаленням на панелі відображаються формат, розмір, час підготовки та SHA-256 останнього завантаженого
підписаного архіву, а також з’являється запит на підтвердження того, що цей архів збережено поза робочою областю. Сервер відхиляє запит
DELETE /api/profiles/{id}, якщо параметр kept_copyне встановлено на значення цього SHA-256 (або на confirmed для архіву,
завантаженого до того, як було записано відбиток).
Видалення додаткового робочого простору зупиняє його колектор та видаляє його локальні дані. Якщо
блокований файл або помилка файлової системи перериває видалення, панель повідомляє про збій і
залишає робочий простір у списку як недоступний (DeletionPending). Закрийте програми, що утримують його
файли, та спробуйте виконати видалення ще раз. Перезапуск TgWitness залишає цей робочий простір зупиненим і
не відновлює його частково видалений журнал або ключі. Успішне видалення фіксується
лише після видалення каталогу; окремо експортовані або збережені резервні копії залишаються
під дією власної політики зберігання.
Сповіщення#
Відкрийте Налаштування → Сповіщення та копіювання поза сайтом → Пункти призначення сповіщень або Додаткові інструменти → Додаткові функції → Сповіщення → Налаштувати. TgWitness використовує Apprise для надсилання сповіщень у Matrix, Telegram, Discord, Slack, ntfy, електронну пошту та інші підтримувані сервіси. Ви можете додати кілька пунктів призначення до одного робочого простору.
- Введіть одну URL-адресу призначення Apprise у кожному рядку. Використовуйте каталог служб та формати URL-адрес для вашої служби.
- Увімкніть «Надсилати сповіщення», а потім виберіть сповіщення про проблеми, зміни в спостережуваних чатах та щоденний звіт. Час у звіті визначається за серверним часом.
- Увімкніть опцію «Включати короткі уривки», якщо ви хочете, щоб у сповіщеннях з’являвся збережений текст із видалених та відредагованих повідомлень.
- Натисніть «Зберегти сповіщення», а потім «Надіслати тест», щоб перевірити доставку.
Для власного одержувача використовуйте JSON-вебхук Apprise.
Наприклад, jsons://notify.example.org/tgwitness надсилає JSON через HTTPS на цю
кінцеву точку. Це вигаданий приклад; замініть його на власний пункт призначення.
Пункти призначення та налаштування належать до обраного робочого простору. Повідомлення про зміни охоплюють джерела, що відстежуються, включаючи нещодавно додані чати. Дзвіночок у верхній панелі також відображає список останніх проблем та змін у чатах.
У демо-версії елементи керування сповіщеннями відображаються, але надсилання вимкнено. Налаштуйте доставку в реальному робочому просторі. Сповіщення використовують маршрут «Direct», SOCKS5 або HTTP цього робочого простору; MTProxy не може їх передавати. Не-HTTP-призначення, такі як SMTP, вимагають прямого маршруту.
Розташування панелей#

Журнал відображає спостереження, пошук та фільтри. Редагування відкриває збережені версії; видалення відкриває попередній вміст, якщо він доступний. Невідомі джерела залишаються явно вказаними. Статистика доступна в розділі «Огляд»; деталі збору даних зберігаються в локальному посібнику.
Відкрийте відредаговане повідомлення, щоб порівняти його версії за допомогою Зміни в тексті або Поруч; Вихідні дані показує збережені поля. Зміни прихованих посилань і кнопок ботів відображаються окремо. Відкрийте попередній перегляд вкладення, щоб переглянути збережені зображення, аудіо чи відео; кнопка завантаження забезпечує доступ до збереженого оригіналу.
Режим Live оновлює журнал і чати в міру надходження записів. Призупиніть його під час перегляду або скористайтеся кнопкою нових подій, коли будете готові; збір даних при цьому продовжує працювати. Комбінація Ctrl/Cmd+K знаходить дії панелі та виконує пошук у журналі.
Більше інструментів → Джерела містять область спостереження (обрані чати, папку Telegram або весь акаунт), доступні чати всіх типів, вибрані джерела з зірочками пріоритету, налаштування вкладень та повторної перевірки, а також знімки історії. Приватні джерела обираються за діалогом/ID без публічного посилання. Статус доступу описує останню перевірку, а не постійні дозволи.
Відфільтруйте джерела, позначте їх прапорцями, а потім одночасно увімкніть, призупиніть або позначте їх як пріоритетні. У списку доступних чатів кнопка Додати вибрані використовує ваш вибір; Додати всі знайдені використовує поточний пошуковий запит і фільтр за типом.
У розділі «Чати → Користувачі» перелічено всіх, чиї повідомлення збережено; якщо для чату ввімкнено профілі користувачів, один клік відкриває профіль цієї особи з посиланнями на записи в журналі.
Більше інструментів → Додаткові функції → Незалежний свідок створює токени свідка, доступні лише для читання, показує, коли кожен свідок востаннє перевіряв дані, та надає команди й параметри для запуску одного (незалежного свідка).
Більше інструментів → У розділі Параметри містяться всі обмеження та темпи роботи робочого простору, які не вказані на інших сторінках:
кількість прочитаних діалогів, частота перечитування списку чатів, інтервали пульсу та контрольних точок
, буфер запуску, спосіб розподілу запитів під час повторної перевірки (перша затримка, кількість чатів за
прохід, пауза між чатами, відновлені та повторно запитані повідомлення), резерв дискового простору, тайм-аути та
повторні спроби завантаження, що шукають профілі користувачів (включно з вашими власними регулярними виразами),
розмір та частота сповіщень, обмеження на знімки, ZIP-файли та завантаження через браузер, а також тайм-аути та
повторні спроби клієнта Telegram. Кожне поле показує свій діапазон та значення за замовчуванням; змінені поля
позначені та можуть бути відновлені поодинці або всі разом. Кожна зміна фіксується як
parameters.changed із значеннями до та після, а записи про початок спостереження вказують
діючі значення. Значення застосовуються з наступного використання; тайм-аути клієнта та повторні спроби — з
наступного підключення. Інтервали повторної перевірки, типи та розміри вкладень, інтервали збереження доказів та копій поза сервісом
залишаються на своїх сторінках і можуть приймати будь-яке значення в межах діапазону, а не лише попередні налаштування.
Дзвіночок у верхній панелі відображає останні проблеми та зміни в спостережуваних чатах; непрочитані повідомлення підраховуються, доки їх не позначено як прочитані. Зміни групуються за чатами та годинами («12 видалено, 1 відредаговано, 0 не знайдено»), а такі проблеми, як вихід із системи або переповнений диск, залишаються у списку незалежно від того, наскільки активними є чати.
Більше інструментів → Реєстрація починається з поля для введення номера телефону. Натискання Продовжити веде безпосередньо до введення коду, а запит на введення облікових даних API з’являється лише у разі їх відсутності. QR-код та імпорт файлів — це альтернативні вкладки. Збережені облікові дані API використовуються повторно лише в межах власного робочого простору. Екран введення даних не містить бічної панелі, статистики чи розділів налаштувань. Іконка Налаштування відкриває елементи керування API, проксі, сховищем та додатковими обліковими записами. Новий робочий простір відкриває початкове налаштування ; після входу в систему робочий простір із збереженими джерелами та записами відкриває Чати . Зміна маршруту вимагає призупинення спостереження та скасовує незавершений вхід. Існуючий журнал не можна автоматично прив’язати до іншого облікового запису Telegram.
Експорт перевіряє цілісність журналу та створює переносимі файли. Його ідентифікатор робочої області можна передати до командного рядка завантаження. Кожен експорт фіксує префікс повного журналу; пізніші події потрапляють до наступного експорту. Фільтри пошуку не змінюють область дії пакета. Детальна інформація щодо підписання та охоплення наведена у розділі Верифікація та докази.
Панель відображає стан колектора, медіафайли в черзі/з помилками, найстаріші медіафайли в очікуванні, вільне місце на диску, паузи запитів та джерела, доступ до яких не підтверджено, у розділі «Стан колектора» . Ці деталі спочатку згорнуті та приховані на сторінці «Обліковий запис». Картка налаштувань показує наступний крок: підключити обліковий запис, вибрати джерела або розпочати спостереження. Список облікових записів є знімком на момент завантаження; обрана робоча область періодично оновлюється. Це не багатопроцесний монітор SLA.
Інтерфейс використовує локальні ресурси та текстове відображення вихідного вмісту. Протестовано настільний і вузький макети в Chromium.
Середовища розгортання#
| Середовище | Встановлення | Статус перевірки |
|---|---|---|
| ПК/сервер на базі Windows | Python 3.11+, scripts\Setup.cmd/Start.cmd, приватний каталог даних | Перевірено локально на Windows/Python 3.12 |
| Сервер Linux/VPS | Python venv, виділений сервер, HTTPS/SSH | Наведено приклади коду, CI та systemd; не виконується на цьому хості |
| macOS | Python venv, процес у фоновому режимі або агент користувача | Наведено приклад запуску; необхідна окрема перевірка встановлення |
| Docker/Compose | Постійний обсяг роботи, один виконавець | Надано визначення та перевірку працездатності CI; Docker недоступний локально |
| Мобільний браузер | Підключіться до захищеної панелі на працюючому сервері | Перевірено на вузькому макеті Chromium; колектор не працює на iOS/Android |
Портативність означає відсутність обов’язкового хмарного сервісу чи фронтенд-збірки. Кожна цільова система все одно потребує сумісних залежностей Python/криптографії, локального диска та доступу до мережі. Див. файл DEPLOYMENT.md та шаблони сервісів.
Робочі середовища спільно використовують процесор, пам’ять та цикл подій. Для ізоляції процесів використовуйте окремі екземпляри, порти, каталоги даних та авторизації облікових записів. Не існує єдиної панелі управління для окремих екземплярів. Ніколи не направляйте кілька робочих процесів до однієї бази даних.
Перевірка та експорт даних#
Перед запуском підготовленого середовища виконайте команду python start.py --check. Додайте --json
для перевірок у машиночитаному форматі або вкажіть потрібні параметри --data-dir, --host та --port.
Команда перевіряє наявність необхідних умов без входу в Telegram або створення журналу.
Перевірка журналу виконується під час запуску програми, а готовність до збору даних відображається
на панелі. Зайнятий порт може бути просто існуючим екземпляром.
Браузери, що підтримують API доступу до файлової системи, зберігають експортовані дані через потік із можливістю запису. Інші браузери буферизують не більше 128 МіБ. Для експорту великих обсягів даних або у разі використання браузерів без підтримки потокового запису файлів скористайтеся командним рядком для потокового запису:
python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip
Додайте --profile ID
з розділу «Експорт» для дочірнього робочого простору. Для віддаленого доступу використовуйте --url https://server
. Простий HTTP приймається лише для локальних адресатів. Токен
зчитується з файлу та надсилається у заголовку, а не виводиться на екран чи вставляється в URL-адресу. Перенаправлення
не допускаються. Існуючі адресати не перезаписуються. У разі невдалої передачі видаляється
її тимчасовий фрагмент файлу. Повідомлений SHA-256 є контрольною сумою передачі; перевірте підписаний
ZIP-файл окремо за допомогою надійного відбитка/контрольної точки.
Створення резервних копій, відновлення та перебої в роботі#
- Призупиніть спостереження та коректно завершіть процес.
- Скопіюйте весь каталог даних: бази даних, WAL/SHM (якщо є), мультимедіа,
credentials.enc,signing.enc,network.enc, ключі сховища/метадані, токен, контрольні точки та кожен каталогprofiles/. - У режимі зовнішнього ключа окремо зберігайте головний ключ та кожен ключ
vault.external.json. Створення нового ключа не дозволяє відновити старі секретні дані. - Відновіть дані, поки пункт призначення зупинено; налаштуйте вихідний ключ, обмежте доступ та перевірте цілісність перед відновленням роботи.
- Записувати час простою та результати верифікації. Час простою залишається записаним проміжком; знімок історії додає стан після нього.
Evidence ZIPs exclude sessions/private keys and are not full service backups.
tgwitness backup FOLDER makes the same copy while the panel keeps running and leaves out the
search index, which rebuilds itself; see Updates and backups.
Four things are protected differently:
| Що | Захист |
|---|---|
| Файли експорту без пароля (за замовчуванням) | Підписано, тому зміни можна виявити; щоб зашифрувати експорт, задайте пароль |
| Файли експорту з паролем | Якщо ви встановите пароль, готовий експорт без змін зберігається у форматі ZIP із шифруванням AES-256 за допомогою WinZip, який можна відкрити за допомогою 7-Zip та WinRAR; пароль не зберігається (обробка доказів) |
| База даних журналу та збережені на диску вкладення | Зашифрований диск або том і права доступу до папки |
| Сесії Telegram та ключі підпису | Зашифровано в каталозі даних (credentials.enc, signing.enc, network.enc) |
Повне резервне копіювання — це описаний вище каталог зупинених даних, а не експорт.
Для обох випадків використовуйте захищене сховище та механізм контрольованої передачі. Тимчасові експортовані дані зберігаються у папці
temporary-exports/ кожного робочого простору; завершені відповіді очищуються, а перервані файли експорту
видаляються під час наступного запуску, поки триває блокування екземпляра цього робочого простору.
Після події відновлення з’єднання колектор запитує пропущені оновлення, починаючи з збереженої позиції оновлення. Постійні завдання з обробки медіаданих та позиція оновлення Telegram зберігаються після перезапуску; див. формат доказів.
Ємність та термін зберігання#
Стандартні обмеження, які можна змінити в меню Додаткові інструменти → Параметри: перші 1,000 діалогів, 500 повідомлень
на знімок, 4 ГіБ нестисненого підписаного вмісту ZIP (для більших архівів потрібно
verify.py --max-gib N) та 128 МіБ для резервного варіанту браузера. Вкладення займають 1–2,000 МіБ на
тип у меню Додаткові інструменти → Джерела → Запис → Вкладення. За замовчуванням CLI для завантаження передає 5 ГіБ. Доступний простір на диску може бути
нижчою межею. Зарезервуйте місце для журналів, мультимедіа, WAL, тимчасових експортів та резервних копій.
Експорти використовують обсяг даних, а не папку 512 MiB /tmp у Compose.
Вимірюйте події за секунду, вік черги, обсяг медіаданих у байтах та затримку диска, а не лише кількість груп. Вимірювання потокової передачі здійснюється на працюючому колекторі. Автоматичного видалення збережених даних не відбувається. Видалення кінця журналу порушує його зв’язок із збереженими контрольними точками.
Пріоритетні повторні перевірки вже є: джерела, позначені зірочкою, за замовчуванням перевіряються кожні 15 хвилин, інші — кожні 6 годин (див. рівні повторної перевірки). Експорт із паролем працює, як описано вище. Обмежений доступ описано в розділі доступ і дозволи. Див. READINESS.md, LIVE_ACCEPTANCE.md та VERIFICATION.md.