TgWitness / 文档

已测试的内容 →

参考 / 设置

Telegram · 快速入门

安装和启动 TgWitness 的所有方法:Windows 安装包、Python、Docker 以及综合演示,并附带初步测试。

TgWitness / 文档

入门指南

英语 · 俄语 · 乌克兰语 · 西班牙语 · 葡萄牙语(巴西) · 土耳其语 · 阿拉伯语 · فارسی · 乌尔都语 · हिन्दी · 印尼语 · 越南语 · 简体中文

TgWitness 是一款用于监控您账户可访问的 Telegram 群组和频道的独立应用程序, 它在本地运行并拥有独立的数据目录。

初次访问?请先体验演示,然后再连接账户。 选择代理、见证人、导出或服务器设置的相关指南。 GitHub Actions 捕获(预览)功能可在您自己的 GitHub 分支中运行捕获任务,而无需本地安装。

安装并启动#

引导式安装程序自带 Python 环境,并在安装前会检查包哈希值和发布 签名。再次运行该程序将更新现有安装。

Linux / macOS:

curl -fsSL https://get.destroy.tools/install.sh | bash

Windows(PowerShell 或命令提示符):

powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://get.destroy.tools/install.ps1 | iex"

在 Ubuntu 服务器上,请以 root 身份运行以安装后台服务;在桌面系统上,请 以普通用户身份运行。在 Ubuntu 上,安装程序会显示控制面板地址和访问密钥; 在 macOS 和 Windows 上,本地控制面板会在您的浏览器中自动打开。请继续执行下方的连接 Telegram 步骤。安装、验证和更新部分涵盖了服务器访问选项、 运行脚本前的检查、更新及卸载操作。

其他方法#

GitHub 发布版本、源代码和 Docker 镜像均可作为安装程序的替代方案。便携式 下载包将在发布构建版本发布后提供:

主机 无需安装 来源:Python 3.11+ Docker:Engine/Desktop 搭配 Compose 2.20+
Windows 从 GitHub Releases 中提取 TgWitness-<version>-windows-amd64-portable.zip,双击 TgWitness.cmd 双击 Start.cmd 双击 scripts\Docker.cmd
Linux / macOS — sh start.sh sh scripts/docker-start.sh

对于源码方式,请下载并解压当前的 main 分支, 或克隆仓库:

git clone https://github.com/phishdestroy/TgWitness.git
cd TgWitness

如果未找到合适的 Python,Start.cmd 会提议为您的 Windows 用户安装 Python 3.12(通过 winget 或带签名的 python.org 安装程序)。如果缺少 Python,start.sh 会打印 适用于您的 Linux 发行版或 macOS 的确切安装命令。 首次从源码启动会自动创建 .venv 并安装依赖项。

Docker 负责构建应用程序并在后台启动它;无需在主机上安装 Python。当 容器运行正常时,scripts\Docker.cmd 和 scripts/docker-start.sh 会输出控制面板地址和令牌。在所有受支持的主机上,相应的 Docker 命令如下:

docker compose up -d --build --wait
docker compose exec tgwitness cat /data/panel-token.txt

打开 http://127.0.0.1:8787。使用 Docker 辅助程序或第二个 Docker 命令生成的令牌,或者在便携式或源代码安装中读取 data/live/panel-token.txt 文件。继续执行下方的 “连接 Telegram”步骤。 原生安装和 Docker 安装使用独立的存储空间; 启动 Docker 不会导入现有的原生日志。

对于服务器,部署涵盖自动 HTTPS、重启、 发布图片、更新和备份。

探索界面#

  1. 在便携包中运行 TgWitness-Demo.cmd ,在 Windows 源 文件夹中运行 scripts\Demo.cmd ,或在 Linux/macOS 上运行 sh start.sh --demo 。首次从源代码启动会先创建 .venv 并安装依赖项。
  2. 访问 http://127.0.0.1:8787。
  3. 本地演示会自动打开示例日志。无需复制令牌即可直接进行本地访问。

演示消息均为虚构。演示模式无法连接真实的 Telegram 账户。

连接 Telegram#

[!警告] 请使用专用账户。Telegram 可能会因请求 量过大而限制或永久封禁账户,无论请求来自何种客户端。请连接专门用于 观察的账户,而非个人或重要账户,并在 专用账户上创建 API ID / 哈希值。

  1. 如果原生演示程序正在运行,请将其停止,并运行 Start.cmd 或 sh start.sh。 否则,请继续运行上文启动的实时安装程序。
  2. 使用面板令牌登录。新工作区将打开初始设置界面。 选择仅下载、关注聊天或案件证据。
  3. 请检查连接状态。如有需要,请配置您自己的代理;连接 设置在配置完成后仍可使用。
  4. 在 Connect Telegram 中,选择一个电话号码、一个二维码、账户文件(TData、 .session、StringSession、账户 JSON)或完整的授权密钥。系统提示时,请完成 Telegram 确认、验证码及双重验证密码的输入。
  5. 请核对显示的账户,选择聊天群组并检查您的设置。在 最后一个屏幕上点击完成。对于仅下载选项,开始导出将启动一次性的 导出操作并打开导出页面以显示进度;此操作不会启用持续观察功能。

配置完成后,聊天→选择可更改所选聊天。 设置控制 数据收集和文件;更多工具→来源提供详细来源列表 (标准或专家级别)。面板指南描述了六个主要 部分及其上下文控制项。

