TgWitness / 文档

已测试的内容 →

本页面部分内容仍为英文:英文原文在翻译后发生了变更。

参考 / 收集

Telegram · 工作流程与操作

控制面板的日常操作:模式、监控类别、参数、通知、导出、备份及容量。

TgWitness / 文档 · 部署与恢复

部署与恢复

首次连接时,请使用账户和会话格式。 有关保存版本、事件策略和数据缺失的说明,请参阅 “数据采集原理”。本指南涵盖日常操作和数据恢复。

受管安装包除启动器外,还包含 、START-HERE.html、、、START-HERE.txt 以及 , 其中包含针对其安装路径定制的仓库链接和命令。通过 SSH 运行 tgwitness guide --print,或运行 tgwitness paths 以定位 实际数据目录。root 级 systemd 安装将私有状态存储在 /var/lib/tgwitness-… 中;/opt/tgwitness 存放程序本体。

对于托管式临时 Cloudflare 隧道,tgwitness tunnel off 将关闭公共 访问,同时本地控制面板和数据收集功能仍继续运行。tgwitness tunnel on 将其启用;tgwitness tunnel restart 创建新的隧道连接。使用 tgwitness open 查看其当前地址。显式关闭设置在 服务重启后仍会保留。tgwitness stop 将同时停止控制面板和数据收集功能。

本页内容

操作员工作流程#

流程图选择存储方式和密钥保护方案 → 使用其令牌打开面板; 使用其令牌打开面板 → 选择工作区; 选择工作区 → 配置直连或代理路径; 配置直连或代理路径 → 输入手机号码或选择文件 / QR码; 输入手机号码或选择文件 / QR码 → 验证账户身份并选择可加入的群组; 验证账户身份并选择可加入的群组 → 保存事件和附件策略,然后开始监控; 保存事件和附件策略,然后开始监控 → 监控错误、访问、队列和磁盘; 监控错误、访问、队列和磁盘 → 保留独立检查点; 保留独立检查点 → 导出和验证材料选择存储方式和密钥保护方案使用其令牌打开面板选择工作区配置直连或代理路径输入手机号码或选择文件/ QR码验证账户身份并选择可加入的群组保存事件和附件策略,然后开始监控监控错误、访问、队列和磁盘保留独立检查点导出和验证材料
图表转为文本
  1. 选择存储方式和密钥保护方案 → 使用其令牌打开面板
  2. 使用其令牌打开面板 → 选择工作区
  3. 选择工作区 → 配置直连或代理路径
  4. 配置直连或代理路径 → 输入手机号码或选择文件 / QR码
  5. 输入手机号码或选择文件 / QR码 → 验证账户身份并选择可加入的群组
  6. 验证账户身份并选择可加入的群组 → 保存事件和附件策略,然后开始监控
  7. 保存事件和附件策略,然后开始监控 → 监控错误、访问、队列和磁盘
  8. 监控错误、访问、队列和磁盘 → 保留独立检查点
  9. 保留独立检查点 → 导出和验证材料

授权、传输连接、群组访问权限以及 消息送达完整性是不同的属性。绿色连接状态并不意味着所有 事件均已被捕获。

在不共享主密钥的情况下共享工作成果#

打开更多工具→访问权限,为审核员或分析师分配专属令牌。选择他们 可以打开的账户和聊天群,然后授予查看、导出或操作权限。 启动/停止收集的操作员需要整个工作区的访问权限;审核员 的权限可限制为单个聊天群。会话限制、过期规则和 IP 规则与 Telegram 账户授权相互独立。参见访问与权限。

使用“打开的会话”功能可终止单个连接,或撤销访问权限以终止所有 会话。管理员控制台整合了跨 工作区的当前进程活动。关闭会话后,数据采集仍将继续运行。

运行模式#

模式 操作 行为
演示 scripts\Demo.cmd 或 --demo 合成数据;已禁用真实账户关联功能
观察 开始监控 记录所选来源的已发布更新
历史快照 聊天 → 聊天操作 → 加载历史记录 最多可记录 500 条当前消息;不重建所有历史变更
暂停 暂停观察 在保留数据和队列任务的同时停止采集
审核/交接 导出功能 ZIP、JSONL/CSV/HTML、检查点、处理回执和时间戳请求
多个账户 工作区或顶部的 + 按钮 在一个进程中可创建任意数量的独立工作区

本地演示访问将自动开启,无需手动输入令牌。该功能采用 进程生命周期权限,仅适用于直接回环访问一个隔离的 合成演示环境;主控制面板的令牌不会被披露。真实工作区以及远程 或通过代理访问演示环境仍需进行令牌身份验证。进入演示环境并不授予任何 Telegram 授权。

监控类别#

支持按账户设置监控参数,并提供合成源数据

