快速入门

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

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

初次访问？在连接账户前，请先体验演示版。 选择代理、Witness、数据导出或服务器设置的相关指南。

安装并启动#

通过 GitHub Actions 采集（预览版）

请选择一种方式。发布版本发布后，即可获取便携版下载：

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

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

当前源码包含批量导入账户、MTProxy 仪表板以及可恢复的 历史记录加载功能。0.7.0 便携预览版及其发布源码压缩包早于 这些新增功能。有关版本界限，请参阅更新日志。

如果未找到合适的 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#

[!警告] 请勿使用任何您无法承受损失的资源。我们强烈建议不要连接 个人或重要账户，也不要在您珍视的账户上创建 API ID / 哈希值。 Telegram 会不按规律且往往永久封禁账户，无论使用何种客户端。 测试运行是否顺利取决于 Telegram 自身，而非 TgWitness，且无法保证后续效果。

1. 如果原生演示程序正在运行，请将其停止，并运行 Start.cmd 或 sh start.sh。 否则，请继续运行上文启动的实时安装程序。
2. 请使用与您的安装方式对应的面板令牌来打开面板。
3. 如果您需要使用代理，请在“账户”→“设置”→“连接设置”→“更改连接路径”中进行保存。
4. 在“账户”中，输入您的手机号码并点击“继续”，选择 “二维码”→“显示二维码”，或选择文件并点击“连接账户”。 API ID + 哈希为可选项：工作区将使用其已保存或导入的配对， 或来自内置池中的有效配对。若要使用您自己的应用程序，请将一组 API ID:API Hash配对粘贴到API ID中。 如需完整的授权密钥，请选择“授权密钥”，粘贴全部 512 个十六进制 字符，并选择提供的 DC ID。用户 ID 为可选项，若输入则会被勾选。
5. 请完成您选择的登录方式：手机/验证码/双因素认证（2FA），通过 已登录的 Telegram 应用确认二维码，或导入受支持的授权会话。
6. 请核对显示的账户 ID。开放来源：您的聊天记录会自动加载；请添加您的群组。
7. 在“选择要保留的更改”下，选择事件类别或 “消息、编辑和删除”预设，然后保存监控设置。
8. 请分别选择附件设置，然后点击“开始监控”。

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

对于现有账户，请参阅账户和会话格式：面板 支持 Telethon StringSession、Telethon/Pyrogram SQLite、单账户 TData ZIP 以及受支持的账户 JSON。同时选择一个会话及其配套的 JSON 文件， 然后按连接账户。二维码登录同样 可用，并支持相同的可选 API 设置。不支持 TDLib、机器人会话以及 CSV/JSON 账户清单。

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

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

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

查看与导出#

• 日志：可按来源和事件类型搜索和筛选记录。
• 选择一项事件，查看其原始记录、来源信息及保存的版本。
• 编辑详情显示可用的编辑前/编辑后内容。删除详情显示 最后捕获的内容（如有）；未知行为者仍为未知。
• 导出格式：带签名的 ZIP、JSONL、CSV 以及离线 HTML。
• 完整聊天记录导出（来源 → 完整聊天记录导出）：将单个聊天窗口的全部可见 历史记录下载为包含 chat.json（Telegram-export 风格）和可读 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 验证此类存档）。请使用可信的验证器副本以及 独立保存的密钥指纹/检查点来验证该存档。

查看安装指南#

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 在本地进行转换，随后 加载到 Account 中。还支持直接文件导入和 QR 码登录。有关登录格式、SOCKS5、 HTTP CONNECT、MTProxy 及外部主密钥的详细信息，请参阅 CONNECTION-SECURITY.md。

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

会话和密钥均经过加密。消息内容、媒体文件及导出数据需要存储在 加密磁盘或卷上。签名基于可信密钥来验证数据完整性； 但无法证明消息源自 Telegram，也无法防止由控制收集器及其密钥的操作员 伪造数据。

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

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