API ID + Hash 为可选项:工作区使用其已保存或导入的配对, 或来自内置池中的有效配对。若要使用您自己的应用,请将一组 API ID:API Hash配对粘贴到 API ID 字段中。对于 Auth key,请粘贴全部 512 个十六进制 字符,并选择提供的 DC ID。用户 ID 为可选项,若输入则会进行验证。

API 凭据用于识别您的应用程序;它们本身并不能 授权任何账户。私人群组无需公开用户名,但您的账户必须具备访问权限。

对于现有账户,请参阅账户和会话格式:该 面板支持 Telethon StringSession、Telethon/Pyrogram SQLite、单账户 TData ZIP 以及受支持的账户 JSON 格式。请同时选择一个会话及其对应的 JSON 文件, 点击检查文件,然后点击连接账户。QR 登录功能也 可用,且具有相同的可选 API 设置。 TDLib、机器人会话以及 CSV/JSON 账户清单均不支持。

对于多个账户,请使用账户 → 导入账户并选择其受支持的 会话文件。配套的 JSON 文件按基本名称(basename)配对;每个导入的账户 都会获得各自的工作区。请参阅批量导入与账户组。

要添加另一个账户,请点击账户选择器旁边的+号,或使用 账户 → 添加账户。工作区拥有独立的会话、 日志、密钥、数据源和队列。切换视图时,其他收集器将继续运行。 在此安装环境中,同一个 Telegram 账户不能分配给两个工作区。 工作区的数量没有限制;它们共享一个进程,因此容量取决于机器性能。

实时面板令牌用于保护您对 Telegram 授权及已保存 材料的访问权限;它与 Telegram API 凭据相互独立。只有明确启动的、 直接访问的本地演示版本才会自动获得访问权限。远程/代理演示版本仍使用 data/demo/panel-token.txt。

查看与导出#

  • 日志:可按来源和事件类型搜索和筛选记录。
  • 选择一项事件,查看其原始记录、来源信息及保存的版本。
  • 编辑详情显示可用的编辑前/编辑后内容。删除详情显示 最后捕获的内容(如有);未知行为者仍为未知。
  • 导出格式:带签名的 ZIP、JSONL、CSV 以及离线 HTML。
  • 完整聊天导出(聊天 → 导出聊天,或导出 → 捕获或导出一个 聊天):将一个聊天的全部可见 历史记录下载为包含 chat.json(Telegram 导出风格)和可读 chat.html 的签名包。私聊功能仅在账户为成员时有效。这是当前的 快照,并非已删除或先前编辑过的消息的重建。使用 python verify.py chat-export.zip --fingerprint TRUSTED_SHA256 验证 副本。
  • 保存检查点:将签名日志的边界保持在收集器之外。
  • 下载签名运行收据:保留收集器的程序/版本记录。
  • 准备时间戳请求:向时间戳授权机构发起离线请求; 按照 TIMESTAMP.md 中的说明获取并验证响应。
  • 验证日志:检查事件签名和链节。ZIP 导出功能还会检查媒体文件。

支持的浏览器可将大型导出文件直接保存到指定文件中。其他浏览器 最多缓存 128 MiB。在服务器运行期间,流式 CLI 支持 更大规模的下载,而无需缓存整个响应:

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

若需使用其他工作区,请通过导出 → 工作区 ID添加--profile ID。 若需连接远程服务器,请添加--url https://your-server。默认传输限制为 5 GiB;可通过--max-mib调整该限制。 签名 ZIP 内容默认具有单独的 4 GiB 未压缩 验证限制(通过更多工具 → 参数可提高该限制;使用 verify.py --max-gib N 验证此类归档文件)。请使用可信的验证器副本、 独立保留的密钥指纹以及(作为证据的最低要求)时间戳 权威机构的根证书(--tsa-ca)来验证归档文件。

查看安装指南#

python start.py --setup-only
python start.py --check
python start.py --check --json

--check用于检测本地依赖项、签名支持、存储、密钥配置以及 监听地址。该工具不会安装任何内容,也不会连接到Telegram。若端口 已被占用,可能意味着已有另一个实例正在运行。请使用另一个--port实例,或先停止当前实例。

启动程序将安装到.venv目录下。辅助的python -m tgwitness...命令必须 在Windows系统上使用.venv\Scripts\python.exe,或在Linux/macOS系统上使用.venv/bin/python, 除非该环境已激活。

会话、保护与操作#

一个封闭且一致的 Telethon SQLite .session 文件可通过以下命令在本地转换: python -m tgwitness.sessions account.session --out account.tgwitness-session,随后 可在更多工具→账户→文件中加载。还支持直接文件导入和二维码登录。有关登录格式、SOCKS5、 HTTP CONNECT、MTProxy 及外部主密钥的信息,请参阅 CONNECTION-SECURITY.md。

暂停观察将停止数据采集。锁定仅关闭浏览器访问权限。 关闭标签页不会终止采集进程。停止该进程才会中断 数据采集;历史快照无法还原所有遗漏的编辑或删除操作。 了解数据采集在事件策略、附件队列、 账户隔离及重启行为方面的运作原理。

会话和密钥均经过加密。消息内容、媒体文件和导出数据需要使用 加密磁盘或卷。使用可信密钥验证日志签名,并单独保存检查点。 审查所选采集模式下的 捕获记录、外部时间凭证和环境证明。

请阅读 OPERATIONS.md 了解备份/恢复操作,阅读 DEPLOYMENT.md 了解托管方案,并访问 deploy/ 查看服务示例。已安装的 控制面板还包含一份离线设置指南,地址为 /guide.html。

实际验证情况及现有局限性 记录在 VERIFICATION.md 和 READINESS.md 中。