在更多工具→源→记录→选择要保留的更改中,可分别选择新消息、编辑、 删除通知、反应更新和成员事件。默认设置 保留所有类别。消息、编辑和删除选项保留原始上下文, 同时禁用单独的反应/成员更新。所有可见活动选项则恢复 全部五类。预设会更改表单;点击保存记录设置以应用。

保存的策略适用于该工作区中所有选定的消息源。其他 工作区将保留各自的设置。每次实际变更都会记录带签名的变更前/变更后 值;当前策略也会包含在处理收据和观察 开始记录中。禁用某类别不会删除之前的观察记录。重新启用 该类别也不会恢复已遗漏的变更。 此版本中不支持按组覆盖类别设置。

当先前内容重要时,请保持“记录新消息”功能启用:删除通知无法 恢复从未被捕获过的文本。操作/覆盖记录及其他群组 服务事件将始终被保留。 明确的历史快照与 实时分类选择相互独立,且可能包含服务消息。这些开关不会 对嵌入在已捕获 Telegram 对象中的反应/成员元数据进行屏蔽。

历史快照在暂停期间可能会将附件加入队列。开始监控以处理 这些附件。“已加入队列”并不意味着已下载。若原始文件不可用,系统不会用 较新的编辑版本进行替换;处理结果将分别记录。

点击“锁定”按钮将清除浏览器访问权限和密钥字段,但数据采集仍将继续运行。 关闭标签页后,进程仍将继续运行。停止 Python 进程或服务 将终止数据采集,无论浏览器状态如何。

只有在包含该工作区的日志及其“案例板”笔记的已签名 ZIP 或 ASiC-E 容器被完全下载后,才能删除该额外工作区。仅准备好归档文件还 不够:如果存在设置事件之外的记录,或者在下载后添加了笔记,则删除 选项将不可用。

当面板接收到文件本身时,它会在接收完每个 字节后才将该导出计入统计,然后将文件大小上报至 POST /api/exports/{id}/received;中途中断的 下载不会被计入。如果使用浏览器保存选择器(文件系统访问),则面板会在 文件写入并关闭后进行上报。 如果没有文件保存对话框,面板会将接收到的文件传递给浏览器的 下载管理器,且无法得知浏览器是否保留了该文件(例如当保存对话框被 取消时);此时面板仅报告下载已开始,而非文件已保存。 由 浏览器自行下载的文件(即超过面板浏览器缓冲区大小的导出文件)以及 由其他 HTTP 客户端进行的下载,在服务器发送完整响应后才被计入。由于 操作系统和反向代理会缓存数兆字节的响应数据,因此对于此类 下载,服务器无法检测到接近末尾时的中断。 除非面板显示文件已保存, 否则在删除前请检查已下载的文件。群组导出在 准备完成后立即下载时,会计入其账户统计;而从已准备的导出中再次下载则不计入。

Before deleting, the panel shows the format, size, preparation time and SHA-256 of the last downloaded signed archive and asks to confirm that this archive is saved outside the workspace. The server refuses DELETE /api/profiles/{id} without kept_copy set to that SHA-256 (or to confirmed for an archive downloaded before the fingerprint was recorded).

删除额外的工作区将停止其收集器并清除其本地数据。如果 因文件被锁定或文件系统错误导致删除中断,控制面板将报告失败,并 将该工作区标记为不可用(DeletionPending)。请关闭正在使用其 文件的程序,然后重试“删除”操作。 重启 TgWitness 不会恢复该工作区的运行状态,也不会 重建其部分已删除的日志或密钥。只有在目录被移除后, 才会记录成功的删除操作;单独导出或备份的副本仍 受其自身的保留策略约束。

通知#

打开设置→通知和异地备份→通知目的地,或 更多工具→扩展功能→通知→配置。TgWitness使用 Apprise向Matrix、Telegram、Discord、Slack、ntfy、电子邮件及其他 受支持的服务发送警报。您可以在一个工作区中添加多个通知目的地。

  1. 每行输入一个 Apprise 目标 URL。请根据您使用的服务 ,参考服务目录和 URL 格式进行设置。
  2. 开启“发送通知”功能,然后选择问题警报、受监控 聊天中的变化以及每日摘要。摘要显示的时间以服务器时间为准。
  3. 若希望在警报中包含已删除和已编辑 消息中的保存文本,请开启“包含简短摘录”选项。
  4. 点击“保存通知”,然后点击“发送测试”以检查送达情况。

若要使用您自己的接收端,请使用 Apprise 的 JSON Webhook。 例如, jsons://notify.example.org/tgwitness 通过 HTTPS 将 JSON 发送至该 端点。这是一个虚构的示例;请将其替换为您的实际目标地址。

目标和设置属于所选工作区。变更通知 涵盖其监视的来源,包括新添加的聊天。顶部栏中的铃铛图标 还会列出最近的问题和聊天变更。

