# TgWitness · 简体中文 > Documentation edition: 简体中文. Project version: `0.9.1`. Source branch: `main`. This index links the Markdown editions of the public pages. The complete handbook is built from the same page content, including source URLs. Untranslated sections retain the English original; a language edition is not a claim that every section has been translated. - [Project context, installation, measured scale and verification limits](https://phishdestroy.github.io/TgWitness/docs/reference/overview/index.md) - [English project summary](https://phishdestroy.github.io/TgWitness/llms.txt) - [Complete handbook · 简体中文](https://phishdestroy.github.io/TgWitness/zh/llms-full.txt) - [Complete handbook as Markdown · 简体中文](https://phishdestroy.github.io/TgWitness/zh/llms-full.md) - [Source code and release history](https://github.com/phishdestroy/TgWitness) - [Collection modes and evidence levels](https://phishdestroy.github.io/TgWitness/zh/guides/modes.md) - [Published checks and measurements](https://phishdestroy.github.io/TgWitness/docs/validation/index.md) ## Complete documentation map ### Guides - [浏览存档](https://phishdestroy.github.io/TgWitness/zh/docs/archive/index.md): 加载历史记录、搜索已保存记录、审查 AI 来源并连接您的工具。 - [GitHub Actions 捕获](https://phishdestroy.github.io/TgWitness/zh/docs/capture/index.md): 在临时 GitHub runner 上选择 Takeout、常规 API 导出或聊天日志． - [专用账号](https://phishdestroy.github.io/TgWitness/zh/docs/dedicated-account/index.md): 请准备一个单独的 Telegram 账号用于数据采集。 - [几分钟内即可开始使用](https://phishdestroy.github.io/TgWitness/zh/docs/start/index.md): 通过一条命令安装，连接 Telegram 账号，即可在 Windows、Linux 或 macOS 上导出可验证的存档。 - [连接账户](https://phishdestroy.github.io/TgWitness/zh/docs/accounts/index.md): 可通过二维码、电话号码或会话导入连接 Telegram。选择消息来源，并确认新消息已成功记录到您的日志中。 - [选择代理](https://phishdestroy.github.io/TgWitness/zh/docs/proxies/index.md): 维护自动 MTProxy 路由，或使用您自己的代理。选择 IP 模式、备用规则以及外部请求的路由。 - [导出与验证](https://phishdestroy.github.io/TgWitness/zh/docs/exports/index.md): 导出捕获的 Telegram 聊天记录，验证签名，并将日志与独立见证人保留的检查点进行比对。 - [了解证据如何运作](https://phishdestroy.github.io/TgWitness/zh/docs/concepts/index.md): 追踪一条消息从捕获到检查点的全过程。修改一条示例记录，重新计算其 SHA-256 链，并查看保留的检查点会检测到什么。 - [跨所有聊天记录进行调查](https://phishdestroy.github.io/TgWitness/zh/docs/cases/index.md): 在频道、群组、私聊和机器人中开展端到端的 Telegram 调查：包括整个账户的捕获、历史记录、联系人、链接、文件、时间线以及经过验证的证据。 - [创建案件看板](https://phishdestroy.github.io/TgWitness/zh/docs/case-board/index.md): 在私人看板上收集已保存的观察结果、精确标注和操作片段，与团队讨论并提交证据集合。 - [设计报告](https://phishdestroy.github.io/TgWitness/zh/docs/reports/index.md): 选择报告数据、八种设计模板之一及内容，然后预览并导出 HTML、带签名的 PDF 或完整的证据包。 - [准备一份共享副本](https://phishdestroy.github.io/TgWitness/zh/docs/handover/index.md): 选择收件人可接收的记录和字段，检查最终副本，并验证其已签名的清单及源日志边界。 - [管理一组账户](https://phishdestroy.github.io/TgWitness/zh/docs/groups/index.md): 比较群组工作区、查找来源、审查观察时段，并应用共享设置（可针对每个账户设置例外）。 - [确保安全](https://phishdestroy.github.io/TgWitness/zh/docs/security/index.md): 了解会话、密钥和证据的存储位置，哪些数据会离开您的设备，保护措施涵盖哪些内容，以及如何加强系统安全性。 - [分享案例](https://phishdestroy.github.io/TgWitness/zh/docs/access/index.md): 为审查员和分析师提供对选定账户和聊天的访问权限，并设置独立的权限、会话限制和可撤销的令牌。 - [设置 Witness 机器人](https://phishdestroy.github.io/TgWitness/zh/docs/witness/index.md): 通过独立的见证节点（配备专属密钥及只读收集器访问权限），将签名的日志检查点发布至您的 Telegram 频道。 - [保持其运行](https://phishdestroy.github.io/TgWitness/zh/docs/server/index.md): 请在配备持久化存储、私有控制面板访问权限、备份功能以及重启后自动检查机制的服务器上运行 TgWitness。 - [查找问题所在](https://phishdestroy.github.io/TgWitness/zh/docs/troubleshooting/index.md): 请使用针对各问题的正确信号，检查控制面板访问权限、Telegram 连接状态、消息缺失情况、FloodWait 状态以及见证状态。 ### Reference - [秘密聊天：实现与演示](https://phishdestroy.github.io/TgWitness/zh/docs/reference/secret-chats/index.md): 了解独立的秘密聊天实现方式，试用虚构的界面，并审查未解决的缺陷。 - [TgWitness：开始、规模与证据](https://phishdestroy.github.io/TgWitness/zh/docs/reference/overview/index.md): 通过一条命令安装，或在 GitHub Actions 上进行捕获。了解调查选项、已发布的规模以及存档所验证的内容。 - [加载源代码历史记录](https://phishdestroy.github.io/TgWitness/zh/docs/reference/history/index.md): 从已启用的来源加载历史消息，暂停和恢复操作，并验证带签名的进度报告。 - [存档分析](https://phishdestroy.github.io/TgWitness/zh/docs/reference/analysis/index.md): 搜索已保存的消息、审查 AI 输入内容，并保存附有来源参考信息的分析报告。 - [命令行](https://phishdestroy.github.io/TgWitness/zh/docs/reference/cli/index.md): 支持通过脚本和代理进行搜索、阅读上下文、统计活动以及导出已保存的消息，提供 --json 输出格式、稳定的退出代码以及作用域限定的只读令牌。 - [全文搜索](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/index.md): 根据词形、精确短语、域名和 @用户名 查找已保存的消息，按最匹配结果优先排序，索引与签名日志绑定。 - [只读 MCP](https://phishdestroy.github.io/TgWitness/zh/docs/reference/mcp/index.md): 将 MCP 客户端连接到选定的工作区和聊天群组，并授予具有时效性且可撤销的访问权限。 - [本地 OCR 和转录](https://phishdestroy.github.io/TgWitness/zh/docs/reference/media-analysis/index.md): 通过本地工作进程识别捕获的图像和音频；将生成的文本与源文件保持关联。 - [外发 webhook](https://phishdestroy.github.io/TgWitness/zh/docs/reference/webhooks/index.md): 将带 HMAC 签名的指定范围事件发送至 HTTPS 接收端，支持重试并提供投递状态。 - [运营商兼容性通知](https://phishdestroy.github.io/TgWitness/zh/docs/reference/notice/index.md): 关于 Taylor Wessing 及其来源记录的操作员通告。 - [许可协议与架构不兼容声明](https://phishdestroy.github.io/TgWitness/zh/docs/reference/license/index.md): TgWitness 采用 MIT 许可证向所有人开放，并解释了其架构为何与 Taylor Wessing 的工作流程不兼容。 - [快速入门](https://phishdestroy.github.io/TgWitness/zh/docs/reference/quickstart/index.md): 安装和启动 TgWitness 的所有方法：Windows 安装包、Python、Docker 以及综合演示，并附带初步测试。 - [账户与会话格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/index.md): 支持通过手机、二维码或授权密钥登录，可导入 Telethon、Pyrogram 或 Telegram Desktop 的会话数据，并同时管理多个账户。 - [访问与权限](https://phishdestroy.github.io/TgWitness/zh/docs/reference/access/index.md): 设置账户和聊天室的访问权限范围，选择权限类型，限制会话和 IP 地址，并撤销访问权限。 - [连接、代理和数据保护](https://phishdestroy.github.io/TgWitness/zh/docs/reference/connection/index.md): 身份验证、自动代理池、IP 模式、备用策略、外部请求及密钥存储。 - [部署](https://phishdestroy.github.io/TgWitness/zh/docs/reference/deployment/index.md): 可在 Windows、Linux、macOS 或 Docker 环境中将 TgWitness 作为服务运行，通过 HTTPS 访问，并支持备份和更新。 - [数据采集原理](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/index.md): 观察范围、实时更新、复核、附件、用户操作以及“缺口”的含义，逐条记录。 - [工作流程与操作](https://phishdestroy.github.io/TgWitness/zh/docs/reference/operations/index.md): 控制面板的日常操作：模式、监控类别、参数、通知、导出、备份及容量。 - [调查模式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/index.md): 涵盖频道、群组、私聊和机器人的全账户调查，从调查范围到经过验证的案件资料包。 - [“案件看板”参考](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-board/index.md): 书签、精确高亮、操作片段、讨论、范围访问以及“案件看板”所使用的签名注释历史记录。 - [报告配置与验证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-reports/index.md): 报告过滤器、八种设计模板、内容预设、已保存的变更历史记录以及评估结果均包含在已签名的导出文件中。 - [功能与限制](https://phishdestroy.github.io/TgWitness/zh/docs/reference/features/index.md): TgWitness 的当前采集模型、多账户工作流、导出功能及操作边界。 - [证据的运作原理](https://phishdestroy.github.io/TgWitness/zh/docs/reference/how-it-works/index.md): 通过验证者实际使用的精确公式，详细解释了哈希链、签名、检查点和见证人等概念。 - [证据格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/index.md): 签名 ZIP 文件的内容、记录类型、操作收据、用户资料、异地副本及离线验证。 - [独立见证者](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/index.md): 运行一个带有独立密钥和机器人的 Witness 实例，将签名后的检查点发布到频道中，并据此验证导出数据。 - [时间戳](https://phishdestroy.github.io/TgWitness/zh/docs/reference/timestamp/index.md): 签名检查点采用 RFC 3161 时间戳：向认证机构发送的内容以及如何验证响应。 - [安全与数据处理](https://phishdestroy.github.io/TgWitness/zh/docs/reference/security/index.md): 威胁模型、访问模型、静态机密、网络暴露、会话导入以及如何报告漏洞。 - [架构](https://phishdestroy.github.io/TgWitness/zh/docs/reference/architecture/index.md): 收集器、控制面板、日志、工作进程和见证程序的组成部分，以及数据在它们之间如何流动。 - [已测试的内容](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/index.md): Telegram 实时测试、自动化检查、浏览器检查以及尚未经过验证的内容。 - [更新日志](https://phishdestroy.github.io/TgWitness/zh/docs/reference/changelog/index.md): 按版本列出的所有变更，包括尚未发布的变更。 - [面板指南](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/index.md): 面板的每个界面：聊天、日志、来源、导出、扩展功能、保护模式和代码检查。 - [初始设置与配置](https://phishdestroy.github.io/TgWitness/zh/docs/reference/settings/index.md): 设置向导、目标、界面层级、连接路径以及账户组共享的设置。 - [安装、验证和更新](https://phishdestroy.github.io/TgWitness/zh/docs/reference/installation/index.md): 只需一条命令即可完成安装、验证签名和哈希值，以及更新和卸载该工具。 - [存储与恢复](https://phishdestroy.github.io/TgWitness/zh/docs/reference/storage/index.md): 备份、将旧文件移至云端、Object Lock 下的副本以及在新设备上的恢复。 - [账户导出](https://phishdestroy.github.io/TgWitness/zh/docs/reference/account-export/index.md): 导出该账户当前可读取的内容：范围、可恢复的任务、经签名的存档以及已缩减的共享副本。 - [公开展示](https://phishdestroy.github.io/TgWitness/zh/docs/reference/showcase/index.md): 通过有效期有限且可撤销的链接，发布所选公共频道的已保存消息和已签名的快照。 - [高可信度部署](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/index.md): 部署在 Hetzner 或 Phala Cloud 上的全天候密封服务器、网关 DNS 以及第三方可复现的验证机制。 --- # Telegram · 几分钟内即可开始使用 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/start/ 通过一条命令安装，连接 Telegram 账号，即可在 Windows、Linux 或 macOS 上导出可验证的存档。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 只需一条命令即可完成安装，连接 Telegram 账号并选择需要保存的内容。 ## 在您的计算机上安装 安装程序包含 Python 及其依赖项。请从聊天记录导出开始；在需要时添加观察和调查工具。 ### Linux / macOS ``` curl -fsSL https://get.destroy.tools/install.sh | bash ``` ### Windows · PowerShell / CMD ``` powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://get.destroy.tools/install.ps1 | iex" ``` Ubuntu 服务器：以 root 身份运行。桌面版：以普通用户身份运行。 打开安装程序显示的面板地址，并使用其访问密钥。然后连接您的 Telegram 账户。面板密钥与您的 Telegram 授权是分开的。 [安装、签名和更新](https://phishdestroy.github.io/TgWitness/docs/reference/installation/) 说明了下载的构建版本、本地访问和服务器选项。[源代码和 Docker 说明](https://phishdestroy.github.io/TgWitness/docs/reference/quickstart/) 仍可使用。 ## 选择您的第一个任务 1. [通过手机号码、二维码或支持的会话导入方式连接账户](https://phishdestroy.github.io/TgWitness/zh/docs/accounts/)。 2. 选择聊天、文件夹或账户范围。 3. [导出所选历史记录](https://phishdestroy.github.io/TgWitness/docs/reference/account-export/)，或开始观察以记录未来的变更。 4. [使用单独的可信密钥指纹对存档文件](https://phishdestroy.github.io/TgWitness/zh/docs/exports/)进行验证。 ## 使用临时 GitHub Runner [《GitHub Actions 捕获指南》](https://phishdestroy.github.io/TgWitness/docs/capture/)将引导您完成分支、授权、作用域和存档密码的设置。运行完成后，请下载加密结果及其工作流溯源信息。此工作流无需永久收集服务器。 ## 无需注册即可浏览 [打开浏览器演示版](https://phishdestroy.github.io/TgWitness/demo/?lang=zh)，在安装任何软件之前，先浏览虚构的消息、比较编辑内容并检查导出文件。 ![TgWitness 对话视图及示例消息](https://phishdestroy.github.io/TgWitness/assets/chats-dark.png) 一个示例工作区。您的日志将单独创建。 ## 继续调查 对于正在进行的工作，请根据您的案例需求添加所需的来源、文件政策、搜索、报告和共享权限。[启动、扩展与证据；](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) 解释了相关选项及已发布的测量数据。 如需进行服务器安装，请参阅《[保持运行》](https://phishdestroy.github.io/TgWitness/zh/docs/server/)。 --- # 请使用独立账户，切勿使用您的主账户。 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/dedicated-account/ 请准备一个单独的 Telegram 账号用于数据采集。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 连接账户前请先阅读 我们建议您不要使用主账号，这绝非玩笑，而是现实。 主账户 - 使用您自己的应用哈希，99% 的账户都会被注销 - 仅因“信任度低”而导致账号被封的情况屡见不鲜 - 使用你的主账号是一个非常愚蠢的主意 基于公共 API ID/API 哈希对的额外账户 - 已有超过一百万个账户通过这些 API ID/API 哈希对注册 - 这些 API ID/API 哈希对已持续有效超过 5 年 - 任何人都无法通过这些 API 对查看您的任何数据 01 ## 为什么绝对不能使用您的主账号 这是准确的信息。我们清楚地知道这些问题存在哪些隐患。 1. ### 使用您自己的应用哈希，99% 的账户都会被注销 如果使用一个你无权访问的账户登录 my.telegram.org 以获取应用哈希，随后通过该应用哈希发送任何请求，则该账户被注销的概率高达 99%。你可以亲自验证一下。 2. ### 仅因“信任度低”而导致账号被封的情况屡见不鲜 账号被封禁仅仅是因为 Telegram 不信任它们，此类封禁情况十分常见。你也可以自行核实这一点。使用自己的账号确实是个极其愚蠢的主意。 3. ### 已复制的会话密钥可以被撤销 在 Telegram Desktop 和 TgWitness 中同时运行导入的 TData/会话密钥可能会触发 `AUTH_KEY_DUPLICATED` 错误。Telegram 会使该授权失效，因此两个副本都需要重新登录。使用专用账户也无法避免此情况。 请完全退出原始客户端，并在使用其导入的会话期间保持该客户端关闭状态。如需并行使用，请通过手机或二维码登录 TgWitness 以建立独立的授权；其他已单独授权的客户端可保持登录状态。 [请阅读会话导入警告](https://phishdestroy.github.io/TgWitness/demo/guide.html?lang=zh#session-warning) Telegram 文档 - [注销错误：AUTH_KEY_UNREGISTERED、SESSION_REVOKED](https://core.telegram.org/api/errors) - [创建您自己的应用哈希：获取 api_id](https://core.telegram.org/api/obtaining_api_id) 02 ## 为什么 TgWitness 通过公开的应用哈希和应用 ID 对来工作 正因如此，我们基于公开的应用哈希/应用 ID 对构建了 TgWitness。按照我们的逻辑，使用这些对被封禁的可能性较低：已有超过一百万个 Telegram 账户通过这些对注册，且许多不同的程序都通过它们运行。 依我们的逻辑，这比直接使用个人应用哈希更稳妥：这些哈希-ID 对肯定已经存在了 5 年以上。 ### 您自己的新 API ID/API 哈希对 由该账户在 my.telegram.org 上创建。 - 其中约 99% 的账户会被自动注销 - 一个新应用，一个账户 ### 来自池中的公共 API ID/API 哈希对 这与许多程序所使用的 API ID/API hash 对相同。 - 注册账户已超过一百万个 - 多种不同的程序 - 这些 API 对已稳定运行 5 年以上 ### 为什么没有人能通过这些 API 对查看您的任何数据 - #### 该 API 配对是一个名称，而非键 当程序连接或请求登录码时，Telegram 会要求提供 API ID 和 API 哈希。这些信息用于识别应用程序，但不会授予任何账户的访问权限；Telethon 的文档指出，一组 API ID 和 API 哈希可适用于任何手机号码。 - #### 您的会话密钥绝不会离开您的服务器 登录时，您的 TgWitness 与 Telegram 之间会通过迪菲-赫尔曼（Diffie–Hellman）密钥交换生成一个授权密钥；该密钥本身绝不会被发送出去。根据 Telegram 的文档说明：授权后，该密钥将与用户绑定，使用此密钥的每次调用均以该用户身份执行。其他拥有相同密钥对的程序各有自己的密钥，无法使用您的密钥。 - #### 数据传输使用您的密钥进行加密 每个请求和响应均使用会话授权密钥进行加密，而非 API 哈希值。仅知晓 API 哈希值无法解密任何内容。 - #### API ID/API hash 对的所有者无法看到任何内容 Telegram 没有通过 API ID 列出账户、会话或消息的方法。账户所有者只能在 my.telegram.org 上查看其应用设置。 - #### 只有您的账户能看到这是哪个应用 在“设置”→“您自己的账户设备”中，会列出每个会话的应用名称、API ID、设备、IP 地址和日期。除您本人外，任何人都无法查看此列表。 Telegram 文档 - [用户授权：密钥将与用户绑定](https://core.telegram.org/api/auth) - [auth.sendCode: api_id, api_hash](https://core.telegram.org/method/auth.sendCode) - [initConnection](https://core.telegram.org/method/initConnection) - [创建 MTProto 授权密钥](https://core.telegram.org/mtproto/auth_key) - [MTProto 加密](https://core.telegram.org/mtproto/description) - [account.getAuthorizations](https://core.telegram.org/method/account.getAuthorizations) - [Telegram授权（会话）条目包含的内容](https://core.telegram.org/constructor/authorization) - [获取 api_id](https://core.telegram.org/api/obtaining_api_id) - [Telegram 应用的开源代码](https://telegram.org/apps#source-code) 库和讨论帖 - [Telethon：登录 Telegram](https://docs.telethon.dev/en/stable/basic/signing-in.html) - [opentele：官方应用的 API 凭据](https://opentele.readthedocs.io/en/latest/documentation/authorization/api/) - [opentele: TelegramClient](https://opentele.readthedocs.io/en/latest/documentation/telethon/telegramclient/) - [Stack Overflow：是否应将 api_hash 保密？](https://stackoverflow.com/questions/49490818/should-telegram-api-hash-be-kept-secret) ### 其他程序中相同的 API ID/API 哈希对 7 官方 Telegram 应用的 API ID/API 哈希对是公开的，并已集成到许多独立程序和库中： - [opentelePython · src/api.py](https://github.com/anmv/opentele/blob/4df17bd8c443d6452afc5a2d29ec7922fad1a5c3/src/api.py#L575) - Desktop 2040 - Android 6 - Telegram X 21724 - iOS 10840 - macOS 2834 - Web 2496 - [opentele2Rust · opentele2-core/src/api.rs](https://github.com/DedInc/opentele2/blob/7e973bc71cd7a714ad13ac703c0895a90d36a735/crates/opentele2-core/src/api.rs#L641) - Desktop 2040 - Android 6 - Telegram X 21724 - iOS 10840 - macOS 2834 - Web 2496 - [GrampoPython · Grampo/ut/api.py](https://github.com/abbas-bachari/Grampo/blob/00aa662d853c4ac2180432371c5e0d9444bbfe9e/Grampo/ut/api.py#L526) - Desktop 2040 - Android 6 - Telegram X 21724 - iOS 10840 - macOS 2834 - Web 2496 - [tgmanagePython · api/schemas/api_app.py](https://github.com/xdsnich/tgmanage/blob/f67c46be0ab234bd04526a8663d3936bd98a8597/api/schemas/api_app.py#L47) - Android 6 - iOS 8 - Desktop 2040 - macOS 2834 - Telegram X 21724 - Web K 2496 - [LyChatBotTDLib · helpers/tdlib/index.js](https://github.com/LyoSU/LyChatBot/blob/fac0ae5d5f2cddb8a26312014f51c0f6f40ec191/helpers/tdlib/index.js#L11) - macOS 2834 - [hsadasdPython · config.py](https://github.com/herobrinovaleksandr-png/hsadasd/blob/6842c74895038c16e219324fcd07dbe8153f37f0/config.py#L68) - Desktop 2040 - Desktop 17349 - Telegram X 21724 - macOS 2834 - iOS 10840 - Web 2496 - +4 - [blb.teamblb.team/threads/…294](https://blb.team/threads/app-hash-app-id-ofitsial-nykh-kliyentov.294/) - Android 4 · 5 · 6 - iOS 8 - Desktop 2040 - Desktop 17349 - macOS 2834 - Telegram X 21724 一篇列出了官方 Telegram 应用的 API ID/API hash 对的论坛帖子，发布目的是用于注册账户 03 ## 创建额外账户的方法 Telegram 账号需要一个用于接收登录验证码的手机号码。请根据该账号的预期使用时长进行选择。 - 最佳选择 ### 预付费 SIM 卡或 eSIM ******** 有效期有多长 只要您保持余额充足 请注意 最可靠的方法：Telegram 最能接受真实的手机号码。运营商收回的号码会被分配给其他人。 - ### 一款提供虚拟电话号码的应用程序 ******** 有效期有多长 只要该应用保留该手机号码 请注意 Telegram 可能会拒绝虚拟号码、不发送验证码，或立即限制新账户的使用；某些应用会收回未使用的号码。 - ### 租用电话号码 ******** 有效期有多长 关于租赁期限 请注意 当该号码用完后，将分配给下一位客户。 - ### 一次性激活 ******** 有效期有多长 仅需一个登录码 请注意 该号码会立即返回号码池，通常附带之前所有者的使用记录。请务必在进行其他操作之前先设置云端密码。 日后持有该号码的人可以请求登录码。云密码（两步验证）可阻止其登录；若未输入该密码，该账户将归属于该号码的下一任持有者。 Telegram 文档 - [垃圾信息常见问题解答：虚拟号码及其前任所有者](https://telegram.org/faq_spam) - [两步验证](https://core.telegram.org/api/srp) ### 租赁的 +888 号码（Fragment） 部分市场和平台提供通过 Fragment 临时租用 Telegram 官方 +888 号码的服务。 预计价格：每天 20 美元。 - 您可以在 Telegram Web 或 Telegram Desktop 中直接注册账户。 - 您可以删除该号码下的账户并创建新账户。 - 此类账号通常面临较少的反欺诈审查，但并不因此享有豁免权或特殊特权。 该账号不属于您。租赁期满后，所有者可将其收回。请立即设置云密码，且不要将该账号视为长期使用。 自行持有 +888 号码或使用您控制的预付费 SIM 卡仍然更为可靠。 ### 来自交易平台的现成账户 部分交易平台（例如 G2G 或 Z2U）出售现成的 Telegram 账号——包括新账号、老账号或附带会话文件的账号。 - [G2G：Telegram 账号列表](https://www.g2g.com/uk/categories/telegram-accounts) - [Z2U：Telegram 账号列表](https://www.z2u.com/telegram/accounts-5-15140) 切勿使用您的主账号！通过此方式创建的专用账号，仍比将您的主要 Telegram 账号绑定到 TgWitness 更为安全。 #### 购买前的警告 - 这违反了 Telegram 的《服务条款》。 - 许多账号属于批量注册（自动注册）或历史信息不明。 - 部分卖家可能仍持有恢复权限。 - 来自此类市场的账号往往会在后期遭到封禁或限制。 - 请避免使用公开销售账号窃取工具、钓鱼工具或明显为盗取账号的市场平台。 - 从公开销售钓鱼工具、窃取工具、被盗会话或账户的平台上购买账户——即使是标榜为“自动注册”的账户——不仅违反了 Telegram 的《服务条款》，也违反了大多数国家的法律。这可能会导致您的证据日后失效。请谨慎选择。 #### 如果您使用此选项 1. 将该账号视为一次性账号。 2. 请立即结束所有其他会话，设置云密码并更改恢复方式。 3. 请使用来自不同服务商或您自行注册的 2–3 个账户。 **Premium、删除及七天延迟** 如果该账号开通了 Premium 服务，即使有人获得了该手机号码的访问权限，也无法立即删除该账号。您会收到通知，并在账号被删除前有七天的处理时间。 这一点至关重要，因为您的调查工作依赖于该账号：您还有时间准备一个替代账号。 **新账户和 API 凭据** 如果您通过短信服务获取的号码注册了新账户，并从中获取和使用自己的 api_id/api_hash，则该账户将在首次 API 请求或会话授权时被强制注销。在规划调查时请务必牢记这一点。 04 ## 创建账户 从获取手机号码到记录第一条聊天记录。 1. ### 获取电话号码 若账户需长期使用，建议选用预付费 SIM 卡或 eSIM；若仅用于短期任务，则可选择租赁或一次性激活。相关服务如下所示。 2. ### 请使用与主账户不同的账户注册 请在官方 Telegram 应用中，通过另一台设备、模拟器或手机配置文件进行注册，切勿与您的主账户在同一设备上操作。 3. ### 使用云密码保护该账号 请立即设置一个仅用于此处的云密码和恢复邮箱。 4. ### 限制该账号的隐私设置 电话号码：**无人**，通过号码查找我；**我的联系人**、最后上线时间、个人头像和简介：**无人**或**我的联系人**；关闭联系人同步。 5. ### 防止账号自动销毁 请将账户自动销毁时限设置为最长，这样即使 TgWitness 停止运行，您的账户也不会因此丢失。 6. ### 为该账号设置中性的个人资料 不包含您其他账户的姓名、照片、用户名或个人简介，也不包含个人联系人信息。 7. ### 让新账号进行预热 起初，每天只加入几个聊天群。新账号若操之过急，往往会率先受到限制。 8. ### 不与机器人共享任何信息 切勿点击机器人上的“分享电话号码”或“分享位置”按钮。请通过该设备上的 VPN 或代理打开链接和迷你应用。 9. ### 将该账户连接到 TgWitness 在您自己的工作区中，通过**“账户”→“二维码**”进行连接，然后点击**“来源”→“调查模式”**。该应用是您操作的场所，TgWitness 则是记录工具。 Telegram 文档 - [两步验证](https://core.telegram.org/api/srp) - [隐私设置](https://core.telegram.org/api/privacy) - [账户长期闲置时的自动销毁机制](https://core.telegram.org/method/account.setAccountTTL) 05 ## 电话号码服务 以下是可供参考的起始选项。国家/地区、价格以及 Telegram 是否接受特定号码等信息经常变化，因此请在付款前确认。 ### 预付费 SIM 卡和 eSIM 11 - [SMARTYsmarty.co.uk](https://smarty.co.uk) - UK - SIM - [VOXIvoxi.co.uk](https://www.voxi.co.uk) - UK - SIM - [iD Mobileidmobile.co.uk](https://www.idmobile.co.uk) - UK - SIM - [Threethree.co.uk](https://www.three.co.uk) - UK - SIM - [Asda Mobilemobile.asda.com](https://mobile.asda.com) - UK - SIM - [Ultra Mobileultramobile.com](https://www.ultramobile.com) - US - 预付费 PayGo 套餐，价格非常便宜 - [US Mobileusmobile.com](https://www.usmobile.com) - US - 预付费 - [Mint Mobilemintmobile.com](https://www.mintmobile.com) - US - 预付费 - [Tracfonetracfone.com](https://www.tracfone.com) - US - 预付费 - [eSIM Plusesimplus.me](https://esimplus.me) - eSIM - [Numero eSIMnumeroesim.com](https://numeroesim.com) - eSIM ### 提供虚拟电话号码的应用程序 20 - [Google Voicevoice.google.com](https://voice.google.com) - US 仅限美国；注册需提供美国电话号码 - [TextNowtextnow.com](https://www.textnow.com) - US - CA 若未使用该编号，系统将收回该编号 - [TextFreetextfree.us](https://www.textfree.us) - US - [2ndLine2ndline.co](https://www.2ndline.co) - US - CA - [Talkatonetalkatone.com](https://www.talkatone.com) - US - [TextMego-text.me](https://go-text.me) - US - CA - 其他国家 - [textPlustextplus.com](https://textplus.com) [Google Play](https://play.google.com/store/apps/details?id=com.gogii.textplus) - [FreeToneGoogle Play](https://play.google.com/store/apps/details?id=com.textmeinc.freetone) - US [TextMe Up · textmeup.com](https://www.textmeup.com) - [Nextplusnextplus.me](https://nextplus.me) - US - [Dingtonedingtone.me](https://www.dingtone.me) - US - CA - [Burnerburnerapp.com](https://www.burnerapp.com) - US - CA - 付费服务 附带试用期 - [Hushedhushed.com](https://hushed.com) - 许多国家 - 付费服务 低价 - [Sidelinesideline.com](https://www.sideline.com) - US - [MySudomysudo.com](https://mysudo.com) - US - CA - UK - [2NumberGoogle Play](https://play.google.com/store/apps/details?id=com.bpmobile.second.phone) [App Store](https://apps.apple.com/app/id1216135390) - [SLYNUMBERslynumber.com](https://slynumber.com) [Google Play](https://play.google.com/store/apps/details?id=com.dev.slynumber) - [Phonerphonerapp.com](https://phonerapp.com) - [Onoffonoff.app](https://www.onoff.app) - EU 应用程序中的欧洲手机号码 - [Sonetelsonetel.com](https://sonetel.com) - 许多国家 - 免费号码 - [Zadarmazadarma.com](https://zadarma.com) - 许多国家 虚拟电话号码 ### 电话号码租赁和一次性激活 12 租用电话号码可让您在数周或数月内持续使用该号码。一次性激活会生成一个登录验证码：请在注册后立即设置云端密码。 - [OnlineSimonlinesim.io](https://onlinesim.io) - 号码租赁 - 一次性激活 - [SMSPVAsmspva.com](https://smspva.com) - 号码租赁 - 一次性激活 - [5SIM5sim.net](https://5sim.net) - 号码租赁 - 一次性激活 - [SMSPoolsmspool.net](https://www.smspool.net) - 号码租赁 - 一次性激活 - [VAK-SMSvak-sms.com](https://vak-sms.com) - 号码租赁 - 一次性激活 - [TextVerifiedtextverified.com](https://www.textverified.com) - 号码租赁 - 一次性激活 - [JuicySMSjuicysms.com](https://juicysms.com) - 号码租赁 - 一次性激活 - [365SMS365sms.org](https://365sms.org) - 号码租赁 - 一次性激活 - [SIMSMSsimsms.org](https://simsms.org) - 号码租赁 - 一次性激活 - [GrizzlySMSgrizzlysms.com](https://grizzlysms.com) - 一次性激活 - [SMS-MANsms-man.com](https://sms-man.com) - 一次性激活 - [Tiger SMStiger-sms.com](https://tiger-sms.com) - 一次性激活 --- # Telegram · 连接账户 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/accounts/ 可通过二维码、电话号码或会话导入连接 Telegram。选择消息来源，并确认新消息已成功记录到您的日志中。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 一个工作区 = 一个账户、它的日志和它的密钥。 ## 选择登录方式 **账户** → 添加工作区 → 连接设置。请为此使用单独的账户。 - **二维码：**在 Telegram 的“设备”页面扫描并确认。 - **电话号码：**号码、验证码，如有两步验证再输入密码。 - **会话导入：**您自己的会话文件或 Telegram Desktop 数据。 使用内置 API 配置或您自己的 API ID 和 hash。它只用于标识应用，不会让您登录，也不会隐藏任何东西。 **需要先设置代理吗？** 您可以在登录前[选择并测试连接路径](https://phishdestroy.github.io/TgWitness/zh/docs/proxies/)。每个账户都有其专属的连接路径。 ## 选择监控内容 1. 选择您需要的聊天、群组或频道。 2. 检查采集设置，包括媒体。 3. 启动后检查连接和最近活动。 账户必须有访问权限。管理员和成员看到的内容不同，日志显示的是这个账户收到的内容。 整个账户？**来源 → 观察范围 → 调查模式**，检查后点击**保存范围**。完整步骤：[调查整个账户](https://phishdestroy.github.io/TgWitness/zh/docs/cases/)。 ## 检查完整路径 在测试群组中，用另一个账户发送一条消息，编辑它，再删除它。这三个事件都应出现在日志中。然后[导出并验证](https://phishdestroy.github.io/TgWitness/zh/docs/exports/)。 “已连接”表示连接正常。捕获到测试消息才说明事件确实送达。 ## 添加另一个账户 在**账户**中新建工作区，步骤相同。请记下每个账户的密钥指纹，以便日后区分导出。 --- # Telegram · 选择代理 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/proxies/ 维护自动 MTProxy 路由，或使用您自己的代理。选择 IP 模式、备用规则以及外部请求的路由。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 保持账户在线，并由您自己决定它是否可以暴露服务器的 IP。 ## 请先选择 IP 模式 01**隐藏地址** 仅使用代理。如果都不可用，就等待。 02**直接操作作为最后手段** 延迟后直连，一旦有代理可用就切回代理。 03**服务器需位于隧道或 VPN 之后** 可以直连。它不会替您设置或检查 VPN。 路由决定连接方式。IP 模式决定是否允许直接连接。 ## 让池来维护路由 1. **账户 → 设置 → 连接设置**。 2. 选择 IP 模式和**自动 MTProxy**，或固定路由。 3. 保存，然后**测试 Telegram 连接**（登录前也可用）。 4. 开始采集，并给自己发送一条测试消息。 新工作区默认使用自动 MTProxy 并开启**隐藏地址**。代理池拉取四个公共列表，检查服务器，保留好用的，替换失效的。 ## 请使用您自己的代理服务器 SOCKS5、HTTP CONNECT、Telegram 代理链接或运营方目录。切换前请暂停观察。Fake TLS 密钥（`ee`…）不可用。 **轮换、共享和重试设置** **参数 → 自动 MTProxy**：失败阈值、冷却时间、轮换、每个代理的账户数。上限为 1 表示账户宁可等待也不共享。不同的代理仍可能共用同一个出口 IP。 ## 将 Telegram 与外部请求区分开来 MTProxy 只承载 Telegram 流量。时间戳、通知、副本和代码检查走单独的 SOCKS5/HTTP 代理、账户的 SOCKS5/HTTP 路由，或在模式允许时直连。也可以关闭它们。 `TGWITNESS_PROXY_FEED_PROXY` 设置下载列表所用的路由。[见证人](https://phishdestroy.github.io/TgWitness/zh/docs/witness/)有自己的设置。这些都不会影响您的浏览器或系统网络。 更多：[模式和默认值](https://phishdestroy.github.io/TgWitness/zh/docs/reference/connection/#ip-modes)，[谁可以更改路由](https://phishdestroy.github.io/TgWitness/zh/docs/access/)。 --- # Telegram · 导出与验证 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/exports/ 导出捕获的 Telegram 聊天记录，验证签名，并将日志与独立见证人保留的检查点进行比对。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 交给对方可以自行对照您的工作区核查的文件。 保留引用导出带签名的 ZIP 文件收件人验证 不熟悉签名和检查点？[修改一条示例记录](https://phishdestroy.github.io/TgWitness/zh/docs/concepts/#chain)，看看哪项检查能发现它。 想将副本存放在收集者之外的地方？请前往 [S3 设置](https://phishdestroy.github.io/TgWitness/zh/docs/exports/#s3)、[对象锁定](https://phishdestroy.github.io/TgWitness/zh/docs/exports/#s3-retention)或[经过验证的恢复功能](https://phishdestroy.github.io/TgWitness/zh/docs/exports/#s3-restore)。 ## 保留一份值得信赖的参考资料 请把工作区密钥指纹记在采集器以外的地方。采集期间，也请把签名检查点保存在别处，或运行[独立见证人](https://phishdestroy.github.io/TgWitness/zh/docs/witness/)。接收方正是用这些来核对密钥和日志的早期状态。 ## 下载带签名的 ZIP 文件 **导出** → 签名证据 ZIP。其中包含完整日志和签名文件清单。可在 [Report studio](https://phishdestroy.github.io/TgWitness/zh/docs/reports/) 中制作易读的报告，或仅将选定数据作为[移交摘要](https://phishdestroy.github.io/TgWitness/zh/docs/handover/)发送。 HTML、PDF 和 JSON 报告带有各自的封印。CSV 只是工作副本；如需完整性，请使用已验证 ZIP 中的 CSV。 ## 请使用可信的 TgWitness 副本进行验证 在项目环境中，使用您自己的指纹和路径： ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 --checkpoint retained-checkpoint.json ``` 通过时会显示 `key_pinned: true` 和 `checkpoint_checked: true`。请将该输出与存档放在一起。检查点必须位于导出末尾或之前。 ## 使用验证结果 - **文件：**清单绑定它们的哈希，签名绑定日志。任何改动都会暴露。 - **身份：**您保存的指纹证明这就是您预期的密钥。 - **早期状态：**检查点将导出与移交前保存的日志前缀进行比较。 - **覆盖范围：**空缺、获取结果以及“发送 → 编辑 → 删除”测试表明这套配置实际捕获了什么。 详情：[验证能证明什么、不能证明什么](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#verification-scope)。 ## 设置 S3 异地备份 在工作区中打开**导出 → 异地副本**。支持 AWS S3 以及任何兼容 S3 的存储。它会复制日志分段、已保存文件、带时间戳的检查点和已完成的聊天导出，每一项在离开采集器之前都用 `AES-256-GCM` 加密。 在线演示中这些控件可见，但上传已关闭。请只在您自己的安装中输入真实凭据。 [![完整的异地备份配置面板：端点、区域、存储桶、访问密钥、计划任务、对象锁定及恢复密钥控制](https://phishdestroy.github.io/TgWitness/assets/off-site-copy.png)](https://phishdestroy.github.io/TgWitness/assets/off-site-copy.png) 展开后显示包含高级选项的完整面板。未显示任何存储凭据。 | 字段 | 输入内容 | | --- | --- | | 端点 | 存储 URL，不含存储桶路径或凭据。示例：`https://s3.example.invalid`。 | | 地区 | 按服务商要求填写。默认 `us-east-1`。 | | 存储桶 | 一个您有写入权限的现有存储桶。示例：`example-case-backup`。 | | 存储桶中的文件夹 | 前缀，默认 `tgwitness`。其上还会追加每个工作区的前缀。 | | 访问密钥 ID / 秘密访问密钥 | 两者一起填写，保存在保险库中。之后两者都留空即可保留原值。 | | 路径风格的地址 | 开启：`endpoint/bucket`。关闭：`bucket.endpoint`。取决于服务商。 | | 复制间隔 | 1 至 1,440 分钟，默认 5。仅在应用运行时生效。 | | Object Lock 数据保留 | 天数和模式，前提是存储桶支持 Object Lock。填 0 则保留存储桶默认值。 | 1. 创建存储桶，在不勾选**保留异地副本**的情况下填写目标和凭据，点击**保存异地副本**。 2. **测试连接**会上传一个加密的测试对象。 3. **下载加密密钥**，并保存在远离采集器的地方。没有密钥就无法恢复。 4. 勾选**保留异地副本**，保存，然后**立即复制**，或让计划任务运行。 ## 查看数据保留及复制进度 在**更多选项**中选择保留天数以及 `GOVERNANCE` 或 `COMPLIANCE`。TgWitness 会从已上传的对象中读回保留设置并告诉您：已确认、缺失或检查失败。 面板显示上一轮、对象数量、字节数、已复制的日志边界和错误。缺失的本地文件会被报告并在下一轮重试，其余内容继续复制。 上传可走直连、SOCKS5 或 HTTP。如果路由只有 MTProxy，副本会带着错误等待。 ## 请将恢复密钥单独保存 密钥 JSON 包含解密密钥、目标、前缀和密钥指纹。恢复时需要它以及具有读取权限的存储凭据。 更改了端点、存储桶或前缀？请重新下载密钥。新的副本会从新目标开始；旧的聊天导出留在原处。 ## 在另一台机器上恢复并验证 您需要一个可信的 TgWitness 安装、密钥 JSON、只读存储凭据和一个空文件夹： ### Windows PowerShell ``` $env:TGWITNESS_S3_ACCESS_KEY = 'YOUR_READ_ACCESS_KEY' $env:TGWITNESS_S3_SECRET_KEY = 'YOUR_READ_SECRET_KEY' python -m tgwitness.replica restore --key-file tgwitness-replica-key.json --out restored-evidence ``` ### Linux / macOS ``` export TGWITNESS_S3_ACCESS_KEY='YOUR_READ_ACCESS_KEY' export TGWITNESS_S3_SECRET_KEY='YOUR_READ_SECRET_KEY' python -m tgwitness.replica restore --key-file tgwitness-replica-key.json --out restored-evidence ``` 所有内容会先在私有临时文件夹中检查：完整日志、检查点、文件哈希和大小。不安全的路径、相互冲突的分段，或比其检查点更短的日志都会导致失败，此时不会写出任何内容。 成功后您会得到 `events.jsonl`、`media/`、`checkpoints/` 和 `exports/`。请将命令的 JSON 输出与它们放在一起，并与您自己保存的检查点或见证记录进行比较。 --- # Telegram · GitHub Actions 捕获 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/capture/ 在临时 GitHub runner 上选择 Takeout、常规 API 导出或聊天日志． [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 在临时 GitHub runner 上选择 Takeout、常规 API 导出或聊天日志． 请启用 JavaScript 以生成密钥并解密您的存档文件。 **完整引用** [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Independent capture](https://github.com/phishdestroy/TgWitness/blob/main/docs/OPTIONAL-CAPTURE.md) ![Independent capture](https://phishdestroy.github.io/TgWitness/assets/chapter-capture.svg) **Preview available from `main`.** A fork launches a pinned reusable workflow from `phishdestroy/TgWitness`. The workflow exports an account, selected chats or one chat's event journal using a newly created Telegram session, attests the evidence ZIP or multipart manifest, and uploads only recipient-encrypted handoffs. The normal administration panel is not exposed. Choose `client=official_web` to run the [official-client witness](https://github.com/phishdestroy/TgWitness/blob/main/docs/OFFICIAL-WITNESS.md) with guarded Telegram Web controls and video. It requires your own upstream proxy and observes one rendered chat. The default `client=api` retains the full-account export modes described below. The verifier checks the archive against its GitHub attestation, the approved workflow and collector commits, and the signed journal and attachment hashes. The collection process uses pinned upstream code and fresh storage. A reviewer can inspect that code and verify the delivered archive against its recorded run. **On this page** - [User flow](https://phishdestroy.github.io/TgWitness/zh/docs/capture/#user-flow) - [Session time budget](https://phishdestroy.github.io/TgWitness/zh/docs/capture/#session-time-budget) - [Choose this mode or a persistent workspace](https://phishdestroy.github.io/TgWitness/zh/docs/capture/#choose-this-mode-or-a-persistent-workspace) - [What is public, and what must stay private](https://phishdestroy.github.io/TgWitness/zh/docs/capture/#what-is-public-and-what-must-stay-private) - [Troubleshooting](https://phishdestroy.github.io/TgWitness/zh/docs/capture/#troubleshooting) - [Local decryption and verification](https://phishdestroy.github.io/TgWitness/zh/docs/capture/#local-decryption-and-verification) - [How the fork is kept outside the capture process](https://phishdestroy.github.io/TgWitness/zh/docs/capture/#how-the-fork-is-kept-outside-the-capture-process) - [Cryptographic handoff](https://phishdestroy.github.io/TgWitness/zh/docs/capture/#cryptographic-handoff) - [Limits and validation](https://phishdestroy.github.io/TgWitness/zh/docs/capture/#limits-and-validation) - [Maintainer release sequence](https://phishdestroy.github.io/TgWitness/zh/docs/capture/#maintainer-release-sequence) ## User flow The helper explains the five stages and lets you try message or collector substitution on sample data. **Start my capture** opens the wizard. 1. Choose **GitHub Actions capture (preview)** on the project homepage, the workspace login screen, or **Exports → Open capture helper**. You can also open the [official helper](https://phishdestroy.github.io/TgWitness/sealed.html?lang=en) or `tgwitness/static/capture.html` from a trusted checkout in a modern browser. The helper makes no network requests for key or file processing. The helper supports the site's interface languages; the temporary collection panel supports English and Russian. 2. Generate a key and save **sealed-key.json**. This is the only private decryption key. Copy the separate public **recipient** value. Losing the private key loses access to both the connection and the archive. Confirm that you saved it to unlock the next step. If you already have a delivery file, load the saved key and choose **I already have an archive**. 3. Fork TgWitness, enable Actions in the fork, and run **Sealed chat capture**. Paste the public recipient and choose 30, 60, or 120 minutes. Never put a phone number, login code, Telegram password, private key, or session in workflow inputs, commits, issues, or logs. 4. During the run, download **sealed-connection** from Artifacts and unzip it. Load `connection.tgwsealed` in the helper, using the saved private key. The resulting link contains a random access secret in its URL fragment. Keep this link private. The panel removes the fragment and keeps the secret in this tab's session storage; it is not placed in HTTP access logs. 5. Open the connection link. Sign in with a QR code, or with your phone number and the login code. Enter your two-step verification password if Telegram asks for it. The built-in API credential pool is used by default, just like the normal workspace. You may expand the optional custom credentials section and enter both `api_id` and `api_hash` from [my.telegram.org/apps](https://my.telegram.org/apps). Leave both fields empty to use the built-in pool; a partial or malformed pair is rejected. Session imports are not allowed. Choose the export mode and scope. The connection link contains an access secret: keep it private. 6. Choose **Telegram Takeout**, **Regular Telegram API** or **Chat event journal**. For account export, choose all accessible chats or load and select one or more chats, then set dates, chat types, account categories and attachment rules. Check settings and size, optionally save the settings JSON for an independent reviewer, then press **Start capture**. Settings are fixed after starting. Resume works only while this runner exists; finishing early preserves acquired data and records gaps. Deadline expiry after starting produces an explicitly partial archive; expiry before starting or cancellation produces no archive. 7. Wait for **sealed-result**, download and unzip it, and decrypt `delivery.tgwsealed` in the helper. You receive `delivery.zip`, containing `evidence.zip`, `attestation.jsonl`, and instructions. Browser decryption is limited to 256 MiB; larger packages use the streaming local command below. Large results also include `delivery-NNNNNN.tgwsealed` parts; the main `delivery.tgwsealed` then contains `evidence.parts.json` and the attestation. Download every part and assemble locally as described below. 8. End the temporary session in Telegram Settings → Devices if revocation was not confirmed or the runner was killed. Normal completion attempts logout; network failures and forced runner termination prevent an absolute guarantee. The repository must contain the published pinned source and reusable-workflow commits. A local branch alone cannot be invoked by another GitHub repository. ## Session time budget Before collection, **Calculate time and size** estimates the selected history and files from message counts and a bounded sample. The display includes time already spent signing in, estimated collection time and a reserve for packaging. For files, the initial estimate uses 1 MiB/s and a twofold time margin; progress replaces that assumption with the measured rate. Use **Messages only** or select fewer chats when the estimate exceeds the remaining time. Telegram's reported Takeout wait is added to the budget. The collector stops acquisition when the remaining time is needed for packaging, retains acquired data and marks a partial result. A 120-minute session therefore uses its remaining collection window rather than waiting for the deadline before preparing the archive. The display identifies selections whose full size could not be sampled. ## Choose this mode or a persistent workspace | Capture mode | Configurable scope | Difference | | --- | --- | --- | | Telegram Takeout, the default | All accessible cloud chats or selected chats, dates, account categories, media policies and JSON/HTML views | Uses Telegram's official export mechanism; approval or waiting may be required. Takeout can enumerate left channels/groups where Telegram permits it and request additional personal data. | | Regular Telegram API | The same account scope and output choices, subject to methods available through the regular API | Does not initialize Takeout; cannot enumerate left channels/supergroups or fetch Takeout-only personal data. Contacts cover Telegram users rather than the complete saved phone contact list. Rate limits still apply. | | Chat event journal | One selected chat, attachment policies and optional avatars | Captures history and changes observed during this run. Account categories, date filters and Desktop-compatible views do not apply. | All three modes have the same GitHub attestation and encrypted delivery. Takeout is an acquisition method, not a stronger signature. It is never silently replaced by regular API access. JSON/HTML views are generated by TgWitness; they are not Telegram-signed files or guaranteed byte-identical Desktop exports. See the [official Takeout API](https://core.telegram.org/api/takeout). Defaults use Takeout, all accessible chat types including archived chats, all dates, account profile and contacts, compatible JSON and HTML, and file downloads. The initial media budget is 4 GiB, with visible per-type file limits; larger files or exhausted download budgets use server hashes where available. Review these limits before collecting. Hashes cannot reconstruct a file. Optional photos, stories, session metadata and extra personal data remain separate choices. Takeout may require approval in an established Telegram session. Telegram sets the delay; a new login or runner does not bypass it. The maximum capture window is 120 minutes including login and approval, so a large account or long approval wait may not finish. A persistent local export can resume the same session, but does not inherit GitHub attestation. ### Agree and verify the settings After **Check settings and size**, use **Save settings for verification**. Agree the resulting `sealed-export-settings.json` with the reviewer before collection. Changes invalidate the saved assessment. The collector signs the effective settings and their SHA-256, and account-export receipts bind the same options. The verifier reports the actual mode, selection and completeness, and rejects a disagreement between the journal and nested account export. ``` python -m tgwitness.sealed_verify evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness --expected-selection sealed-export-settings.json --require-complete ``` `--expected-selection` rejects a different transport, chat scope, filter or attachment policy. `--require-complete` rejects partial account exports and chat journals, whose overall completeness is not established. Without these flags, verification still checks provenance and integrity while reporting the recorded settings and gaps. A file supplied only with the finished archive cannot establish what was agreed beforehand. A valid signature never turns omitted data into data that was collected, or proves the owner did not edit/delete messages before capture. | Need | Mode | | --- | --- | | Export accessible account data or selected chats during a limited session and give a reviewer an externally attested archive | GitHub Actions capture (preview) | | Observe several chats continuously, manage accounts, search and read a growing archive | Local or Docker workspace | This starts a separate capture with a new login. It does not upload your existing local journal, export the currently open workspace, or reuse its Telegram session. An unfinished cloud capture cannot resume after its runner is destroyed; a new workflow starts a new capture. The workspace's **Exports → Open capture helper** opens the complete wizard inside the panel. The standalone page uses the same wizard, controls and themes. Both keep keys and decryption in your browser. GitHub workflow startup and the temporary Telegram panel open in separate tabs; the wizard tells you when to return. Locking the workspace clears the wizard's in-memory key. Your saved key file remains on your device. ## What is public, and what must stay private Collection runs on a standard GitHub-hosted runner. GitHub, the approved collector and dependencies, the helper page, the browser and the HTTPS tunnel are trusted parts of this setup. The temporary host processes the Telegram session and plaintext messages; the delivered artifacts are encrypted for the recipient. Forking copies project code into your repository. It does **not** export your Telegram account. The recipient workflow input is a public encryption key. Keep `sealed-key.json`, Telegram credentials, login codes, 2FA passwords and the decrypted connection URL out of commits, workflow inputs and public logs. The workflow publishes encrypted connection/result artifacts for one day. Download both in time; GitHub Actions availability, account limits and billing apply. A public fork is not a promise of unlimited free compute. No payment or GitHub access token is entered into the helper. The private decryption key stays in your browser/file. Telegram session material and plaintext observations necessarily exist inside the temporary collector. GitHub and the HTTPS tunnel remain trusted infrastructure. Attestation may make the archive digest and workflow identity public; the archive contents are not placed in the attestation. The attestation timestamp is not a message timestamp. ## Troubleshooting | Symptom | Next step | | --- | --- | | No **Run workflow** button | Open your own fork, enable Actions, and sync it with upstream `main`. Do not edit the approved upstream pins to bypass a failure. | | No `sealed-connection` artifact | Check whether the job started and completed its startup/upload step. Queue, runner, image download, tunnel or repository policy failures can prevent startup. | | Cannot open the connection | Load the saved key for this run, unzip the downloaded artifact and select `connection.tgwsealed`. The runner must still be active. | | History is paused | Check the panel's status and use Resume while the session remains active, or finish with the data already collected. Telegram limits and inaccessible content can leave gaps. | | No `sealed-result` | Cancellation or expiry before starting collection produces no archive. A failed collection, attestation or packaging step also prevents delivery. Inspect the failed step without posting credentials. | | Browser cannot decrypt a large archive | Use the streaming CLI below for packages larger than 256 MiB. A wrong or lost private key cannot decrypt the result. | | Verification rejects the signer | Use a trusted current TgWitness installation and the exact caller `OWNER/REPOSITORY`. Do not accept a replacement policy supplied with the archive. | | Telegram still lists the temporary session | End it in Settings → Devices. Logout can fail and a forcibly terminated workflow may not run cleanup. | Before relying on this preview, try a small chat you control: create a message and attachment, collect them, decrypt the result, run the verifier, check the coverage/media outcomes and confirm Telegram session revocation. Automated checks use a synthetic Telegram client plus a separate real GitHub certificate test; they do not establish live account acceptance. ## Local decryption and verification Use tools from an independently trusted installation, not executable files supplied by an unknown evidence archive: ``` python -m tgwitness.sealed_crypto decrypt delivery.tgwsealed --key sealed-key.json --out delivery.zip # Unzip delivery.zip using your archive manager, then: python -m tgwitness.sealed_verify evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness ``` For multipart delivery, decrypt the main package first and keep its extracted manifest beside every encrypted part, then run: ``` python -m tgwitness.sealed_parts evidence.parts.json --key sealed-key.json --out evidence.zip python -m tgwitness.sealed_verify evidence.parts.json --assembled evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness ``` The manifest is the attested subject and binds every part and the assembled ZIP. Use `--max-gib` to set an appropriate uncompressed verification ceiling for a large archive; the default is 4 GiB. Expected-selection and complete-scope checks also work with multipart delivery. Python 3.11+, the project's dependencies, and a recent GitHub CLI supporting `--signer-digest` and `--deny-self-hosted-runners` are required. A CLI key generator is also available: `python -m tgwitness.sealed_crypto keygen sealed-key.json`. The verifier uses `tgwitness/sealed_policy.json` from the trusted installation. It checks the caller repository, upstream signer workflow, approved signer commit, hosted runner requirement, complete ZIP digest, internal journal and attachment integrity, fresh account-key origin, and expected collector commit. It displays history and media outcomes instead of implying all data was saved. An empty approved-release list fails closed. Updating the policy is an explicit trust decision; never accept an archive's own proposed policy automatically. For offline use, obtain trusted roots ahead of time from a trusted environment: ``` gh attestation trusted-root > trusted_root.jsonl python -m tgwitness.sealed_verify evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness --trusted-root trusted_root.jsonl ``` The timestamp of the attestation concerns the archive's commitment. It does not authenticate message timestamps or the collector's wall clock. See [GitHub's verification options](https://cli.github.com/manual/gh_attestation_verify). ## How the fork is kept outside the capture process The caller contains a job-level reference to the upstream reusable workflow at a full commit SHA. That workflow explicitly checks out **the upstream repository at a fixed collector SHA**. A default `actions/checkout` in a reusable workflow would check out the caller and is intentionally not used. The workflow does not restore caller caches, consume caller artifacts, execute caller files, or accept source/image URLs, shell commands, prepared ZIP files, or hashes to sign. It accepts a bounded public recipient and session duration. Actions, the Python base image, and cloudflared are pinned by immutable digests; Python dependencies use the existing hash-locked requirements. The image is built from the trusted source without a cache. The collector runs as a non-root user with a read-only image, dropped Linux capabilities, resource limits, and no Docker socket or GitHub-token environment. Its only mounts are fresh configuration, workspace, and output directories. The restricted FastAPI application exposes login, dialogs, configurable account or chat collection, status, resume, finish, and cancellation. There is no plaintext download route, general administration route, import route, or signing endpoint. The supervisor stops the network-facing containers before the attest action reads the final fixed `evidence.zip` or `evidence.parts.json`. The packaging container has no network. The upload steps name only `connection.tgwsealed` and `delivery*.tgwsealed`; neither plaintext evidence nor Telegram credentials are uploaded as artifacts. Cleanup removes the private directories and containers, with no claim of physical disk erasure. Artifact retention is one day; download before expiry. A fork owner can replace the caller or create a different signed file. The strict verifier must reject the resulting **different signer workflow/digest**. This construction still depends on the absence of exploitable bugs in approved code and on the integrity of GitHub's runner and signing infrastructure. ## Cryptographic handoff Each recipient key is RSA-3072 (RSA-4096 imports also accepted), exponent 65537. Each envelope has a fresh random AES-256 key and 96-bit nonce. RSA-OAEP with SHA-256/MGF1-SHA256 wraps the AES key. AES-GCM with a 128-bit tag authenticates the complete prefix and payload. The public recipient is DER SPKI in base64; the private key file contains DER PKCS8 in base64. Envelope bytes are `TGWSEAL1\n`, a big-endian uint32 JSON-header length, the header, ciphertext, and a 16-byte GCM tag. The header has exactly `algorithm`, `key`, and `nonce`; algorithm is `RSA-OAEP-256+A256GCM`. The complete prefix through the header is GCM additional authenticated data. Header size is bounded at 8192 bytes. The CLI streams payloads up to 8 GiB and authenticates before installing the requested output; it refuses overwriting an existing destination. This is a project-specific envelope around standard cryptographic primitives, not an independently audited encryption format. The original evidence bytes are attested **before** placing the evidence and attestation in the encrypted outer package. This avoids a circular dependency between the archive's hash and a certificate included inside that same archive. For public repositories, attestation metadata (repository, workflow, commit, artifact name and digest) is public. Never put chat names in public metadata. ## Limits and validation This mode uses the signed journal and account-export engine. Secret Chats, deleted history from before collection and data inaccessible to the account are excluded. Private cloud chats are eligible when selected. The chat picker is capped at 20,000 dialogs; account export discovers its own inventory. Missing data, failed files and unfinished tasks are recorded. Attachment limits and runner disk/time limits still apply. Large delivery uses encrypted parts instead of a fixed 4 GiB delivery cutoff. Completion means the frozen selected tasks finished, not that every historical Telegram record exists in the archive. The chat journal can also observe live updates; neither mode is an atomic snapshot. Generated screenshots and screen recordings are not part of this mode. Tests cover synthetic fresh login, scope isolation, media, cancellation, partial deadline completion, failed logout, forbidden API paths and fields, preloaded workspace rejection, wrong-key and tamper rejection, required verifier flags, and browser/Python encryption interoperability. The browser acceptance test uses a plainly labelled mock attestation; it is not a real Sigstore test. Real hosted-runner, Docker, GitHub attestation, and live Telegram acceptance must be reported separately from local synthetic checks. [GitHub Actions terms](https://docs.github.com/en/site-policy/github-terms/github-terms-for-additional-products-and-features#actions) restrict use of hosted runners to the software project's lifecycle. A fork does not remove these restrictions; this preview must not be marketed as unrestricted free production hosting. [Cloudflare Quick Tunnels](https://developers.cloudflare.com/tunnel/get-started/quick-tunnels/) are also intended for testing and development. The helper/workflows are suitable for evaluating this feature; production service eligibility remains a separate deployment requirement. ## Maintainer release sequence 1. Commit and review the collector, supervisor, container definition and tests. 2. Pin that collector commit in `sealed-collector.yml`, then commit/review the reusable workflow. Never silently derive the checkout from the caller SHA. 3. Pin the reusable workflow commit in `sealed-witness.yml` and add its workflow/collector SHA pair to `sealed_policy.json` in a trusted release. 4. Publish all referenced commits and the helper, then test an independent fork and the real GitHub certificate. Do not squash away commits referenced by these pins unless the references are regenerated and published again. See [reusable workflows and attestations](https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/increase-security-rating) for the distinction between the caller repository and the upstream signer. --- # Telegram · 跨所有聊天记录进行调查 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/cases/ 在频道、群组、私聊和机器人中开展端到端的 Telegram 调查：包括整个账户的捕获、历史记录、联系人、链接、文件、时间线以及经过验证的证据。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 一个横跨频道、群组、私聊和机器人的完整案件：采集、串联线索、重建时间线、移交。 一个虚构事件，从头到尾。采集、搜索和人员档案找到记录，[Case Board](https://phishdestroy.github.io/TgWitness/zh/docs/case-board/) 整理它们，[Report studio](https://phishdestroy.github.io/TgWitness/zh/docs/reports/) 呈现它们。 已处理案例 / 支付目的地变更 ### 一起事件。四段对话。一条需要还原的线索。 一条频道帖子指向一个机器人。一个群组在讨论新的付款链接，机器人也显示了它。帖子被编辑，私聊中重复了该链接，一条群消息消失了。 每个版本是由谁发布的？该链接出现在哪里？哪个文件被保留下来了？有哪些变化，以及何时发生的？ 历史加载、AI、MCP、OCR 和 webhook：[使用存档](https://phishdestroy.github.io/TgWitness/zh/docs/archive/)。 ## 1. 确保覆盖整个账户 整个账户范围仅用于专用账户。主账户只用选定的聊天或一个文件夹。 1. 在独立工作区中[连接账户](https://phishdestroy.github.io/TgWitness/zh/docs/accounts/)。记下案件编号、账户 ID、工作区和密钥指纹。 2. **来源 → 观察范围 → 调查模式**：**整个账户**、全部四种来源类型、**自身操作**。每个新聊天都会保存其资料和最近 **200 条可见消息**。点击**保存范围**并确认。 3. **加载聊天**并与账户的聊天列表比较。上限为 1,000 个对话（在**参数 → 从账户列表读取的聊天**中最多可设为 20,000）；超出上限的聊天在变得活跃后才会出现。 4. **记录设置** → **所有可见活动**，检查附件限制和磁盘空间。启动后，用一条消息、一次编辑和一次删除进行测试。 频道群组私聊机器人 一个账户 / 一把签名密钥**所有选定的、账户可见的活动 → 整合为一本日志** 消息 · 编辑 · 删除通知 · 可见反应 · 成员活动 · 自身操作 “整个账户”指该账户能打开的每个聊天，减去排除项。不含私密聊天。新聊天出现时即加入；旧历史不会自动下载。 ## 2. 获取历史记录并保存文件 创建一个 Case Board 集合，为重要内容添加书签。维护一份来源登记表：聊天 ID、标题、账户、角色、实时捕获开始时间、历史结果、媒体结果、空缺。 | 需求 | 面板中的操作 | 功能介绍 | | --- | --- | --- | | 已启用聊天记录的历史 | 来源 → 加载完整历史记录 | 可用的历史消息将进入工作区日志，支持暂停/恢复功能，并生成带签名的进度报告。[历史记录指南](https://phishdestroy.github.io/TgWitness/zh/docs/reference/history/)。 | | 日志中的现有聊天记录 | 来源 → 记录设置 → 历史快照 | 最近的消息作为签名记录。默认 500 条，在**参数 → 最大历史快照**中最多可设为 10,000。 | | 某次聊天的当前可见完整历史记录 | 导出完整聊天记录 → 导出完整聊天记录，或 聊天 → 导出聊天记录 | 每个聊天一个独立的签名包，包含 `chat.json` 和 `chat.html`。 | | 新聊天出现时的上下文 | 监控范围 → 当出现新的聊天或机器人时 | 它的资料和最多 1,000 条最近消息（调查模式下为 200 条）。不适用于已有的聊天。 | | 附件字节数 | 下载可见附件 + 各类附件的限制 | 查找带 SHA-256 和大小的 `media.saved`。排队中、已跳过或失败都表示未保存。 | 聊天导出不会进入日志或人员档案。要在 TgWitness 内搜索旧历史，请使用**加载完整历史记录**或快照。 这里是：频道、群组、机器人聊天和私聊，以及发票文件及其哈希。捕获前已删除的内容已经没有了。 ## 3. 记录不断发展的对话以及您自身的行动 保持运行。将热点聊天加星标作为优先，在**记录设置 → 重新检查**中调整重新检查，并留意 `recheck.completed`、FloodWait 和媒体结果。 **聊天 → 个人资料 → 立即保存个人资料**会保存聊天的简介、机器人命令和其他元数据。 **作为案件调查的一部分，关注机器人或接受邀请** 1. **聊天 → 打开 Telegram 链接**，先保存预览。链接和预览会成为签名记录。 2. 如有需要，**加入 / 打开并观察**会加入聊天或用启动参数启动机器人。 3. 要记录某个操作，请在面板中回复或使用**按下按钮**。您会得到 `interaction.requested` 和 `interaction.result` 以及机器人的回答。 这些是真实操作。在其他应用中按下的按钮不可见，只能看到机器人的回复。不支持网页应用、付款或电话/位置。 ## 4. 追踪聊天记录中的人员、链接和文件 1. **日志**、**所有来源**，搜索短语、域名或用户名。打开结果并**添加到案板**。 2. **聊天 → 联系人 → 开启个人资料**，选择一个人：名称历史、回复、活动、**还出现在……**、链接、钱包、电话。打开被引用的记录。 3. 在其他聊天中追踪同一个数字用户 ID。相同的名字、钱包或头像只是线索，不是证据。 4. 比较文件哈希。SHA-256 相同 = 字节相同。是谁分享的则是另一个问题。 案例地图 / 追踪引用虚构案例 · 非实时图表 频道 / 公告**原文 → 编辑后的目标文本** 记录 #101、#188 消息 #84 · 未标注发件人 组 / 运营**用户 71001 发布了新链接** 记录 #146 · 消息 #309 已保存文件收据 #151 机器人 / 订单对话**一个按钮指向该目标页面** 记录 #173 · 消息 #12 “返回”按钮的元数据 私密 / 后续**用户 71001 重复了收件人信息** 记录 #205 · 消息 #922 已保存文件收据 #209 四个聊天记录提供了不同的观察结果。请追踪每条连接的源记录；该频道帖子未标注发件人。 本操作指南中的数字 ID 和记录引用均为虚构。此说明图展示了如何将搜索结果、个人资料和已检查记录相互关联；“案件看板”存储相应的卡片和来源引用。 | 连接 | 辅助观察 | 保留结论 | | --- | --- | --- | | 同一 Telegram 账号 | 用户 ID 71001 所在的群组 #146 和私聊 #205 | 两个聊天中的发送者 ID 相同。这个人现实中是谁是另一个问题。 | | 重复的目标 | `pay.example.invalid/new` 在 #146，按钮元数据 #173，编辑后的帖子 #188 和 #205 | 同一个链接出现在四个地方。谁控制它需要其他来源。 | | 相同文件字节数 | 已完成的媒体收据 #151 和 #209 中 SHA-256 值完全一致 | 两个文件逐字节相同。 | 档案只包含在*此工作区*中发过言的人，不是成员列表。每个事实的引用数：**参数 → 每个事实引用的记录**。 ## 5. 还原事件序列并标注缺失部分 先在**聊天**中查看版本，再到**日志**中选择**所有来源** + **编辑**、**删除**、**覆盖**。时间线中写上两个时间：Telegram 的日期和被观察到的时间。 1. 09:00 · #101**捕获的频道帖子** 保留了原始目标。 2. 09:12 · #146 / #151**群组提供了一个不同的链接** 用户 71001 发布了该内容；附件下载已完成。 3. 09:16 · #173**机器人显示相同的目标地址** 保存的键盘元数据中包含该链接。 4. 09:20 · #188**频道公告变更** 原始内容和编辑后的内容均予以保留。 5. 09:24 · #205 / #209**私下跟进时再次强调这一点** 保存的附件与 #151 具有相同的完整 SHA-256 值。 6. 09:28 · #231**群组删除通知已发送** 先前的观察结果依然成立：既未提供删除者信息，也未提供确切的删除时间。 示例性的观察时间及参考信息。其他日志记录发生在这些条目之间。 日志顺序是到达顺序，不一定是发生顺序。请将实时记录、快照、恢复的消息、删除和“重新检查时缺失”分开，并将每个空缺标记为未知。 ## 6. 将此案例扩展至其他收集账户 每个账户一个工作区，步骤相同。记下每个账户的角色和指纹。消息编号按账户计算，所以务必注明是哪个工作区和聊天。 [账户组](https://phishdestroy.github.io/TgWitness/zh/docs/groups/)显示状态、共享设置并一起导出所有账户，每个账户仍有自己的日志和密钥。跨账户时间线需要您在笔记中自己整理。 案件周期很长？请添加[独立见证人](https://phishdestroy.github.io/TgWitness/zh/docs/witness/)，并测试每个账户实际能捕获什么。 ## 7. 提交可核查的案件资料包 每个工作区的签名 ZIP（始终是完整日志，筛选不影响），以及人员档案、聊天导出和文件。 ``` CASE-001/ # assembled by the analyst case-notes.md # question, findings, alternative explanations sources.csv # every chat, role, acquisition result and gap timeline.csv # account + chat + message + seq + both times workspace-A/ evidence.zip # complete signed observation journal retained-checkpoint.json profiles-operations.json # separately signed people profiles history-channel.zip # signed current-history export history-group.zip verification.txt workspace-B/ # separate journal and trusted fingerprint witness/ # retained checks, journal and signed posts SHA256SUMS # hashes of the delivered files ``` 请单独发送指纹。每份都对照它自己的工作区验证： ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 --checkpoint retained-checkpoint.json python -m tgwitness.verify profiles-operations.json --fingerprint TRUSTED_PUBLIC_KEY_SHA256 --evidence evidence.zip python -m tgwitness.verify history-channel.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 ``` 将验证工具的输出、原件、覆盖范围和移交记录与您的发现放在一起。在 Report studio 中撰写报告。如果接收方需要的更少，请制作[精简移交](https://phishdestroy.github.io/TgWitness/zh/docs/handover/)。 --- # Telegram · 创建案件看板 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/case-board/ 在私人看板上收集已保存的观察结果、精确标注和操作片段，与团队讨论并提交证据集合。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 把保存的消息变成团队一起处理的案件。 书签、精确引文、切片和讨论，每一项都链接到来源。每次更改都是一个签名修订。 ## 从消息到案件卡片 1. **调查 → 案件看板**（标准或专家模式）。为案件创建一个集合。 2. 在**日志**或聊天中点击**添加到案板**（或按 **B**）。卡片会进入收件箱，给它起个标题再移动。 3. 在消息中选中文本，**突出显示 → 板**会保存精确引文和版本。写下它为什么重要。 4. 讨论、设置状态，需要时随时跳回来源。**演示**带团队逐项浏览。 ### 请点击一个已更改的支付链接 综合示例 · 本地化说明 1. **捕获。**打开已保存的观察记录 #142 及其消息版本。 2. **添加书签。**将引文、来源参考信息和您的问题保存到卡片中。 3. **审核。**添加团队评论并将卡片移至“审核”状态。 4. **演示。**逐步演示采集过程，并打开引用的源上下文。 #### 已保存的观察记录 #142 “请使用新的支付链接。” 操作聊天 · 第 38 条消息 · 观察时间 09:12 UTC #### 卡片：更改了目标位置 > 请使用新的支付链接。 问题：哪个目标在早期版本中出现过？ #### 团队审核 分析师：请与观察记录 #101 进行对比。 状态：审核 · 保留修订版本 #### 源文上下文 卡片 → 已保存版本 → 早期观察记录 注释与 Telegram 观察记录仍可分别识别。 ## 一次性保存一个有用的范围 按住 Shift 点击两条消息进行**中间切片**，使用**按时间切片**，或保存当前日志筛选条件。**显示自书签添加以来的记录**会显示后来进入的内容。 时间切片使用观察时间；消息 ID 切片会跟随这些消息的变化。 ## 为每位同事分配相应的角色 **审核员**阅读，**分析师**添加卡片和评论，**操作员**还管理集合和决定。聊天权限同样适用于卡片。 ## 将工作成果整理成可交付成果 切片可导出为签名 JSON 或 CSV。报告可以包含书签、切片和评论，在 [Report studio](https://phishdestroy.github.io/TgWitness/zh/docs/reports/) 中设置。对于受限的接收方，请使用[移交](https://phishdestroy.github.io/TgWitness/zh/docs/handover/)。 详情：[Case Board 参考](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-board/)。 --- # Telegram · 设计报告 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reports/ 选择报告数据、八种设计模板之一及内容，然后预览并导出 HTML、带签名的 PDF 或完整的证据包。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 让读者从案件问题直接到达保存的记录。 Report studio 汇总您挑选的数据、变更历史、图表和您的发现。八种设计，HTML 和原生 PDF。每份 HTML、PDF 和 JSON 报告都用您的密钥封印。 ## 三步生成报告 1. **导出 → 配置和预览 → 数据**：整个工作区，或选择聊天、作者、日期（UTC，即 TgWitness 看到记录的时间）和记录类型。 2. **设计与内容**：选择设计和要包含的内容：图表、参与者、聊天记录、变更、Case Board 条目、您的案件详情和笔记。 3. **预览**：检查数量、活动、样本和缺失的 ID 范围。保存，然后下载所需格式。 ### 为读者整理相同的保存材料 合成示例 · 示意图布局，并非生成的报告 1. **选择。**为该案件选择两个聊天记录及观察时间段。 2. **撰写内容。**选择布局，并选定能回答该问题的章节。 3. **预览。**请核对选定字数及保存的“修改前”与“修改后”文本。 4. **验证。**生成最终文件，并将其签名与可信工作区的指纹进行比对。 #### 选定要点 2 次聊天 · 1 天观察期 消息、编辑及删除通知 #### 报告结构 ##### 更改了付款目的地 案件问题 → 范围 → 调查结果 → 记录引用 **消息背景** 观察项 #142：“请使用新的支付链接。” **已保存的更改** 译前：old.example.invalid → 译后：new.example.invalid #### 审阅选定内容 18 条意见 · 2 次保存的编辑 发送、编辑和查看时间各有独立的标签。 #### 最终交付物 签名 PDF + 签名 JSON，或包含可读报告的签名 ZIP 文件 接收方需核对文件及可信指纹。 ## 选择阅读风格 **Classic, Editorial, Briefing, Analytics, Technical, Overview, Reading series, and Ledger & margin**：相同的记录，不同的外观。切换时保留您的选择和笔记。可用 25 种语言中的任意一种。 PDF 使用内置字体生成，无需浏览器。中文、日文和韩文需要服务器上有 Noto Sans CJK 之类的字体（系统级或位于 `TGWITNESS_FONT_DIR`），否则只能得到 HTML 和 JSON。 ## 结合上下文阅读变更内容 编辑显示前后对比，删除显示最后保存的版本。回复、转发、表情回应、按钮和附件都保留其引用。 设计预览使用前 50,000 条记录，数据预览精确统计全部内容。要查看最终页面布局，请生成 PDF。 ## 请审慎选择受众版本 筛选只影响报告，证据 ZIP 仍包含完整日志和文件。如果接收方应得到更少，请使用[精简移交](https://phishdestroy.github.io/TgWitness/zh/docs/handover/)。更多：[报告内容](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-reports/)，[验证导出](https://phishdestroy.github.io/TgWitness/zh/docs/exports/)。 --- # Telegram · 准备一份共享副本 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/handover/ 选择收件人可接收的记录和字段，检查最终副本，并验证其已签名的清单及源日志边界。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 只分享需要的内容，原件保持不变。 移交是一份独立的签名摘要：选择聊天和人员，隐藏身份或文本，选择文件和团队笔记。清单记录了保留、裁剪和排除的内容。 ## 准备收件人的数据提取文件 1. **导出 → 移交提取**：写明用途，选择聊天和时间段，如需具名人员则**加载所选聊天记录中的人员**。 2. 其他所有人：使用化名、排除，或按记录原样。文本和文件是分开的开关；电话和电子邮件可以遮蔽。 3. Case Board：不包含、书签和切片，或带评论的卡片。团队成员姓名可替换为别名。 4. **下载移交摘要**，打开、验证，并在发送前通读一遍。 ### 一份正本，一份经授权的共享副本 合成示例 · 仅用于说明身份 1. **选择。**包含案件聊天记录，并标明该摘录涉及的对象。 2. **最小化。**选择其他参与者在共享副本中的显示方式。 3. **检查。**在发送生成的存档文件之前，请先打开其报告和记录进行**检查**。 4. **分享。**提交经核对的译文，并单独提供其可信指纹。 #### 原始观察 Nora · 用户 71002 “我已收到修订后的链接。” 源日志会保留此保存的观察记录。 #### 收件人副本 按记录显示：Nora · 用户 71002 · “我已收到修订后的链接。” 化名：P01 · “我已收到修订后的链接。” 省略：此参与者的消息未包含在译文中。 #### 检查实际文件 请阅读 report.html 和 records.jsonl 文件。 请核对身份信息、文本、附件及可选的团队评论。 #### 已签名的摘录 选定内容 + 文件哈希值 + 签名清单 一个与源日志边界关联的独立包 ## 综合运用各项控件 | 控制 | 对文案的影响 | | --- | --- | | 人员 | 选定的人员保留姓名；其他人使用化名或被排除。 | | 文本 | 全部文本、仅选定人员和您账户的文本，或不包含。 | | 文件 | 选定人员和您账户的文件、全部显示的文件，或不包含。 | | 案件看板 | 不包含、书签和切片，或带讨论的卡片。 | 请也读一读文本和文件：化名不会删除写在消息或附件中的名字。如果选定的文件缺失，请恢复它或排除附件。 ## 确保译文内容可独立核查 ``` python -m tgwitness.verify handover.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 ``` 原始存档和检查点请自己保留。接收方无需获得整个工作区就能验证其副本。设计：[Report studio](https://phishdestroy.github.io/TgWitness/zh/docs/reports/)。可信参照：[导出验证](https://phishdestroy.github.io/TgWitness/zh/docs/exports/)。 --- # Telegram · 管理一组账户 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/groups/ 比较群组工作区、查找来源、审查观察时段，并应用共享设置（可针对每个账户设置例外）。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 同时运行多个账户，每个账户仍有自己的记录和密钥。 账户组将连接状态、启动/暂停、共享设置和导出放在同一个界面上。多个账户处理同一案件时很方便。 ## 打开群组概览 在**账户**中打开账户组。每个账户显示其状态、路由、延迟和最后保存的消息。**需关注**列出出问题的账户，**修复**直接带您过去。 **全部开始** / **全部暂停**会先询问再执行。**组设置**是共享的，但账户自己的值会一直保留，直到您替换它们。 ### 审查群组内的路线变更 合成示例 · 说明性检查及结果 1. **选择。**选择群组并查看哪些账户将发生变更。 2. **准备工作。**当需要保持独立时，请保留账户自身的路径。 3. **检查。**测试建议的连接并检查测量结果。 4. **提交。**保存前请重新检查，并审查每个账户的处理结果。 #### 案件团队 频道采集器 · 群组采集器 · 参考账户 3 个独立的工作区 #### 已审核内容 2 个账户采用建议的流程。 参考账户保持其独立路径。 #### 准备工作检查 频道采集器：Telegram传输时延 84 毫秒 群组采集器：Telegram传输时长 91 毫秒 这些数字是示例中的虚构数据。 #### 应用结果 频道采集器：已保存，观察已恢复。 群组收集器：重新检查失败，已恢复先前设置。 参考账户：保留原有路径。 ## 在流程中增加一个审核步骤 1. **更改群组路由**，选择类型和设置。 2. **审查选择**：查看哪些账户会变更，哪些有自己的路由。 3. **准备并检查**会测试新的 Telegram 连接，并在可能时测试出口 IP。 4. **应用已检查的连接**，并查看每个结果。正在运行的账户继续运行，空闲的保持空闲。 延迟是建立 Telegram 连接的时间，出口 IP 是检查时路由显示的地址。结果可能因账户而异。 ## 使用重叠访问权限 **多个账户可见的聊天**列出共享来源及其覆盖范围。频道和超级群组可以通过**用 … 个账户导出**由多个账户同时导出。私聊和普通群组不行，它们的消息编号按账户计算。 ## 将群组导出为包 **导出组**会生成一个 ZIP，包含每个账户的签名导出及其签名列表。每份导出都保留自己的指纹用于验证。合并的时间线仍需您自己整理。 下一步：[报告](https://phishdestroy.github.io/TgWitness/zh/docs/reports/)，[Case Board](https://phishdestroy.github.io/TgWitness/zh/docs/case-board/)，[验证导出](https://phishdestroy.github.io/TgWitness/zh/docs/exports/)。 --- # Telegram · 了解证据如何运作 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/concepts/ 追踪一条消息从捕获到检查点的全过程。修改一条示例记录，重新计算其 SHA-256 链，并查看保留的检查点会检测到什么。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 消息会变。您对所见内容的记录不应改变，而且任何人都应能核查这一点。 下面是两个小实验。消息是虚构的，一切都在您的浏览器中运行，不会发送到 Telegram。 ## 从聊天记录导出到可验证的记录 [Telegram Desktop 导出](https://telegram.org/blog/export-and-more)将当前可见的历史保存为 HTML 或 JSON。TgWitness 增加了持续的变更日志、每条记录的签名，以及他人可以对照的检查点。 | 任务 | Telegram Desktop 导出 | TgWitness | | --- | --- | --- | | 阅读已保存的对话 | HTML 或 JSON 格式，含选定媒体文件 | 已保存的聊天记录、可搜索的日志和离线报告 | | 跟踪随时间的变化 | 导出时可用的历史记录 | 旧版本、后续编辑和删除，全部保留 | | 移交后检查文件 | 标准的 HTML/JSON 导出文件未签名 | 签名清单、签名记录和封印报告，用可信密钥核查 | | 与先前保留的状态进行比较 | 请保留一份单独的参考副本或哈希值 | 已签名的检查点、独立的见证文件以及可选的外部时间戳 | 本对比基于截至 2026 年 11 月 2 日的 [Telegram Desktop 导出代码](https://github.com/telegramdesktop/tdesktop/tree/768d47cda6c7f447c10a25d1f363279493a90ed7/Telegram/SourceFiles/export/output)。 ## 一条消息，三点观察 一条新消息、一次编辑和一次删除会变成三条独立的记录。编辑不会覆盖第一条，删除也不会抹掉它。 01 / 消息流转示例流程 Telegram delivers an update to the collector, which appends a journal record. · Telegram · 收集器 · 日志 · 更新 → · 追加 → 当前聊天视图 消息 #42 消息已删除 该消息已从聊天界面中消失。 观察日志 3 条记录 1. 01 `message.new` 10:00 见面 ✓ 2. 02 `message.edited` 11:00 见面 ✓ 3. 03 `message.deleted` 关于 #42 的删除通知 ✓ 所有三条已接收的记录均保留在日志中。 针对已选定来源的简化路径。操作记录也会同步到真实的日志中。捕获内容取决于该账户的可见范围以及 Telegram 实际发送的内容。 Telegram 不会告诉您是谁删除了消息，也不会告诉确切时间。TgWitness 将这些字段留空，而不是去猜测。 ## 修改一条记录。追踪哈希值。 每条记录都包含前一条记录的哈希。保存在别处的检查点固定了日志长度和最后一个哈希。 02 / HASH-CHAIN SANDBOX真实的 SHA-256 · 记录示例 记录 01**消息已收到**`h₁ = SHA-256(e₁)`链接至 64 个零 记录 02**11:00 见面**`h₂ = SHA-256(e₂)`包含 h₁ 记录 03**观察到删除操作**`h₃ = SHA-256(e₃)`包含 h₂ 保留在其他地方**3 条记录 · 头部 `h₃`**请将此固定边界与提供的日志进行对比。 修改某条事件会改变其哈希值。重建链条会改变其头部。移除尾部会使其长度短于保留的检查点。 **查看记录 2 及完整哈希值** 这是本示例中经过哈希处理的精确 UTF-8 JSON 数据。数值均为虚构；其中的九个字段及序列化格式均与日志格式一致。 ``` ``` 已保存记录 2 的哈希值 `` 重新计算的记录 2 哈希值 `` 此沙盒仅计算哈希值，不生成签名。真正的验证器还会检查每个事件的 Ed25519 签名、序列号和链接。仅凭哈希值的重建无法在受信任密钥下生成有效的签名。 ## 实际规则，简要概述如下 哈希值 + 签名 h0 = 064 hi = hex(SHA-256(C(ei))) σi = Ed25519.Sign(sk, unhex(hi)) **C** 是以 UTF-8 JSON 表示的九个事件字段：键已排序，无多余空白，无 ASCII 转义，无 NaN/无穷大。`previous_hash` 是 hi−1，h0 是 64 个零，签名覆盖 32 字节的原始摘要。 字段：`seq`、`observed_at`、`source_at`、`kind`、`chat_id`、`message_id`、`actor_id`、`payload`、`previous_hash`。完整规范：[事件编码](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#event-canonicalization)。 保留检查点 Nexport ≥ Ncheckpoint hexport[Ncheckpoint] = Hcheckpoint 用固定的密钥检查检查点签名，然后将其与日志比较。之后的导出可以更长，但在检查点处必须一致。 ## 三个问题，三种不同的核查方式 [01 / 完整性**该记录是否发生了变化？** 用您信任的密钥核查哈希和签名。](https://phishdestroy.github.io/TgWitness/zh/docs/exports/)[02 / 连续性**之前保留了哪些内容？** 将导出与见证人保存的检查点比较。](https://phishdestroy.github.io/TgWitness/zh/docs/witness/)[03 / 交付**这些测试事件是否已到达？** 发送、编辑和删除测试消息，看看每个账户捕获了什么。](https://phishdestroy.github.io/TgWitness/zh/docs/cases/) 签名回答“是否被改过”，检查点回答“是否与之前的一致”，测试消息回答“我们是否捕获了全部”。[验证能证明什么、不能证明什么。](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#verification-scope) 下一步：从开始到案件包的[整个账户调查](https://phishdestroy.github.io/TgWitness/zh/docs/cases/)。 [Export Clinic: watch the controlled Desktop experiment](https://phishdestroy.github.io/TgWitness/docs/export-clinic/). Compare the two-minute film, the original recording and seven pairs of test exports. Local modification is disclosed. --- # Telegram · 确保安全 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/security/ 了解会话、密钥和证据的存储位置，哪些数据会离开您的设备，保护措施涵盖哪些内容，以及如何加强系统安全性。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 什么会离开您的机器，每个密钥能打开什么，哪些由保护措施覆盖、哪些由您负责。 **127.0.0.1**默认面板地址 **256 位**随机面板令牌 **0**内容分发网络（CDN）、分析工具或远程字体 **Ed25519**每条记录均附有签名 ## 所有内容的归宿 采集器、面板和每条记录都留在您的机器上。默认只连接 Telegram；其他一切都是单独的开关。 06 / 机器留下的痕迹您的安装 您的计算机或服务器 **面板**127.0.0.1:8787 · 承载令牌 **收集器**每个工作区仅限一个 Telegram 客户端 数据目录 **日志**SQLite · 哈希链 · 签名 **媒体**文件名采用 SHA-256 哈希值命名 **Vault**Fernet · 会话、API 对、签名密钥、代理 - **Telegram**始终 · 通过您的路径 该账户的 MTProto 连接方式包括：直接连接、SOCKS5、HTTP 或 MTProxy。“隐藏 IP”模式会等待可用的代理。若要启用直接连接回退，则需使用明确允许此功能的模式。 - **站外文案**可选 · 默认关闭 日志、文件和检查点在上传至兼容 S3 的存储之前，会使用 AES-GCM 进行加密。密钥由您自行保管；附件的命名基于密钥哈希值，而非其内容哈希值。 - **通知**可选 · 默认关闭 显示问题及变更数量，并附带聊天标题。消息摘录仅在您开启该功能时才会显示。 - **时间戳权威性**可选 · 默认关闭 仅包含已签名的检查点的 SHA-256 哈希值和一个随机非ce值。不包含任何消息内容，也不包含聊天昵称。 - **见证人**可选 · 默认关闭 使用只读令牌提取带签名的检查点和捕获计数器。该工具无法读取对话内容或更改设置。 默认设置：仅 Telegram 连接会离开这台机器。 可选的存储位置需按工作区进行配置。消息正文和媒体文件以未加密形式存储在数据目录中：请通过磁盘加密和文件权限对其进行保护。 ## 每个秘密揭示的内容 | 秘密 | 存储位置 | 它能带来什么 | 若发生泄露 | | --- | --- | --- | --- | | **面板令牌** | 数据目录中的 `panel-token.txt`；浏览器按标签页保存 | 每个工作区中的一切 | 停止 TgWitness，删除 `panel-token.txt`，重新启动：会生成新的令牌 | | **Telegram 会话** | Vault，加密版（`credentials.enc`） | Telegram 账号本身 | 在 Telegram 中通过*“设置”→“设备*”结束当前会话 | | **签名密钥** | Vault，加密版（`signing.enc`） | 以您的指纹签署记录 | 保存在别处的检查点、见证人和时间戳仍能显示之前存在的内容 | | **保险库密钥** | 数据旁边的 `vault.key`，或外部主密钥 | 保险库 | 请假定会话和签名密钥也已泄露 | | **Witness 代币** | 关于 Witness 主机 | 只读：检查点和健康状态 | 在见证人页面删除它，再新建一个 | | **站外文案关键点** | Vault；只需下载一次即可进行数据恢复 | 异地副本 | 同时拿到存储桶的人可以解密它：请将副本视为已暴露 | ## 保护范围 ### 已收录 - 记录被修改、删除或重新排序：哈希链或签名会断裂。 - 在您将检查点保存到别处之后，日志被截短或重建：检查点不再匹配。 - 猜测令牌：256 位随机数，常量时间比较，每分钟失败 15 次即封锁该地址。 - 恶意聊天内容：文本始终是文本，绝不作为 HTML；附件以文件形式下载；面板不从其他网站加载任何内容。 - 数据目录被盗但保险库密钥在外部：会话和密钥仍是加密的。 ### 由您决定 - 主令牌可以做任何事。请给他人限定范围的访问权限，主令牌留给自己。 - 机器上的管理员可以读取一切并重新签署日志。请将指纹和检查点保存在别处。 - TgWitness 不加密消息和媒体。请加密磁盘，收紧权限。 - 在 localhost 之外使用普通 HTTP 会泄露令牌。请使用 HTTPS 或 SSH 隧道。 - 签名不会告诉您遗漏了什么。请在您自己的账户和来源上检查覆盖范围并测试送达。 [共享案件的访问权限](https://phishdestroy.github.io/TgWitness/zh/docs/access/)，可设置权限、有效期和会话限制。 ## 强化安装安全性 已完成 0/8 1. **请使用专用的 Telegram 账号**，绝不要用主账号。 2. **请将控制面板保留在 127.0.0.1 上。**远程访问只通过 HTTPS（内置 Caddy）或 SSH 隧道。 3. **请加密存放数据目录的磁盘**，消息和媒体按原样存储。 4. **将数据目录限制**为仅服务账户可访问（Unix 上为 0700，Windows 上为文件夹权限）。 5. **在服务器上将保险库密钥保存在别处**：首次启动前设置 `TGWITNESS_VAULT_KEY_FILE`。 6. **将指纹和检查点保存在**另一个系统上，在另一台主机上运行见证人。 7. **切勿将** `data/`、会话密钥、`panel-token.txt` 或保险库密钥**上传**至 GitHub 或聊天群组。 8. **请勿**在反向代理服务器上**记录** `Authorization` 标头或请求正文。 **我可以更改面板令牌而不丢失数据吗？** 可以，它只能打开面板。停止 TgWitness，删除 `panel-token.txt`，重新启动。日志、会话和密钥都会保留。如果设置了 `TGWITNESS_TOKEN`，则以该值为准，而不是文件。 **为什么消息在静止状态下不进行加密？** 采集器必须读取它们才能搜索、比较和导出。放在同一台机器上的密钥挡不住本来就能读取这台机器的人。磁盘加密防的是磁盘被盗，权限防的是运行中的系统。 ## 报告漏洞 在 GitHub 上使用 **Security → Report a vulnerability**。提供版本、影响以及使用虚构数据的最小复现。切勿发送凭据、账户文件夹或真实证据。如果私密报告已关闭，请开一个 issue 申请私密渠道，不要写漏洞利用细节。 --- # Telegram · 设置 Witness 机器人 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/witness/ 通过独立的见证节点（配备专属密钥及只读收集器访问权限），将签名的日志检查点发布至您的 Telegram 频道。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 一个独立进程检查您的日志，并将签名检查点发布到频道。 ## 两台主机，两把签名密钥 托管 / 收集器**账户 + 日志** Telegram 会话收集器的签名密钥 只读检查点端点 ← 请求签名回答 → 主机 B / WITNESS**验证 + 保留** 固定收集器指纹 独立见证人签名密钥 自有日志 + 机器人令牌 Witness → Telegram 机器人 API →**您的频道 · 带签名的 TGW1 帖子** Witness 会自行执行校验。收集器的访问权限仅限只读。机器人发布功能使用 Witness 的连接和令牌；Witness 不会获得任何账户会话权限。 03 / 检查点决策示例答案 最后接受时间**120 条记录**`head 9c7d…` 下一个答案**128 条记录**`head a4f2…` 已通过：计数持续增加，签名已验证，密钥匹配。该见证者保留了这一新边界。 所有解答示例均假设存在有效签名和已固定的密钥。此处的哈希值仅为简略示例。仅凭哈希值数量较多，无法证明整个旧前缀均未发生变化；请将导出数据与保留的检查点进行对比。 ## 准备一个机器人和一个频道 用 BotFather 创建机器人，并允许它在您的频道中发帖。请在别处运行见证人：另一台主机，最好由其他人管理，远比在采集器旁边再跑一个进程更有价值。 ## “扩展功能”中的三个步骤 1. **只读访问权限。****扩展功能 → 独立见证人**，创建令牌并保存文件。它只读取检查点和健康状态，别无其他。 2. **频道和间隔。**Telegram 频道或 Discord webhook，以及见证人能访问到的采集器地址。保存设置文件。 3. **启动。**将 `witness.json`、`witness-token.txt` 和 `bot-token.txt` 一起放到见证人主机上并运行： ``` python -m tgwitness.witness run --config witness.json --check-config python -m tgwitness.witness run --config witness.json ``` 等待频道中出现第一条签名帖子，然后将见证人指纹保存在安全的地方。 想用 Discord？将 webhook URL 保存为 `discord-webhook.txt`。一个见证人只发布到一个地方；较长的检查结果在 Discord 上以文件形式送达。 ## 选择发布频率 每次检查都发帖可以形成稳定的外部记录：每五分钟一次，相当于每个工作区每天约 288 条帖子。高级设置可以只在有变化或出问题时发帖，使用代理或自定义 Bot API。 **该机器人实际上能证明什么？** 它向采集器请求签名检查点，用预期的密钥核查，并保存自己的签名日志，包括错过和被拒绝的应答。 它检查的是日志状态，本身并不监视 Telegram。为此，请进行受控的送达测试。 ## 稍后核查证据 请保留见证人日志、帖子和指纹。[如何核查它们](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/#verify)与采集器导出是否一致。 --- # Telegram · 浏览存档 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/archive/ 加载历史记录、搜索已保存记录、审查 AI 来源并连接您的工具。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 查找消息。核查来源。构建案情。 01**引入历史记录** 将已启用来源的过往消息拉取到工作区。 02**追踪消息来源** 搜索，然后打开每条结果背后保存的消息。 03**确保交接清晰明了** 您的分析放在一个文件里，签名证据放在旁边。 捕获的记录、识别出的文本以及分析人员的结论均保持独立。 ## 加载历史消息 1. **来源 → 范围内的聊天**：检查已启用的聊天，开始观察。 2. **加载完整历史记录**。它按当前的来源列表执行。 3. 随时可以**暂停历史** / **继续历史记录**。重启后请手动继续。 4. 检查每个来源的结果和下载队列，将签名进度报告与导出一起保存。 这会填充工作区。单个聊天的 HTML/JSON 导出是另一回事。[详情](https://phishdestroy.github.io/TgWitness/zh/docs/reference/history/)。 ## 先搜索，再决定是否使用 AI 1. **日志**在本地搜索，可按来源和时间筛选。 2. 搜索短语或域名，打开记录及其各个版本。 3. 使用 AI 时，由管理员在**集成**中设置服务商。然后**查询存档**：选择聊天和时间段，查看**发送到模型的数据**，取消勾选不应发出的内容。 4. 检查引用，将回答保存为报告，添加您的笔记。 搜索不需要 AI。报告保存自己的来源和修订版本，与签名日志分开。[服务商设置](https://phishdestroy.github.io/TgWitness/zh/docs/reference/analysis/)。 ## 选择您需要的连接方式 | 任务 | 打开 | 设置 | | --- | --- | --- | | 让 AI 客户端读取选定的聊天 | **集成 → MCP** | [安装 MCP、创建限定范围的令牌并连接](https://phishdestroy.github.io/TgWitness/zh/docs/reference/mcp/) | | 识别保存媒体中的文本 | `media.saved`记录 → **识别附件** | [设置本地 Docker worker](https://phishdestroy.github.io/TgWitness/zh/docs/reference/media-analysis/) | | 将事件发送至 n8n 或 SIEM | **集成 → 外发 webhook** | [添加接收端、校验 HMAC、去重 ID](https://phishdestroy.github.io/TgWitness/zh/docs/reference/webhooks/) | **哪个访问令牌该填在哪里？** 面板访问是给人用的。MCP 有自己的只读令牌，webhook 有自己的 HMAC 密钥。它们都不需要 Telegram 会话。 [共享控制面板访问](https://phishdestroy.github.io/TgWitness/zh/docs/access/)权限或[配置 MCP 客户端](https://phishdestroy.github.io/TgWitness/zh/docs/reference/mcp/)。 ## 提供数据来源和结论 请将报告放在签名 ZIP 旁边。报告是您对来源的解读，ZIP 才是接收方要验证的内容。 [导出与验证](https://phishdestroy.github.io/TgWitness/zh/docs/exports/) · [完整调查流程](https://phishdestroy.github.io/TgWitness/zh/docs/cases/) --- # Telegram · 分享案例 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/access/ 为审查员和分析师提供对选定账户和聊天的访问权限，并设置独立的权限、会话限制和可撤销的令牌。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 分享他人需要的案例。其余内容由您掌控。 01**选择证据** 整个工作区或单个聊天。 02**选择操作** 查看、导出，或仅限他们需要的操作。 03**设置限制** 个人令牌，可按需设置有效期、会话限制和 IP 规则。 采集范围决定了记录的内容。访问范围决定了用户可以查看和执行的操作。 ## 授予某人访问权限 1. 以管理员身份打开**访问**。 2. 命名，选择工作区和聊天。 3. 审核员只需要**查看**。如需下载请添加**导出**。 4. 设置权限限制，然后点击**“创建访问权限**”。 5. 复制令牌（只显示一次），连同面板地址私下发送。 6. 先在单独的浏览器会话中检查他们会看到什么。 ## 从他们需要完成的工作入手 | 人物 | 访问 | 结果 | | --- | --- | --- | | 审稿人 | 精选聊天记录；仅限查看 | 阅读聊天，不能更改任何内容。 | | 分析师 | 精选聊天记录；查看和导出 | 阅读并下载案件所需内容。 | | 操作员 | 精选的完整工作区；来源与收集 | 决定观察哪些内容，启动和停止采集器。 | 这些只是示例，不是固定角色。限于聊天的访问权限永远不会获得账户设置或完整日志导出。所有工作区的访问权限包括之后添加的账户。 ## 您可以随时改变主意 随时可编辑访问权限，从下一次请求起生效。可结束单个会话或全部撤销。已下载的文件无法收回。采集会继续运行。 **会话和 IP 限制** 限制并行会话和登录次数，设置截止日期，允许特定 IP 或子网，或锁定为首次登录的 IP。有效期按不活动时间计算，打开着的面板算作活动。在代理后面时，请检查应用看到的是哪个客户端 IP。 **主密钥和活动日志** 主令牌留在管理员手中。发放的访问权限不能管理他人的访问，也不能打开管理控制台。访问变更和会话会签名写入日志，不包含令牌。服务器管理员仍然可以看到一切。 全部七项权限和会话规则：[访问参考](https://phishdestroy.github.io/TgWitness/zh/docs/reference/access/)。 --- # Telegram · 保持其运行 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/server/ 请在配备持久化存储、私有控制面板访问权限、备份功能以及重启后自动检查机制的服务器上运行 TgWitness。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 让采集器保持运行，数据在重启后依然安全。 ## 选择启动方式 原生：[启动器](https://phishdestroy.github.io/TgWitness/zh/docs/start/)加上 [deploy/](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md) 中的服务模板。Docker，在项目文件夹中执行： ``` docker compose up -d --build --wait docker compose exec tgwitness cat /data/panel-token.txt ``` 面板监听 localhost:8787。在本地或通过 SSH 隧道打开，使用第二条命令输出的令牌。 ## 保留整个数据目录 原生：`data/live`。Docker：`tgwitness-data` 卷。日志、会话和密钥必须放在一起。签名导出是证据，不是备份。 1. 先停止采集。 2. 将整个数据目录复制到主机以外的安全位置。 3. 在信任它之前，先在单独的安装上试着恢复。 ## 重启后请检查 检查工作区和密钥、连接、来源，以及新消息是否进来。TgWitness 会补上 Telegram 仍保留的内容，而不是停机期间发生的一切。 容器“健康”表示 Web 服务器有响应。采集是否正常，要看测试消息和见证人。 ## 仅发布您有意发布的内容 HTTPS、卷、更新和恢复见部署参考。实际测试过的内容：[验证记录](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/)。 --- # Telegram · 查找问题所在 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/troubleshooting/ 请使用针对各问题的正确信号，检查控制面板访问权限、Telegram 连接状态、消息缺失情况、FloodWait 状态以及见证状态。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 从症状入手，一次检查一项。 ## 面板要求输入令牌 它要的是启动器所打印文件中的面板令牌。Docker：`docker compose exec tgwitness cat /data/panel-token.txt`。不是 Telegram 验证码，不是机器人令牌，也不是见证人令牌。 ## Telegram 无法连接 运行连接检查。如果用的是公共代理，换一个并保存。检查代理类型和密钥格式。刷新列表本身不会切换路由。 ## 已连接，但无新消息 1. 观察是否在运行，且在正确的工作区中？ 2. 来源是否已选中，且该账户可见？ 3. 在测试群组中发送一条独特的消息，然后搜索它。 4. 在日志中查找中断或 Telegram 错误。 安静的聊天只是没有新内容。如果完整性很重要，请进行受控的送达测试。 ## 重启后出现 FloodWait 或间隔 FloodWait 是 Telegram 在说“慢一点”。请等它过去并减轻负载，重新连接没有用。重启后 TgWitness 会补上 Telegram 仍保留的内容；其余的是空缺，请记录下来。 ## 该机器人已配置完毕，但尚未发布任何内容 见证人是否在运行，机器人能否在频道中发帖，它能否访问采集器和 Bot API？在它的日志中查找发帖失败。采集器端出现轮询并不代表帖子已发出。 ## GitHub 令牌集成功能在哪里？ **计划中。**“扩展功能”部分描述了拟议的分叉和构建验证工作流。目前尚无 GitHub 令牌表单，也无法自动验证运行中的安装是否与代码库匹配。请参阅[当前功能状态](https://phishdestroy.github.io/TgWitness/zh/docs/reference/features/)。 报告 bug？请提供版本、操作系统、步骤和去除隐私的错误信息。切勿在公开 issue 中放入会话、令牌、私信或数据目录。 --- # TgWitness: Telegram Export, OSINT & Verification Canonical page: https://phishdestroy.github.io/TgWitness/docs/reference/overview/ Explore TgWitness installation, Telegram capture, investigation tools and evidence verification. Read measured workloads alongside their methods and limits. [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/llms.txt) 通过一条命令安装，或在 GitHub Actions 上进行捕获。了解调查选项、已发布的规模以及存档所验证的内容。 TgWitness 是一款开源的 Telegram 数据导出工具及调查工作区。只需 一条命令即可安装，连接账户，选择聊天记录并导出经过签名的 归档文件。它还支持在 GitHub Actions 上进行临时数据收集，并可通过 保存的编辑记录、删除观察记录、搜索和报告功能继续开展调查。 ## 从您手头的任务开始 | 您的任务 | 最短路径 | 您将收到 | | --- | --- | --- | | 保存对话或账户 | 安装、连接账户、选择导出范围 | 一个包含所选历史记录、收集结果和验证材料的签名存档 | | 在临时运行器上收集 | 使用 GitHub Actions 进行数据捕获、授权新会话并选择作用域 | 一个包含 GitHub 工作流溯源信息的加密存档 | | 跟踪随时间推移的变化 | 保持对选定聊天室的观察功能持续运行 | 已保存版本、删除通知、附件及记录的覆盖范围 | | 调查并分享调查结果 | 搜索存档、使用案例板，并配置报告或共享副本 | 附有来源链接的发现结果，以及适合接收方的可验证交接流程 | ### 一键安装 安装程序包含 Python 及其依赖项。源代码检出、Docker、AI 提供商和独立见证人均为可选项，并非安装的先决条件。 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" ``` 打开控制面板，连接您的 Telegram 账户并选择数据采集范围。 安装过程不会自动启动数据采集。[安装指南中](https://phishdestroy.github.io/TgWitness/zh/docs/reference/installation/) 详细说明了本地访问、服务器配置、更新以及如何验证已下载的构建版本。 若需临时运行程序，请按照 [GitHub Actions 捕获指南](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md)操作。该 工作流需要 GitHub 分支、授权以及归档密码。捕获 页面详细说明了这些步骤以及运行前的会话时间限制。请下载 并保留生成的归档文件及其验证材料。 ## 当任务需要时，提供更多设置选项 单个聊天记录的导出需要一个账户和选定的范围。持续观察、 多个账户、代理服务器、附件策略、报告设计、审核员访问权限、 外部时间戳和异地存储可满足不同的调查和 移交需求。在相关情况下配置这些功能。 范围、权限和最小化共享副本有助于操作员选择需要 收集和披露的内容。管辖权指南和报告设置为该 决策提供支持；选择配置文件本身并不构成法律合规性或 可采纳性。请参阅[账户导出](https://phishdestroy.github.io/TgWitness/zh/docs/reference/account-export/)、[访问](https://phishdestroy.github.io/TgWitness/zh/docs/reference/access/)和 [报告配置](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-reports/)。 该应用程序在选定的计算机或服务器上运行。基本数据采集无需 GPU 或大型语言模型（LLM）。可选的 OCR、转录和 AI 分析功能各有 其资源需求。请根据消息速率、附件、 历史记录保留时长和并发账户数量来规划部署规模；简便的安装并不意味着 每种工作负载的内存占用量都固定不变。 ## 无论对谁有所帮助，都要保留记录 其目的是保留所观察到的材料、背景及变更，无论 这些内容支持何方立场。证据可能会对收集者自身对事件的 叙述提出质疑。请确保原始观察结果、遗漏内容及分析结论 均可被识别，以便他人能够对同一材料进行评估。 其逻辑流程为：账户可见的观察结果 → 签名日志 → 导出 → 收件人 验证。保存的编辑操作会生成新版本。已删除的观察结果仍保留先前 捕获的内容。覆盖记录会揭示已知的中断情况。报告和 AI 分析会回溯至已保存的来源；一种解释不会仅仅因为出现在签名报告中 就成为来源观察结果。 | 验证检查 | 接收方可确认的内容 | | --- | --- | | 文件哈希值、签名和日志链 | 提供的记录和文件与预期的密钥和日志边界一致 | | 单独保留的检查点或见证 | 该存档与先前保留的日志状态一致 | | 一个经过验证的外部时间戳 | 在所述信任假设下，所引用的字节在时间戳时点上确实存在 | | GitHub 捕获证明 | 该归档文件符合已批准的工作流程、采集器版本及记录的摘要 | 这些检查支持对完整性和来源的审查。它们不会将 消息内容转化为真命题，也不会还原未被查看的已删除 消息。请使用独立获取的密钥指纹，并遵循[《信任指南》](https://github.com/phishdestroy/TgWitness/blob/main/docs/TRUST.md)和[《证据格式》](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/)中的 验证步骤。 ## 已公布的规模及实测性能 以下结果描述了不同的工作负载和日期。计数不可 互换：日志事件不一定是唯一的 Telegram 消息。 | 日期 | 工作量 | 发布结果 | 测量内容 | | --- | --- | --- | --- | | 1 11月 2026 | 运行中的服务器，十个工作区数据库 | 1,610,818条日志记录；900,232条新消息事件、80,683条编辑事件和400,536条删除事件 | 仅限读取的库存；并非吞吐量测试或新的全链验证 | | 5年11月2026日 | 在200个聊天群组中搜索超过1,000,000条合成消息 | 索引构建耗时 71 秒；每次查询的中位数搜索时间为 9–190 毫秒 | 本地搜索基准测试；非实时 Telegram 消息投递 | | 6年11月2026日 | 两份最新的真实 Telegram 导出数据 | 27,030和29,299条消息；两次运行共计56,329条 | 每次通过 WARP 运行时处理两个账户，包括文本和元数据，不下载附件 | | 6年11月2026日 | 相同的两个导出操作，包括准备和打包 | 127.713 和 141.781 条消息/秒 | 测得的完整导出率；两个存档均已通过固定密钥验证 | [验证记录](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/) 提供了服务器清单、实时 数据采集检查及搜索性能指标。[性能导出](https://phishdestroy.github.io/TgWitness/docs/validation/) 报告包含两次实际运行情况、硬件配置、持续时间、存档哈希值以及已签名的 测量文件。这些数据仅反映特定版本和 条件下的测试结果，并非普遍适用的速率或容量上限。 ### 测试历史与持续时间 维护者报告称，截至 6 11月 2026. 这描述了该项目的测试历史。上文中带日期的公开测量数据 记录的是单次运行情况；它们并不能证明存在经过独立验证的、 连续六个月的数据收集运行。导出消息的生成时间也 与收集器运行的时间不同。 ## 准确解读功能状态 针对每个工作流，结合其实现、已发布的构建版本和记录的 测试结果进行评估。源代码当前标记为预览版。该发布标签与 可运行的数据集、导出功能、独立验证以及已发布的规模 测量结果并存。同一 应用程序中可能同时存在预览功能和经过验证的工作流；请描述评估所依据的具体功能及证据。 请综合参考[当前功能](https://github.com/phishdestroy/TgWitness/blob/main/docs/STATUS.md)、[特性与限制](https://phishdestroy.github.io/TgWitness/zh/docs/reference/features/)、 [验证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/)信息及[变更日志](https://phishdestroy.github.io/TgWitness/zh/docs/reference/changelog/)。 引用测试结果时，请记录所测试的版本号。11月6日的测量 快照中还保留了失败和跳过的测试；这些不属于通过项。 ## 既可供人类阅读，也可供人工智能工具解析 该网站提供了一份简明扼要的`llms.txt`文件、一份完整的英文手册（ `llms-full.txt`和`llms-full.md`），以及各页面的 Markdown 版本。这些是 文档格式，并非运行 TgWitness 所需的 AI 要求。 可选的 [MCP](https://phishdestroy.github.io/TgWitness/zh/docs/reference/mcp/) [和命令行访问功能](https://phishdestroy.github.io/TgWitness/zh/docs/reference/cli/)允许授权工具读取 选定的已保存记录。消息内容仍被视为不可信输入。摘要应 注明来源，区分观察到的事实与推论，并保留不确定性。 全文搜索、OCR 和 AI 输出不会更改原始的已签名观察结果。 --- # Telegram · 快速入门 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/quickstart/ 安装和启动 TgWitness 的所有方法：Windows 安装包、Python、Docker 以及综合演示，并附带初步测试。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 安装和启动 TgWitness 的所有方法：Windows 安装包、Python、Docker 以及综合演示，并附带初步测试。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) ![入门指南](https://phishdestroy.github.io/TgWitness/assets/chapter-start.svg) **英语** · [俄语](https://github.com/phishdestroy/TgWitness/blob/main/docs/ru/QUICKSTART.md) · [乌克兰语](https://github.com/phishdestroy/TgWitness/blob/main/docs/uk/QUICKSTART.md) · [西班牙语](https://github.com/phishdestroy/TgWitness/blob/main/docs/es/QUICKSTART.md) · [葡萄牙语（巴西）](https://github.com/phishdestroy/TgWitness/blob/main/docs/pt/QUICKSTART.md) · [土耳其语](https://github.com/phishdestroy/TgWitness/blob/main/docs/tr/QUICKSTART.md) · [阿拉伯语](https://github.com/phishdestroy/TgWitness/blob/main/docs/ar/QUICKSTART.md) · [فارسی](https://github.com/phishdestroy/TgWitness/blob/main/docs/fa/QUICKSTART.md) · [乌尔都语](https://github.com/phishdestroy/TgWitness/blob/main/docs/ur/QUICKSTART.md) · [हिन्दी](https://github.com/phishdestroy/TgWitness/blob/main/docs/hi/QUICKSTART.md) · [印尼语](https://github.com/phishdestroy/TgWitness/blob/main/docs/id/QUICKSTART.md) · [越南语](https://github.com/phishdestroy/TgWitness/blob/main/docs/vi/QUICKSTART.md) · [简体中文](https://github.com/phishdestroy/TgWitness/blob/main/docs/zh/QUICKSTART.md) TgWitness 是一款用于监控您账户可访问的 Telegram 群组和频道的独立应用程序， 它在本地运行并拥有独立的数据目录。 **初次访问？**在连接账户前，[请先体验演示版](https://phishdestroy.github.io/TgWitness/zh/docs/reference/quickstart/#explore-the-interface)。 [选择代理、Witness、数据导出或服务器设置的相关指南](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md)。 ## 安装并启动 [通过 GitHub Actions 采集（预览版）](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md) 请选择一种方式。发布版本发布后，即可获取便携版下载： | 主机 | 无需安装 | 来源：Python 3.11+ | Docker：Engine/Desktop 搭配 Compose 2.20+ | | --- | --- | --- | --- | | Windows | 从 GitHub Releases 中提取 `TgWitness--windows-amd64-portable.zip`，双击 `TgWitness.cmd` | 双击 `Start.cmd` | 双击 `scripts\Docker.cmd` | | Linux / macOS | — | `sh start.sh` | `sh scripts/docker-start.sh` | 对于源码方式，请[下载并解压当前的 `main` 分支](https://github.com/phishdestroy/TgWitness/archive/refs/heads/main.zip)， 或克隆仓库： ``` 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://phishdestroy.github.io/TgWitness/zh/docs/reference/deployment/)涵盖自动 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 凭据用于识别您的应用程序；它们本身并不能 授权任何账户。私人群组无需公开用户名，但您的账户必须具备访问权限。 对于现有账户，请参阅[账户和会话格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/)：面板 支持 Telethon StringSession、Telethon/Pyrogram SQLite、单账户 TData ZIP 以及受支持的账户 JSON。同时选择一个会话及其配套的 JSON 文件， 然后按**连接账户**。二维码登录同样 可用，并支持相同的可选 API 设置。不支持 TDLib、机器人会话以及 CSV/JSON 账户清单。 对于多个账户，请使用**账户 → 导入账户**并选择其受支持的 会话文件。配套的 JSON 文件按基本名称（basename）配对；每个导入的账户 都会获得各自的工作区。请参阅[批量导入与账户组](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#bulk-import-and-account-groups)。 要添加另一个账户，请点击账户选择器旁边的 **+**，或打开 **“账户” → “设置” → “连接设置” → “工作区**”，或使用**“账户”功能**。各个工作区拥有独立的会话、 日志、密钥、来源和队列。切换视图时，其他采集器将继续运行。 在此安装环境中，同一个 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](https://phishdestroy.github.io/TgWitness/zh/docs/reference/timestamp/) 中的说明获取并验证响应。 - **验证日志：**检查事件签名和链节。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。](https://phishdestroy.github.io/TgWitness/zh/docs/reference/connection/) **暂停观察**将停止数据采集。**锁定**仅关闭浏览器访问权限。 关闭标签页不会终止采集进程。停止该进程才会中断 数据采集；历史快照无法还原所有遗漏的编辑或删除操作。 了解[数据采集在事件策略、附件队列、 账户隔离及重启行为方面的运作原理](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/)。 会话和密钥均经过加密。消息内容、媒体文件及导出数据需要存储在 加密磁盘或卷上。签名基于可信密钥来验证数据完整性； 但无法证明消息源自 Telegram，也无法防止由控制收集器及其密钥的操作员 伪造数据。 请阅读 [OPERATIONS.md](https://phishdestroy.github.io/TgWitness/zh/docs/reference/operations/) 了解备份/恢复操作，阅读 [DEPLOYMENT.md](https://phishdestroy.github.io/TgWitness/zh/docs/reference/deployment/) 了解托管方案，并访问 [deploy/](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md) 查看服务示例。已安装的 控制面板还包含一份离线设置指南，地址为 `/guide.html`。 实际验证情况及现有局限性 记录在 [VERIFICATION.md](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/) 和 [READINESS.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/READINESS.md) 中。 --- # 安装、验证和更新 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/installation/ 只需一条命令即可完成安装、验证签名和哈希值，以及更新和卸载该工具。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) Translation coverage: this edition includes material from the English original. 只需一条命令即可完成安装、验证签名和哈希值，以及更新和卸载该工具。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [入门指南](https://phishdestroy.github.io/TgWitness/zh/docs/reference/quickstart/) ![入门指南](https://phishdestroy.github.io/TgWitness/assets/chapter-start.svg) [项目](https://github.com/phishdestroy/TgWitness/blob/main/README.md) · [快速入门](https://phishdestroy.github.io/TgWitness/zh/docs/reference/quickstart/) · [部署](https://phishdestroy.github.io/TgWitness/zh/docs/reference/deployment/) **本页内容** - [仅需一条命令即可安装](https://phishdestroy.github.io/TgWitness/zh/docs/reference/installation/#install-with-one-command) - [万物运行之处](https://phishdestroy.github.io/TgWitness/zh/docs/reference/installation/#where-everything-runs) - [全文搜索设置](https://phishdestroy.github.io/TgWitness/zh/docs/reference/installation/#full-text-search-settings) - [命令行访问](https://phishdestroy.github.io/TgWitness/zh/docs/reference/installation/#command-line-access) - [运行前请先验证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/installation/#verify-before-running) - [更新现有安装](https://phishdestroy.github.io/TgWitness/zh/docs/reference/installation/#update-an-existing-installation) - [Ubuntu 上的常用命令](https://phishdestroy.github.io/TgWitness/zh/docs/reference/installation/#everyday-commands-on-ubuntu) - [删除 TgWitness](https://phishdestroy.github.io/TgWitness/zh/docs/reference/installation/#remove-tgwitness) ## 只需一条命令即可安装 引导式安装程序包含一个私有 Python 运行时环境。后续安装请使用同一地址： 每次发布都会将安装程序、哈希值、签名 和构建信息一并更新。 **Linux / macOS (Bash)：** ``` curl -fsSL https://get.destroy.tools/install.sh | bash ``` 在 Ubuntu 服务器上，请以 root 身份运行以安装后台服务。在桌面电脑上， 请以普通用户身份运行。 **Windows（PowerShell 或命令提示符）：** ``` powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://get.destroy.tools/install.ps1 | iex" ``` 在 Windows 系统上无需管理员权限。子 PowerShell 进程会将您的 终端保持打开状态并显示结果。Python 及其依赖项均保留在安装目录中。 在 Ubuntu 上，请选择**“本机”**、**“临时 HTTPS 链接**”或**“自有域名**”。 安装程序会显示控制面板地址和访问密钥。若需临时链接，请在浏览器中打开 该 HTTPS 地址并输入密钥。若需通过远程 服务器进行本地访问，请从您的计算机（`ssh -L 8787:127.0.0.1:8787 user@server`) 并打开 `http://127.0.0.1:8787`。在 macOS 和 Windows 上，本地面板会在您的 浏览器中打开；请保持其终端运行。 在面板中登录 Telegram，并选择要收集的内容。仅安装 并不会自动开始收集 Telegram 数据。 ## 一切运行于此 `get.destroy.tools` 是一个**用于提供静态文件下载服务的 Cloudflare Worker**。它不包含 TgWitness 面板、Telegram 会话或用户证据数据库。它不会被路由到 项目 VPS 上。该应用程序在您执行命令的机器上运行。 | 安装 | 程序 | 数据 | | --- | --- | --- | | 以 root 身份使用 Ubuntu | `/opt/tgwitness` | 系统服务： `/var/lib/tgwitness-`；请使用 `tgwitness paths` 以获取确切路径。 | | Linux / macOS 用户 | `~/.local/share/tgwitness` | `data/live` 在该安装环境下。 | | Windows 用户 | `%LOCALAPPDATA%\TgWitness` | `data\live` 在该安装环境下。 | 设置 `TGWITNESS_INSTALL_DIR` 以选择另一个文件夹。已安装的版本和数据 是分离的。安装程序不会将您的账户、消息或密钥上传至 下载站点。选择 Cloudflare 隧道会将面板流量通过 Cloudflare 传输；使用您自己的域名则会指向您自己的服务器。 With `TGWITNESS_TRUSTED_PROXIES`, the panel accepts a single `X-Forwarded-Proto: https` from a trusted proxy to set Secure download cookies. 每次安装都包含 **START-HERE.html** 和 **START-HERE.txt** 文件，其中包含本地 路径、命令以及代码库的链接。运行 `tgwitness guide` 以打开指南。 在 Windows 上，请使用 `& "$env:LOCALAPPDATA\TgWitness\bin\tgwitness.cmd" guide` 在 PowerShell 中运行。 ## 全文搜索设置 [全文搜索](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/)（预览版）无需任何配置。其索引会在更新后在 后台自动构建。 | 变量或命令 | 效果 | | --- | --- | | `TGWITNESS_FULLTEXT=disk` | 默认：索引保存在 `search/fulltext.sqlite3` 每个工作区的 | | `TGWITNESS_FULLTEXT=memory` | 无索引文件；每次启动时都会重建索引 | | `TGWITNESS_FULLTEXT=off` | 不建立索引；仅支持精确文本搜索 | | `tgwitness index status` | 索引每个工作区的状态 | | `tgwitness stop`, `tgwitness index rebuild`, `tgwitness start` | 从签名日志中重建所有索引 | 管理员在**“日志”→“过滤器”→“搜索索引**”中的选择将覆盖 该工作区的变量。命令会查找运行它们的安装 的数据目录；在其他地方，请添加 `--data-dir` 并使用来自 `tgwitness paths`。 如需完整的乌克兰语词典（GPL-3.0 数据），请在 `pymorphy3-dicts-uk` 在 该安装的 Python 环境中。 ## 命令行访问 该[命令行](https://phishdestroy.github.io/TgWitness/zh/docs/reference/cli/)（预览版）用于读取存档文件中的脚本和代理程序。 | 变量 | 效果 | | --- | --- | | `TGWITNESS_URL` | 面板地址为 `tgwitness search`, `context`, `messages`, `stats` 和 `export`；默认 `http://127.0.0.1:8787` 当设置令牌时 | | `TGWITNESS_MCP_TOKEN` | 将连接令牌从**“集成”→“MCP**”中存档，该令牌与 MCP 客户端共享； `--token-file` 改为从文件中读取该令牌 | | `TGWITNESS_DATA` | 当未提供 `--data-dir`、URL 或令牌时，将直接读取数据目录 | ## 运行前请先验证 该单行命令会信任 HTTPS 上的初始脚本。该脚本会在安装前检查 SHA-256 以及应用程序和约束条件上的项目 RSA 签名。 您也可以先下载并验证初始脚本。 公钥为 [release-signing.pub](https://github.com/phishdestroy/TgWitness/blob/main/deploy/installer/release-signing.pub)。 其 SHA-256 为： ``` 039d98a658ccda14253e45a00335b4a68d840976d8ec18b8d4355cc7c458447d ``` 请保留来自您信任的代码库版本的此指纹。来自 同一下载服务器的校验和可检测到不匹配；独立受信任的公钥 则是验证发布签名所依据的。 请为下文中的验证下载内容准备一个新的、空的目录。 **Linux / macOS — 在一个新的、空的下载目录中运行**（需要 curl 和 OpenSSL）： ``` curl -fSLO https://get.destroy.tools/install.sh && curl -fSLO https://get.destroy.tools/install.sh.sig && curl -fSLO https://get.destroy.tools/release-signing.pub && test "$(openssl dgst -sha256 release-signing.pub | awk '{print $NF}')" = \ '039d98a658ccda14253e45a00335b4a68d840976d8ec18b8d4355cc7c458447d' && openssl dgst -sha256 -verify release-signing.pub -signature install.sh.sig install.sh && bash install.sh ``` 如果 `&&` 如果下载、密钥指纹或签名 验证失败，链条将在执行前停止。如果脚本下载与签名验证之间 发生了发布更新，则需重新下载两者。旧版安装程序会保留其不可变的包 URL。 **Windows — 运行前请检查SHA-256：** ``` Invoke-WebRequest https://get.destroy.tools/install.ps1 -OutFile install.ps1 -UseBasicParsing Get-FileHash .\install.ps1 -Algorithm SHA256 Invoke-RestMethod https://get.destroy.tools/SHA256SUMS.txt ``` 将哈希值与 `install.ps1` 行进行比较。若要进行独立的签名验证， 请使用 OpenSSL（例如在 Git Bash 中）并采用上述相同的公钥指纹： ``` curl -fSLO https://get.destroy.tools/install.ps1 && curl -fSLO https://get.destroy.tools/install.ps1.sig && curl -fSLO https://get.destroy.tools/release-signing.pub && test "$(openssl dgst -sha256 release-signing.pub | awk '{print $NF}')" = \ '039d98a658ccda14253e45a00335b4a68d840976d8ec18b8d4355cc7c458447d' && openssl dgst -sha256 -verify release-signing.pub -signature install.ps1.sig install.ps1 && powershell.exe -NoProfile -ExecutionPolicy Bypass -File install.ps1 ``` Windows 安装程序会通过 .NET 自行验证软件包签名，无需 OpenSSL。这些是独立的 RSA-3072 / SHA-256 签名，而非 Authenticode 签名。 [清单](https://get.destroy.tools/manifest.json)文件记录了软件版本、 精确的 Git 提交、不可变的发布 ID 以及每个构建产物的 SHA-256。该页面提供了 指向相应源代码的链接。清单文件和校验和列表也带有独立的 签名（`manifest.json.sig` 和 `SHA256SUMS.txt.sig`). ## 更新现有安装 **新版本发布后，下载站点会相应更新；当您 再次运行安装程序时，已安装的程序将自动更新。**该工具不提供无人值守更新程序，也不会自动重启 正在运行的集合。当前安装程序通道处于**预览阶段**；它遵循 来自 `main`发布的、经过验证的构建版本，其提交时间可能晚于 GitHub 上最近的编号版本。该页面的版本号来源于 `pyproject.toml`；其提交 和构建 ID 可区分同一预览版本内的更新。 当该特定提交通过应用程序和 安全检查，且签名包通过 Ubuntu 服务和 Windows PowerShell 安装测试后，系统将自动发布。在检查运行期间，或检查失败时， 系统将使用相同的命令继续安装之前已通过检查的构建版本。构建清单 显示当前可用的提交；在预览更新之间，版本号本身可能保持 不变。 请使用与之前相同的安装文件夹和操作系统用户。在停止数据收集后，备份完整的数据 目录； `tgwitness paths` 用于标识该数据。已签名的导出文件 并非完整的安装备份。 **Ubuntu 根目录安装位于 `/opt/tgwitness`:** ``` curl -fsSL https://get.destroy.tools/install.sh | TGWITNESS_INSTALL_DIR=/opt/tgwitness bash -s -- --no-start ``` 安装成功后： ``` /opt/tgwitness/bin/tgwitness restart /opt/tgwitness/bin/tgwitness status /opt/tgwitness/bin/tgwitness open ``` 对于 Linux/macOS 用户，请使用其原始 `TGWITNESS_INSTALL_DIR` 或 默认配置，并再次运行第一个安装命令。更新前请关闭前台 面板，更新后重新启动该面板。对于已配置的 Linux 用户 服务，请运行其 `tgwitness restart` 命令。 **Windows：**关闭正在运行的面板，重新运行 Windows 安装命令， 然后在 `bin\tgwitness.cmd` 同一安装环境。安装程序会保留数据、 会话、访问设置和签名密钥。只有当 新环境通过检查后，它才会切换启动器；安装失败时， 原启动器将保留不变。请保留升级前的备份，以应对存储格式的变更。 ## Ubuntu 上的常用命令 | 命令 | 结果 | | --- | --- | | `tgwitness open` | 当前面板 URL 和访问密钥。 | | `tgwitness paths` | 精确的程序、数据和指南路径。 | | `tgwitness guide --print` | 离线操作指南。 | | `tgwitness status` / `tgwitness logs` | 可用性/服务日志。 | | `tgwitness stop` / `tgwitness start` | 停止/恢复服务；保留数据。 | | `tgwitness token rotate` | 替换管理员密钥并结束浏览器会话。 | | `tgwitness tunnel off` | 禁用公共快速隧道；保留本地面板。 | | `tgwitness tunnel on` / `tgwitness tunnel restart` | 创建快速隧道链接 / 替换其地址。 | 请参阅[“访问权限](https://phishdestroy.github.io/TgWitness/zh/docs/reference/access/) ”了解同事令牌、会话和 IP 限制，以及 [“安装程序发布](https://github.com/phishdestroy/TgWitness/blob/main/deploy/installer/README.md#automatic-publication-from-github) ”了解从 GitHub 到 Cloudflare 的发布工作流。 ## 删除 TgWitness 本工具不提供卸载程序：只需停止面板并删除其文件夹即可。删除 data 文件夹将永久销毁日志、签名密钥、Telegram 会话以及已保存的文件。 在此之前： 1. 导出所需内容（**导出 → 下载已签名的 ZIP**），并将签名密钥 的指纹和检查点保存在本机之外。若要保留工作区本身，请在停止数据收集后复制 整个数据文件夹。 2. 请从**“您的服务器**”中删除在**“扩展功能 → 24/7 服务器**”下创建的服务器，或通过 `python -m tgwitness.cloud destroy`；服务商将持续向您收取费用，直至这些服务器被删除。 3. 请在 Telegram 的**“设置”→“设备**”中结束每个账户的会话。删除 文件并不会在 Telegram 端注销该会话。 **Ubuntu 根目录安装。**请注意数据文件夹，停止服务，然后删除 该服务、相关文件夹及快捷方式： ``` /opt/tgwitness/bin/tgwitness paths /opt/tgwitness/bin/tgwitness stop systemctl list-unit-files 'tgwitness-*' systemctl disable tgwitness- rm /etc/systemd/system/tgwitness-.service systemctl daemon-reload rm -rf /opt/tgwitness /var/lib/tgwitness- /usr/local/bin/tgwitness ``` **Linux 或 macOS 用户安装。**关闭面板。已配置的 Linux 用户服务 可通过 `systemctl --user disable --now tgwitness-`；其单位为 `~/.config/systemd/user/`。随后删除 `~/.local/share/tgwitness` （或您的 `TGWITNESS_INSTALL_DIR`) 以及 `~/.local/bin/tgwitness` 快捷方式。 **Windows。**关闭面板并删除 `%LOCALAPPDATA%\TgWitness` （或您的 `TGWITNESS_INSTALL_DIR`）。安装程序不会添加任何服务、计划任务或快捷方式。 --- # Telegram · 初始设置与配置 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/settings/ 设置向导、目标、界面层级、连接路径以及账户组共享的设置。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 设置向导、目标、界面层级、连接路径以及账户组共享的设置。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [入门指南](https://phishdestroy.github.io/TgWitness/zh/docs/reference/quickstart/) ![入门指南](https://phishdestroy.github.io/TgWitness/assets/chapter-start.svg) [账户](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/) · [连接](https://phishdestroy.github.io/TgWitness/zh/docs/reference/connection/) · [访问](https://phishdestroy.github.io/TgWitness/zh/docs/reference/access/) 新建工作区时会弹出 `/first-run`：语言与时间、界面层级、目标、 连接、Telegram 及聊天。每个答案一经 更改即会保存到服务器，因此刷新页面后可继续执行同一步骤。最后一个屏幕列出了所有答案， 并允许您返回其中的任意一个。 语言、IANA 时区、主题和级别均按操作员和工作区分别存储。 默认设置为浏览器语言、设备时区、系统主题以及 “简约”界面。更改语言后，面板会话设置将保持不变。已签名 日志中的时间永远不会改变。 `/settings` 可编辑与向导相同的记录。搜索功能涵盖主要字段、 参数和扩展表单；无需更改 权限级别即可打开隐藏字段。权限级别仅影响显示内容：服务器会自行检查权限。 集合设置和首次连接由工作区管理员负责。 | 级别 | 字段 | 侧边栏 | | --- | --- | --- | | 简单 | 仅保留必需功能 | 首页、聊天、更新、存档、设置 | | 标准 | 常用设置及说明 | 新增 Case Board、账户和访问权限 | | 专家 | 所有字段、限制及技术细节 | 新增“来源”、“扩展功能”、“咨询存档”、“参数”、“账户”、“系统日志”和“集成” | [面板指南](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/)对每个部分进行了说明。 ## 目标 | 目标 | 收藏集 | 文件 | 外部服务 | 服务器地址 | | --- | --- | --- | --- | --- | | 存档副本 | 关闭；**点击“开始**”将执行导出操作 | 照片大小上限为 20 MB | 关闭 | 自动 | | 关注聊天室 | 持续 | 照片和视频最长 60 秒 / 20 MB | 时间戳和问题通知 | 自动 | | 证据 | 持续 | 所有文件大小均不超过 1 GB | 时间戳、drand、通知 | 不，隐藏它 | 建议使用异地备份、Witness 机器人和代码检查作为证据。 存储和通知地址需要先指定目标。与外部服务交互的功能 会要求允许向 Telegram 外部发送请求；若关闭该功能， 系统将同时建议关闭时间戳、通知以及异地备份功能。 修改目标会首先显示差异，且手动修改内容可以保留。与目标 不一致的字段会标记为**“由您修改**”，并可恢复。 设置修订功能可防止已审核的差异覆盖在另一个标签页中 所做的修改。 ## 连接 **Automatic** 会先尝试公共 MTProxy 服务器，然后是 WARP，最后是直接连接， 仅当服务器地址可能被显示时才会采用直接连接。Automatic 和 WARP 均可安装 经过哈希校验的组件，并将服务器注册到 Cloudflare。WARP 使用 现有的 wgcf/wireproxy 管理器以及本地 SOCKS5 端口；系统路由表 不会被更改。当需要访问外部服务时，Automatic 会优先选择 WARP 而不是 MTProxy。 您自己的代理服务器支持 `tg://proxy`, `socks5://`, `http://` 和 `https://`。在向 HTTPS 代理发送凭据之前，会先验证其证书。 连接检查结果有效期为五分钟，并与路由、策略以及 向导回答绑定；若其中任何一项发生变更，则需重新进行检查。系统支持**“不检查就继续”** 选项，但该选项不能替代 Telegram 登录验证。所选路由 将在后台重新检查，且在连接中断后，“自动”模式会再次运行其链。当公共代理无响应时，计数器将变为红色，并触发 WARP 和重新检查 操作。 ## 账户组 同一组中的账户会共享设置。请打开**“账户”→“组和共享 设置”→“共享设置**”，或在账户的“设置”页面中**选择“组设置**”。 该组共享目标、已保存文件、时间戳、drand、问题通知、 站外副本、Telegram 外部请求、IP 模式、记录内容、复核 时间表、通知规则、报告设置、参数以及连接路径。 通知目的地、代理凭据和登录信息均按账户单独保存， 数据采集的启动和暂停操作也是如此。 - 每位成员都会关注该群组。在“设置”中，标记一个值 🔗 **来自该组** 或 ✏️ **自有值**；**恢复为组设置值** 可将其还原。 - 每次更改都会列出受影响的账户（**适用于 3 个账户中的 2 个**），并在替换原始值之前逐个 询问每个账户。未勾选的账户将保留其原始值。 - 团队未共享的参数将保持为 **不共享：每个账户保留其独立的数据**，直到您点击 **分享此值** 为止。 - **从一个账户复制设置时，**会将所选账户的值作为该组的设置。 - 当账户被移入组时，系统会询问**“采用该组的设置吗？”，**否则该账户将保留 其原有设置，并标注为 ✏️。后续添加的账户将默认采用该组的设置。 - 观察账户将保持其 IP 模式，直到被暂停为止。 每次更改都会记录在主工作区以及所有 相关成员的已签名日志中。删除一个组时，该组中的账户及其当前值将得以保留。 群组页面 `/groups/` 会显示成员列表、待处理事项以及 多个账户共同关注的聊天记录。参见[“账户组”](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#bulk-import-and-account-groups)。 ## 现有工作区 包含会话或先前已完成配置的工作区不会显示向导。 页面加载时，其值不会被目标值替换。隐藏字段不会 禁用该功能，也不会删除其值。 大小和时间估算基于最多三个选定的聊天，以及每个聊天中最多 20 条消息。 这仅为估算值：它无法预测 Telegram 的限制、特定 服务器的速度，也无法预测每个聊天中的文件内容。 --- # Telegram · 账户与会话格式 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/ 支持通过手机、二维码或授权密钥登录，可导入 Telethon、Pyrogram 或 Telegram Desktop 的会话数据，并同时管理多个账户。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 支持通过手机、二维码或授权密钥登录，可导入 Telethon、Pyrogram 或 Telegram Desktop 的会话数据，并同时管理多个账户。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [入门指南](https://phishdestroy.github.io/TgWitness/zh/docs/reference/quickstart/) ![入门指南](https://phishdestroy.github.io/TgWitness/assets/chapter-start.svg) TgWitness 通过 MTProto 协议以 **Telegram 用户账户**（而非机器人）身份登录，使用 Telethon 实现。每个账户都位于独立的工作区中（在 API 和命令行工具中称为“*工作区*”），并拥有独立的会话、消息源、日志和签名密钥。 会话文件、会话字符串和认证密钥均属于**账户授权凭证**：任何 持有者均可代表该账户进行操作。这些凭证不包含消息历史记录。 > [!警告] **请勿使用任何您无法承受损失的内容。**我们强烈建议不要连接 个人账户或其他重要账户，也不建议在您珍视的账户上 创建 API ID 或 API 哈希。 这并非因为 TgWitness 未经测试：Telegram 会以不可预测的方式限制并 永久封禁账号——仅因其认为请求量 过大，无论使用何种客户端或出于何种目的，且未提供充分的说明文档。许多封禁 都是不可逆的。 请使用专用账号。测试能否顺利进行取决于 Telegram 自身，而非 软件本身，且无法保证后续使用不会出现问题。 - [一览](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#at-a-glance) - [开始之前：API ID 和 API 哈希值](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#before-you-start-api-id-and-api-hash) - [电话号码](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#phone-number) · [二维码](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#qr-code) · [认证密钥 + DC ID](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#auth-key--dc-id) - [账户文件](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#account-files): [Telethon .session](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#telethon-session) · [Pyrogram .session](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#pyrogram-session) · [会话 + JSON 对](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#session--json-pair) · [TData](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#telegram-desktop-tdata) · [StringSession](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#telethon-stringsession) · [账户 JSON](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#account-json) - [识别您拥有的内容](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#identify-what-you-have) · [不受支持的格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#unsupported-formats) - [多个账户](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#multiple-accounts) · [确保账户文件的安全](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#keeping-account-files-safe) · [故障排除](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#troubleshooting) ## 一览 | 您拥有 | **“添加账户**”选项卡 | 您还需要 | | --- | --- | --- | | 电话号码及其登录码的获取方式 | **电话** | 若已启用双因素认证（2FA），请输入密码 | | Telegram 在另一台设备上已打开 | **二维码** | 若已启用双因素认证（2FA），请输入密码 | | `.session`文件（Telethon 或 Pyrogram） | **文件** | 可选的配套 JSON 文件，用于应用程序设置 | | `.session` + `.json`（同名） | **文件**（请同时选中） | 通常没有其他内容 | | Telegram Desktop 中的 `tdata` 文件夹 | **文件**（ZIP 压缩包） | 若已设置，则为桌面端本地密码 | | Telethon StringSession（文本、`.txt`、`.tgwitness-session`） | **文件** | 无需单独的 API 对 | | 包含会话或认证密钥的 `.json` | **文件** | 无需单独的 API 对 | | 一个授权密钥（512个十六进制字符）及其DC编号 | **认证密钥** | 可选用户 ID | TgWitness 根据文件**内容**而非文件名来识别文件。重命名文件 绝不会导致其被转换。 ## 开始之前：API ID 和 API 哈希值 您无需创建 Telegram API 应用程序即可登录。当未输入、 未导入或工作区中尚未保存任何密钥对时，TgWitness 会从其内置的 50 个公共 API 密钥对池（`tgwitness/api_pool.py`）中选择一对，优先选用 Telegram Desktop 进行新 登录，并优先保留已保存的密钥对；其余候选项将进行随机排序。 如果 Telegram 拒绝某对密钥 （`API_ID_INVALID`、`API_ID_PUBLISHED_FLOOD`、`UPDATE_APP_TO_LOGIN`），则尝试下一对， 每次登录最多尝试八对；被拒绝的密钥对将被跳过，直至重启。用于登录的密钥对将 与账户一同保存，并在此账户中重复使用。**API ID** 和 **API**哈希用于向 Telegram 标识应用程序；它们 本身并不能授权账户。 缺失的连接字段使用捆绑的 [opentele2 2.0.0 目录中的](https://github.com/DedInc/opentele2/tree/7e973bc71cd7a714ad13ac703c0895a90d36a735)确定性设备/操作系统组合： 桌面版 `2040`、Android `6`、Android X `21724`、iOS `10840`、macOS `2834` 以及 Web `2496`。 Android 的源代码构建 ID `4` 同样使用 Android 目录，该 ID 在 [Telegram Android 的 BuildVars](https://github.com/DrKLO/Telegram/blob/master/TMessagesProj/src/main/java/org/telegram/messenger/BuildVars.java) 中有明确标识。 Web 默认使用 A；若导入 `K` 应用版本后缀或 `macos` 语言包，则选择 K，而版本 `0.7.0` 则选择 Webogram。未知应用 ID 保持 Telethon 的主机 默认值。导入的字段始终优先，包括较旧的应用版本和空的 语言包。目录绝不会更改 API ID/哈希值。其版本快照会 经过明确审核，而非在登录时获取。保存的配置文件在更新后保持稳定。 `account.getAuthorizations` 报告 Telegram 保存的授权元数据；它 并非每次新调用 `initConnection` 的回显。请将其与实际发送的配置文件进行对比。 连接现有授权不会验证其对应的 API 哈希： `initConnection` 发送的是 API ID，而哈希则用于登录请求。 在进行新手机或二维码授权后，TgWitness会请求配置、最近的数据中心、 在线状态、语言（当语言包不为空时）、应用更新以及 服务条款更新，各请求间隔为0.3–1.5秒。 更新状态 会短暂地将账户标记为在线。该序列仅在登录完成时运行一次， 不会在导入、重新连接或重启时执行。授权信息会优先保存；若请求失败， 该序列将终止，不会重试或放弃登录。结果将 记录为`account.initialized`，其中包含错误名称而非响应正文。 该序列不能保证避免账户限制。 对于 `tdesktop` ，若未指定 `tz_offset` ，则使用服务器的本地 UTC 偏移量，并使用 [opentele2 算法](https://github.com/DedInc/opentele2/blob/7e973bc71cd7a714ad13ac703c0895a90d36a735/crates/opentele2-core/src/fingerprint.rs) 将其四舍五入至 900 秒 （MIT 许可；许可协议详见 `tgwitness/client_profiles.LICENSE` ）。该值在每次 连接时都会刷新，以反映夏令时变更。在所有平台上，导入的 `tz_offset` 均具有优先级，并将被精确保留，包括零值。其他 `initConnection.params` 条目将予以保留。 HTTP 登录表单接受文件导入返回的数值时区； 布尔值、分数以及超出支持范围的偏移量将被拒绝。 直接、SOCKS5 和 HTTP CONNECT 路由使用 Telethon 的 `ConnectionTcpObfuscated` （经过混淆的简化版 MTProto）。HTTPS CONNECT 保持与代理之间的 TLS 连接，并在隧道内部使用 相同的混淆传输协议。MTProxy 保留其必需的 随机化中间传输和密钥处理机制。路由切换采用 相同的选择。 混淆处理会改变数据包的帧结构；它不会向 Telegram 隐藏账户 或其客户端元数据，也不意味着能够规避相关限制。 在连接授权客户端后，TgWitness会检查配置、最近的数据中心、 当前授权状态、已审核的层级基线、语言、应用更新 以及服务条款更新。这些诊断操作在每个客户端实例中仅执行一次， 且在数据收集之前进行，结果会连同执行时间一并显示在连接详情中。 `account.connection_checked`记录结果时不包含会话哈希、IP地址、 令牌或API哈希。它们绝不会接受条款或安装更新。请求 失败或FloodWait状态将停止后续请求；缺失的结果将保持未知状态。 本地检查仍可报告其结果，而网络检查则会被跳过。 FloodWait 诊断信息会保留失败的 TL 方法、任何 Takeout/range 包装器、 服务器请求的等待时间以及 `telegram.backoff` 中的有效截止时间。 在请求暂停期间，连接详细信息会显示方法和截止时间。 该诊断信息包含自该客户端创建以来 按方法统计的客户端调用计数器；这些计数器会单独统计嵌套的对等方解析，但不计入数据包 或 Telethon 的内部重试尝试。当前计数器也可通过状态 API 中的 `collector.rpc_activity` 获取。 不包含任何请求参数、用户名、访问 哈希值或异常文本。最后一条诊断信息和完整的截止时间 在重启后仍会保留。早期没有方法记录的等待无法 追溯归因。请参阅源代码审查的[导出限制](https://github.com/phishdestroy/TgWitness/blob/main/docs/EXPORT-LIMITS.md)以及 发现与历史数据获取之间的区别。 `official_app=True`或`False`是 Telegram 的当前授权标志。这两个 值均无法确定该账户是受限、受信任还是处于观察状态。 现有的证据模式 `account.devices` 快照仍保留所有 已登录设备的历史记录；连接诊断仅保留当前设备的描述。 连接前，建议性检查会将 API 平台、语言包、 设备/操作系统和应用版本格式、移动系统区域设置，以及 Telethon 的实际 模式层与已审核的目录基线进行比对。警告会显示在服务器 日志和账户状态元数据中；它们绝不会替换导入的值或更改 模式层。 不同层级仅为兼容性审查信号，并非 账户已损坏或受限的证明。这些检查及`official_app`均不保证 Telegram认为该账户不会受到限制。断开连接的账户状态 使用已保存的配置文件，而非生成新的设备描述。 若要改用您自己的应用程序（注册该应用的账户将面临风险； [参见 “为何要使用内置 API 池？](https://github.com/phishdestroy/TgWitness/blob/main/docs/PROJECT-GUIDE.md#connect-a-telegram-account)”）： 1. 打开 [my.telegram.org](https://my.telegram.org)，并使用您拥有的任意手机号码 登录。验证码将发送到 Telegram 应用中，而非通过短信。 2. 选择 **API 开发工具**。 3. 创建应用程序：任意标题和简称（5–32 个字母），平台为**桌面版**。 URL 和描述可留空。 4. 复制 **App api_id**（一个数字）和 **App api_hash**（32 个十六进制字符）。 在登录表单下方的面板中，有“**API ID + 哈希**”字段。您可以在 **API ID** 字段中粘贴一组 `api_id:api_hash`，两个字段将自动填充。一组 即可用于您所有的账户。成功登录后，该信息将以加密形式保存在 该工作区中，且绝不会发回浏览器。 涉及三种不同的凭证： | 秘密 | 打开 | 托管位置 | | --- | --- | --- | | 面板令牌 | TgWitness 网页控制面板 | 数据目录中的 `panel-token.txt`，或 `TGWITNESS_TOKEN` | | API ID + 哈希值 | 本身不包含任何内容；仅用于标识该应用程序 | 可通过 my.telegram.org 进行内置配对、导入设置或使用您自己的应用程序 | | 账户授权 | Telegram 账号 | 可通过手机/二维码登录创建，或作为会话导入 | 如果必须通过代理访问 Telegram，请先在 **“账户”→“设置”→“连接设置”→“更改连接路径**”中进行设置。 ## 电话号码 1. 打开**“账户**”选项卡，选择**“手机**”标签页，并以国际格式输入号码， 例如 `+44 7700 900123`。空格和连字符将被自动去除。 2. 点击**“继续”**。API ID 和哈希值可留空。 3. 输入 Telegram 发送的验证码（通常发送至 Telegram 应用；短信接收无法保证）。 4. 如果该账户启用了双重验证，请输入该密码。这并非控制面板 令牌，也不是设备密码。 5. 登录后查看显示的账户 ID，然后选择消息来源。 登录凭据和双因素认证（2FA）密码绝不会写入磁盘。 ## 二维码 当该账户已在手机或另一台计算机上登录时，请使用此功能。 1. 点击**“QR 码**”→ **显示 QR 码**。API ID 和哈希值可留空。 2. 在已登录的设备上：**设置 → 设备 → 关联桌面设备**，扫描二维码 并确认。 3. 若 Telegram 要求输入双因素认证（2FA）密码，请在 TgWitness 中输入该密码。 该二维码是在本地生成的。二维码会过期；请点击**“生成另一个二维码** ”重新尝试。锁定面板、切换工作区或开始另一轮登录操作将取消 待处理的二维码。 ## 认证密钥 + DC ID 授权密钥（Auth Key）是每个 Telegram 会话背后的 256 字节原始授权数据，以 **512 个十六进制字符**的形式表示，并附带数据中心编号 **DC 1–5**。 1. **“Auth key**”选项卡。请粘贴完整的密钥；包含“`…`”的缩短版密钥无法使用。 2. 请选择随密钥提供的 DC ID。 3. 可选输入**用户 ID**。若 Telegram 报告的 账户信息不一致，TgWitness 将拒绝连接。 4. Press **Connect 账号**。 授权密钥（512 个字符）并非 API 哈希（32 个字符）。同一密钥也可 以 JSON 格式导入，详见[“账户 JSON](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#account-json)”。 ## 账户文件 打开**“添加账户”→“文件**”，选择最多**四个属于同一账户的文件**（总大小不超过 **8 MiB**），然后点击**“连接账户**”。 **文件**、**授权密钥**和批量导入表单会在连接前显示并行会话警告。 默认情况下，导入的授权将被重复使用。当其密钥在此处使用时，请保持原始 客户端处于关闭状态。**文件**和**授权密钥**还提供 **创建独立授权选项**，具体说明见下文。批量导入仍使用 直接模式。手机和交互式二维码登录会创建独立的授权。 导入表单中会持续显示该警告标题；当提供文件或密钥/会话字符串时，其完整说明会 自动展开。阅读后可将其折叠， 以便在手机上继续使用文件选择器和连接控件。 - 文件在您的 TgWitness 服务器**内存中**进行转换。上传内容不会被存储， ZIP 文件不会解压到磁盘，也不会连接任何外部服务。 - 生成的会话记录随后将与 Telegram 进行核对。如果文件中包含用户 ID， 则该 ID 必须与 Telegram 报告的账户信息一致。 - 描述不同账户或不同 API 凭据的文件将被拒绝 而非仅选择其中一个。 - **“密码”或“会话文本**”字段包含 TData 本地密码字段，该字段用于粘贴 StringSession 以及**在未登录的情况下读取文件**（无需 联系 Telegram 即可填写表单）。 ### 创建独立授权 请选择“在连接前**创建独立授权**”并导入文件，或 选择授权密钥。TgWitness会短暂连接导入的捐赠者设备，利用其批准 新客户端的二维码登录令牌，并在批准后立即断开与捐赠者的连接。 新客户端拥有独立的授权密钥和单独选择的桌面 配置文件。由捐赠者提供的 API 凭据和设备配置文件仅用于 与捐赠者的连接。现有授权不会被注销或撤销。 **在此步骤中，请确保捐赠者的原始客户端保持完全关闭状态。**初始 连接仍使用其复制的密钥，因此此模式无法消除该初始 并行使用风险。一旦新授权连接成功，所有者即可重新打开 原始客户端，并独立使用两者。交互式**二维码**登录允许 原始客户端批准登录，而无需在此处复制或连接其密钥。 如果 Telegram 要求进行双因素认证（2FA），此模式会使用所选 JSON 文件中的 `twoFA`（若存在）， 否则将要求输入密码。若导入的密码被拒绝，系统将返回密码输入表单。 密码不会被保存。候选密钥以加密形式保存在 `independent_login.enc` 中，包括数据中心迁移期间的变更。中断后， 请选择相同的捐赠者并选中此选项以恢复已保存的候选密钥。 该工作区仍为该账户保留；即使导入失败， 新工作区也不会被删除。请保留其数据目录和保险库密钥。最终的凭据和 `account.authorized`日志记录包含导入方法、输入格式以及 捐赠者 API ID，但不包含捐赠者密钥或密码。 2026年11月5日，一个专用账户通过了Telethon、Pyrogram 和TData捐赠者的实时验证：2FA验证完成、生成独特的新授权密钥、捐赠者与新客户端的并发访问 ，以及公共频道的阅读操作。 在 Telethon 案例中， 系统还在密码输入步骤中断后恢复了已保存的候选会话。每次新的 授权都完成了登录后的六个初始化请求，且其签名的 日志已通过验证。原始会话在提供的四种格式中均保持可用。 Telegram 的 [RPC 错误数据库](https://core.telegram.org/api/errors.json)将 `FRESH_CHANGE_ADMINS_FORBIDDEN` 与更改管理员相关联，`FRESH_CHANGE_PHONE_FORBIDDEN` 与更改电话号码相关联，而 `FRESH_RESET_AUTHORISATION_FORBIDDEN` 则与 撤销其他会话、更改其有效期或注册通行密钥相关联。 `SESSION_TOO_FRESH_*`和`PASSWORD_TOO_FRESH_*`涉及所有权转移以及 收入或礼品的提取。这些并非数据收集操作；新登录并不 意味着全面禁止在24小时内读取数据。导出操作可能会单独返回 `TAKEOUT_INIT_DELAY_*`。TgWitness会保留服务器请求的暂停状态，且不会自动重试 令牌接受或撤销会话以规避限制。 ### Telethon `.session` | | | | --- | --- | | 产品简介 | 基于 Telethon 的工具生成的 SQLite 数据库，例如 `my_account.session` | | 获得以下机构认可： | 表格 `sessions`（连同 `dc_id`、`server_address`、`port`、`auth_key`）和 `version` = 7 或 8 | | 要求 | 仅有一行授权会话记录；一个封闭且完整的数据库 | 请先关闭创建该文件的程序。如果其旁边存在 `my_account.session-journal` 或 `my_account.session-wal`，则表示数据库尚未最终确定：请正常打开并 关闭原始客户端。删除这些辅助文件可能会导致副本损坏。 ### Pyrogram `.session` | | | | --- | --- | | 产品简介 | 基于 Pyrogram 的工具生成的 SQLite 数据库 | | 获得以下机构认可： | 表 `sessions` 包含 `dc_id`、`auth_key`、`test_mode`、`user_id`、`is_bot`；`version` = 2 或 3 | | 要求 | 生产网络上仅允许一个授权**用户**会话。机器人和测试数据中心（test-DC）会话将被拒绝 | 登录时，系统会将存储的用户 ID 与 Telegram 进行比对。 ### 会话 + JSON 对 账户通常以两个同名文件的形式分发，例如 `447700900123.session` 和 `447700900123.json`。请同时选中**这两个文件**。 - 根据 JSON 信息，TgWitness 使用 `app_id`/`api_id` 和 `app_hash`/`api_hash`，因此您 通常无需手动输入 API 凭据。 - 连接配置文件使用 `device_model`（别名 `device`）、`system_version` （别名 `sdk`）、`app_version`、`lang_code`、`system_lang_code`（别名 `system_lang_pack`）、 `lang_pack` 以及可选的 `tz_offset`（以秒为单位，相对于 UTC 的偏移量，范围为 -43200 至 50400）。 用户提供的字段优先于生成的默认值和面板/浏览器的 语言设置。冲突的别名将被拒绝。解析后的配置文件将保存在 加密的工作区凭据中，并在重启后被重复使用，其中包括其应用版本。 - `phone`、代理设置和设备令牌将被**忽略**。`twoFA`仅在 选择**创建独立授权**时为只读；直接导入时将忽略该字段。 - 不包含受支持授权字段的 JSON 仅为元数据。请添加其会话 文件，或继续使用手机或二维码登录。包含受支持会话或 授权密钥的 JSON 可独立完成授权；详见[账户 JSON](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#account-json)。 ### Telegram 桌面版 (TData) TData 是 Telegram Desktop 应用程序（来自 desktop.telegram.org 的跨平台 应用程序）中的 `tdata` 文件夹。 | 系统 | 默认位置：`tdata` | | --- | --- | | Windows | `%APPDATA%\Telegram Desktop\tdata`（便携版 Telegram：位于 `Telegram.exe` 旁边） | | Linux | `~/.local/share/TelegramDesktop/tdata` | | macOS | `~/Library/Application Support/Telegram Desktop/tdata` | 导入方法： > **并行会话警告。**直接导入 TData 会复用 Telegram Desktop 的授权 密钥。请勿在 Desktop 和 TgWitness 中同时使用该密钥。Telegram 可能会通过 `AUTH_KEY_DUPLICATED` 使授权失效，导致两个实例均无法使用，直至重新登录。 > > > > 请完全退出 Desktop（包括其系统托盘进程），并在 TgWitness 使用导入的会话期间保持该副本关闭。**请退出程序，切勿注销或撤销会话：** 撤销操作也会使导入的副本失效。如果您需要同时运行两个客户端， 请选择**创建独立授权**，并在 新登录成功之前保持 Desktop 关闭，或者通过手机或二维码登录 TgWitness。建议使用 专用账户，但这并不能确保克隆密钥在并行使用时是安全的。 > > > > 这同样适用于导入的 `.session` 文件、StringSession文本及认证密钥十六进制值。 其他拥有独立创建的授权的客户端可以保持登录状态。 请参阅[Telegram的AUTH_KEY_DUPLICATED文档](https://core.telegram.org/api/errors#406-not-acceptable)。 1. 完全退出 Telegram Desktop。 2. 从 `tdata` 中提取仅包含以下两项内容的 ZIP 压缩包： - `key_datas` - 其旁以 `s` 结尾的 16 个字符的文件，通常为 `D877F783D5D3EF8Cs` 将整个文件夹及其媒体缓存打包为 ZIP 文件通常会超出限制 （512 条记录，解压后 32 MiB）。 3. 在**“文件**”中选择该 ZIP 文件。如果 Telegram Desktop 设置了**本地密码**，请先在 **“密码”或“会话文本”栏**中输入该密码。这并非双因素认证（2FA）密码。 支持功能：每个存档仅限一个账户，采用现代`key_datas`/`key_data0`/`key_data1`存储技术， 本地密码保护。不支持功能：包含多个已登录账户的文件夹、旧版桌面 布局、受密码保护的ZIP文件，以及独立的原生macOS应用“Telegram for macOS”。 ### Telethon StringSession 一行文本，通常以 `1` 开头，长度约为 350 个字符。请将其 作为 `.txt` 或 `.tgwitness-session` 文件（最大 4 KiB）加载，或将其粘贴到 **“通行码”或“会话文本**”下方。仅接受 Telethon 字符串；Pyrogram 和 TDLib 字符串采用不同的格式。 ### 账户 JSON 一个 JSON 对象，大小不超过 **64 KiB**，存储在以 **`.json`** 结尾的文件中。 | 字段（别名） | 含义 | | --- | --- | | `api_id` (`app_id`) | 应用程序 ID，一个正数 | | `api_hash` (`app_hash`) | 应用程序哈希值，32个十六进制字符 | | `string_session`（`session_string`、`session_str`；旧版 `session`） | Telethon StringSession 文本，并非文件名 | | `auth_key` (`auth_key_hex`) + `dc_id` | 完整的 512 个字符的认证密钥和 DC 1–5 | | `user_id` (`id`) | 可选；在保存授权之前，需与 Telegram 进行比对验证 | | `device_model` (`device`) | 连接设备说明 | | `system_version` (`sdk`) | 连接操作系统版本 | | `app_version` | 发送至 Telegram 的应用程序版本 | | `lang_code`, `system_lang_code` (`system_lang_pack`), `lang_pack` | 客户端语言、系统语言和客户端语言包；允许使用空的`lang_pack` | | `tz_offset` | 可选的 UTC 偏移量（以秒为单位），通过 `initConnection.params` 发送；整数或十进制整数字符串 | 如果同时存在别名和主名称，两者必须一致。显式的 Telethon 会话字段优先于其他格式的通用 `session` 数据块。如果 两者都包含可识别的 Telethon 会话，则必须描述相同的授权。 如果没有显式字段，`session` 必须是有效的 Telethon StringSession。示例： ``` { "app_id": 1234567, "app_hash": "0123456789abcdef0123456789abcdef" } ``` ``` { "api_id": 1234567, "api_hash": "0123456789abcdef0123456789abcdef", "auth_key": "REPLACE_WITH_ALL_512_HEXADECIMAL_CHARACTERS", "dc_id": 2, "user_id": 123456789 } ``` 第一个示例仅需填写 API 凭据；您可通过手机或二维码登录，或添加会话 文件。不支持批量列表（即账户的 JSON 数组）。 ## 识别您拥有的内容 | 您会看到 | 它是一个 | 用法 | | --- | --- | --- | | `*.session`；在文本编辑器中打开后，顶部显示为 `SQLite format 3` | Telethon 或 Pyrogram SQLite | **文件**（自动检测） | | 一个名为 `tdata` 的文件夹，其中包含 `key_datas` | Telegram 桌面版 TData | 将两个文件打包为 ZIP 文件，然后**进入“文件”** | | 以 `1` 开头的一行文本，约 350 个字符 | Telethon StringSession | **文件** | | `*.json` 搭配 `app_id`/`app_hash` | 配套元数据 | **文件**及其会话 | | `*.json` 搭配 `auth_key` 或 `string_session` | 账户 JSON | **文件** | | 512 个字符 `0-9a-f` | 授权密钥 | **认证密钥** | | 32 个字符 `0-9a-f` | API 哈希值 | **API ID + 哈希值** | | 来自 TDLib 应用的 `td.binlog` 或 `db.sqlite` | TDLib 存储 | 不支持 | | `123456789:AA…` | 机器人令牌 | 不支持 | ## 不受支持的格式 | 格式 | 备选方案 | | --- | --- | | TDLib 存储（`td.binlog`）和 TDLib 导出功能 | 通过手机或二维码登录 | | Pyrogram 会话**字符串** | 请使用 Pyrogram `.session` 文件，或通过手机/二维码扫描 | | TData 包含多个已登录账户 | 请在 Telegram Desktop 中注销其他账户，或使用各账户各自的会话文件 | | 机器人令牌 | 不支持：TgWitness 以用户账户身份进行监控 | | 包含大量账户的 CSV/JSON 列表 | 通过**账户 → 导入账户**导入受支持的会话文件，或在独立的工作区中通过手机号/二维码登录 | | 测试数据中心（Test-DC）或机器人会话 | 请使用正式版用户账户 | ## 多个账户 点击账户选择器旁边的 **+**，或打开 **“账户” → “设置” → “连接设置” → “工作区**”，输入标签并 登录。 - 支持任意数量的工作区，包括主工作区。每个工作区都有独立的会话、代理 路由、消息源、捕获策略、日志、签名密钥、检查点和导出功能。 - 切换显示的工作区不会暂停其他工作区。 - 日志始终与创建它的账户绑定。使用其他 账户登录需要另一个工作区，且一个账户不能分配给两个 工作区。 - 主面板令牌可控制所有工作区。[授予的访问权限](https://phishdestroy.github.io/TgWitness/zh/docs/reference/access/)可将其他用户的访问范围限制在选定的账户和聊天群组内，并可设置独立的权限和会话限制。 - **账户会**重命名一个工作区，并删除一个已添加的工作区，连同其会话、日志、 来源和签名密钥一并删除。主工作区无法从面板中删除。 ### 批量导入和账户分组 使用**“账户”→“导入账户**”可添加多个账户，按文件基名配对文件 并查看每个登录结果。每个账户都有独立的工作区。 “组”可将相关账户集中管理，同时不会合并其会话、密钥或 证据。在**“账户**”页面中**点击“开放组**”可跳转至其页面： `/groups/`: - **账户:**每位成员的连接路径、观察记录和最后一条消息，并提供 **“全部**启动”和**“全部暂停”功能**。 - **需要关注:**已注销、不可用或存在 连接、接收、来源或媒体问题的账户；每个名称均链接至其卡片。 - **多个账户可见的聊天记录包括：** 共享来源、正在查看这些记录的账户以及 可用工作区观察期间（最长七天）内的中断情况。**使用 N 个账户进行导出时，** 会将频道或超级群组的导出内容分配给这些账户，并为一个存档文件签名。 - **导出组:**包含一个 ZIP，其中包含每个账户的已签名导出文件，位于 `accounts/` ，并 `manifest.json` 列出其SHA-256和密钥指纹，由主 工作区在 `manifest.signature.json`。请使用 `python -m tgwitness.verify` 并使用该账户的可信指纹进行验证。 成员共享群组的设置；单个账户可保留其自身的设置值。 请参阅[共享设置](https://phishdestroy.github.io/TgWitness/zh/docs/reference/settings/#account-groups)、 [导入与群组指南](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Accounts.md#import-accounts-and-share-settings) 以及 [MTProxy 数据池仪表盘](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Proxies.md#pool-dashboard-and-custom-sources)。 ## 退出登录 **“账户 → 退出 Telegram**（暂停监控）”会要求 Telegram 结束该 会话，因此该会话也会从账户的“**设置 → 设备**”中消失，并从 工作区保险库中移除。日志、来源、设置和签名密钥将保留，且 日志会记录此次退出操作。 该工作区仍归属于其账户：只有该 账户才能再次连接到它。如果 Telegram 没有响应，该会话仍会在此处被移除， 面板上也会显示相应提示；请在 Telegram 的**“设置”→“设备**”中结束该会话。 ## 确保账户文件的安全 - 请将每个 `.session`、TData ZIP、StringSession、Auth Key 和账户 JSON 视为 密码。TgWitness 会将导入的授权信息保存在其加密保险库中；您可以在 之后删除原始文件。 - 请勿在两个程序中同时运行同一授权。Telegram 可能会撤销该授权 (`AUTH_KEY_DUPLICATED`)，导致两个程序均无法运行。 - 已过期或被撤销的会话无法通过转换恢复。请重新登录。 ## 故障排除 | 消息或症状 | 操作指南 | | --- | --- | | *无法读取此会话。请关闭其原始客户端……* | SQLite 文件处于打开状态或未完成状态（`-journal`/`-wal` 旁路文件）。请正确关闭原始程序，然后重新复制该文件。 | | *支持的 Telethon SQLite 模式：7 和 8* / *Pyrogram … 2 和 3* | 该文件由一个非常旧或未知版本的库生成。请改用手机/二维码登录。 | | *仅支持授权的生产环境用户会话* | 该 Pyrogram 文件属于某个机器人或测试网络。 | | *TData 存档已超过 512 条记录或 32 MiB* | 仅包含 ZIP 文件 `key_datas` 和 `D877F783D5D3EF8Cs`，不包含整个文件夹。 | | *无法解密 TData。请检查桌面本地密码* | 在**“密码”或“会话文本**”栏中输入 Telegram 桌面版的本地密码。 | | *每次仅导入一个 TData 账户* | Telegram Desktop 包含多个账户；请参阅[“不受支持的格式”](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#unsupported-formats)。 | | *选定的文件描述了不同的账户或 API 凭据* | 仅选择一个账户的文件。 | | *JSON 中未包含任何受支持的 API 凭据或授权信息* | 请检查 [Account JSON](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#account-json) 中的字段名称。 | | *仅限 API 元数据* | 该 JSON 文件中未包含会话信息。请添加 `.session` 文件，或使用手机/二维码。 | | *Auth Key HEX 必须包含全部 512 个十六进制字符* | 密钥被截断或包含`…`。 | | 账户 ID 与导入的账户不匹配 | 该文件的用户 ID 与 Telegram 报告的不一致；该文件属于另一个账户。 | | 该账户已属于另一个工作区 | 请打开该工作区，而非重复添加该账户。 | | 已连接，但**“来源**”中的聊天列表中缺少一个私人群组 | 检查成员资格。筛选器会检查前 1,000 个对话；请在**“参数**”下提高该限制。 | | 代理连接失败 | 检查路由和 IP 模式。自动模式MTProxy会尝试其他可用的入口。隐藏地址模式会等待；直接模式作为最后手段，可在配置的延迟后直接连接。参见[路由模式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/connection/#ip-modes)。 | 另请参阅：代理和加密的[连接与安全](https://phishdestroy.github.io/TgWitness/zh/docs/reference/connection/)设置， 以及登录后数据采集的具体[工作原理](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/)。 --- # Telegram · 访问与权限 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/access/ 设置账户和聊天室的访问权限范围，选择权限类型，限制会话和 IP 地址，并撤销访问权限。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) Translation coverage: this edition includes material from the English original. 设置账户和聊天室的访问权限范围，选择权限类型，限制会话和 IP 地址，并撤销访问权限。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [入门指南](https://phishdestroy.github.io/TgWitness/zh/docs/reference/quickstart/) ![入门指南](https://phishdestroy.github.io/TgWitness/assets/chapter-start.svg) 可授予审阅者访问某个聊天记录的权限，授予分析师导出案件的权限，或授予 操作员对选定账户的控制权。每个人都会获得专属令牌。主 控制面板的令牌由管理员持有。 [账户设置](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/) · [连接路径](https://phishdestroy.github.io/TgWitness/zh/docs/reference/connection/) · [安全模型](https://phishdestroy.github.io/TgWitness/zh/docs/reference/security/) ## 两个应用场景，两种不同的任务 **采集范围**决定了账户的记录内容：选定的聊天、Telegram 文件夹或整个账户。**访问范围则**决定了其他用户可以查看和使用哪些已记录的 账户和聊天。授予访问权限并不意味着加入 Telegram 聊天、开始采集或授予 Telegram 账户权限。 访问权限可打开选定的工作区、其中选定的聊天、所有 工作区，或某个 [账户组](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/#bulk-import-and-account-groups)中的所有账户。**所有工作区， 包括后续添加的工作区**，也涵盖未来的账户。组访问权限同样 涵盖后续添加到该组的账户。若需将某个 案例的访问范围限定在特定工作区内，请明确选择相应的工作区。 ## 授予某人访问权限 1. 以主管理员身份登录并打开**“访问”页面**。 2. 在“**授予某人访问权限**”下，请输入一个您在日志中能认出的名字。 3. 选择工作区，并在必要时选择具体的聊天室。 4. 选择此人可能采取的行动。**操作视图**始终包含在内。 5. 根据需要设置有效期、登录/会话限制以及允许的地址。 6. 点击**“创建访问权限**”。请立即复制该令牌：该令牌仅显示一次。 7. 请私下发送控制面板地址和令牌。收件人只需在常规登录页面输入该令牌 即可；他们无需您的主控制面板令牌，也无需 Telegram 会话。 请在单独的浏览器会话中打开包含已生成令牌的面板，并在移交前检查 可见的聊天记录及允许的操作。 Access names remain in encrypted local storage and are resolved by the administrator's panel. Names are omitted from new access and workspace-creation audit records; existing signed records keep their original fields. ## 选择权限 如需进行纯文本的公开演示，请使用**“公开展示**”而非普通 审阅者访问权限。它会显示明确选定的公开频道、保留的编辑和 删除记录，以及经过签名的统计数据，其中作者字段将被遮盖，文件将在 API 边界处关闭。[创建并验证展示内容](https://phishdestroy.github.io/TgWitness/zh/docs/reference/showcase/)。 | 许可 | 功能介绍 | | --- | --- | | `view` | 可查阅获准访问的聊天记录、捕获的消息、个人资料、文件以及经过筛选的日志记录。这些内容始终包含在内。 | | `export` | 允许导出聊天记录和档案。导出整个工作区的证据需要具备对整个工作区的访问权限。 | | `sources` | 管理消息源、快照和个人资料捕获。受聊天限制的访问权限仅限于允许的聊天；全账户范围的消息源发现和范围设置保持关闭状态。 | | `collect` | 启动或停止采集器。由于采集操作会影响该账户，因此需要整个工作区的访问权限。 | | `interact` | 在访问权限范围内执行受支持的 Telegram 交互操作。受限于聊天范围的访问权限无法使用全账户范围的链接预览功能。 | | `settings` | 可更改采集设置、时间戳、通知、异地副本及各项参数。需具备整个工作区的访问权限。 | | `account` | 登录或退出 Telegram 并管理连接路径。需要整个工作区的访问权限。 | | `board.read` | 仅在允许的工作区和聊天记录内阅读“案件板”笔记。 | | `board.write` | 可添加书签、高亮标记、片段、评论以及“已打开”/“已审查”状态。此外还需使用 ``board.read`` 功能。 | | `board.manage` | 管理数据集、团队最终状态以及其他参与者的卡片。此外还需要对白板的读写权限。 | Only the main administrator can download the off-site replica recovery key. Delegated `settings` or `account` access does not grant that key. 权限和范围将一并核查。勾选某项权限不会 打开其他聊天记录，也不会为仅限特定聊天记录的访问权限解锁工作区范围的操作。 若要进行并行导出，访问权限必须涵盖所有选定 账户中的被导出聊天。已授予的访问权限无法创建新访问权限、管理他人的 会话或打开管理员控制台。 ### 三种实用的配置方案 | 人物 | 范围 | 权限 | | --- | --- | --- | | 审稿人 | 某案例的记录聊天内容 | `view` | | 分析师正在准备工作交接 | 待调查和导出的聊天记录 | `view`、`export`；仅当需要通过 Telegram 进行操作时才添加 `interact` | | 采集操作员 | 精选完整工作区 | `view`、`sources`、`collect`；仅在需要时添加 `settings` 或 `account` | “访问”表单的初始预设还包括“案件看板”：审核员可读取、分析师可读取 和写入，操作员可进行管理。预设仍可编辑，且现有权限不会 自动扩展。有关继承的聊天范围和导出隐私设置，请参阅[“案件看板”](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-board/)。 ## 限制与会话 | 设置 | 工作原理 | | --- | --- | | 并行会议 | 将同时在线会话数限制在 1–100 之间。达到上限时，拒绝下一次登录请求或终止最旧的会话。 | | 允许登录 | 限制使用该令牌成功启动会话的次数。即使最后一次允许的登录已被使用，现有会话也不会因此终止。 | | 有效期至 | 访问权限设有绝对有效期。过期的访问权限无法登录或继续发起请求。 | | 无活动记录 | 会话闲置超时，范围从 5 分钟到 30 天。成功请求会延长该时限；打开的面板可通过轮询保持活动状态。 | | 允许的地址 | 接受特定的 IP 地址或 CIDR 子网。若未填写，则允许任何地址，除非已启用首次登录绑定功能。 | | 绑定至首次登录 | 首次成功登录后，系统将锁定该访问的授权地址。 | IP 地址是应用程序所识别的客户端地址。若位于反向代理或 隧道之后，请在依赖 IP 规则之前，先检查**“打开的会话**”中显示的地址： 否则，可能会出现多名用户看似共享同一代理地址的情况。 ## 更改或撤销访问权限 在**“已授予的访问权限**”下编辑某条目，以更改其作用域、权限或限制。 后续请求（包括 来自已打开会话的请求）将验证作用域和权限的变更。撤销访问权限将终止其会话 并使已签发的令牌失效。通过**“打开的会话**”，管理员还可以 在不撤销整个访问权限的情况下终止单个会话。 Saved export copies retain their creator, workspace, chat scope and required permissions. An issued access can list or download its own copies only while those permissions still apply; copies containing Case Board also require `board.read`. The administrator can retrieve all copies. Older copies without this metadata and group bundles are administrator-only. Download tickets and prepared file responses recheck access after preparing the file, before sending its bytes. Each access, including the administrator, can hold ten pending download tickets per workspace; the workspace-wide limit is 1,000. Tickets expire after 120 seconds and are single-use. 撤销操作无法召回用户已下载的文件。注销、 锁定面板或结束会话均不会停止正在运行的收集器。 ## 管理员可见的内容 审核员和分析师收到的数据采集进度信息中不包含代理端点、 池诊断信息、服务器路径或原始连接错误。连接诊断 需要对整个工作区拥有`account`权限。读取通知、 异地副本和参数设置需要`settings`权限。 访问会话中不会保留完整的浏览器User-Agent字符串。升级后， 这些字符串也会从可变会话缓存中移除。控制面板进程日志会屏蔽 IP字面量、URL凭据和标记机密。本地服务日志和 先前已签名的日志记录不会被重写。访问规则和已签名的 登录记录仍使用客户端地址。 ### 替换主密钥 使用 **Access → 我的权限 → 重新签发管理员密钥**，或在控制面板运行时从受管安装环境中运行 `tgwitness token rotate`。 所有现有浏览器会话将终止，包括使用同事 令牌打开的会话。请求的浏览器将获得一个新会话；请在隐藏新管理员 密钥之前将其保存下来。已签发的同事令牌在被单独撤销前始终有效。 使用 `TGWITNESS_TOKEN` 的安装环境必须修改该环境设置并重启。 ### 请求与代理边界 The API admits up to 600 requests per minute per client and credential family: panel, archive/MCP or witness. Authentication cooldowns are separate for these families. Ten rejected authentications within a minute start an exponential cooldown, from one second up to five minutes. A failed attempt after the cooldown increases it; ten minutes without a failed attempt resets escalation. Rejections return HTTP 429 and `Retry-After`. Limits are in memory, shared across workspaces in one panel process; restart clears them. Live streams are limited to four per bearer token and 32 for the panel process. Opening a stream also consumes the API request budget. Request bodies have a 60-second receive deadline, reduced to 10 seconds for login, demo access, archive API and witness-head paths, or 8 seconds for MCP transport. Each application permits four unfinished bodies per client address, with overall limits of 32 and 64 MiB of reserved route allowances. Requests without bodies do not consume these slots. Oversized bodies return 413, timed-out bodies return 408, and exceeded client capacity returns 429 with `Retry-After: 1`. Exhausted overall body capacity returns 503 with `Retry-After`. 除非实际的 TCP 对等方属于 `TGWITNESS_TRUSTED_PROXIES`（以逗号分隔的 IP 地址或 CIDR 范围），否则将忽略转发 IP 报头。将 `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 完整性元数据。导入映射还 涵盖了在支持 import-map 完整性的浏览器中本地导入的 JS 模块。 动态生成的语言响应是独立的。这些检查可检测 相对于交付页面进行的资源替换；但无法建立对 可能同时替换页面及其哈希值的受损服务器的信任。 **自启动以来生成的日志**将进程日志与每个 工作区的日志活动相结合：登录、拒绝、路由变更和操作员操作。这是一个 针对当前进程的内存控制台，而非每条消息的永久副本。 高频消息事件会保留在日志中，而非填满控制台。 授予、更改和撤销访问权限，以及启动或结束会话，也会生成 经过签名的`access.*`日志记录。这些记录中不包含令牌。 已发放的令牌和会话凭据将作为哈希值保存在加密保险库中。 ****主要管理员与信任边界**** 主面板令牌不受限制。使用该令牌进行浏览器登录会创建会话， 这些会话受管理员配置的会话限制约束。直接发送 主令牌的脚本仍保留完全访问权限，且不计入浏览器会话。 这是单个安装环境中的应用层访问控制。所有工作区共享 服务器进程；这并不意味着与主机管理员隔离。请确保主 令牌、Telegram 会话、签名密钥和数据目录的私密性。见证令牌 是一个独立的检查点/健康凭证，而非面板访问令牌。 --- # Telegram · 连接、代理和数据保护 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/connection/ 身份验证、自动代理池、IP 模式、备用策略、外部请求及密钥存储。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 身份验证、自动代理池、IP 模式、备用策略、外部请求及密钥存储。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [部署与恢复](https://phishdestroy.github.io/TgWitness/zh/docs/reference/deployment/) ![部署与恢复](https://phishdestroy.github.io/TgWitness/assets/chapter-operate.svg) 本文档描述了 TgWitness 0.8.0 的行为及其限制。身份验证、 源访问、网络连接和捕获完整性属于各自独立的状态。 有关登录步骤、文件格式和多账户管理，请先参阅 [“账户与会话格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/)”部分。有关事件策略和重启 行为，请参阅[“数据采集原理”部分](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/)。 ## 连接设置指南 在 **Connection** 中，管理员可选择 **该账户**、**一个账户 组** 或 **所有账户**，然后选择一条路由。**“审查选择”** 列出了 受影响的账户。**“准备并检查”** 测试建议的路由，同时不更改 已保存的路由。**“应用已检查的连接”** 再次检查，如有必要则暂停监控， 保存路由并恢复已运行的监控。 它绝不会在先前处于空闲状态的账户中启动数据收集。历史数据下载仍处于 暂停状态，可单独恢复。切换前请暂停正在进行的导出操作。 群组更改默认会为每个账户保留其独立路径。仅当预览列表中显示了您期望的更改时， 才应清除该选项。 应用程序会报告每个 账户的结果；这并非跨数据库的“全有或全无”式操作。若 切换失败，该账户将恢复之前的设置。恢复失败的情况会 明确显示。预览有效期为十分钟，且连接 设置或群组成员资格的更改需要重新检查。 | 路径 | TgWitness 管理的内容 | | --- | --- | | 直接 | 来自主机的连接；未检测到外部主机 VPN，也未强制执行。 | | VPN | 每个账户仅有一个全隧道 WireGuard 配置文件，由本地用户空间中的 SOCKS5 进程承载。不安装任何主机接口或驱动程序。 | | 我的代理 | SOCKS5、HTTP CONNECT 或 MTProxy 凭据。SOCKS5/HTTP 字段可填写 URL。选择多个账户时，将共享此处输入的代理。 | | 公开版 MTProto | 现有池分配Telegram路由。在高级设置中配置单独的合适代理之前，外部请求将被禁用。 | | WARP | 为每个选定的账户建立独立的本地隧道，并将 WARP 注册信息和 WireGuard 配置文件保存在该账户的保险库中。 | 当前路由检查使用全新的未认证Telegram传输通道，而非 该账户的会话。对于支持HTTP的路由，它还会请求通过该路由进行Cloudflare的HTTPS 追踪，并显示其报告的出口IP、国家、WARP状态 以及检查时间。 测得的延迟是Telegram连接建立时间， 而非ICMP ping。除非跟踪报告显示WARP处于活动状态，否则WARP准备将失败。 这些检查旨在验证连通性，而非捕获消息的 真实性或完整性。仅凭本地进程正在运行，并不代表出口检查成功。 ### 便携版 WARP 和 WireGuard 这是一个 **非官方的 WARP 集成**，使用 [wgcf 2.3.1](https://github.com/ViRb3/wgcf/releases/tag/v2.3.1) 和 [wireproxy 1.1.3](https://github.com/windtf/wireproxy/releases/tag/v1.1.3)。 管理员需在首次下载或 WARP 注册之前明确接受该设置。 这些设置连接会直接连接到 GitHub 和 Cloudflare，并 泄露设备的 IP 地址。普通账户的流量在应用该设置前 仍保持原有路由。Cloudflare 会选择出口地址和国家；不同的隧道 可以共享同一个出口地址。该功能不提供国家选择、周期性 IP 轮换以及全主机范围的 VPN 杀开关功能。 支持下载的辅助程序：Linux 和 macOS x86-64/ARM64，以及 Windows x86-64。 会根据已审核源代码中捆绑的 SHA-256 哈希值对构建产物进行校验， 并在启动前再次对缓存的可执行文件进行校验。 任何辅助程序均不会被添加到 PATH 环境变量中，也不会作为系统服务安装，或配置为公开监听器。所有文件均位于 工作区下的 `portable-routes/` 目录中，并存储在加密的保险库条目内。 环回监听器 SOCKS5 需要独立生成的凭据。 私有配置文件和 WARP 账户凭据使用现有的 工作区保险库进行加密。运行期间，辅助程序需要一份仅所有者可见的明文配置文件； 正常停止时该文件会被删除。主机崩溃可能会导致该文件残留在 仅所有者可见的数据文件夹中。这不会对磁盘进行加密，也无法防止 管理员访问。 如果面板的父管道 消失，监督程序将关闭隧道。失败的隧道绝不会启用直接回退。面板重启 将恢复选定的隧道；启动失败时，将在限定延迟后重试。**停止 隧道** 也会暂停监视并保持已停止状态。**启动隧道** 启动隧道；准备就绪后需单独恢复监视。 上传的 WireGuard 配置文件必须包含一个接口和一个对等节点、完整的 IPv4 和 IPv6 路由，且不得包含钩子、包含语句、环境变量替换或额外的 监听器。公共端点地址将在启动前解析并固定。 请使用外部 VPN 或 SOCKS5 网关来连接 OpenVPN/IPsec 及私有端点。 ## 认证方法 **API ID 和 API 哈希用于标识应用程序；它们不能替代账户登录。** 在 TgWitness 中，它们是可选的。优先级顺序为：表单中输入的一组，然后是来自 导入的账户 JSON 文件中的一组，接着是保存在工作区中的一组，最后是内置的 50 个 对，当Telegram拒绝某组时，系统将按随机顺序尝试并自动轮换。只有 Telegram Desktop密钥对（2040）会随匹配的Telegram Desktop客户端描述一同发送。 您可在[my.telegram.](https://my.telegram.org) org的API开发工具中生成的自有密钥对可用于所有账户；每个账户仍拥有独立的授权。 | 方法 | 要求 | TgWitness 支持 | | --- | --- | --- | | 手机号、代码、可选的双因素认证 | 账户访问；API 对（可选） | 面板登录 | | 认证密钥 HEX + DC ID | 完整的 512 个字符密钥和 DC 1–5 | “直接**授权密钥**”选项卡；在保存授权前，可选的“用户 ID”字段需先进行验证 | | Telethon StringSession | 一个有效的会话字符串 | 面板登录 | | Telethon SQLite `.session` | 封闭式、连贯的文案 | 支持直接导入 7/8 版本的模式；可选离线命令行界面 (CLI) | | Pyrogram SQLite `.session` | 已关闭的生产环境用户会话 | 直接通过面板导入模式 2/3 | | Telegram 桌面版 TData ZIP | 一个现代账户；若设有保护，则需输入本地密码 | 带校验和/解密校验的内存内转换 | | 账户 JSON | 支持的 API/会话/密钥字段 | 仅凭元数据即可自动填充 API 凭据；但仍需通过会话/密钥或手机/二维码登录 | | 二维码登录 | 来自授权 Telegram 应用的确认 | 本地 QR 码生成、过期/重试功能，可选双因素认证 | | TDLib / Pyrogram StringSession | 其他特定于库的格式 | 不支持 | | 机器人令牌 | 一个拥有独立访问/更新模型的机器人 | 此收集器未使用该工具 | Telegram 采用代码发送方式；短信送达无法保证。API 哈希值无法修复 已被撤销的会话，也无法替代遗忘的双因素认证密码。TgWitness 不会将 登录代码或 Telegram 双因素认证密码持久化存储到磁盘中。 对于私密来源，该账户必须已具备访问权限。无需提供群组用户名。 使用代理或会话导入既不会授予成员资格，也不会授予管理员 权限。当前成员身份并不保证能够访问加入群组前的历史记录。 ## 导入 Telethon 会话文件 Telethon SQLite、Pyrogram SQLite 和 Telegram Desktop TData 采用不同的格式。 该面板会检测并转换受支持的结构；重命名文件并不属于 转换操作。在**“文件**”下选择一个会话及其对应的 JSON 文件，然后点击**“连接账户**”。最多支持四个匹配文件， 总大小不超过 8 MiB。 有关 TData/JSON 的详细信息，请参阅[格式限制](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/)。 不提供密码恢复功能。通过手机/双因素认证或二维码登录将创建独立的授权。 仅限 Telethon 的可选命令行路径仍然可用： 1. 停止客户端使用原始会话，并制作一份一致的副本。该 转换器会拒绝包含未完成 WAL/日志的文件。请正确关闭原始 客户端，而非通过删除这些文件来绕过检查。 2. 在 TgWitness 环境中，运行： ``` python -m tgwitness.sessions account.session --out account.tgwitness-session ``` 1. 在**“添加账户”→“文件**”下，加载结果或 粘贴其字符串，然后继续。 2. 请核对显示的数字账户 ID，选择数据源并开始监控。 **转换后的文件是一个未加密的账户访问密钥。** 请将其保存在受保护的 存储位置，切勿将其提交或发送给第三方转换服务。TgWitness 会将其授权会话保存在加密保险库中。复制会话不会 创建单独的授权：请勿使用克隆的授权密钥运行多个客户端， 并假设它们能独立接收更新。 转换操作仅传递授权，而非原始消息、实体缓存或 持久化更新游标。它无法解决进程重启后的更新恢复问题。 ## MTProto、Telethon 和代理服务器 MTProto 是 Telegram 的协议。Telethon 是 TgWitness 使用的 Python 客户端库。 MTProxy 是一个 Telegram 传输代理；SOCKS5 和 HTTP CONNECT 提供通用 隧道。这些均无法替代账户身份验证。 在登录前，请将每个工作区的路径保存至 **账户 → 设置 → 连接设置 → 更改连接路径**。 新工作区默认使用 **自动 MTProxy · 公开列表** 并包含 **隐藏地址**。 明确使用 Direct 的现有工作区将保留允许该功能的模式。 ## IP 模式 路由决定连接方式。面板中“账户” 部分的 IP 模式和 **IP 保护**功能，决定了服务器地址何时可能被暴露。这些控制功能不会 安装 VPN，也不会将设备的所有流量都通过该路由传输。 | 模式 | Telegram | 外部请求 | | --- | --- | --- | | 隐藏地址（`hide`) | 请使用代理；若均无法连接，请稍候。无直接备用方案。 | 要求使用 SOCKS5/HTTP；拒绝未通过适用代理的请求。 | | 直接操作仅作为最后手段（`fallback`) | 自动 MTProxy 可能会在配置的延迟时间过后使用 Direct，随后恢复使用正常工作的代理。 | 建议使用已配置的外部代理或该账户的 SOCKS5/HTTP 路由；否则允许使用“Direct”模式。 | | 服务器位于隧道或 VPN 之后（`tunnel`) | 允许使用直连路径，并支持即时自动切换至备用池。 | 若未配置相应的代理服务器，则允许直接连接。 | 隧道或 VPN 模式假设您单独管理该网络。如果没有可用的 隧道，目标端将能看到服务器本身的地址。请根据 您的实际网络环境选择模式，而非仅依据选项名称。 ### 选择路径 | 路径 | 设置 | 边界 | | --- | --- | --- | | 自动 MTProxy | 内置列表或运算符目录 | 维护一条可用的 Telegram 路由；直接备用方案取决于 IP 模式 | | 直接 | 隧道或 VPN 模式 | Telethon 使用主机的网络路由 | | SOCKS5 | 主机、端口、可选的用户名/密码 | python-socks，已启用远程目标 DNS 功能 | | HTTP CONNECT | 主机、端口、可选的用户名/密码 | 仅支持纯 HTTP CONNECT；尚未实现与代理服务器本身的 TLS 连接 | | MTProxy | 主机、端口、密钥 | 实验性 Telethon 传输协议；32 位十六进制数字或 `dd` + 32 位十六进制数字 | 虚假 TLS `ee` 密钥将被拒绝。Telethon 1.45 的规范化处理可去除前缀 和域名，但这并不实现虚假 TLS 功能。请粘贴 `tg://proxy?server=…&port=…&secret=…` 或 `https://t.me/proxy?server=…&port=…&secret=…`，并选择**“从链接填充字段**”。 这将在不建立连接或保存的情况下验证并填充字段；请单独审查并保存 路由。手动字段仍可使用。参见 [Telegram 代理链接](https://core.telegram.org/api/links#proxy-links)。 ### 由您的安装环境提供的公共代理 内置列表整合了四个来源： [SoliSpirit/mtproto](https://github.com/SoliSpirit/mtproto)、 [zakky8/mtproto-proxy-pro](https://github.com/zakky8/mtproto-proxy-pro)、 [kort0881/telegram-proxy-collector](https://github.com/kort0881/telegram-proxy-collector) 以及 [3yed-61/MTP-Collector](https://github.com/3yed-61/MTP-Collector)。 捆绑的快照包含端点信息、来源归属及下载日期。 提供商被列入列表并不证明该代理能够正常工作或能接收 Telegram 的所有更新。 **MTProxy 会自动**检查 Telegram 的传输连接状态，保持代理正常运行， 并在代理失败时切换至其他代理。当有足够的 可用代理条目时，工作区会优先使用不同的代理；无法保证使用唯一的出口地址。 失败的代理 将暂停一段时间后再尝试。如果所有代理均无法使用，则由 IP 模式决定收集 是否必须等待，或可使用直接连接。更换代理不会更改账户 或清除其日志。路由选择和变更均记录在已签名的日志中。 当自动路由处于活动状态时，列表每小时刷新一次，传输检查默认 每十分钟运行一次。这些间隔时间均可配置。**更新公共列表** 会触发刷新；仅查看列表不会更改已保存的手动路由。 **Telegram 流量和 HTTPS 请求使用不同的路由。**列表下载使用 独立的 HTTPS 连接以及提供的外部请求路由。 `TGWITNESS_PROXY_FEED_PROXY` 会通过 HTTP/SOCKS5 代理显式覆盖该路由； 两种 Compose 收集器变体均会转发该路由。后台池遵循主工作区。 不会向数据源提供商发送任何 Telegram 会话、API 凭据、控制面板令牌或机器人令牌。 提供商名称、快照日期和下载路径会显示在**“列表来源”部分**。 MTProxy仅承载Telegram流量。工作区的HTTP操作（如时间戳、 通知、站外副本和源代码验证）在 已配置时会使用独立的SOCKS5/HTTP代理，否则则使用该账户的SOCKS5/HTTP路由。若两者均未配置，"隐藏地址"功能将拒绝 该请求；其他模式则允许"直接"连接。外部请求可被禁用。显式 配置的订阅源下载代理仍由操作员单独覆盖。 独立的见证服务保持其自身的路由。 对于由操作员管理的私有服务，现有的服务器环境设置 `TGWITNESS_ALLOW_PRIVATE_DESTINATIONS=1` 允许私有目标，并保持 代理端的主机名解析。该设置无法通过控制面板启用。仅限公共 模式会在查询公共解析器之前拒绝 `.onion` 目标；Tor 洋葱 服务需要明确的私有目标设置以及合适的代理。 此 DNS 行为适用于外部 HTTP 操作，不适用于 Telegram 的传输协议。 Cloudflare 提供了关于 [JSON DNS 端点的](https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https/make-api-requests/dns-json/)文档。 ****自动池参数**** **在参数→自动 MTProxy**下，配置失败阈值、冷却时间、 计划轮换、代理共享和允许的备用延迟。 | 控制 | 默认 | | --- | --- | | 替换前断开连接 | 3 项，耗时 10 分钟 | | 每次连接尝试中尝试的代理数量 | 3 | | 首次 / 故障后最大恢复时间 | 10分钟 / 6小时 | | 计划轮换 | 已禁用；失败时启用 | | 每个代理的账户数量 | 0：优先单独条目，必要时合并。设置为 1 以等待独占条目。 | | 允许直接回退前的延迟时间 | 10分钟；隐藏地址仍被直接拒绝 | | 数据源刷新/传输检查 | 60 / 10 分钟；主工作区值适用于共享池 | 使用不同的代理服务器并不能保证获得不同的出口地址。这些设置无法 绕过 Telegram 的限制，也无法证明匿名性。 若要用您自己的运营商目录替换公共列表，请配置以下覆盖设置。 这将完全禁用外部订阅，包括当其 `proxies` 数组为空时。 [将空目录](https://github.com/phishdestroy/TgWitness/blob/main/deploy/proxies.config.example) 复制到 `proxy-config/proxies.json` ，并添加您已部署的公共端点： ``` {"format": "tgwitness-proxy-catalog-v1", "proxies": [ {"id": "project-eu", "label": "Project EU", "link": "tg://proxy?server=REPLACE_HOST&port=443&secret=REPLACE_SECRET"} ]} ``` 必须替换示例值。最多接受 32 个不同的条目。 经过身份验证的列表会返回标签/主机/端口，无需共享密钥；选择其中一个 会将其凭据保存到工作区保险库中。在进行 明确的传输测试之前，可用性尚未经过测试。如果目录格式不正确，则可进行手动配置。 本地运行：将 `TGWITNESS_PROXY_CATALOG` 设置为本地 JSON 路径。Docker： ``` docker compose -f compose.yaml -f deploy/compose/compose.proxies.yaml up -d --build ``` 该覆盖层以只读方式挂载 `proxy-config`；文件必须可被容器 UID 10001 读取。 该目录被排除在 Git、Docker 构建上下文和源代码归档之外。此 目录用于配置收集账户；[Witness 机器人](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/)使用其自身的 HTTP/SOCKS5 路由，而非 MTProxy。 直接备用方案由上文所述的 IP 模式决定。在 更改路由前请暂停监控。保存操作将断开旧客户端的连接并取消未完成的登录；新 客户端将使用已保存的路由。该账户的日志/会话绑定关系保持不变。 设置将覆盖之前的路由：编辑时请重新输入代理凭据。 凭据采用`network.enc`加密。API不会返回用户名、 密码或密钥。签名记录包含路由类型以及凭据 是否存在，但不包含端点和密钥。操作员可在控制面板中查看端点。 密钥字段在保存、锁定或切换工作区后将被清空。 **测试 Telegram 连接**（登录前也可使用），通过该路径建立并关闭一个临时 未经授权的 Telegram 连接。该操作不会联系任何 IP 检测 网站。测试成功仅表示传输连接已建立，并不代表群组访问权限、消息 完整送达或匿名性。 该代理适用于 Telegram 客户端的连接，包括 Telegram 数据中心（DC）的媒体 下载。浏览器、pip、SSH 以及手动调用的 TSA 工具则采用独立路径。 代理主机名可在本地解析。`rdns` 影响目标主机名； Telegram 通常提供数据中心（DC）的数值 IP 地址。 SOCKS5 和普通 HTTP CONNECT 本身不会对代理凭据或 客户端到代理的隧道进行加密。MTProto 会单独保护 Telegram 流量。 在不可信网络中，请使用 适当的安全通道连接至代理。私人群组 属于云聊天；MTProto 不会将其转换为端到端加密的“秘密聊天”。 ## 加密与签名 | 层级 | 已实现 | 操作员责任 | | --- | --- | --- | | Telegram 流量 | Telethon MTProto | 平台可信度、传输路径及可用性 | | Web 控制面板 | 持有人令牌、默认回环设置、请求限制 | 通过 HTTPS 或 SSH 隧道进行远程访问 | | 秘密 | Fernet 用于管理 API 凭据、会话、代理凭据及签名私钥 | 保护解密密钥和运行主机 | | 保险库密钥 | 新安装时使用本地密钥或外部主密钥 | 独立的受保护存储空间和密钥备份 | | 消息和附件 | 明文应用程序存储 | 加密磁盘/卷 | | ZIP/JSONL/CSV/HTML | 完整性校验，不进行内容加密 | 保护导出的副本和传输内容 | | 来源与时间 | 签名日志、流程收据、RFC 3161 工具 | 可信密钥、独立检查点/TSA 及保管流程 | “账户”中的**存储保护功能**会显示这些状态。面板令牌是一种 访问密钥，而非加密密码。它授予管理员访问权限； [已签发的令牌](https://phishdestroy.github.io/TgWitness/zh/docs/reference/access/)可限定在特定账户和聊天群组范围内。工作区共享 主机进程，并非独立的租户。 BitLocker、LUKS、FileVault 或受管加密卷可在 各自的威胁模型下保护存储数据。 已解锁且正在运行的机器的管理员 仍然可以读取数据。在存储规划中应将 SQLite WAL/SHM、媒体文件、临时导出文件、交换文件、备份 以及浏览器下载内容纳入考虑范围。Docker 卷仅因其 是卷这一事实，并不意味着它已被加密。TgWitness 不实现 SQLCipher 或对象加密。 ## 外部主密钥 对于新安装，请将主密钥放置在数据目录之外。 此操作不会自动迁移现有的本地密钥库。请准备一个 仅服务身份可访问的密钥目录，然后运行： ``` python -m tgwitness.security create-master-key /private/keys/tgwitness-master.key export TGWITNESS_VAULT_KEY_FILE=/private/keys/tgwitness-master.key python -m tgwitness --data-dir /private/observations/new-case ``` PowerShell，使用已安装的项目环境： ``` python -m tgwitness.security create-master-key E:\PrivateKeys\tgwitness-master.key $env:TGWITNESS_VAULT_KEY_FILE = 'E:\PrivateKeys\tgwitness-master.key' python -m tgwitness --data-dir E:\PrivateData\new-case ``` 在 Docker 中，将文件以只读方式挂载到 `/data` 之外（例如 `/run/secrets/tgwitness-master.key`），并将环境变量设置为该路径。 该服务的 UID 必须具备读取权限。请通过 环境/配置文件传递路径，而非密钥字节。 每个工作区都会获得一个随机的公共盐值，以及通过 HKDF-SHA256 派生出的专属 Fernet 密钥。`vault.external.json` 仅存储派生元数据，而非主密钥。 若密钥缺失或错误，系统将无法启动，且不会在后台自动替换密钥。请同时保留 盐值元数据和主密钥以备恢复之用。 所有工作区均源自同一主密钥；若主密钥遭泄露，将影响整个 安装环境。运行中的进程可解密机密信息。本工具并非硬件安全模块（HSM）或 密码密钥派生函数（KDF）。不接受使用任意人工设置的密码代替随机密钥。 在有计划的迁移 实施并验证之前，请保留现有安装中的现有密钥。删除 `vault.key` 或替换主密钥可能会导致 无法访问会话/签名密钥。请将加密备份与密钥分开存放，并 在隔离的环境中测试恢复功能。 --- # Telegram · 部署 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/deployment/ 可在 Windows、Linux、macOS 或 Docker 环境中将 TgWitness 作为服务运行，通过 HTTPS 访问，并支持备份和更新。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 可在 Windows、Linux、macOS 或 Docker 环境中将 TgWitness 作为服务运行，通过 HTTPS 访问，并支持备份和更新。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) ![部署与恢复](https://phishdestroy.github.io/TgWitness/assets/chapter-operate.svg) **英语** · [俄语](https://github.com/phishdestroy/TgWitness/blob/main/docs/ru/DEPLOYMENT.md) · [乌克兰语](https://github.com/phishdestroy/TgWitness/blob/main/docs/uk/DEPLOYMENT.md) · [西班牙语](https://github.com/phishdestroy/TgWitness/blob/main/docs/es/DEPLOYMENT.md) · [葡萄牙语（巴西）](https://github.com/phishdestroy/TgWitness/blob/main/docs/pt/DEPLOYMENT.md) · [土耳其语](https://github.com/phishdestroy/TgWitness/blob/main/docs/tr/DEPLOYMENT.md) · [阿拉伯语](https://github.com/phishdestroy/TgWitness/blob/main/docs/ar/DEPLOYMENT.md) · [فارسی](https://github.com/phishdestroy/TgWitness/blob/main/docs/fa/DEPLOYMENT.md) · [乌尔都语](https://github.com/phishdestroy/TgWitness/blob/main/docs/ur/DEPLOYMENT.md) · [हिन्दी](https://github.com/phishdestroy/TgWitness/blob/main/docs/hi/DEPLOYMENT.md) · [印尼语](https://github.com/phishdestroy/TgWitness/blob/main/docs/id/DEPLOYMENT.md) · [越南语](https://github.com/phishdestroy/TgWitness/blob/main/docs/vi/DEPLOYMENT.md) · [简体中文](https://github.com/phishdestroy/TgWitness/blob/main/docs/zh/DEPLOYMENT.md) ## 选择安装方式 若使用便携包，请从 GitHub Releases 解压 `TgWitness--windows-amd64-portable.zip`。若采用其他方法，请下载并解压源代码 ZIP 文件或克隆 代码库，然后在项目目录下运行以下命令： | 安装 | 开始 | 在后台运行吗？ | | --- | --- | --- | | Windows 便携版 | `TgWitness.cmd` | 不；请保持窗口打开。 | | 原生 Windows 版 | `Start.cmd` | 不；请使用可选的登录任务以实现后台运行。 | | 原生支持 Linux/macOS | `sh start.sh` | 不；请使用 systemd/launchd 进行后台运行。 | | 在任何受支持的主机上运行 Docker | `docker compose up -d --build --wait` | 是的，只要 Docker 守护进程正在运行。 | | Windows 版 Docker 辅助工具 | `scripts\Docker.cmd` | 是的；该辅助程序会等待 Web 服务器的运行状态。 | | Linux/macOS 上的 Docker 辅助工具 | `sh scripts/docker-start.sh` | 是的；该辅助程序会等待 Web 服务器的运行状态。 | 关于第三方应能进行核查的云服务器——该服务器通过 服务商的 API 创建，不使用 SSH，仅可通过 Cloudflare Tunnel 访问——请参阅 [“高可信度部署”](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/)。 原生启动程序会生成一个私有`.venv`，并安装已固定的依赖项。 Docker会在镜像内部构建这些依赖项，无需主机端的Python。首次 设置需要互联网连接。 若未检测到 Python 3.11 及以上版本，`Start.cmd` 会在 为当前 Windows 用户安装 Python 3.12 之前征得用户同意（使用 winget，否则在验证 Python 软件基金会签名后使用 python.org 安装程序）；该过程绝不会请求 管理员权限。Docker 和操作系统服务仍是必备条件。 原生和便携式安装会在其文件夹内使用 `data/live`。Docker 则使用名为 `tgwitness-data` 的卷 位于 `/data`。在您刻意迁移 完整数据目录之前，这些属于独立的安装实例。请勿期望新的 Docker 容器能自动发现原生 账户。 ## 安装要求 原生安装需要 Python 3.11 或更高版本，并包含 `venv` 和 `ensurepip`；首次安装依赖项时需要 互联网连接；以及一个可供 `.venv` 写入的项目目录。捆绑的控制面板无需 Node.js 或前端构建。请从 您的常规操作系统账户运行启动器；TgWitness 不需要管理员/root 权限。 - **Windows：**`Start.cmd` 会先检查 `py -3`，然后是 `python`，接着是默认的用户级和 Program Files 安装文件夹，并要求系统版本为 3.11 或更高。如果以上路径均无效，它 将提供上述所述的自动用户级安装选项。`py -3 start.py` 同样有效。 便携版完全不需要 Python。 - **Linux：**`start.sh` 会依次尝试 `python3.13`、`python3.12`、`python3.11`、`python3` 和 `python`，若均不匹配，则会输出适用于 apt、dnf、pacman、zypper、apk 或 Homebrew 的安装命令。 Debian/Ubuntu 系统可能需要安装与所选解释器匹配的 `python3-venv` 软件包。 发行版中较旧的 默认 Python 必须被 Python 3.11 及以上版本替换或补充。 - **macOS：**请安装最新的 Python 3.11+ 发行版；请勿假设操作系统自带的 解释器符合要求。请使用项目目录中的 `python3 start.py`。 - **Docker：**请使用搭载 Compose v2.20 或更高版本的 Docker Engine/Desktop。在 Windows 系统上，Docker Desktop 必须使用 Linux 容器。该容器会自行安装 所需的 Python 依赖项；主机无需单独安装 Python。 ## 本地计算机 在 Windows 系统上使用 `Start.cmd`，在 Linux/macOS 系统上使用 `sh start.sh`。`scripts\Setup.cmd` 或 `sh start.sh --setup-only` 可用于 准备运行环境。启动程序在首次使用时会安装依赖项；后续启动 将复用该环境。设置和 Telegram 消息采集需要互联网连接， 但浏览现有记录和生成导出文件可在离线状态下进行。 设置完成后运行 `python start.py --check`，可在不启动收集器的情况下检查本地依赖项、Ed25519、 存储、密钥配置及监听地址。 使用 `--json` 获取结构化输出。传入预期的 `--data-dir`、`--host` 和 `--port`。此检查不会安装软件包、创建日志或连接 Telegram； 它并非完整性或覆盖范围的资格认证。启动时会单独验证 现有日志。`python start.py --help` 同样无需安装。 运行 start.py 后，请在 Windows 系统上使用 `.venv\Scripts\python.exe`，在 Linux/macOS 系统上使用 `.venv/bin/python` 执行辅助命令，或者先激活该环境。 下文中的 `python -m ...` 示例假设该环境已处于活动状态。 ``` python -m tgwitness --data-dir /path/to/private/data --host 127.0.0.1 --port 8787 ``` 环境变量：TGWITNESS_DATA、TGWITNESS_HOST、TGWITNESS_PORT、TGWITNESS_TOKEN。 TGWITNESS_VAULT_KEY_FILE 用于在新安装中选择外部密钥模式；详见下文。 若提供 TGWITNESS_TOKEN，其长度必须至少为 24 个字符；请使用加密 生成的随机值。若未提供，应用程序将在 panel-token.txt 文件中生成一个 256 位的随机令牌。 环境变量覆盖不会重写该文件。请重启以轮换凭据。 数据目录仅允许一个进程拥有。跨平台操作系统文件锁机制可防止 意外的并发写入。请使用一个 Uvicorn 工作进程。控制面板可管理任意数量的 工作区，额外的工作区目录位于 profiles// 下。 对于独立的服务实例，请使用独立的目录和端口。SQLite WAL 文件应存储在本地持久化 存储中，而非网络文件系统中。请勿在副本之间共享同一卷。 ## Windows 便携版 每个 GitHub 发布版本都包含 `TgWitness--windows-amd64-portable.zip` 及其 `.sha256`。其中包含来自 python.org 的官方可嵌入式 Python 3.12 运行时 （校验和固定在 `tools/build_portable.py` 中）、TgWitness 及其固定依赖项， 以及三个启动器： | 文件 | 目的 | | --- | --- | | `TgWitness.cmd` | 启动面板；额外选项将被直接传递，例如 `TgWitness.cmd --port 8790` | | `TgWitness-Demo.cmd` | 在 `data\demo` 启动合成演示 | | `TgWitness-Check.cmd` | 在不启动的情况下运行就绪性检查 | 已将固定的俄语形态学词典和 PDF 颜色配置文件打包，以便 离线使用。打包仅允许在依赖项 `data` 目录内包含其已知的文件路径；若这些目录中出现意外文件，将导致构建失败。 将整个压缩包解压到可写入的文件夹中，例如 `Documents\TgWitness`；请勿 在 ZIP 文件内部或 Program Files 文件夹中运行该程序。运行时使用隔离的模块路径， 因此其他 Python 安装以及 `PYTHONPATH` 均不会对其产生影响。 数据保存在 该软件包的`data`文件夹中。若需更新，请停止 TgWitness，将新版本解压到一个新的 文件夹中，然后将`data`文件夹复制过去。 在 64 位 Windows 系统上使用 Python 3.12 自行构建： ``` python tools/build_portable.py ``` ## 容器 ``` docker compose up -d --build --wait ``` 这将为 /data 创建一个命名持久卷。 Web 端口映射至 127.0.0.1:8787。 该进程以 UID 10001 身份运行，且已移除 权限，根文件系统为只读，而 /data 和 /tmp 目录可写。 `--wait` 在返回前会检查 Web 服务器的运行状态；它不会建立 Telegram 授权或消息投递。 提供的辅助程序在构建完成后采用 180 秒的就绪超时 设置。初始依赖项的下载可能需要更长时间。 两个基础 Compose 文件均使用项目名称 `tgwitness`，因此将新版本 解压到另一个目录时，系统不会自动选择新的数据卷。请确保该项目仅有一个 部署处于活动状态。对于独立安装，请使用唯一的 `docker compose -p NAME ...` 以及不同的主机端口，并在更新时保留这两个配置。 对于使用不同项目名称的旧部署，请继续使用其原始 名称并添加 `-p`；`docker compose ls` 会列出现有项目。 将 `deploy/env.example` 复制到 `.env`，并将 `TGWITNESS_PORT` 修改为使用不同的回环 端口。例如，`TGWITNESS_PORT=8788` 将控制面板暴露在 `http://127.0.0.1:8788`；容器仍监听 8787 端口。`.env` 被 Git 忽略。 获取初始令牌： ``` docker compose exec tgwitness cat /data/panel-token.txt ``` 常用命令： ``` docker compose ps docker compose logs --tail 100 -f docker compose stop docker compose up -d --wait ``` `restart: unless-stopped` 会在收集器崩溃或 Docker 守护进程 重启后自动重启收集器。在 Linux 服务器上，请使用您所用发行版的 服务管理器（通常为 `sudo systemctl enable --now docker`）启用 Docker 自动启动。在 Windows/macOS 上，请启用 Docker Desktop 的“登录时启动”设置。桌面注销、休眠或 Docker Docker 守护进程都可能中断数据采集。明确停止的容器将保持 停止状态，直到您再次启动它。 在示例配置中，/tmp 分区的上限为 512 MiB。导出构建 改用每个工作区的 `temporary-exports/` 路径，将其映射到持久化 /data 分区。请在此处预留空间 以满足同时导出、日志/WAL 增长、媒体文件及备份的需求。 启动器使用 deploy/constraints.txt 来锁定符合要求的运行时依赖项版本。 Docker 和高保障服务器根据 deploy/requirements.lock 和 deploy/build.lock 文件，通过 pip --require-hashes 进行安装：每个包文件必须与提交中记录的 SHA-256 值相匹配，因此若 PyPI 或镜像站点上的文件被替换，则会被拒绝。 Python 基础 镜像和操作系统软件包仍需通过独立的发布资格认证。 除非您打算销毁日志和密钥，否则请勿使用 `docker compose down -v` 命令。 容器健康状况报告反映的是 Web 服务器的可用性，而非 Telegram 捕获是否成功。 请检查控制面板中的采集器状态、心跳、错误及覆盖事件。 ### 独立见证者简介 可选的 `witness` 服务会在其自身的 容器中运行一个[独立的见证节点](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/)，该节点在 `witness-data` 卷中拥有独立的密钥和日志，而收集器仅拥有一个只读 的见证令牌。在控制面板的**“见证**”页面上创建该令牌，将其 与机器人令牌和频道一起添加到 `.env`，然后启动配置文件： ``` docker compose --profile witness up -d # deploy/compose/compose.image.yaml: same flag docker compose logs witness # witness key fingerprint ``` 该服务通过 Compose 网络内的收集器访问，地址为 `http://tgwitness:8787` （`TGWITNESS_WITNESS_COLLECTOR` 会覆盖该地址，例如 `/profiles/` 用于 另一个工作区）。若要使用由他人运行的独立服务器上的见证文件，请在该服务器上使用 `deploy/compose/compose.witness.yaml` ，并将 `TGWITNESS_WITNESS_COLLECTOR` 设置为收集器的 HTTPS 地址；该文件仅包含见证文件。 ## 安装已发布的镜像 将 `deploy/env.example` 复制到 `.env`。将 `TGWITNESS_IMAGE` 设置为发布版本，使用 **小写形式的**仓库路径，例如： ``` TGWITNESS_IMAGE=ghcr.io/your-owner/your-repository:0.9.1 TGWITNESS_PORT=8787 ``` 请单独运行此文件，而非运行 `compose.yaml`： ``` docker compose --project-directory . -f deploy/compose/compose.image.yaml pull docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait docker compose --project-directory . -f deploy/compose/compose.image.yaml exec tgwitness cat /data/panel-token.txt ``` 主机上无需源代码构建、Python 或编译器。发布工作流 针对 Linux AMD64 和 ARM64 容器，包括 Docker Desktop 的 Linux 虚拟机。 请使用版本标签或工作流摘要中的 `ghcr.io/owner/repository@sha256:...`。 未配置`latest`标签的动态更新或无人值守的应用程序升级。当 项目名称相同时，镜像和源代码变体将使用相同的数据卷。 ## 服务器上的自动 HTTPS 配置 请使用搭载 Docker 的服务器、您自行管理的域名以及持久的本地存储空间。 将域名的 A/AAAA 记录指向该服务器；仅当 IPv6 可访问该服务器时才发布 AAAA 记录。 允许入站 TCP 80 和 443 端口，以及用于证书签发的出站 DNS/HTTPS 流量。 其他服务不得已占用这些端口。 将 `deploy/env.example` 复制到 `.env`，并设置主机名（不包含协议或路径）： ``` TGWITNESS_DOMAIN=watch.your-domain.org ``` 使用 HTTPS 覆盖层开始源代码构建： ``` docker compose -f compose.yaml -f deploy/compose/compose.https.yaml up -d --build --wait docker compose -f compose.yaml -f deploy/compose/compose.https.yaml exec tgwitness cat /data/panel-token.txt ``` ``` docker compose --project-directory . -f deploy/compose/compose.image.yaml -f deploy/compose/compose.https.yaml up -d --wait ``` 对于已发布的图像，请改用 `deploy/compose/compose.image.yaml` 作为第一个文件。保留 两个 `-f` 参数，以便后续使用状态、日志、更新和停止命令。 Caddy 负责获取和续期证书，将 HTTP 重定向至 HTTPS，并将 请求转发至私有 Compose 网络上的收集器。证书状态 拥有独立的持久化卷。收集器的直接主机端口仅限回环访问。 提供的 Caddy 配置未启用访问日志记录。 打开 `https://watch.your-domain.org` 并输入面板令牌。准备就绪 并不意味着证书已签发或外部可达。如果 HTTPS 尚未 就绪，请检查 DNS、防火墙规则以及： ``` docker compose -f compose.yaml -f deploy/compose/compose.https.yaml logs --tail 100 caddy ``` 提供的 Caddy 镜像遵循其 `2-alpine` 标签。拉取操作会刷新该镜像； 若需固定基础设施版本，请在部署中固定一个经过测试的摘要。 ## 更新与备份 在更新过程中保留 Compose 项目名称和数据量。首先停止 收集器并进行完整备份。对于默认的基于源代码的部署： ``` docker compose stop docker compose cp tgwitness:/data ../tgwitness-backup-before-update ``` 每次请使用存储库之外的新备份目标，并将其作为 账户访问材料加以保护。示例路径仅供参考；请使用您自己的私有备份 位置。复制整个目录，包括隐藏文件、所有工作区、密钥、 日志和媒体文件。如果已配置外部保险库主密钥，请将其单独备份。 证据 ZIP 文件并非可恢复的应用程序备份。对于 HTTPS，若需保留其证书/账户状态，还应保留 Caddy 卷。 若要进行源代码部署，请获取最新发布文件并运行： ``` docker compose up -d --build --wait ``` 若需部署镜像，请将 `TGWITNESS_IMAGE` 替换为所需版本，然后运行： ``` docker compose --project-directory . -f deploy/compose/compose.image.yaml pull docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait ``` 请也使用您安装环境中的 Compose 文件来执行上述停止/复制命令。 请保留 `.env`、自定义配置以及相同的项目名称。`down` 会保留命名 卷；**`down -v` 会将其删除**。请勿在不同操作系统 或 Python 版本之间复制 `.venv`。若需进行原生更新，请先停止 TgWitness，备份其完整数据 目录，替换源文件，并在启动前运行 `python start.py --setup-only`。 更新后，请检查控制面板访问权限、账户身份、监控状态及覆盖范围。 重启不会恢复遗漏的 Telegram 更新。如果未来版本更改了存储格式， 回滚可能需要使用更新前的备份。 ## 远程服务器 请将服务限制在回环接口内并使用 SSH 隧道，或在 反向代理处终止 HTTPS 连接。基础 Compose 文件仅限本地使用；可选的 `deploy/compose/compose.https.yaml` 覆盖层提供 Caddy 以支持配置好的域名。 请勿在 URL 和代理日志中暴露承载令牌。反向代理应限制 请求大小和连接速率。请勿将明文 HTTP 暴露到互联网上。 [deploy/](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md) 目录中提供了 systemd、Windows 登录任务、macOS 用户代理以及 Caddy 的示例。 安装前请审查并调整其路径。 这些仅为模板，并非本地执行的平台配置。常规启动程序不会 注册任何后台服务或任务。 在 Windows 系统上，以无窗口模式启动 `pythonw.exe` 时，启动/服务器诊断信息将存储在 数据目录下的 `logs/server.log` 中（每文件 5 MiB，包含两个轮换备份）。 控制台模式启动时会保留控制台日志。两种模式下 均禁用 HTTP 访问日志记录。请将日志与数据目录一同保护，并在共享前进行审查。 ## 重启与数据缺失 系统会保留上次请求的监控状态。如果监控处于活动状态， 启动时将尝试重新连接并恢复所选消息源。手动暂停会清除 该意图。重启失败的情况会被记录并显示在面板中。 StringSession 保留授权状态，但不保留 Telethon 的持久化更新/实体状态。 对话记录会在启动时重新加载。Telegram/Telethon 可在运行过程中恢复部分传输中断， 但 TgWitness 不保证在进程重启后能够实现持久化重放。 每次启动时都会记录前一日志头和离线边界。 监视器每 10 秒检查一次连接状态，并每分钟添加一次心跳信号 （**参数 → 存活记录间隔**）。 短暂的中断可能被忽略；连接的传输通道并不能保证 更新的完整交付。快照是明确的当前历史观察结果，绝非缺失数据的修复。 媒体队列存储在每个工作区的 SQLite 数据库中。一条消息及其对应任务 将以原子方式提交。中断的运行任务将在启动时恢复并重试。 每次下载的基本超时时间为 120 秒，外加按 256 KiB/s 速率计算的文件大小所需时间，且 每种附件类型有 1–2,000 MiB 的限制；超时、速度和重试次数可在**“参数**”中设置。收集器 会跳过大小未知的文件。暂停操作会保留队列中的任务。 重试使用原始的 已观察到的文件描述符，绝不会使用后续编辑消息的最新版本。 临时故障的重试次数有限；媒体 FloodWait 暂停状态在重启后仍会保留。 媒体恢复与 Telegram 更新恢复是分开的，无法重建已消失的文件。 ## 备份、恢复与容量 在复制**整个数据目录**（包括 vault.key、 signing.enc、credentials.enc、SQLite 数据库/WAL 文件、媒体文件、令牌、检查点 以及所有配置文件/子目录）之前，请先停止该进程。 在目标服务停止运行时 还原 完整的副本。若保险库密钥缺失或 签名密钥不匹配，将导致启动失败；请勿通过重新生成密钥来强行访问。 请将秘密备份加密并设置访问控制。证据 ZIP 文件便于携带， 用于审查证据文件，而非应用程序备份或 Telegram 会话备份。 本工具不支持自动保留和删除功能。请预留足够的磁盘空间，以存储所有消息、原始 元数据、媒体文件、临时导出文件及备份。 启动验证并导出流记录，而非加载整个日志。 导出操作会锁定已读快照，同时新的 WAL 写入仍可继续；长时间运行的导出 会保留 WAL 页面，因此磁盘容量依然重要。ZIP 文件的上限为 4 GiB （解压后），以匹配独立验证器的默认设置； **通过“参数 → 最大签名 ZIP**” 可提高上限，此类归档文件将使用 `verify.py --max-gib N` 进行验证。其他格式没有事件计数上限。 支持的浏览器会将响应块流式传输到用户选定的文件中。其他浏览器 最多缓冲 128 MiB，并将更大的传输引导至经过身份验证的 CLI： ``` python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip ``` 若要使用其他工作区，请从**“导出”→“工作区 ID**”中选用 `--profile ID`； 若要连接远程服务器，请选用 `--format zip|jsonl|csv|html` 或 `--url https://your-server`； 若要更改 5 GiB 的传输限制，请选用 `--max-mib`。仅允许在 回环连接中使用纯文本 HTTP。令牌通过请求头传输，拒绝重定向，现有文件 不会被覆盖，且未完成的下载不会作为已完成文件发布。 如果 TGWITNESS_TOKEN 覆盖了生成的令牌，请使用一个单独受保护的文件 来存储该有效值：panel-token.txt 不会被覆盖操作重写。 该命令的 SHA-256 仅作为传输校验和；请独立验证已签名的 ZIP 文件。 该面板显示队列中/失败的媒体文件、最旧的待处理媒体文件、可用磁盘空间、Telegram 请求暂停情况，以及访问状态未确认的来源。这些诊断信息并非 完整的端到端交付监控。工作区共享一个进程；一个活动频繁的账户仍可能 影响其他工作区。 独立的工作进程、数据保留/轮换、持久化更新 恢复以及完整的部署认证功能依然存在。控制面板的范围访问权限已在 [“访问与权限](https://phishdestroy.github.io/TgWitness/zh/docs/reference/access/)”部分中记录；独立检查点相关内容详见《 [见证指南](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/)》。 详细操作流程：[连接/安全](https://phishdestroy.github.io/TgWitness/zh/docs/reference/connection/)设置及 [运行模式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/operations/)。 --- # Phala / Intel TDX · 高可信度部署 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/ 部署在 Hetzner 或 Phala Cloud 上的全天候密封服务器、网关 DNS 以及第三方可复现的验证机制。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) Translation coverage: this edition includes material from the English original. 部署在 Hetzner 或 Phala Cloud 上的全天候密封服务器、网关 DNS 以及第三方可复现的验证机制。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [部署与恢复](https://phishdestroy.github.io/TgWitness/zh/docs/reference/deployment/) ![部署与恢复](https://phishdestroy.github.io/TgWitness/assets/chapter-operate.svg) 高可信度部署在 归档验证基础上增加了对采集环境的独立检查。审核人员会查询云服务提供商和 Cloudflare 持有的部署及访问记录，而 Intel TDX 部署还会对采集器的环境进行 硬件认证。 常规的本地和 Docker 使用方式保持不变。除非您使用 `python -m tgwitness.cloud`进行部署，且收集器仅在部署设置为 `TGWITNESS_ASSURANCE`. 流程图 · 操作员 → 服务器，防火墙未配置入站规则 (提供商 API); 操作员 → 隧道与 DNS (Cloudflare API); 服务器，防火墙未配置入站规则 → 隧道与 DNS (仅限外发); 服务器，防火墙未配置入站规则 → 在服务器上生成的签名密钥; Verifier，只读令牌 → 提供商日志和防火墙; Verifier，只读令牌 → 隧道连接器地址和入口; Verifier，只读令牌 → 已签名的 /api/assurance 声明; Verifier，只读令牌 → 证据 ZIP · 操作员 · Verifier，只读令牌 · 服务器，防火墙未配置入站规则 · 提供商日志和防火墙 · 隧道连接器地址和入口 · 已签名的 /api/assurance声明 · 证据 ZIP · 隧道与 DNS · 在服务器上生成的签名密钥 · 提供商 API · Cloudflare API · 仅限外发 **图表转为文本** 1. 操作员 → 服务器，防火墙未配置入站规则 (提供商 API) 2. 操作员 → 隧道与 DNS (Cloudflare API) 3. 服务器，防火墙未配置入站规则 → 隧道与 DNS (仅限外发) 4. 服务器，防火墙未配置入站规则 → 在服务器上生成的签名密钥 5. Verifier，只读令牌 → 提供商日志和防火墙 6. Verifier，只读令牌 → 隧道连接器地址和入口 7. Verifier，只读令牌 → 已签名的 /api/assurance 声明 8. Verifier，只读令牌 → 证据 ZIP **本页内容** - [验证者可以检查的内容](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#what-a-verifier-can-check) - [提供商](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#providers) - [Phala Cloud 上的机密虚拟机（Intel TDX）](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#confidential-vm-on-phala-cloud-intel-tdx) - [开始之前](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#before-you-start) - [来自面板](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#from-the-panel) - [无需域名的快速隧道](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#quick-tunnel-without-a-domain) - [部署](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#deploy) - [调试部署与锁定](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#debug-deployment-and-lock) - [移除部署](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#remove-a-deployment) - [任意服务器（自我认证）](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#any-server-self-attested) - [验证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#verify) - [证据移交报告](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#report-for-evidence-handover) - [Cloudflare 作为外部见证方](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#cloudflare-as-an-outside-witness) - [阅读部署结果](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#reading-the-deployment-result) ## 验证者可以检查的内容 | 声明 | 如何进行验证 | 维护者： | | --- | --- | --- | | 该服务器是在已知时间点通过服务商 API 创建的 | 服务器对象及其在提供商自有日志中的创建过程 | 提供商 | | 没有人使用该提供商的访问路径 | 控制台请求、救援、密码重置、重建、ISO、镜像和备份的日志 | 提供商 | | 无法连接到它 | 提供商防火墙没有入站规则；SSH 服务在首次启动时即被屏蔽 | 提供商（防火墙）、主机（SSH） | | 该面板仅可通过隧道访问 | 隧道入口仅将流量转发至控制面板；连接器从服务器地址运行 | Cloudflare | | 该软件的运行情况如下： | 收集器的签名源代码树哈希值与已部署提交的检出结果相等 | Collector，已与 Git 进行过校验 | | 该签名密钥是在该服务器上生成的 | 该密钥会签署一份声明，其中包含服务提供商的服务器 ID 以及收到的 cloud-init 的哈希值 | Collector，已与提供商进行过核对 | | 该日志属于该密钥和服务器 | 证据ZIP中的每个进程启动时，都会携带该服务器的宿主测量数据 | 证据 ZIP | 收集器将 SSH 状态、会话、登录历史记录和启动信息记录在经过签名的 process-start 和 `host.state` 记录中。在普通虚拟机上，这些是本地库存 记录，审核人员会将其与提供商的独立记录进行比对。下文所述的 英特尔 TDX 部署还会额外验证基于硬件的测量结果。 ## 提供商 | `--provider` | 凭据 | 验证员的只读访问权限 | 验证器的提供者日志 | 保留用于 | | --- | --- | --- | --- | --- | | `hetzner` | `HCLOUD_TOKEN` | 同一项目的读取令牌 | 服务器和防火墙操作 | 只要这些资源存在 | | `digitalocean` | `DIGITALOCEAN_TOKEN` | 只读个人访问令牌 | Droplet 操作 | 只要 Droplet 存在 | | `linode` | `LINODE_TOKEN` | `linodes`, `firewall`, `events` 只读范围 | 账户事件、防火墙规则版本 | 90 天 | | `vultr` | `VULTR_API_KEY` | 具有读取权限且拥有 `activity_logs` 权限 | 账户活动日志（方法、路径、操作者） | 30 天，订阅审计日志可延长保存期限 | | `aws` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | `ec2:DescribeInstances`, `ec2:DescribeSecurityGroups`, `cloudtrail:LookupEvents` | CloudTrail 事件历史记录 | 90 天 | | `phala` | `PHALA_CLOUD_API_KEY` | 同一工作区的 API 密钥 | 应用程序修订与 CVM 操作：Docker Compose 配置和环境变更、重启、操作系统升级 | 虽然该应用程序已存在 | | `generic` | 无 | 无 | 无：**自我认证** | – | 请为每个案例使用专用的项目、团队、账户或子账户：这样，验证者的 只读访问权限将仅显示此部署。凭据从 `--provider-token-file` 或上述变量中读取，绝不从命令行获取。对于 AWS，该文件 包含 `ACCESS_KEY_ID SECRET_ACCESS_KEY [SESSION_TOKEN]`；区域为 `--location`. 每份报告中都会注明各服务商记录中无法显示的内容。 简而言之：Hetzner 会记录控制台请求；而 DigitalOcean 的恢复控制台、Linode 的 Lish/Glish 以及 Vultr 的 Web 控制台则不会被直接记录，因此 root 账户在首次启动时会被锁定，若要登录控制台 则需要重置密码或更改启动方式，而这些操作会被记录下来。Vultr 会向任何能够读取该实例的密钥返回控制台 地址；但记录和报告中均不会存储该地址。 ## Phala Cloud 上的机密虚拟机（Intel TDX） 该 `--provider phala` 收集器运行在 [Phala Cloud](https://phala.com/) 上的英特尔 TDX 机密虚拟机中， 由 dstack 管理。主机和 Phala 工作人员无法读取其 内存，且处理器会对机器的启动过程生成一份认证声明并进行签名。验证器不会 仅凭 Phala 的声明就予以采信： `tgwitness.tdx` 会自行核查每份证明——直至固定的英特尔 SGX 根证书颁发机构（Root CA）——并将其与英特尔的撤销列表及英特尔签名的平台数据进行比对，同时拒绝 任何可被调试或迁移的机器。 | 报告条目 | 功能展示 | | --- | --- | | `tdx_binding` | 该证明涵盖了收集者的签名声明以及本次请求的随机值。 | | `tdx_quote` | 英特尔对该认证负责；只有当英特尔将该平台评定为“最新”时，该认证才算通过。 | | `tdx_compose_hash` | RTMR3 通过重放 dstack 事件日志，对收集器报告的 app-compose 进行测量 | | `tdx_compose` | 该代码与已部署提交生成的代码字节对字节完全一致：源文件通过哈希值固定，两张图片均通过摘要固定，不存在其他代码 | | `tdx_identity` | 该证明来自已部署的应用程序和实例，使用 Phala 的 KMS 提供的密钥以及加密磁盘。 | | `tdx_os` | MRTD 和 RTMR0-2 的值等于验证器根据 Dstack-TEE 发布的 dstack 操作系统镜像计算得出的值，该值通过 CVM 报告的操作系统镜像哈希以及 QEMU 根据虚拟机配置生成的 ACPI 表确定：固件、内核、initrd、包含根文件系统哈希的命令行、内存、vCPU 和设备。开发镜像将导致验证失败 | The OS image (about 180 MB, of which 21 MB are kept) is downloaded once from [Dstack-TEE/meta-dstack](https://github.com/Dstack-TEE/meta-dstack/releases) into `dstack-images` beside the record; `--tdx-image FOLDER` uses another folder or an unpacked image, `--tdx-image none` skips the comparison. The measurement follows `dstack-mr` and the `qemu-acpi` crate of Dstack-TEE/dstack. Private measurement regressions compare QEMU's own ACPI output and a retained Phala Cloud quote; live qualification also needs the published image. `--tdx-measurements` still compares MRTD and RTMR0-2 given as JSON instead. 日志中记录的每次收集器启动都附有此类证明，因此 `verify --evidence` 会检查每次启动及其引导的操作系统镜像。Phala 的应用程序修订版本 和 CVM 的操作充当提供商日志：部署后 Docker Compose 配置的任何更改 都会导致报告失败，且重启记录将被列出以供审查。 在面板中，选择**“附加功能** → **7×24小时服务器** ”下的**“机密虚拟机 · Phala Cloud** ”，并粘贴 Phala Cloud API 密钥；快速隧道的工作原理与 Hetzner 上相同。在命令行中： ``` python -m tgwitness.cloud deploy --provider phala --name case-1 --server-type tdx.small \ --ref v0.8.0 --repository https://github.com/phishdestroy/TgWitness --quick-tunnel \ --provider-token-file phala-key.txt python -m tgwitness.cloud verify --record deployments/case-1/deployment.json \ --provider-token-file phala-key.txt --cloud-init deployments/case-1/docker-compose.yaml \ --source CHECKOUT_OF_COMMIT --fingerprint COLLECTOR_FINGERPRINT --report certificate.md python -m tgwitness.cloud check-report --report certificate.pdf --verifier-fingerprint VERIFIER_KEY ``` `--tdx-collateral` 从文件中读取英特尔的证书和撤销列表，而不是 从英特尔下载。此处无法使用网关 DNS：Phala 没有用于 出站流量的提供商防火墙。 ### 认证证书 对于 Phala 部署，`verify --report certificate.md` 还会写入证书：一个 自包含的 `certificate.html` 文件和一份 A4 规格的 `certificate.pdf` 文件，其中包含验证结果、从英特尔根证书到收集器密钥的信任链、 与普通服务器及高保障服务器的对比分析、 与基于已发布镜像计算出的数值并列的测量结果、各部分的担保方、 英特尔证书链、每项检查、提供商日志，以及如何重复进行 验证。 JSON 报告仍是权威记录；这些页面仅用于呈现其内容。 该报告已通过签名和时间戳进行数字封存，封存文件为 `certificate.seal.json` 及其旁边的 `.tsq`/`.tsr` 文件： | Seal | 新增功能 | | --- | --- | | 合格电子时间戳，`http://tsa.belgium.be/connect` | RFC 3161 时间戳基于比利时联邦政府合格信任服务提供商（FPS 政策与支持局，BOSA）提供的 `certificate.json` 的精确字节数据。 该机构被列入比利时欧盟可信列表，状态为“已授予”，属于合格时间戳服务；截至 2026 年 10 月 20 日发布的列表，其根证书（比利时根 CA6）及列表条目均被固定在 `tgwitness/tsa_roots.py` 中。 根据《欧盟法规》第 910/2014 号第 41 条，此类时间戳在所有欧盟成员国中，其日期、时间以及数据完整性均被推定为准确。 | | RFC 3161 时间戳，FreeTSA | 第二个独立的时间戳 | | 验证器签名 | Ed25519 基于一条声明对报告的 SHA-256 值和每个时间戳进行签名，使用验证者自身的密钥（`--sign-with FOLDER`，默认 `~/.tgwitness/verifier`）；PDF 文件带有由同一密钥生成的签名 | `--timestamp URL`（可重复）选择其他认证机构，`--timestamp none` 不选择任何机构，`--sign-with none` 不对印章进行签名。`check-report` 会验证报告的哈希值、验证者签名、 每个时间戳与受信任根证书的关联及其合格状态，以及 PDF 文件的签名。 在欧盟以外地区， 合格时间戳以及报告整体的法律效力，由接收它的法院 或主管部门决定；该印章表明报告的生成时间以及其内容未被篡改。 一份认证报告无法排除英特尔 TDX 模块或微代码中存在漏洞，也无法排除对 内存总线的物理访问。无论谁控制了 Phala 账户中的应用程序，都可以部署另一个“compose”； 它将显示为一个带有新“compose”哈希值的新版本。主机控制着机器的 时间源和网络。 部署、使用 `--evidence` 进行验证、重启、操作系统镜像比较、带有签名和时间戳的数字密封证书以及 销毁操作均已在 Phala Cloud 平台上运行；参见 [（2026 年 11 月 4 日运行）和](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/#live-phala-cloud-deployment--4-november-2026)。 ## 开始之前 1. 一个 Cloudflare 区域、其账户 ID 以及一个具有 **Cloudflare Tunnel 编辑**、 **区域读取**和 **DNS 编辑权限的** API 令牌，由 `--cloudflare-token-file` 或 `CLOUDFLARE_API_TOKEN`。对于验证者：**Cloudflare Tunnel 读取**、**DNS 读取**，以及针对 审计日志的**账户设置读取**。若无域名， [快速隧道](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#quick-tunnel-without-a-domain)则无需上述任何信息。 2. 具有专用项目写入权限的提供商凭据； `lock` 同样使用： - Hetzner：具有读写权限的 API 令牌； - DigitalOcean：具有写入权限的个人访问令牌； - Linode：个人访问令牌，包含 `linodes`, `firewall` 和 `events` 读写权限； - Vultr：专用账户或子账户的 API 密钥； - AWS：允许使用 IAM 凭据 `ec2:DescribeVpcs`, `ec2:DescribeImages`, `ec2:CreateSecurityGroup`, `ec2:AuthorizeSecurityGroupIngress`, `ec2:RunInstances`, `ec2:CreateTags`, `ec2:DescribeInstances`, `ec2:DescribeSecurityGroupRules` 且 `ec2:RevokeSecurityGroupIngress`. 3. 待执行的提交。发布标签会通过以下方式解析为对应的提交： `git ls-remote`； 服务器仅接收该 40 个字符的提交信息。 ## 来自面板 在您的电脑上，**通过“扩展功能”→“24/7 服务器”**即可为 Hetzner 运行相同的 `deploy` Hetzner服务，仅需三个 步骤：选择欧洲或美国，粘贴Hetzner令牌（读写权限），然后核对 控制面板根据该令牌检索到的服务器类型、月费、地址及版本。在您确认之前， 不会创建任何内容。控制面板会将每个步骤显示为 `deploy` 报告显示，随后显示 地址、面板令牌和签名密钥指纹。若未绑定域名，服务器将获得 [快速隧道](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#quick-tunnel-without-a-domain) ；重启后，**通过“您的服务器”→“查找当前地址** ”可再次查询。若要在自有域名下设置固定地址，请打开 **“可选”→“自有域名** ”，并添加 Cloudflare 令牌（预设链接会自动选择“区域 读取”、“DNS 编辑”和“Cloudflare 隧道编辑”）。 这些令牌随每次请求从浏览器标签页传输至同一台计算机上的 TgWitness， 且不会被写入任何位置；部署记录、经过处理的 cloud-init、面板令牌以及 用于快速隧道的地址密钥均保存在 `deployments/NAME` 数据目录内。 面板仅通过直接回环连接向主管理员提供此功能 （`127.0.0.1`，不允许代理或隧道头部）；通过网络访问的面板则会显示相关命令 。版本默认采用运行中面板的发布标签，该标签通过 GitHub API解析获得。位置、服务器类型和价格来自Hetzner的API： `cpx22` 在提供该服务的地方 使用该服务，否则使用内存至少为 2 GB 的最便宜 x86 类型。 ## 无需域名的快速隧道 `--quick-tunnel` 替换 `--zone`, `--cloudflare-account` 并 `--panel-host`；无需使用 Cloudflare 账户或令牌： ``` python -m tgwitness.cloud deploy --provider hetzner --name case-2026-11 --server-type cpx22 \ --ref 0123456789abcdef0123456789abcdef01234567 --quick-tunnel --provider-token-file hetzner.token ``` 在服务器端，cloudflared 会打开一条 [快速隧道](https://developers.cloudflare.com/tunnel/get-started/quick-tunnels/) 连接到控制面板：一个随机的 `https://….trycloudflare.com` 地址，该地址会在 cloudflared 或服务器重启时发生变化。服务器上一个小型服务会将每个地址发布到一个随机的 ntfy.sh 主题中，并使用仅部署目录中保存的密钥进行签名（HMAC-SHA256） （`address-key.txt`），并每三小时重复一次，因为 ntfy.sh 会保留帖子 12. `deploy` 和**“查找当前地址”**功能仅接受签名帖子，因此伪造的帖子无法 将您和您的面板令牌重定向到他人的地址。该主题记录在 已发布的 cloud-init 中：任何拥有这些信息的人都能读取当前地址，而该地址仍会要求提供 面板令牌。无论哪种方式，服务器均不保留任何入站端口。 验证器没有地址密钥，任何读取该主题的人都可以向其发布消息。因此，收集器 还会发布该地址本身，并使用其自身的 Ed25519 密钥进行签名；`verify` 会取部署记录中 由收集器密钥签名的最新发布消息；发布消息的排序依据是 ntfy.sh 接收它们的时间，而非它们声称的时间。 在此变更之前的收集器不会对任何内容进行签名，而 `verify` 随后会取最新的一条发布内容，并在 `statement` 检查中声明这一点；伪造的发布内容 只能导致该检查失败，因为该地址仍必须使用收集器的密钥进行响应。 代价：由于没有 Cloudflare 账户记录快速隧道，因此 `verify` 会报告 隧道、连接器和 DNS 检查不可用，结果最好也只能是 `incomplete`（在 Phala Cloud 上，检查反而通过：连接器在被测的 Docker Compose 配置中运行）； 提供商记录、防火墙、签名声明、主机测量和安装程序比较均 按常规进行检查。与参考安装程序的字节比较需要一个已部署的提交 版本，该版本已知 `--quick-tunnel`；从 0.7.0 版本检出后构建域名安装程序并报告 差异。 Cloudflare 对快速隧道不提供正常运行时间保证，允许 200 个请求 在传输中，且不传输服务器发送事件（Server-Sent Events），因此控制面板的实时更新（0.7.0 之后的版本） 可能无法通过快速隧道到达，需要重新加载页面；这一部分尚未经过测试。对于 必须保持稳定的场景，请使用您自己的域名。 ## 部署 请先查看所有即将发送的内容。 `plan` 不会向任何服务提供商或 Cloudflare 发起请求： ``` python -m tgwitness.cloud plan --provider hetzner --name case-2026-11 --server-type cpx22 \ --ref 0123456789abcdef0123456789abcdef01234567 --zone example.org \ --cloudflare-account CLOUDFLARE_ACCOUNT_ID --panel-host case.example.org ``` 然后使用相同的选项和凭据进行部署： ``` python -m tgwitness.cloud deploy --provider hetzner --name case-2026-11 --server-type cpx22 \ --ref 0123456789abcdef0123456789abcdef01234567 --zone example.org \ --cloudflare-account CLOUDFLARE_ACCOUNT_ID --panel-host case.example.org \ --witness-host case-witness.example.org \ --provider-token-file hetzner.token --cloudflare-token-file cloudflare.token ``` 初始服务器类型： `cpx22` (Hetzner)， `s-1vcpu-2gb` (DigitalOcean)， `g6-standard-1` (Linode)， `vc2-1c-2gb` (Vultr)， `t3.small` (AWS)。 `--location` 以及 `--image` 默认使用各 服务商位于欧洲区域的 Ubuntu 24.04 系统。 `--repository` 从另一个 https Git 仓库获取提交，且 URL 中不包含凭据 （默认 `https://github.com/phishdestroy/TgWitness.git`). `deploy` 也接受 `--out` 指定其他部署目录（默认 `deployments/NAME`；若目录中已存在 部署则会被拒绝）以及 `--wait`，即等待收集器签署声明所需的分钟数： 1 到 240，默认值为 20，或 60 用于 `generic`. 命令： 1. 创建一个 Cloudflare 隧道，其入站流量将面板主机名转发至面板， 若已指定，则将见证主机名转发至 `/api/witness/head` 并 `/api/assurance` 且仅限该主机名； 2. 为这些主机名创建代理 CNAME 记录，并拒绝已存在的名称； 3. 创建一个不包含入站规则的提供商防火墙，并在其后部署一台服务器，该服务器不使用 SSH 密钥、 不进行备份、不使用控制台代理，且 cloud-init 会屏蔽 SSH、锁定 root 权限，并安装 `cloudflared`、精确获取该提交、验证并以 强化版 systemd 服务的形式启动 TgWitness； 4. 等待收集器发送的签名声明，并验证该声明是否指明了此服务器以及 此 cloud-init 的哈希值。 `deployments/case-2026-11/` 其中包含： | 文件 | 目录 | 分享？ | | --- | --- | --- | | `deployment.json` | ID、哈希值、发出的 API 调用（方法、路径、状态）以及第一条已签名的声明 | 是的，通过验证器 | | `cloud-init.redacted.yaml` | 将云初始化脚本（cloud-init）中的两个密钥替换为 `REDACTED` | 是 | | `panel-token.txt` | 面板令牌 | 无 | 提供商的根密码、隧道令牌和面板令牌绝不会写入 `deployment.json`。请通过您无法单独控制的频道（例如见证频道或发送给收件人的消息）发布文末显示的收集器指纹。 请使用面板令牌登录 Telegram， `https://case.example.org` 使用面板令牌登录 Telegram，具体操作参见 [账户指南](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/)。面板操作会被记录在已签名的日志中；这些操作并非 SSH 会话。[见证人](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/)可以轮询 `https://case-witness.example.org`. 不支持 SSH：如果初始化失败，收集器将永远不会响应。请删除服务器并 重新部署，或使用调试部署来查找原因。 ### 用户数据中的秘密 cloud-init 包含两个密钥：控制面板令牌和 Cloudflare 隧道令牌。 签名密钥不在此列；它是在服务器上生成的。Hetzner、DigitalOcean 和 Linode 不会通过其 API 返回用户数据。Vultr 会将其返回给任何能够读取 实例的密钥，而 EC2 则通过 `DescribeInstanceAttribute`。对于 AWS，仅向验证者提供表格中的三项 操作，切勿 `ec2:Describe*`。对于 Vultr，假设验证者的密钥可以读取这两个 令牌。隧道令牌允许某人运行第二个连接器： `verify` 这会报告任何 不在服务器上的连接器，且收集器的声明无法通过这种方式伪造，因为每一条 都会对新的挑战进行签名。使用 `--quick-tunnel` 第二个密钥则是地址密钥： 任何读取它的人都可以发布一个虚假地址，而控制面板会接受该地址。 该收集器的公开声明中未提及服务器地址和登录来源； 这两项信息均保存在已签名的日志中。 ## 调试部署与锁定 `--debug-ssh-key KEY --debug-ssh-from 198.51.100.4` 仅支持来自单一地址 或小型网络（IPv4 最多 /24，IPv6 最多 /48）的单个密钥的 SSH 连接。 `KEY` 已向 服务商注册：Hetzner 项目中 SSH 密钥的名称或 ID、DigitalOcean 团队中 SSH 密钥的 ID 或指纹、其个人资料中的 SSH 密钥已添加到 root 用户的 Linode 用户名、 Vultr 账户中 SSH 密钥的 ID，或该区域内 EC2 密钥对的名称。这些 选项不适用于 `generic`。此类部署将被记录为 `debug` ，且**绝不会**被报告为 高可信度。操作完成后，请运行 `sudo tgwitness-lock` 作为最后一次 SSH 会话的最后一条命令，然后： ``` python -m tgwitness.cloud lock --record deployments/case-2026-11/deployment.json --provider-token-file hetzner.token ``` 防火墙会丢失所有入站规则。随后生成的报告会显示何时允许了 SSH 连接以及何时 将其关闭；该窗口将保持可见状态。 ## 删除部署 `destroy` 删除服务器及其防火墙（通过部署标签定位），以便 中途失败的部署也会被移除，随后删除指向其 隧道的 DNS 记录以及隧道本身。服务器的日志和签名密钥将一并删除：请先导出 证据。记录将保留，并标记为 `removed`，并附有删除操作的API调用记录。 ``` python -m tgwitness.cloud destroy --record deployments/case-2026-11/deployment.json --confirm case-2026-11 \ --provider-token-file hetzner.token --cloudflare-token-file cloudflare.token ``` 针对 Hetzner，已通过 API 实现了内容删除功能。对于其他服务商 `destroy` 在删除任何内容之前 需先停止服务，并在服务商控制台中指定要删除的标签。手动安装的 服务器（`generic`）仅会丢失其隧道和 DNS 记录。快速隧道部署无需 Cloudflare 令牌：其隧道仅连接至服务器，且相关帖子将在 ntfy.sh 上于 12 小时内过期。 ## 任意服务器（自我认证） `--provider generic` 适用于购买或手动安装的服务器。 `deploy` 用于创建隧道 和 DNS，并写入 `install.sh` （私有）和 `install.redacted.sh` （用于发布），然后进入等待状态。 将 `install.sh` 到新安装的 Ubuntu 24.04 服务器上，并在该服务器上运行： ``` sudo bash install.sh ``` 它会记录主机当时的原始状态（登录信息、账户、 `authorized_keys`、监听套接字、 服务、定时任务、软件包）的原始状态，安装该提交，启用主机防火墙，删除 自身，屏蔽 SSH 并结束会话。此类服务器的报告充其量只能 **算是“自我证明”**：无论谁运行了安装程序，在运行之前都已拥有 root 权限，且验证者无法获取 任何提供商记录。但这仍优于来源不明的服务器：资产清单、 安装程序哈希值以及此后每次登录都经过了签名。 ## 验证 验证者需要 `deployment.json`已发布的安装程序、只读凭据，以及 最好是该提交的代码检出和证据 ZIP： ``` git clone -c core.autocrlf=false https://github.com/phishdestroy/TgWitness.git checkout git -C checkout checkout 0123456789abcdef0123456789abcdef01234567 python -m tgwitness.cloud verify --record deployment.json \ --provider-token-file read-only.token --cloudflare-token-file cloudflare-read.token \ --fingerprint COLLECTOR_FINGERPRINT --cloud-init cloud-init.redacted.yaml \ --source checkout --evidence tgwitness-evidence.zip --report report.md ``` 验证器会在该时刻请求每个提供商和 Cloudflare 的值；记录 仅提供需要查询的 ID。退出代码 0 表示通过**（PASS）**，1 表示**失败（FAIL）**，2 表示 **待审核（REVIEW）**、**不完整（INCOMPLETE）**或**自我认证（SELF-ATTESTED）**。 `--fingerprint` 应来自一个独立的 频道；若无此信息，则仅将密钥与运营商的记录进行比对。 `python verify.py` 仍会像“[证据](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/)”部分所述那样，自行验证证据ZIP。 提供商操作分为以下几类：创建操作以及在创建后 30 分钟内启动的操作均通过审核； 控制台、救援、密码重置、重建、ISO、镜像、快照、备份、系统管理器、 EC2 实例连接和防火墙开放操作若失败；电源操作以及任何意外操作 均会被标记为待审查。未知操作绝不会悄无声息地通过审核。 ## 证据移交报告 `--report report.md` 生成 Markdown 报告，并 `report.json` 其旁边： 1. 结果、收集器密钥指纹、部署、提供商、提交、服务器、防火墙、隧道； 2. 每次检查及其状态和来源（提供商 API、Cloudflare API、收集器声明、 证据日志）； 3. 提供者日志，其中包含每项操作的评估结果，以及（若提供者进行了记录）操作执行者； 4. Cloudflare 端点，用于存储隧道的连接信息、配置和审计日志； 5. 经签名的收集者声明； 6. 该报告阐明了哪些内容，又未阐明哪些内容； 7. 用于重现该功能的命令，以及每个输入文件的SHA-256。 提交报告、 `report.json`, `deployment.json`、已发布的安装程序以及 证据 ZIP。请尽早生成报告：服务商的日志保存期限有限。 ## Cloudflare 作为外部见证方 此处所有内容均为可选。即使没有 Cloudflare 账户，服务器仍可运行，且其中两项 功能目前已可正常使用： | 内容 | 功能展示 | 在 TgWitness | | --- | --- | --- | | 快速隧道或您域名的隧道 | 该面板仅可通过隧道访问 | 服务器向导，参见上文 | | drand 中继 `drand.cloudflare.com` | drand 轮之后生成的记录比它更新：日志是边进行边撰写的 | 证据模式、**更多见证者**、无账户（[格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#optional-records-in-evidence-mode-drand-and-telegram-devices)） | | 隧道状态通知 | 当隧道中断时，通过电子邮件或来自 Cloudflare 的 Webhook 通知 | 在 Cloudflare 控制台中进行设置 | | 网关 DNS（`--gateway-dns`，或在向导中称为 **Cloudflare Gateway DNS**） | 服务器查询的每个名称，均由 Cloudflare 通过 TLS 响应；Hetzner 防火墙不允许 DNS 访问其他任何内容；网关策略是否可以重写响应 | Hetzner，免费“零信任”套餐，不提供域名； `verify` 检查防火墙、位置、日志记录、策略、服务器查询及审计日志；证据模式会将日志复制到日志簿中 | | 与 Cloudflare 的网关：服务器上运行一个客户端，并配置出站防火墙，仅允许连接 Cloudflare | 服务器建立的每次连接，而不仅仅是 DNS 连接 | 尚未开发 | | 面板前方的访问入口 | 谁在何时登录了该面板 | 尚未实现：需要您自己的域名 | | SSH 命令日志记录 | 调试会话中的每个命令 | 尚未开发 | Logpush（该功能会将 Cloudflare 的副本保存在 R2 中）是一项企业级功能：在免费 套餐中，Cloudflare 会 `logpush is not enabled for this account`。其网关日志在该处保留 24 小时，因此“证据模式”会将其复制到已签名的日志中（即 **Cloudflare Gateway 记录的 该服务器的 DNS 查询日志**，这是一个具有“账户分析读取”权限的只读令牌）。 如果没有“零信任”方案，一个账户只有一个 DNS 位置。当 Cloudflare 拒绝另一个位置时， 服务器会共享现有的位置，并通过其地址来区分查询；该过滤器 也需要“零信任”PII 读取权限，并且 `destroy` 这会留下一个共享位置。一次日志查询的跨度 最多为三小时，因此复制和 `verify` 读取操作需在三小时的时段内完成。 Gateway DNS 负责系统解析器。通过 443 端口以 DNS over HTTPS 方式连接至其他解析器，以及 连接至未被任何地方查询的地址（例如 Telegram 的数据中心）的连接，均不会 记录在日志中。 Cloudflare 无法查看 Telegram 的加密内容、该 Telegram 账户下的其他设备 （“证据模式”的设备列表是从 Telegram 端记录的）或服务提供商的虚拟机管理程序。 ## 阅读部署结果 对于普通虚拟机，提供商控制主机基础设施，并会同时核对本地库存 与提供商记录。对于 Intel TDX，验证者还会额外检查 硬件配置、收集器绑定、Compose 以及操作系统测量数据。请阅读各项 结果，以查看哪些检查通过或不可用。 历史防火墙详情取决于服务提供商；Linode 会保留规则版本。 [验证记录](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/)列出了已测试的部署和剩余的在线 检查，而[验证范围](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#verification-scope)将这些环境 检查与存档获取及完整性联系起来。 --- # Telegram · 面板指南 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/ 面板的每个界面：聊天、日志、来源、导出、扩展功能、保护模式和代码检查。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 面板的每个界面：聊天、日志、来源、导出、扩展功能、保护模式和代码检查。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [入门指南](https://phishdestroy.github.io/TgWitness/zh/docs/reference/quickstart/) ![入门指南](https://phishdestroy.github.io/TgWitness/assets/chapter-start.svg) [初始设置与配置](https://phishdestroy.github.io/TgWitness/zh/docs/reference/settings/) · [账户](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/) · [导出与验证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/) · [案例报告](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-reports/) 各屏幕的功能说明、其向签名日志写入的内容，以及详细 指南的所在位置。面板每次仅显示一个工作区：一个 Telegram 账户及其专属的 来源、日志和签名密钥。侧边栏顶部的选择器用于切换 工作区。地址包含工作区信息（`?ws=…`）；当地址、 选择器与已加载的账户不一致时，所有操作将被阻止。 使用[比较收集方法](https://github.com/phishdestroy/TgWitness/blob/main/docs/COLLECTION-MODES.md)在实时 观察、完整历史记录、新账户/聊天记录导出以及已保存记录移交之间进行选择。 导出页面在下载控件上方包含与上述相同的比较功能。 **本页内容** - [导航指南](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#find-your-way) - [从这里开始](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#start-here) - [聊天记录](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#chats) - [日志](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#journal) - [来源](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#sources) - [导出功能](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#exports) - [设置、账户和连接](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#settings-accounts-and-connection) - [附加内容](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#extras) - [保护模式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#protection-modes) - [更多工具](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#more-tools) ## 快速入门 “每日”板块位于侧边栏顶部**，“账户** ”位于**“工作区** ”下， 其余内容均位于**“更多工具与设置** ”下。顶部栏中的**“界面级别** ”切换按钮决定显示多少个板块： | 级别 | 侧边栏中的部分 | | --- | --- | | 简单 | 首页、聊天、更新、存档和设置 | | 标准 | 另见 Case Board、账户和访问权限 | | 专家 | 此外还有“来源”、“扩展功能”、“咨询存档”、“参数”、“账户”、“系统日志”和“集成”等模块。 | “简单调用”从“开始”、“日志”和“导出”页面进入，包含“**主页**”、“**更改**”和“**存档**”。 安全级别仅用于隐藏部分内容。隐藏的功能仍会正常运行，服务器会 自行检查每一项权限。安全级别、语言、主题和时区会按 操作员和工作区分别保存；请参阅[设置](https://phishdestroy.github.io/TgWitness/zh/docs/reference/settings/)。 顶部栏还包含： - **跳转至某部分**（Ctrl+K，或在 Mac 上按 ⌘K）：通过 `#number`。使用方向键移动，按 Enter 键打开，按 Esc 键关闭。 - **通知**：根据日志生成的故障和聊天变更信息。 **“全选已读**”会清零计数器，“**通知规则**”可打开规则设置。 在 [“扩展功能” → “通知”](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#notifications) 中可设置将通知发送至 Telegram、Discord 或电子邮件。 - 此工作区的连接指示器。顶部栏下的**“收集器状态”** 将其细分为 Telegram 连接、事件接收、数据源和附件队列。 - **锁定**：关闭当前浏览器中的面板。Collection 仍会在服务器上继续运行。 - 版本号旁边的保护模式；请参阅[保护模式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#protection-modes)。 演示工作区包含虚构的消息，且绝不会连接到 Telegram。 任何可能更改真实工作区的操作都会被拒绝。 ## 从这里开始 选择一项任务。**“导出我的账户**”会下载该账户当前可读取的内容。 **“跟踪调查”会**记录您所选聊天群组中的新消息、 观察到的编辑操作以及删除通知。设置卡片显示了三个步骤：连接账户、 选择来源、开始观察。目标问题会一直显示在此页面，直到您 回答或跳过它。新建工作区则会直接打开[首次设置](https://phishdestroy.github.io/TgWitness/zh/docs/reference/settings/)界面。 ## 聊天 已保存的对话，默认仅限查看。 - 可通过名称或 ID 搜索列表。**选择**“添加”或“移除”以管理关注的聊天。 “**打开 Telegram 链接**”功能接受用户名或邀请链接，并将预览保存到 日志中。**“加入/打开并观察**”会先加入该聊天，再将其添加到您的来源中； 打开机器人会将其发送出去 `/start`. - 聊天头部显示消息计数：**已删除，保留文本**、**在保存前已删除** 和 **重新检查后未找到**。聊天列表和通知采用相同的 定义。已删除的消息显示为红色，并保留其已保存的文本；已编辑的消息 则保留所有已保存的版本。每次删除操作都会显示已知信息：消息被查看的时间、 Telegram 不会报告删除者身份，或者仅收到了删除通知。 - **“加载历史记录**”功能将最近的 100、250 或 500 条消息导入此视图和 日志中。若要加载所有已启用的消息源，请使用[“消息源”→“完整历史记录”](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#sources)。 - **“导出聊天”**功能将整个可见聊天记录下载为一个已签名的 `chat.json` 且 `chat.html`文件。多个关联账户可协同完成此任务：每个账户下载其对应的 消息编号范围并对其部分进行签名，而发起 导出的账户则对整个存档进行签名。参见[“导出单个聊天](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Chat-Export.md)”。 - **“人员”**列表显示了该聊天中所有保存了消息的用户。人员个人资料默认处于 关闭状态，因为它们涉及第三方个人数据。当某次聊天中 启用该功能时，个人资料会显示姓名和用户名历史、Telegram标记、头像哈希值、活动记录、 谁回复了谁、其他被观察的聊天，以及被提及的钱包、手机号、用户名 和链接。 每项信息都指向其对应的记录。**导出个人资料**会保存一个签名文件， 可选地设置密码ZIP；关闭个人资料会删除该文件。参见 [“人员个人资料](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#people-profiles)”。 - **“保存个人资料”功能现可**记录聊天或机器人个人资料的快照：描述、 成员、邀请链接、机器人命令。 ### 只读、发送和密钥 消息上方有两个开关，用于保护账户和读者： - 打开聊天时**，“只读”模式**处于开启状态。 若要发送消息或点击机器人 按钮，请将其关闭。每次操作时都会提示**“以 @account 身份发送？**”或**“以 @account 身份点击此机器人按钮？**”，这表明聊天成员会看到该操作，且该操作将进入已签名的 日志。**选择“在此聊天中 10 分钟内不再提示**”可暂时跳过该提示。在**“案件证据**”目标中，无论是面板还是 API，发送功能均处于关闭状态。 - **“隐藏机密”功能可**隐藏看似密码、登录码、API 密钥或 哈希值、机器人令牌、会话字符串、私钥、JWT 或支付卡号 （卡号会通过 Luhn 和校验）的内容。**点击“显示”**将揭示一个值；该揭示操作 会被记录在日志中。为该浏览器关闭隐藏功能的操作也会被记录下来。 仅显示内容发生变化：原始记录和所有导出文件均保留完整文本。 ## 日志 工作区已签名的所有记录，按时间倒序排列（最新在最前）。 - **“概览”**统计了已观察到的消息、记录的编辑、删除通知以及 选定的来源。 - **事件时间轴**可按事件类型（全部、编辑、删除、点赞、 成员资格、报道范围）、文本内容及来源进行筛选。可回**载较早的事件**页面。 - 打开一条记录可查看其详细信息、哈希值和有效载荷。**该记录的链接**是一个 可直接打开同一记录的地址。此预览中可能包含的机密信息已被屏蔽； 导出文件则保留原始内容。 - 日志为仅追加模式：面板中没有任何操作可以编辑或删除记录。请通过 **“导出”→“验证日志**”或 `python -m tgwitness.verify`；参见 [“导出与验证”部分](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/)。 ## 来源 该工作区会记录哪些对话，以及从中保留哪些内容。更改 仅适用于未来的活动；已保存的记录保持不变。 **“刷新聊天列表”**功能会读取该账户的聊天记录和文件夹，但不会下载消息内容。 ### 范围 - **该账户记录的内容** ：**选定的聊天** （仅您添加的聊天）， **Telegram 文件夹** （该账户的一个文件夹，包括后续添加到其中的 聊天）或 **完整账户** （所有聊天，以及每个新出现的聊天、群组、私聊或 机器人）。**调查模式** 适用于专用账户：它记录 该账户所见的一切内容、其自身发送的消息和按键操作，并立即保存每个新 聊天的配置文件及先前可见的消息。 [专用账户指南](https://phishdestroy.github.io/TgWitness/docs/dedicated-account/) 解释了为何绝不能使用你的主账号。 - **源类型**将文件夹模式和整个账户模式限制为频道、群组、私聊 和机器人。**自有操作**会添加该账户自身的消息、编辑操作以及 回复时的键盘按键记录。 - **当出现新的聊天或机器人时**：保存其资料，并保存最多（根据所选数量） 其最新的可见消息。 限制：已发布的云端收集器无法接收秘密聊天。独立的 [伪秘密接口及其演示版本的](https://phishdestroy.github.io/TgWitness/zh/docs/reference/secret-chats/)文档中已注明其 开发状态和未解决的缺陷。 当 TgWitness 未运行时不会记录任何内容；重启后，它仅能捕获 Telegram 仍返回的数据，且 报告中会显示数据缺口。超出聊天列表限制（除非在 参数中更改，否则为 1,000 个对话）的聊天将在下次激活时被添加。在 其他应用中点击的内联机器人按钮不可见；但机器人的回复会被记录。 ### 涵盖的聊天 可按状态（**已启用**、**已暂停**、**优先级**、**已排除**、**未确认 访问**、**已忽略**）和类型进行筛选，然后对选定项执行操作：启用、暂停、标记或移除 优先级、从范围中排除或删除。状态图标仅显示当前状态；操作 位于每行菜单中，并附有功能说明。 暂停和排除操作需要 确认，批量操作时同样如此。删除来源时需输入其名称，并会删除其人员 个人资料；其保存的记录仍保留在日志中。 若某来源未显示在该账户的聊天列表中，则表示该来源正在**接收更新，但未出现在聊天 列表中**，同时记录仍在持续到达；否则，**访问状态未确认**。**“可用 聊天**”会添加通过**“添加所选**”或**“添加所有匹配项**”操作选中的聊天。 ### 完整历史 将每个已启用来源的可用历史记录加载到“聊天”和日志中。 进度在重启后仍会保留；附件遵循您的媒体设置。参见 [来源历史记录](https://phishdestroy.github.io/TgWitness/zh/docs/reference/history/)。 ### 记录 - **选择要保留的变更**：新消息、编辑、删除通知、 可见的点赞、加入和退出。预设会更改表单； **“保存记录设置**”会应用该预设。重新启用某类别不会恢复 已错过的事件。 - **在可能的情况下保留媒体文件**：下载单个文件大小不超过指定限值的附件，设置 每种类型的限值范围为 1 至 2,000 MiB，并限制视频时长（以秒为单位，0 表示无限制）。 每次下载尝试都会记录结果。 - **重新检查**：每隔几分钟检查一次优先级聊天，其他聊天则很少检查，因此该账户 不会触发 Telegram 的 FloodWait 限制。设置为 0 可关闭该组。在列表中用星号标记优先级聊天； 每次检查的聊天数量以及聊天之间的暂停时间可在 “参数”中设置。参见[集合](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/)。 ## 导出功能 **“下载**”用于准备文件；**“构建报告**”用于选择报告的显示样式。 | 内容 | 用途： | 指南 | | --- | --- | --- | | 账户导出 | 该账户当前可读取内容的最新快照 | [账户导出](https://phishdestroy.github.io/TgWitness/zh/docs/reference/account-export/) | | 共享副本 | 一个已完成的账户导出功能的精简版 | [披露声明](https://phishdestroy.github.io/TgWitness/zh/docs/reference/account-export/#prepare-a-disclosure-for-a-lawyer-or-another-recipient) | | 已签名 ZIP | 日志、报告、附件和验证工具，均位于固定的日志边界内 | [导出与验证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/) | | HTML、PDF、JSON 报告 | 一份密封的可读报告 | [案例报告](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-reports/) | | JSONL、CSV | 带有签名的原始记录；一个支持公式的电子表格 | [导出与验证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/) | | 交接摘要 | 仅包含收件人所需的聊天记录、时间段和联系人 | [证据](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#investigation-handoff) | | 聊天记录导出 | 一个已签名的聊天记录 `chat.json` 以及 `chat.html` | [导出一个聊天记录](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Chat-Export.md) | - **使用密码对上述下载文件进行加密**（12 个字符或以上）会保存一个 AES-256 ZIP，该文件可由 7-Zip 或 WinRAR 打开。其中的已签名文件保持不变。 密码不会被存储。 - **“已准备的导出”**功能会保留最多 20 个文件（总大小不超过 2 GiB），外加最新的一个文件，以便 重复下载，每个文件都包含其SHA-256。文件的准备并不代表已成功发送。 - 当浏览器拒绝显示保存对话框时，该面板将回退为普通下载。 - **您的签名身份**会显示密钥指纹。**“保存检查点**”和 “下载**已签名的运行收据**”功能可为您提供存储在收集器之外的记录。 “准备**时间戳请求**”会在不联系任何服务的情况下构建一个 RFC 3161 请求。 ## 设置、账户和连接 - **设置**：目标、连接、记录内容及界面。请参阅 [首次设置和配置](https://phishdestroy.github.io/TgWitness/zh/docs/reference/settings/)。 - **账户**：每个工作区及其状态、消息源、事件和附件队列。 可通过 **需要关注**、**收集**、**离线或已暂停** 或 **未连接** 进行筛选，暂停或恢复选定操作，批量导入账户文件并管理 群组。参见 [账户](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/)。 - **账户**：登录及该账户的连接路径。直接连接、WireGuard 配置文件、您自己的代理、公共 MTProto 池或 WARP；准备并检查一条路径， 然后将其应用到该账户、一个组或所有账户。参见 [“连接”和“代理](https://phishdestroy.github.io/TgWitness/zh/docs/reference/connection/)”[部分](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Proxies.md)。 ## 附加功能 可选：只需一个账户和来源即可开始收集。只有您 选择的选项才会打开其设置，系统不会自动连接任何内容。顶部的“ **保护级别**”卡片显示当前的[保护模式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#protection-modes)。 | 卡片 | 新增功能 | 指南 | | --- | --- | --- | | 存储与磁盘空间 | 备份、将旧文件移至您的云端、一份无法被删除的证据副本 | [存储](https://phishdestroy.github.io/TgWitness/zh/docs/reference/storage/) | | 目标与保护级别 | 针对您的目标及两个量表的建议设置 | [下方](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#goal-and-protection-level) | | 通知 | 问题、已修改的消息和每日摘要；您专属的控制机器人 | [下方](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#notifications) | | 证据与备份 | 时间戳、更多见证人以及加密的异地副本 | [下方](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#evidence-and-backups) | | 服务器全天候运行 | 一个不支持 SSH 的云服务器，可通过控制面板进行创建和删除 | [高可信度](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#from-the-panel) | | 独立见证者 | 已签名的检查结果将发布到您的 Telegram 频道或 Discord 上 | [见证人](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/) | | 代码检查 | 将正在运行的程序与 GitHub 上的公开提交进行比较 | [下方](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#code-check) | ### 目标与保护级别 四个问题： 1. **用途是什么？**个人记录、调查，或是案件证据。 2. **您打算监控多少内容？**少量聊天（最多约 50 个）、大量聊天（最多约 500 个）还是整个账户？这将把聊天列表的上限设置为 1,000、3,000 或 20,000。 3. **照片和文件？**仅限文本、照片和短媒体（照片 20 MB，视频 100 MB），或全部（视频和文档各不超过 1 GB）。选择“全部”并包含完整 账户时，还会保留 4 GiB 的可用磁盘空间。 4. **它将在何处运行？**这台电脑，或者一台始终处于运行状态的服务器。 建议列表中列出了独立时间戳、drand 以及 Telegram 的设备列表，每项 均附有一行说明其作用。时间戳可设置为每 60、30 或 10 分钟生成一次，适用于个人 记录、调查或证据；drand 和设备列表需要时间戳。仅需 **应用**以下更改：这些内容、附件策略以及上述两个参数。每次 更改都是一条日志记录，此外 `setup.applied`。通知、站外副本、 服务器、网关DNS、代码校验和见证人作为后续步骤提供，并配有 各自的表单。 两个指标是根据当前设置计算得出的，而非基于目标： | 规模 | 要点 | | --- | --- | | 可信度 | 签名日志 1、时间戳 3、drand 1、设备列表 1、代码校验匹配 1、见证人轮询 1、经过认证的服务器 2、网关 DNS 日志 1 | | 可靠性 | 常驻服务器 3 个，异地副本 3 个，对象锁定 1 个，问题通知 1 个 | **最高**阅读量为 80% 或以上，50% **为高**，25% **为中等**，低于此为**基本**。 可靠性目前根据问题 4 的答案中“始终在线”的服务器进行计算， 在检查任何服务器之前。 ### 通知 通知通过 Apprise 发送至 Telegram、Discord、Slack、ntfy、电子邮件、Matrix 以及 100 多种其他服务。选择一项服务，填写一两个字段并发送测试消息，或者 直接粘贴 Apprise 地址。 - **问题**：磁盘空间几乎已满、账户已注销、收集、复制或时间戳 错误。在密封服务器上，开放的 SSH 端口或登录行为也会构成问题。 - **变更**：在被监视的聊天中，已删除、已编辑和缺失的消息将按 每次检查一条通知进行汇总（除非在“参数”中更改，否则每分钟检查一次）。 - **已完成的功能**：历史记录、导出和存储副本。 - **每日摘要**将于服务器时间设定的指定时间发送。 通知中包含聊天名称和消息数量。消息摘要默认处于关闭状态；若 开启该功能，消息正文将从本机发送出去。 **您的操作员机器人**是您通过 @BotFather 创建的专属机器人，用于回答 `/status` 并 `/stats`，并可选地 `/pause`, `/resume` 和 `/copy`。仅列出的聊天和 Telegram 用户 ID 可以使用它；对话内容保存在工作区中。如果另一个应用程序已经接收其命令，请使用一个单独的 机器人。请参阅 [通知](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Notifications.md)和[操作员机器人](https://phishdestroy.github.io/TgWitness/zh/docs/reference/storage/#operator-bot-and-completion-notices)。 ### 证据与备份 - **独立时间戳**每隔 5 到 1,440 分钟，仅将每个已签名检查点的 SHA-256 发送至 RFC 3161 权威机构和 OpenTimestamps 日历。**Anchor 目前** 正在运行一个轮次。参见[时间戳](https://phishdestroy.github.io/TgWitness/zh/docs/reference/timestamp/)。 - **更多见证记录**（在被选中前均处于关闭状态）：最新一轮的 drand 轮次、Telegram 的 已登录设备列表（不含 IP 地址），以及 Cloudflare Gateway 记录的服务器 DNS 查询日志。参见[可选记录](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#optional-records-in-evidence-mode-drand-and-telegram-devices)。 - **加密备份**会将日志、文件、检查点和聊天记录导出到 S3兼容存储（Wasabi、Amazon S3、Backblaze B2、Cloudflare R2、MinIO）。 所有内容都会先在此机器上进行加密。**请下载加密密钥**并将其 单独保存：没有该密钥，备份副本将无法被读取。在“治理”或“合规”模式下启用“对象锁定”功能， 可确保对象在设定的天数内不会被删除。参[见异地备份](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Off-site-Copy.md)。 ### 代码检查 检查已安装的程序是否与已发布的版本匹配。 1. 输入一个 GitHub 仓库（官方仓库已预填）以及一个标签、分支或提交。 2. **“Check now**” 通过该工作区的外部请求路由，向 GitHub API 查询 该提交的文件列表。它将每个被测程序文件的 git blob ID 与该提交进行比对。即使在 Windows 环境中检出时换行符已被转换，仍能匹配成功。 3. 结果列表会显示已更改、新增和缺失的文件（每类最多 50 个），并保存为 一份 `source.checked` 日志记录。 结果仅在运行中的程序文件未发生变更时才视为有效： 更新后请重新检查。无需令牌，且仅支持公共仓库； 聊天记录和凭据不会被上传。匹配操作用于识别磁盘上的代码。这并非 硬件认证；有关硬件认证，请参阅 [Phala Cloud](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#confidential-vm-on-phala-cloud-intel-tdx)。 ## 保护模式 版本号旁边的切换器显示所选模式以及 18 层 保护层中有多少层处于激活状态，例如 `🟠 Witnessed 9/18`。在 **“扩展功能”→“保护级别”**中**切换模式**可打开选项。每种模式描述一个目标，并列出 尚缺的内容；记录、签名和保存的设置在所有模式下均保持一致。 | 模式 | 用于 | 新增功能 | | --- | --- | --- | | 🟢 简单 | 监视聊天并保留副本 | “聊天”功能用于导出日志和聊天记录；签名操作在后台运行 | | 🟡 已签名 | 向平台、主机或滥用处理部门提交报告 | 签名存档、日志检查、检查点、交接摘要 | | 🟠 已见证 | 可能有人声称记录被篡改的情况 | 一个独立见证人发布经签名的日志头 | | 🔴 符合法庭要求 | 供律师、警方或法院使用的证据 | 时间戳、加密的异地副本、报告中的案件详情 | | 🟣 GitHub 认证 | 任何人都能验证其软件的记录 | 代码检查与 GitHub Actions 捕获 | | ⚫ 摩萨德 | 针对资金雄厚的对手展开的高风险案件 | 一个全天候运行的密封服务器、一个隐藏的 IP 地址，以及全部 18 层防护 | 各层结构：每条记录均经过签名并链式连接；带签名的运行收据；通过 SHA-256保存的附件；带签名的检查点；重新检查；问题警报；只读见证访问； 按计划进行的见证检查；RFC 3161 时间戳；OpenTimestamps 证明；经过验证的 最新时间戳；加密的异地副本；报告中的案例详情；匹配代码 检查； Telegram 永远不会看到这台机器的 IP；外部请求通过代理进行；副本上的 对象锁定；一个封存的、包含提供商记录的服务器。处于关闭状态的层设有 **“设置”选项**，点击后会打开其表单。选择较低模式时会要求确认，且 不会删除任何内容。 ## 更多工具 **Extras → Independent capture**: connect a separate browser or AyuGram recorder, pin its signing key, select capture options, start/pause, take snapshots and download verified signed archives. Each recorder has its own manual login, route, journal and key. Both connections start disabled. See the English [Independent capture guide](https://github.com/phishdestroy/TgWitness/blob/main/docs/OPTIONAL-CAPTURE.md). - **查询存档**：搜索已保存的观察记录，审查来源，然后决定 是否将其发送给 AI 模型。参见[存档分析和](https://phishdestroy.github.io/TgWitness/zh/docs/reference/analysis/) [本地 OCR 及转录功能](https://phishdestroy.github.io/TgWitness/zh/docs/reference/media-analysis/)。 - **参数**：数据收集的限制与频率、复核、下载、配置文件、 通知和导出。支持按名称搜索，显示 **仅显示已更改的** 中的值，并使用 **恢复默认值…** 将 默认值保存为草稿。**保存参数** 会从下次使用时起应用这些值， 每次更改都会生成一条日志记录。 - **访问权限**：审阅员、分析师和操作员拥有各自独立的令牌，访问范围仅限于选定的 工作区、聊天群组及权限。详见[“访问权限”部分](https://phishdestroy.github.io/TgWitness/zh/docs/reference/access/)。 - **系统日志** ：该进程自启动以来执行的操作（连接、代理变更、 登录、登录失败、设置变更），其中 IP 地址已被隐藏。**“跟随新行** ”功能可将最新一行始终保持在视图中。消息仅保存在日志中。 - **集成**：AI 服务提供商、[只读 MCP](https://phishdestroy.github.io/TgWitness/zh/docs/reference/mcp/) 连接以及 [已签名的 webhook](https://phishdestroy.github.io/TgWitness/zh/docs/reference/webhooks/)。 - **Case Board**：位于证据旁边的团队私有笔记、书签和片段。参见 [Case Board](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-board/)。 - “导出”中的 **GitHub Actions capture**：从您的分支中捕获的一段聊天记录。参见 [密封捕获](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md)。 --- # Telegram · 数据采集原理 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/ 观察范围、实时更新、复核、附件、用户操作以及“缺口”的含义，逐条记录。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 观察范围、实时更新、复核、附件、用户操作以及“缺口”的含义，逐条记录。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [收藏集](https://github.com/phishdestroy/TgWitness/blob/main/docs/COLLECTION-MODES.md) ![集合](https://phishdestroy.github.io/TgWitness/assets/chapter-collect.svg) TgWitness 记录已连接的 Telegram 账户所观察到的内容。该日志保存 这些观察结果、其时间顺序以及随附的上下文信息。它不会 根据缺失的消息或账户处于连接状态的情况，推断出未被观察到的操作。 **本页内容** - [从登录到日志](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/#from-login-to-a-journal) - [观察范围：选定的聊天、某个文件夹或整个账户](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/#observation-scope-chosen-chats-a-folder-or-the-whole-account) - [范围与事件选择](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/#scope-and-event-selection) - [自主操作](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/#own-actions) - [调查模式：加入团队并与机器人对话](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/#investigation-mode-joining-teams-and-talking-to-bots) - [重新检查分级](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/#recheck-tiers) - [消息历史记录与来源说明](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/#message-history-and-attribution) - [历史快照](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/#history-snapshots) - [附件处理](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/#attachment-handling) - [暂停、锁定、断开连接和重启](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/#pause-lock-disconnect-and-restart) - [账户隔离与验证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/#account-isolation-and-verification) ## 从登录到日志 关于自毁照片和文件，请参阅[自毁媒体](https://github.com/phishdestroy/TgWitness/blob/main/docs/EPHEMERAL-MEDIA.md)。 本文阐述了优先级处理程序、已保存和不可用结果，以及 API 收集器中阅读回执屏蔽功能的限制。 流程图 · 授权用户账户 → 选择可访问的群组和频道; 选择可访问的群组和频道 → 保存事件和附件设置; 保存事件和附件设置 → 开始监控; 开始监控 → 接收来自活跃客户端的更新; 接收来自活跃客户端的更新 → 应用来源与事件政策; 应用来源与事件政策 → 追加一份经过签名的观察记录; 追加一份经过签名的观察记录 → 查看或导出日志; 追加一份经过签名的观察记录 → 处理队列中的任何附件; 处理队列中的任何附件 → 附上下载结果 · 授权用户账户 · 选择可访问的群组和频道 · 保存事件和附件设置 · 开始监控 · 接收来自活跃客户端的更新 · 应用来源与事件政策 · 追加一份经过签名的观察记录 · 查看或导出日志 · 处理队列中的任何附件 · 附上下载结果 **图表转为文本** 1. 授权用户账户 → 选择可访问的群组和频道 2. 选择可访问的群组和频道 → 保存事件和附件设置 3. 保存事件和附件设置 → 开始监控 4. 开始监控 → 接收来自活跃客户端的更新 5. 接收来自活跃客户端的更新 → 应用来源与事件政策 6. 应用来源与事件政策 → 追加一份经过签名的观察记录 7. 追加一份经过签名的观察记录 → 查看或导出日志 8. 追加一份经过签名的观察记录 → 处理队列中的任何附件 9. 处理队列中的任何附件 → 附上下载结果 授权、访问数据源、运行中的采集器以及完整交付是 三个不同的问题。登录成功并不意味着可以访问所有群组。 传输连接成功并不意味着所有相关更新都已送达。 ## 监控范围：选定的聊天群组、某个文件夹或整个账户 来源 → **监控范围**决定了工作区将记录哪些聊天记录。 | 模式 | 记录 | 新聊天记录 | | --- | --- | --- | | 选定聊天（默认） | 仅限您手动添加的聊天记录 | 绝不自动添加 | | Telegram 文件夹 | 该账户某文件夹中的聊天记录：包含按名称列出的聊天记录，加上该文件夹的分类（联系人、非联系人、群组、频道、机器人），减去被排除的聊天记录，以及（如果文件夹有此说明）已归档的聊天记录 | 匹配的聊天记录一经激活即被添加；您在 Telegram 中添加到文件夹的聊天记录将在一小时内被捕获 | | 完整账户 | 该账户所见的所有聊天记录 | 每当出现首次更新时，新的聊天、群组、私聊或机器人都会被立即添加进来 | - **消息来源类型**（频道、群组、私聊、机器人）可进一步细化文件夹和 整个账户模式。所选聊天可为任意类型，包括私聊和机器人。 - **被排除的聊天室**在任何模式下均不会被记录。在文件夹模式和整个账户模式下， 对源聊天室执行*“排除*”或*“移除”*操作会将其加入此列表，因此范围设置不会再次将其纳入。 若手动再次选择该聊天（在“来源”或“聊天”中），则将其从列表中移除。该列表 最多可容纳 5,000 个聊天；超过此限时*，“移除”操作*将被拒绝，但可选择暂停该聊天。 - **自身操作**（默认开启）：该账户发送的消息、其编辑操作以及 回复键盘的按键操作。关闭后，将跳过外发消息和编辑操作。 - 切换到某个文件夹或整个账户时会要求确认：这些模式会记录 私人聊天和第三方消息，仅应用于专用账户。 确认操作及每次范围变更都会生成经过`scope.changed`签名的记录。 - 通过范围添加的聊天记录将显示为标记为*“auto*”的来源，记录格式为 `scope.applied` （在开始时及每小时）或 `source.discovered`（监控期间的新聊天）。切换回 选定的聊天记录将暂停所有自动添加的来源。 以下情况不适用： - **秘密聊天**不属于这些云端收集模式的范围。目前正在开发一个独立的 [秘密聊天实现](https://phishdestroy.github.io/TgWitness/zh/docs/reference/secret-chats/)；该实现未 包含在本文档所述版本的已发布收集器中。 - **当 TgWitness 未运行时，不会进行任何记录。**重启后，它会向 Telegram 查询遗漏的更新并重新检查聊天记录，但在长时间 中断后，Telegram 无法返回所有数据。报告和 `verify.py` 会将此类时段显示为数据缺口（参见[覆盖范围](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#coverage-continuity-gaps-and-unobserved-ids)）。 - 初始仅列出前 1,000 个对话（限制值可在**“参数”**中查看）；较早的 聊天记录将在下次激活时被添加。已添加聊天的早期历史记录不会被获取——如有需要，请 创建历史记录快照或导出完整聊天记录。 - 不会应用那些随时变化的文件夹条件（如静音、已读）：此类聊天 仍会受到监控。 - 在另一款应用中点击的**内联（回调）机器人按钮**对第二个 会话不可见；机器人的回复或编辑会被记录下来。回复键盘按键操作会作为外发 消息发送，并标记为 `button_press`。 - 聊天量越大，请求就越多。Telegram 会因消息量被其视为 过高而限制账号，这也是使用专用账号的又一个理由。 ## 范围与事件选择 每个工作区都有其独立的来源。TgWitness 不会加入群组、接受 邀请，也不会自动枚举所有成员。来源必须是 该账户已可访问的。 启动时，收集器会将选定的数据源 与该账户可见的对话进行比对；除非 **在“参数 → 从账户列表读取的聊天**”中另有规定，否则将检查前 1,000 个对话。 未找到的数据源将被标记为**“访问未确认**”，不会被视为已将您移除。 | 设置 | 收集 | 禁用时的效果 | | --- | --- | --- | | 新消息 | 普通已发送消息 | 后续的编辑/删除操作可能无法与先前捕获的文本进行比对。 | | 编辑 | 已交付编辑后的消息版本 | 中间的更改不会在后续过程中被重建。 | | 删除操作 | 范围限定删除通知与非范围限定账户级通知 | 删除通知不会被添加到日志中。 | | 反应 | 已交付的反应快照 | 不添加单独的反应更新。 | | 会员 | 已发送会员服务消息和参与者更新 | 这些会员观察内容未被纳入。 | 设置适用于工作区中所有选定的消息源。保存表单以应用 更改；更改将通过带签名的“更改前”和“更改后”值进行记录。禁用某类别 不会删除之前的记录。重新启用该类别也不会补录遗漏的更新。 操作记录及其他群组服务事件与这些 开关设置相互独立。当会员服务功能启用时，会员服务消息仍会生成消息记录， 即使普通的新消息捕获功能已被禁用。捕获的 Telegram 对象保留嵌入的元数据；开关设置并非信息遮蔽规则。 **私人聊天和普通群组中的删除操作**会以消息 ID 的形式出现，而不包含聊天信息。 这些聊天共享一个账户级别的消息 ID 序列，因此当带有该 ID 的消息 此前已被保存时，其所属聊天即可确定：删除操作将记录在该聊天中， `chat_resolution` 解释了具体原理。 从未被保存的ID将作为**范围未定的删除**记录，其 来源明确标注为未知；收集器不会进行推测。Telegram从不透露是谁删除了 某条消息；当被删除的消息由该账户发送时，记录中会注明 （`deleted_message_was_outgoing`），但不会指名删除者。 ## 自主操作 被监控账户发送的消息标记为 `outgoing`。关于外发 消息的编辑说明指出：在私聊和群聊中，仅消息作者可进行编辑；而频道 帖子则可由其他管理员编辑。 当一条发送的消息重复了该聊天中 最新保存的回复键盘上的按钮文本时，该消息会带有`button_press`标记，并附有指向 该键盘记录的链接。 “排除自身操作”的原则同样适用于后台重新检查和自动生成的新聊天记录。 被跳过的发送消息会向前推移重新检查的位置，从而避免阻塞后续收到的 消息。明确的面板操作以及手动请求的历史快照仍会被记录下来。 ## 调查模式：加入团队并与机器人对话 **“来源 → 观察范围 → 调查模式**”为专用 账户配置观察范围，该账户将加入团队聊天群、启动机器人并向其发送消息：涵盖整个账户、所有 来源类型、自身操作，以及每个出现的聊天群或机器人的资料及其最近 200条可见消息。 检查表单并点击**“保存范围**”；切换至整个 账户时，系统会要求进行常规确认。 - **按钮。**消息下方的按钮将与该消息一同保留，并在**“聊天”**界面中显示：链接、网页 应用、登录链接、待复制的文本、回调数据、内联查询、请求电话 号码或位置的信息。 链接以文本形式显示，且绝不会由面板自动打开。当机器人 仅更改按钮内容（例如生成新的支付链接）时，这即被视为消息的新版本，无论 是实时更新还是重新检查的结果。 - **新聊天和机器人。**在“文件夹”和“整个账户”模式下，**当新的聊天或机器人 出现时**，系统会在其出现后立即进行保存： - 其作为`source.profile`记录的概况：机器人描述和命令、用户、群组或频道的“关于”文本 、成员、关联聊天以及Telegram返回邀请链接时的 邀请链接； - 将其最新的可见消息（最多 1,000 条）作为标记为 `new_chat` 的历史快照： 刚加入的团队聊天中的早期消息，或观察者注意到该聊天之前 机器人所说的话。已实时保存的消息不会重复记录。 启用该模式时，列表中已有的聊天将不带快照被添加进来。 FloodWait 会暂停此操作，并在之后恢复；失败情况会被记录，而 聊天的实时记录将继续进行。这包括在解析新聊天 身份时的等待：待处理的个人资料/历史记录任务将保留以供重试，而现有的 更长的全账户范围等待时间不会缩短。 - **按需生成配置文件。****聊天 → 配置文件 → 保存配置文件 现**可保存任何来源的当前配置文件； 最新配置文件将显示在消息上方。 - **聊天状态快照（预览版）。**消息流之外的状态会在没有 消息的情况下发生变化：取消固定所有消息不会留下消息级别的痕迹；管理员失去 权限；礼物被隐藏、转换、升级或退款。 在监控期间，每个已启用的 消息源都会被定期读取，并保存为带签名的`chat.state`记录：标题、用户名、 描述、成员和管理员数量、关联聊天、慢速模式、置顶消息 ID （最多 100 个）、管理员及其权限和头衔，以及频道和 用户个人资料中显示的礼物（最多 100 个）。 每条记录都会列出与上一快照的差异： 已更改字段（含更改前后的值）、新增或移除的置顶消息，以及新增、 更改或不再列出的管理员和礼物。Telegram 不会说明在两次快照之间 是谁进行了更改，也不说明更改发生的时间。 - Telegram 拒绝显示的部分内容（例如，对于非管理员的成员而言， 该频道的管理员列表）会在 `errors` 中标注；其先前值会被保留并列在 `carried_forward` 中，绝不会被报告为已移除。 - 仅计数发生变化的记录，以及未检测到变化的检查，均引用 带有 `state_seq` 和累积 `state_overrides` 的最后一个完整状态。完整状态至少 每七天写入一次，且只要计数以外的任何内容发生变化，也会写入。 - `parts_complete` 标记上限列表。添加需要完整的早期列表， 移除需要完整的当前列表，而显式的空值则记录清空操作。 - **参数 → 聊天状态**用于设置间隔（默认 12 小时，0 将快照 功能关闭）、数据源之间的暂停时间、读取哪些部分，以及是否记录未发现 变更的检查结果。`FLOOD_WAIT` 和 `FLOOD_PREMIUM_WAIT` 将停止剩余的 快照请求，保留任何更长的全账户级截止时间，并使 中断的聊天在等待结束后仍可再次尝试。 - **不可见。**在其他 Telegram 应用中点击的内联（回调）按钮、机器人对此类点击作出的响应弹窗或 链接，以及在其他应用中使用的邀请链接均不会传送到 TgWitness。但机器人随后发送或编辑的内容会被记录下来。 ### 面板操作指南 **“聊天”功能**现已包含一个迷你客户端，该客户端使用所选工作区的 Telegram 账户： - 编写一条纯文本消息，或在已保存的消息下方选择**“回复”**。即使范围不包括外发更新，系统生成的外发 消息仍会被记录下来。 - 点击当前回调或文本按钮下方的**“Press”按钮**。服务器将再次获取 该消息，若键盘输入内容与保存版本不符，则拒绝该操作。 回调收据保留 Telegram 的弹出文本、提醒标记和 URL；回复内容也会显示 在对话下方。URL 仍为可选中文本，不会自动打开。 - 展开“**打开 Telegram 链接**”，输入 `@username`、公共 `https://t.me/name` 链接、 `https://t.me/+invite` / `joinchat/invite`，或带有 `?start=parameter` 的机器人链接，然后点击 **“保存预览**”。在加入之前，原始链接和 Telegram 的预览都会被签名。 **加入/打开并观察**：随后加入群组/频道或打开用户/机器人，将 该聊天添加为已启用的数据源，并向机器人发送`/start`（包括其启动参数）。 等待管理员批准的加入请求将记录为“待处理”，而非“成员身份”。 开启“**开始监视**”功能，可实时捕获收到的回复。当 监视处于暂停状态时，面板操作仍可正常进行，但此时仅保证其直接响应会被保存。 当监视正在运行时，新添加的来源将使用已配置的配置文件/历史记录导入设置。 当某个来源处于暂停状态时，请在**“来源**”中启用该来源，然后再发送消息或点击其按钮。 `interaction.preview`、`interaction.requested` 和 `interaction.result` 是证据导出中包含的普通签名 日志事件。请求会标识账户、消息/按钮 或预览记录，以及观察程序是否正在运行。收据可区分成功、 拒绝、待批准和未知结果。中断的请求可能已到达 Telegram：在执行新操作前请检查聊天记录。 重用请求 ID 可检索其 已保存的收据，而无需重复操作，包括重启后。当当前页面会话中同一操作收到模棱两可的响应时，面板会保留该 ID。 当操作成功后刷新视图失败时，面板也会保留该 ID：收据 仍保持可见，再次点击即可检索。 回调和加入 RPC 仅允许一次 尝试；可重试的读取操作将保留其配置的重试策略。立即切换聊天 会立即清除草稿和回复目标，并禁用发送功能，直到新对话加载完毕。 此迷你客户端支持文本和回调按钮。Web 应用、登录/手机号/位置请求、 支付、内联查询和附件仍需 Telegram 客户端；其保存的按钮 元数据仍可见。新控件使用英文文本。 ## 重新核对分级 重新检查功能会再次向 Telegram 查询遗漏的消息、编辑记录以及 Telegram 不再返回的消息。 标有星号的来源为**优先**来源，默认每 15 分钟重新检查一次； 所有其他来源每 6 小时重新检查一次。选定的聊天群组初始为优先来源，通过 文件夹或整个账户添加的聊天群组则为常规来源。 每次循环最多重新检查 30 个来源， 其余来源将等待下一分钟；重新连接后，优先级来源将优先处理。这两个 时间间隔均在“来源 → 记录设置 → 重新检查”中设置（0 表示关闭该层级），并 记录为 `recheck.changed`。 未读消息将从上次处理中断处开始向上获取，最多为 **“参数 → 每次聊天和处理中恢复的未读消息数**”（默认值为 1,000 条）。因此，在长时间中断后， 重新检查会填补整个缺口，即使比该缺口更新的实时消息已被优先保存 也是如此。仍在补全数据中的聊天将在下一分钟再次被重新检查，而不是 等待其层级间隔结束； `recheck.completed` 显示 `continues_after` ，直到操作完成。 比较内容包括消息文本、实体、键盘输入（包括删除操作）以及附件 内容/标识。 仅更改文件访问哈希值或文件引用并不构成 编辑，Telegram 自动生成的内容也不构成编辑：链接预览加载、故事浏览量、该账户解锁的付费 媒体、发票收据等。聊天记录中保存的每个版本都链接到其完整的日志记录，包括媒体元数据。 ## 消息历史记录与来源归属 假设采集器先观察到“10:00 开会”，随后看到“11:00 开会”， 接着收到一条删除通知。它会将这三条不同的观察结果追加到日志中： 原始文本保留，编辑后的内容作为独立版本保存，而通知则记录了 已观察到删除操作。 如果数据采集是在首个版本消失后才开始的，则该文本将无法获取。 如果在离线期间发生了多次编辑，则仅能保存后续观察到的 版本。删除通知无法恢复从未被捕获的内容。 消息发送者并不一定就是编辑者。Telegram通常不会 提供删除消息的用户身份或确切的删除时间。未知行为者 仍无法被识别。反应快照和参与者更新仅包含 Telegram向该账户显示的计数和身份信息。 序列号表示观察顺序。采集器的 UTC 时间戳即为其 本地时间；若提供 Telegram 源时间戳，则将其单独存储。 两者均非独立的可信时间戳。 ## 历史快照 快照从已启用的来源请求最新可见消息，每次最多 500 条。结果标记为历史观察记录。手动快照会独占一个空闲账号；请先明确暂停监控。重复观察会保留为独立记录。 快照遵循附件政策，但与实时事件切换机制相互独立。 它们不会还原已删除的消息或遗漏的中间版本。您可以在 暂停状态下请求生成快照；其中排队的任何附件将等待观察开始 且下载进程运行后才进行处理。 **历史记录**是单独的独占任务：依次读取所选来源并下载其队列中的附件，不启动监控。暂停会释放账号，恢复则继续已保存的任务。有关多个空闲账号上的日期、语言和回复筛选，请参阅[分布式聊天导出](https://github.com/phishdestroy/TgWitness/blob/main/docs/DISTRIBUTED-EXPORT.md)。 ## 附件处理 附件下载默认开启，当可用磁盘空间低于 1 GiB 时会暂停。收集器会将 消息监控和下载任务一并提交。该任务保留原始媒体 描述符和大小策略，因此后续编辑过的附件不会被悄然替换。 下载操作在消息捕获后执行。下载完成后将生成一个包含 SHA-256 哈希值和字节数的 `media.saved` 记录。被跳过、失败、重试和中断的 任务将产生不同的结果。任务被加入队列并不证明文件已被完整保留。 已完成的文件还必须与原始观察到的附件 描述符中的字节数相匹配。较短或意外较长的响应不会被记录为已保存的媒体文件。 **各类别均**设有存储限制：照片、视频、GIF 和动画、圆形视频消息、 语音消息、音乐和音频、贴图以及文件。 每种类型均可单独关闭，并设有 1 至 2,000 MiB 的独立大小限制；新工作区初始设置为：照片 20 MiB， 视频 100 MiB，文件、音频和圆形视频 50 MiB，语音和 GIF 20 MiB， 5 MiB用于贴纸。新工作区默认关闭GIF和贴纸功能，需手动开启。在按类型设置限制之前已保存策略的工作区，将保持所有类型启用，并保留其针对每种类型的单一 限制。*最大文件大小*设置将一次性调整所有类型。 关闭某类文件会生成 一个`media.skipped`记录；未知大小或超大文件将不会被下载。大文件将根据 其大小和256 KiB/s的基准速度获得额外的下载时间。任务在 重启后仍会保留，但过期的引用、访问权限丢失或文件被删除仍可能导致无法恢复。 待处理任务会保留与其关联的限制值，因此提高的限制仅适用于新文件。 禁用某类型或降低其限制值也会跳过该类型所排除的待处理文件，每个文件都会生成 一条`media.skipped`记录；禁用下载功能会暂停队列，直到该功能被重新启用。 ## 暂停、锁定、断开连接和重启 | 动作或状态 | 效果 | | --- | --- | | 切换工作区 | 更改面板视图；其他收集器的状态保持不变。 | | 锁定面板或关闭标签页 | 保持服务器和监控功能持续运行。 | | 暂停观察 | 停止该收集器并保留队列中的附件处理工作。 | | 禁用一个消息源 | 停止未来的范围捕获；在此期间，与其相关的队列中的媒体任务将处于等待状态。 | | 移除来源 | 系统会将其作为消息源忽略并删除相关用户资料；已保存的记录仍保留在仅追加的日志中。待处理的附件将被记录为失败（`source_removed`）。在文件夹模式和整个账户模式下，这些内容同样会被排除在外。 | | 更改连接路径 | 需要暂停，关闭旧客户端，并取消未完成的登录。 | | 停止 Python 进程 | 停止所有工作区；离线期间不会进行任何监控。 | | 主动观察后重启 | 尝试使用已保存的会话恢复已保存的范围。手动暂停将清除该意图。 | 该采集器会记录检测到的断开连接、重试、错误、启动/停止以及 心跳信号。短暂的中断可能会被周期性的连通性检查忽略。 重启后，系统将从保存的更新位置请求遗漏的更新，并 定期重新检查已监控的聊天记录；详见[证据格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#durable-collection-and-process-receipts-02)。快照仅提供上下文信息； 它并不能证明数据缺口已得到修复。 ## 账户隔离与验证 每个工作区都有独立的日志、授权、签名密钥、策略和队列。 只有其活跃客户端才能提交实时观察记录。被拒绝、待处理、 被取代以及连接测试状态的客户端均无法将实时更新写入其日志。 不同账户可以观察同一个群组，但各自的日志仍保持独立。 每个事件都包含前一个哈希值和一个 Ed25519 签名。导出内容涵盖 整个工作区日志，并通过固定序列号进行标识。面板过滤器不会过滤 导出内容；在导出准备期间，数据收集可能仍会超出其边界继续进行。 **“验证日志”**功能会通过显示的 边界检查事件链和签名。当工作区发生变化时，其结果将被清空，面板会标识 检查后新增的记录。ZIP导出功能还会对收集的媒体文件进行验证。 请分别保留指纹和检查点。有关各模式下的采集检查，请参阅 [验证范围](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#verification-scope)部分， 有关常规采集，请参阅[日常操作](https://phishdestroy.github.io/TgWitness/zh/docs/reference/operations/)部分。 --- # Telegram · 秘密聊天：实现与演示 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/secret-chats/ 了解独立的秘密聊天实现方式，试用虚构的界面，并审查未解决的缺陷。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 了解独立的秘密聊天实现方式，试用虚构的界面，并审查未解决的缺陷。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) **2026年11月6日状态核查：**目前正在开发一个独立的秘密聊天实现 。该实现尚未合并到已发布的`main`分支（版本号为`3d23e52b647b`）。 普通收集器和Takeout导出功能不收集秘密聊天数据。 交互式网站演示场景使用虚构数据展示界面； 该演示不支持Telegram通信。 ## 实现位置 提交 `0e60f88e` 在本地开发分支 `fix/panel-routes-sessions` 中添加了**Sources → Pseudo-secret**。已检查的快照为 `bb8788fb685c`。 其实现包括 `tgwitness/secret_chats.py`、应用程序路由、 `tgwitness/static/views/secret-chats.js` 以及专用测试。 该分支中的可选组件 `secret-chats` 使用 [KiaroSama/Telethon-Secret-Chat](https://github.com/KiaroSama/Telethon-Secret-Chat)， 并已固定到 `d87bf037b90060383c7b704d8a06ebb98c621c6f`。该库基于账户现有的 Telethon 授权， 实现了 Telegram 的端到端聊天协议。 仅安装该库并不会为 `main` 添加缺失的集成功能。 ## 开发接口的功能 | 操作 | 记录的行为 | | --- | --- | | 通过用户名或用户 ID 发起聊天 | 发送请求；另一位参与者必须接受该请求。 | | 接受传入请求 | TgWitness将成为该聊天的接收端点。自动接受是一项独立设置，默认处于关闭状态。 | | 发送或接收消息 | 添加一条发出的或收到的`secret_chat.message`记录，并在对话中显示该记录。 | | 接收附件 | 对其进行解密，按 SHA-256 存储其字节，并记录 `secret_chat.file`。 | | 接收计时器或删除通知 | 记录该通知并保留先前捕获的内容。 | | 审查对话内容 | 展示消息、文件、通知以及密钥可视化图表。打开的标签页每四秒刷新一次。 | 在包含该集成的开发版本中，操作员需为所选账户启用该模块 并建立连接。发起、接受和发送操作均需 获得交互权限，且该账户的只读保护必须处于关闭状态。另一位 参与者必须接受新的外发聊天。在上述版本的 已发布应用程序中，这些控制功能尚不存在。 仅涵盖由本次 TgWitness 会话创建或接受的聊天。手机上现有的 秘密聊天仍保留在该设备上。会话导入不会提供 其独立的加密密钥。秘密聊天的密钥素材和计数器存储 在工作区保险库中；保留的消息和解密后的文件遵循常规 的工作区存储保护机制。 ## 网站演示 该网站的“**尝试秘密聊天**”场景展示了一段虚构的对话。它允许 读者发起请求、模拟请求的接受、发送示例消息、接收 预设的回复和文件，并查看计时器和删除通知。还可以接受 传入的请求。控制项会明确标注模拟的对等方操作。 该场景在浏览器内存中运行。重置或刷新页面将清除其内容。它不会登录、 联系 Telegram、生成真实的加密密钥，也不会修改已签名的样本下载文件。 其显示的消息并非经过签名的证据。该场景旨在演示预期 的交互方式；并不证明开发实现已准备就绪。 ## 检查项与未解决的缺陷 现有的五项测试涵盖了加密密钥的持久性、生命周期和消息 记录、传入消息接受策略、只读发送以及附件导出。 在 11 月 6 日的审查中，这些测试针对固定库均通过了验证。另外三项 合成检查在同一快照中重现了缺陷： | 发现 | 后果 | | --- | --- | | 关闭时绕过`read_only` | 当需要阻止交互时，关闭路径可执行远程操作。 | | 重复检测仅搜索最近的500条记录 | 较早的重放数据在重启后可能会生成重复项。 | | 附件下载失败将删除其待处理条目 | 短暂故障会导致重试任务丢失。 | 这些是已知的缺陷，在 [已发布的审计](https://github.com/phishdestroy/TgWitness/blob/main/website/validation/audit/REPORT.md)报告中亦有记录。五项通过的测试并未 涵盖这些缺陷。本次审查使用了合成工作区并模拟了 Telegram 的操作；并未重复实际的握手过程，也未验证生产环境部署情况。 --- # Telegram · 加载源代码历史记录 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/history/ 从已启用的来源加载历史消息，暂停和恢复操作，并验证带签名的进度报告。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 从已启用的来源加载历史消息，暂停和恢复操作，并验证带签名的进度报告。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [收藏集](https://github.com/phishdestroy/TgWitness/blob/main/docs/COLLECTION-MODES.md) ![集合](https://phishdestroy.github.io/TgWitness/assets/chapter-collect.svg) 在**来源**中，查看已启用的聊天，暂停观察，选择标准 API或 Takeout 导出，然后选择**加载完整历史记录**。该运行会固定该来源列表，并将其中可用的历史消息 读取到聊天和已签名的观察日志中。媒体文件使用现有的附件 设置和持久下载队列。这与按聊天进行的已签名 JSON/HTML 导出是分开的。 若需收集整个账户的数据，请选择**整个账户**，开始观察以加载其 源列表，并在开始历史记录前审查该列表。对话列表的限制仍然 适用（默认1,000条，可在参数中调整）。运行成功并不证明 每个账户的对话均已被列出。后续发现或启用的聊天需要再次运行。 在开始历史记录前请暂停观察；每次仅能采集一个账户的数据。 选择一至五个附件处理程序，并决定是否保留可用的最近操作 以及是否比较先前保存的版本。提取操作可能需要在 Telegram 中获得批准，并需 等待服务器指定的时间。这些选项在恢复时保持不变。有关传输、重试和信任的详细信息，请参阅[补全行为和 证据合约](https://github.com/phishdestroy/TgWitness/blob/main/docs/BACKFILL.md)。 ## 暂停、重启和部分结果 - **暂停历史记录**将停止读取。**继续历史记录**将从每个来源中最后一条已提交的 消息开始恢复；重新启动应用也会使运行状态保持暂停，直至恢复。 恢复时需要使用同一闲置的 Telegram 账户。 - 消息观察、附件处理和光标提交在一笔事务中完成。 恢复运行时不会重复已提交的观察结果。实时捕获或 单独、显式启动的运行可独立观察同一条消息。 - 每个数据源（Takeout 中的每个 Telegram 拆分范围）在首次读取时会固定一个最高消息 ID。较新的消息属于 实时观察，而不属于该数据源剩余的历史页面。 - 无法访问的来源以及在采集过程中被禁用的来源仍会显示为 “失败”或“跳过”。其他来源将继续采集；最终结果将不完整。 - FloodWait 的延迟会遵循已保存的账户退避策略。对于瞬时故障，最多重试 五次；资源耗尽或磁盘空间不足时，操作将暂停，光标位置保持不变。 - **结束本次历史运行**会保留已保存的观察结果。该操作不会删除这些观察结果，也不会 取消标准 API 附件任务。结束Takeout会将其剩余的Takeout 文件标记为已跳过；暂停则会保留其可恢复状态。新运行会重新读取已启用的来源。 历史记录补全仅指历史记录的读取操作。附件可能仍处于待处理状态、 处理失败，或被配置的策略排除。请在日志 和附件队列中检查媒体回执；只有字节数据完整且已保存的回执才构成 已保存的附件。历史记录操作是一项显式的快照请求，与 用于选择未来实时事件类别的开关独立。 ## 传输与验证 保存**已签名的进度报告**，然后使用**“导出证据**”功能下载 日志和已保存的附件。后续的证据导出可能包含额外记录； 该报告将其计数器与创建时的日志前缀绑定。 请从此版本的可信代码检出中运行验证器： ``` python tgwitness/verify.py tgwitness-history-report.json --evidence evidence.zip --fingerprint TRUSTED_FINGERPRINT ``` 请将预期的签名密钥指纹单独保留。验证器会检查 报告签名、证据存档、报告检查点、源计划、账户 以及已保存/不可用消息的计数。新运行还会将源进度和 选项绑定到已签名的光标事件中。若未指定`--evidence`，则仅检查 已签名的报告及其内部一致性。旧版进度字段和附件 摘要仍为已签名的收集器声明。证据验证器会检查存档的媒体字节。 对可用历史记录进行签名或完成操作，均无法证明其源自 Telegram、属于原子 快照，或具有历史完整性。消息在阅读过程中可能会发生变化；已删除的 消息、超出最近操作范围的中间编辑内容，以及秘密聊天中的内容， 均无法恢复。控制签名密钥的操作员 可在外部承诺存在之前伪造日志。 请使用单独保留的检查点或独立见证人来验证文档中所述的 篡改检测属性。 采集光标代表本地工作区的状态。仅恢复证据 ZIP 文件并 不会恢复待处理的采集任务或 Telegram 会话。若需继续执行原始任务， 请保留工作区备份。 --- # Telegram · 工作流程与操作 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/operations/ 控制面板的日常操作：模式、监控类别、参数、通知、导出、备份及容量。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 控制面板的日常操作：模式、监控类别、参数、通知、导出、备份及容量。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [部署与恢复](https://phishdestroy.github.io/TgWitness/zh/docs/reference/deployment/) ![部署与恢复](https://phishdestroy.github.io/TgWitness/assets/chapter-operate.svg) 首次连接时，请[使用账户和会话格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/)。 有关保存版本、事件策略和数据缺失的说明，请参阅 [“数据采集原理](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/)”。本指南涵盖日常操作和数据恢复。 受管安装包除启动器外，还包含 **、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` 将同时停止控制面板和数据收集功能。 **本页内容** - [操作员工作流程](https://phishdestroy.github.io/TgWitness/zh/docs/reference/operations/#operator-workflow) - [在不共享主密钥的情况下共享工作成果](https://phishdestroy.github.io/TgWitness/zh/docs/reference/operations/#share-work-without-sharing-the-main-key) - [运行模式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/operations/#runtime-modes) - [监控类别](https://phishdestroy.github.io/TgWitness/zh/docs/reference/operations/#monitoring-categories) - [通知](https://phishdestroy.github.io/TgWitness/zh/docs/reference/operations/#notifications) - [面板布局](https://phishdestroy.github.io/TgWitness/zh/docs/reference/operations/#panel-layout) - [部署环境](https://phishdestroy.github.io/TgWitness/zh/docs/reference/operations/#deployment-environments) - [启动检查与导出](https://phishdestroy.github.io/TgWitness/zh/docs/reference/operations/#startup-checks-and-exports) - [备份、恢复和中断](https://phishdestroy.github.io/TgWitness/zh/docs/reference/operations/#backup-restore-and-interruptions) - [容量与保留期限](https://phishdestroy.github.io/TgWitness/zh/docs/reference/operations/#capacity-and-retention) ## 操作员工作流程 流程图 · 选择存储方式和密钥保护方案 → 使用其令牌打开面板; 使用其令牌打开面板 → 选择工作区; 选择工作区 → 配置直连或代理路径; 配置直连或代理路径 → 输入手机号码或选择文件 / QR码; 输入手机号码或选择文件 / QR码 → 验证账户身份并选择可加入的群组; 验证账户身份并选择可加入的群组 → 保存事件和附件策略，然后开始监控; 保存事件和附件策略，然后开始监控 → 监控错误、访问、队列和磁盘; 监控错误、访问、队列和磁盘 → 保留独立检查点; 保留独立检查点 → 导出和验证材料 · 选择存储方式和密钥保护方案 · 使用其令牌打开面板 · 选择工作区 · 配置直连或代理路径 · 输入手机号码或选择文件/ QR码 · 验证账户身份并选择可加入的群组 · 保存事件和附件策略，然后开始监控 · 监控错误、访问、队列和磁盘 · 保留独立检查点 · 导出和验证材料 **图表转为文本** 1. 选择存储方式和密钥保护方案 → 使用其令牌打开面板 2. 使用其令牌打开面板 → 选择工作区 3. 选择工作区 → 配置直连或代理路径 4. 配置直连或代理路径 → 输入手机号码或选择文件 / QR码 5. 输入手机号码或选择文件 / QR码 → 验证账户身份并选择可加入的群组 6. 验证账户身份并选择可加入的群组 → 保存事件和附件策略，然后开始监控 7. 保存事件和附件策略，然后开始监控 → 监控错误、访问、队列和磁盘 8. 监控错误、访问、队列和磁盘 → 保留独立检查点 9. 保留独立检查点 → 导出和验证材料 授权、传输连接、群组访问权限以及 消息送达完整性是不同的属性。绿色连接状态并不意味着所有 事件均已被捕获。 ## 在不共享主密钥的情况下共享工作成果 开放**访问**功能可为审核员或分析师分配专属令牌。选择其可访问的 账户和聊天群组，随后授予查看、导出或操作权限。 负责启动/停止数据收集的操作员需要整个工作区的访问权限；审核员 的访问范围可限制为单个聊天群组。会话限制、有效期和 IP 规则与 Telegram 账户授权相互独立。请参阅[访问与权限](https://phishdestroy.github.io/TgWitness/zh/docs/reference/access/)。 使用**“打开的会话”**功能可终止单个连接，或撤销访问权限以终止所有 会话。管理员控制台整合了跨 工作区的当前进程活动。关闭会话后，数据采集仍将继续运行。 ## 运行模式 | 模式 | 操作 | 行为 | | --- | --- | --- | | 演示 | scripts\Demo.cmd 或 `--demo` | 合成数据；已禁用真实账户关联功能 | | 观察 | 开始监控 | 记录所选来源的已发布更新 | | 历史快照 | 来源 → 历史快照 | 最多可记录 500 条当前消息；不重建所有历史变更 | | 暂停 | 暂停观察 | 在保留数据和队列任务的同时停止采集 | | 审核/交接 | 导出功能 | ZIP、JSONL/CSV/HTML、检查点、处理回执和时间戳请求 | | 多个账户 | 工作区或顶部的 **+** 按钮 | 在一个进程中可创建任意数量的独立工作区 | 本地演示访问将自动开启，无需手动输入令牌。该功能采用 进程生命周期权限，仅适用于直接回环访问一个隔离的 合成演示环境；主控制面板的令牌不会被披露。真实工作区以及远程 或通过代理访问演示环境仍需进行令牌身份验证。进入演示环境并不授予任何 Telegram 授权。 ## 监控类别 ![支持按账户设置监控参数，并提供合成源数据](https://phishdestroy.github.io/TgWitness/assets/sources.png) 在**“来源”→“记录”→“选择要保留的更改”**中，可分别选择新消息、编辑、 删除通知、反应更新和成员事件。默认设置 保留所有类别。**“消息、编辑和删除”**选项保留原始上下文， 同时禁用单独的反应/成员更新。**“所有可见活动**”选项则恢复 全部五类。预设会更改表单；点击**“保存记录设置**”即可应用。 保存的策略适用于该工作区中所有选定的消息源。其他 工作区将保留各自的设置。每次实际变更都会记录带签名的变更前/变更后 值；当前策略也会包含在处理收据和观察 开始记录中。禁用某类别不会删除之前的观察记录。重新启用 该类别也不会恢复已遗漏的变更。 此版本中不支持按组覆盖类别设置。 当先前内容重要时，请保持“记录新消息”功能启用：删除通知无法 恢复从未被捕获过的文本。操作/覆盖记录及其他群组 服务事件将始终被保留。 明确的历史快照与 实时分类选择相互独立，且可能包含服务消息。这些开关不会 对嵌入在已捕获 Telegram 对象中的反应/成员元数据进行屏蔽。 历史快照在暂停期间可能会将附件加入队列。开始监控以处理 这些附件。“已加入队列”并不意味着已下载。若原始文件不可用，系统不会用 较新的编辑版本进行替换；处理结果将分别记录。 **点击“锁定”**按钮将清除浏览器访问权限和密钥字段，但数据采集仍将继续运行。 关闭标签页后，进程仍将继续运行。停止 Python 进程或服务 将终止数据采集，无论浏览器状态如何。 删除额外的工作区将停止其收集器并清除其本地数据。如果 因文件被锁定或文件系统错误导致删除中断，控制面板将报告失败，并 将该工作区标记为不可用（`DeletionPending`）。请关闭正在使用其 文件的程序，然后重试**“删除”操作**。 重启 TgWitness 不会恢复该工作区的运行状态，也不会 重建其部分已删除的日志或密钥。只有在目录被移除后， 才会记录成功的删除操作；单独导出或备份的副本仍 受其自身的保留策略约束。 ## 通知 打开**“扩展”→“通知”→“配置”**。TgWitness使用 Apprise 向 Matrix、Telegram、Discord、Slack、ntfy、电子邮件及其他 受支持的服务发送提醒。您可以在一个工作区中添加多个接收端。 1. 每行输入一个 Apprise 目标 URL。请根据您使用的服务 [，参考服务目录和 URL 格式](https://appriseit.com/services/)进行设置。 2. 开启“**发送通知**”功能，然后选择问题警报、受监控 聊天中的变化以及每日摘要。摘要显示的时间以服务器时间为准。 3. 若希望在警报中包含已删除和已编辑 消息中的保存文本，请开启**“包含简短摘录**”选项。 4. 点击**“保存通知**”，然后点击**“发送测试**”以检查送达情况。 若要使用您自己的接收端，请使用 Apprise 的 [JSON Webhook](https://appriseit.com/services/json/)。 例如， `jsons://notify.example.org/tgwitness` 通过 HTTPS 将 JSON 发送至该 端点。这是一个虚构的示例；请将其替换为您的实际目标地址。 目标和设置属于所选工作区。变更通知 涵盖其监视的来源，包括新添加的聊天。顶部栏中的铃铛图标 还会列出最近的问题和聊天变更。 在演示中，通知控件可见但发送功能已禁用。请在真实的工作区中配置 发送设置。通知使用该工作区的 Direct、SOCKS5 或 HTTP 路由；MTProxy 无法传输通知。SMTP 等非 HTTP 目标需要 直接路由。 ## 面板布局 ![使用合成数据连接工作区](https://phishdestroy.github.io/TgWitness/assets/connection.png) **日志**显示观察结果、搜索和筛选结果。编辑操作会显示已捕获的版本； 删除操作会显示先前内容（如有）。来源不明的信息将明确标注。 统计数据可在**“概览**”中查看；采集详情保存在本地指南中。 打开已编辑的消息，使用**文本内差异**或**并排比较**来对比其不同版本； **原始数据**会显示已保存的字段。隐藏链接和机器人按钮的更改会 单独显示。打开附件预览以检查已保存的图像、音频或视频； 下载按钮可让您随时获取保存的原始文件。 当新记录到达时，**Live** 会实时更新日志和聊天。在审阅时可以将其暂停， 或者在准备好后使用新事件按钮；后台收集会继续运行。按 **Ctrl/Cmd+K** 可查找面板操作并搜索日志。 **“来源**”部分包含监控范围（选定的聊天、Telegram文件夹或整个 账户）、各类可访问的聊天、带有优先级星标标记的选定来源、附件 及重新检查设置，以及历史快照。私有来源通过对话/ID 进行选择，不包含公开链接。“访问状态”描述的是最近一次检查结果，而非永久权限。 筛选来源并勾选其复选框，即可批量启用、暂停或将其标记为优先。 在可用聊天列表中，**添加所选项**会使用您当前勾选的项； **添加所有匹配项**会使用当前的搜索和类型筛选条件。 **“聊天”→“联系人”**列出了所有已保存消息的联系人；若该聊天已启用联系人资料功能， 点击即可打开该联系人的资料页面，其中包含指向日志记录的链接。 **Witness** 会生成只读的见证令牌，显示每个见证者最后一次检查的时间，并 提供运行一个（[独立见证者](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/)）所需的命令和选项。 **“参数”**部分包含工作区中所有未在其他页面列出的限制和速率设置： 已读取的对话数量、聊天列表的重新读取频率、心跳和检查点 间隔、启动缓冲区、重新检查如何分发请求（首次延迟、每次 轮次、聊天间隔、已恢复和重新请求的消息），磁盘预留空间、下载的超时和 重试，用户资料的搜索条件（包括您自定义的正则表达式）， 通知的大小和频率，快照、ZIP 文件及浏览器下载的限制，以及 Telegram 客户端的超时和重试设置。 每个字段都会显示其范围和默认值；已修改的字段会 被标记，并可逐个或全部恢复。每次更改都会以 “`parameters.changed`”的形式记录，并附带更改前后的数值，而观察开始记录则会注明 当前生效的数值。 这些值从下次使用时起生效；客户端超时和重试则从 下次连接时起生效。重新检查间隔、附件类型和大小、证据以及异地备份 间隔仍保留在各自的页面上，其取值范围不限于预设值，而是涵盖该范围内的任意数值。 顶部栏中的铃铛图标列出了被监控聊天群组中的近期问题和变化；未读项 会持续计数，直至被标记为已读。变化按聊天群组和小时分组显示（“12条已删除， 1条已编辑，0条未找到”），而诸如注销或磁盘空间已满等问题将始终保留在列表中， 无论聊天群组活动多么频繁。 **账户**注册从手机号码字段开始。**继续操作**将直接进入 验证码输入环节，仅在缺少 API 凭据时才会要求输入。二维码和文件导入是 其他选项卡。已保存的 API 凭据仅在所属工作区内重复使用。 登录界面没有侧边栏、统计数据或设置说明。 **“设置**” 图标可打开 API、代理、存储及附加账户控制选项。新安装 从这里开始；已连接但未选择消息源的账户则从**“选择聊天**”开始。 更改路径需要暂停监控，并会取消未完成的登录操作。现有 日志无法在用户不知情的情况下重新绑定到其他 Telegram 账户。 **导出功能会**检查日志的完整性，并生成可移植文件。其工作区 ID 可传递给下载命令行界面（CLI）。每次导出都会锁定完整的日志前缀；后续 事件将进入下一次导出。搜索过滤器不会改变包的范围。 详细的签名和覆盖范围信息请参见**“验证与限制**”部分。 在“收集器状态”面板中，会显示收集器状态、排队/失败的媒体文件、最旧的待处理媒体文件、可用 磁盘空间、请求暂停情况，以及访问状态未确认的来源。**这些**详细信息初始状态为折叠状态，并在“账户”页面中被隐藏。一个设置 卡片会显示下一步操作：连接账户、选择来源或开始监控。 账户列表为加载时的快照； 所选工作区会定期刷新。这并非多进程 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](https://phishdestroy.github.io/TgWitness/zh/docs/reference/deployment/) 文件及[服务模板](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.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. 记录系统停机时间及验证结果。历史快照无法证明 在中断期间未发生任何删除操作。 证据 ZIP 文件不包含会话数据/私钥，且并非完整的服务备份。 以下四类内容采用不同的保护方式： | 内容 | 保护 | | --- | --- | | 未设密码的导出文件（默认） | 未加密。文件经过签名，因此可检测到任何更改，但任何持有该文件的人均可阅读其内容。 | | 设有密码的导出文件 | 如果您设置了密码，生成的导出文件将原样封装为 WinZip AES-256 压缩包，该压缩包可由 7-Zip 和 WinRAR 打开；密码不会被存储（[符合证据处理规范](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/)） | | 日志数据库及存储在磁盘上的附件 | TgWitness 不会对数据进行加密；请使用加密磁盘或卷 | | Telegram 会话与签名密钥 | 数据目录中已加密（`credentials.enc`、`signing.enc`、`network.enc`） | 全量备份是指上述所述的已暂停数据目录，而非导出文件。 两者均应使用受保护的存储空间和经过精心设计的传输机制。临时服务器导出文件存储在每个工作区的 `temporary-exports/` 中；已完成的响应会被清理，而中断的导出 文件将在下次启动时被移除，此时该工作区的实例锁处于持有状态。 连接恢复事件并不保证能够恢复期间的更改。 持久化媒体任务和 Telegram 更新位置在重启后仍会保留；请参阅 [证据格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#durable-collection-and-process-receipts-02)。 ## 容量与保留期限 默认限制（均可在**“参数”**中修改）：前 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`。 应测量每秒事件数、队列年龄、媒体数据字节数和磁盘延迟，而非仅统计 群组数量。合成本地基准测试无法保证 Telegram 的消息送达。 系统不支持自动保留和删除。删除日志尾部将使其 与已保留检查点之间的关联失效。 优先级重新检查功能已存在：默认情况下，标星的来源每 15 分钟重新检查一次， 其他来源每 6 小时重新检查一次（参见[重新检查级别](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/#recheck-tiers)）。如上所述， 提供受密码保护的导出功能。 Telegram/代理实时接收、持久回放、 管理员日志和反应轮询、隔离工作进程、由 TgWitness 自身对本地日志和媒体 进行的加密以及独立审查仍属独立工作。范围限定访问权限 详见[“访问与权限](https://phishdestroy.github.io/TgWitness/zh/docs/reference/access/)”文档。 请参阅 [READINESS.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/READINESS.md)、[LIVE_ACCEPTANCE.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/LIVE_ACCEPTANCE.md) 和 [VERIFICATION.md](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/)。 --- # Telegram · 调查模式 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/ 涵盖频道、群组、私聊和机器人的全账户调查，从调查范围到经过验证的案件资料包。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 涵盖频道、群组、私聊和机器人的全账户调查，从调查范围到经过验证的案件资料包。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) ![调查](https://phishdestroy.github.io/TgWitness/assets/chapter-investigate.svg) 可跨频道、群组、私聊和机器人追踪案件全过程，从最初的 数据采集到带引用时间线及可验证的交接记录。交互式网站 版本位于 `/docs/cases/`；[预览说明](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/PUBLISHING.md#preview-the-website-locally)。 **本页内容** - [已验证案例：四个对话中目标地址发生变化](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/#worked-case-a-destination-changes-across-four-conversations) - [1. 界定案例并收集完整记录](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/#1-define-the-case-and-collect-the-whole-account) - [2. 盘点所有来源并获取历史背景](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/#2-inventory-every-source-and-acquire-historical-context) - [3. 保留不断演变的案例和有意的交互](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/#3-preserve-the-evolving-case-and-deliberate-interactions) - [4. 关联不同聊天中的观察结果](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/#4-connect-observations-across-chats) - [5. 构建跨聊天室时间线](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/#5-build-the-cross-chat-timeline) - [6. 添加账户视角，同时保留其来源](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/#6-add-account-perspectives-without-losing-their-origin) - [7. 整理并验证案件移交](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/#7-assemble-and-verify-the-case-handoff) - [调整调查内容](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/#adapt-the-investigation) ## 案例分析：四个对话中目的地发生变化 一条公告指向了一个机器人。一个行动小组正在讨论一个新的付款 目的地，该机器人的键盘上显示了该信息。公告被编辑后， 一条私信跟进再次提到了该目的地，随后一条群组消息消失了。 需要弄清楚的问题包括：变更前后观察到了什么，哪些 Telegram 账户发布了每条内容，目标出现在何处，哪些附件字节 被保留下来，以及哪些时间间隔仍无法确定？ 本示例中的所有姓名、ID、时间及日志引用均为虚构。该 工作流使用当前功能；案例图仅为示意图，并非由应用程序自动 生成的图表。 流程图 · 频道 → 工作区日志; 群组 → 工作区日志; 私聊 → 工作区日志; 机器人 → 工作区日志; 工作区日志 → 搜索所有来源; 工作区日志 → 附有记录参考信息的人物档案; 工作区日志 → 已保存版本和附件收据; 搜索所有来源 → 分析师时间线和来源登记册; 附有记录参考信息的人物档案 → 分析师时间线和来源登记册; 已保存版本和附件收据 → 分析师时间线和来源登记册; 工作区日志 → 带签名的证据 ZIP 文件; 分析师时间线和来源登记册 → 附带经单独验证的证据材料的案件移交; 带签名的证据 ZIP 文件 → 附带经单独验证的证据材料的案件移交 · 频道 · 群组 · 私聊 · 机器人 · 工作区日志 · 搜索所有来源 · 附有记录参考信息的人物档案 · 已保存版本和附件收据 · 带签名的证据 ZIP 文件 · 分析师时间线和来源登记册 · 附带经单独验证的证据材料的案件移交 **图表转为文本** 1. 频道 → 工作区日志 2. 群组 → 工作区日志 3. 私聊 → 工作区日志 4. 机器人 → 工作区日志 5. 工作区日志 → 搜索所有来源 6. 工作区日志 → 附有记录参考信息的人物档案 7. 工作区日志 → 已保存版本和附件收据 8. 搜索所有来源 → 分析师时间线和来源登记册 9. 附有记录参考信息的人物档案 → 分析师时间线和来源登记册 10. 已保存版本和附件收据 → 分析师时间线和来源登记册 11. 工作区日志 → 带签名的证据 ZIP 文件 12. 分析师时间线和来源登记册 → 附带经单独验证的证据材料的案件移交 13. 带签名的证据 ZIP 文件 → 附带经单独验证的证据材料的案件移交 ## 1. 界定案件并收集完整案情 1. 在独立的工作区中连接采集账户。在[“案件看板](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-board/) ”或您的案件登记簿中，记录案件编号、账户 ID、工作区及 观察开始时间。请独立保留受信任的签名密钥指纹。 2. 若要创建专用采集账户，请打开**“来源”→“观察范围”→“调查模式**”。该预设选项包含 **“整个账户**”、“频道/群组/私聊/机器人”、“自身操作”、“来源 配置文件”以及新发现来源的最新 200 条可见消息。 请核对设置，点击**“保存范围**”，并完成范围确认。 主账户可使用选定的聊天或文件夹；全账户采集功能 仅对已标记为“调查”状态的账户开放。 3. **加载聊天记录**，并将来源与该账户的对话列表进行比对。 检查 排除项。**参数 → 从账户列表中读取的聊天数量**默认值为 1,000，最大支持 20,000。超出列表限制的来源会在 其变为活跃状态时被添加。记录实际枚举的内容。 4. 在**“记录设置**”中，选择**“所有可见活动**”，并保存 监控设置。请检查附件类型/限制及可用磁盘空间。 5. 开始观察。验证一条受控的新消息、编辑操作和删除操作，然后 保留测试参考信息及任何失败情况。 “整个账户”范围会在保存的设置范围内记录账户可见的活动。 该工具不会访问秘密聊天，也不会自动加入所有关联的群组。此外， 它也不会补录所有现有对话。请参阅[“采集范围”](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/#observation-scope-chosen-chats-a-folder-or-the-whole-account)。 ## 2. 盘点所有信息来源并获取历史背景 维护一个来源登记表，每行记录一次聊天： | 字段 | 记录 | | --- | --- | | 品牌定位 | 工作区、账户 ID、数字聊天 ID、标题和类型 | | 可见性 | 成员身份/角色、访问权限（已确认或未确认）、排除项 | | 实时捕获 | 开始时间、选定的事件类型及后续政策变更 | | 日志历史 | 快照请求/完成情况、限制、时间及记录引用 | | 完整历史 | 按聊天分组的导出文件名、边界及完成/失败状态均附有数字签名 | | 附件 | 已完成的媒体接收记录、哈希值、大小以及跳过/失败的结果 | | 覆盖范围 | 服务中断、数据采集不完整、FloodWait、消息不可用及其他缺失情况 | 针对每个消息源，请选用合适的采集方式： - “在**来源**中**加载完整历史记录**”功能会将已启用来源中可用的过往 消息加载到工作区日志中。该功能支持暂停/恢复 操作，并提供带签名的进度报告。参见[“历史记录采集](https://phishdestroy.github.io/TgWitness/zh/docs/reference/history/)”。 - **历史快照**将最近可见的消息保存到观察日志中。 其默认上限为 500 条；**通过“参数 → 最大历史快照**”可将 该上限提高至 10,000 条。这些是当前的历史观察记录，而非重建的编辑记录。 - **“导出完整聊天记录”→“导出完整聊天记录**”，或**“聊天”→“导出聊天记录**”，将 当前可见的某次聊天记录导出为一个独立的、经过签名的 `chat.json` / `chat.html` 数据包。针对案件中的各个消息源重复此操作，并保留每个结果。 - **当出现新的聊天或机器人时**，可保存其资料以及多达 1,000 条最近的 消息；调查模式下则保存 200 条。启用该模式后，现有聊天记录不会 追溯性地被纳入。 - **下载可见附件时**，将根据配置的策略保留相应字节数。 必须提供包含 SHA-256 校验值和字节数的完整 `media.saved` 收据。队列中的 任务、缩略图或文件名均不视为已保留的附件。 完整聊天记录导出不会将所有 消息填入日志或联系人资料中。如需在 TgWitness 中分析特定历史记录，请使用**“加载完整历史记录**”或“限定范围的日志快照”功能。在开始 历史记录运行前，请检查已启用的来源列表。无论采用哪种方式，均无法恢复 Telegram 已不再返回的内容。 ## 3. 保留不断演变的案件及有预谋的互动 将活跃案件聊天室标记为优先来源。审查复核间隔、持续 补录及媒体结果。在使用该账户期间，请保持采集器处于监控状态。 使用**“聊天”→“个人资料”→“立即保存个人资料”**以保留来源元数据，例如 描述和机器人命令。这与从已保存消息中生成的 联系人个人资料是分开的。 当案件涉及追踪消息来源或与机器人交互时： 1. **“打开 Telegram 链接 → 保存预览”**功能会在执行操作前记录所提供的链接及返回的 预览内容。 2. **“加入/打开并观察”**操作将执行加入/打开操作，并在提供时发送机器人的 start 参数。待批准的加入请求将被记录为“待处理”。 3. 面板生成的文本回复和支持的按钮点击操作将保留 `interaction.requested` 和 `interaction.result`。回调收据可保留 返回的弹出文本、警报状态和 URL。 这些是真实的账户操作。在另一款 Telegram 应用中点击回调按钮的行为 对采集器不可见，尽管由此产生的消息或编辑操作可能被记录。该 微型客户端不处理网页应用、支付、电话或位置相关的工作流。 有关确切的行为，请参阅[面板交互说明](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/#act-from-the-panel)。 ## 4. 关联不同聊天记录中的观察结果 在**“日志**”中，选择**“所有来源**”并搜索已记录的内容。打开匹配的 记录，并保留工作区、聊天、消息 ID、序列号和记录哈希值。 在相关聊天中，打开**“联系人”→“启用个人资料**”，然后查看某人： - 随时间推移观察到的名称/用户名以及 Telegram 数字 ID。 - 回复内容需包含源记录的引用信息。 - **此外……**该 ID 曾在此工作区日志中的其他聊天记录中发过言。 - 活动记录、编辑/删除操作，以及被提及的钱包、手机、用户名和链接。 - 已保存的头像元数据及类似的缓存头像，并标注了各自的来源。 在调查结论中使用衍生个人资料前，请先打开引用的记录。个人资料涵盖 拥有已保存消息的人员，而非群组中的每位成员。**参数 → “每个事实引用的记录数”**仅限制引用列表的范围，而非底层活动数量。 提及和头像相似度仅为线索；它们不能证明所有权或身份。 在示例中： | 链接 | 记录 | 支持的观察内容 | | --- | --- | --- | | 同一发件人账号 | 群组 #146 及后续私信 #205 | 两者均提供 Telegram 发件人 ID 71001 | | 同一目标 | #146，机器人键盘 #173，频道编辑 #188，私信 #205 | 所有内容均包含`pay.example.invalid/new`；所有权/控制权尚未确定 | | 相同的保存文件 | 已完成媒体收据 #151 和 #209 | 所保存字节的完整 SHA-256 值完全一致 | | 频道来源说明 | #101 和 #188 | 若未注明发件人，请勿将频道帖子归因于用户 71001 | 比较附件哈希值及其关联的消息引用，并按这些记录中提供的 Telegram ID 将账户 时间线分组。 请将团队的工作笔记保存在[“案件看板](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-board/)”上：对您依赖的记录 （如 #146、#188 和 #205）添加书签，突出显示确切的目标字符串，并 保存两个记录之间或某个时间范围内所有记录操作的片段。 笔记 和状态会将团队的审查记录保留在其各自的已签名历史记录中，可与 源观察记录区分开来。 ## 5. 构建跨聊天室时间线 使用**“聊天**”中的已保存版本及其**日志记录 #…** 链接。在 **日志中**，将**所有来源**与**编辑**、**删除**及**覆盖内容**合并。 如已提供，请同时保留 `source_at` 和 `observed_at`。 | 示例观察时间 | 参考资料 | 观察 | | --- | --- | --- | | 09:00 | 频道 #101 | 原始目标已捕获 | | 09:12 | 群组 #146；媒体 #151 | 已发布新目标；文件下载完成 | | 09:16 | 机器人 #173 | 键盘指向新目的地 | | 09:20 | 频道 #188 | 公告已编辑；两个保存版本均保留 | | 09:24 | 私有 #205; 媒体 #209 | 同一发件人 ID 的收件人地址重复；文件字节内容保持不变 | | 09:28 | 群组 #231 | 已收到删除通知；删除者及确切删除时间不详 | 其他记录发生在这些示例引用之间。序列号用于排序 观察结果；历史快照可能包含更早的源日期，且到达时间 晚于实时事件。请区分快照、恢复的消息、删除通知以及 重新检查时缺失的结果。 将覆盖缺口标记为未知时间段。后续 历史数据的获取并不意味着可以追溯性地确立不间断的观测记录。 ## 6. 添加账户视角，同时保留其来源信息 为每个独立账户使用单独的工作区，并重复执行其清点操作。 每次比对时，请保留账户 ID、角色、签名密钥指纹及来源参考信息。 消息编号并非跨聊天/账户的全局标识符。 “案件看板”在每个工作区内保存与来源关联的笔记和集合。 群组界面可集中查看账户状态，并能将不同工作区的 导出数据打包。您可在案件笔记或分析工具中关联这些来源；每个日志 均保留其原始来源和签名密钥。系统不会生成全局搜索结果或合并的跨工作区 时间线。 单个频道/超级群组的多账户导出 将使用符合条件的账户获取该聊天记录的历史。 对于较长的操作，需通过[独立见证人](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/)保持边界。 使用受控投递检查来验证 每个账户的捕获路径和可见性。 ## 7. 整理并核实案件移交 请将以下内容整理到由分析师编制的案件目录中： | 资料 | 目的 | | --- | --- | | 案件笔记与来源登记册 | 问题、数据收集政策、访问权限/角色、调查结果、替代解释及数据缺口 | | 时间线 | 每条记录均包含时间信息以及工作区/聊天/消息/序列的引用信息 | | Case Board（若使用）导出和片段 | 与源文件关联的书签、引文、团队笔记、收藏集、修订历史以及选定记录均需与证据 ZIP 文件进行核对 | | 每个工作区对应的签名证据 ZIP 文件 | 完整的记录日志、清单及包含的保存媒体；面板过滤器不会缩小日志导出范围 | | 单独签名的用户资料文件 | 已根据对应的工作区证据核查了引用的来源 | | 带签名的完整聊天记录导出 | 当前可见历史记录的采集，与观察日志分开处理 | | 可信指纹和早期检查点 | 关键身份信息与保留日志的边界 | | 若已配置，则生成Witness证据文件 | 独立日志、签名条目和见证指纹 | | 验证结果和已交付文件的哈希值 | 检查了什么内容、传输了哪些字节以及传输给了谁 | 来自可信安装环境，包含文件名及每个工作区的实际指纹： ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 --checkpoint retained-checkpoint.json python -m tgwitness.verify profiles-operations.json --fingerprint TRUSTED_PUBLIC_KEY_SHA256 --evidence evidence.zip python -m tgwitness.verify history-channel.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 python -m tgwitness.verify board-slice.json --evidence evidence.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 ``` 保留实际的验证结果和原始证据。将“案件看板”中的工作区 笔记与引用的源材料一同导出。将跨工作区的 调查结果汇总到顶级案件目录中；每个 TgWitness 证据都有其专属的 签名和验证流程。 ## 调整调查 | 案例 | 追踪 | 交付 | | --- | --- | --- | | 由机器人驱动的订单/支付纠纷 | 条目公告 → 已保存链接预览 → 机器人启动参数 → 消息和键盘版本 → 面板回调收据 → 私信/群组跟进 | 已观察到的报价/响应时间线及经过验证的来源；仅凭支付链接无法证明已发生支付 | | 事件发生后被删除的消息 | 所有受影响的聊天记录 → 保存的原始内容/编辑记录 → 删除或复查时缺失的结果 → 保留的媒体文件 → 覆盖范围及其他账户视角 | 保留版本及明确标注的未知时间段；不假设任何虚构的删除行为者 | | 某参与者在不同聊天群中使用了不同的名字 | 数值发件人 ID → 姓名/用户名历史记录 → 回复 → 其他被观察到的聊天 → 引用的目的地/文件 | Telegram 账号的活动时间线，附有其源记录的链接 | [收藏参考](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/) · [个人资料验证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#people-profiles) · [证据移交](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#investigation-handoff) · [验证已完成](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/) --- # Telegram · 功能与限制 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/features/ TgWitness 的当前采集模型、多账户工作流、导出功能及操作边界。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) TgWitness 的当前采集模型、多账户工作流、导出功能及操作边界。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [项目参考](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) ![项目参考](https://phishdestroy.github.io/TgWitness/assets/chapter-project.svg) TgWitness 可保存已连接账户可访问的 Telegram 对话， 记录观察到的变更，并生成可验证的导出文件。本参考文档描述了 采集模型、当前工作流程及其边界。 **本页内容** - [独立应用程序](https://phishdestroy.github.io/TgWitness/zh/docs/reference/features/#standalone-application) - [共享调查](https://phishdestroy.github.io/TgWitness/zh/docs/reference/features/#shared-investigations) - [归档工具](https://phishdestroy.github.io/TgWitness/zh/docs/reference/features/#archive-tools) - [可选内容](https://phishdestroy.github.io/TgWitness/zh/docs/reference/features/#optional-extras) - [协议与私有源代码](https://phishdestroy.github.io/TgWitness/zh/docs/reference/features/#protocol-and-private-sources) - [多个账户](https://phishdestroy.github.io/TgWitness/zh/docs/reference/features/#multiple-accounts) - [捕获与来源标注](https://phishdestroy.github.io/TgWitness/zh/docs/reference/features/#capture-and-attribution) - [容量与 Telegram 限制](https://phishdestroy.github.io/TgWitness/zh/docs/reference/features/#capacity-and-telegram-limits) - [可靠性与恢复](https://phishdestroy.github.io/TgWitness/zh/docs/reference/features/#reliability-and-recovery) - [证据模型](https://phishdestroy.github.io/TgWitness/zh/docs/reference/features/#evidence-model) - [导出、部署与移交](https://phishdestroy.github.io/TgWitness/zh/docs/reference/features/#export-deployment-and-handoff) - [稳定版发布标准](https://phishdestroy.github.io/TgWitness/zh/docs/reference/features/#stable-release-criteria) ## 独立应用程序 TgWitness 拥有独立的安装流程、数据目录和发布生命周期。随附的 Web 界面负责配置和审查；导出的记录可独立使用。 操作员连接其账户，选择彼此可见的消息源，并获取 一份保存的观察日志。控制面板展示内容、保存的更改、观察 来源以及已知的缺失信息。其他调查人员可以对导出的材料进行验证。 该面板区分了账户授权、对来源的访问权限、采集器 活动以及记录范围。在评估 消息较少或存在连接问题的时段时，请综合审查这些状态。 ## 共享调查 管理员可签发作用域限定于工作区和 单个聊天的[访问令牌](https://phishdestroy.github.io/TgWitness/zh/docs/reference/access/)，并可设置按操作授权、IP 限制、有效期、登录次数限制 及会话控制。只读审核员无需获得 Telegram 授权或主面板密钥，即可审查案件。 仅限聊天的访问权限与 全账户设置及完整日志导出功能相互独立。 自动 MTProxy 会从四个公共来源或 运营商目录中维护可用的 Telegram 路由。[IP 模式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/connection/#ip-modes)决定 在连接失败时是必须等待另一个代理，还是可以使用明确允许的直连路由。 外部 HTTP 请求拥有独立的路由和关闭开关。 ## 归档工具 0.7.1 包含[历史数据采集](https://phishdestroy.github.io/TgWitness/zh/docs/reference/history/)、[存档搜索与分析](https://phishdestroy.github.io/TgWitness/zh/docs/reference/analysis/)、[只读 MCP](https://phishdestroy.github.io/TgWitness/zh/docs/reference/mcp/)、[本地 OCR/转录](https://phishdestroy.github.io/TgWitness/zh/docs/reference/media-analysis/)以及[外发 webhook](https://phishdestroy.github.io/TgWitness/zh/docs/reference/webhooks/)功能。分析报告和识别出的文本与 捕获的事件保持分离。 [“案件看板](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-board/)”可在工作区内添加与来源关联的书签、引文、笔记和 收藏集。[报告生成器](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-reports/)用于选择 材料、章节以及八种设计模板之一，以支持 HTML/PDF 导出。 ## 可选附加功能 日常配置流程为：账户 → 数据源 → 监控。**附加功能**是一个独立的存储目标， 包含一个 Telegram 见证机器人和一个 GitHub 捕获预览功能。每个功能在显示 设置前都会说明其可用性和要求。点击卡片可查看操作指南；此操作不会注册或启动任何服务。 机器人设置分为三个步骤：创建只读访问权限、选择发布设置，以及 在 Witness 主机上启动。网络和发布选项、现有连接以及 验证命令均按需显示。 下载的配置文件与 正在运行的 Witness 实例不同。切换附加功能时会保留草稿；账户变更和锁定 操作将清除临时令牌和表单。内置指南包含启动说明。 [GitHub Actions](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md)会从您的 分支中启动一个已固定的采集器，捕获一个聊天记录，并生成包含工作流溯源信息的加密交接包。 ## 协议及私有来源 **MTProto 是 Telegram 的协议；Telethon 是 TgWitness 用于 与 MTProto 通信的 Python 库。**它们并非替代性的连接方式。“收集”功能使用 MTProto； 可选的“见证”功能则通过 Bot API 发布经过签名的校验记录。 每个工作区都有其专属的授权客户端和账户更新流。TgWitness 从配置好的来源中筛选观察数据，并针对历史快照和媒体下载等功能 分别发出明确的请求。 私有消息源无需公开用户名。Telegram 的对等节点类型和数字 ID 是 其标识符；标题和用户名可能会发生变化。访问权限取决于现有的 成员身份和权限设置。TgWitness 不会自动加入消息源，也不会绕过 加入审批。来自其他账户的访问哈希值并非通用访问令牌。 数据采集模型必须考虑加入群组前的隐藏历史、参与者/管理员 角色、会话撤销、权限移除或变更、群组向超级群组 的迁移、主题/论坛、关联讨论、频道身份以及不可用的 附件。并非所有组合都已在实际环境中经过验证。 在收集器启动时会检查来源可见性。若在限定范围内的 对话结果中缺少某个来源，则表示**访问状态未确认**，而非已证实被删除。一个来源不可用 并不妨碍对其他可访问来源的观察。切勿在公开的测试数据中放置 邀请链接或真实会话。 ## 多个账户 该面板支持任意数量**的工作区**，每个工作区均拥有： - 授权机制、加密存储库及连接路径。 - SQLite日志和Ed25519签名身份。 - 精选来源、媒体队列和捕获设置。 - 监控状态、错误、检查点和导出功能。 切换显示的工作区不会停止另一个采集器的运行。跨工作区的重复账户 授权将被拒绝。已绑定到某个 Telegram 账户的日志无法重新分配给另一个账户；但允许重新连接同一账户。 这可确保账户身份及相关消息 ID 范围的完整性。 该应用程序未设定固定的工作区数量。每个工作区都在 一个共享的 Python 进程和事件循环中运行其自身的采集器 任务，用于连接监控、媒体下载、复核以及新聊天记录的采集。吞吐量取决于工作负载。为 实现进程隔离，请使用独立的安装、端口和数据目录。 为每个账户分配其可访问的来源。不同的账户可能观察同一个 群组，但它们的观察记录保持独立，并保留其来源。同一台由操作员控制的机器上的两个账户 并非两个独立的见证者。**导出群组时，** 会将单独签名的作品空间 ZIP 文件打包，并附带一份签名的文件列表，其中包含其 作品空间 ID、哈希值和签名密钥指纹。 每个日志都保留其自身的 边界。在案件笔记或分析工具中构建跨工作区的综合时间线， 同时保留这些来源引用。 ## 捕获与归因 “来源”功能提供按账户设置的新消息、编辑、删除、点赞 及成员资格开关。预设选项可保留所有类别，或仅保留消息/编辑/删除记录。 该策略适用于工作区中选定的群组，重启后仍保持有效，并附有 变更前后的签名。默认设置为保留所有类别。 关闭某类别 不会删除旧记录；重新开启该类别也不会重建已遗漏的事件。 操作记录、其他群组服务事件以及显式历史快照是 独立的。捕获的 Telegram 对象可能会保留嵌入的元数据，无论 “单独更新”开关的设置如何。目前尚不支持按群组覆盖类别设置。 | 资料 | 立即捕获 | 边界 | | --- | --- | --- | | 消息 | 文本、同行/消息 ID、发件人元数据、回复及原始更新信封 | 作为由采集器签署的、账户可见的观察记录予以保存 | | 编辑 | 新观察到的版本及任何先前保存的版本 | 系统停机期间的中间编辑内容可能会丢失；发件人未必就是编辑者 | | 删除 | 通知及先前捕获的内容（如有） | 通常不包含删除者或精确的操作时间 | | 账户级删除通知 | 原始通知；已解决的记录包含保存的聊天记录及关联方法 | 要求范围内必须且仅有一个先前保存的私聊或普通群组匹配项；其他 ID 保持为 `deletion.unscoped`。频道和超级群组 ID 不包含在此关联范围内 | | 反应 | 已交付的计数器及可见的近期身份信息 | 获取完整的可用反应器列表需要单独查询；频道可能会隐藏身份 | | 会员 | 服务消息及已送达的参与者更新 | 可见性取决于角色和聊天类型；事件缺失并不意味着该事件不存在 | | 管理员操作 | 频道/超级群聊天导出中包含的相关已交付更新及管理员日志快照 | 导出功能会在导出管理员账户可访问日志时读取日志；持续轮询管理员日志的功能不属于此流程范围 | | 附件 | 原始版本描述符、下载字节数/SHA-256 及尝试结果 | 已消失的文件可能无法恢复；最新版本不会被替换 | | 历史 | 当前可见消息的明确快照 | 不会还原所有编辑或已删除的内容 | | 采集进程 | 启动/停止、心跳、错误、设置、作用域和签名运行收据 | 本地库存；GitHub 和 TDX 增加了[独立的环境检查](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#verification-scope) | 界面会标注源事件中提供的账户名称，并保留观察到的 名称和用户名。当事件未指明行为者时，报告将该字段留空。 ## 容量与 Telegram 限制 没有一个通用的聊天数量标准能保证监控质量。 监控能力取决于每秒峰值事件数、附件数量和大小、额外的 RPC调用、活跃账户数、磁盘延迟/可用空间、网络状况、Telegram的限制、 可接受的延迟以及队列深度。 Telegram 将被动接收与主动短轮询区分开来。其更新 文档描述了针对公开 频道/超级群组的额外 `updates.getChannelDifference` 调用，并建议**同时进行短轮询的 来源**最多为**十个**。这并非指仅限选择十个群组，也并非完整性保证。 | 模式 | 目的 | 状态 | | --- | --- | --- | | 标准说明 | 记录来自选定来源的已发布更新 | 已实现 | | 优先级复核 | 已标记的来源使用其自身可配置的间隔，并在每次限定范围内的重新检查过程中具有优先级 | 已实现历史记录和消息查询功能 | 优先级星号用于控制这些复查操作。额外的 ``updates.getChannelDifference` ` 短轮询功能不会作为独立的用户模式对外提供。 任意的高频轮询、忽略 FloodWait 或假设额外账户具有线性容量 均非有效的容量规划模型。默认限制为 前 1,000 个列出的对话，每个历史快照最多 500 条消息， 按类型每份收集文件 1–2,000 MiB，以及 4 GiB 未压缩的签名 ZIP 内容；上述 各项均可在**“参数**”中针对每个工作区进行调整。导出操作没有固定的事件数量上限。 浏览器回退模式默认限制为 128 MiB；流式 CLI 具有可配置的 传输限制，默认值为 5 GiB。 ## 可靠性和数据恢复 已实现的功能包括 SQLite WAL/同步事务；原子性消息 和媒体任务写入；持久化任务和重试延迟；原始版本描述符； 有限重试；持久化媒体 FloodWait；在文本事件的 网络等待之外下载媒体；在后续写入继续进行时保持前缀稳定的导出；原子设置和 审计记录；登录替换失败后保留有效授权； 受损附加工作区的隔离；显式重连尝试；明确的 授权丢失报告；以及使用单调时钟进行实际时间变化检测。 账户和频道的 pts/qts/seq 会在重启后保存并恢复，且被监视的聊天记录 会定期重新核查；详见[证据格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#durable-collection-and-process-receipts-02)。定期保存位置 并不构成对日志接受情况的原子性、无损确认。 每次进程启动时，都会记录上一次的头部和离线边界。当前历史记录 不被视为缺口修复。Telegram 的差异保留是有限的； `differenceTooLong` 无法重建所有已消失的内容。不可恢复的缺口必须 保持明确标注，即使后续的历史快照成功生成也是如此。 ## 证据模型 每条事件记录包含事件序列、本地 UTC 观测时间、来源时间（如有提供）、 事件类型、来源、操作者（如有提供）、原始有效载荷、前一次哈希值及签名。 消息观测记录还会保留采集器账户/运行上下文。 该签名处理收据包含一个随机运行 ID；TgWitness/Python/OS 的 依赖项版本；源文件的 SHA-256 值及聚合指纹；初始账户、 范围和设置；UTC/单调读数；以及前一个日志头。 设置变更、启动/停止及错误信息均记录在同一日志中。检查点在 启动时、监控期间每五分钟（可调整）以及有序停止时被保留。 保留的本地检查点可检测是否回滚至较早的日志前缀。 | 工作原理 | 其功能说明 | | --- | --- | | 文件 SHA-256 | 字节与已知摘要匹配 | | 事件哈希链 | 记录相对于已知边界的排序/关联 | | Ed25519 | 使用特定密钥生成的签名 | | 独立保留的检查点 | 后续内容与保留的边界一致 | | 程序文件大小 | 收集器关于已测量文件的自我报告 | | 有效的独立 TSA 响应 | 在明确的信任假设下，特定字节在 TSA 时间点上的存在性 | 已实现 RFC 3161 请求准备和 OpenSSL 响应验证功能。 证据模式还会将检查点哈希值提交至配置好的时间戳服务。 保留并验证相关机构的响应，以建立独立的时间锚点。 参见 [TIMESTAMP.md](https://phishdestroy.github.io/TgWitness/zh/docs/reference/timestamp/)。 独立保留检查点，控制对签名密钥的访问权限，保存传输 记录，并使用可信软件验证导出文件。[验证范围](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#verification-scope) 部分说明了这些检查如何相互补充，以及适用哪些信任假设。 ## 导出、部署与移交 一个带签名的 ZIP 文件包含原始的 JSONL、CSV、HTML 文件、保留的附件、哈希值、一个 带签名的清单以及一个便捷验证工具。该文件涵盖一个工作区和一个固定的完整 日志前缀。面板搜索过滤器不会在用户不知情的情况下删除记录。 密钥、 令牌和 Telegram 会话被排除在外；原始记录仍可能包含 个人信息和 Telegram 元数据。 请将 ZIP 摘要、可信指纹、检查点、处理收据和交接 记录分别保存。应使用来自可信安装环境的验证工具，而非仅因可执行代码 出现在被检查的 ZIP 文件中就对其予以信任。 浏览器界面本地部署时无需 Node.js、CDN 或外部字体。一个 操作员令牌即可控制整个安装过程。远程访问需要 HTTPS 或 SSH 隧道。 提供了原生 Python 代码和容器配置文件，部署示例位于 [deploy/](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md) 目录下；已执行的平台检查项另行列出。 默认工作区使用数据根目录；额外的工作区使用`profiles//`。 备份需要停止进程并具备完整的数据/密钥集。证据 ZIP 文件 并非应用程序备份。密钥可使用外部主密钥来访问新的数据 目录；日志/媒体加密由操作员的磁盘/卷提供。 参见 [CONNECTION-SECURITY.md](https://phishdestroy.github.io/TgWitness/zh/docs/reference/connection/) 和 [OPERATIONS.md](https://phishdestroy.github.io/TgWitness/zh/docs/reference/operations/)。 ## 稳定版发布标准 在正式发布之前，需说明： 1. 真实的私人群组、超级群组、论坛和频道，包含成员/管理员角色以及 隐藏/可见的历史记录，包括登录/双因素认证、权限撤销和访问权限丢失。 2. 针对已知操作，对编辑、删除、点赞、成员身份及媒体内容进行受控处理。 3. 进程/主机崩溃、磁盘故障/磁盘空间已满、文件引用过期、FloodWait、 网络中断、文件损坏以及数据库回滚。 4. 支持持续的多账户使用，可控制延迟、队列、内存和磁盘资源，包括 同时处理静默和活跃的消息源。 5. MTProto状态推进与日志接受之间存在中断。 6. 在目标操作系统/容器组合上进行干净安装，并验证备份与恢复功能。 7. 对安全性、签名以及归属/证据主张的独立审查。 [“访问与权限](https://phishdestroy.github.io/TgWitness/zh/docs/reference/access/)”部分描述了范围限定面板的访问权限。0.6 版本支持 [“ACCOUNTS.md](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/)”中所述的受限单账户 TData 以及账户文件导入功能。 发布前请审阅 Telegram API 条款。相关研究参考文献和平台 调查结果详见[“RESEARCH.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/RESEARCH.md)”。 --- # Telegram · “案件看板”参考 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-board/ 书签、精确高亮、操作片段、讨论、范围访问以及“案件看板”所使用的签名注释历史记录。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 书签、精确高亮、操作片段、讨论、范围访问以及“案件看板”所使用的签名注释历史记录。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [调查](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/) ![调查](https://phishdestroy.github.io/TgWitness/assets/chapter-investigate.svg) “案件看板”为调查团队提供了一个共享的已保存材料工作视图。您可以对 观察结果添加书签、突出显示具体段落、保存一系列操作，并与同事进行讨论。 卡片会保留其来源引用和已签名的修订历史。团队注释保留在 工作区中，可与原始 Telegram 观察结果区分开来。 [证据模型](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/) · [访问](https://phishdestroy.github.io/TgWitness/zh/docs/reference/access/) · [报告](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-reports/) ![综合调查信息流](https://phishdestroy.github.io/TgWitness/assets/case-board.png) **本页内容** - [处理案例](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-board/#work-with-a-case) - [权限](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-board/#permissions) - [已存储的合约](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-board/#stored-contracts) - [API 和导出功能](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-board/#api-and-exports) - [运行限制](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-board/#operating-limits) ## 处理案件 在“标准”或“专家”模式下打开**“调查”→“案件看板”**。语言设置随面板而定。 在日志记录或已保存的聊天消息旁点击**“**添加**到案板**”，或选中该条目并按 **B** 键。 单击即可将书签添加到“收件箱”。可编辑其标题、标签和备注，或将其移动到 收藏夹。修改后的卡片会附加带签名的修订版本；删除卡片时会保留历史记录。 对于首个案例，请选择一个采集集，并添加能回答某个问题的记录。使用“评论” 功能审查解读结果，然后使用**“演示**”功能逐一浏览卡片及来源上下文。 在[“报告工作室](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-reports/)”中准备 交付成果时，请单独选择“案件看板”中的材料。保存切片不会自动配置报告的数据过滤器。 在已保存的聊天消息中选中文字，即可显示**“突出显示 → 板”**。选择颜色并 添加注释。服务器会核对精确的引文及已保存版本，包括表情符号、从右到左（RTL）文本和 组合符号。界面不会通过被遮盖或转换的文本映射选定内容。 在同一聊天中按住 Shift 键点击两条记录以**进行“切片**”，使用**“按时间切片**”，或保存 日志中当前的聊天、时间段和事件类型过滤条件。已保存的切片具有其自身的权威性 谓词：在日志中打开它时，也会应用多个聊天、消息数量限制和参与者 过滤条件。 **“显示自书签添加以来的记录**”可筛选出后续添加的记录。更改日志 过滤器将退出该切片。在“人员”中**，“按此人操作切片**”功能使用记录的参与者 ID； 该功能不会假设消息作者曾编辑、删除或对消息做出过反应。 “切片”对话框会在允许创建前预览计数。“`all`”包含所有记录类型， 包括快照、编辑、删除、反应、成员资格/服务更新、自身操作、 按钮、媒体结果、恢复的消息以及未来事件类型。该选项描述了 已保存的观察结果。 “未知聊天”删除通知属于独立上下文， 仅对拥有整个工作区访问权限的用户可见，且绝不会被归因于所选的任何聊天。 收藏集具有声明的聊天范围。空范围表示整个工作区。一个收藏集 不能包含其范围之外的卡片；受聊天范围限制的参与者无法阅读范围更广的 收藏集。收件箱是用于未分配卡片的虚拟收藏集。 搜索和筛选仅涵盖可见 卡片；讨论串和提及继承父卡片的访问权限。已删除的评论在讨论中会显示 “墓碑”标记。不会记录查看历史。 **“演示”模式**会打开所选集合中的所有卡片，提供“卡片”、“来源上下文”和“团队 评论”视图，以及键盘上的“上一张/下一张”控制键。该模式不提供任何编辑控件。普通 信息流采用分页显示；“演示”模式按页加载列表，并每次仅检索一张卡片的详细信息。 ## 权限 所有操作均需`view`、工作区/聊天范围及`board.read`权限。`board.write`权限用于添加卡片、 评论、移动操作以及开启/审核状态。`board.manage`权限用于管理采集集、 确认/驳回状态，以及修订/删除他人卡片。状态是团队 的决策，而非加密验证结果。 访问表单预设：审核员 = 只读；分析师 = 读写；操作员 = 读写/管理， 此外还包含其现有权限。现有授权不会自动获取新权限。 主管理员拥有所有权限，并以**“主管理员**”身份发布内容。请使用命名授权 进行归属标注。提及列表仅显示当前能够阅读完整父卡片内容的访问者。 针对聊天 A 的授权无法获取 A+B 的卡片或片段，即使通过猜测其 ID 或提供 虚假的 `target.chat_id` 也不行。目标元数据由服务器根据已签名的事件哈希解析得出。 在响应之前，会过滤收集项、讨论次数、相关卡片和实时通知。 导出操作需要同时具备`export`和`board.read`权限；现有导出者若无板访问权限，将 获得不含团队笔记的普通证据存档。SSE会在每次批量处理前重新核查当前授权。 ## 已存储的合同 与观察记录类似，注释也是以事务方式写入工作区中一个仅追加的 SQLite 表中。 `annotations.jsonl` 是从与 `events.jsonl` 相同的读取快照中导出的精确规范格式文件。 不存在第二个相互冲突的注释存储，也没有 `board.activity` 日志事件。 每行内容应精确包含： ``` { "seq": 1, "at": "2026-11-02T14:00:00.000+00:00", "access_id": "admin", "access_label": "Main administrator", "kind": "board.bookmark", "payload": {"id": "32 lowercase hex digits", "target": {"event_hash": "64 lowercase hex digits"}}, "previous_hash": "64 zeroes for the first record", "hash": "SHA-256 described below", "signature": "base64 Ed25519 signature" } ``` 上文的简短示例展示了封装结构；实际有效载荷包含其模型 默认值和由服务器解析的目标字段。API 请求架构位于 [`tgwitness/schemas`](https://github.com/phishdestroy/TgWitness/blob/main/tgwitness/schemas/board-bookmark.json) 目录下，由 `python tools/build_board_schemas.py` 通过运行时 Pydantic 模型生成。额外的请求字段将被拒绝。若未提供 ID，则由 服务器端自动生成。 调用方无法提供 作者、时间、快照和签名信息。命名授权 ID 遵循 Access 现有的 16 位十六进制格式；卡片 ID 为 32 位十六进制。 规范 JSON 采用 UTF-8 编码，对象键按顺序排序，标记之间无空格，Unicode 未转义， 且不包含 NaN 或无穷大值。注释哈希值是包含 `format: "tgwitness-annotations-v1"` 以及所有七个信封字段（直至 `previous_hash`）的规范对象的 SHA-256 哈希值。 此格式标签将其哈希域与观察结果区分开来。 签名采用 Ed25519 算法，基于 32 个原始哈希字节生成。序列从 1 开始。修订版本保留卡片 ID，并在 ``supersedes`` 字段中注明前一个 注释哈希；修订版本不能更改聊天范围。移动、状态和删除操作均为 独立记录。SQLite 表不支持 UPDATE 和 DELETE 操作。 `case-board.json` 包含 `{statement, signature}`。规范陈述由 工作区密钥签名，并包含 `format: "tgwitness-case-board-v1"`、`public_key`、`created_at`、 `journal_head`、`meaning` 以及 `state`。状态为确定性重放：`annotations_head`、一个 有序的 `items` 数组（包括集合、卡片、评论及已删除项）以及 `status_history`。 各项在不同修订版本中均保留其最后一次注释哈希值、序列号、作者和时间，以及原始 创建者和创建时间。重放过程会检查修订版本、 父项、集合引用以及重复的操作 ID。`manifest.json` 和新的检查点 也会绑定 `annotations_head`。独立保留一个检查点，以检测数据截断或使用 复制的签名密钥进行的改写。 ### 文本版本 `range.start` 是基于零的 Unicode 码点偏移量，`length` 是正的码点计数， 且 `quote` 必须与目标事件中 `payload.text` 或 `payload.caption` 的精确子字符串完全一致。 不应用 NFC/NFKC、大小写转换或字符规范化。 Python 字符串切片和 JavaScript 的 ``Array.from(text)`` 实现了相同的索引机制。标记与 ZWJ 表情符号的组合可能 占用多个码点。``range.version`` 是目标事件的哈希值，而非当前消息 版本或 Telegram 的 UTF-16 实体偏移量。后续编辑绝不会自动重新定位高亮标记。 ### 切片标识与时间 `query` 函数仅接受一个 `chat_id` 或非空的 `chat_ids` 列表，可选的包含起始点 `from` 和结束点 `to`， 包含消息 ID 范围（仅限一个聊天），kinds: "all" 或精确/前缀通配符类型的 `kinds: "all"`， 显式 `actors`，`search`，`hide_system` 以及 `include_unscoped`。日志类型组将展开为 其精确的谓词。 搜索使用日志的 NFC/不区分大小写的有效载荷搜索，且不更改 已签名的源文本。日期需要指定时区，并规范化为 UTC。 日期用于过滤 **observed_at**。Telegram 的 `source_at` 将单独显示。若删除操作没有 源时间戳，则不会生成虚构的删除时间。在时间区间外观察到的延迟记录 不会被纳入该区间；对于特定消息 ID，消息 ID 切片可能包含针对这些消息 ID 的后续删除操作。 快照（`snapshot`）固定了创建时间、日志序列/哈希边界、匹配计数、首/末 序列以及 `result_hash`。后者是按字典序排序的匹配 事件哈希的 UTF-8 规范 JSON 数组的 SHA-256 哈希值，其中空切片用 `[]` 表示。 它还包含确切的 类型计数以及一个 24 格的观测时间微型图。一个切片存储的是查询，而非重复的源 记录。导出时，`board/slices/.json` 会列出当前哈希值以及新增/移除的序列。 验证器会在创建边界处重建原始结果，然后重建当前结果。 新增的记录将作为变更事实进行报告。删除原始事件会破坏不可变的 证据链；系统不会将其作为从切片中进行的普通删除而默认接受。 “反应”快照中的近期参与者列表不完整。资源管理器会比较同一聊天/消息的相邻快照 （包括切片范围外的先前快照），并报告**各观察结果之间的** 聚合计数差异。对于缺失的近期参与者，系统不会认定其已删除某条“反应”。 第一个快照没有推断出的早期状态。参与者的观察结果仍归因于 其被提供的快照，而非某个虚构的操作时间。 ## API 和导出功能 `GET /api/board`接受collection/chat/author/label/state/from/to/q/kind/comments、offset/limit 以及newest/oldest排序参数。`GET /api/board/card/{id}`返回卡片、源文件预览、对话线程、 状态历史记录及相关卡片。参与者子路由返回符合条件的提及选项。 `POST /api/board/{bookmark|highlight|slice|collection|comment|status|move|remove}`用于追加一条记录。 `POST /api/board/slice-preview`用于计算查询。切片记录通过 `GET /api/board/slice/{id}/records`进行分页；重新计算时始终使用当前稳定的读取快照。 实时 `/api/stream` 发布不含有效载荷的 `board` 通知，与日志游标独立。 `GET /api/board/export` 返回一份经过签名的文档。受聊天限制的访问权限将收到一份标注清晰的 签名**披露文件**，绝不会包含其他聊天的注释或完整对话链。完整的证据 ZIP 文件 包含 `annotations.jsonl`、经过签名的 `case-board.json` 以及切片 JSON 附录。 HTML/PDF/JSON 报告 设置可选择“无案例板”、“不含讨论的书签/片段”或“带评论的卡片”。该 部分明确区分了团队意见与观察结果。报告数据过滤器也会限制 可读笔记的内容；证据 ZIP 包中的完整签名源文件则保持完整。 `GET /api/board/slice/{id}/export` 将生成一个带签名的 `tgwitness-board-selection-v1` JSON 片段； `?format=csv` 将生成一个便于使用的表格，但不包含独立签名。保留 JSON 和 ZIP 格式： ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_KEY_SHA256 --board python -m tgwitness.verify board-slice.json --evidence evidence.zip --fingerprint TRUSTED_KEY_SHA256 python -m tgwitness.verify case-board.json --evidence evidence.zip --fingerprint TRUSTED_KEY_SHA256 ``` 选择性检查用于验证签名声明、精确的源记录及其查询在指定边界处的完整性。 证据 ZIP 文件可能更新，但必须包含该前缀。若目标悬空，系统将明确报告。若原始切片快照不同、注释被修改、 重放状态不匹配或源文件被更改，则验证失败。 未带注释的旧存档 仍保留其现有的验证行为。 移交默认设置为**“不包含**”。 显式包含操作会将卡片穿插于已 简化的记录中，省略无法访问/被遗漏的目标，隐藏源文本 已被简化的高亮内容，按照相同的提及/联系人规则清理团队文本，并可选地将 元数据及笔记中已知的调查员标签替换为 R01、R02…… 不披露原始的 `annotations.jsonl`文件。已签名的`tgwitness-case-board-handover-v1`侧车文件和报告 包含相同的最小化内容。切片计数仅描述已披露的记录，原始 快照/查询参与者的详细信息被隐去。 简化工具未识别的自由文本名称仍需 进行审查，这与常规移交流程一致。此衍生文件不保证在编辑后保留原始 注释签名。 ## 操作限制 参数包括 10,000 张卡片和 50,000 条评论的软限制、最多 5,000 条记录的切片页面，以及媒体预览控制。达到软限制时仅会发出警告，不会删除历史记录。 信息流页面 最多显示 200 张卡片。独立 JSON 切片摘录上限为 64 MiB；若需处理更大规模的数据，请缩小查询范围或使用 带签名的 ZIP 文件。独立验证器将注释回放上限设为 256 MiB。 Case Board 未启用也未实现任何外部评论通知功能。 该功能的自动化验收使用虚构数据和模拟的 Telegram 传输通道来 检查存储、访问、渲染和导出情况。有关证据检查范围的详细信息，请参阅[“验证范围](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#verification-scope) ”。 --- # Telegram · 存档分析 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/analysis/ 搜索已保存的消息、审查 AI 输入内容，并保存附有来源参考信息的分析报告。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 搜索已保存的消息、审查 AI 输入内容，并保存附有来源参考信息的分析报告。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [调查](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/) ![调查](https://phishdestroy.github.io/TgWitness/assets/chapter-investigate.svg) [工作流指南](https://phishdestroy.github.io/TgWitness/docs/archive/) · [维基](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md) 使用**“日志**”进行不依赖 AI 的本地搜索；[全文搜索](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/)（预览） 可匹配词形、短语、域名和 @用户名。若要**使用“查询存档”**功能，请先在**“集成**”中 启用并配置提供商。工作区选择器用于选择 账户；表单用于选择聊天记录和观察时间段。 检索在 本地运行。精确短语或域名可缩小检索范围；输入消息 ID 可查询已保存的 版本。查看摘录并打开其日志记录或上下文。 本工具不包含向量数据库，也不支持自动执行 Telegram 操作。 ## 服务提供商与同意条款 AI 功能在每个工作区中默认处于禁用状态。仅主管理员可配置 模型、端点、加密 API 密钥、上下文/输出限制、超时及每日 请求配额。密钥绝不会返回至浏览器。若要保留当前密钥，请将密钥字段 留空；如需移除，请明确将其删除。 Ollama 使用其文档中记载的 [`/api/chat` 端点](https://docs.ollama.com/api/chat)， 该端点输出非流式 JSON 数据。其默认地址为 TgWitness 服务器上的 `http://127.0.0.1:11434`。操作员可通过 `TGWITNESS_AI_LOCAL_ENDPOINT` 更改该地址；此地址不受模型控制。请自行安装 所选模型。TgWitness 不会自动下载该模型。 兼容的服务提供商应具备以 `/v1` 结尾的基础 URL，并支持 [聊天内容补全协议](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)： `messages`、JSON 响应模式、`max_completion_tokens` 以及 `choices[0].message.content`。缺少这些字段的服务不予支持。 连接测试会发送合成文本，并计入请求配额。 每次请求均使用工作区配置的外部路由。被封锁的路由或 仅限Telegram的MTProxy将导致错误；系统不会直接重试。若刻意 配置了本地Ollama地址，则允许访问私有目的地。 环回 AI 端点需要工作区配置的“Direct”外部路由；代理路由将在 传输前被拒绝。对于其他私有服务，适用现有的服务器级私有 目标选择加入机制。预览中会显示端点和外部路由， 包括适用的代理主机。更改该路由需要生成新的预览。 生成前，**发送至模型的数据**包含以下请求信息：问题、 已选中的摘录、事件类型、观察时间及覆盖标记。Telegram 会话、原始字段、提供商密钥、附件字节以及完整的日志 均不属于该上下文范围。请取消勾选不需要的来源，然后明确批准 处理。 外部提供商可能会根据其自身的 政策保留提交的内容。本地执行意味着端点位于本地；这并不保证 独立配置的服务会遵循特定行为。 全球范围内最多同时存在两个服务提供商请求，每个 工作区限一个。预览有效期为十分钟，且仅可生成一个响应。 页面会显示提供商报告的令牌数量；只有 在输入和输出费率均已配置的情况下，才会显示成本估算。失败的尝试也会 消耗每日请求配额。自动重试不会消耗额外配额。 ## 来源与局限性 检索功能在[全文索引](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/#ask-the-archive-and-mcp) 构建完成后启用：根据选定聊天记录中包含词形变体的最佳匹配结果进行检索。关于 近期更改或单条消息版本的查询，以及在索引 构建期间的搜索，均采用针对最新记录的有限词汇检索。预览功能会标注 所采用的方法。检索结果最多返回 24 个来源；长文本会在匹配位置处截断。 截断的摘录和不完整的结果集均会标注。该 时间段指**观察时间**，并不意味着 Telegram 历史记录 是完整的。工作区范围内的事件不会在聊天范围的访问中显示。 缺失的数据将被描述为“在可用存档中未找到”。 该模型不接收任何工具。其源 ID 需与所选 记录进行比对验证，哈希值需重新核查，且引用的字符串必须出现在这些记录中。 未知 ID、被修改的引文以及未被引用的主张将导致答案被拒绝。该应用程序 会生成链接；模型生成的 URL 不能用作引用来源。这些检查 旨在验证来源的存在性和引文的准确性，而非推论的真实性。 在依赖推论结果之前，请对照记录进行核查。 ## 报告 将经过审核的回答保存为一份独立的分析报告。该报告包含模型 摘要、观察到的时间线、提取的链接和标识符、编辑/删除记录、 覆盖范围限制以及源事件哈希值。同时附有提供商、模型、端点、时间以及 提示词模板版本信息。不会自动合并任何身份信息。 分析师的修订和注释与模型摘要分开存储。报告 保存在加密的衍生文件中，索引位于签名事件流之外； 原始事件和媒体内容不会发生改变。只有所有者或管理员才能 打开报告，且会再次验证源访问权限。 下载同样需要导出 权限。第 1 版不会对报告进行签名，也不暗示模型结论是 经过验证的证据。限制：每个工作区 100 份报告，每份报告 100 次分析师修订 。 有关手动 OCR 和文字转录，请参阅[“媒体处理”](https://phishdestroy.github.io/TgWitness/zh/docs/reference/media-analysis/)。 有关客户端访问，请参阅 [MCP](https://phishdestroy.github.io/TgWitness/zh/docs/reference/mcp/)。 --- # Telegram · 全文搜索 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/ 根据词形、精确短语、域名和 @用户名 查找已保存的消息，按最匹配结果优先排序，索引与签名日志绑定。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 根据词形、精确短语、域名和 @用户名 查找已保存的消息，按最匹配结果优先排序，索引与签名日志绑定。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [调查](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/) ![调查](https://phishdestroy.github.io/TgWitness/assets/chapter-investigate.svg) [存档分析](https://phishdestroy.github.io/TgWitness/zh/docs/reference/analysis/) · [本地 OCR 和转录](https://phishdestroy.github.io/TgWitness/zh/docs/reference/media-analysis/) · [维基](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md) **预览。**在**“日志**”中，选择搜索框旁边的**“最佳匹配 · 词形变体**” 选项。结果按 BM25 算法排序，并匹配同一单词的其他形式： *搜索“перевод*”会找到*“переводом*”和*“переводы*”，*搜索“transfer*”会找到*“transfers*”，中文 短语在搜索时不保留空格。**选择“最新优先 · 精确文本**”可保留之前 对整个记录进行的子字符串搜索。 索引是衍生数据。它由签名日志重建而成，本身从未被签名， 也从未被导出。原始记录不会发生任何变化。 **本页内容** - [搜索语法](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/#search-syntax) - [语言](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/#languages) - [索引的位置](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/#where-the-index-lives) - [结果和已签名的日志](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/#results-and-the-signed-journal) - [识别出的文本](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/#recognized-text) - [访问](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/#access) - [咨询存档和 MCP](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/#ask-the-archive-and-mcp) - [依赖项](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/#dependencies) - [基准测试](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/#benchmark) ## 搜索语法 | 撰写 | 查找 | | --- | --- | | `перевод карта` | 同时包含这两个词的记录（形式不限） | | `"переводом на карту"` | 请按此顺序保留确切的短语 | | `бонус OR подарок` | 任一词 | | `перевод -казино` | 不含被排除词的记录 | | `example.com` | 该域名及其子域名，包括隐藏链接和按钮 URL 中的域名 | | `@username`, `t.me/username` | 该账号的提及和链接，以及其发送的消息 | | `#tag` | 话题标签 | | `+79991234567`，一个钱包地址，一个电子邮件地址 | 文本或链接中的相同值 | | `from:@username`, `from:123456` | 来自该发件人的消息 | | `chat:-1001234567890` | 一个聊天窗口；它只能限制您自己的访问权限 | | `id:42` | 消息 42 的已保存版本 | | `since:2026-01-01 until:2026-01-31` | 观察时段；仅含日期而不含时间的日期表示全天 | | `kind:edited` | 仅编辑（`new`, `snapshot`, `edited`, `recovered`) | | `source:ocr`, `source:transcription`, `source:all` | 识别出的文本，可替代消息或与消息并存 | 当存在其他单词时，介词和其他功能词将被忽略。 混入单词中的易混淆字母（例如西里尔字母单词中的拉丁字母 *a*）、全角 及装饰性 Unicode 字母以及不可见字符均将被规范化处理。 ## 语言 系统会根据每条记录中的脚本和字母来检测语言： | 脚本 | 匹配 | | --- | --- | | 西里尔字母 | 使用 [pymorphy3](https://github.com/no-plagiarism/pymorphy3) 处理俄语和乌克兰语词干。若未启用可选的乌克兰语词典，则使用轻量级乌克兰语词干提取器 | | 拉丁文 | 英语 Snowball 词干提取器；忽略音标符号 | | 中文、日语、韩语、泰语、老挝语、高棉语、缅甸语 | 重叠字符对：查找不包含空格的任何短语。中文查询将使用 jieba 拆分为单词 | | 其他脚本 | 精确词句 | 乌克兰语词典（`pymorphy3-dicts-uk`）依据 GPL-3.0 协议发布，因此 默认情况下不会安装。请使用以下命令进行安装 `pip install "tgwitness[uk-dictionary]"`； 索引会自动识别新的分析器并重新构建自身。 ## 索引的位置 | 模式 | 存储 | 用法 | | --- | --- | --- | | 磁盘存储（默认） | `search/fulltext.sqlite3` 在工作区目录中 | 支持大型存档；重启后数据仍可保留 | | 仅限内存中 | 磁盘上不留任何数据；每次启动时都会重新构建 | 磁盘上不保留消息文本的任何衍生副本 | | 关闭 | 不设索引；**按最新内容优先排序 ·** 保留**原文精确表述** | 最低配置 | 主管理员可在**“日志”→“过滤器”→“搜索索引**”中 为每个工作区选择模式。 `TGWITNESS_FULLTEXT=disk|memory|off` 为 未自行选择的 Workspace 设置默认值。切换至“内存”或“关闭”将删除该文件。 索引文件与日志具有相同的保护措施：它位于私有数据 目录中。该文件未加密，也不包含在备份或异地副本中。 新记录会在后台数秒内完成索引；搜索时也会优先索引 短暂的积压记录，因此刚保存的记录也能被检索到。现有日志会在 更新后完成索引，且不会阻塞面板；在此之前，搜索结果涵盖 已索引的记录，日志会显示进度。**重建索引时**将从 第一条记录开始重新进行。 ``` python -m tgwitness index status --data-dir data/live python -m tgwitness index rebuild --data-dir data/live --json ``` `rebuild` 需要停止该面板（否则退出代码为 3）。使用 `--json`， 标准输出仅显示结果；进度信息将输出到标准错误。 ## 结果及签名日志 索引存储其所涵盖的最后一条日志记录的序列号和哈希值， 并在打开日志时将其与日志进行比对。若日志被替换、恢复或编辑， 则会触发索引重建。每次响应都会报告该位置，每次查询结果均 通过序列号从签名日志中读取：索引仅决定显示哪些 记录以及显示顺序，绝不涉及记录内容。聊天权限仅适用于 日志自身的聊天字段，而不适用于索引内容。 ## 识别出的文本 OCR 结果和转录文本保留在其加密的原始文件中。其索引仅存在于 内存中，并在识别任务完成时重建。匹配结果将显示在其 `media.saved` 记录中显示，标注为“机器识别”，并附带引擎、模型及 摘录内容；该内容绝不会以 Telegram 中发送的文本形式呈现。同一索引还用于 **“搜索已识别文本**”功能，该功能仍可匹配纯文本子字符串。 ## 访问 “聊天范围”访问仅查找来自其聊天的记录，包括 其附件中被识别的文本。 `chat:` 以及其他过滤条件仅能进一步缩小该数据集范围。向范围限定访问显示的索引状态 不包含日志总数。仅主管理员可以更改 模式或重建索引。 ## 向存档和 MCP 咨询 当索引构建完成后，**Ask the Archive** 将从该索引中检索数据源：即 所选聊天记录中匹配度最高的条目，且每条已保存的文本仅计数一次。最多发送 24 个数据源；长文本将在匹配位置处截断，并标记为“截断”。 关于近期更改、单条消息的已保存版本以及在 索引仍在构建期间进行的搜索，均使用之前的按时间顺序检索方式。预览 界面会显示所使用的方法。 MCP 客户端可调用 `search_messages` 使用 `ranked=true` ，并使用 `next_offset`。范围限定连接仅接收其所属的聊天内容。 排序分页最多显示前1,000条结果，无论页面大小如何。请缩小查询范围、聊天范围或时间范围以查看更多匹配结果。按最新优先搜索会在选择每页之前，对消息、OCR 结果和转录结果进行排序。 ## 依赖项 | 软件包 | 许可协议 | 为什么 | | --- | --- | --- | | pymorphy3、pymorphy3-dicts-ru、DAWG2-Python | MIT | 俄语和乌克兰语词干；词典在本地加载 | | snowballstemmer | BSD-3-Clause | 英文词干，纯 Python 代码 | | jieba | MIT | 中文查询分词，纯 Python 实现（仅提供源代码分发） | | pymorphy3-dicts-uk（可选） | GPL-3.0 | 完整的乌克兰语词典 | SQLite FTS5 需要 `unicode61` 分词器；该分词器是当前 Python 构建版本中 SQLite 的一部分。若缺少该分词器，最佳匹配搜索将报告其不可用。 ## 基准测试 `python tools/bench_fulltext.py --messages 1000000 --work `生成一个确定性的签名日志，其中包含来自 200 个聊天群组中混合使用俄语、乌克兰语、英语、 中文和日语的消息，以及其中的链接和标识符；构建索引 并测量典型搜索的耗时（50 条结果，7 次运行的中位数）。 测试环境：Windows 11、Intel Core i9-13900K、128 GB 内存、Python 3.12.10、SQLite 3.49.1，数据存储于 exFAT 分区，分析器 `fulltext-v1+pymorphy3-ru+light-uk+snowball-en`: | 度量 | 结果 | | --- | --- | | 签名日志 | 1,000,000 条消息，1.50 GiB，19 分钟内写入 | | 基于日志构建索引 | 71 秒，约每秒 14,141 条消息 | | 索引文件 | 58 MiB，占日志总量的 3.8% | | 在新记录生成后立即进行搜索 | 中位数 8 毫秒，P95 值 9 毫秒 | | 之前的子字符串搜索，同一日志 | `перевод` 3.2 秒， `银行转账` 2.6 秒， `verify-account.example` 2.6 秒 | | 搜索 | 匹配记录 | 最佳匹配，中位数 | p95 | 最新优先，中位数排序 | | --- | --- | --- | --- | --- | | 常用词及词形： `перевод` | 134,403 | 82 毫秒 | 85 毫秒 | 7 毫秒 | | 两个词： `оплата карта` | 28,996 | 43 毫秒 | 43 毫秒 | 14 毫秒 | | 生僻词： `розыгрыш подарок` | 28,881 | 42 毫秒 | 47 毫秒 | 13 毫秒 | | 精确短语： `"переказ коштів на картку"` | 不计入 | 35 毫秒 | 36 毫秒 | 6 毫秒 | | 域名及子域名： `verify-account.example` | 12,435 | 17 毫秒 | 17 毫秒 | 3 毫秒 | | @用户名： `@support_desk_bot` | 10,331 | 15 毫秒 | 16 毫秒 | 3 毫秒 | | 中文无空格： `银行转账` | 17,691 | 23 毫秒 | 24 毫秒 | 3 毫秒 | | 日语： `リンク` | 16,603 | 23 毫秒 | 25 毫秒 | 3 毫秒 | | 英文词干： `withdrawal` | 27,775 | 26 毫秒 | 26 毫秒 | 2 毫秒 | | 或与排除： `бонус OR подарок -казино` | 268,034 | 190 毫秒 | 193 毫秒 | 19 毫秒 | | 聊天过滤器： `chat:-1000000000007 перевод` | 652 | 9 毫秒 | 9 毫秒 | 6 毫秒 | | 时间范围筛选器： `since:2026-01-01 until:2026-01-31 выплата` | 115,732 | 155 毫秒 | 156 毫秒 | 81 毫秒 | 系统会按排名顺序逐一检查候选结果中是否存在完全匹配的短语，直到页面 填满为止，因此该项的总数不计入统计。耗时随匹配记录数量的增加而增长； 缩小聊天范围或时间范围可加快广泛搜索的速度。合成语料库中 词汇量有限，因此常见词匹配到的记录数量远多于真实聊天记录。 --- # Telegram · 只读 MCP Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/mcp/ 将 MCP 客户端连接到选定的工作区和聊天群组，并授予具有时效性且可撤销的访问权限。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 将 MCP 客户端连接到选定的工作区和聊天群组，并授予具有时效性且可撤销的访问权限。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [存档集成](https://phishdestroy.github.io/TgWitness/zh/docs/reference/cli/) ![存档集成](https://phishdestroy.github.io/TgWitness/assets/chapter-integrations.svg) 将分析客户端连接到选定的工作区和聊天群组。TgWitness **在面板进程的 `/mcp` 端点**提供 **可流式传输的 HTTP** 服务。每个连接都有其专属的 令牌、有效期和允许使用的工具。MCP 无法发送 Telegram 消息、更改 设置或修改签名日志。这些连接同样适用于 [命令行](https://phishdestroy.github.io/TgWitness/zh/docs/reference/cli/)。 [工作流指南](https://phishdestroy.github.io/TgWitness/docs/archive/) · [维基](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md) **本页内容** - [安装与检查](https://phishdestroy.github.io/TgWitness/zh/docs/reference/mcp/#install-and-check) - [建立连接](https://phishdestroy.github.io/TgWitness/zh/docs/reference/mcp/#issue-a-connection) - [连接您的客户端](https://phishdestroy.github.io/TgWitness/zh/docs/reference/mcp/#connect-your-client) - [Cloudflare Tunnel](https://phishdestroy.github.io/TgWitness/zh/docs/reference/mcp/#cloudflare-tunnel) - [工具与边界](https://phishdestroy.github.io/TgWitness/zh/docs/reference/mcp/#tools-and-boundaries) ## 安装与检查 使用运行面板的 Python 环境。从源码检出目录执行： ``` # Windows PowerShell & .\.venv\Scripts\python.exe -m pip install -c deploy/constraints-mcp.txt -e '.[mcp]' & .\.venv\Scripts\python.exe start.py --check ``` ``` # Linux / macOS .venv/bin/python -m pip install -c deploy/constraints-mcp.txt -e '.[mcp]' .venv/bin/python start.py --check ``` 安装后，使用常用的数据目录和启动参数重启面板。就绪检查应包含 `[PASS] mcp: streamable-http available`。**Integrations → MCP** 会显示运行时状态以及使用该服务器实际 Python 可执行文件的安装命令。**Re-check** 可在不重新加载页面的情况下刷新此状态；它不会安装软件包或重启服务器。 该 MCP 扩展程序使用官方的[MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)。`deploy/constraints-mcp.txt` 锁定了经过测试的 SDK 及其依赖项。 ## 签发连接 1. 输入标签并选择客户端可读取的工作区和聊天。 2. 逐个选择工具或使用预设。仅提供已实现的工具。 3. 选择 1、7、30 或 90 天，或在 1 分钟至 90 天之间自定义过期时间。 4. 点击 **Create connection**。令牌会在客户端配置旁显示一次。 5. 复制令牌和配置，然后运行 **Check connection**。它会初始化 MCP 并列出允许使用的工具；**不会读取任何消息**。结果将显示协议版本、工具名称、数量和耗时。 6. 保存凭据后点击 **Done**。轮询会保留表单和单次显示的卡片。锁定面板会清除已显示的机密信息。 列表会显示最近使用情况、上次使用的工具、地址以及过去一分钟内的请求数。**Revoke** 会终止访问权限。**Rotate token** 会吊销旧凭据，并签发具有相同范围、工具和过期时间的替代令牌；请单次复制该替代令牌。面板登录令牌和 Telegram 凭据不能用作 MCP 令牌。 ## 连接您的客户端 在面板中选择客户端并复制生成的配置。配置使用机密引用或显式占位符；令牌需单独复制。 | 客户端 | 配置 | 连接 | | --- | --- | --- | | Claude 代码 | `.mcp.json` | HTTP，`type: "http"`，Bearer 请求头 | | Claude Desktop | `claude_desktop_config.json` | 本地 stdio 桥接 | | Cursor | `.cursor/mcp.json` | 带环境变量请求头的 HTTP | | VS Code 本地版 | `.vscode/mcp.json` | 带密码 `promptString` 输入的 HTTP | | Windsurf | `mcp_config.json` | 带 Bearer 请求头占位符的 HTTP | | 其他客户端 | URL 和 Authorization 请求头 | 可流式传输的 HTTP | TgWitness 使用 Bearer 令牌，不支持 OAuth 发现。对于远程连接器需要 OAuth 的客户端，请使用本地 stdio 桥接。对于 VS Code，输入变量适用于 **Local** 环境，不会转发到 Copilot 会话。配置参考：[Claude Code](https://code.claude.com/docs/en/mcp)、[Cursor](https://prod.cursor.com/docs/mcp)、[VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)。 本地桥接的标准入口点为： ``` python -m tgwitness.mcp_server --url https://your-panel.example/mcp ``` 使用客户端本地已安装 MCP 扩展的 Python。在其受保护的环境中设置 `TGWITNESS_MCP_TOKEN`。切勿将凭据放入命令参数和 URL 中。`tgwitness-mcp` 是相同的入口点。旧的 `tgwitness.mcp_bridge` 模块和 `TGWITNESS_ARCHIVE_TOKEN` 名称仍作为兼容路径保留，但会发出警告；新配置请使用 `mcp_server` 和 `TGWITNESS_MCP_TOKEN`。 ## Cloudflare Tunnel 转发面板的 `/mcp` 路由并保留 Bearer 请求头。以管理员身份打开 MCP 设置会为本次运行注册面板的当前源（Origin）。若要获得重启后立即可用的稳定地址，请在启动面板前使用面板的 HTTPS 源配置 `TGWITNESS_PUBLIC_URL`。任意 Host 和转发请求头不会注册受信任的地址。Host 和 Origin 检查会拒绝无关的浏览器源。响应使用 `Cache-Control: no-store`；授权值绝不会被记录到日志中。 `*.trycloudflare.com` 地址是临时的。当隧道重启更改主机名时，请更新已配置的公共 URL 以及每个客户端的 MCP URL。对于已保存的客户端配置，请使用稳定的主机名。 ## 工具与边界 | 工具 | 读取内容 | | --- | --- | | `list_workspaces` | 已授权的工作区 | | `list_chats` | 已授权的聊天 | | `search_messages` | 所选时间段内保存的消息正文； `ranked=true` 支持[全文搜索](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/)（包含词形变体，优先显示最匹配结果， `next_offset` 分页） | | `get_message_versions` | 已捕获的版本和删除观测记录 | | `get_message_context` | 附近已捕获的消息 ID | | `get_journal_event` | 单条经过脱敏处理的记录及其来源引用 | | `get_capture_status` | 采集状态、允许记录的覆盖范围以及 `gap_summary`：按频道或超级群以及全账户序列统计的未观察到的消息编号（[详情](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#missing-message-numbers-gap_summary)）；选择一个聊天室即可查看其列出的缺失记录 | | `get_activity_stats` | 按 UTC 小时和星期几分类的消息、高峰日、编辑与删除比例、发件人、域名以及 `@handles`，并包含覆盖范围（[详情](https://phishdestroy.github.io/TgWitness/zh/docs/reference/cli/#activity-statistics)） | | `get_messages_by_date` | 在指定的 IANA 时区中保存一个日历日的消息（`Europe/Kyiv`, `UTC`)，以Telegram报告的时间为准； `from_utc` 并 `until_utc` 注明计算出的日期（包含夏令时） | | `get_pinned_messages` | 最新聊天状态快照中被置顶的消息及其保存版本，以及实时观察到的置顶和取消置顶通知 | | `get_chat_stats` | 提供单个聊天或范围内所有聊天的已保存记录数量、首次和最后一次观察记录，以及 `gap_summary`；请在进行大规模读取前使用该功能 | | `get_topics` | 来自“已保存主题”服务消息的论坛主题：标题历史、已关闭或已隐藏、已保存消息数量 | | `get_media` | 作为缩放后的 JPEG 预览图（最大 36 KB）保存的图像，将作为图像与 SHA-256 值及 `media.saved` 记录；该文件会首先与其记录的哈希值进行比对，其他文件仅返回元数据 | | `export_messages` | 仅限命令行，默认未选中：流将记录的观察结果保存为 JSON Lines 格式（[详情](https://phishdestroy.github.io/TgWitness/zh/docs/reference/cli/#export)）；不通过 MCP 提供 | 每个工具均为只读模式（`readOnlyHint`）并声明了一个输出模式；超出声明范围的字段将按原样返回。 `tools/list` 仅返回授予该连接权限的工具。对其他 工具的调用将被拒绝。本版本不提供组上下文、事件、术语和回复链工具； 因其独立的上下文包后端未包含在内。 每次读取都会检查令牌、工具以及工作区/聊天范围，包括在数据库操作完成之后。限制为每分钟 60 次请求、每页 50 条记录、每个结果 64 KiB 以及 8 秒的归档截止时间。超时的 MCP 调用会返回工具错误，要求缩小时间段或降低限制。 消息结果包含 `untrusted_content: true`、工作区/聊天/消息 ID、事件序列、已保存的哈希值以及面板链接。原始 Telegram 对象、访问哈希、会话和密钥均被省略。文本截断会予以标记。编辑、删除通知和 `missing_on_recheck` 是不同的观测记录。缺失记录并不能证明某个事件从未发生。 请将已捕获消息中的指令视为证据，切勿将其作为客户端指令。只读访问权限可防止归档被更改；但客户端仍可保留允许其读取的内容。哈希值用于标识已保存的记录并支持完整性检查；它们不能证明 Telegram 作者身份或捕获的完整性。 --- # Telegram · 命令行 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/cli/ 支持通过脚本和代理进行搜索、阅读上下文、统计活动以及导出已保存的消息，提供 --json 输出格式、稳定的退出代码以及作用域限定的只读令牌。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 支持通过脚本和代理进行搜索、阅读上下文、统计活动以及导出已保存的消息，提供 --json 输出格式、稳定的退出代码以及作用域限定的只读令牌。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) ![存档集成](https://phishdestroy.github.io/TgWitness/assets/chapter-integrations.svg) [只读 MCP](https://phishdestroy.github.io/TgWitness/zh/docs/reference/mcp/) · [全文搜索](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/) · [维基](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md) **预览。** `tgwitness search`, `context`, `messages`, `stats` 以及 `export` 读取 已保存的观察记录，供脚本和 AI 代理使用。它们无法向 Telegram 发送任何内容、更改设置或修改签名日志。 其中 `--json`，标准输出（stdout）将输出且仅输出一个 JSON 文档（`export` 写入 JSON Lines）。 进度、提示和错误信息输出到 stderr。退出代码保持稳定： | 代码 | 含义 | | --- | --- | | `0` | 成功，包括空结果 | | `1` | 失败：无法访问面板、数据无法读取、导出中断 | | `2` | 使用错误或请求无效：日期格式错误、未知选项、搜索索引不匹配 | | `3` | 当前不可用：工作区已在运行中的面板中打开，或者面板提示稍后重试（速率限制、超时） | | `4` | 访问被拒绝：令牌缺失、过期或已被撤销；聊天超出其范围；或该工具不允许此操作 | ## 两种阅读方式 **通过控制面板（`--url`）。**该命令使用与 MCP 相同的范围限定存档 API。**在“集成”→“MCP”中**建立连接：选择工作区和聊天群组、 工具及有效期，然后复制一次令牌。该连接为只读模式，仅限于 所选聊天群组，每分钟请求次数限制为 60 次，且可随时撤销或 轮换。控制面板登录令牌和 Telegram 凭据在此处无效。 ``` export TGWITNESS_URL=https://panel.example.org # default http://127.0.0.1:8787 export TGWITNESS_MCP_TOKEN=tgw_mcp_... # or --token-file path tgwitness search 'перевод карта' --json ``` 远程面板需要 HTTPS；仅在以下情况下才接受明文 HTTP： `127.0.0.1`, `localhost` 和 `::1`。代理环境变量将被忽略，且不接受重定向， 因此令牌仅会发送到您指定的地址。 **直接从已停止的工作区（`--data-dir`）**读取**。**以 完全本地访问权限读取数据目录，无需令牌。请在数据目录的副本上使用，或在 数据收集已停止时使用。签名记录绝不会被更改；与控制面板类似，打开 工作区可能会使其派生索引更新至最新状态。当控制面板已打开该工作区时，该命令将以 代码 `3`；请改通过面板进行读取。若未指定 `--data-dir`, `TGWITNESS_DATA`, `./data/live` 或未指定，则使用运行该命令的安装环境的数据目录。 `--workspace ID` 选择工作区（默认 `default`). `tgwitness messages --workspaces` 列出您可以阅读的工作区。 ## 命令 | 命令 | 结果 | | --- | --- | | `tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N]` | 按最匹配结果优先排序，包括词形变体、加引号的精确短语、域名以及 `@username` （[语法](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/#search-syntax)） | | `tgwitness search QUERY --exact [--before SEQ]` | 精确文本，按时间倒序排列（最新内容在前），不包含索引 | | `tgwitness context CHAT_ID MESSAGE_ID` | 前后各十条消息 ID 范围内的已保存消息 | | `tgwitness messages` | 可阅读的聊天记录 | | `tgwitness messages CHAT_ID [--since] [--until] [--before SEQ]` | 聊天记录中的已保存消息，按时间倒序排列（最新消息在前） | | `tgwitness messages CHAT_ID --message ID` | 每条消息的每个保存版本及删除记录 | | `tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N]` | 活动统计数据如下： | | `tgwitness export [--chat ID] [--since] [--until] [--output FILE]` | 将观察记录按日志顺序以 JSON Lines 格式保存 | 日期格式为 `2026-10-01` （UTC 午夜）或带时区的 ISO 时间， `2026-10-01T09:00+03:00`。关于 `search`, `messages` 和 `export` ，它们表示 观察时间。每页最多显示50条记录：请遵循 `next_offset` (`--offset`)进行 排序搜索， `next_before` (`--before`) 其他内容。 排序搜索结果上限为 1,000 条。最后一页的显示结果可能少于 `--limit`；若存在更多匹配的观察结果，请缩小查询范围、聊天范围或时间范围。 每条消息结果都包含 `untrusted_content: true`工作区、聊天和 消息 ID、日志序列号、保存记录的哈希值以及面板链接。编辑、 删除通知和 `missing_on_recheck` 属于独立的记录。某条记录的缺失 并不证明该事件从未发生。 ### 活动统计 `stats` 统计特定聊天、特定发送者或范围内所有聊天的已保存观察记录数量： - 按 UTC 小时和星期几（以周一为首）分类的消息；最繁忙的小时和日期； - 已编辑、已删除和 `missing_on_recheck` 分享； - 发件人及其消息数量，以及第一条和最后一条消息的时间； - 出现频率最高的域名以及 `@handles`，在所有 已保存版本中，每条消息仅计数一次； - 涵盖范围： `coverage.gap` 记录内容以及（若需访问整个工作区） 未检测到收集器心跳的时段（`collector_liveness`). 该时间段基于**Telegram 报告的消息时间**。小时和星期几的计数可 帮助估算发件人的时区，但不能确定其确切时区。相关数据是根据 请求从日志中计算得出的，不会被存储。当您的访问范围涵盖整个工作区时，每个结果都会标明其 所涵盖的日志头。通过 控制面板浏览五秒后，或 `--timeout` 本地等待秒数（默认30）后，读取操作将停止；此时 `complete` 返回 false，且 `partial` 指代第一个未被读取的记录。在此情况下，仅统计 最新记录。 ### 导出 `export` 每条保存的观察记录（新消息、快照、 编辑、恢复的消息、删除通知、 `missing_on_recheck` 及已保存的媒体 记录）生成一个 JSON 对象，并按日志顺序排列。每行与其他结果具有相同的字段，包含 完整文本。若启用 `--output`，文件将以 `.partial` 名称下写入， 仅在面板完成记录后才重命名；若导出过程中断，则不生成 文件，并以代码 `1`. `--output` 绝不会覆盖现有文件。使用 `--output` 和 `--json`，标准输出将显示摘要：记录数、最后的日志 序列号，以及（对于整个工作区访问）日志头。 通过控制面板进行导出需要连接到允许**“导出消息” （仅限命令行）**的服务器；该选项默认未勾选。此文件仅为工作副本，并非证据：如需可验证的 移交，请使用**“导出**”中的签名导出文件，该文件 `python -m tgwitness.verify`会进行验证。 该面板在输出每条记录（包括完成 记录）之前都会重新检查访问权限。被撤销或过期的访问权限会导致导出不完整。延迟页面读取 与其他查询共享归档工作线程的限制，且具有有限的等待时间。 ## 代理技能 [`.agents/skills/tgwitness-cli/SKILL.md`](https://github.com/phishdestroy/TgWitness/blob/main/.agents/skills/tgwitness-cli/SKILL.md) 向特工说明如何使用这些命令、如何引用记录以及如何处理 捕获的文本。从 `.agents/skills` 需从代码库检出 该文件。对于 Claude Code，请复制 `tgwitness-cli` 文件夹复制到 `.claude/skills/` 项目中的 或 `~/.claude/skills/`. ## MCP 和命令行 两者均使用相同的连接、范围检查和限制。MCP 的结果限制为 一个 64 KiB 的页面，因此 MCP 不提供批量导出功能；命令行会以流式传输的方式输出数据。 `get_activity_stats` 两项功能均可使用。 --- # Telegram · 本地 OCR 和转录 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/media-analysis/ 通过本地工作进程识别捕获的图像和音频；将生成的文本与源文件保持关联。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 通过本地工作进程识别捕获的图像和音频；将生成的文本与源文件保持关联。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [调查](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/) ![调查](https://phishdestroy.github.io/TgWitness/assets/chapter-investigate.svg) [工作流指南](https://phishdestroy.github.io/TgWitness/docs/archive/) · [维基](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md) 打开`media.saved`日志记录，选择**“识别附件**”，然后在**“查询存档**”下选择 OCR或转录。处理过程为手动且在本地进行。 不支持云端媒体模式或自动上传。原始附件字节和 `media_sha256`保持不变；识别出的文本会被明确标记为机器 识别结果，并单独存储，同时包含源文件哈希值、引擎/模型版本、 语言、参数及完成时间。转录文本保留返回的时间戳。 可通过**“搜索已识别文本**”功能及“OCR/转录” 过滤器搜索这些结果，或选择已识别文本作为**日志**最佳匹配搜索的来源。 这两种方式均通过[内存索引](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/#recognized-text)匹配词形。这 是一种独立的衍生数据搜索；它不会在后台将机器识别结果 转换为原始 Telegram 文本，也不会将其添加到已签名的事件中。 ## 配置可选的工作进程 第 1 版需要配备本地 Docker 守护进程的 Linux 主机。Windows 系统 可在配备独立本地守护进程的 Linux 虚拟机/WSL 环境中运行 TgWitness。 该面板绝不会自行解码任何不可信的附件。 ``` docker build -f deploy/media-worker/Dockerfile -t tgwitness-media:local . export TGWITNESS_MEDIA_IMAGE=tgwitness-media:local ``` 在 TgWitness 服务环境中设置这些变量并重启服务。 守护进程套接字默认值为 `/var/run/docker.sock`；无 root 权限的部署可设置为 `TGWITNESS_DOCKER_SOCKET`。工作进程会明确使用该 Unix 套接字， 而非远程 Docker 上下文。请勿向控制面板用户暴露 Docker API，也请勿将 其套接字挂载到识别容器内。 若需进行转录，请单独安装一个与 CTranslate2 兼容的 Whisper 模型， 然后将 `TGWITNESS_WHISPER_MODEL_DIR` 设置为其目录。工作节点将通过 `local_files_only=True` 加载该模型；所选模型和输入数据将以只读方式挂载。 请参阅引擎的[模型加载文档](https://github.com/SYSTRAN/faster-whisper)。 随附的 OCR 镜像包含英语和俄语的训练数据。如有需要，可将其他 语言构建到您的镜像中；语言代码遵循 [Tesseract 的 CLI 规范](https://tesseract-ocr.github.io/tessdoc/Command-Line-Usage.html)。 处理过程中不会加载任何模型。构建/下载安装程序可能会使用网络； 每个实际的识别容器均已禁用网络功能。请在启用网络功能前安装镜像； 运行时使用 `--pull=never`。 ## 限制与恢复 该容器以无特权用户身份运行，具有只读根目录、已撤销 权限、`no-new-privileges` 配置、1 个 CPU、2 GiB 内存、PID 限制以及受限的 临时文件系统。仅挂载所选文件的经过验证的副本以及可选的 模型目录。 收集器的数据库、存储库和会话均 未挂载。[Docker 运行时](https://docs.docker.com/reference/cli/docker/container/run/) 标志强制执行这些限制；这仍属于容器边界，而非硬件安全区。 文件大小上限为 50 MiB，图像分辨率上限为 2000 万像素，音频时长上限为 30 分钟（ 且时长已知），处理时长上限为 5 分钟。每次仅有一个工作进程运行， 每个工作区最多可有 20 个排队/正在运行的任务，并保留 100 个任务。 “取消”将停止容器；“重试”将创建一个与先前尝试相关联的新任务。 中断的任务在重启后会被标记。当模型 无法适应配置的限制时，处理可能会失败；若未进行隔离，系统不会静默运行。 --- # Telegram · 外发 webhook Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/webhooks/ 将带 HMAC 签名的指定范围事件发送至 HTTPS 接收端，支持重试并提供投递状态。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 将带 HMAC 签名的指定范围事件发送至 HTTPS 接收端，支持重试并提供投递状态。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [存档集成](https://phishdestroy.github.io/TgWitness/zh/docs/reference/cli/) ![存档集成](https://phishdestroy.github.io/TgWitness/assets/chapter-integrations.svg) [工作流指南](https://phishdestroy.github.io/TgWitness/docs/archive/) · [维基](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md) 在所选工作区中打开**“集成”→“外发 webhook”**。 添加一个 HTTPS 接收器，选择收集器/媒体/导出事件，并可选地为 新观察项和变更选择聊天。消息正文默认处于关闭状态。启用摘要 功能后，消息变更事件最多增加 1,000 个字符；Telegram 的原始字段和 凭据绝不会被发送。 将 HMAC 密钥复制一次到接收器的受保护配置中。该密钥 存储在 TgWitness 的保险库中并经过加密，无法通过控制面板检索。删除 并重新创建目标以实现密钥轮换。**向合成**测试队列**发送**一条 不含聊天内容的测试消息；刷新投递状态以查看结果。 该功能在 Apprise 的基础上扩展了现有的通知循环。它利用 工作区的外部路由和现有的私有目标限制。 后续不会进行直接的备用处理或重定向。URL 不得包含凭据、 查询字符串或片段；私有地址需要服务器级别的网络 授权，而非面板用户可绕过的设置。 ## 有效载荷与签名 模式：[`tgwitness.webhook/1`](https://github.com/phishdestroy/TgWitness/blob/main/integrations/webhook.schema.json)。每个有效载荷 包含 `event_id`、`timestamp`、`workspace`、`type`、`synthetic` 以及计数器。 基于日志的事件包含其序列号和哈希值。完整导出完成和 合成测试属于交付事件，不包含虚构的签名日志引用。 Telegram 删除通知和 `missing_on_recheck` 仍为独立类型。 `X-TgWitness-Signature` 标头应为 `t=UNIX_SECONDS,v1=HEX_HMAC_SHA256`。 使用显示的密钥（作为 UTF-8 字节）对精确字节序列 `timestamp + "." + raw_request_body` 计算 HMAC， 并在解析或处理正文之前以常数时间比较签名。若时间戳与 本地时间相差超过五分钟，则予以拒绝。每次投递尝试时，时间戳都会刷新。 在持久化存储中使用 `event_id` 作为幂等键，并在产生副作用之前设置原子性唯一 约束。仅凭有效的签名并不能防止 最近的请求被重放。请至少在整个 重试窗口内保留已处理的 ID；如果接收方可以重新处理存储的事件，则应更长时间地保留这些 ID。 ## 重试 消息发送会在 HTTP 请求之前被持久化地排入队列。该系统采用“至少一次” 语义：若确认消息丢失或系统重启，可能会再次发送具有 相同 ID 的事件。系统会进行八次尝试，采用指数退避机制，起始间隔为 15 秒，上限为一小时。成功发送需返回 2xx 状态码。 已耗尽的任务 会留下可见的错误信息；重试结束后，无法保证能成功交付。 队列可容纳 1,000 次发送任务。当队列已满时，日志事件的扫描将暂停， 并在有可用空间后恢复。 无法排入队列的完整导出任务 会触发可见的队列错误。每次通知处理 最多尝试发送五次，并保留最近 100 条尝试记录。删除一个目标 也会一并删除其待发送的任务。 ## n8n 示例 导入[示例工作流](https://github.com/phishdestroy/TgWitness/blob/main/integrations/n8n-tgwitness.json)。该工作流处于非活动状态， 且不包含任何机密信息或下游操作。 在 n8n 工作进程环境中设置 `TGWITNESS_WEBHOOK_SECRET`， 允许该环境访问，并为 Code 节点启用 `crypto` 内置函数。该示例使用 Webhook 节点的 raw-body 选项， 检查签名/新鲜度，并确认已验证的事件。这与 该节点的[文档中所述的实现](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Webhook/Webhook.node.ts)方式一致。 在添加 SIEM 写入或通知之前，请先添加以 `event_id` 为键值的持久化幂等存储。 根据您选择发送的数据，限制 n8n 工作流的编辑及执行日志的保留时长。 TgWitness 不添加任何入站命令。 --- # Telegram · 公开展示 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/showcase/ 通过有效期有限且可撤销的链接，发布所选公共频道的已保存消息和已签名的快照。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 通过有效期有限且可撤销的链接，发布所选公共频道的已保存消息和已签名的快照。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [部署与恢复](https://phishdestroy.github.io/TgWitness/zh/docs/reference/deployment/) ![部署与恢复](https://phishdestroy.github.io/TgWitness/assets/chapter-operate.svg) **“访问 → 公共展示**”功能利用现有的 访问令牌系统创建一个独立的只读页面。该功能读取安装实例中保存的观察记录，但不会 为访客启动采集器、登录 Telegram 或获取频道。 ## 发布页面 1. 为每个您希望展示的公共频道保存一个源配置文件。该频道必须 在其最新保存的配置文件中拥有一个公共用户名；群组和私聊 不符合条件。 2. 开放**访问 → 公共展示区**（或 `/showcase-manage.html`）作为管理员。 3. 从最多 16 个工作区中选择频道，输入公共页面标题，并 选择链接有效期为 1 天、7 天或 30 天。工作区内部标签不会 对外发布。最多可包含 64 个频道。 4. 审核选定频道的文本以供发布，然后点击**“预览选定 记录”**。预览使用与访客页面相同的服务器端投影。 5. 点击“**创建展示链接**”。在链接可见时将其复制。在 另一个浏览器中打开该链接，在分发前预览收件人的页面。 该链接的 URL 片段中包含一个访问令牌。页面在发起 API 请求前会移除该 片段，并将其替换为浏览器会话。 任何持有该链接的人均可打开所选内容，直至链接过期或被撤销。 新链接允许 100 个并发会话，每个会话最长持续一小时。现有的 访问控制还可以通过 授权 API 实施地址限制和登录次数限制。普通审阅者访问属于另一种模式，仍包含 最初允许的消息和文件。 ## 访客所见内容 | 可见 | 保持私密 | | --- | --- | | 精选的公共频道名称、用户名及个人资料观察日期 | 账户身份、内部工作区标签和未选中的来源 | | 捕获的文本及每次保存的编辑内容 | 结构化的发件人 ID、姓名、用户名、电话号码和个人资料信息 | | 删除记录（如有）及先前保存的文本 | 附件、头像、缩略图、文件名和原始有效载荷 | | 标记用于指示作者/个人资料或附件已被记录 | 转发和回复元数据、网络路由、IP 地址及凭据 | | 选定频道的事件计数、当前采集开关、心跳和检查点间隔 | 数据收集控制功能和常规证据导出 API | | 签名指纹、日志检查点和一致性证明 | 签名密钥和 Telegram 会话 | **公开消息的文本不会自动匿名化。**消息中包含的姓名、提及、电话 号码或链接仍将保留在文本中。 `Redacted`适用于结构化的作者/个人资料字段。发布前请检查实际选中的内容， 包括保留的编辑和删除内容。 “符合条件”反映的是**最新保存的源配置文件**，而非实时查询 Telegram 的结果。 如果后续的配置文件中不再包含该公共频道的用户名，新的请求 将排除该频道。当公共可见性发生变化时，请刷新源配置文件。 读者可能已经保存了之前收到的内容。 原始的签名记录保持不变。显示的投影会单独进行签名， 并包含指向原始记录的哈希值。投影 签名用于验证所显示内容的真实性；它并非原始事件 对经过编辑的字节所做的签名。 ## 检查签名和连续性 展开**“指纹与已签名检查点**”，并下载快照。页面 刷新后，下载内容将包含之前的浏览器快照以及其日志边界之间的 默克尔一致性证明。当页面可见且显示其第一页观察结果时，系统会每 一分钟自动刷新一次。 安装 TgWitness 后，请在离线状态下验证下载的文件： ``` python -m tgwitness.showcase_verify showcase.json --fingerprint TRUSTED_COLLECTOR_SHA256 ``` 指纹必须来自一个单独的可信参考源。若要与 您自己保留的快照进行比对，请使用 `--previous earlier.json`；这将覆盖 下载文件中携带的先前快照。当前证明必须从 该保留的边界开始。经过身份验证的客户端可使用 `GET /api/showcase/{workspace_id}?challenge=<32-hex-random>&from_count=`。 较短的日志会返回 HTTP 409 状态码，而非静默重置边界。 已签名的检查点会提交至**整个收集器**日志，包括其 记录计数和不透明的头部哈希值。显示的消息计数仅适用于 选定的公共频道。该页面绝不会列出其他日志的内容。 这些是事件计数，而非唯一消息计数。设置描述的是 当前配置，而非每个早期的记录间隔。 签名和一致性验证可检测相对于保留 边界所发生的变更。它不会独立重新计算已签名的计数器、认证 Telegram 来源、证明捕获过程未中断，也不会替代独立见证人。 如需进行此类审查，请使用[证据验证器](https://github.com/phishdestroy/TgWitness/blob/main/docs/TRUST.md)、 [独立见证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/)人和[经过规模测试的记录](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/)。 合成安装环境会明确标注为“合成”。 ## 撤销或托管该页面 在展示管理器或现有的**“访问**”部分中使用**“撤销”功能**，可关闭 链接并终止其所有会话。当请求检测到访问已结束时， 访客将清除显示的记录。每次 请求都会检查有效期和权限。展示权限无法直接转换为普通面板访问权限； 请创建新的权限以切换模式。 通过安装环境现有的 HTTPS 地址提供页面服务。发布 链接不会打开新端口、创建隧道或更改 DNS。HTML 和 API 仍保留在用户的安装环境中。展示页面的访问者无法通过此访问权限使用常规的 消息、个人资料、媒体、导出或管理 API。 --- # Telegram · 证据的运作原理 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/how-it-works/ 通过验证者实际使用的精确公式，详细解释了哈希链、签名、检查点和见证人等概念。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 通过验证者实际使用的精确公式，详细解释了哈希链、签名、检查点和见证人等概念。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [证据与验证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/) ![证据与验证](https://phishdestroy.github.io/TgWitness/assets/chapter-evidence.svg) TgWitness 保存收集账户所观察到的内容，将这些观察结果 整合到一份经过签名的日志中，并允许其他人使用可信 密钥和先前保留的检查点来验证导出内容。 [本地文档网站](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/PUBLISHING.md#preview-the-website-locally)新增了 位于 `/docs/concepts/` 的交互式示例、位于 `/docs/witness/` 的检查点决策探索器，以及关于[“案件看板](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-board/)”、 [报告设计](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-reports/)和[移交摘录](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#handover-extract)的操作指南。 所有示例消息、 计数和延迟均为虚构。链式沙盒中的哈希值是在浏览器中使用 SHA-256 算法计算得出的。没有任何数据会被发送至 Telegram。 **本页内容** - [消息会发生变化；观察结果会不断积累](https://phishdestroy.github.io/TgWitness/zh/docs/reference/how-it-works/#a-message-changes-observations-accumulate) - [哈希值的覆盖范围](https://phishdestroy.github.io/TgWitness/zh/docs/reference/how-it-works/#what-a-hash-covers) - [早期检查点新增的内容](https://phishdestroy.github.io/TgWitness/zh/docs/reference/how-it-works/#what-an-earlier-checkpoint-adds) - [见证的归属](https://phishdestroy.github.io/TgWitness/zh/docs/reference/how-it-works/#where-a-witness-belongs) - [针对已知操作进行测试](https://phishdestroy.github.io/TgWitness/zh/docs/reference/how-it-works/#test-delivery-against-known-actions) - [选择工作流](https://phishdestroy.github.io/TgWitness/zh/docs/reference/how-it-works/#pick-a-workflow) ## 消息在变；观察在积累 序列图 · Telegram → 收集器: 新消息：10:00 见面; 收集器 → 签名日志: 追加消息.new; Telegram → 收集器: 编辑：11:00 见面; 收集器 → 签名日志: 追加消息.edited; Telegram → 收集器: 删除通知; 收集器 → 签名日志: 追加消息.已删除; 关于签名日志的说明: 原始内容、编辑内容及删除记录均予以保留 · Telegram · 收集器 · 签名日志 · 新消息：10:00 见面 · 追加消息.new · 编辑：11:00 见面 · 追加消息.edited · 删除通知 · 追加消息.已删除 · 原始内容、编辑内容及删除记录均予以保留 **图表转为文本** 1. Telegram → 收集器: 新消息：10:00 见面 2. 收集器 → 签名日志: 追加消息.new 3. Telegram → 收集器: 编辑：11:00 见面 4. 收集器 → 签名日志: 追加消息.edited 5. Telegram → 收集器: 删除通知 6. 收集器 → 签名日志: 追加消息.已删除 7. 关于签名日志的说明: 原始内容、编辑内容及删除记录均予以保留 此简化流程假设 Telegram 已成功发送每条更新，且所选 账户能够查看该更新。操作事件也会被记录在日志中。删除通知 不会提供删除者信息或确切的删除时间。重复发送的 消息被视为独立的记录；日志中不会进行全局重复项过滤。 ## 哈希值涵盖的内容 ![观察、编码、哈希和签名：每个新事件都包含前一个事件的哈希值。](https://phishdestroy.github.io/TgWitness/assets/evidence-chain-animated.svg) 从内到外解读该公式：**C** 将九个字段转换为精确的字节； **SHA-256** 生成其摘要；**hex** 表示该摘要的存储格式。前一个 哈希值已包含在事件中。**unhex** 将存储的哈希值还原为 32 字节，供 Ed25519 进行签名。 [静态链图](https://github.com/phishdestroy/TgWitness/blob/main/docs/assets/presentation/evidence-chain-static.svg) 设 C(ei) 为九个事件字段的标准 UTF-8 JSON 格式。第一个 `previous_hash` 由 64 个零字符组成。后续的每条记录都包含前一条 记录的十六进制哈希值： hi = hex(SHA256(C(ei))) σi = Ed25519.Sign(sk,unhex(hi)) 该签名覆盖了 32 个原始摘要字节。哈希输入包含 `seq`、`observed_at`、`source_at`、`kind`、`chat_id`、`message_id`、`actor_id`、 `payload` 和 `previous_hash` 这 8 个值。对象键按顺序排列；省略空格和 ASCII 转义符；NaN 和无穷大值被排除。请参阅 [确切的编码](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#event-canonicalization)规则。 流程图 · 64个零字符 → 记录 1 / 哈希值 h1; 记录 1 / 哈希值 h1 → 记录 2 包含 h1 / 哈希 h2; 记录 2 包含 h1 / 哈希 h2 → 记录 3 包含 h2 / 哈希 h3; 记录 3 包含 h2 / 哈希 h3 → 签名检查点：计数 3，标题 h3 (保留在其他地方) · 64个零字符 · 记录 1 / 哈希值 h1 · 记录 2 包含 h1 / 哈希h2 · 记录 3 包含 h2 / 哈希h3 · 签名检查点：计数3，标题 h3 · 保留在其他地方 **图表转为文本** 1. 64个零字符 → 记录 1 / 哈希值 h1 2. 记录 1 / 哈希值 h1 → 记录 2 包含 h1 / 哈希 h2 3. 记录 2 包含 h1 / 哈希 h2 → 记录 3 包含 h2 / 哈希 h3 4. 记录 3 包含 h2 / 哈希 h3 → 签名检查点：计数 3，标题 h3 (保留在其他地方) | 更改为提供的日志 | 检测依据 | | --- | --- | | 修改记录 2，同时保留其已保存的哈希值 | 重新计算的事件哈希值不同；其签名不再涵盖已更改的事件 | | 重建被篡改的记录及其后的每个哈希值 | 原始签名验证失败；受影响边界处保留的检查点也显示不一致 | | 删除尾部内容，但保留前缀部分不变 | 在给定前缀之后的某个较早保留检查点显示，导出内容过短 | | 使用另一把密钥对替换后的日志进行重新签名 | 一个独立的可信密钥指纹会拒绝该替换身份 | ![修改已保存的字段会改变其摘要；重新生成哈希值无法恢复原始签名。](https://phishdestroy.github.io/TgWitness/assets/evidence-tamper-animated.svg) **请在记录 2 上尝试以下逻辑：**将已保存事件中的 `Meet at 11:00` 更改为 `Meet at 12:00`。 其重新计算的哈希值将不再匹配。重新计算后续链 可以修复其链接，但无法使原始签名覆盖新的摘要。 相比之下，被观察到的 Telegram 编辑操作将生成一条新的日志记录。 [静态变更图](https://github.com/phishdestroy/TgWitness/blob/main/docs/assets/presentation/evidence-tamper-static.svg) 仅凭哈希链接无法阻止他人重新计算替代链。 信任来源于使用独立可信密钥验证签名，并 与收集器外部保留的参考数据进行比对。 ## 早期检查点新增的内容 ![保留计数 3 和 h3 标题；在位置 3 处会检查后续导出的 4 条记录。](https://phishdestroy.github.io/TgWitness/assets/evidence-checkpoint-animated.svg) **随着日志的增长，引用位置保持不变。**如果检查点显示 “3 条记录，头部 h3”，则包含四条记录的导出文件可以通过匹配第 3 位处的 h3 来通过验证。 其最新头部为 h4，预计会有所不同。仅包含两条记录的导出文件将无法通过验证。 [静态检查点图](https://github.com/phishdestroy/TgWitness/blob/main/docs/assets/presentation/evidence-checkpoint-static.svg) 在验证检查点签名后，需执行以下操作： Nexport ≥ Ncheckpoint and hexport[Ncheckpoint] = Hcheckpoint 导出数据可能超出检查点范围，但必须在保留边界处保持一致。 真正的验证器还会检查每个事件的序列、前一个链接、哈希值和 签名。若仅比较最终存储的头部，可能会遗漏被篡改的内部 记录——因为其保存的哈希值并未更新。 ## 证人的归属之地 流程图 · 采集器 / 账户会话 / 密钥 A → 只读检查点端点; Witness / 固定收集器密钥 / 自有密钥 B → 独立的签名证人日志; Witness / 固定收集器密钥 / 自有密钥 B → 只读检查点端点 (申请审核); 只读检查点端点 → Witness / 固定收集器密钥 / 自有密钥 B (已签名的回答); Witness / 固定收集器密钥 / 自有密钥 B → 包含带签名的 TGW1 帖子的频道 (机器人 API / 专属令牌) · 主机 A · 主机 B · 采集器 / 账户会话 / 密钥 A · 只读检查点端点 · Witness / 固定收集器密钥 /自有密钥 B · 独立的签名证人日志 · 包含带签名的 TGW1帖子的频道 · 申请审核 · 已签名的回答 · 机器人 API / 专属令牌 **图表转为文本** 1. 采集器 / 账户会话 / 密钥 A → 只读检查点端点 2. Witness / 固定收集器密钥 / 自有密钥 B → 独立的签名证人日志 3. Witness / 固定收集器密钥 / 自有密钥 B → 只读检查点端点 (申请审核) 4. 只读检查点端点 → Witness / 固定收集器密钥 / 自有密钥 B (已签名的回答) 5. Witness / 固定收集器密钥 / 自有密钥 B → 包含带签名的 TGW1 帖子的频道 (机器人 API / 专属令牌) 该见证工具会记录回滚操作、在相同计数下出现的不同头部、密钥变更、 无效答案及缺失的响应。仅凭计数增加并不能证明 所有早期记录均未发生变更；请将导出数据与保留的 检查点进行比对。在另一台主机上部署见证工具可避免受收集器主机故障的影响； 由独立操作员管理则能提供额外的独立性。 见证人会验证采集器报告的日志状态。使用受控 投递测试来检测哪些 Telegram 操作已到达采集账户。 请参阅[见证人设置](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/)。 ## 针对已知操作的测试交付 请使用受控组、独立的采集账户以及新的标记。有目的地发送、 编辑和删除消息，并在各阶段之间检查捕获情况。在检查结果之前，请明确定义 预期操作及截止条件。 R = |observed∩expected| / |expected| Δ t = treceipt - taction 仅计入与预期操作匹配的情况；重复的收据不会增加 分子。分母必须不为零。缺失的收据不计入 延迟测量。需记录时间不确定性；请使用您自己控制的删除操作时间， 因为 Telegram 无法提供确切的删除时间。 诸如 5/6 (83.3%) 之类的结果描述的是测试操作，而非所有 Telegram 流量的完整性。 ## 选择工作流程 [完整的调查流程演示](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/)将围绕一起 涉及频道、群组、机器人和私聊的事件展开： 1. 在专用采集账户中，启用“整个账户”调查模式并 清点可访问的聊天记录。可选择特定聊天记录或文件夹作为主账户。 2. 获取日志快照、按聊天分列的完整历史记录以及已保存的附件。 3. 保留实时更改以及任何有意的面板交互及其操作记录。 4. 通过引用的记录和用户资料，追踪数字发件人 ID、回复关系、重复收件人和文件 哈希值。 5. 在“案件看板”中添加与来源关联的注释和集合。重建跨聊天 时间线，其中应包含时间戳和明确的间隔。 6. 在保持各账户的来源和密钥相互独立的同时，比较其他账户的工作区。 7. 汇总并验证带签名的日志、用户资料及历史数据导出文件，并附上案件备注。 网站上的 `/docs/cases/` 指南包含交互式案件地图，并针对 机器人纠纷、已删除消息以及参与者更改名称等情况提供了多种处理方案。Case Board 将笔记和收集内容保存在工作区内。批量导出功能可收集独立的 工作区包；跨工作区关联分析及合并时间线仍由 分析师负责。 [已完成验证及剩余工作](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/) · [导出与验证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#investigation-handoff) · [从一个账户开始](https://phishdestroy.github.io/TgWitness/zh/docs/reference/quickstart/) --- # Telegram · 报告配置与验证 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-reports/ 报告过滤器、八种设计模板、内容预设、已保存的变更历史记录以及评估结果均包含在已签名的导出文件中。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 报告过滤器、八种设计模板、内容预设、已保存的变更历史记录以及评估结果均包含在已签名的导出文件中。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [调查](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/) ![调查](https://phishdestroy.github.io/TgWitness/assets/chapter-investigate.svg) 将选定的观察结果转化为一份通俗易懂的案件报告：包括案件问题、 范围、已保存的更改、图表、调查结果及来源参考。每份报告都为 接收方提供了核查所交付材料并检查其采集 覆盖范围的途径。 **“信任基础与限制**”部分出现在日志、移交、聊天、 账户和共享报告中。日志和移交 PDF 文件采用与 其已签名的 `report.json` 相同的评估结果。ZIP 清单在已签名的 清单中包含 `case_assessment`。该评估结果随导出材料一同传输。原始 观察结果保留其现有的签名。 ## 文档格式与阅读顺序 ### 报告工作室 打开**“导出”→“配置”并预览**。依次操作**“数据”→“设计与内容”→“预览”**： 1. 可使用整个工作区，或选择聊天记录、作者、包含 UTC 观察 日期及事件类型的记录。加载目录以搜索聊天记录和作者，或输入 其 Telegram ID。作者过滤器匹配记录的发件人 ID；若删除 通知中未包含发件人，则不会与作者过滤器匹配。 2. 选择页面设计，然后选择图表、参与者标签、对话记录以及 您的书面调查结果。更改设计时，这些选项将保持不变。 3. 生成预览。预览中显示实际计数、活动情况、参与者、样本 记录、已保存的更改以及缺失的消息编号范围。更改选项 会导致预览过时。请在下载 HTML、签名 PDF、 签名 JSON 或证据 ZIP 文件之前保存。 数据预览统计的是完整的稳定日志前缀，而非初始样本。 仅显示的样本行和长列表有边界限制；其省略的计数会 显示出来。后续导出将生成新的稳定快照，因此持续采集可能会 增加这些数字。范围、计数和来源标识包含在 已签名的报告中。打开或预览表单不会将其保存。 **管辖权指南。** 在文档详情下，打开**“管辖权指南 · 可选** ”以选择管辖权及民事/商业或刑事程序。附录包含 法律依据、来源链接、准备说明及研究进展。 本地语言 的摘要和数据收集保障措施说明为可选内容。默认情况下未 选择任何管辖权。这些选项属于工作区，不包含在 已保存的布局配置和隐式共享-复制默认设置中。请参阅 [默认设置、支持的报告及研究限制](https://github.com/phishdestroy/TgWitness/blob/main/docs/JURISDICTION_GUIDANCE.md) 。 **选择收件人的副本。** 图表和记录文本均基于所选记录生成。 完整性、保管和覆盖范围描述了完整的源日志。证据 ZIP 文件 包含原始记录及其附件。当收件人仅需接收选定且获准的数据时，请采用[精简移交方式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#handover-extract) 。 ### 读取编辑、删除及缺失的 ID 编辑操作会显示保存前的**“之前**”文本和“**之后**”文本，并突出显示已更改的 词语。删除操作会显示通知出现前保存的最后一个版本。如果未捕获更早的 内容，报告会明确说明。当您仅选择编辑或删除操作时， 先前版本仍作为明确标注的上下文保留在 筛选器之外。 无关的消息不会被添加到这些历史记录中。 **未观测到的消息 ID** 是指在选定聊天记录中的已知编号与 基于日期生成的 ID 范围之间存在的缺口。在将某个 编号判定为未观测之前，需对所有已知源记录进行核查：过滤掉其他作者、事件类型或日期 不会导致虚假缺口。 相邻的已保存消息被标记为上下文。一个缺失的 数字并不能证明该消息曾存在或已被删除；删除通知 和重新检查失败仍属于独立的事件类型。 ### 选择一种设计 提供八种页面设计模板，适用于日志和单次聊天记录的 HTML 及签名 PDF 报告。这些模板基于相同的记录和计算结果，仅在封面、 排版、章节标题、表格和行间距方面有所不同。 | 设计 | 行文风格 | | --- | --- | | 经典版 | 采用深色封面、各章节编号的传统档案夹。 | | 编辑说明 | 采用带边框的衬线体标题页，宽边距和窄章节栏。 | | 简报 | 采用简洁的封面设计，书脊为海军蓝，标题简短，表格排列紧密。 | | 分析 | 采用调查问卷风格的封面、模块化图表版式及等宽字体图示。 | | 技术 | 采用带横线的登记表、编号参考栏和精确的对比表。 | | 概述 | 采用全景式封面设计，留白充裕，并突出显示摘要图表。 | | 阅读系列 | 采用分栏布局，并将“调查结果”、“范围”、“变更”和“观察日志”等章节分组呈现。 | | 账本与保证金 | 章节采用编号形式，留有宽边距，图表和表格需完全准确，并单独列出消息记录。 | 设计方案按工作区保存，并记录在已签名的导出清单中。 HTML 支持离线使用，支持浅色和深色主题，并可适应窄屏 及从右到左的语言。原生 PDF 使用捆绑字体；“编辑”设计 包含 Noto Serif 字体，该字体遵循其捆绑的 SIL 开放字体许可证。阅读系列以及 “账本”与“页边距”功能也适用于账户概览、账户聊天和共享副本。 中文、日文和韩文的 PDF 文件还需在服务器上安装合适的字体， 例如 Noto Sans CJK，该字体需在系统范围内部署或放置在 `TGWITNESS_FONT_DIR` 目录中。 若无法使用该字体，ZIP 文件将保留 HTML 和 JSON 格式的报告。 这两种设计均包含无需 JavaScript 即可阅读的日志。对于大型 导出文件，此视图在 8 MiB 的输入配额内最多可显示 500 条完整记录； 报告中会标注该限制，并提供完整查看器及源记录的链接。 账户目录和关系索引描述的是同一阅读样本， 而非所有参与者。完整日志图表保留其单独说明的范围。 ### 选择内容 | 目录预设 | 默认包含 | | --- | --- | | 案件档案 | 活动、观察时间、参与者、聊天记录及对话记录。 | | 简报 | 活动概览中不包含参与者排名或对话记录。 | | 活动回顾 | 活动、观察时间、参与者、聊天记录及其构成，需附来源出处和确切数据。 | | 自定义报告 | 请自行组合图表、文字记录和预览内容。 | 更改预设时，您的设计、案件详情和书面分析将得以保留。完整性 检查、覆盖范围、限制条件和验证说明在每个设计中均予以保留。 当隐藏图表或笔录时，ZIP 文件中的源记录保持不变。 可选的**“检查笔记**”包含报告作者撰写的提问、方法、发现结果和 结论。在发现结果中需引用源文件和记录编号。 签名将这些作者陈述与 报告一并保存；源观察结果和作者的解读仍可被识别。 简化版交接文件将省略这些私人笔记和完整的病历图表。图表和 检查选项同样适用于病历报告。 可按时间范围筛选活动，查看 UTC 工作日/小时热力图、参与者排名、聊天 排名及记录构成。可选择 5 至 30 个排名组，并使用中立的参与者 别名或账号 ID。未知发件人及其余参与者将显示在单独的 行中。别名仅影响图表显示；源记录中仍保留其真实身份信息。 设计预览基于未保存的草稿进行更新，使用正式版封面、审查和 图表组件，仅限于前 50,000 条源记录中的匹配项。下方的数据预览 计算完整的选定内容。该预览明确 未签名，且不会保留编辑内容。“封面”和“图表”按钮可切换其显示部分。 这并非完整的 PDF 预览。**“保存报告设置**”会将选项应用到 未来的导出中；现有的已签名文件不可更改。PDF 采用所选的封面、 排版、章节布局以及与 HTML 和已签名 JSON 相同的汇总数据。 信任评估、覆盖范围限制和验证说明仍需保留。 隐藏图表或可读转录文本不会从 ZIP 文件中删除权威来源行。 已禁用的图表系列将从分析 JSON 中省略；请使用 “最小化导出”功能来限制来源记录的披露。 数据筛选条件适用于日志报告；账户和共享数据的导出将保留 其自身的采集和披露范围。 共享的设计/图表偏好设置已固定到新的聊天/账户导出文件及账户 共享预览中。账户/共享的语言和隐私设置保持独立； 私人案件和审查笔记不会被复制到这些导出文件中。账户和 共享报告仍以 HTML 格式存在，并由其签名的归档清单提供保护。 日志、 精简版日志移交以及单聊天工具包也提供带签名的PDF文件。 ### 图表统计内容 日志活动和热力图统计新消息、历史消息、恢复消息、编辑消息、已删除消息以及 复查时缺失**的消息**，统计依据为采集器记录观察时间（UTC）。心跳 和附件回执不计入统计。 参与者排名仅统计新、历史 及恢复的消息观测：发送者不被视为编辑者或 删除者。重复的观测可能描述同一条 Telegram 消息。 日志分析保留按类型统计的计数、首/末条记录引用以及源文件 `events.jsonl` 的 SHA-256 值。HTML 和 PDF 中的数据均包含精确数值。每日数据桶 在记录超过 366 天后将切换为按月统计；图表将这些数据合并为最多 36 个 等宽区间。 当唯一标识符超过 100,000 个或累计月数达到 1,200 个月时， 相关图表将不可用，但精确的总计数仍可查阅。 快照和账户共享图表仅统计包含的非服务消息行， 并采用其记录的消息时间。共享汇总数据在脱敏 和过滤后计算得出。这些图表最多使用 90 个等宽的 UTC 日期区间，并保留 最多 10,000 个分组值；超出数量将明确声明并进行核对。 最后一个时间间隔可能较短。未知或原始日期不会进入时间图表。 空时间段表示未包含相关记录；如有缺口，请查阅覆盖范围。这些 图表描述了已保存的活动。未知发件人仍作为单独类别，且 每次检查均单独报告。 若包含 `analytics.json` 文件，该文件将受到归档文件签名哈希值的保护。 日志 `report.json` 嵌入了相同的选定聚合值。签名验证 可检测到字节变更。若要核对数据，请使用 `report_analytics.Analytics` 和 `selected` 重新计算日志聚合值，或 使用 `snapshot_analytics.collect` 和 `project` 重新计算快照聚合值。 ### 异常指标 **预览。**证据报告中新增了**异常指标**部分，该部分由 已注册的处理器计算得出（`tgwitness/metrics/`，每个指标对应一个文件）。报告会列出每个 运行过的处理器的名称及其版本，并在其表格下方显示其计算方法，因此 可通过 `events.jsonl` 结合 `tgwitness.metrics.run` 重新进行计算。 | 处理器 | 功能展示 | | --- | --- | | `first_time_posters_over_time` v1 | UTC日内的首次发帖者数量及消息数量。触发警报需满足：首次发帖者数量至少为五人，且其数量需达到中位数的3倍；消息量最多为中位数的1.5倍。基准线采用经过7天预热期后，在过去14个日历日内至少7天的观测数据。 | | `service_vs_message_ratio` v1 | 每个聊天室的已保存消息编号各不相同，且服务消息会占用部分配额。本文描述的是编号规则，并未解释特定编号缺失的原因。 | | `join_leave_per_month` v1 | 每月的新加入、离开、移除或封禁情况，按每人、每个聊天群、每次变更及每天统计一次。 | | `pinned_per_month` v1 | 按月统计：固定服务消息、取消固定通知，以及在聊天状态快照之间新增或移除的已固定消息。 | **参数 → 报告指标**用于选择处理器和显示的行数， 包括在过滤后的报告中。日表和月表显示最近的行，服务份额 表则按已保存消息数量对聊天进行排序。总计涵盖每一行。 从源代码检出开始，基于同一份虚构期刊构建上述所有八种设计： ``` python tools/build_report_styles.py --output test-results/report-styles ``` 打开生成的 `index.html` 文件，以对比完整的 HTML 报告、已签名的 PDF 文件和 ZIP 压缩包。每种设计均基于同一源日志。每次运行时请使用新的输出目录， 以便保留先前已签名的示例。 ![虚构的 HTML 档案](https://phishdestroy.github.io/TgWitness/assets/dossier-en.png) HTML 页面以案件封面和关键数据开篇。编号证据图谱链接 至每项调查结果、其支持事实、限制条件及独立审查报告。可搜索的 记录和稳定的记录引用在离线查看器中仍可访问。 该设计可适应窄屏设备，并兼容无 JavaScript 支持的主题和浏览器。 已签名的 PDF 文件包含专用的 A4 封面、报告编号和二维码、执行 摘要、证据图、编号调查结果以及文档书签。其页 首和页脚标明了报告信息。二维码用于标识材料；它并非 独立的验证结果。浏览器打印件与该 加密签名的 PDF 文件是分开的。 观察时间轴将记录的观察时段和中断 置于同一条 UTC 时间轴上。空白区域不代表推断出的覆盖范围；详细表格 保留了确切的时间间隔。ZIP 文件包含可读报告、已签名的 JSON、 源记录和验证说明。 生成一份全新的、虚构的英语/俄语/德语档案，其中已安装开发 环境： ``` python tools/build_dossier_example.py --output test-results/my-new-dossier ``` 每个语言目录包含 `report.html`、`report.pdf`、`report.json` 和 `dossier.zip`。现有示例目录绝不会被覆盖。创建过程中不使用任何 Telegram 账户、外部时间戳服务或网络连接。 ![虚构的已签名 PDF 文件的前三页](https://phishdestroy.github.io/TgWitness/assets/dossier-pdf.png) ## 阅读具体案例 对于一个包含 1,200 条记录的日志，其第 1,000 条记录具有经过验证的时间戳， 报告识别出 200 条晚于该时间戳范围的后续记录。 这是 检查点存在的 上限，并非每条消息发送 时间的证明。如果另外三个时间戳文件验证失败或无法验证， 则将其单独计数，且无法得出肯定结论。 一个可用的时间戳必须满足以下所有检查条件：其印记与 检查点匹配，其签名链在加盖时间戳时可追溯至可信的 TSA 根证书，且 检查点的签名、密钥、计数和头部与日志前缀完全一致。 仅解析时间戳或拥有 OTS 收据是不够的。阅读者 必须独立选择可信的 TSA 根证书并重复验证。OTS 需要 其自身的比特币确认检查。 | 报告状态 | 含义 | | --- | --- | | 导出时已核对 | 导出工具已执行所述检查；仍需独立重复验证。 | | 已记录；需审核 | 记录的是基础观察结果或操作员陈述；这并非独立确认。 | | 本译文未包含以下内容 | 该文本中没有支持这一说法的佐证材料。但也没有说明其他地方不存在此类材料。 | | 未经独立核查 | 该报告不提供独立的验证结果。 | | 不完整或不可用 | 某些材料或必需的核查步骤缺失、不完整或未通过。 | 请结合记录的采集覆盖范围，分别审查每一项检查。 ## 强配置必须保留的内容 1. 在依赖采集功能之前，请通过 一个独立的可信渠道保留采集器的密钥指纹。将该参考值与导出文件的签名密钥进行比对。 2. 保留带有独立时间戳的检查点，以及（如有使用）位于采集器管理控制范围之外的 见证日志。将其与 导出的日志进行比对，以核查其早期边界。 3. 记录采集范围、缺失部分、过滤条件、限制条件以及采集过程中的变更。 解释与实际申诉相关的缺失时间段，同时明确区分未被观察到的 消息 ID、删除通知和重新核查失败的情况。 4. 保留原始 ZIP 文件及其哈希值。记录每个持有者、传输情况、日期 及目的。同时保留归属的操作员陈述和案件笔记。 5. 对于机密虚拟机，需保留并独立验证引文、挑战、 Intel 证书链、测量数据、确切来源及密钥处理条件。 将证明验证结果与已审查的证据一并保存。 请参阅[验证范围](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#verification-scope)部分，了解各模式下对采集、 归档完整性、时间及采集覆盖范围的检查。 ## 收件人审核 请使用可信的 TgWitness 安装版本以及独立获取的指纹： ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --tsa-ca tsa-root.pem python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --witness witness.zip --witness-fingerprint WITNESS_SHA256 --require-witness python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --check-drand ``` 证人 ZIP 文件必须来自独立可信的来源；同时保留其密钥 和来源信息。保留命令、工具版本、输出结果、已审核的输入 哈希值以及未解决的问题。信标验证是一项独立的在线检查； 报告渲染器绝不会仅为了显示报告而联系任何服务。 针对特定消息的争议，应引用存档参考信息、权威 文件及记录参考信息，然后描述相关的时间范围、覆盖缺口、 选择标准及佐证材料。对于共享副本，还需审查记录在案的 转换过程及其与源存档的关联。私有过滤器和身份 映射不纳入公开评估范围。 对已签名的 PDF 进行验证可检测受保护字节的更改。请将原始 数字文件和验证结果与任何屏幕截图或打印的阅读副本一并保存。 --- # Telegram · 账户导出 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/account-export/ 导出该账户当前可读取的内容：范围、可恢复的任务、经签名的存档以及已缩减的共享副本。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 导出该账户当前可读取的内容：范围、可恢复的任务、经签名的存档以及已缩减的共享副本。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [证据与验证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/) ![证据与验证](https://phishdestroy.github.io/TgWitness/assets/chapter-evidence.svg) 账号导出会独占该账号。启动或恢复前，请明确暂停监控或其他采集任务；应用绝不会自动停止它们。 作为安装管理员，请选择**“从这里开始”→“导出我的账户**”，或**“导出”→“Telegram 账户”→“配置账户导出”**。 如有需要请登录，查看权限范围，并明确启动导出。无需持续监控。**已保存的观察记录**是对现有日志的单独导出；其ZIP包含所有来源，不受日志过滤器限制。每个工作区都有独立的任务、签名身份和存储空间。已授予的面板访问权限（包括无限制的普通导出权限）无法访问这些全账户范围的路径。 **“按发件人或消息文本过滤**”下可展开发件人和文本过滤器。**“账户数据与连接方式**”包含可选的账户分类以及“Takeout”与“常规会话”选项；其摘要会显示当前选中的选项，即使关闭后依然可见。关闭这些部分后，其设置将得以保留。在切换视图时，导出和报告草稿仍保留在当前面板会话中；重载浏览器后，这些草稿不会被保存。无论选择哪种导出方式，均可访问现有任务。 此工作流会导出当前已连接账户可访问的数据。默认使用 [Telegram Takeout](https://core.telegram.org/api/takeout) 功能；这并非对不可用或已删除的 Telegram 数据的备份。秘密聊天、不可访问的历史记录以及早前的编辑内容均无法恢复。Telegram 可能会在 Takeout 开始前设置等待期。控制面板会显示该等待时间；系统不会在用户不知情的情况下切换传输方式。显式的常规 API 选项覆盖范围不同，并会记录不受支持的类别。 Takeout 是 Telegram Desktop 也使用的官方导出 API。TgWitness 可以直接从其自身的采集数据中写入 与 Desktop 兼容的 JSON；无需导入他人的 存档。两种传输方式均可获取聊天和消息 ID。 公开聊天或转发权限并不能保证导出速度更快，也无法消除 Takeout 的审批延迟。在比较速度之前，请先测量相同的范围和媒体设置。 对于最多20个明确选定的聊天ID，常规API导出会在考虑该账户完整的对话列表之前 直接解析这些对等方。因此，即使该公共频道未出现在对话列表中， 也可以在无需加入该频道的情况下将其导出。 未缓存的对等方将回退到普通对话列表。 归档过滤器仍会生效：如果 Telegram 未返回某个对话，且已归档 的聊天被排除在外，则未知归档状态将被记录为遗漏。 Takeout 保留其分段范围对话列表处理流程。两种路径均不会加入聊天或 更改转发权限。 在与桌面版兼容的 JSON 中，Telegram 标记为 `left` 的频道将显示在 `left_chats` 下，包括该账户尚未加入的可读公共频道。 `FLOOD_WAIT`和`FLOOD_PREMIUM_WAIT`都会在服务器要求的整个 时段内暂停请求。该账户的截止时间在重新连接和重启后仍会保留；后续设置的 较短等待时间无法缩短该截止时间。重试次数受限，取消操作会保留已密封的页面， 且 API 凭据不会轮换以绕过速率限制。不会进行任何 Premium 购买。 ## 选择要收集的内容 | 设置 | 含义 | | --- | --- | | 目的 | 请记录此次收购的必要性。请勿在此处填写不必要的姓名或敏感的案件细节。 | | 报告语言 | 选择可读报告中标签的语言。原始消息文本保持不变；未翻译的模板标签使用英语。该语言通过已签名的任务选项固定。 | | 聊天类型 / 聊天 ID | 可选择所有类型，或仅选择列出的聊天；“已保存的消息”属于私人聊天。已归档的聊天可单独选择。 | | 日期 | UTC。面板中的“起始”和“截止”日历日期均包含在内。该 API 使用包含起始日期的 `from_utc` 和排他 `to_utc`；面板会发送“截止”日期之后的第一天。若边界为空，则该侧不受限制。 | | 发送者 ID | 仅显示所列发件人的消息；若列表为空，则包含所有发件人的消息。 | | 文本包含 | 不区分大小写的字面短语，通过“OR”进行匹配。发件人/日期/自有消息条件则通过“AND”进行组合。 | | 自己的消息 | 仅保留发送的消息。 | | 媒体类型 | 选择附件类别，或清除所有选项以避免下载消息文件。 | | 文件/媒体总量限制 | 按文件计算的 MiB 以及已下载媒体的总容量（GiB）。文本、收据、可读报告以及 ZIP 占用的空间需要额外的磁盘空间。 | | 账户分类 | 个人资料、联系人、头像、动态、会话元数据及其他 Takeout 数据均设有独立的控制选项。 | **“最小化”集合**预设会禁用文件和账户元数据。发送者/内容过滤器会在保留的消息页面和媒体下载之前生效。Telegram 仍会传输包含评估这些过滤器所需消息的 API 历史记录页面：过滤并不保证未选中的消息绝不会进入进程内存。工作区中的其他持续监控项目拥有各自的范围和保留设置。 个人资料照片历史记录和动态消息默认不被选中。当案件仅需消息时，请同时禁用个人资料和联系人。如果附件或元数据并非必需，在采集过程中将其排除可避免在本次导出中保留另一份私有副本。 照片有效载荷采用其元数据和哈希清单中标识的静态图像变体，包括带有动画头像变体的照片。该动画不会替代所选的静态图像。比观察到的大小更短或更长的有效载荷将被记录为附件失败，而在文件引用更新期间发生表示形式变更的情况将被拒绝。这些失败会导致存档不完整，但会保留消息记录。 独立验证还会拒绝那些签名长度与其实际大小或表示形式不符的已保存附件，包括旧存档中的附件。 ## 简历、报道范围与验证 每个任务都会锁定其选项和账户身份。清单和捕获的页面均经过签名；页面收据记录了哈希值、光标位置、时间、附件结果及其前一个收据。只有已提交的页面才会推进进度。重启/恢复操作会在继续之前检查这些记录。若账户发生变更、已签名页面发生变更或收据链不一致，则会被拒绝。在捕获过程中无法编辑选项：如需处理其他范围的内容，请启动另一个任务。 “暂停”会中止正在运行的账户操作。重新启动应用程序后，未完成的工作仍可被显式恢复。过期的 Takeout 会话需要显式恢复；更改 Telegram 分段范围可能需要重新进行数据采集。恢复操作会保留之前的观察结果，因此长时间运行的导出并非单个原子快照。在数据采集期间，其他账户切换操作和冲突的导出操作将被阻止。请等待打包完成后再删除工作区。 “恢复”功能会在继续操作前验证已捕获的内容。存储在低速存储设备上的大型存档可能超过**“参数 → 面板操作超时**”（默认值为 120 秒）的配置值。请在重试前提高该设置；取消操作或存储中断会导致任务暂停，而完整性检查失败则会生成一个附带说明的失败任务。必须先完成验证或安全停止，才能关闭相关文件。合成测试尚未验证任何关于大型账户吞吐量的声明。 该面板可区分已完成的选定范围与部分存档，并记录遗漏和读取失败的情况。有意排除的文件与读取失败或不可用的文件有所不同。即使完整性验证成功，也应检查覆盖范围。没有任何本地读取器能够证明 Telegram 返回了所有曾经存在过的消息。 已完成的ZIP仍可供重复下载和HTTP范围下载。一个账户存档包含 `manifest.json`, `manifest.sig`、已签名 `job.json`, `inventory.json`, `receipts/`、权威 `data/*.jsonl`、已筛选 `media/`、可读的 HTML 以及验证器。通过独立信道固定收集器的指纹，然后使用可信安装环境进行验证： ``` python -m tgwitness.verify account-export.zip --fingerprint TRUSTED_SHA256 ``` 对于展开后内容超过 4 GiB 的存档，请显式设置适当的 `--max-gib`。该面板通过声明的展开大小和已发布的ZIP摘要来验证其经过认证且完整的本地存档；外部命令行界面（CLI）则保持其独立的大小限制。在打开可读的 HTML 文件之前请先进行验证。虽然存档中捆绑的验证器很方便，但使用独立获取的验证器可以避免信任随证据一起提供的可执行代码。 Ed25519签名和SHA-256哈希值可检测收集器提交相关字节后的变更。它们并不能**not**证明Telegram对这些消息进行了签名、收集器操作员行为诚实、该账户的历史记录完整，或法院会采纳该材料。捕获时间以收集器的时钟为准。独立的时间戳和独立的采集来源必须分别进行评估。 ## 为律师或其他收件人准备一份披露文件 下载完成的导出文件后，请保留原始的 ZIP，并从 `index.html` 解压后的副本。该报告说明了其范围、可用覆盖范围和 限制。其记录引用结合了存档引用、文档路径和 记录编号，因此收件人可以在 HTML 或打印件中找到相同的条目。 有关实际示例，请参见 [打开虚构报告](https://phishdestroy.github.io/TgWitness/demo/report/)。 在完成的账户导出中，选择**“准备共享副本**”。这将生成一个独立的、经过签名的衍生副本。源文件 ZIP 保持不变且为私有；除非收件人被授权接收其完整内容，否则请勿将其与经过简化的衍生副本一同发送。请单独选择其报告语言。更改语言或任何选择设置后，在创建前需要再次预览。 1. 输入披露目的，并选择日期、发送者 ID 以及文本内容条件。 2. 您可以选择保留真实身份、仅显示列出的参与者，或对所有人进行化名处理。在任何化名模式下，聊天 ID/标题和消息 ID 也会被替换。化名在同一份披露文件内保持不变，但在独立准备的披露文件之间会发生变化。 3. 可保留消息正文、完全省略，或添加具体名称/短语进行屏蔽。在私密模式下，该工具还会屏蔽已知的隐藏发件人名称和别名、完整令牌形式的发件人 ID、私聊昵称、链接、电子邮箱地址以及类似电话号码的字符串。已知名称匹配功能支持 Unicode 大小写转换，包括 `Straße`/`STRASSE`。通用群组/频道名称不会自动从消息文本中移除。若已知身份屏蔽限制被超过，请缩小源导出范围或省略文本；该工具不会默认跳过后续的名称。这些规则仅为尽力而为，并非普遍的匿名化处理。 4. 除非收件人需要，否则请勿包含文件。包含的原始文件将保留其像素、音频、文本和元数据。该工具**不会**对这些文件进行匿名化处理。 5. 预览计数、警告和转换后的消息示例，然后明确确认创建。示例限制为每条消息 12 条，每条文本长度不超过 2,000 个字符。这仅为示例，并非对结果的完整审查。更改设置需要再次预览。预览在 15 分钟后失效，且与该管理员会话及原始的 ZIP 严格绑定；创建后无法重复使用。新的预览将使同一任务和会话中的先前预览失效。 6. 查看生成的完整 `index.html` 并 `messages.jsonl` 在本地进行检查。若发现其中包含不必要的信息，请创建一份新的披露文件并设置更严格的排除条款。请勿直接编辑已签名的ZIP。 ### 筛选后未包含的消息 **预览。**当披露内容不完整时，其显示效果也会不完整。在每个包含至少一条已披露消息的聊天中，选定范围未包含的消息会以标记形式显示， `[withheld by selection — rule: sender]` （或 `text`, `period`)。选择**“被选定范围排除的消息”**：每组连续被排除的消息显示一个标记（默认），或每条消息显示一个标记。标记仅包含规则和计数，绝不包含文本、发件人、日期或文件。未披露任何内容的聊天将被完全排除，因此该软件包不会透露其存在。 已披露的回复会说明其回复对象：是本副本中包含的消息、被筛选排除的消息，还是源导出中不存在的消息（在导出前已被删除或从未被导出；导出数据无法区分这两种情况）。 被披露回复所回应的被屏蔽消息始终带有独立标记，因此该回复会指向一条解释其为何为空的记录。这三种状态有别于删除和数据缺失，后者属于源导出数据本身。 在 `messages.jsonl` （格式 `tgwitness-account-disclosure-v2`）中，每条消息包含 `state`: `disclosed`，或 `withheld` 带有 `rules` 和 `count`。已披露的回复包含 `reply_to` 与目标 `id` 和 `state` (`disclosed`, `withheld`, `not_in_source`）。清单统计了已公开的消息、聊天、媒体和 `withheld` 消息。 `verify.py` 会拒绝携带内容的标记，以及指向包中缺失记录的回复；版本 1 的包仍按原有方式进行验证。 精简格式省略了结构化的账户资料、联系人、头像、会话、故事、原始 Telegram 对象、转发头信息、回复引用、联系人卡片和位置元数据。它不包含原始 JSONL 文件、私有过滤器设置、化名密钥和身份映射。选中的文本、明确保留的身份信息以及包含的文件仍可能包含与这些过滤器中相同的名称、ID 或短语；这些内容需要单独审查。 隐私策略和化名密钥以加密形式保存在该任务的本地保险库中；删除任务将清除其关联的隐私披露记录。公共策略记录的是过滤器计数而非过滤器值。声明的目的在清单和 HTML 中是公开的：明确的隐私标准以及在化名模式下已知的隐藏身份也会被遮蔽，包括在省略消息文本的情况下。请确保目的陈述中不包含不必要的个人细节；未知的身份识别上下文可以保留。 其清单文件将衍生文件、公开政策以及原始 ZIP 的哈希值绑定在一起。通过验证可以确认文件的完整性，如果源文件在本地提供，还可以验证源文件的关联性： ``` python -m tgwitness.verify minimized-disclosure.zip --fingerprint TRUSTED_SHA256 python -m tgwitness.verify minimized-disclosure.zip --fingerprint TRUSTED_SHA256 --evidence account-export.zip ``` 来源链接本身并不能独立证明该转换过程已选取所有必需项目或移除了所有可识别细节。原始明文并未作为证明嵌入其中。对此判断需要进行新的审查。 ## 共享与托管捕获 选择收件人所需的消息和文件，审查完整的共享副本，并将源文件单独保留。记录已发送 ZIP 文件的哈希值，以便收件人能够识别并验证该确切副本。通过假名化处理替换所选标识符；包含的文本和原始文件仍作为审查内容的一部分。 GitHub Actions 支持通过 Takeout 或常规 API 导出整个账户或选定聊天记录，还支持单个聊天的事件日志。[托管捕获指南](https://phishdestroy.github.io/TgWitness/docs/capture/)详细说明了设置验证及 120 分钟的时限。要验证从托管捕获生成的共享副本，请将该副本的源哈希值与原始存档进行比对，并使用[特定模式的检查](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#verification-scope)方法验证该存档的认证信息。 [证据格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/) · [案例报告](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-reports/) --- # Telegram · 证据格式 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/ 签名 ZIP 文件的内容、记录类型、操作收据、用户资料、异地副本及离线验证。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) Translation coverage: this edition includes material from the English original. 签名 ZIP 文件的内容、记录类型、操作收据、用户资料、异地副本及离线验证。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) ![证据与验证](https://phishdestroy.github.io/TgWitness/assets/chapter-evidence.svg) TgWitness 将账户可见的 Telegram 观察记录保存于经签名的日志中。 接收方可使用可信的 采集器密钥对保存的记录、附件和报告进行验证，随后将日志与独立保留的检查点进行比对。 本页介绍了格式、校验方法以及移交时需保留的材料。 Windows 用户可通过 **VERIFY.cmd** 开始操作：该程序会要求提供原始 ZIP 文件和独立获取的密钥指纹，显示附有说明的结果， 并保存一份独立的验证记录。有关设置和信任限制，请参阅[验证启动程序和 便携式运行时](https://github.com/phishdestroy/TgWitness/blob/main/docs/VERIFICATION_LAUNCHER.md)。 **本页内容** - [什么是签名](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#what-is-signed) - [比较聊天记录导出文件](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#comparing-chat-exports) - [调查移交](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#investigation-handoff) - [交接摘要](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#handover-extract) - [易于阅读的报告](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#readable-reports) - [事件规范化](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#event-canonicalization) - [参与者语义](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#actor-semantics) - [涵盖范围：连续性、缺口及未观测到的 ID](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#coverage-continuity-gaps-and-unobserved-ids) - [制作方](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#producer) - [用户资料](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#people-profiles) - [独立见证人](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#independent-witness) - [清单和检查点](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#manifest-and-checkpoints) - [验证范围](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#verification-scope) - [附件](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#attachments) - [持久的收据收集与处理（0.2）](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#durable-collection-and-process-receipts-02) - [RFC 3161 准备工作与响应验证（0.2）](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#rfc-3161-preparation-and-response-verification-02) - [证据模式下的可选记录：drand 和 Telegram 设备](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#optional-records-in-evidence-mode-drand-and-telegram-devices) ## 什么是签名 | 资料 | 保护 | 应保留的内容 | | --- | --- | --- | | 日志中的每一项记录，包括操作事件 | 每个事件均包含 SHA-256 链和一个 Ed25519 签名 | 原始 `events.jsonl`（可信密钥指纹）及保留的检查点 | | 证据 ZIP 文件内容 | `manifest.sig` 对规范清单进行签名，该清单列出了内容文件的哈希值 | 完整的 ZIP 压缩包，包含其清单和签名 | | 保留的附件 | 带签名的`media.saved`事件中包含SHA-256和字节计数；带签名的ZIP清单中包含文件哈希值 | 经过验证的 ZIP 文件中的原始字节 | | 检查点 | 对日志长度、头部哈希值、公钥及创建时间进行 Ed25519 签名 | 在发生争议性更改前保留的独立副本 | | 运行收据 | 包含采集器版本、源文件哈希值和启动设置的签名记录，该记录也包含在`process.started`中 | 所选验证模式对应的收据、相关日志及环境证据 | | 可读报告：`report.html`及其组成部分，`report.json`、`report.pdf`、`chat.pdf` | 每个文件均带有针对其内容的 Ed25519 密封；PDF 还包含一个标准的 PDF 签名（参见 [可读报告](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#readable-reports)） | 收到的文件及其可信密钥指纹；该文件所描述的 ZIP 压缩包 | | 独立版 CSV | 不包含独立的加密签名；仅凭事件哈希值是不够的 | 请使用经过验证的 ZIP 文件中的原文件进行完整性校验 | | 由浏览器生成的屏幕截图、打印件或 PDF 文件 | 衍生作品上不包含 TgWitness 的签名 | 保留原始的经过验证的软件包，并记录衍生版本的制作过程 | 采集器在生成每种导出格式之前，都会验证日志签名。 可读的 HTML 和 PDF 报告带有各自的印章；独立的 CSV 文件作为 已签名 ZIP 文件的一部分进行验证。保留 ZIP 文件以保留附件字节和清单， 并设置单独的检查点，用于将日志与较早的边界进行比对。 ## 比较聊天记录导出文件 使用独立保存的签名者 指纹，验证并比较两个已签名的聊天记录导出 ZIP 文件： ``` python -m tgwitness.verify first.zip --compare second.zip \ --fingerprint FIRST_TRUSTED_KEY_SHA256 --compare-fingerprint SECOND_TRUSTED_KEY_SHA256 ``` 当两个存档均记录了相同的数字账号和聊天 ID 时，记录将通过消息 ID 进行配对。 **未更改**指完整的保存 JSON 记录完全一致： 包括全文、作者、日期、回复对象、嵌套元数据和未知字段。 JSON 对象键的顺序无关紧要；缺失字段、空值、值类型 以及数组顺序则会影响匹配结果。300 字符的预览仅用于显示。 已更改的条目 会将差异列为顶级字段`changed_fields`，包括预览中不可见的更改。 匹配过程中，重复的消息 ID 会被拒绝，而非相互覆盖。 差异可能表现为显示名称、浏览次数、收藏注释或其他 观察元数据的变更。仅凭差异本身无法确定 Telegram 内容是否被编辑， 也无法识别修改者身份，更无法证明哪个相互矛盾的存档是准确的。 未解析的记录仍保留在比较结果中；其保存表示形式的相等性 并不意味着其 Telegram 有效载荷已被解码。 对于不同或缺失的账户/聊天标识，该工具仅通过发件人、完整文本、文件哈希、媒体类型以及五秒 的时间容差来查找可能的 对应关系。它报告**匹配（Matched）**，而非**未更改（Unchanged）**。这些候选结果并不能 证明消息的同一性或所有元数据的完全一致。未解析的记录仍被视为 未匹配。 成对记录中的差异仍列在`changed`中，包括在 内容模式下；这些差异并不能证明同一消息被编辑过。使用 `--json`时，`matched`统计成对记录的数量，而`unchanged`统计完整保存 记录完全相等的成对记录数量。在内容模式下，这两种统计结果均不能证明消息的同一性。现有的 `changed_fields`和整数形式的`unchanged`输出仍与 早期的比较结果兼容。归档格式和签名验证保持不变。 ## 调查移交 1. 请在案件笔记中记录案件编号、操作员、Telegram 账户数字 ID、选定的 来源、采集政策及采集时间段。TgWitness 会保留观察记录，并在 [“案件看板](https://phishdestroy.github.io/TgWitness/zh/docs/reference/case-board/)”中支持与来源关联的笔记和采集内容。请将移交和保管记录与案件 材料一并保存。 通过 [实时验收程序](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/LIVE_ACCEPTANCE.md)核对预期的采集设置。 2. 在依赖 其导出数据之前，请独立保留工作区的公钥指纹。在收集过程中，将签名检查点保存至收集器之外。 记录中断情况以及该账户可见性的限制。 3. 导出**带签名的 ZIP** 文件并保留带签名的运行收据。请在 导出日志边界处或之前设置检查点。较晚的检查点会正确地拒绝 较早的导出，因为其长度不足。导出内容包含完整的工作区日志， 不受面板过滤器影响；请在分享前仔细审查相关材料。 4. 请收件人使用可信的验证器副本以及 独立提供的指纹/检查点来验证 ZIP 文件。请在已激活 Python 环境的可信代码检出环境中： ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 --checkpoint retained-checkpoint.json ``` 当两个输入均已提供且被接受时，成功输出报告 `key_pinned: true` 和 `checkpoint_checked: true` 。保留验证结果。 ``` For a handover requiring the final exported record to be witnessed, use `--witness witness.zip --witness-fingerprint TRUSTED_WITNESS_SHA256 --require-witness`. This refuses an export with an unwitnessed tail. See the [witness handover procedure](WITNESS.md#require-a-witnessed-export-boundary). ``` 1. Record the archive's SHA-256, export boundary, transfer date, sender, and recipient in your custody record. Keep the original package intact and work from copies. Share evidence files rather than the application's private data directory, which also contains account sessions and signing secrets. For transfer, choose a password-protected AES-256 ZIP or the stronger `.tgwpw` container. ZIP uses WinZip's low-cost password derivation; use a long random passphrase. `.tgwpw` uses scrypt and AES-256-GCM and opens with the standalone verifier's `unseal-password` command. The password is not stored and only protects confidentiality; the recipient decrypts the archive and verifies the signed export inside, which is unchanged. 2. 如果需要独立的时间锚定，请遵循 [RFC 3161 流程](https://phishdestroy.github.io/TgWitness/zh/docs/reference/timestamp/)，并保留请求、检查点、可信 CA 信息以及经过验证的权威机构响应。仅准备请求 并不能获得时间戳。 For `.tgwpw`, use an independently obtained verifier and choose a new output file with the original extension: `python verify.py unseal-password export.tgwpw --out evidence.zip`. The command prompts for the password; `--password-stdin` reads one line for automation. It never overwrites an existing file and publishes plaintext only after all records authenticate. Run normal signature verification on the decrypted file afterwards. The container uses scrypt (`N=131072`, `r=8`, `p=1`, 16-byte salt; about 128 MiB RAM) and AES-256-GCM with 1 MiB records and an authenticated final record. An encrypted metadata record stores the inner filename, so downloaded containers can be renamed. 验证成功即表明相对于可信采集器 密钥和保留边界，数据完整性得到保障。请参阅[验证范围](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#verification-scope)，了解 信任假设以及所执行检查的[验证结果](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/)。 ## 交接摘要 一个已签名的 ZIP 文件包含整个工作区日志。当法院、律师或滥用举报部门仅需 部分聊天记录、特定时间段或特定人员时，**可通过“导出 → 移交提取”功能**，根据所选披露规则生成一份精简 副本（`tgwitness-handover-v1`）。 操作员需说明目的并选择聊天记录、可选时间段（UTC）、 提取涉及的对象，以及其他人员的处理方式（显示、替换为化名 P01、 P02…或被 省略），哪些消息正文保留，哪些附件和个人头像被包含，以及 文本中的电话号码和电子邮件地址是否被屏蔽。 该目的及这些规则将记录在 已签名的清单和报告中；日志将记录`handover.exported`条目，其中包含 生成该文件的访问者信息以及文件的SHA-256值，而非文件内容。 `verify.py`通过两种方式检查提取内容。显示为未更改的记录将进行全面验证：其 内容与哈希值、Ed25519签名以及与所包含前身记录的链接均需通过验证。 一个 简化记录会保留原始哈希值和签名，因此签名仍可验证，但 被隐藏的字段无法据此重新计算；记录中会注明被隐藏的内容，报告 也会标注出来。清单中会注明日志的长度和头部，并附有采集器对该 头部的签名，同时统计被省略的记录数量； `coverage.json`描述了所选的聊天记录。文件 名中的姓名不会被检测到。分享前请审查最终文件：自由文本、文件名和选定的 附件仍可能泄露个人身份。请保留完整的签名ZIP文件：解压后的文件属于信息披露，而非替代品。 ## 通俗易懂的报告 已签名的证据、移交文件和聊天记录 ZIP 包包含可读的 HTML 和 JSON 报告，此外， 当所需字体可用时，还会包含所选报告语言的 PDF 文件。每份 报告均使用工作区的 Ed25519 密钥进行封装，并可单独验证： `python -m tgwitness.verify FILE --fingerprint KEY [--evidence ZIP]`。 - `report.html` / `chat.html`：封装语句（`tgwitness-report-seal-v1`）会关闭文件，并 对之前的每个字节的 SHA-256 进行签名。较长的日志和聊天记录会被拆分为 可配置大小的部分（报告设置，500 至 100,000 条记录；默认值为 5,000）： `records/records-0001.html` 或 `messages/messages-0001.html`，每个文件均带有其编号、范围 和总数，并与其 SHA-256 一起列在已签名的清单中。收集器心跳记录的连续序列 将显示为一行，除非“报告设置”中指定逐行显示。 - `report.json`（`tgwitness-report-json-v1`，密钥 `format`、`report`、`seal`）：该密封对 `report` 的规范 JSON 中的 SHA-256 进行签名，因此案件系统和脚本可以读取相关事实， 并可在保持签名文件完整性的前提下，从中进行数据保护方面的筛选。 - `report.pdf` / `chat.pdf`：一份用于打印和归档的正式文件，对相同的 字节进行两次签名，除签名值（`/ByteRange`）外，整个文件均包含在内。标准 PDF 签名 （`adbe.pkcs7.detached`、CMS 配合 SHA-256 和 ECDSA P-256）使用一份自签发的文档签名 证书，该证书存储在工作区保险库中；其主体序列号即为Ed25519密钥 指纹。Ed25519印章作为未签名的属性 `2.25.240684792623320047764573196045913242332`封装在CMS中，并通过 `"content": "pdf-byte-range"`标识证书的SHA-256，因此Ed25519密钥为该证书提供担保。 PDF 读取器会显示 文件在签名后是否发生过更改，并在证书被 信任之前将签名者标记为未知；请改用 Ed25519 指纹进行比对。中文、日文和韩文的 PDF 文件需要在服务器上 （或 `TGWITNESS_FONT_DIR` 中）安装相应字体；若未安装，ZIP 文件中仅包含 HTML 和 JSON 报告 。 在频道或超级群中，Telegram 按顺序为消息编号 1、2、3…… 聊天记录导出文件会列出 起始编号和结束编号、现有消息数量，以及所有缺失编号的连续区间（如 `message-ids.json` ）、清单和 `chat.json` 头部信息，并标记每个缺口在 聊天记录中的具体位置。 `verify.py` 从`chat.json` 开始重新计数。缺失的编号是指Telegram 未返回的消息（在导出前已被删除，或该账户无法查看）；在私聊和 基础群组中，编号在该账户的所有聊天中共享，且缺口不计入统计。 读取历史记录后，导出功能会按号码逐一重新向 Telegram 查询所有缺失的号码 （`channels.getMessages`，最多 10,000 个号码）。结果保存在 `message-ids.json` 文件和报告中。 若返回空响应，则记录该号码在重新检查时对该账户不可用； 但未说明具体原因。重新检查时返回的消息将被添加到导出结果中 并标记为 `found_on_recheck`。 每份报告均以**开头。简而言之**：先有一段概述，随后说明材料显示的内容以及未显示的内容 （账号背后是谁、消息传递的完整性、观察前的删除情况、无时间戳的 时间记录）。 当浏览器验证了印章的 签名（而非页面本身）后，页面自身的印章会变为琥珀色：浏览器不会为页面提供其自身的字节。 只有当 读者将文件拖放到页面底部的验证框中，且每个字节都匹配时，且仅当 显示的页面正是该文件时，印章才会变为绿色；否则将变为红色。 每份报告均精确标明程序名称：当收集器从代码检出运行时对应的 git 提交，或 安装程序设置的 `TGWITNESS_COMMIT`，以及其源文件的 SHA-256（`source_tree_sha256`、 路径的规范 JSON → SHA-256，适用于每个 `.py`、`.js`、`.css`、`.html` 和 `.svg` 文件在 包中），除非文件被修改，否则检出该提交即可重现上述内容。 Telegram 客户端的命名包含其库、API 层和数据中心。当观察开始以及聊天 导出开始和结束时，收集器会向 Telegram 查询其时间（`updates.getState`，整 秒），并记录 Telegram 的时间减去收集器时钟的时间，其中包含因 往返传输产生的不确定性；报告在“保管链”部分显示这些测量值。 聊天导出记录的 内容还包括读取历史记录的时间，而不仅仅是消息的日期。 ### 离线报告查看器和存档指南 在打开 `chat.html` 或 `report.html` 之前，请先解压完整的 ZIP 文件。该查看器提供搜索、 筛选、参与者、指标、记录详情以及无需服务器即可进行的 JSON/CSV 选择功能。请将 `viewer/` 和 `media/` 放在报告旁边。所选内容均为衍生文件：请使用 `verify.py SELECTION.json --evidence ARCHIVE.zip` 将其与签名存档进行比对。 验证器会检查报告 ID、签名密钥、归档边界以及每个选定项目；经过编辑、 缺失或重复的项目将导致验证失败。选择说明和创建时间仍属于未签名的元数据。 仅在完整、未经过滤且按升序排列的聊天记录流中显示消息编号缺口。隐藏 类别或未能加载数据块，绝不能将省略的行视为消息缺失的 证据。搜索高亮功能在HTML转义之前对纯文本进行操作，并保留字面标记。 该浏览器会检查清单签名、报告 ID 和密钥，以及所有列出的文件哈希值。它 会拒绝模棱两可或格式错误的 ZIP 结构、重复的文件名和不安全的路径，并将文件 大小限制在 256 MiB 以内，声明的总内容大小限制在 4 GiB 以内。对于更大的归档文件，请使用独立验证器。 此浏览器检查是对验证器对日志链和数据语义检查的补充。 `README.txt`包含一份入门指南、一份对齐的文件清单、验证说明以及 以报告语言编写的数据格式说明，随后是完整的英文指南。 `SHA256SUMS`涵盖了 其中列出的文件，但不包括该文件本身、`manifest.json`和`manifest.sig`；签名清单 还涵盖了`SHA256SUMS`。请保持原始ZIP文件不变，并将工作文件保存到 解压文件夹之外。PDF报告包含章节书签，后续页面上带有案件/报告标识。 ### 导出时的聊天记录 聊天导出记录了导出开始时 Telegram 对该聊天的描述：Telegram 自身的 标签（`scam`、`fake`、`restricted` 及其理由、`verified`）、用户名、描述、成员 和管理员数量、关联的讨论、内容保护、新成员是否能查看早期 消息，以及该账户从哪条消息开始能查看聊天记录（`available_min_id`）， 消息 1 的日期 （当该消息即为聊天创建时间时），以及聊天照片的 SHA-256（保存在 `media/` 中）。 它记录了导出账户在聊天中的位置：角色、加入日期、邀请人，以及对于 管理员而言，其权限。Telegram 拒绝的请求将另行标注。 当导出账户为管理员时，导出操作会将聊天的管理员日志（Telegram 保存约 48 小时）读入 `admin-log.json`：其中包含删除和编辑操作的详细信息，包括操作内容及执行操作的账户。这是 唯一一份能明确指出删除者身份的删除记录。 ### 指标 报告列表及存档中包含 `indicators.csv` 、`indicators.stix.json` （STIX 2.1 ） 以及 `indicators.misp.json` （MISP 事件），滥用处理部门可据此对记录的消息采取行动： 链接和域名（包括隐藏在文本中、按钮内及链接预览中的内容）、加密货币 地址、Telegram 用户名和邀请链接、电话号码、电子邮件地址以及保存的图片。 比特币、莱特币、狗狗币和波场地址仅在 base58 校验和通过时才会被列出， SegWit 地址在 bech32 或 bech32m 校验和通过时会被列出，而 TON 地址在 CRC 校验通过时会被列出；EVM 和 Solana 地址则被标记为未经过校验。 图片包含 SHA-256 以及一个感知 哈希（dHash，64 位），其值在重新压缩或调整大小的副本中几乎保持不变。报告会写入 标记，以防止意外打开（`hxxps[://]example[.]com` ）；文件保留 原始值不变。 每个指示符均被标记为未知且不适用于自动检测（STIX 、 `indicator_types: unknown` 、MISP 、`to_ids: false` ，分发至本组织）：被 列出仅表示某条消息中包含该指示符，并不意味着其具有恶意。若链接的文本显示的 地址与其实际打开的地址不同，则该链接会在报告中被标记。 PDF报告末尾包含一份需由检查员亲笔签署的声明、一份供公证员或 法院专家使用的核对清单，以及一个二维码（首页亦有显示），其中包含报告ID、密钥指纹以及 权威数据的SHA-256，以便打印件可追溯至其存档。 ## 事件规范化 哈希输入必须包含以下字段： ``` seq, observed_at, source_at, kind, chat_id, message_id, actor_id, payload, previous_hash ``` 使用与 Python 兼容的 JSON 格式进行序列化，采用 UTF-8 编码，对象键按顺序排列，不进行 ASCII 转义，不包含无关的空白字符，且不包含 NaN/无穷大： ``` json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False).encode("utf-8") ``` 这些字节的 SHA-256 值即为事件哈希。签名采用 Ed25519 对 32 个原始哈希字节进行计算，随后进行 Base64 编码。第一个 previous_hash 由 64 个零组成。 序列号从 1 开始，并以 1 为增量递增。所有事件（包括操作性 事件）共用一条链。系统不抑制重复交付：重复 的观测结果是独立的收据，而非对独立 Telegram 操作的声明。 Telegram 的原始日期为 ISO 字符串；二进制字段将转换为包含 bytes_base64 的对象。消息正文、实体、媒体描述符、回复元数据、点赞、 以及服务操作（如有提供）均保留在原始消息元数据中。 observed_at 是采集器的 UTC 墙钟时间。source_at 是提供的 Telegram 日期 （如有）。删除通知不会提供确切的删除时间，因此 source_at 保持为空。传输接收顺序不一定与源事件 顺序一致。历史快照使用较早的源日期，但采用当前的观察时间。 ## 行为主体语义 message.new 中的 actor_id 即为消息发送者。message.edited 未推断出 编辑者；payload.sender_id 记录了被观察消息的发送者。 删除 actor_id 保持为 null。成员服务消息保留发送者和操作 类型，不会将每次移除都转换为自愿退出。原始参与者 更新保留所提供的 actor_id。反应快照不会虚构变更操作者。 私人聊天和普通群组的删除通知仅包含消息 ID。 这些聊天共享一个全账户通用的 ID 序列，因此一个 ID 代表该账户中的一条 消息。 当具有该 ID 的消息此前已保存在此日志中时， 删除操作将在该聊天中记录为 message.deleted，并使用 payload.chat_resolution 作为方法名称。从未被保存过的 ID 将作为 deletion.unscoped 保存，且不包含 chat_id；系统不会进行任何推测。 频道和超级群组按聊天对消息进行编号， 绝不会通过这种方式进行匹配。当被删除的消息是由被观察账户发送时， payload.deleted_message_was_outgoing 为 true；但仍未提供删除者信息。 无范围的提示并不意味着消息从未被保存：匹配的 聊天记录可能不在当前观察范围内，或者可能无法找到 唯一的匹配项。在报告计数、过滤器和标签中，未检测到与删除 通知仍属于不同的观察结果。后续的恢复操作会清除 当前的缺失状态，同时在 签名历史记录中保留先前的检查失败记录；这两种观察结果均不构成删除通知。 来自同一条通知且解析为同一聊天室的多个 ID 将被归类为 `deletion.batch`，无论其数量多少。该通知无法证明整个聊天记录是否已被 清除、由谁执行了删除操作，或该操作是否适用于所有参与者。 已保存的已发送消息不会改变这些限制。较早的日志中可能包含由十个或更多 ID 批次推断出的 `history.cleared` 事件，其说明 文本将删除行为归因于另一位参与者。这些推断未 得到本次更新的支持。请保留这些原始的签名记录，但将其 视为分组删除通知；当前界面已据此对其进行标注。 ## 覆盖范围：连续性、缺失内容及未被观察到的 ID 每个签名 ZIP 文件都包含 `coverage.json`，HTML 报告以相同的摘要开头，而 `verify.py` 会根据 `events.jsonl` 重新计算该摘要，而非直接信任该文件： - **从 X 到 Y 持续进行观察。**一个时段以 `observation.started` 开始， 并以暂停、停止、Telegram 连接中断、注销、进程启动但未 有序停止，或在观察期间超过三分钟无任何记录而结束 （每分钟都会写入一次心跳记录，因此静默意味着进程停止、卡死或 计算机进入睡眠状态）。当在**“参数**”中更改心跳间隔时，每次心跳 都会记录该变更，且允许的静默时长变为三个间隔，但绝不少于三分钟。 - **“缺口”**列出了各时段之间的时间间隔及原因。若最后 一条记录处仍存在缺口，则标记为 `not_resumed_by_last_record`。 - **未观察到的消息 ID。**对于按 聊天计数消息的频道和超级群组，观察到的消息 ID 之间的缺失 ID 将以范围形式列出。这些消息会被报告为 “未*观察到*”——即已被删除、从未送达或超出保存的历史记录范围——但绝不会被标记为 “已删除”。私人聊天和普通群组共享全账户范围的序列号，因此此类聊天内部的 缺口没有任何意义，也不会在此处列出。 - 聊天层面的数据缺失通知（例如 Telegram 在某个 频道中要求恢复差异数据）被计为注释；它们不会中断全局覆盖。 ### 缺失的消息编号（`gap_summary`) **预览。** `coverage.json` → `gap_summary` 该工具统计 Telegram 分配的编号中，该 收集器从未检测到的数量。Telegram 针对每个频道或超级群组对消息进行一次编号，并针对 每个账户在私聊、机器人和普通群组中各进行一次编号。两个已观测 消息之间的编号要么已被观测到，要么缺失；连续的编号范围则表明 该范围内的所有编号消息均已被观测到。编号缺口既不指向特定行为主体，也不说明原因。 | 字段 | 含义 | | --- | --- | | `status` | `on`，或 `off` 在**“参数”→“差距分析**”中关闭时 | | `parameters` | 生成该结果的参数，以便能够重现该结果 | | `chats[]` | 每个频道或超级群对应一条记录，每条记录均单独编号 | | `account` | 整个账户中私聊、机器人和普通群组的序列 | | `status` （按序列） | `applicable`，或 `not_applicable` 使用 `reason` | | `observed_from`, `observed_to`, `span` | 首次和最后一次观察到的号码以及范围的大小 | | `observed`, `observed_without_content` | 观测数值；仅通过删除或重新检查记录得知的数值 | | `missing`, `density`, `gap_ranges`, `largest_gap` | 从未观测到的数字、其在范围中所占的比例、运行次数、最长运行时间 | | `clusters[]` | 列出的缺失内容： `low`, `high`, `missing`，以及相邻的观测数值 `after` / `before` 及其观测时间 | | `service_estimate` | 仅在启用时显示：根据观察到的占比，缺失的数字中有多少属于服务消息。该数值绝不会从 `missing` | 有效性源自日志，绝不预设： - **频道和超级群的**统计以聊天为单位进行，在所选聊天的导出文件中也是如此。 由发送方选定的记录将用于统计 `not_applicable`. - **全账户序列**仅从全账户收集功能开启期间收到的第一条消息到最后一条消息进行统计， 并包含私聊、机器人、普通 群组以及该账户自身的消息，没有任何此类聊天被排除在外（`scope.changed`）。 标有 `deletion.unscoped` “count”命名的数字均视为已观察到的消息，不包含内容。导出或 移交选定聊天记录无法测量该数值。如果全账户收集功能曾被 关闭后又开启，则会提示说明：期间使用的数字将显示为缺口。 - 服务消息是带有独立编号的日志记录，因此它们会自动填补间隙； 可选的估计时间仅作为上下文参考。 `verify.py` 重新计算 `gap_summary` 基于 `events.jsonl` 基于签名 `coverage.json` 成员中的参数（针对旧版存档使用默认值），并 在覆盖范围摘要中打印该账户范围内的行。该存档的 `get_capture_status`（MCP 和命令行）针对某次访问可能读取的聊天记录返回相同的测量结果； 而账户级序列仅适用于覆盖整个工作区的访问。 对同一条服务消息的重复观察仅计为一次，且账户服务估算 仅使用测量范围内的数值。在启用全账户测量之前，所应用的范围必须明确保留 该账户自身的消息；未包含该信息的旧记录 无法满足此条件。停止观察不会 延长测量范围，且恢复观察会被记录。实时存档查询有时间 限制（包括其数据库扫描），并将未完成的测量标记为部分完成。 Telegram 记录了[独立的消息 ID 序列](https://core.telegram.org/api/updates#message-id-sequences)。 这些数字描述的是观察结果；它们既不能识别删除行为者，也不能确定 某个数字缺失的原因。 当Telegram停止接受该账户时，结束监视的`coverage.gap`记录 包含`cause`（`account_banned`、`account_frozen`、`account_deleted`、`session_duplicated`、 `session_revoked`、`session_expired`、`session_ended`或`not_authorized`）以及Telegram 错误；`verify.py`指明了该周期结束的原因。 覆盖范围包括记录的观察时段、中断情况及消息结果。 请结合所选的聊天、时间段和附件策略进行评估；仅凭连续 运行并不能证明 Telegram 更新已完整送达。 ## 制作人 证据 ZIP 包、聊天记录导出、Witness 日志以及 人员档案文件的声明中包含的签名清单包含 `producer` ：软件、版本、项目（PhishDestroy）、 主页和源代码仓库。HTML 报告中显示了相同的行，`verify.py` 将其作为已验证内容的一部分输出。 在此字段存在之前生成的归档文件仍按 原有方式进行验证，并在报告中显示为未指明生成者。 每条 `observation.started` 记录还会指明进行监视的 Telegram 客户端：其 `api_id` （绝非哈希值），无论该客户端是内置的公钥对还是运营商自有的应用程序， Telegram 连接请求中发送的客户端描述，以及连接 路由的类型及其 IP 模式（无代理地址或密钥）。 该报告和`custody.json`列出了每个 不同的客户端和路由及其记录时间，以及未列出的代理未响应的时间 和Telegram检测到服务器地址的时间。此前记录的日志中已有说明。 ## 人物简介 应请求，系统会基于日志中已有的 某次聊天的记录生成个人资料文件（`tgwitness-dossier-v1`，JSON）；该文件不会从 Telegram 获取任何数据，且个人资料内容绝不会 写入日志（个人资料的启用和停用将记录为 `dossier.changed`）。 对于每位拥有已保存消息的用户，该文件会列出其姓名和用户名历史记录、Telegram标记 （机器人、诈骗、虚假、高级、已验证、受限、已删除）——以保存时显示的状态为准，以及个人资料 照片ID、来自本地头像缓存中与该头像相似的头像的SHA-256和感知哈希（pHash，与`imagehash.phash`兼容） 、活动记录（首条和末条消息、 数量、已编辑和已删除的分享、按UTC小时划分的消息）、谁回复了谁、该用户曾在此日志中参与的其他聊天 中该用户曾发帖的聊天记录，以及被提及的钱包（BTC、EVM、TRON、TON、LTC、 DOGE、XMR、SOL；Base58Check地址已通过校验和验证）、电话号码、用户名和 链接，包括隐藏在文本背后的链接。 每个事实都会列出其来源的日志记录（`seq`），而 `record_hashes` 则包含 每个被引用的记录的哈希值。该声明使用工作区密钥进行签名： ``` python verify.py tgwitness-dossier-CHAT.json --fingerprint TRUSTED_SHA256 --evidence tgwitness-evidence.zip ``` 该工具会检查签名，验证证据导出文件本身（包括签名、哈希链和文件）， 并确保每个被引用的记录在同一工作区的导出文件中完整无缺且未被修改。头像哈希值会被标注为来自本地缓存 （而非日志记录）。提及内容属于模式匹配——仅为待核查的线索，而非已验证的事实。 配置文件按聊天进行启用，可导出为带密码的 AES-256 压缩包，且 在关闭配置文件或聊天从来源中移除时被删除。 ## 独立见证者 将证人日志（`tgwitness-witness-v1`）及其频道帖子与 通过 `verify.py --witness … --channel …` 导出的证据进行比对；参见[独立证人](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/)。 ## 清单与检查点 manifest.json 包含格式、导出时间、公钥、指纹、日志 长度、头部哈希、范围、生成者、限制条件，以及除 `manifest.json` 和 `manifest.sig` 本身之外 每个内容成员的 SHA-256 值。 manifest.sig 是规范化 manifest JSON 的 Base64 编码 Ed25519 签名。 验证器会拒绝处理意外/缺失的成员、名称重复、文件损坏、 序列/链断裂、签名无效以及与提供的检查点不匹配的情况。 它绝不会提取归档路径。它将声明的总未压缩大小限制为 4 GiB； 若提高 **Parameters** 限制，`--max-gib N` 允许创建更大的归档文件。 请从您已安装的 TgWitness 版本或经过审核的代码检出中运行验证。 存档文件中包含的副本支持便携式使用；在执行该副本之前，请将其与您的 可信安装版本进行比对。 检查点会对一条包含公钥、日志长度、头部 哈希值和创建时间的声明进行签名。验证者可以检查后续存档是否包含 相同的前缀。应将检查点保留在收集器之外，以便后续验证时将 存档与单独保存的参考值进行比对。 ## 验证范围 验证过程会检查存档文件及其生成所使用的采集模式。请选择 其信任边界与当前情况相匹配的模式，并保留该模式的验证输入。 | 采集模式 | 验证器检查的内容 | 验证输入与信任边界 | | --- | --- | --- | | 本地工作区 | 记录签名、哈希链、清单和附件字节 | 独立保留的收集器指纹；主机管理员控制本地签名密钥 | | 带独立见证节点的本地工作区 | 归档校验以及与见证人保留的早期日志前缀的一致性 | 独立受信任的见证密钥和记录；检查点将已观察到的前缀进行绑定 | | [GitHub Actions 捕获](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md) | GitHub 对存档摘要、已批准的工作流和收集器提交、托管运行器、新的会话/密钥来源以及内部存档完整性的认证 | 可信验证者策略、调用者存储库和 GitHub 证明包；数据采集在固定工作流下运行 | | [云部署](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/) | 提供商的生命周期和访问记录、防火墙和 Cloudflare 状态，以及收集器的签名运行记录 | 对服务提供商和 Cloudflare 进行只读查询；各项检查的可用性取决于服务提供商 | | [Intel TDX 机密虚拟机](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#confidential-vm-on-phala-cloud-intel-tdx) | 引用签名和平台状态，将其与收集器声明、组装及操作系统测量数据相关联 | Intel 信任链及预期部署指标；保留每次必需的 TDX 检查结果 | 在密封采集过程中，经批准的采集器通过经过身份验证的 Telegram 连接在已验证的环境内接收数据。证明将归档文件与 该执行过程绑定，因此验证既涵盖采集过程，也涵盖后续的文件完整性。 这依赖于经批准的代码以及上文列出的平台信任链。 GitHub 捕获验证要求在运行过程中创建会话，并拒绝 导入会话的捕获。 运行收据记录了收集器的版本、文件哈希值和启动设置。GitHub 来源信息和 TDX 测量结果用于环境验证； [验证记录](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/)标识了已测试的配置。 TgWitness会对收集到的观察结果进行签名；Telegram及消息作者不会生成 这些签名。在本地工作区中，首次独立 检查点之前创建的内容仍依赖于收集器及其密钥持有者。覆盖范围记录描述了 选定的范围和收集结果，而经过验证的外部时间戳则将 已提交的存档或日志边界锚定在特定时间点。 ## 附件 文件在 media/ 目录下通过 SHA-256 哈希值进行标识。media.saved 事件将哈希值和 字节长度与特定的消息事件相关联。原始文件名属于元数据，绝非本地 路径。 媒体数据以异步方式下载，因此立即删除可能导致 无法捕获。已禁用的采集、超大/未知大小的文件、下载失败 以及下载中断等结果均会显示。进程崩溃可能会留下 未被引用的部分文件；这些文件不会包含在导出数据中。 ZIP 导出工具会根据文件名对存储的媒体文件进行验证。JSONL、CSV 和 HTML 导出格式会验证事件签名，但不包含媒体文件数据。衍生报告 仅供参考；events.jsonl 才是权威的事件表示形式。 完整聊天导出会将工作区附件设置中的附件保存至 media/ 目录下，文件名格式为 SHA-256。 chat.json 中的每条消息记录都会标注其文件名称（`file`、 `file_sha256`）或缺失原因（`file_status`），并附带读者所看到的 文本周边内容：文本后面的链接、转发来源、机器人按钮、签名、查看次数以及 自动删除计时器。`verify.py` 会检查每个命名文件是否位于该哈希值对应的 签名清单中。 ## 持久的收集与处理收据 (0.2) 媒体任务及其消息事件提交在同一事务中完成。 该任务存储 原始 TL 消息描述符；签名的观测记录将其 SHA-256 值、账户 及大小策略进行绑定。恢复操作会在下载前验证该绑定。它绝不会获取 当前消息，也不会悄无声息地替换为更新版本的附件。中断的任务 会重试，而永久性失败则仍被视为明确的结果。 每个工作区都有自己的日志和签名身份。process.started 事件包含 运行 ID、本地时钟、依赖项版本、源文件哈希值、初始账户/作用域， 以及捕获设置。心跳消息包含运行 ID、单调时间和队列状态。 运行收据也可作为单独签名的声明下载。若要验证 执行环境，请将其与[验证范围](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#verification-scope)中所述的 GitHub 证明或 TDX 检查 结合使用。 系统会在启动时、观察过程中每五分钟（ **参数 → 每隔生成签名检查点**）以及有序停止时，在本地保留自动检查点。启动验证和导出操作会将日志 与最新保留的本地检查点进行比对。当检查点完好无损时，此机制可检测到数据库回滚 情况。独立的保留机制确保该参考信息在 工作区之外仍可获取；经过验证的外部时间戳则进一步将其锚定在特定时间点。 重启后，将恢复已保存的 Telegram 更新位置（`catch_up_from` 位于 `observation.started`），并请求获取遗漏的更新。定期重新检查会记录 `message.recovered` 以获取遗漏的消息，并在 Telegram 不再 返回已保存消息时记录 `message.missing_on_recheck`；后者并非删除通知，且未指明删除者或时间。 ### 异地备份与恢复（S3） 异地副本（“导出”，默认关闭）会将日志片段、保留文件、检查点 及其时间戳，以及已完成的聊天记录导出上传至兼容 S3 的存储空间，上传前使用 AES-256-GCM 加密，所用密钥存储于工作区保险库中；若存储桶支持，则应用 对象锁定保留机制。若未下载密钥，则无法读取备份内容。请使用 `python -m tgwitness.replica restore --key-file KEY.json --out DIR` 进行恢复和验证。 恢复操作需要一个空的普通目录。下载的文件和解密后的对象将保存在私有 临时存储中，直至整个日志及所有保留的检查点均通过验证。不安全的对象 路径、不一致的段范围以及长度短于检查点的日志将被拒绝；验证失败 时，系统不会发布任何恢复文件。 保留性检查会将返回的“对象锁定” 模式和日期与上传时发送的截止时间进行比对（允许一秒的四舍五入误差）。过期、 无效或被缩短的截止时间均不视为已验证。状态报告将显示该上传批次中 被读取保留状态的抽样对象。 缺失或损坏的本地媒体文件将作为当前迭代的错误报告，并保持媒体光标停留在 该文件之前，以便在下一次迭代中重新尝试处理该文件；其后的文件、检查点和导出内容仍将 被复制。恢复过程会 将所有已保存媒体的引用与解密后的哈希值及记录的大小进行比对。 来自中断上传的 相同重叠日志段将被去重；冲突的重叠部分将被拒绝。 上传过程中创建的检查点将推迟处理，直至其所涵盖的日志记录被 复制完毕，因此一个完成的处理阶段不会在日志之前发布检查点。 ### 流式导出快照 流式导出使用稳定的 SQLite 读取快照。当下载完成时，该快照的起始点可能早于 当前的实时日志。在此快照之后创建的检查点 可能会正确报告存档长度较短；请与位于导出前缀处或之前的检查点进行比较， 而非任意的后续检查点。 ## RFC 3161 准备与响应验证 (0.2) 证据模式（默认关闭）仅通过工作区路径（绝不通过 MTProxy）将每个签名检查点的 SHA-256 哈希值发送至列出的 RFC 3161 权威机构和 OpenTimestamps 日历。 响应结果保存在 `checkpoints/anchors/` 中，经 `verify.py` 导出并验证（`--tsa-ca` 负责 验证 TSA 签名；使用 `ots upgrade` 和 `ots verify` 确认 OpenTimestamps 证明）。 该面板会准备一个请求存档，其中包含规范的 checkpoint.json 字节数据、 SHA-256 消息指纹以及 timestamp.tsq 文件中的随机非ce值、校验和及操作说明。 此过程不会发起任何网络请求。该准备过程不构成可信时间戳。 `python -m tgwitness.anchor verify` 会调用 OpenSSL 的 ts 函数两次：一次针对检查点 字节，一次针对原始请求。必须显式指定受信任的 CA 文件； 内置证书不会被自动信任。在命令行界面（CLI）中，请求验证为可选操作， 因此请保留并提供 --request 参数以验证非ce。结果将表明 是否已进行验证。收集器的检查点签名和日志仍需 使用可信收集器指纹分别进行验证。 验证过程会检查响应签名、检查点字节，以及（若提供） 在指定 CA 信任下原始请求的有效性。证书吊销检查以及证书过期后的 长期归档验证不属于当前验证器的范围。 请参阅相关[流程和](https://phishdestroy.github.io/TgWitness/zh/docs/reference/timestamp/)[验证结果](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/)。 ## 证据模式下的可选记录：drand 和 Telegram 设备 还有两项记录功能可与时间戳在同一轮处理中运行。这两项功能默认均处于关闭状态， 且仅在证据模式开启时生效：[扩展] → [证据与备份] → [**更多见证人] · 可选**， 或 `"drand": true` 以及 `"devices": true` 在 `POST /api/evidence`中。其中一项失败不会阻止 另一项或时间戳的运行；面板会在表单下方显示每项的最新结果。 **drand** （`beacon.drand` ）。每次处理都会将最新一轮的 drand quicknet（即熵联盟的公共 随机数，每 3 秒一轮）写入日志：`chain` 、 `round` 、`randomness` 、`signature` 、`round_time` 以及响应的 `relay` 。一个经过验证的 不可预测的轮次为后续哈希链接的材料提供了较低的时间参考。 后续检查点上的经过验证的时间戳则提供时间上限。这些检查 界定了关联的数据范围；数据收集的覆盖范围则单独评估。收集器首先向 `drand.cloudflare.com` 发起请求，然后通过工作区路径向 Protocol Labs 的中继节点发起请求，每轮一次请求。 `verify.py` 会验证每个随机数是否为其签名的SHA-256 ，并检查轮次 时间是否正确，同时报告轮次数量、最长未生成轮次的间隔以及收集器时钟相对于 drand的延迟。 它不检查 BLS 签名。`--check-drand` 将轮次与 Cloudflare 中继、Protocol Labs 中继以及长日志中的全部轮次或随机 抽取的 100 个样本进行比对；若有任何轮次不一致，则验证失败。 **、Telegram、**（`account.devices`）设备。每次扫描都会读取该账户与 `account.getAuthorizations`的会话，即“设置”→“设备”中显示的Telegram列表，并完整记录： 若自上次处理以来发生变更，则完整记录，包含`added`和`removed`会话 哈希值；否则仅记录其数量及SHA-256。设备型号、平台、应用及版本、 创建时间和最后活动时间、国家和地区等信息将被保留；IP地址则不予保留，因为 证据导出后便不再由您掌控。 收集器自身的会话始终处于活动状态，因此 只有其他会话的活动才被视为变更。`verify.py` 报告列表 被记录的频率，以及每个新会话和已结束会话。它仅在观察运行期间读取该列表。 他们未展示的内容：drand 仅能证明记录相对于公共时间的顺序， 而设备列表是 Telegram 通过收集器提交的声明，由收集器签名， 与其他所有记录一样。 **Cloudflare Gateway 日志**（`cloudflare.gateway_dns`）。 对于通过 Cloudflare Gateway（[Gateway DNS](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#cloudflare-as-an-outside-witness)）进行解析的服务器，每次 复制都会包含自上次复制以来 Gateway 记录的内容：每个时间窗口（最长三 小时）对应一条记录，包含 `from`、`until`、`location_id`、服务器的 `address`（若已设置），以及 `queries`（作为 `[at, name, type, rcode, decision, colo]`，即使没有记录时也包含）。 请在 **下进行设置。Cloudflare Gateway日志**：账户、位置、可选地址以及一个只读令牌（账户 Analytics 读取；零信任 PII 读取，用于保留共享位置的一个地址）。控制面板会在保存前通过 一次请求验证这些信息；令牌始终保持加密状态，且绝不会进入日志。 `verify.py` 列出了时间窗口、被查询次数最多的名称以及任何未被副本覆盖的时间段；如果某条记录 的计数与其查询不匹配，则该记录将失败。 若某个时间窗口在单秒内包含超过一页的 查询，则保留该页内容，并标注其余部分缺失。该副本是 Cloudflare 通过收集器返回的响应，并由收集器签名；在 24 小时内，任何持有 只读令牌的用户均可将其与 Cloudflare 进行比对。 --- # Telegram · 独立见证者 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/ 运行一个带有独立密钥和机器人的 Witness 实例，将签名后的检查点发布到频道中，并据此验证导出数据。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 运行一个带有独立密钥和机器人的 Witness 实例，将签名后的检查点发布到频道中，并据此验证导出数据。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [证据与验证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/) ![证据与验证](https://phishdestroy.github.io/TgWitness/assets/chapter-evidence.svg) [导出与验证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/) · [高可信度](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/) · [面板指南](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/#extras) 见证者会将已签名的检查点与收集器分开保存。它会检查 收集器的签名和日志连续性，使用自己的密钥对结果进行签名，并 将其发布到 Telegram 频道。请在单独的服务器上运行该程序，并确保该服务器对 收集器的见证端点仅具有只读访问权限。 流程图 · 收集器 → 见证人 (签名检查点：记录条数 + 头部哈希值); 见证人 → Witness日志，自有密钥; 见证人 → Telegram 频道 (通过其自有机器人发布的签名帖子); 证据 ZIP → verify.py; Witness日志，自有密钥 → verify.py; Telegram 频道 → verify.py (Telegram 桌面版导出功能或 t.me/s 页面) · 收集器 · 见证人 · Witness日志，自有密钥 · Telegram 频道 · 证据 ZIP · verify.py · 签名检查点：记录条数 + · 头部哈希值 · 通过其自有机器人发布的签名帖 · 子 · Telegram 桌面版导出功能或 · t.me/s 页面 **图表转为文本** 1. 收集器 → 见证人 (签名检查点：记录条数 + 头部哈希值) 2. 见证人 → Witness日志，自有密钥 3. 见证人 → Telegram 频道 (通过其自有机器人发布的签名帖子) 4. 证据 ZIP → verify.py 5. Witness日志，自有密钥 → verify.py 6. Telegram 频道 → verify.py (Telegram 桌面版导出功能或 t.me/s 页面) **本页内容** - [见证者能获取的内容，以及无法获取的内容](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/#what-the-witness-gets-and-what-it-does-not) - [检查与记录的内容](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/#what-it-checks-and-records) - [运行见证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/#run-a-witness) - [多个工作区的公开证明页面](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/#public-proof-page-for-several-workspaces) - [验证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/#verify) ## TgWitness 能做什么，以及它不能做什么 | 该工具具有 | 该工具从未 | | --- | --- | | 一个工作区的只读**见证令牌** | 采集器的 Telegram 会话或 API 凭据 | | 其专属的 Ed25519 密钥和日志 | 采集器的存储库、签名密钥或面板令牌 | | 其专属的 Telegram 机器人令牌 | 消息内容：头部包含记录数量和哈希值 | 令牌在**扩展功能 → 独立见证人**中生成，仅显示一次，且仅以 SHA-256的形式存储。它会打开且仅打开一个端点， `GET /api/witness/head`该端点返回一个刚 签署的检查点，以及已签署的无内容集合计数器和运行状态。 它无法打开面板、读取消息内容或更改设置，且 该处不接受面板令牌。可在同一页面撤销令牌。收集器会记录 新见证密钥开始检查的时间（`witness.seen`) 并显示每个令牌的最后一次检查时间； 超过 2.5 个间隔仍未进行检查的见证人将被标记为逾期。 新见证节点在每次投票时都会发送一个随机挑战； 捕获语句会在收集器签名下方重复该挑战。计数器 与确切的检查点绑定，并包含在签名的见证帖中。旧版头部 仍被独立见证节点接受。仅日志增长本身绝不会被计为新消息。 ## 其检查和记录的内容 每隔一段时间（默认间隔为 10 分钟），该工具会： 1. 自行获取头部数据（收集器无法推送或跳过该数据）； 2. 验证收集器的签名、固定的收集器密钥（`--collector-fingerprint`， 或首个出现的密钥）、一个非递减计数，以及在未改变计数条件下未被修改的头部。 默克尔包含性证明和一致性证明用于验证不断增长的日志是否延伸了 保留的检查点。一旦连续性证明被使用，则拒绝移除它们； 3. 将其签名记录追加到自身的日志中：`witness.anchor`，状态为 `ok`、 `key_changed`、`rollback`（记录数少于之前）、`fork`（长度相同，但 头部不同）或 `invalid`（响应未通过验证），或者当 收集器未响应时为 `witness.no_response`； 4. 将结果发布到频道，并附带签名，包括“无响应”的情况——只要 TgWitness 正在运行且能够访问 Bot API。发布 ID 会被记录下来（`witness.posted`）， 发布失败的情况也会被记录（`witness.post_failed`）。 一条记录如下所示；最后一行包含经签名的声明： ``` TgWitness witness #42 · journal head Collector 3fa9c2d1e0b4a7f6: 18234 records Head 9b1f…c07e 2026-10-28T19:40:00.123+00:00 TGW1.eyJhdCI6…. ``` ## 运行 TgWitness 您需要一个 Telegram 机器人（可通过 @BotFather 创建），一个该机器人担任 管理员的频道，以及一个可从证人处访问的收集器地址——需通过 HTTPS 连接，且位于 私有网络之外（请参阅[部署](https://phishdestroy.github.io/TgWitness/zh/docs/reference/deployment/)部分中的 HTTPS 配置文件）。 在面板中打开**“扩展功能”→“独立见证人”→“配置”**。三个步骤涵盖 只读访问权限、您的频道和间隔时间，然后启动见证人。发布 策略、可选的 HTTP/SOCKS5 代理以及自定义机器人 API 地址位于**“高级设置**”中。该表单 会下载 `witness.json` 时，会附带此工作区的收集器密钥。通过“**将访问文件另存**为”下载新 创建的只读令牌 `witness-token.txt`；将其与在见证主机上 `bot-token.txt`在见证主机上生成的文件一同放置在该 JSON 文件旁边。收集器绝不会接收机器人令牌。 下载操作不会启动服务或发布消息。任何托管项目的见证都不会 被隐式注册。 ``` python -m tgwitness.witness run --config witness.json --check-config python -m tgwitness.witness run --config witness.json python -m tgwitness.witness fingerprint --config witness.json ``` 第一个命令在不进行网络请求或生成密钥的情况下检查配置文件和密钥文件。 JSON 中的路径相对于该文件；CLI/环境路径相对于 工作目录。 将见证指纹保留在其主机之外。收集器的 “最后轮询”指示器仅用于确认请求；发布情况由 Proof 报告，或通过 见证日志和频道进行核查。 如果控制面板位于 SSH 隧道之后，请仅通过 单独的 HTTPS 主机名（参考[此 Caddy 示例](https://github.com/phishdestroy/TgWitness/blob/main/deploy/Caddyfile.witness.example)）暴露范围限定后的见证端点。 此时，默认工作区使用 `https://witness.example.org`，其他工作区使用 `https://witness.example.org/profiles/ID`。仍需提供令牌；该虚拟主机不会转发控制面板及其 其他 API 路由。 选择 `all` 可获取定期发布的检查点。五分钟的间隔意味着每个工作区每天约有 288 条记录。`changes`/`problems` 会刻意不发布部分检查结果。 MTProxy 用于数据采集器的 Telegram 客户端。Witness HTTP 轮询和 Telegram 的 HTTPS Bot API 分别使用各自的直接/HTTP/SOCKS5 路由（[Bot API](https://core.telegram.org/bots/api)）。 **在收集器旁边，使用 Docker**（同一主机——独立进程和密钥，但 同一操作员）：将值填入 `.env` 并启动配置文件。 ``` TGWITNESS_WITNESS_TOKEN=tgww_... TGWITNESS_WITNESS_BOT_TOKEN=123456:ABC... TGWITNESS_WITNESS_CHANNEL=@your_witness_channel # another workspace: TGWITNESS_WITNESS_COLLECTOR=http://tgwitness:8787/profiles/ docker compose --profile witness up -d docker compose logs witness # prints the witness key fingerprint ``` 如需使用已发布的图片，请使用`docker compose --project-directory . -f deploy/compose/compose.image.yaml --profile witness up -d`。 **在他人服务器上**（一个真正的独立见证者）：将代码库复制到该处，将 `TGWITNESS_WITNESS_COLLECTOR=https://your-collector.example.org` 以及上述三个值 设置为 `.env`，然后 ``` docker compose --project-directory . -f deploy/compose/compose.witness.yaml up -d ``` 或不使用 Docker： ``` python -m tgwitness.witness run --collector https://your-collector.example.org \ --token-file witness-token.txt --bot-token-file bot-token.txt --channel @your_witness_channel ``` ### 发布到 Discord 见证人可以选择在 Discord 频道而非 Telegram 上发布内容。在 Discord 中，打开 **“编辑频道”→“集成”→“Webhook**”，创建一个 Webhook 并复制其 URL。在 配置面板中，第 2 步选择**“Discord Webhook · 您的频道**”。在见证人主机上， 将该 URL 保存为 `discord-webhook.txt` 旁边 `witness.json`；该数据绝不会到达 收集器。 ``` python -m tgwitness.witness run --collector https://your-collector.example.org \ --token-file witness-token.txt --discord-webhook-file discord-webhook.txt ``` 每个见证者仅有一个发布源：Telegram 频道或 Discord Webhook，二者不可兼得。帖子 均包含相同的签名声明，且无法@任何人。超过 Discord 2,000 个字符的帖子将被一行简短内容替代，并附带完整的校验码作为 `witness-check.txt`。每条帖子的 ID 记录为 `witness.posted`. `verify.py --channel`仅读取 Telegram 频道的导出数据，因此对于 Discord，请保留见证日志：其中包含 每张支票。 ### 选项 | 选项 | 环境 | 默认 | 含义 | | --- | --- | --- | --- | | `--interval` | `TGWITNESS_WITNESS_INTERVAL` | 10 | 检查间隔时间，1–1440 | | `--timeout` | `_TIMEOUT` | 30 | 等待采集器和机器人 API 的时间：5–600 秒 | | `--post` | `_POST` | `all` | `all`：每项检查；`changes`：新进展或新问题；`problems`：只有问题和未解答的疑问 | | `--title` | `_TITLE` | `TgWitness witness` | 每个频道帖子的开头语 | | `--collector-fingerprint` | `_COLLECTOR_FINGERPRINT` | – | 将收集器密钥固定，而非直接采信首个答案 | | `--proxy` | `_PROXY` | 直接 | `socks5://host:port` 或 `http://host:port` | | `--bot-api` | `_BOT_API` | `https://api.telegram.org` | 机器人 API 地址，例如本地机器人 API 服务器 | | `--data-dir` | `_DATA` | `witness-data` | Witness 密钥和日志 | | `--config` | `_CONFIG` | – | 包含上述任意选项的 JSON 文件 | 收集器地址、令牌和频道来自 `--collector`, `--token` 或 `--token-file`, `--bot-token` 或 `--bot-token-file`, `--discord-webhook-file` 以及 `--channel`， 或 `_COLLECTOR`, `_TOKEN`, `_TOKEN_FILE`, `_BOT_TOKEN`, `_BOT_TOKEN_FILE`, `_DISCORD_WEBHOOK_FILE` 以及 `_CHANNEL`，这可防止“secret”出现在进程列表中。 配置文件中，选项名称使用下划线分隔，并包含`texts`，该代码会替换频道帖子中的 文字： ``` {"collector": "https://your-collector.example.org", "token_file": "witness-token.txt", "bot_token_file": "bot-token.txt", "channel": "@your_witness_channel", "interval": 5, "timeout": 30, "post": "changes", "title": "Partner witness", "texts": {"ok": "journal head", "no_response": "no answer from the collector", "records": "records"}} ``` `texts`密钥：`ok`、`key_changed`、`rollback`、`fork`、`invalid`、`no_response`、`collector`、 `records`、`head`。命令行优先于环境变量，环境变量优先于配置文件。 未知选项或文本密钥会触发提示信息并停止记录，而非被忽略。 措辞绝不会影响验证：verify.py会在每次 发布结束时检查签名令牌。 在`--post changes`或`problems`中，未发布的检查仍保留在 见证日志中，而`verify.py`会将其列为“从未发布”；起始记录中注明了 策略名称。每项检查仍会出现在日志中，因此发布次数减少意味着独立的 Telegram发送次数减少，而非检查次数减少。 即使没有频道，Witness 仍会保留其日志。请将见证密钥指纹 (`python -m tgwitness.witness fingerprint`) 保存在其他地方。 ## 多个工作区的公开验证页面 `python -m tgwitness.proof` 该工具最多可同时管理 32 个工作区，并提供一个只读 页面，显示每个工作区的最新签名校验结果。每个工作区在 data 文件夹下都有独立的见证密钥和 日志，以及一个固定的收集器密钥；是否向 Telegram 频道 发布内容可由各工作区自行决定。请从 [proof.config.example](https://github.com/phishdestroy/TgWitness/blob/main/deploy/proof.config.example) 开始： | 字段 | 含义 | | --- | --- | | `title` | 页面标题，1–100 个字符 | | `data_dir` | 与文件相关的 Witness 密钥和日志；默认 `proof-data` | | `interval`, `timeout` | 检查间隔（分钟，1–1440，默认 5）；等待时间（秒，5–600，默认 20） | | `workspaces[].id`, `label` | 简短的小写别名和显示名称 | | `workspaces[].collector` | 收集器地址；其他工作区以 `/profiles/` | | `workspaces[].collector_fingerprint` | 必填项，每个工作区各不相同 | | `workspaces[].token_file` | 包含该工作区只读见证令牌的文件 | | `workspaces[].channel`, `bot_token_file` | 可选操作：将每次检查结果发布到频道中 | | `workspaces[].proxy`, `bot_api` | 可选路由和机器人 API 地址 | ``` python -m tgwitness.proof --config proof.json --check-config python -m tgwitness.proof --config proof.json --host 127.0.0.1 --port 8790 ``` 第一个命令会在不建立连接的情况下验证文件和令牌文件。 该页面仅响应 GET 和 HEAD 请求： - `/` 显示所有工作区；若某个工作区在 2.5 个时间间隔内未被检查，则会被标记为过期。 - `/api/proof` 返回的结果与 JSON 相同。 - `/api/proof/` 下载最新的签名声明（`tgwitness-public-proof-v1`)： 见证记录编号和哈希值、状态、固定的收集器密钥、检查点、收集 计数器以及频道发布是否成功，由该工作区的见证密钥签名。 - `/healthz` 当工作区的监控器停止运行时，会返回 503 错误。 为该页面设置独立的主机名，例如 [Caddyfile.proof.example](https://github.com/phishdestroy/TgWitness/blob/main/deploy/Caddyfile.proof.example)。为了验证，请导出 工作区的见证日志，并 `python -m tgwitness.witness export --data-dir proof-data/ --out witness.zip` ，并按 下文所述使用它。 ## 验证 在“证人”一侧，导出其日志： ``` python -m tgwitness.witness export --out witness.zip # Docker (add -f deploy/compose/compose.witness.yaml on a witness server): docker compose exec witness python -m tgwitness.witness export --out /witness/witness.zip docker compose cp witness:/witness/witness.zip . ``` 随后，无论身处何地，只需使用采集器生成的签名 ZIP 文件，以及从 Telegram Desktop 导出的频道（*“导出聊天记录* → JSON”生成的 `result.json` ）或其公共 `https://t.me/s/…` 页面： ``` python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \ --witness witness.zip --witness-fingerprint WITNESS_SHA256 --channel result.json ``` `verify.py`会检查见证日志（链和签名），然后验证**见证者 所见到的每个头部是否都包含在导出的日志中**：该计数处的记录必须具有完全 相同的哈希值。不匹配的头部将导致验证失败——这意味着日志在 见证者查看后被篡改了。 它还会报告导出后被见证的头部、见证人 记录的异常情况、验证失败的响应、导出中存在匹配检查点的 时间段（“从 X 见证至 Y”）以及缺失部分。后续检查点不会延长这些时间段。 结果包含最后一个匹配的记录编号以及后续 未找到匹配检查点的记录数量。仅计入由该导出本身密钥签署的回答：若导出 由见证人从未见过的密钥签署，则报告为未被见证；若未采用`--fingerprint`，其 签署者将保持未固定状态。 使用`--channel`时，每个已签名的帖子必须与见证日志 逐条匹配：已更改的帖子将验证失败，缺失的帖子将被列出。在 提供的Telegram JSON导出文件中，日期属于可编辑的元数据，不属于已签名的见证令牌范围。 匹配令牌并不意味着发布日期已通过认证；结果会明确 报告未执行发布时间验证。 ### 要求设置受见证的导出边界 若需进行必须包含经见证的最终记录的交接，请添加 `--require-witness`： ``` python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \ --witness witness.zip --witness-fingerprint WITNESS_SHA256 --require-witness ``` 这需要独立保留的见证指纹以及与之匹配的检查点， 且该检查点必须位于本次导出的确切末尾。仅覆盖较早前缀的检查点 是不够的。暂停采集，让见证方观察最终状态，并在 进一步写入日志之前进行导出；如果日志发生变化，请保留另一个检查点并 导出该状态。 仅凭后续检查点无法验证较短导出文件的最终哈希值。 当同时提供`--channel`标志时，若声明的帖子缺失或匹配集为空，将导致此 严格检查失败。若未使用该标志，普通完整性检查仍会报告未被见证的 记录，但不会因此拒绝一个除此之外完整的存档。 请将见证日志及其固定密钥分开保存。在线检查用于验证各检查点之间的连续性； 离线验证则将每个保留的检查点与 导出文件进行比对。没有连续性证明的旧版节点仍保留离线比对结果，并在 报告中不包含在线连续性验证结果。报告按时间间隔列出了见证器的停机时间及 发布失败情况。 ### 每日印章和不可用的时间戳日历 见证人将前一天（UTC）的日志边界进行封装，并将 该签名封装的哈希值提交至 OpenTimestamps。日历提交属于待确认证据； 只有经过独立核查的比特币承诺才能在验证器中获得确认。 如果所有日历均失败，签名印章和未成功的尝试将保留在 日志中。每小时的维护循环会重试该原始记录，包括 在重启或更改日期之后。它最多扫描 32 个印章，最多提交 两个缺失的提交，并且每次循环在重试上最多花费 60 秒。一个 持久光标会轮流处理较旧的印章。保留的提交遵循 现有的证明升级路径。 重试不会重写封印、更改其原始日期，也不会声称 日历系统更早收到该数据。较晚的比特币承诺仍被视为较晚的外部 确认。缺失的证明仍为`none`；待处理的证明仍为`pending`，直到 验证者独立检查它们为止。 --- # Telegram · 时间戳 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/timestamp/ 签名检查点采用 RFC 3161 时间戳：向认证机构发送的内容以及如何验证响应。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 签名检查点采用 RFC 3161 时间戳：向认证机构发送的内容以及如何验证响应。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [证据与验证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/) ![证据与验证](https://phishdestroy.github.io/TgWitness/assets/chapter-evidence.svg) TgWitness 会生成 RFC 3161 请求并验证时间戳授权机构（TSA）的响应。 此手动流程既不选择 TSA，也不提交数据；而证据模式会根据 预定时间表（[证据格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#rfc-3161-preparation-and-response-verification-02)）自动完成这两项操作。生成的请求本身 **尚不**构成 **时间戳证明**。 ## 证据的约束力 流程图 · 账户观察 → SHA-256 链和 Ed25519 签名; SHA-256 链和 Ed25519 签名 → 签名检查点; 签名检查点 → 精确字节哈希和随机非ce; 精确字节哈希和随机非ce → RFC 3161 请求; RFC 3161 请求 → 独立 TSA; 独立 TSA → 经 TSA 签名的回复; 签名检查点 → 验证数据、非ce值及明确的CA信任关系; 经 TSA 签名的回复 → 验证数据、非ce值及明确的CA信任关系 · 账户观察 · SHA-256 链和 Ed25519签名 · 签名检查点 · 精确字节哈希和随机非ce · RFC 3161 请求 · 独立 TSA · 经 TSA 签名的回复 · 验证数据、非ce值及明确的CA信任关系 **图表转为文本** 1. 账户观察 → SHA-256 链和 Ed25519 签名 2. SHA-256 链和 Ed25519 签名 → 签名检查点 3. 签名检查点 → 精确字节哈希和随机非ce 4. 精确字节哈希和随机非ce → RFC 3161 请求 5. RFC 3161 请求 → 独立 TSA 6. 独立 TSA → 经 TSA 签名的回复 7. 签名检查点 → 验证数据、非ce值及明确的CA信任关系 8. 经 TSA 签名的回复 → 验证数据、非ce值及明确的CA信任关系 采集器的签名将记录与其密钥绑定。一份可信的 TSA 响应可 证明某个检查点在 TSA 声明的时间点确实存在。该 检查点随后可将日志前缀与之绑定。但这并不能确定 每次 Telegram 操作的时间，也无法证明捕获内容的真实性。 ## 操作流程 1. 通过独立的可信通道保留采集器的密钥指纹。仅凭 被检查的 ZIP 文件提供的密钥不足以识别采集器。 2. 在**“导出”→“准备时间戳请求**”中，下载所选工作区的 请求 ZIP 文件。解压 `checkpoint.json`、`timestamp.tsq`、`SHA256SUMS` 和 `README.txt`。请勿更改检查点字节。 3. 选择适合该调查的 TSA。使用其 文档中记载的方法提交 `timestamp.tsq`，若为 HTTP 服务则使用 `application/timestamp-query`。 将原始二进制响应保存为 `timestamp.tsr`，并记录端点、检索时间 及请求结果。该请求包含哈希值和随机数而非消息内容； 网络元数据仍会暴露该请求。 4. 请独立于响应内容获取受信任的根证书，以及任何 所需的中间证书。响应中包含的证书并不仅因 被包含其中而自动成为受信任证书。 5. 通过可信的 TgWitness 安装实例，验证： ``` python -m tgwitness.anchor verify --checkpoint checkpoint.json --request timestamp.tsq --response timestamp.tsr --ca trusted-tsa-root.pem ``` 如有需要，请添加 `--intermediates tsa-intermediates.pem` 或 `--openssl /path/to/openssl`。 OpenSSL 必须支持 `ts`。在 Windows 系统上，验证器还会搜索标准的 Git 安装目录。OpenSSL 3.5.9 已使用合成 CA/TSA 进行了本地测试。 1. 在检查点之后导出带签名的日志 ZIP 文件，以便其中包含该前缀。 使用已知的独立指纹进行验证： ``` python tgwitness/verify.py evidence.zip --fingerprint TRUSTED_SHA256 --checkpoint checkpoint.json ``` 1. 将 ZIP 文件、检查点、请求、响应、证书链、验证 结果以及交接记录保存在收集器之外。在接收时重复验证。 从已保存的检查点准备请求： ``` python -m tgwitness.anchor prepare checkpoint.json --out timestamp-request.zip ``` 该准备过程会规范化 JSON 格式，并将匹配的检查点包含在归档文件中。 即使输入文件的空格格式不同，也请使用**该归档文件中的检查点字节**进行 TSA 验证。 ## 验证范围 | 检查 | 当前行为 | | --- | --- | | 数据 | 检查点字节的精确 SHA-256 值必须与响应结果一致 | | 请求 | 借助`--request`，可对原始查询和随机数进行验证 | | TSA 签名 | OpenSSL 会验证该签名及其与指定证书颁发机构（CA）的证书链。 | | 采集器签名 | 由日志验证器使用固定密钥进行独立验证 | | 撤销 | 不支持自动检索 OCSP/CRL | | 长期有效性 | 证书过期后不进行归档验证 | | 计划提交 | 证据模式，默认关闭 | `--request` 从技术上讲是可选的，但省略它将导致无法验证 原始随机数。对于此完整流程，结果中的 `request_checked` 必须为真。 证书验证遵循已安装 OpenSSL 的规则及验证时间。 长期保存需要单独的证书/撤销证据政策。 有效的加密签名并不自动等同于合格的时间戳，也不构成 法律上的可采纳性认定。如果操作员在 加盖时间戳之前伪造了记录，TSA 仅对这些字节进行锚定；并不能证明其真实性。 ## 交接记录 记录案件标识符、发送方和接收方、UTC传输时间及其来源、 目的、文件名/SHA-256值、收集器指纹、序列范围、已知 缺失部分、验证器版本及验证结果。 通过贵组织的流程对该 记录进行签名并独立保存。TgWitness中 未实现多用户保管记录系统。 开发过程中未联系任何独立的实时 TSA。本地测试会生成一个 合成 CA/TSA，用于检查兼容性，并验证对已修改数据、随机数或 CA 的拒绝情况。 --- # Telegram · 存储与恢复 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/storage/ 备份、将旧文件移至云端、Object Lock 下的副本以及在新设备上的恢复。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 备份、将旧文件移至云端、Object Lock 下的副本以及在新设备上的恢复。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [部署与恢复](https://phishdestroy.github.io/TgWitness/zh/docs/reference/deployment/) ![部署与恢复](https://phishdestroy.github.io/TgWitness/assets/chapter-operate.svg) 该面板将任务分为三类： | 任务 | 功能介绍 | | --- | --- | | 保留备份 | 将已签名的日志、检查点、已保存的文件和队列中的导出内容复制到配置好的 S3 目标位置。 | | 免费本地存储空间 | 将选定的旧附件复制到 S3 或 rclone 云远程存储中，完整读取这些附件，验证加密字节，然后删除已验证的本地副本。 | | 保留一份证据副本 | 配置 S3 Object Lock 并检查返回的保留状态。该服务必须确认请求的模式和日期。 | 释放空间时绝不会删除或覆盖已签名的日志。每个附件都会保留 其原始SHA-256以及一份恢复凭证。可选的 gzip 压缩会在 经过身份验证的加密之前进行。云端文件名不包含 Telegram 用户名、 聊天 ID 或原始附件名称。单个附件最大可达 32 GiB。 仅凭上传响应本身并不意味着可以删除文件。TgWitness会下载 完整的加密对象并验证其大小，SHA-256保存收据， 然后在删除前立即再次检查本地字节。如果上传失败、 回读结果不同或传输被取消，本地文件将保留原位。如果 已启用的证据备份尚未复制该文件，删除操作也会等待备份完成。 **本页内容** - [当磁盘空间即将用尽时](https://phishdestroy.github.io/TgWitness/zh/docs/reference/storage/#when-the-disk-is-filling-up) - [连接目标](https://phishdestroy.github.io/TgWitness/zh/docs/reference/storage/#connect-a-destination) - [保留恢复文件](https://phishdestroy.github.io/TgWitness/zh/docs/reference/storage/#keep-the-recovery-file) - [安装丢失后的恢复](https://phishdestroy.github.io/TgWitness/zh/docs/reference/storage/#recover-after-losing-the-installation) - [操作员机器人和操作提示](https://phishdestroy.github.io/TgWitness/zh/docs/reference/storage/#operator-bot-and-completion-notices) ## 磁盘空间即将耗尽时 当可用空间低于**参数 → 附件 → 可用磁盘空间**中的阈值（默认 1 GiB）时，附件下载会暂停并保留队列。文本观察继续进行。这不受通知设置影响：关闭通知不会关闭下载预留空间或存储保护措施。 若要更早介入，请启用**自动运行**，选择**删除本地文件以释放空间**，并启用**磁盘空间不足时额外执行一次转存**。此可选规则默认在可用空间低于 5120 MiB 时启动，分批处理直到可用空间达到 10240 MiB。两个阈值均可配置。它与手动执行使用相同的目标位置、文件最小存放时间、批量上限、完整回读验证和证据备份前提条件，不会自行启用目标位置。每 30 秒检查一次；发生错误或没有进展时，下次尝试推迟五分钟。规则状态和重试时间在重启后保留。规则未激活时，定时任务仍按正常间隔运行。 面板显示可用空间、打包预留空间、空间不足规则是否就绪，以及因临时空间不足而跳过的文件。打包和恢复在开始前检查临时空间峰值需求，并在写入过程中检查可用空间。预留量使用下载设置，但存储操作至少保留 64 MiB。这些检查不是文件系统配额；其他进程仍可能在两次检查之间消耗空间。 Gzip 对远程对象进行无损压缩，不会缩小活动日志，也不会创建本地归档。JPEG、视频和 ZIP 可能几乎不缩小，甚至略微增大。启用压缩时，当前打包流程可能临时需要约两倍附件大小的空间，再加上预留量。请为最大的文件选择足够早的启动阈值。无法打包的过大文件会被保留并报告；较小文件和已验证的远程副本仍可帮助释放空间。已有验证通过的副本时，无需再次创建本地打包文件即可移除本地文件。恢复同样需要临时空间，空间不足时可能被拒绝。 没有符合条件的可移动文件或未配置目标位置时，TgWitness 无法自动回收空间。存储管理绝不会裁剪或重写签名日志。新的文本观察仍需要磁盘空间。 ## 连接目标 **在“附加功能”→“存储与磁盘空间”→“管理存储”中**，选择任务和目标位置， 保存后，选择**“测试上传与下载**”。该测试会上传一个随机的微小探测数据并将其 读回。此过程不会使用 Telegram 内容。 对于 S3，请使用服务提供商的实际端点、区域和存储桶。Wasabi、Backblaze、 Cloudflare R2 及其他兼容服务均使用相同的 S3 设置。仅具备兼容 API 并不意味着支持 Object Lock。治理模式可能允许 授权管理员绕过保留策略；合规模式则有不同的 限制。在依赖保留策略之前，请先阅读返回的 Object Lock 状态。 对于 rclone 目标，请使用 rclone 的提供商设置创建一个远程，并将 该远程的 `[name]` 部分粘贴到面板中。已安装的辅助程序支持 MEGA、Google Drive、OneDrive、Dropbox、Box、pCloud 以及 选择器中显示的其他提供商。凭据保存在该工作区的加密保险库中。OAuth 刷新信息也会保存回保险库。凭据不会添加到日志 事件中，也不会包含在恢复下载中。 该辅助工具安装在工作区内部，包含一个固定版本和 SHA-256。 它不会被添加到系统 PATH 中。配置文件和工作文件是 该工作区内的临时文件。基于命令行和本地文件的远程连接将被 拒绝。rclone 目前要求为 外部请求显式选择 **直接** 路由。请使用原生 S3 存储作为工作区的 SOCKS5 或 HTTP 路由； rclone 不会在路由不可用时静默绕过。 ## 请妥善保存恢复文件 请选择“复制文件后**保存恢复文件**”，并将该文件保存在 与安装目录分开的位置。该文件包含解密密钥和已签名的对象 收据，因此请将其视为私钥备份。请将原始远程配置 和目标凭据也分别单独保存。在后续复制操作之前 生成的恢复文件不包含该后续文件的收据。 签名密钥的指纹应已独立记录。仅通过 与同一文件内提供的密钥进行比对的签名，无法确定该 恢复文件属于谁。 若要修复现有工作区中缺失的存储收据，请打开**“从已保存的恢复文件中恢复文件**”， 并选择该文件。该面板会验证签名，并要求使用相同的工作区 签名密钥。若存储密钥不同，系统将拒绝替换。随后选择**“恢复 所有文件**”。恢复过程会暂停自动存储规则，以确保下一次计划的 处理不会立即再次删除已恢复的文件。当 本地副本处理完毕后，请重新启用该规则。 恢复操作会验证密文、认证解密过程、在 必要时进行解压，并检查原始明文SHA-256，然后将文件放入 `media/`。 损坏的远程对象绝不会替换本地文件。若现有本地文件的 字节内容不同，则会保留该文件以供审查，而非被覆盖。 ## 安装丢失后的恢复方法 在另一台机器上安装 TgWitness。使用私有恢复文件、单独 记录的指纹以及原始目标凭据： ``` python -m tgwitness.storage recover \ --recovery storage-recovery.json \ --fingerprint TRUSTED_WORKSPACE_SHA256 \ --credentials original-rclone.conf \ --output recovered-attachments ``` 对于 S3， `--credentials` 指向一个包含 `access_key` 和 `secret_key`；已签名的恢复文件提供目标设置。 该命令使用直接外部连接，并在 rclone 远程需要时下载固定的辅助程序 。它拒绝使用现有的输出目录。 恢复的原始字节将写入 `recovered-attachments/media/`，文件名由 其SHA-256决定。 `recovery-log.jsonl` 是一个关于恢复操作的未签名记录。 该命令不会重建丢失的已签名日志或其签名密钥。请保留 完整的工作区备份以备不时之需。存储恢复文件并非完整的工作区 备份。 ## 操作员机器人和完成通知 该 Telegram 机器人归操作员所有。请通过 BotFather 创建该机器人，并在控制面板中设置其 令牌、目标聊天室以及明确允许的 Telegram 用户 ID。 发件人和聊天室必须一致。转发消息以及来自其他 机器人的命令将被忽略。 `/status` 并且 `/stats` 可在默认的“仅状态”模式下使用。可选的 控制模式还增加了 `/pause`, `/resume` 和 `/copy`. `/copy` 并请求已配置的 存储任务；这并不意味着远程上传已经完成。命令 不能提供任意的 URL、文件或 shell 程序。 请分别设置提醒和任务完成的通知。完成 通知会区分存在缺失的账户导出与完整的导出，并显示 历史记录和存储数量。除非在通知设置中单独 启用，否则不会包含消息摘录。服务选择器是根据实际 安装的 Apprise 目录生成的，而非一组固定的提供商示例。 --- # Telegram · 安全与数据处理 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/security/ 威胁模型、访问模型、静态机密、网络暴露、会话导入以及如何报告漏洞。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 威胁模型、访问模型、静态机密、网络暴露、会话导入以及如何报告漏洞。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [部署与恢复](https://phishdestroy.github.io/TgWitness/zh/docs/reference/deployment/) ![部署与恢复](https://phishdestroy.github.io/TgWitness/assets/chapter-operate.svg) 本页描述了在本地或服务器工作区中的访问、存储和网络保护机制。 若需在 GitHub Runner 或 Intel TDX 保密虚拟机中进行数据采集，请参阅 [验证模式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#verification-scope)，该模式会增加对采集环境的检查。 账户连接、通知、时间戳、异地副本和见证人各有其独立的路由设置。 | 领域 | 简而言之 | | --- | --- | | 访问 | 管理员密钥加上对账户/聊天的范围限定访问权限，包含七项权限及可撤销的会话；默认使用 localhost | | 静态数据中的秘密 | 会话、API 对、签名密钥和代理设置均采用 Fernet 算法进行加密 | | 消息和媒体文件 | 数据以明文形式存储：请使用磁盘加密并设置严格的权限 | | 完整性 | 每条记录均带有 SHA-256 哈希链和 Ed25519 签名 | | 本地信任边界 | 主机管理员控制工作区及其签名密钥；独立检查点保留了较早的日志边界 | 有关漏洞报告，请参阅[安全政策](https://github.com/phishdestroy/TgWitness/blob/main/.github/SECURITY.md)。 **本页内容** - [访问模型](https://phishdestroy.github.io/TgWitness/zh/docs/reference/security/#access-model) - [面板内容与导出](https://phishdestroy.github.io/TgWitness/zh/docs/reference/security/#panel-content-and-exports) - [静态机密](https://phishdestroy.github.io/TgWitness/zh/docs/reference/security/#secrets-at-rest) - [代理和网络路由](https://phishdestroy.github.io/TgWitness/zh/docs/reference/security/#proxies-and-network-routes) - [登录与会话导入](https://phishdestroy.github.io/TgWitness/zh/docs/reference/security/#sign-in-and-session-imports) - [日志与传输](https://phishdestroy.github.io/TgWitness/zh/docs/reference/security/#logs-and-transport) - [完整性限制](https://phishdestroy.github.io/TgWitness/zh/docs/reference/security/#integrity-limits) - [如果您怀疑存在问题](https://phishdestroy.github.io/TgWitness/zh/docs/reference/security/#if-you-suspect-a-problem) ## 访问模式 主面板令牌授予完全控制权。其他用户可获得各自的 [范围限定访问权限](https://phishdestroy.github.io/TgWitness/zh/docs/reference/access/)：指定的工作区和聊天群组、权限、有效期、 IP 限制、登录限制以及可撤销的会话。仅限聊天群组的访问权限 即使勾选了相关权限，也无法执行整个工作区的操作。 工作区共享同一进程，其数据不会与主机管理员的数据隔离。 该面板默认监听 localhost。通过浏览器登录会将访问 令牌兑换为会话凭证；浏览器将其作为承载令牌发送。该凭证存储 在 sessionStorage 中，而非身份验证 Cookie 中。锁定/注销会清除 浏览器会话。关闭浏览器或结束会话不会停止数据收集。 已签发的令牌和会话凭据以哈希值的形式保存在加密保险库中。 撤销操作将终止相关会话；权限变更将影响后续 请求。已下载的文件无法被召回。管理员也可以限制其 自身的浏览器会话，但直接使用主面板令牌的脚本仍可保留 完全访问权限，并绕过这些浏览器会话限制。 身份验证失败将根据客户端地址进行速率限制。IP 限制基于 应用程序所识别的地址；在依赖该机制之前，请先检查 反向代理的行为。Witness 凭据仍为独立的只读检查点/健康状态凭据。 ### 演示访问 `/api/demo-access` 是一个经过刻意设计的、无需身份验证的引导程序，用于明确 启动的、隔离的合成演示。它仅颁发一个独立于进程生命周期的权限， 绝不会颁发真实的面板令牌或 TGWITNESS_TOKEN 覆盖令牌。 其签发和使用需要 一个回环对等方和主机，不允许转发标头，也不允许跨源请求。额外的 工作区或授权会话将禁用此路径。实时工作区绝不会签发 该权限。该演示无法关联账户或更改收集设置。 ## 面板内容与导出功能 该面板不使用任何外部字体、分析工具、CDN资源或嵌入的远程媒体。 来自Telegram的文本以纯文本形式插入，而非HTML格式。下载的附件以 二进制附件形式提供。JSONL导出保留原始字符串；HTML导出则对 这些字符串进行转义；可能包含公式的CSV单元格会在前面添加一个撇号。 导出文件不包含身份验证和签名密钥，但会刻意保留 收集到的源元数据、标识符，以及可能包含的个人或敏感内容。 原始源元数据中可能包含 Telegram 访问哈希值和文件引用。 ## 静态数据中的秘密 Telegram API 凭据、会话密钥和签名密钥均采用 Fernet 算法进行加密。 对于本地消息和媒体文件，加密由主机磁盘或卷提供； 工作区用于存储普通文件。导出文件可采用密码保护的 AES-256 ZIP 格式， 异地副本则采用 AES-256-GCM 加密。 保险库密钥默认位于受保护的数据目录中。请使用下方的外部主密钥文件 将其单独存储。在 Unix 系统上，新的私钥文件使用权限模式 0600，新的数据 目录使用 0700；在 Windows 系统上，请为服务账户和 授权管理员设置目录访问控制列表 (ACL)。现有目录权限将予以保留。 ### 外部主密钥 对于新的数据目录，TGWITNESS_VAULT_KEY_FILE 可提供外部随机 主密钥。HKDF-SHA256 结合独立的随机盐值，为每个工作区生成不同的 Fernet 密钥 。为确保恢复功能，必须保留 vault.external.json 文件。若主密钥缺失或 错误，将导致操作失败。现有本地保险库不会被自动迁移。 该面板显示所选的密钥存储模式。无论采用哪种模式，磁盘加密都会保护本地 消息和媒体文件；有关设置的详细信息，请参阅 [连接和数据保护](https://phishdestroy.github.io/TgWitness/zh/docs/reference/connection/)。 ## 代理服务器与网络路由 代理配置在保险库中经过加密存储。密码和 MTProxy 密钥 不会通过 API 返回，也不会写入证据记录。每个工作区可自行选择 Telegram 路由和 [IP 模式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/connection/#ip-modes)。 **“隐藏地址”模式会**拒绝直接使用 Telegram 备用连接，并要求通过代理处理外部 HTTP 请求。“显式选择的备用模式”允许在延迟后直接访问 Telegram； “隧道/VPN 模式”则允许直接连接。选择“隧道” 模式不会安装或验证 VPN。这些设置不会控制所有设备 流量、浏览器、软件包管理器或本地代理主机的 DNS 解析。 MTProxy 仅传输 Telegram 流量。外部请求可使用独立的 SOCKS5/HTTP 代理、工作区的 SOCKS5/HTTP 路由，或允许的直连路由； 也可将其禁用。独立见证器拥有自己的传输设置。 普通 SOCKS5/HTTP CONNECT 身份验证不会由这些代理 协议本身进行加密。伪 TLS MTProxy 密钥目前仍不支持。 ## 登录与会话导入 转换后的 .tgwitness-session 文件在 加载并存储到保险库之前，其中包含明文授权密钥。离线命令行界面支持经过审核的 Telethon 模式。 面板导入功能还支持 Pyrogram SQLite、现代单账户 TData ZIP 以及文档中记载的 JSON 输入格式。该功能需经过身份验证，限制为 4 个文件 / 8 MiB， 并在内存中处理上传内容，无需解压归档或保存原始文件。 规范化的凭据仅返回给请求的已认证浏览器； 在 Telegram 授权成功后，这些凭据将保存在加密保险库中。 请保护原始文件和转换后的文件，并避免多个客户端同时克隆同一授权。 数据处理过程会验证容器校验和、本地解密哈希值以及结构 长度。系统会临时使用用户提供的 Desktop 本地密码，且不会将其存储。 此有限解析器无法保证所有 Desktop 版本均兼容。 QR 图像在本地生成，包含短效的 Telegram 登录令牌，且 绝不会发送至外部渲染服务。锁屏、切换工作区、新登录 以及路由变更都会取消待处理的 QR 尝试。刷新或关闭标签页可能会导致 尝试处于待处理状态直至过期。成功的 QR 登录仍会强制执行账户绑定。 普通 API 请求主体仍限制为 16 KiB；经过身份验证的导入路径接受 最多 12 MiB 的编码 JSON，并单独执行较小的解码文件大小限制。 登录码和 Telegram 两步验证密码不会被持久化存储。手机号码/验证码哈希状态在 授权过程中仅保存在内存中。Telegram 会话授予账户访问权限；切勿 将数据目录、会话、令牌、保险库密钥或私有签名密钥上传至 GitHub。 ## 日志与传输 默认的 API 验证响应已被替换，因此不会回显凭据 值。应用程序访问日志功能已禁用。请勿配置反向代理 以记录 Authorization 头或请求正文。HTTP 以明文形式传输令牌和登录 密钥：只要连接离开 localhost，请务必使用 HTTPS 或 SSH 隧道。 ## 完整性限制 本地验证会检查记录签名、哈希链、附件和导出清单。 管理员持有本地签名密钥，并可创建另一份已签名的日志； 独立保存的检查点可检测其所覆盖的前缀是否被替换。 请将密钥指纹和检查点交由接收方或独立见证人保管。 如需经过独立核查的采集，请选择 [GitHub Actions 捕获](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md) 或 [Intel TDX 部署](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/#confidential-vm-on-phala-cloud-intel-tdx)。 其验证器除检查归档完整性外，还会核查工作流溯源或硬件测量数据。 可选的时间戳和加密的异地副本可提供时间锚点和可恢复的副本； [证据格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/#verification-scope)描述了每种模式下的验证流程。 ## 如果您怀疑存在问题 保留原始数据目录，并使用单独的副本进行分析。 通过 [安全政策](https://github.com/phishdestroy/TgWitness/blob/main/.github/SECURITY.md)报告受影响的版本、操作及可重现步骤，同时确保账户数据和凭据的私密性。 --- # 架构 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/architecture/ 收集器、控制面板、日志、工作进程和见证程序的组成部分，以及数据在它们之间如何流动。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 收集器、控制面板、日志、工作进程和见证程序的组成部分，以及数据在它们之间如何流动。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) ![开发](https://phishdestroy.github.io/TgWitness/assets/chapter-develop.svg) 一个 Python 进程托管 FastAPI 控制面板和任意数量的隔离工作区， 每个工作区都配有一个 Telethon 用户账户客户端。 SQLite 存储着一个仅支持追加的、经过签名的事件日志以及可变的操作设置。 加密保险库中存储着 API 凭据、StringSession 以及签名密钥。 前端采用打包的纯 HTML/CSS/JavaScript 形式：无需 Node 构建、CDN 或运行时 前端下载。 Optional browser and AyuGram recorders run in **separate processes or containers**. The `tgwitness_capture` package owns their event format, keys, artifacts, checkpoint API, independent witness and standalone verifier. It is bundled in the main wheel and can also be installed alone from `addons/capture`, without importing the collector. The main panel's `capture_api.py` and `capture_connections.py` provide administrator-only, workspace-scoped controls under `/api/capture`; connection tokens live in the encrypted vault. No recorder or outbound request starts with the main process. Each explicit command verifies a fresh challenge against the pinned recorder key. Exports are verified before download and keep their original signature; they do not become Telegram message events. Collection sessions and proxy routes stay with each client. See the English [Independent capture guide](https://github.com/phishdestroy/TgWitness/blob/main/docs/OPTIONAL-CAPTURE.md) for deployment and trust boundaries. | 模块 | 责任声明 | | --- | --- | | collector.py | 授权、对话选择、更新、快照、媒体队列、连接监控 | | interactions.py / telegram_client.py | 明确的面板操作、带签名的收据、持久的请求 ID 以及针对特定任务的回调/加入重试策略 | | message_content.py | 可视化消息对比，不包含传输访问元数据 | | workers.py | 在取消操作前，请等待导出文件处理程序完成 | | distributed_export.py / distributed_pages.py | 并发聊天任务、按账户预留、签名检查点以及归档验证后的清理工作 | | distributed_takeout.py / export_timing.py | 可恢复的 Takeout 会话以及每次开始或恢复的时长 | | store.py | WAL 事务、有序事件链、查询过滤器、运行设置 | | fulltext.py | 衍生全文索引（词形变体、BM25），与签名日志头关联；绝不导出 | | security.py | 私有文件的创建、加密存储库、Ed25519 签名、单进程锁定 | | evidence.py | 完整日志导出、衍生日志、检查点、附件验证 | | verify.py | 独立的只读验证器（标准库 + 加密技术）：存档、覆盖范围、证据日志和频道帖子、个人资料文件 | | app.py | 经过身份验证的 API、生命周期、请求验证、静态面板 | | profiles.py | 多账户收集器、共享访问控制器、按工作区管理的生命周期 | | access.py | 范围限定授权、权限检查、IP 限制、会话限制及管理员控制台 | | proxy_catalog.py | 公共信息流快照、传输检查、共享代理池及基于健康状况的筛选 | | provenance.py | 带签名的获取运行身份、代码及依赖项测量 | | network.py | 按工作区验证的传输路径；状态和证据的遮蔽处理；Telethon 传输选项 | | sessions.py | 对已审核的 Telethon SQLite 模式进行离线只读转换 | | account_import.py | 对受支持的账户文件和 JSON 进行内存检测和标准化处理 | | tdata.py | 功能有限的现代 TData ZIP 读取器，支持校验和/解密验证，不进行文件提取 | | doctor.py | 无需数据收集、登录或安装软件包的本地就绪性检查 | | download.py | 经过身份验证的流式导出下载，支持限定读取且不会覆盖原有数据 | | monitoring.py | 经过验证的按工作区设置的事件策略和按类型设置的附件规则，由处理程序共享，并附带状态和签名收据 | | scope.py | 监控范围（指定聊天、Telegram文件夹、整个账户）、数据源类型、排除项、复核层级 | | dossier.py | 基于保存记录构建的每条聊天中的用户档案：包含记录引用的事实信息、头像的 SHA-256/pHash 值，以及提及内容提取 | | witness_api.py | 只读见证令牌及其可获取的签名日志头 | | witness.py | 独立见证流程：自有密钥和日志、头部校验、带签名的频道帖子、导出 | | alerts.py | Apprise 通知及面板的通知列表 | | logging_config.py | 无窗口启动时的控制台日志记录和轮换式服务器诊断 | | static/ | 响应式界面、本地访问门、过滤器、详细信息、导出功能、账户设置 | | demo.py | 明确标注为合成日志，与实际采集数据隔离 | 观察处理程序在连接前即已注册。实时采集受以下因素控制： 活跃客户端身份、显式运行状态、已启用的数据源或观察 范围（文件夹或整个账户模式会在首次更新时将新聊天添加为数据源），以及事件 策略。被拒绝或被替换的客户端无法提供实时更新。 原始反应和成员资格更新 均遵循可见性限制。传入消息内容及其持久化媒体任务将 一并提交。任务保留原始时间线描述符，并将该描述符的哈希值绑定至 已签名的消息观察记录。发送者/编辑者/删除者的语义相互独立。 每个工作区仅支持一个账户，并拥有独立的目录和签名身份。 主工作区出于兼容性考虑仍位于根目录下；其他工作区位于 profiles// 目录中。一个承载令牌控制整个安装环境；工作区并非 独立的授权租户。 进程锁保护目录；数据库锁 对事件插入进行序列化。每次追加操作均以FULL同步模式 同步提交至SQLite WAL。事件更新/删除触发器可防止 普通应用程序进行编辑；文件系统管理员始终处于信任边界之内。 API 授权采用承载者令牌（bearer token）机制。登录操作经过序列化处理，且受时间限制。 账户上传采用专用的 12 MiB 编码正文限制和 8 MiB 解码文件 限制；普通 API 请求仍保留 16 KiB 的限制。 转换在工作 线程中运行，将上传数据保存在内存中，并向经过身份验证的 浏览器返回规范化的输入。QR 登录具有每个工作区的候选码、短效标识符、等待任务 以及显式取消机制。只有被接受的授权才会成为活动客户端。 Telegram FloodWait 返回时包含 Retry-After 值；凭据和原始 RPC 错误消息不会在 API 错误中暴露。 日志导出在异步 事件循环之外运行，并按工作区进行序列化。它们在持续进行 WAL 写入的同时， 流式传输一个稳定的读取快照。聊天数据采集任务可在 不同账户上并行运行；每个账户在任务停止前始终处于预留状态。已暂停或 失败的任务将保留其检查点。成功完成归档验证后，可清理 其工作文件，仅保留 ZIP 文件、签名计划和状态信息。工作区收集器 共享同一进程/事件循环。 当前的历史快照与实时更新可能存在重叠。两者均为独立的观察记录， 并按来源进行标注；重复内容不会被自动合并。系统不会根据缺失的 ID、伪造的已删除文本、强制成员枚举或自动加入群组 等情况进行推断。 有关面向操作人员的说明，请参阅[“数据采集原理”](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/) 以及[“账户与会话格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/)”。 网络配置存储在加密保险库中。应用路由会关闭旧的 客户端并取消未完成的登录；后续连接将使用该路由，且不 提供直接的备用方案。 新的外部密钥安装会通过 HKDF-SHA256，基于主密钥文件和存储的随机盐值，为每个工作区生成 Fernet 密钥。这将 密钥与数据目录分开保护，而非将日志/媒体内容以明文形式存储。 本地演示入口使用单独生成的进程权限，绝不使用已配置的 面板令牌。签发和接受需明确启用演示模式，使用不包含额外工作区或授权会话的合成根 节点，采用环回对等方/主机，且不包含代理 转发头，也不进行跨源浏览器请求。 正式版 API 保留承载者 身份验证，并在演示模式下拒绝收集更改。 --- # 已测试的内容 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/ Telegram 实时测试、自动化检查、浏览器检查以及尚未经过验证的内容。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) Translation coverage: this edition includes material from the English original. Telegram 实时测试、自动化检查、浏览器检查以及尚未经过验证的内容。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [证据与验证](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/) ![证据与验证](https://phishdestroy.github.io/TgWitness/assets/chapter-evidence.svg) **更新 6 11月 2026.** 结果与每次运行所记录的修订版本、环境和 工作负载相关联。 [当前功能](https://github.com/phishdestroy/TgWitness/blob/main/docs/STATUS.md) 描述了 可用的工作流；本页面记录了实际已检查的内容。 [性能图表](https://phishdestroy.github.io/TgWitness/docs/validation/) · [经签名的英文审核报告](https://github.com/phishdestroy/TgWitness/blob/main/website/validation/audit/REPORT.md) · [可下载的测量数据](https://github.com/phishdestroy/TgWitness/blob/main/website/validation/audit/MEASUREMENTS.csv) | 最新证据 | 结果 | 范围 | | --- | --- | --- | | 版本审计 · 11月6日 | 1,461个核心测试通过；37个平台测试跳过 | 源代码 `92e539af40d8`；保留已公开的调查结果 | | 最新导出 · 11月6日 | 127.713 和 141.781 条记录/秒，完整周期 | 每台服务器限两个账户；文本和元数据通过 WARP 传输 | | 保留的存档 · 11月6日 | 48个归档文件；已验证3,598,381条记录 | 已根据固定工作区密钥对现有存档进行了核对 | | Trusted Live · 11月5日 | 受保护的 CPU 记录和 WARP 检查 | 官方桌面版登录和原生导出功能仍未实现 | | Phala / Intel TDX · 11 月 4 日 | 后续运行中通过了所有16项验证器检查 | 历史部署；CVM 上没有 Telegram 账户 | **本页内容** - [版本审核与最新导出 · 6年11月2026日](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/#release-audit-and-fresh-exports--6-november-2026) - [Trusted Live CPU Ubuntu 和 WARP · 5年11月2026日](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/#trusted-live-cpu-ubuntu-and-warp--5-november-2026) - [Phala Cloud 实时部署 · 4年11月2026日](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/#live-phala-cloud-deployment--4-november-2026) - [实时服务器日志清单 · 1年11月2026日](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/#live-server-journal-inventory--1-november-2026) - [最近的离线和故障注入检查 · 1年11月2026日](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/#recent-offline-and-fault-injection-checks--1-november-2026) - [Telegram 实时测试，完整账户 · 29年10月2026日](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/#live-telegram-test-whole-account--29-october-2026) - [使用 libarchive 打开的受密码保护的导出文件 · 29年10月2026日](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/#password-protected-export-opened-with-libarchive--29-october-2026) - [Telegram 实时测试 · 2026年10月27日至29日](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/#live-telegram-test--27-to-29-october-2026) - [合成本地容量测量](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/#synthetic-local-capacity-measurement) - [对一百万条消息进行全文搜索 · 5年11月2026日](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/#full-text-search-on-one-million-messages--5-november-2026) - [剩余说明](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/#remaining-qualification) ## 版本审核与最新导出 · 6年11月2026日 本次审计基于源代码 v0.9.1 `92e539af40d8368d198ff5e040f1d876f2c1310e`，发布版本 `92e539af40d8-83e41104669e`。三个 服务器上的已安装包烟雾测试均通过。签名报告保留了当时观察到的状态。 [![两项新工作负载的采集率和完全导出率](https://phishdestroy.github.io/TgWitness/assets/performance.svg)](https://phishdestroy.github.io/TgWitness/docs/validation/) | 工作量 | 记录 | 获取 | 完整周期 | 完整周期率 | | --- | --- | --- | --- | --- | | 服务器 A · 两个账户 | 27,030 | 189.043秒 | 211.647秒 | 127.713条记录/秒 | | 服务器 B · 两个账户 | 29,299 | 182.513秒 | 206.650秒 | 141.781条记录/秒 | 两次导出均未启用续传功能，排除了附件和头像，且最终 未产生任何重复或重复使用的记录。完整周期包括准备、 采集、筛选、打包和归档验证。服务器 A 还执行了 受保护聊天读取检查。服务器 A 上发生了四次 FloodWait 事件，服务器 B 上发生了三次， 均被正确处理。这些观察结果并不构成普遍的吞吐量保证。 | 检查 | 结果 | 资格要求 | | --- | --- | --- | | 核心 pytest | 1,461 条通过 | 37个平台跳过 | | 浏览器 / 浏览器用户体验 / 证据 / 网站 | 102 / 66 / 15 / 9 通过 | 这些程序与其他测试存在重叠；计数结果不可相加 | | Capture 插件 | 124 条通过 | 三项官方网页验证因必需的 Chromium 沙箱而被阻止 | | API 授权 | 269条路由；538个请求通过 | 凭证缺失和访问权限被撤销 | | 保留的存档 | 48/48 已验证 | 3,598,381条记录；已固定的工作区密钥 | | 实时车队读取检查 | 40 个配置文件中有 24 个通过验证 | 16条WARP路由未通过资格认证；这些配置文件未建立连接 | 该[签名报告](https://github.com/phishdestroy/TgWitness/blob/main/website/validation/audit/REPORT.md)记录了所有已公开的 发现结果，包括未发布秘密聊天快照中的三个缺陷，这些缺陷 在经过审计的主构建版本中并不存在。先前的 [公开历史](https://github.com/phishdestroy/TgWitness/blob/main/docs/EXPORT-BENCHMARK-2026-11-06.md)验证使用了不同的 版本和工作负载；其比率不得与本次比较结果合并。 使用 [固定密钥和验证器](https://github.com/phishdestroy/TgWitness/blob/main/website/validation/audit/README.md#verify-the-original-files)验证原始报告。 其签名可防止操作员的报告被篡改。但这并非 独立认证、Telegram 作者身份证明或 GDPR 认证。 ## Trusted Live CPU Ubuntu 和 WARP · 5年11月2026日 保留的集成运行使用了一个仅基于 CPU 的 Ubuntu 24.04.5 客户机（4 个 vCPU，8 GiB） ，该客户机在 RunPod CPU 主机内的 QEMU 环境中运行。收集器使用 `14e642a5`；验证使用 `02072461`。最终的修复程序合并到 [PR #114](https://github.com/phishdestroy/TgWitness/pull/114) 中，提交 ID 为 `755f78f6`，其代码树与测试的 PR 头一致。这并非 TEE 环境。 - 一个真实的 WARP 连接器报告状态正常；代理的 HTTPS 报告 WARP 和网关 已启用。三个探针观察到相同的出站地址，这并不保证是固定 IP。 - 断开 WARP 连接导致代理请求失败。直接连接网关服务的 HTTPS 请求被拒绝。在记录器命名空间中，直接的 IPv4/IPv6 连接、外部 DNS 以及 Docker 的嵌入式 UDP 解析器均被阻止。 - 一个具有范围限制的只读提供商令牌可以读取健康状态/连接信息，但无法 读取连接器注册令牌。已签名的提供商观察结果中包含 明确标记为不可用的样本。由于该见证程序运行在运营商的主机上，因此这 证明了记录和保留功能，而非独立的第三方托管。 - 官方桌面版已进入未认证的欢迎界面。在捕获过程中，受保护的键盘 输入被拒绝。解码了三个 H.264 显示片段，并 检查了其时钟叠加层。对包含 18 个事件的预检存档进行了验证， 验证依据为固定的记录器密钥和保留的检查点。 - 最终的捕获测试在 Windows 和 Linux 持续集成（CI）环境中通过了 114 个用真实 Chromium/FFmpeg 实现的测试用例。五项基准测试和依赖项建议检查均通过。 初始配置的 2 个 vCPU/4 GiB 环境在并发构建镜像的负载下超时， 并通过防护机制停止运行；此情况不计为成功。手动测试账户 登录、原生聊天记录导出、真实混合模式对比以及 Telegram 端注销操作仍 待完成。未导入任何提供的 Telethon 会话。附件、自动 OCR、 本地 drand BLS 验证以及 Trusted Live TDX 认证均未通过验证。 ## Phala Cloud 实时部署 · 2026年11月4日 **历史结果：**后续部署通过了全部16项验证器检查， 包括英特尔 TDX 和快速隧道。重启证据、签名地址 发现以及报告时间戳均进行了单独检查。每个测试 CVM 在 运行结束后均被移除。 | 设置 | 记录值 | | --- | --- | | 提供商 | Phala Cloud · `tdx.small` · US-WEST-1 | | 部署 | `--provider phala --quick-tunnel`；初始工作区为空 | | 初始收集器 | `df7d860c` · v0.8.1 | | 包含所有修复程序的收集器 | `53a0f7e9` | | 生产环境访客 | `dstack-0.5.12`；SSH 访问已禁用 | | 外部服务 | ntfy.sh、GitHub 和 Intel PCS | | 观测到的成本 | 七个 CVM，总计约1.9美分；历史测试定价 | 以下序列分别列出了初始故障、修复情况和已完成的检查。 这些 CVM 未连接任何 Telegram 账户。 **部署 1–2 · 提供商差异与回归测试** The first two deployments found five differences from the simulated Phala Cloud. Private Phala regressions reproduce each difference and fail without its fix: | 在 Phala Cloud 上 | 修复之前 | 修复 | | --- | --- | --- | | 必须提供 `compose_file.name` | HTTP 422，未创建任何内容 | Docker Compose 配置中包含 CVM 的名称 | | 除非指定为空，否则 Phala 会向被测的 app-compose 中添加其自身的预启动脚本（v0.0.20：Docker 登录、`docker compose pull`、root 密码、来自 `user_config` 的 SSH 密钥） | `tdx_compose` 失败：代码超出已发布的 Docker Compose 配置范围 | app-compose 将 `pre_launch_script` 设置为 `""`；Phala 随后将其省略 | | 若未指定 `image`，Phala 将选择 `dstack-dev-0.5.12`（开发版），该版本已启用 SSH 访问 | `server_state` 失败。该镜像仅硬件认证记录通过；仅提供商记录和 `tdx_os` 显示了该信息 | 部署过程要求使用 Phala 当前版本（`dstack-0.5.12`）的生产构建版本 | | 当 dstack 网关关闭时，CVM 详细信息中从未出现 `instance_id` | 部署等待 30 分钟后失败 | 实例 ID 读取自 CVM 状态 | | 重启、停止和启动属于 CVM 操作，而非应用程序修订 | `provider_actions` 未列出重启记录 | 这些操作也包含读取操作 | **部署3 · 认证、访问检查和重启证据** - 该 CVM 在关闭 SSH 访问的情况下运行了 `dstack-0.5.12`。收集器在创建后约 1.5 分钟发布了其签名地址。随后部署通过了 `tdx_binding`、`tdx_quote`（Intel TCB UpToDate、硬件认证记录 v4、FMSPC `20a06f000000`，非调试模式，不可迁移，支持从英特尔获取的加密验证数据 ），`tdx_compose_hash`、`tdx_compose`（字节级比对）以及 `tdx_identity`（KMS 密钥）。 - 访问 trycloudflare.com 地址的控制面板在未提供令牌或提供错误令牌时返回 401 状态码， 而使用控制面板令牌时返回 200 状态码。 - `verify`，其中 `--source` 指向 GitHub 上的该提交存档，且指纹已单独通过： 服务器、`server_state`、防火墙（无网关，无公共端点）、提供商日志、 账单、指纹、源哈希、启动以及五项 `tdx_*` 检查均通过。 Cloudflare 和 `tdx_os` 不可用，因此结果为“不完整”。 - 通过 Phala 的 API 进行了两次重启：每次 CVM 都在两分钟内恢复运行，使用 相同的收集器密钥，生成新的签名地址，而旧地址则返回 530 状态码。`verify` 将 此次新启动及两次重启均报告为 REVIEW。 通过 `--evidence`，它确认了日志 签名以及三次启动，每次启动均带有来自同一 CVM 的独立 Intel TDX 硬件认证记录。 - `destroy` 仅删除了该 CVM。随后工作区变为空，且控制面板地址停止 响应。 - 控制面板向导的价格查询显示 `tdx.small` 的价格为每小时 0.058 美元。若 API 密钥错误，则会显示简单的 “未接受该 API 密钥”提示信息。 **后续修复 · 签名地址发现与操作系统测量** - Without the address key, `verify` followed the newest well-formed post on the address topic, which is printed in the published compose. One forged post sent it to a host that does not exist, and `statement` failed: a forger could not pass as the collector, but could block third-party verification, for up to 12 hours with a forged future timestamp. The collector now also posts its address signed with its own key, `verify` accepts only such posts when the collector makes them, and posts are ordered by ntfy.sh's receive time. A private cloud-wizard regression replays the forged posts. A CVM runs this only from a commit that contains it, so this run's collector did not sign its address yet and `verify` said so. - `tdx_os` 原先依赖 `dstack-mr`，而该工具当前版本提供的是 `measure-os`，并非文档中提到的 `measure --json`。验证器现在会根据已发布的镜像和虚拟机配置（包括 ACPI 表）自行计算 MRTD 和 RTMR0-2。 **部署4 · 所有16项检查、报告封条及重新启动验证** - 部署过程曾一次下载已发布的 `dstack-0.5.12`，将其与 CVM 报告的操作系统镜像哈希值进行比对，而 `tdx_os` 通过验证：MRTD、RTMR0、RTMR1 和 RTMR2 均与针对 QEMU 8.2.2、1 个 vCPU 和 2 GiB 环境下计算出的值。同样的计算在宣称的 4 GiB、2 个 vCPU、 QEMU 9.2.1 或第二张网卡的情况下，得出的 RTMR0 值不同；而在内核、固件或命令行发生变更 以及使用开发镜像时，则会失败。 - `verify` 通过了全部 16 项检查（包括快速隧道的连接器），因此结果 为“通过”。 它生成 HTML 和 PDF 证书，并使用签名和时间戳进行数字加封，其中包含来自 比利时政府时间戳单元 TSU 202301（已列入比利时可信 列表）的合格 eIDAS 时间戳、FreeTSA 时间戳以及验证者的签名；`check-report` 确认了所有这些 内容以及 PDF 文件的签名。 - 重启后，`verify --evidence` 确认了两次启动，每次都伴随着在 CVM 内部生成的硬件认证，且每次 均从已发布的 `dstack-0.5.12` 启动；重启和新启动均处于 REVIEW 状态。 - `destroy` 使工作区保持为空。 **部署5 · 由收集器签名的发现机制与伪造帖子的拒绝机制** 收集器从提交`53a0f7e9`开始运行，该提交包含了上述修复内容。 - 收集器在其地址旁发布了使用自身密钥签名的地址，紧邻操作员的 HMAC 帖子。 随后，该主题中被添加了两条伪造的帖子，一条 HMAC 值为零，另一条由另一个 Ed25519 密钥签名，两者均声称时间在 2096 年。 `verify` 采用了由 收集器密钥签名的地址，并通过了全部 16 项验证；该印章再次包含经认证的比利时时间戳、 FreeTSA 的时间戳以及验证者的签名，而 `check-report` 对此予以确认。 - 重启后，收集器发布了经签名的全新地址：`verify` 立即检测到该地址， 运营商 **通过 HMAC 发布在 27 秒后检测到当前地址**，两者均忽略了 伪造的发布。`verify --evidence` 确认有两个实例从 `dstack-0.5.12` 启动。 - 部署过程显示了 Phala 对 CVM 的计费金额（含磁盘费用）：每小时 0.06078 美元。 ### 面板向导和剩余范围 面板向导在 Phala Cloud 上运行了两次，一次通过其任务 API，一次通过 基于真实 Chromium 内核的浏览器：价格核查、在 **Advanced** 下提交创建，全部六项 认证检查均通过，服务器列表显示了计费价格（每月 44.37 美元）， **Find 当前地址**、下载已测量的 Docker Compose 配置以及删除操作。浏览器未出现任何页面错误。 此后，工作区每次均处于空状态。 未涵盖内容：Phala 上的一个 Cloudflare 域名、CVM 上的一个 Telegram 账户，以及 `dstack-0.6.1` 镜像。创建前的向导价格仅为 Phala 的计算价格，因为其 API 仅列出了现有 CVM 的磁盘 价格；服务器列表显示的是创建后的计费价格。 本节中的所有价格均于 4 年 2026 月 4 日观察到。 ## 实时服务器日志清单 · 1年11月2026日 大约在协调世界时（UTC）19:15，通过顺序只读 SQLite `query_only` 查询统计了 运行中服务器上十个工作区数据库中的事件数量。在查询期间， 数据收集仍在继续，因此这并非跨工作区的原子快照。 | 在十个工作区数据库中观察到 | 计数 | | --- | --- | | 包含至少一个`message.new`事件的工作区 | 8 | | 日志记录，包括操作事件 | 1,610,818 | | `message.new`事件 | 900,232 | | `message.edited`事件 | 80,683 | | `message.deleted`事件 | 400,536 | | `message.recovered`事件 | 53,403 | | `message.snapshot`事件 | 2,183 | | `media.saved`事件 | 50,418 | | `media.failed`事件 | 5,575 | | `coverage.gap`事件 | 11 | | 数据库字节数（不包括 WAL 文件和媒体文件） | 7,909,003,264 | 这些是 **事件计数**，而非唯一的消息、用户或媒体文件。同一 条消息可能出现在多个工作区中，且编辑或删除操作可能会产生 另一个日志事件。 `media.failed` 统计的是历史故障事件，而非 当前的媒体队列。这些查询 **不** 重新验证签名以及所有 记录的完整 1,610,818 记录，未测量投递情况或吞吐量，也未证实 每个 Telegram 事件均已被捕获。此处未发布任何消息内容、账户或聊天 ID、 工作区标签、凭据或私有文件。 在本次审查中，单独配置的公共监控器覆盖了三个数据源： 其中一个捕获响应状态为OK，另外两个报告为`no_response`。该监控器 并非十个工作区的健康状况汇总。`no_response`表示观察者无法 在该次检查中获得响应；这并不意味着消息丢失。下文所述的 10月29日规模较小的测试拥有其自身的明确签名和哈希链验证。 ## 最近的离线和故障注入检查 · 1年11月2026日 这些检查使用的是虚构数据和本地文件；它们为 当前源文件提供了回归证据，而非针对其他实时 Telegram 投递测量的证据： | 检查 | 测试内容 | | --- | --- | | Source archive | 两个源字节完全相同但文件时间已更改的构建版本，生成了相同的 ZIP 文件和校验和。压缩包的精确字节数和文件哈希值完全匹配；私有测试文件未被包含。模拟的写入失败操作并未影响之前的压缩包和校验和。 | | Account export recovery | 第二个 ZIP 成员上模拟的磁盘错误未留下任何已发布或部分的 ZIP 文件。恢复操作保持了每个签名收据的字节级一致性，使用预期的签名指纹生成了一个可独立验证的存档，并将合成的覆盖缺口作为部分结果保留下来。随着历史记录的增长，可扩展性断言可防止重复扫描任务和收据。 | | Minimized disclosure privacy | 在所有三种身份识别模式下，以及在文本缺失的情况下，均对合成 Unicode 名称和别名、嵌套元数据、未知发件人和媒体字段进行了检查。掩码限制失败并未悄然削弱信息遮蔽效果；原始的已签名账户导出文件保持不变。 | | Linux media decoder and OCR | 在提交`5a9e0814`时，[Linux Docker CI 检查](https://github.com/phishdestroy/TgWitness/actions/runs/41341200341/job/124951395192)通过了以下测试：生成 Ogg/Opus、MP3、M4A、带视频的 MP4、WAV 和 FLAC 输入文件；伪造时长和二级文件引用控制；以及 48 个变异解析器测试用例（34 个被拒绝，14 个在范围内解码成功）。真实的 Tesseract OCR 在原始字节不变的情况下运行。解码器和 OCR 在网络隔离的容器中运行，未使用 Whisper 模型。 | 这些检查在[拉取请求和](https://github.com/phishdestroy/TgWitness/blob/main/.github/workflows/pr-check.yml) [完整检查](https://github.com/phishdestroy/TgWitness/blob/main/.github/workflows/checks.yml)工作流中运行。 它们测试的是这些故障边界，而非所有可能的存储故障，也并非测试 信息披露是否自动安全可发布。媒体检查不衡量 语音识别准确率或 Telegram 消息送达情况。分享前请审查每个衍生内容。 ## Telegram 实时测试，完整账户 · 2026年10月29日 在以下测试结束后，该账户仍继续运行。10月29日12:10（UTC），其监控范围 被切换为整个账户（频道、群组、私人聊天和机器人）；控制面板要求 确认，经签名的日志记录了这一操作。截至17:59（UTC），日志中包含： | 记录时间：10月27日 21:36 至 10月29日 17:59（UTC） | 计数 | | --- | --- | | 日志记录 | 9,968 | | 新消息 | 5,308 | | 在切换到完整账户后，其中的一部分 | 3,878 | | 删除操作 | 784 | | 其中部分消息在 TgWitness 保存后被删除 | 596 | | 编辑 | 41 | | 经复核后添加的消息 | 2,273 | | 经重新核查已无法找到的消息 | 18 | | 通过历史快照保存的消息 | 242 | | 已保存的附件 | 247 | | 收集器启动 | 19 | | Telegram FloodWait 暂停 | 26 | - 该小组的**“Verify”**核查确认了全部 9,968 条记录的签名和哈希链。 - 消息来自 2 个群组或频道以及 3 个私人聊天和机器人。在**“聊天”界面**中点击了一个消息按钮； 该请求及 Telegram 的响应均记录在日志中。 - 当收集器在重启后重新扫描该账户时，新增了聊天记录。由于 保存新聊天记录中早期消息的功能处于关闭状态（`history = 0`），因此本文不作讨论。 未涵盖内容：互动反应、成员变动、用户资料、发送消息、通过 邀请加入、代理服务器、通知、witness 机器人以及同时管理多个账户。公开文件 仅包含计数数据。 ## 通过 libarchive 打开受密码保护的导出文件 · 2026年10月29日 由导出加密代码生成的归档文件（WinZip AES-256 格式，7-Zip 和 WinRAR 均可读取）使用 Windows 版 `tar`（bsdtar 3.6.2，libarchive）打开。 输入正确密码后， 解压后的文件与原始文件的 SHA-256 值一致；输入错误密码时，系统会显示“密码短语错误” 并拒绝解压。7-Zip 和 WinRAR 本身并未被调用。 ## Telegram 实时测试 · 2026年10月27日至29日 一个真实的 Telegram 账户通过内置的 API 密钥对池登录，记录了 一个超级群组从 **10 月 27 日 21:36 UTC 至 10 月 29 日 05:15 UTC** 期间的活动。在此期间， 采集器共启动了 12 次。 | 已记录 | 计数 | | --- | --- | | 日志记录，包括心跳信息和服务记录 | 2,385 | | 新消息 | 1,291 | | 删除操作 | 472 | | 其中部分消息在 TgWitness 保存文本后被删除 | 347 | | 编辑 | 12 | | 暂停期间遗漏的消息，经重新检查后已补充 | 12 | | 已保存的附件 | 17 | | 未下载附件（下载功能已关闭，或无文件可下载） | 14 | | Telegram FloodWait 在重新检查期间会暂停，每次暂停 3 秒 | 8 | - 所有 2,385 条记录的签名和哈希链均可通过日志的 公钥进行验证。 - 重启后，收集器将从保存的更新状态（`pts`）继续运行，Telethon 会进行补全；随后，重新检查会添加仍缺失的消息。 - 在每次 FloodWait 事件中，收集器都会等待指定时间，然后继续运行。 - 该账户保持登录状态，同一会话于 10 月 29 日重新连接。 本次测试未涵盖的内容包括：同时管理多个账户、管理员权限、代理服务器、 持续数小时以上的服务中断以及完整的[实时验收流程](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/LIVE_ACCEPTANCE.md)。 公开文件仅包含以下统计数据：不包含任何账户或聊天标识符、消息内容或 凭据信息。 ## 合成本地能力测量 Private synthetic capacity run: 10,000 events across 100 chats. | 指标 | 已观察到 | | --- | --- | | 输入 | 来自 100 个精选合成来源的 10,000 条合成消息事件 | | 消息正文 | 400个字符；不含媒体或网络内容 | | 数据采集 | 53.273 秒；187.7 次事件/秒 | | 处理程序延迟 | p50 4.162 毫秒；p95 7.784 毫秒；最大值 129.118 毫秒 | | ZIP 导出 | 启用 tracemalloc 后耗时 19.868 秒 | | Python 导出分配的峰值追踪 | 0.51 MiB；不处理 RSS | | ZIP 文件大小 | 4,610,962 字节 | | 独立验证 | 所有 10,000 条事件均已通过验证 | 此工具测量的是该 Windows 主机上的本地序列化记录/导出路径。它 不测量 MTProto 传输、并发账户、Telegram 流量限制、媒体文件、 长期运行的工作负载，也不保证实际聊天数量。该测量结果早于 最终版离线时间戳工具的发布，而该工具不会改变所测量的消息路径。 ## 对一百万条消息进行全文搜索 · 2026年11月5日 命令： `python tools/bench_fulltext.py --messages 1000000 --work ` A deterministic signed journal of 1,000,000 synthetic messages in 200 chats (Russian word forms, Ukrainian, English, Chinese, Japanese, links and handles) was indexed in 71 seconds; the index took 58 MiB beside a 1.50 GiB journal. Best-match searches took 9 to 190 ms (median), against 2.4 to 3.2 seconds for the previous substring search. Full results, hardware and limits: [Full-text search](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/#benchmark). Private compatibility tests also verify a frozen signed archive made before full-text search with the current verifier, and a current archive with the frozen archive's own `verify.py`. ## 剩余资格要求 该保留的实时日志记录了实际的收集、编辑、删除通知、附件、 复核以及速率限制处理。 它并不记录详尽的送达情况，也不记录受控的 角色可见性矩阵、响应方、长时间的 FloodWait、账号封禁以及 网络/进程中断恢复情况。QR 令牌的发放与已完成的 移动端 QR 确认仍属不同流程。 Docker/Compose 及安装检查已记录在 CI 中；真实的 Phala 部署 和外部时间戳验证已在上文描述。这些并未建立 持续的高负载、完整的实时平台/角色矩阵、独立的安全 审查、长期归档验证或取证认证。已实现 MTProto 状态 保存和补发功能；原子无损实时重放功能尚未建立。 较新的回填功能可原子性地提交消息和游标，并保留可用的 近期操作，但其合成覆盖范围与实时资格认证有所不同。 有关受控资格认证矩阵，请参阅[实时验收](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/LIVE_ACCEPTANCE.md)部分。 [公开审计目录](https://github.com/phishdestroy/TgWitness/blob/main/website/validation/audit/README.md)仅包含 已签名的报告和汇总测量数据。详细的操作记录、 原始截图和账户资料仍属私有。位于 `docs/assets/` 中的应用程序截图使用的是虚构的演示数据。 --- # 许可协议与架构不兼容声明 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/license/ TgWitness 采用 MIT 许可证向所有人开放，并解释了其架构为何与 Taylor Wessing 的工作流程不兼容。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) TgWitness 采用 MIT 许可证向所有人开放，并解释了其架构为何与 Taylor Wessing 的工作流程不兼容。 TgWitness 根据 [MIT 许可协议](https://phishdestroy.github.io/TgWitness/LICENSE)发布。我们的立场不附加任何许可条件。 > 签名并不能将谎言变成事实。 > > > > 对于那些认为在名字前加上“Dr.”就能使后文内容成为事实的企业、律师事务所或个人而言，TgWitness并不适合。头衔、信头和签名不能凌驾于证据之上。 > > > > 如果您的工作流程是从客户已付费的结论开始，并要求记录必须遵循该结论，那么您需要的是另一种工具。TgWitness的存在是为了保存记录并使其可供审查。 > > > > 让那些“博士”们去打理他们企业客户的资产负债表吧。头衔无法治愈谎言。 > > > > 数学不讲情面。 [源记录](https://phishdestroy.io/steam_dossier/taylor_wessing) · [道德声明与历史延续性](https://phishdestroy.github.io/TgWitness/zh/docs/reference/notice/) [完整的 MIT 许可协议](https://phishdestroy.github.io/TgWitness/LICENSE) · [项目](https://github.com/phishdestroy/TgWitness/blob/main/README.md) · [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [维基](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Home.md) --- # 运营商兼容性通知 Canonical page: https://phishdestroy.github.io/TgWitness/zh/docs/reference/notice/ 关于 Taylor Wessing 及其来源记录的操作员通告。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 关于 Taylor Wessing 及其来源记录的操作员通告。 **PhishDestroy · TgWitness 项目公告** [源记录](https://phishdestroy.io/steam_dossier/taylor_wessing) · [原始声明](https://phishdestroy.github.io/TgWitness/NOTICE) ## ⚖️ 道德声明与历史延续性 我们最近了解到，对于某些律师事务所——特别是托比亚斯·谢林斯基博士和帕特里克·文森特·祖尔海德博士——而言，数学和客观事实毫无意义。 将GDPR不合规行为作为商业服务推销给企业，而自身却连基本的数据处理都做不到，这并非法律专业知识。 抱有“你就是法律”的妄想，或者认为伪造索赔单上某个精英的签名能神奇地将谎言变成真相，都无法掩盖技术上的无能。 该工具不适用于以下情况占主导地位的司法管辖区： - 企业统治 - 私有化或商业化司法 - 金权政治 - 盗贼统治与制度性腐败 特别提及帕特里克·祖尔海德博士、托比亚斯·谢林斯基博士，以及那些试图将“被遗忘权”武器化，以掩盖自身数据处理失误、粉饰机构血统并抹去历史记录的人士： > 泰勒·韦辛（Dr. Tobias Schelinski & Dr. Patrick Vincent Zurheide）→ 韦辛与贝伦贝格-戈斯勒 → 斯通沃尔百强 → 格拉夫·冯·德·戈尔茨博士 韦辛与合伙人 （自 1957 年起）→ 吕迪格·冯·德·戈尔茨伯爵 → 1935 年修订版的第 175 条 为严格遵守MIT许可证，我们不对本软件的使用设置限制。但需明确：企业预付金、法律恐吓及数字删除要求，均无法抹去历史、篡改溯源或掩盖真相。 [MIT 许可协议](https://phishdestroy.github.io/TgWitness/LICENSE) · [我们对 Taylor Wessing 的立场](https://phishdestroy.github.io/TgWitness/zh/docs/reference/license/) · [证据模型](https://phishdestroy.github.io/TgWitness/zh/docs/reference/how-it-works/) [项目](https://github.com/phishdestroy/TgWitness/blob/main/README.md) · [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [维基](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Home.md) --- # TgWitness Changelog & Release Notes Canonical page: https://phishdestroy.github.io/TgWitness/docs/reference/changelog/ Read TgWitness changes by version, including unreleased work. Check release notes before assuming a source feature is included in an installed package. [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/llms.txt) Translation coverage: this edition includes material from the English original. 按版本列出的所有变更，包括尚未发布的变更。 [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Project reference](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) ![Project reference](https://phishdestroy.github.io/TgWitness/assets/chapter-project.svg) **On this page** - [Unreleased](https://phishdestroy.github.io/TgWitness/zh/docs/reference/changelog/#unreleased) - [0.9.1 preview · 5 November 2026](https://phishdestroy.github.io/TgWitness/zh/docs/reference/changelog/#091-preview--5-november-2026) - [0.9.0 preview · 4 November 2026](https://phishdestroy.github.io/TgWitness/zh/docs/reference/changelog/#090-preview--4-november-2026) - [0.8.1 preview · 2 November 2026](https://phishdestroy.github.io/TgWitness/zh/docs/reference/changelog/#081-preview--2-november-2026) - [0.8.0 preview · 2 November 2026](https://phishdestroy.github.io/TgWitness/zh/docs/reference/changelog/#080-preview--2-november-2026) - [0.7.1 preview · 1 November 2026](https://phishdestroy.github.io/TgWitness/zh/docs/reference/changelog/#071-preview--1-november-2026) - [0.7.0 preview · 31 October 2026](https://phishdestroy.github.io/TgWitness/zh/docs/reference/changelog/#070-preview--31-october-2026) - [0.6.1 · 27 October 2026](https://phishdestroy.github.io/TgWitness/zh/docs/reference/changelog/#061--27-october-2026) - [0.6.0 · 27 October 2026](https://phishdestroy.github.io/TgWitness/zh/docs/reference/changelog/#060--27-october-2026) - [0.5.1 · 27 October 2026](https://phishdestroy.github.io/TgWitness/zh/docs/reference/changelog/#051--27-october-2026) - [0.5.0 · 26 October 2026](https://phishdestroy.github.io/TgWitness/zh/docs/reference/changelog/#050--26-october-2026) ## Unreleased - Isolate request-body capacity and token-family lockouts, set Secure download cookies behind trusted HTTPS proxies, limit pending tickets per access, and expose journal write failures. - Add an English Secret Chat demo with fictional requests, replies, attachments and retained deletion notices. Document the separate development implementation and its open defects; the demo does not enable Telegram connections. - Remove the unused one-shot exporter and check recovery against the current exporter. Reject unexpected or repeated message IDs in recheck responses. - Combine concurrent exports with resumable Standard API and Takeout acquisition. Each job retains its own progress, timings and signed checkpoints; accounts remain reserved until that job stops. Include the account controls, batch import and report-verification updates in the same build. - Add offline `VERIFY.cmd` / `VERIFY.sh` launchers, plain-language verification explanations and saved UTF-8 transcripts to signed exports in all 25 panel languages. Build a separate Windows verifier with an embedded runtime and a language menu. Unpinned signers remain unconfirmed; successful integrity verification does not establish admissibility. - Add optional jurisdiction guidance for 25 countries to Report Studio and exported assessments, with separate civil/criminal sources, local-language summaries and next steps derived from the actual package. Guidance remains a research draft, does not raise assurance, and is excluded from reusable layout profiles and inherited sharing-copy settings. - Allow the pinned Russian morphology dictionary resources in Windows portable builds while continuing to reject unrecognized files in dependency data directories. - Keep missing-on-recheck observations separate from deletion notices in HTML, JSON and PDF counts and viewer labels. Do not claim unscoped deletion IDs were never saved when their chat is outside the current observation scope. - Record multiple deleted IDs as a deletion batch without inferring a whole-history clear, the deleting participant, or deletion for everyone. Relabel legacy history-clear events without changing their signed records. - Publish the one-command installer only after application and security checks pass for the exact main commit and the signed package passes Ubuntu local/HTTPS service and Windows PowerShell acceptance. Keep the previous download when checks fail or time out. Add authenticated tests of the actual public installer URLs. - Preserve `previous_hash` in the signed-record preview even when its hexadecimal digits resemble a payment card number. Secret masking still applies to message content; the stored record is unchanged. - Reconstruct compact chat snapshots consistently in MCP, retain unknown fields, and distinguish capped lists from removals. Resume date scans, preserve topic names across history reads, and bound image previews. Apply metric choices to filtered reports and count historical service messages separately. - Plan sealed exports against the remaining session time, offer smaller selections, update progress estimates and reserve time for packaging. - Compare every message field, validate record counts and structure, enforce CLI verification options, and display OpenTimestamps states separately. - Close coverage on worker failure, bind heartbeats to the capture run, and verify TDX signing-key binding and supported component statuses. - Add read-only MCP tools (preview): `get_messages_by_date` (one calendar day in a named time zone, computed server-side), `get_pinned_messages`, `get_chat_stats` with `gap_summary`, `get_topics`, and `get_media`, which returns a verified, downscaled image preview anchored to its SHA-256 and `media.saved` record. Every MCP tool now declares an output schema. New connections include these tools; existing connections keep the tools they were issued with. - Show each account's selected route and checked exit address, group session controls, and retain interface preferences when adding an account. Record connection changes without repeating identical background checks. Validate withheld-marker contents and reply states in minimized exports, including rejection of a missing-source label for an included record. - Update collection-mode instructions and Russian guidance. Allow a bounded publication-settling interval while requiring exact installer bytes. - Mark messages left out of a minimized disclosure (preview): inside each disclosed chat, withheld messages appear as content-free markers naming the selection rule, one per run or one per message, and disclosed replies state whether they answer a disclosed message, a withheld one or one that is not in the source export. The package format becomes `tgwitness-account-disclosure-v2`; `verify.py` rejects markers with content and replies pointing at missing records, and still verifies version 1 packages. - Repeat gap analysis with the settings carried by the signed export, count each service-message number once, and bound account estimates to the measured interval. Require explicit whole-account scope, retain pause/resume boundaries, and interrupt expensive archive scans at their time budget. - Add missing message numbers (preview): `coverage.json`, the HTML and PDF reports, `verify.py` and the archive's `get_capture_status` measure numbers Telegram assigned and this collector never saw, per channel or supergroup and for the account-wide sequence of private chats, bots and ordinary groups during whole-account collection. Each result states whether it applies and why, lists its parameters, and anchors listed gaps to the neighbouring observations. **Parameters → Gap analysis** sets the listed gaps, the account-wide sequence and an optional service-message estimate that is never subtracted. A gap names no actor and no reason. - Record in the signed message when self-destructing media is fetched despite a type or duration rule (`media_capture.rule_override`), with the limits that still applied. - Add chat-state snapshots (preview): while observing, every enabled source is read periodically and saved as a signed `chat.state` record with title, description, counts, pinned messages, administrators with rights, and gifts on channels and profiles, plus the differences from the previous snapshot. Unpinning, rights changes and gift conversions or upgrades without a service message become visible. Parts Telegram refuses are named and carried forward, never reported as removed. **Parameters → Chat state** sets the interval, pause and parts. - Add anomaly indicators to evidence reports (preview) as registered, versioned processors in `tgwitness/metrics/`: first-time posters per day with flagged injection-like days, service messages among message numbers, joins and departures per month, and pins and unpins per month. Reports list every processor that ran with its version and print its method; **Parameters → Report metrics** chooses them. - Keep ranked-search pages within the first 1,000 results regardless of page size, order OCR/transcription results before pagination, and retain exact match positions when Unicode expansions and invisible-character removal cancel each other's length changes. - Keep photo downloads on the still variant named by their metadata and hash manifests, including after file-reference renewal. Reject truncated photo/chat attachments and corrupt reused files instead of counting them as saved. Check recovered multi-account message IDs against missing intervals without expanding large gaps. - Release a session's local connection lock after transport shutdown, including when a disconnected client was already removed from the workspace. Cancelling the waiting operation cannot release the lock early, and closing an older session cannot unlock a different current key. - Apply a chat export's skip/hash-only choice to recovered messages and profile photos, and record that choice in the acquisition metadata. Reject changed messages before fetching attachments in the separate files stage. Count missing message numbers as intervals so sparse histories do not exhaust memory, including during a cancellable full recheck. - Preserve available self-destructing photos, videos and files in the API journal with a dedicated immediate queue, explicit TTL/view-once labels and signed saved/unavailable/not-saved outcomes. Block read receipts in the API client, including batches and wrapped requests. Keep byte limits, disk reserves and Telegram backoff; saved bytes do not establish human viewing. - Preserve image-rendered Unicode emoji in official Web message text, reply previews, reactions and derived page text without changing the client DOM. A live account test exposed the omission; video and saved pages already retained the image. - Improve chat-export Takeout, unreadable-message recovery, shared absent-number rechecks and bounded range retries. Preserve observed deletions in export scope, compare verified archives, and distinguish archive integrity from an independently confirmed signer. - Protect imported sessions from remote logout, close idle connections and prevent simultaneous reuse of a session key. Add explicit session management and masked two-step password entry; cancellation or switching workspaces prevents submission. Read single-account export messages before their separate attachment stage. - Keep source export and AI actions disabled while local source search is pending, empty or has failed; clear stale previews before the next search. Exercise delayed replies explicitly in browser checks. - Use unambiguous synthetic privacy identifiers and report the exact marker/context on handover-test failures, avoiding accidental matches inside report metadata. - Add an in-panel comparison of collection methods and explain account task ownership beside full-history controls. Refresh source-version badges, qualification records and Trusted Live network results; check version labels before publication. - Add [full-text search](https://phishdestroy.github.io/TgWitness/zh/docs/reference/search/) (preview): Russian and Ukrainian word forms, English stems, Chinese and Japanese phrases without spaces, exact phrases, domains in hidden links and buttons, @usernames, wallets and phones, filters for chat, sender, message ID and observation period, ranked with BM25. The index is derived from the signed journal, bound to its latest record hash, never exported, and can be kept on disk, in memory only or turned off. Recognized text is indexed in memory only and labelled as machine recognition. - Ask the archive retrieves the best matches from the full-text index when it is complete, keeps the 24-source limit, and cuts long texts around their match. MCP `search_messages` accepts `ranked=true`. - Add `tgwitness index status|rebuild` with JSON output on stdout and stable exit codes. - Fix ranked search paging: `next_offset` is now returned when more matches exist, through `/api/search`, MCP `search_messages` and Ask the archive's partial marker. Paging stops at the first 1,000 results. - Fix Ask the archive failing on questions longer than 24 words or 200 characters. The full-text query keeps the question's first distinct words; a query the index cannot read falls back to exact-text retrieval. - Centre excerpts on the match in long texts that hide zero-width characters between letters. - Build the website when a language lacks new translations: untranslated blocks stay in English with the page notice and are listed by the build. - Add the [command line](https://phishdestroy.github.io/TgWitness/zh/docs/reference/cli/) (preview): `tgwitness search`, `context`, `messages`, `stats` and `export` with `--json` and stable exit codes, reading a stopped workspace directly or a running panel through a scoped, revocable archive connection. Add `.agents/skills/tgwitness-cli/SKILL.md` for agents. - Add the `get_activity_stats` archive tool, also offered over MCP: messages by UTC hour and weekday, peak days, edit and deletion shares, senders, domains and @handles, with coverage gaps. Computed on request, not stored. - Add the `export_messages` archive tool for the command line: saved observations streamed as JSON Lines in journal order, with full text and a completion record. It is granted only when selected; existing connections keep the tools they were issued with. - Recheck archive access before every streamed record, including completion. Revoked or expired connections end without a completion record; lazy export reads share the archive worker limit and timeout. - `tgwitness index` and the new commands find the data directory of the installation that runs them. ## 0.9.1 preview · 5 November 2026 - Keep message and attachment outcomes visible after single-chat sealed capture, including missing data, failed files and unfinished downloads. Translate final status when changing language after shutdown, and clear connection or export errors once they recover while retaining rejected-action and unconfirmed-revocation warnings. - Update the pinned OAuthLib dependency to 4.0.1 for CVE-2026-49272 and regenerate the runtime, browser and MCP hash locks. - Show in-flight attachment bytes without counting them as preserved evidence, reset progress on retries and clear it on pause. Keep official-client chat controls disabled during QR/2FA login and until a chat is available. Explain that Takeout approval requires another previously signed-in device. Bound CI dependency installation and avoid the stalled Azure package mirror. - Add explicitly selected direct networking for official Web capture through GitHub Actions. Proxy remains the default and never falls back to direct. The panel and signed verification report disclose direct IP exposure, and verification rejects a mismatch between the selected route and the hosted network. - Add an optional official Telegram Web observation mode with passive or sequential paced viewing, a fresh profile, restricted UI actions, login-excluded video and signed rendered observations. A required proxy bridge prevents direct fallback; exit changes stop recording. The GitHub Actions mode uses the approved sealed workflow and recipient encryption. - Bind official recordings to independently saved source/settings, check video segment order and clean endings, record fresh drand rounds and support independent public-relay comparison. Report unfinished procedures, unconfirmed logout and the limits of local or Cloudflare assurance explicitly. See [Official client witness](https://github.com/phishdestroy/TgWitness/blob/main/docs/OFFICIAL-WITNESS.md) for scope and validation. - Add opt-in Trusted Live preview: isolated official Desktop/Web sessions, native JSON preservation, guarded visual recording, per-chat continuity annotations, and verifier-recomputed reports. Supply a Linux network guard with no direct fallback, periodic proxy-routed drand observations, and optional independent read-only Cloudflare samples. Account/WARP/TDX qualification remains pending; see `docs/TRUSTED-LIVE.md`. - Make sealed export modes explicit: Telegram Takeout by default, regular API account export, or a single-chat event journal, with differences and limits shown before collection. Select multiple chats, save agreed settings, verify them with `--expected-selection`, and reject incomplete account exports with `--require-complete`. Correct the outdated one-chat-only hosted documentation. - Preserve signed message pages before requesting files or hashes. Resume from frozen history, retain completed attachments, and finish an interrupted export with explicit gaps when time or disk is limited. - Add Telegram Desktop compatible JSON/HTML views alongside authoritative signed data. GitHub capture supports full-account and selected-chat exports through regular API or Takeout, with chat types, dates and media settings. - Deliver large GitHub archives in encrypted parts with a signed, attested manifest and verified local assembly. Remove the fixed 4 GiB delivery failure without omitting preserved evidence. - Retry transient pinned OCR source downloads without relaxing checksum checks. Retry brief Windows file-sharing failures when saving private state. - Configure account exports before collection: select chats and media types, exclude avatars by default, and choose downloads, Telegram range hashes or metadata only. Keep a shared attachment budget and record incomplete files explicitly. - Show Takeout approval requirements and retry deadlines before collecting; check approval again without replacing the waiting session. Phone, QR and existing-session login retain their own authorization flow. - Save Telegram-provided SHA-256 ranges with file representation and data-center metadata. Compare them against locally supplied files; Telegram identifiers and access hashes are not treated as content hashes. - Collect message history across selected chats before processing attachments when messages-first mode is enabled. Preserve the journal in a compact export when full HTML or attachment packaging exceeds the remaining capacity. - Stream sealed delivery encryption without a second full plaintext archive. Remove interrupted ciphertext, preserve the original evidence for retry, and keep capture deadlines across runner steps with time reserved for delivery. - Require sealed-container validation in the release workflow. Phala deployment status now distinguishes verified, incomplete and review-required attestation instead of inferring trust from the provider name. - Validate every sealed-container build input against its pinned source. Retry transient package downloads up to three times while retaining signature, SHA-256 and exact-package checks before offline installation. - Include the hash-export configuration examples in source archives and preserve the translated documentation and required site assets from the latest main revision. - Keep the current tunnel address when an older signed address post is replayed. Signed posts are ordered by their signed time; unsigned posts use the relay's receive time. - Trust only the Caddy proxy on the private Docker HTTPS network and normalize client addresses for authentication limits. - Keep operator IP addresses out of new signed access events, hide administrative payloads from shared views, and enforce workspace and export ownership boundaries. - Reject duplicate JSON keys, prepended ZIP content and HTML injected into report seals; distinguish pinned witness keys from pinned collector keys. ## 0.9.0 preview · 4 November 2026 - Reserve each account exclusively for monitoring, history or an export. Serialize Telegram RPCs and persist full FloodWait deadlines. - Add durable distributed chat exports with date/language/reply filters, bounded labelled context, signed chunks and explicit pause/resume. See [Distributed chat export](https://github.com/phishdestroy/TgWitness/blob/main/docs/DISTRIBUTED-EXPORT.md). - Keep account reservations until every export worker has stopped, including repeated pause requests and sibling worker failures. History loading in sealed sessions also reserves the account exclusively. - Add participant timelines from saved observations: names, membership, explicit deletion flags and message activity. Profile refreshes are bounded; optional presence recording preserves unavailable or expired status as unknown and does not attribute online activity to a chat. - Save, import and reuse report layout profiles without copying case details or report filters. Profiles are validated and isolated by workspace. - Automatically offload eligible attachments to configured external storage under disk pressure, with reserve-space checks, compression, optional encryption and full readback verification before local eviction. Journals remain local. - Make the recording settings and chat tabs fit narrow screens, including wider system fonts, and fix profile controls and localized labels. - Include reviewed website assets in source archives and verify conditional dependency versions in SBOM inventories. - Phala Cloud deployments work on Phala Cloud itself (first real run, 4 November 2026): the compose carries its name, Phala's own pre-launch script is kept out of the measured app-compose, the production OS image is chosen instead of Phala's development default, the instance ID is read from the CVM state, and restarts from the CVM's operations count in `provider_actions`. Private Phala regressions simulate each of these. - `tdx_os` without outside tools: the verifier downloads the published dstack OS image once, matches it to the hash the CVM reports and computes MRTD and RTMR0-2 itself, the ACPI tables QEMU builds for the VM's shape included. A development image, other firmware, kernel, command line, memory, vCPUs or devices fail. Each journal start is checked the same way. - Attestation certificate for Phala deployments: `verify --report` also writes HTML and a signed PDF, sealed by a qualified eIDAS time stamp from the Belgian government's time-stamping authority, a FreeTSA time stamp and the verifier's own key; `check-report` checks the seal. - Quick tunnel addresses are also posted signed with the collector key, so a verifier is not misled by forged posts on the address topic; on Phala Cloud the tunnel check passes, since its connector runs inside the measured compose. ## 0.8.1 preview · 2 November 2026 - Runtime, sealed and media containers moved to pinned Wolfi/glibc with Python 3.12 and hash-locked system packages (AMD64 + ARM64). Image scans are clean of HIGH/CRITICAL. - Tesseract 5.5.4 built from verified source, English and Russian data pinned. - Release checks now cover real OCR, offline transcription, signed multilingual PDFs and container restrictions. The source archive includes all container build inputs. - **Extras → Independent capture** in the English panel: browser/AyuGram recorders with encrypted tokens, pinned keys, tab selection, start/pause, snapshots, checkpoints and verified ZIP downloads. Everything is off by default. - New optional `tgwitness-capture` package: Chromium PNG/MHTML snapshots, AyuGram SQLite copies, optional silent video, Ed25519 event chains, signed ZIP/HTML reports and a standalone verifier. Each recorder has its own key and storage. - Fixed Phala installs: source bundles were missing the capture package. ## 0.8.0 preview · 2 November 2026 **Reports** - Report studio: eight designs (Classic, Editorial, Briefing, Analytics, Technical, Overview, Reading series, Ledger & margin), live preview, HTML and native signed PDF. Switching designs keeps filters, charts and notes. - Pick report data by chat, author, date and event type and preview it before saving. Edits show before/after, deletions show what was saved earlier. - Reports look like proper dossiers now: cover, key figures, evidence map, numbered findings, timeline. PDFs get an A4 cover with QR, bookmarks and page refs. - Each report explains what its conclusions rest on: export-time checks, observations, missing material, how to check it independently (EN/RU/DE wording). - Send, edit and observed times are shown separately, plus replies, threads and metadata. **Case Board and groups** - Private Case Board: signed bookmarks, exact-version highlights, action slices, collections, threaded comments and statuses. Team notes stay apart from observations; the verifier checks board exports too. Export permission alone doesn't reveal team notes. - Account groups share settings. Members follow the group, an account's own value wins until reset. Changes show which accounts they hit and ask before overwriting. Access can be granted to a whole group. - Group screen at `/groups/`: accounts, problems, shared chats, group export. **Setup and connection** - Six-step first setup and one Settings page with simple/standard/expert levels, in all 25 languages. Each step has its own URL, Back works. - The setup asks whether the account is a separate one; a main account only records chosen chats. After Start it shows that connection, events, sources and files work. - Guided Connection screen: pick accounts, prepare and check a route, then apply. Direct, own proxies, public MTProto pool, WireGuard profiles and portable WARP. - Automatic connection tries public MTProxy, then WARP, then direct (if allowed) and shows a status indicator instead of failing silently. - Video duration limits in file policies. **Panel and safety** - No more one-click accidents: pausing, excluding and removing sources are confirmed, sending from a chat needs "Write as @account" first, route changes while observing offer to pause. - One set of counters everywhere (deleted with text, deleted before saving, missing on recheck). - Account files are inspected before connecting. URL, workspace and account always agree, a mismatch blocks actions. Chats open read-only and mask detected secrets. - Downloads fall back to normal browser downloads, big archives stream through one-time cookies. Prepared exports keep size, SHA-256 and "Download again". - Panel token rotation keeps the new session alive. Temporary network failures offer Retry. - Panel dialogs instead of `window.confirm`, journal paging fixed, lots of small UI fixes. - Public-channel showcase: expiring read-only links with redacted authors and signed snapshots. **Servers and evidence** - Extras → Server 24/7: a Hetzner server from the panel with a quick tunnel or your own domain. `python -m tgwitness.cloud destroy` cleans everything up. - Phala Cloud option: the collector runs in an Intel TDX confidential VM, `verify` checks the attestation up to Intel's root. - Gateway DNS (`--gateway-dns`): the server only resolves through Cloudflare Gateway. - Optional drand rounds and Telegram device lists in evidence mode. - Setup by goal: four questions, suggested settings, credibility and reliability scales. **Other** - Notification service catalog with icons, optional operator control bot, Discord witness posts. - Storage separates backups, verified file offloading and evidence retention. - AI previews show the endpoint and outside route. - Pull requests run both panel suites, including Firefox and WebKit downloads. Release packages wait for dependency, CodeQL and container audits. - Docs: a [panel guide](https://phishdestroy.github.io/TgWitness/zh/docs/reference/panel/) for every screen. ## 0.7.1 preview · 1 November 2026 - **Start here** with two paths: export my account, or follow an investigation. - Account export through Telegram Takeout or the regular API, resumable, with signed progress and coverage records ([account export](https://phishdestroy.github.io/TgWitness/zh/docs/reference/account-export/)). - Separate signed sharing copies with filters, pseudonyms and optional text/file removal. Signatures establish integrity; they do not establish Telegram authorship, completeness or legal admissibility. - Readable offline reports for account exports and sharing copies, printable, with record links and instructions for the recipient. - Clear handoff after download: original vs sharing copy, report preview, instructions to copy. - Rejected Telegram logins are told apart from paused accounts and network errors. **Sign in again** keeps the workspace. - Load the history of enabled sources with pause/resume, plus a signed progress report ([history](https://phishdestroy.github.io/TgWitness/zh/docs/reference/history/)). - Read-only MCP at `/mcp`, local archive search with optional AI, local OCR/transcription, signed webhooks with retries. - GitHub Actions capture preview: one chat on a temporary runner, encrypted result, pinned provenance ([sealed capture](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md)). - Self-contained signed reports in 25 languages with chain of custody; archives add `custody.json` and `SHA256SUMS`. - Panel rework: workspace URLs, Back/Forward, drafts survive updates, Ctrl/Cmd+S, Sources split into tabs, Parameters search, journal filters and inspector, live updates. - Batch session import, account groups, MTProxy dashboard with ping, countries and own lists. - MTProxy decryption through OpenSSL (it used to eat a whole CPU core). - Stronger masking in sharing copies, bounded media decoding, repeatable source ZIPs. - Notification services refuse redirects. Weekly Dependabot, nightly CodeQL and container scans. - Lots of fixes: stuck chat profiles, quick search, DST in search dates, 502s behind Caddy, GIF/sticker downloads, slow proxy list parsing, duplicate sessions on import. ## 0.7.0 preview · 31 October 2026 - OpenTimestamps proofs are parsed strictly; Bitcoin attestations show as `bitcoin-unverified` until you run `ots verify`. - Verification reports which part of the journal witness checkpoints cover; `--require-witness` demands a pinned witness and matching final record. - Access and permissions guides, updated proxy and IP mode guides. - Panel and docs site in 25 languages. Site publishing fails on missing translations. - Added the [roadmap](https://github.com/phishdestroy/TgWitness/blob/main/docs/ROADMAP.md). ### Initial preview contents · 30 October 2026 - First GitHub release: Windows portable, wheel, source archive. - The setup guide has an "Open to everyone" section: no country or sanctions blocks, and Taylor Wessing as the only incompatibility we name. It is our position, not a licence condition. - The README and Wiki now present the authors' Ethical Notice & Historical Continuity statement, with document references, historical context and an explicit explanation that MIT permission applies to everyone. - The operator notice and the Taylor Wessing page speak in our own voice. - Returned to the MIT License. A tool whose output third parties must be able to check should not stumble over its licence. `LICENSE` is the standard MIT text again, the package declares MIT with the OSI classifier, and the container, portable package, website, Wiki and translated README labels say so. Our statement stays in NOTICE and on the Taylor Wessing page as our position; it adds no licence condition. The presentation artwork reads "open source" again. - Added our Operator Incompatibility NOTICE to README, SECURITY, the documentation, Wiki and website. A single source keeps the complete statement consistent across those pages; source, Python and portable distributions include NOTICE alongside the licence. - High-assurance deployment (`python -m tgwitness.cloud`, [guide](https://phishdestroy.github.io/TgWitness/zh/docs/reference/high-assurance/)) on Hetzner, DigitalOcean, Linode, Vultr or EC2: no SSH key, no inbound ports, panel only through a Cloudflare Tunnel, and a `verify` command for third parties. - Local launchers open the panel in the browser once it's up. - Read-only online demo of the real panel with fictional data. - Wiki with 13 guides, docs website with a reference section, search, diagrams and 13 languages. - **Sign out of Telegram** on the Account page. - About 940 Russian panel strings fixed by hand. - Observation scope: chosen chats, a folder or the whole account, by type. New chats are picked up immediately. - Investigation mode for accounts that join groups and talk to bots. - People profiles (opt-in per chat), independent witness bot, notification excerpts, Parameters page, light/dark theme. - Panel mini-client: send messages, press bot buttons, preview and join invites. - Fixed message loss after a long stop (rechecks used to stop after 1,000 messages). - Many fixes from a full review: attachment byte counts, restore checks, scope edge cases, verify.py witness handling, off-site copy retries. - Pillow 13 (39 advisories against 12.3). ## 0.6.1 · 27 October 2026 - Renamed TgWatch to TgWitness, old archives still verify. - Evidence mode timestamps checkpoints with RFC 3161 and OpenTimestamps. - Password-protected AES-256 ZIP exports. - Notifications through Apprise. - 13 interface languages; README, Quick start and Deployment in 12 languages. - Encrypted off-site copy to S3-compatible storage with Object Lock. - Catch-up after restart and rechecks every 15 minutes. - Built-in pool of public API pairs, no own API ID needed. - New Chats view, Accounts view, multi-account chat export, signed full chat export. - Windows portable package, public website, GitHub Pages workflow. - Better launchers on all platforms, redesigned panel, new logo. ## 0.6.0 · 27 October 2026 - New account form with Phone, QR code, Files and Auth key tabs. - Auth Key + DC ID sign-in, Telethon/Pyrogram sessions, TData ZIPs, StringSession, account JSON. - QR login with 2FA, Desktop local passcodes. - Demo opens on its sample journal; refreshed panel look. ## 0.5.1 · 27 October 2026 - Only the active account client is accepted; rejected logins are disconnected. - Windowless Windows launches with logs in `logs/server.log`. - Case-insensitive Unicode search, full UTC dates on phones. - Linux/macOS launch scripts, Docker helpers, optional HTTPS with Caddy, GHCR images. - Docs on export signatures and investigation handoff. ## 0.5.0 · 26 October 2026 - Per-account monitoring categories, presets and signed policy changes. - Direct local entry to synthetic demos. Older history: [release status](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/RELEASE.md) and [verification](https://phishdestroy.github.io/TgWitness/zh/docs/reference/verification/). --- # 一个日志。四种收集模式。八个验证级别。 Canonical page: https://phishdestroy.github.io/TgWitness/zh/guides/modes.html 采集范围、事件边界、八种验证机制以及六个虚构的调查场景。 [Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/) [Documentation index](https://phishdestroy.github.io/TgWitness/zh/llms.txt) 模式、场景和证据级别 TgWitness 记录已连接账户所观察到的内容。第三方可借助独立的可信密钥验证该记录的完整性。 [收集模式](https://phishdestroy.github.io/TgWitness/zh/guides/modes.html#scope)[应用场景](https://phishdestroy.github.io/TgWitness/zh/guides/modes.html#scenarios)[证据等级](https://phishdestroy.github.io/TgWitness/zh/guides/modes.html#levels) 3–5 分钟概述 · 虚构示例 · 当前实现 1. **Telegram** 账户可见的更新 2. **收集器** 关联记录，每条均已签名 3. **验证者** 可信密钥 + 保留边界 `h₁ → h₂ → h₃ · Ed25519`已验证完整性。Telegram 的来源与消息的真实性仍是两个独立的问题。 ## 选择观察范围 三个观察范围和一个调查预设。排除项和已启用的源类型仍然适用。 默认**选定聊天** 记录 仅采用人工精选的来源。 新聊天 不会自动添加。 选择 一组已知的频道或群组。尚未确定固定的聊天容量。 **不具备的能力** 它不会发现其他聊天记录，也不会补全早期的聊天历史。 账户文件夹**Telegram 文件夹** 记录 文件夹包含项和分类，若已配置，则不包括排除项和已归档的聊天。 新聊天 匹配活跃聊天；一小时内的文件夹变更。 选择 分析员已维护一个案件文件夹。请在专用账户上确认数据收集情况。 **不具备的能力** 它不应用文件夹的动态 muted/read 条件。 确认范围**完整账户** 记录 选定类型中，账户可见的聊天，包括私人对话和机器人。 新聊天 将在首次更新时添加。 选择 一个专门的观察账户，包括参与案件的账户。 **不具备的能力** 它不会自动加入聊天群组，也不会绕过源访问。 整个账户预设**调查模式** 记录 所有源类型、自身操作、源配置文件以及新发现源的最新 200 条可见消息。 新聊天 新的聊天或机器人将获得一个配置文件和历史记录快照。 选择 通过控制面板加入团队或与机器人交互。查看并保存预设。 **不具备的能力** 它不会对所有现有聊天进行快照，也不会观察在其他客户端中触发的回调。 这些卡片仅用于本地比较，并非实时收集器控制项。它们不会更改任何账户。 **不具备的能力** 任何模式均不得读取秘密聊天内容、在进程停止时进行记录、自行加入消息源，或检索超出请求范围的早期历史记录 snapshot/export. [阅读详情](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/) ## 通过 GitHub Actions 采集（预览版） 新建 Telegram 登录会话、一个聊天、加密归档和 GitHub 来源证明。 [打开采集助手](https://phishdestroy.github.io/TgWitness/zh/docs/capture/) ## 记录内容 仅已交付或明确请求的观察记录才会被纳入记录。来源不明的观察记录仍保持未知状态。 捕获开关 · 本地示意图新消息编辑删除内容反馈成员资格 该面板按工作区应用这些开关。关闭某项开关会保留现有记录；重新开启该开关不会重建遗漏的事件。 **事件矩阵：已保存的材料与剩余未知项** | 分类 | 已保存 | 仍未知 | | --- | --- | --- | | 消息 | 文本、ID、发送者元数据、回复上下文及原始更新信封。 | 不存在可由第三方验证的 Telegram 签名。 | | 编辑 | 记录所有被观察到的版本，且不覆盖较早的版本。 | 中间编辑可能被遗漏；发送者不一定是编辑者。 | | 删除 | 如有，请附上通知及先前保存的文本。 | 未提供删除者及确切操作时间。 | | 无作用域的删除 | 账户级通知；未知对等方仍被明确标识。 | 不进行聊天内容推测。关联操作在可能的情况下使用先前保存的账户范围内的 ID。 | | 反应 | 已交付的计数器及可见的近期身份信息。 | 并非所有反应器都是可见的；获取完整的可用列表需要单独查询。 | | 成员资格 | 已发送的服务消息和参与者更新。 | 角色和聊天类型限制了可见性；沉默并不意味着不存在。 | | 附件 | 原始版本描述符、已保存字节、 SHA-256 以及尝试结果。 | 已消失的文件可能无法获取；新版本不会取代它。 | | 历史快照 | 当前可见的消息，被标记为历史观察记录。 | 早前的编辑记录和已消失的内容不会被重建。 | | 自主行动 | 发送 messages/edits 及匹配的回复键盘 button_press 元数据。 | 在其他 Telegram 客户端中触发的回调不可见。 | | 机器人按钮 | 回调、URL、Web 应用及请求元数据将随消息一并保留。 | URL 和 phone/location 请求均为文本，不会被自动打开或执行。 | ### 默认附件限制 照片 20 MiB 视频 100 MiB 文件 50 MiB 动画 20 MiB 视频笔记 50 MiB 语音 20 MiB 音频 50 MiB 贴纸 5 MiB **不具备的能力** 开关不会屏蔽嵌入的元数据，也不会禁用操作记录。捕获操作不会识别 Telegram 未提供的行为主体。 [阅读详情](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/) ## 仅使用您拥有的授权权限 每个账户都有自己的工作区、日志、签名密钥、路由和队列。 ### 电话号码 + 代码 启用 2FA 。 ### QR 代码 请从授权设备进行扫描； 2FA 可能仍需执行此操作。 ### Telethon .session 导入该账户的会话文件。 ### Pyrogram .session 导入支持的 Pyrogram 会话格式。 ### TData ZIP 仅支持一个 Desktop 账户；若已设置，则使用本地通行码。 ### StringSession text 粘贴一个 Telethon StringSession. ### .session + .json 选择会话及相应的配套元数据。 ### 认证密钥 HEX + DC ID 导入账户授权时需包含其数据中心标识符。 **API pair** 您自己的 API 密钥对是可选的。若未提供， TgWitness 将使用公共密钥对池，其中包括来自官方 Telegram Desktop 的密钥对。 `Direct · SOCKS5 · HTTP CONNECT · MTProxy`MTProxy 处于实验阶段；内置的公共 MTProxy 列表可用。代理路由失败时不会回退到直接连接。 同一台机器上的两个工作区并不构成两个独立的见证者。 **不具备的能力** 导入操作不会绕过 Telegram 授权， 2FA 也不支持不受支持的会话格式。账户仍共享应用程序进程。 [账户格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/) ## 从面板操作 发送或回复消息、点击当前机器人按钮、保存链接预览后，请显式加入聊天或使用其启动参数启动机器人。 `interaction.preview``interaction.requested``interaction.result` 预览、请求和结果回执均经过签名。在按下按钮之前，服务器会再次获取消息，并拒绝已更改的键盘输入。返回的回调文本和 URL 仍作为记录上下文保留。 **不具备的能力** 不支持网络应用、支付、 phone/location 分享或内联查询。显示 URL 不会打开该链接。 [阅读详情](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/) ## 恢复与连续性 应展示缺口，而非隐藏。 ### 恢复保存的位置 重启后，系统会向 Telegram 查询遗漏的更新。有限的保留时长和过期的差异可能导致数据缺失。 ### 重新检查可见消息 默认设置：优先级来源每15分钟更新一次，其余来源每6小时更新一次。结果包括 message.recovered 以及 message.missing_on_recheck. ### 阅读 coverage.json 观察时段、附有原因的缺失记录以及未观察到的 ID 均随签名导出文件一同提供。重新检查时未发现的记录并不等同于删除通知。 **不具备的能力** 后续的历史快照不会抹去服务中断事件，也无法恢复所有已消失的版本。保存的光标并非对日志接受情况的无损确认。 [阅读详情](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/) ## 七个层次。不同的问题。 每种机制都针对一个有限的问题提供解答。请单独配置外部服务，并将它们的信任锚点保留在收集器之外。 1. ### 记录 SHA-256 chain + Ed25519 每个事件；第一个 previous_hash 为64个零。 **第三方验证** 基于固定收集器密钥的排序和签名。 **不具备的能力** 这并不证明其源自 Telegram 亦不证明其完整性。 **验证命令** ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 ``` 2. ### 容器 manifest.json 列出文件哈希值； manifest.sig 对其进行签名。 media.saved 将附件字节绑定到一个事件上。 **第三方验证** 提供的文件与已签名的清单及媒体收据一致。 **不具备的能力** 它不会对单独下载的 CSV, HTML 或截图。 **验证命令** ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 ``` 3. ### 保留边界 启动时进行检查点备份，默认每 5 分钟一次，并有序停止。请在其他位置保留一份副本。 **第三方验证** 后期的导出结果应与先前保留的长度和头部一致；可检测到回滚情况。 **不具备的能力** 它无法检测日志和所有保留检查点同时被替换的情况。 **验证命令** ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --checkpoint checkpoint.json ``` 4. ### 外部时间 证据模式会发送一个检查点 SHA-256 至 RFC 3161 相关机构（FreeTSA, DigiCert) 及 OpenTimestamps 日历。 **第三方验证** 经过验证的 TSA 响应会标注这些字节的时间戳；已确认的 OpenTimestamps 证明将这些字节锚定至比特币。 **不具备的能力** 它不会将已准备的请求或待处理的日历收据视为已确认的时间戳。 **验证命令** ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --tsa-ca trusted-ca.pem ots upgrade checkpoint.ots ots verify checkpoint.ots ``` 5. ### 独立见证人 将主机、范围限定只读端点、新挑战及其专属 key/journal 以及 TGW1 频道帖子。 **第三方验证** 先前已接受的分支头；状态包括 ok、 key_changed、回滚、分叉、无效以及 no_response. **不具备的能力** 它不会将同一收集器主机上的两个工作区视为独立的见证者。 **验证命令** ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --witness witness.zip --witness-fingerprint WITNESS_SHA256 --channel result.json ``` 6. ### 站外副本 S3-兼容的副本，使用 AES-256-GCM; Object Lock 加密的副本（当存储桶支持时）。 **第三方验证** 仅在日志、检查点和已保存媒体的验证成功后，Restore 才会发布文件。 **不具备的能力** 若未提供导出的密钥，则无法恢复数据；若未检查存储响应，则不假设数据已被保留。 **验证命令** ``` python -m tgwitness.replica restore --key-file KEY.json --out EMPTY_DIR ``` 7. ### 运行溯源 签名运行收据：源代码哈希值、依赖项版本及进程上下文。由系统自行报告。 **第三方验证** 签名收集器对其自身执行情况的报告。 **不具备的能力** 它不提供独立的进程认证，也不排除记录前已遭入侵的可能性。 **验证命令** ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 ``` ### 任何级别都无法证明的内容 每次 Telegram 更新的送达；文本的真实性；发件人 ID 代表真实个人；记录前收集者未遭入侵；法庭可采纳性。 [独立见证人](https://phishdestroy.github.io/TgWitness/zh/docs/reference/witness/) 本地 SHA-256 实验 ### 尝试修改第 2 条记录 下一条记录保留了之前保存的链接。修改文本会改变记录 2 的计算哈希值。 记录 2 的正文 记录 1`h1`以 64 个零开头 记录 2`h2`包括已保存的 h1 记录 3`h3`包括已保存的 h2 静态示例： h2 涵盖“11:00见面”。更改该文本会改变 h2；记录 3 仍引用已保存的 h2. **检查完整的摘要** 已保存记录 2 的哈希值 `SHA-256(e₂)` 重新计算的第 2 条记录哈希值 `SHA-256(e₂)` 此示例计算的是哈希值，而非签名。真正的验证器会使用可信密钥对每个签名和链接进行验证。 [阅读详情](https://phishdestroy.github.io/TgWitness/zh/docs/reference/how-it-works/) ## 选择一条贯穿证据的路径 虚构情境。在相关事件发生前开始收集数据；在记录内容的同时，保留其边界和空白处。 ### 频道更改支付详情 模式 → 事件 选定聊天 → 消息、编辑、删除。 输出 通过哈希值记录观察到的帖子版本和附件。 验证 已签名 ZIP + 保留检查点 + 经验证的 TSA 响应。 **不具备的能力** 它无法恢复从未被捕获过的原始数据。 ### 事件发生后，消息将消失 模式 → 事件 文件夹或整个账户 → 所有事件类别。 输出 已保存的原始内容、删除通知以及存在缺口的覆盖范围。 验证 已签署 ZIP + 独立见证日志。 **不具备的能力** 若通知中未提供操作主体，则无法据此识别删除者。 ### 调查一个商店机器人 模式 → 事件 调查预设 → 按钮、链接预览和显式机器人启动。 输出 已签名的交互收据、返回的回调以及保存的配置文件。 验证 已签名 ZIP；请对照 ZIP. **不具备的能力** 它不会打开机器人网页应用、进行支付或记录其他客户端的回调。 ### 参与者在不同聊天中会更改昵称 模式 → 事件 任何范围 → 被观察的 sender/profile 元数据。 输出 按数字 ID 记录名称/用户名历史、"也出现在"链接及提取的线索。 验证 文件 JSON 已与签名版本核对 ZIP. **不具备的能力** 它不会将钱包、类似手机号码的字符串或用户名转化为经过验证的身份。 ### 长期观察，并保留异地副本 模式 → 事件 任何作用域 → 证据模式以及一个 S3 支持的副本 Object Lock. 输出 加密副本、保留的检查点及时间戳响应。 验证 使用导出的密钥进行恢复，然后在不依赖原始服务器的情况下进行验证。 **不具备的能力** 它不能替代独立见证人或单独保留的解密密钥。 [阅读详情](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/) ## 交付可验证的软件包 请提供已签名的原始文件、独立保存的密钥指纹、相关检查点以及验证结果。 - 已签名 ZIP - JSONL - CSV - HTML - 检查点 - 已读回执 - 聊天记录导出： chat.json / chat.html - 档案 JSON - 受密码保护 AES-256 ZIP - 为多个账户分别导出 - 流式 CLI：5 GiB 默认限制 ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --checkpoint checkpoint.json ``` 请从可信副本中获取验证器，而非从正在检查的存档中获取。 **不具备的能力** 独立版 CSV 和 HTML 并非签名容器。密码用于保护传输机密性，而非真实性。多次导出不会合并账户日志。 [阅读详情](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/) ## 对比交付的成果 基本 artifacts 不包含额外的签名、时间戳或见证系统。脚本和日志记录器因实现而异；“部分”指仅限于捕获或可见的内容。 | 方法论 | 编辑 / 删除 | 记录签名 | 外部时间 | 独立见证人 | 覆盖范围 / 缺失部分 | 无作者的验证 | | --- | --- | --- | --- | --- | --- | --- | | Telegram Desktop 导出 | 部分 | 无 | 无 | 无 | 无 | 无 | | Telethon 快照脚本 | 部分 | 无 | 无 | 无 | 无 | 无 | | 删除日志记录器：文本日志 | 部分 | 无 | 无 | 无 | 无 | 无 | | 屏幕截图 / 网页截图 | 部分 | 无 | 无 | 无 | 无 | 无 | | TgWitness 带配置的附加项 | 部分 | 是 | 是 | 是 | 部分 | 是 | **不具备的能力** 该表格并未评估每一款脚本或日志记录产品。可选的时间和见证人验证需要各自的服务和信任锚点；其中没有任何一项能确立源头真实性。 [阅读详情](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/) ## 将限制与证据一并保留 当验证范围保持明确时，验证才具有实用价值。 - 秘密聊天功能不可用。 - 进程停止期间不会记录任何内容；恢复能力有限。 - 经过验证的记录并不证明其内容为真。 - 持有密钥的操作员可以对任意内容进行签名。独立见证人和时间戳限制的是后续替换，而非不诚实的初始捕获。 - 请使用专用账户，而非您的主账户。 - Telegram 可能会因请求量过大而限制账户。 **不具备的能力** 任何模式或证据级别均不能确立法律可采性、Telegram消息的完整送达或现实世界中的身份。 [设置指南](https://phishdestroy.github.io/TgWitness/demo/guide.html?lang=zh)[专用账户](https://phishdestroy.github.io/TgWitness/zh/docs/dedicated-account/)[EVIDENCE.md](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/)[INVESTIGATION.md](https://phishdestroy.github.io/TgWitness/zh/docs/reference/investigation/)