在演示中,通知控件可见但发送功能已禁用。请在真实的工作区中配置 发送设置。通知使用该工作区的 Direct、SOCKS5 或 HTTP 路由;MTProxy 无法传输通知。SMTP 等非 HTTP 目标需要 直接路由。

面板布局#

使用合成数据连接工作区

日志显示观察结果、搜索和筛选结果。编辑操作会显示已捕获的版本; 删除操作会显示先前内容(如有)。来源不明的信息将明确标注。 统计数据可在“概览”中查看;采集详情保存在本地指南中。

打开已编辑的消息,使用文本内差异或并排比较来对比其不同版本; 原始数据会显示已保存的字段。隐藏链接和机器人按钮的更改会 单独显示。打开附件预览以检查已保存的图像、音频或视频; 下载按钮可让您随时获取保存的原始文件。

当新记录到达时,Live 会实时更新日志和聊天。在审阅时可以将其暂停, 或者在准备好后使用新事件按钮;后台收集会继续运行。按 Ctrl/Cmd+K 可查找面板操作并搜索日志。

更多工具 → 来源包含观察范围(选定的聊天、Telegram 文件夹或整个 账户)、各类可访问的聊天、带有优先级星标的精选来源、附件 和重新检查设置以及历史快照。私有来源通过对话/ID 选择,不提供公开链接。访问状态描述的是最近一次检查结果,而非永久权限。

筛选来源并勾选其复选框,即可批量启用、暂停或将其标记为优先。 在可用聊天列表中,添加所选项会使用您当前勾选的项; 添加所有匹配项会使用当前的搜索和类型筛选条件。

“聊天”→“联系人”列出了所有已保存消息的联系人;若该聊天已启用联系人资料功能, 点击即可打开该联系人的资料页面,其中包含指向日志记录的链接。

更多工具 → 扩展功能 → 独立见证人会生成只读的见证令牌,显示每个见证人上次检查的时间,并 提供运行独立见证人的命令和选项。

更多工具 → 参数包含工作区中未在其他页面列出的所有限制和节奏: 读取的对话数量、聊天列表的重新读取频率、心跳和检查点 间隔、启动缓冲区、重新检查如何分发请求(首次延迟、每次 ,聊天间隔、已恢复和重新请求的消息),磁盘预留空间,下载的超时和 重试,用户资料的搜索条件(包括您自定义的正则表达式), 通知的大小和频率,快照、ZIP 及浏览器下载限制,以及 Telegram 客户端的超时和重试。每个字段都会显示其范围和默认值;已修改的字段会 被标记,并可逐个或全部恢复。 每次更改都会作为 parameters.changed记录下来,并附带更改前后的数值;观察开始记录会标注 当前生效的数值。数值从下次使用时起生效;客户端超时和重试则从 下次连接时起生效。重新检查间隔、附件类型和大小、证据以及站外副本 间隔仍保留在各自的页面上,其数值可在范围内的任意值,而不仅限于预设值。

顶部栏中的铃铛图标列出了被监控聊天群组中的近期问题和变化;未读项 会持续计数,直至被标记为已读。变化按聊天群组和小时分组显示(“12条已删除, 1条已编辑,0条未找到”),而诸如注销或磁盘空间已满等问题将始终保留在列表中, 无论聊天群组活动多么频繁。

更多工具 → 账户 注册从手机号码字段开始。“继续 ”将直接跳转至 代码输入界面,仅在缺少 API 凭据时才会要求输入。二维码和文件导入是 替代选项卡。已保存的 API 凭据仅在所属工作区内重复使用。 登录界面没有侧边栏、统计数据或设置说明。点击“设置 ”图标可打开 API、代理、存储以及其他账户的控制选项。新建工作区会 首先 进入 初始设置 ;登录后,包含已保存数据源和记录的工作区将打开聊天界面 。 更改路径需要暂停监控,并会取消未完成的登录操作。现有 日志无法在用户不知情的情况下重新绑定到其他 Telegram 账户。

导出功能会检查日志完整性并生成可移植文件。其工作区 ID 可传递给下载命令行工具。每次导出都会固定一个完整的日志前缀;后续 事件将纳入下一次导出。搜索过滤器不会改变包作用域。 详细的签名和覆盖范围信息请参见验证与证据部分。

在“收集器状态”面板中,会显示收集器状态、排队/失败的媒体文件、最旧的待处理媒体文件、可用 磁盘空间、请求暂停情况,以及访问状态未确认的来源。 这些详细信息初始状态为折叠状态,并在“账户”页面中被隐藏。一个设置 卡片会显示下一步操作:连接账户、选择来源或开始监控。 账户列表为加载时的快照; 所选工作区会定期刷新。这并非多进程 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、前台进程或用户代理 提供了 launchd 示例;需单独进行安装验证
Docker/Compose 持久卷,一个工作节点 提供定义和 CI 运行时检查;本地无法使用 Docker
手机浏览器 连接到正在运行的服务器上的受保护控制面板 已测试窄屏 Chromium 布局;数据采集器不支持 iOS/Android 系统

可移植性意味着无需强制使用云服务或构建前端。每个目标系统仍 需要兼容的 Python/加密依赖项、本地磁盘及网络访问权限。请参阅 DEPLOYMENT.md 文件及服务模板。

工作区共享 CPU、内存和事件循环。为实现进程隔离,请使用不同的 实例、端口、数据目录和账户授权。不同实例之间不存在统一的 控制面板。切勿让多个工作进程指向同一个数据库。

启动检查与导出#

在启动预配置环境前,请运行 python start.py --check。若需进行机器可读的检查,请添加 --json 参数,或传入预设的 --data-dir、--host 和 --port 参数。 该命令会在无需登录 Telegram 或创建日志的情况下检查先决条件。 日志验证在应用程序启动时运行,捕获就绪状态将显示 在面板中。端口已被占用可能仅仅是因为已有实例存在。

支持文件系统访问 API(File System Access API)的浏览器会通过可写 流保存导出数据。其他浏览器最多缓冲 128 MiB。若需导出更大容量的 数据,或使用不支持文件流的浏览器,请使用流式 CLI:

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

从“Exports”中添加 --profile ID 以创建子工作区。使用 --url https://server 进行远程访问。仅允许将普通 HTTP 用于回环目标。令牌 从文件中读取并作为标头发送,不会被打印或放入 URL 中。不接受 重定向。现有目标不会被覆盖。 传输失败时将删除其 临时部分文件。报告的 SHA-256 值是传输校验和;请使用可信的指纹/检查点单独验证该签名 ZIP 文件。

备份、恢复与中断#

  1. 暂停监控并干净利落地终止该进程。
  2. 复制整个数据目录:数据库、WAL/SHM(如有)、媒体文件、 credentials.enc、signing.enc、network.enc、保险库密钥/元数据、令牌、 检查点以及所有profiles/目录。
  3. 对于外部密钥模式,请将主密钥单独保存,并保留每个 vault.external.json。生成新密钥无法恢复旧的密钥。
  4. 在目标端停止运行时进行恢复;配置原始密钥、限制 访问权限,并在恢复运行前验证完整性。
  5. 记录停机时间及验证结果。停机时间始终作为记录中的间隔存在; 历史快照则会添加其后的状态。

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:

内容 保护
未设密码的导出文件(默认) 已签名,因此可检测到任何更改;设置密码即可加密导出文件
设有密码的导出文件 如果您设置了密码,生成的导出文件将原样封装为 WinZip AES-256 压缩包,该压缩包可由 7-Zip 和 WinRAR 打开;密码不会被存储(符合证据处理规范)
日志数据库及存储在磁盘上的附件 加密磁盘或卷以及文件夹权限
Telegram 会话与签名密钥 数据目录中已加密(credentials.enc、signing.enc、network.enc)

全量备份是指上述所述的已暂停数据目录,而非导出文件。 两者均应使用受保护的存储空间和经过精心设计的传输机制。临时服务器导出文件存储在每个工作区的 temporary-exports/ 中;已完成的响应会被清理,而中断的导出 文件将在下次启动时被移除,此时该工作区的实例锁处于持有状态。

在连接恢复事件发生后,收集器会从 已保存的更新位置请求缺失的更新。持久化媒体任务和 Telegram 更新位置在重启后仍会保留;参见 证据格式。

容量与保留期限#

默认限制(均可在更多工具→参数中修改):前 1,000 个对话,每张快照 500 条消息 ,4 GiB 未压缩的签名 ZIP 内容(更大的归档文件需要 verify.py --max-gib N 并使用 128 MiB 浏览器备用方案。附件每种类型占用 1–2,000 MiB ,设置路径为更多工具→源→录制→附件。下载 CLI 的默认传输量为 5 GiB。可用磁盘空间可能 是下限。 请为日志、媒体、WAL、临时导出和备份预留空间。 导出操作使用数据卷,而非 Compose 的 512 MiB /tmp 目录。

应测量每秒事件数、队列年龄、媒体字节数和磁盘延迟,而非仅统计 组数。实时交付情况在运行中的收集器上进行测量。 系统不支持自动保留删除。删除日志尾部将使其 与已保留检查点之间的关联失效。

优先复查已经可用:带星标的来源默认每 15 分钟复查一次,其他来源每 6 小时复查一次(参见复查层级)。受密码保护的导出按上文所述工作。限定范围的访问记录在访问与权限中。参见 READINESS.md、LIVE_ACCEPTANCE.md 和 VERIFICATION.md。