# Telegram · GitHub Actions 捕获

Canonical page: https://phishdestroy.io/tgwitness/zh/docs/capture/

在临时 GitHub runner 上选择 Takeout、常规 API 导出或聊天日志．

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/zh/llms.txt)

在临时 GitHub runner 上选择 Takeout、常规 API 导出或聊天日志．

请启用 JavaScript 以生成密钥并解密您的存档文件。

**完整引用**

[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/OPTIONAL-CAPTURE.md)

![独立捕获](https://phishdestroy.io/tgwitness/assets/chapter-capture.svg?v=c979502bc92b)

**可从 `main` 预览。**一个分支会从 `phishdestroy/TgWitness`。该工作流通过新创建的 Telegram 会话导出账户、选定的聊天记录或某条 聊天的事件日志，对证据 ZIP 文件或多部分清单进行认证，并仅上传 收件人加密的交接数据。常规管理面板不会对外公开。

选择 `client=official_web` 以运行带受保护的Telegram Web控件和视频功能的[官方客户端见证](https://github.com/phishdestroy/TgWitness/blob/main/docs/OFFICIAL-WITNESS.md)程序。这需要您自己的上游代理，并仅监视一个已渲染的聊天窗口。默认情况下 `client=api` 保留了下文所述的完整账户导出模式。

验证器会根据 GitHub 证明、已批准的 工作流和收集器提交记录，以及已签名的日志和附件哈希值，对归档文件进行核对。 收集过程使用固定的上游代码和新的存储空间。审核员 可以检查该代码，并根据记录的运行情况对交付的归档文件进行验证。

**本页内容**

- [用户流程](https://phishdestroy.io/tgwitness/zh/docs/capture/#user-flow)
- [会议时间安排](https://phishdestroy.io/tgwitness/zh/docs/capture/#session-time-budget)
- [选择此模式或持久化工作区](https://phishdestroy.io/tgwitness/zh/docs/capture/#choose-this-mode-or-a-persistent-workspace)
- [什么是公开的，什么必须保密](https://phishdestroy.io/tgwitness/zh/docs/capture/#what-is-public-and-what-must-stay-private)
- [故障排除](https://phishdestroy.io/tgwitness/zh/docs/capture/#troubleshooting)
- [本地解密与验证](https://phishdestroy.io/tgwitness/zh/docs/capture/#local-decryption-and-verification)
- [分叉如何被保留在捕获过程之外](https://phishdestroy.io/tgwitness/zh/docs/capture/#how-the-fork-is-kept-outside-the-capture-process)
- [加密交接](https://phishdestroy.io/tgwitness/zh/docs/capture/#cryptographic-handoff)
- [范围与验证](https://phishdestroy.io/tgwitness/zh/docs/capture/#scope-and-validation)
- [维护者发布流程](https://phishdestroy.io/tgwitness/zh/docs/capture/#maintainer-release-sequence)

## 用户

该辅助工具会讲解这五个阶段，并让您在示例数据上尝试消息或收集器 替换。**点击开始捕获**即可打开向导。

1. 在项目主页、 工作区登录界面或**导出→打开捕获助手**中选择**GitHub Actions 捕获（预览版）**。您还可以 在现代浏览器中，从可信的代码检出中打开[官方助手](https://phishdestroy.github.io/TgWitness/sealed.html?lang=en) 或 `tgwitness/static/capture.html`。 该辅助程序在处理密钥或 文件时不会发起任何网络请求。该辅助程序支持本网站的界面语言； 临时收集面板支持英语和俄语，当浏览器语言为上述两种之一时， 面板将以该语言显示。
2. 生成密钥并保存 **sealed-key.json** 文件。这是唯一的 私有解密密钥。复制单独的**收件人**公钥值。一旦丢失 私有密钥，将无法访问连接和归档文件。 请确认已保存该密钥，以便解锁下一步。如果您已有 交付文件，请加载已保存的密钥，并选择**我已有归档文件**。
3. 分叉 TgWitness，在分叉中启用“操作”功能，并运行**密封聊天捕获**。 粘贴公开收件人，并选择 30、60 或 120 分钟。切勿在 工作流输入、提交、问题或日志中填写 电话号码、登录码、Telegram 密码、私钥或会话信息。
4. 运行期间，请从“构建产物”中下载 **sealed-connection** 并解压。 在 `connection.tgwsealed` ，并使用已保存的私钥。 生成的链接在其 URL 片段中包含一个随机的访问密钥。 请妥善保管此链接。控制面板会移除该片段，并将密钥 保存在此标签页的会话存储中；该密钥不会被记录在 HTTP 访问日志中。
5. 打开连接链接。使用二维码登录，或使用您的手机号码和 登录码登录。如果 Telegram 要求输入，请输入您的两步验证密码。默认情况下， 系统会使用内置的 API 凭据池，这与普通工作区一样。您 可以展开可选的自定义凭据部分，并输入以下两项 `api_id` 和 `api_hash` 来自 [my.telegram.org/apps](https://my.telegram.org/apps) 的信息。若要使用内置凭据池，请将这两个 字段均留空；不完整或格式错误的凭据对将被拒绝。 不允许导入会话。请选择导出模式和范围。连接 链接中包含访问密钥：请务必保密。
6. 选择**Telegram Takeout**、**常规 Telegram API**或**聊天事件日志**。 若要导出账户数据，请选择所有可访问的聊天记录，或加载并选择一个或多个 聊天记录，然后设置日期、聊天类型、账户类别和附件规则。 检查设置和大小，可选择将设置 JSON 保存供独立 审核人员查看，然后点击**开始捕获**。开始后设置即无法更改。 “恢复”功能仅在该运行器存在时有效；提前结束将保留已获取的 数据并记录缺失部分。开始后截止时间到期将生成一个明确的 部分存档；开始前到期或取消操作则不会生成任何存档。
7. 等待**密封结果**，下载并解压，然后在 `delivery.tgwsealed` 。您将收到 `delivery.zip`，其中包含 `evidence.zip`, `attestation.jsonl`以及操作说明。浏览器解密 上限为256 MiB；更大的包请使用下方的本地流式解密命令。 大型结果还包含 `delivery-NNNNNN.tgwsealed` 多个部分；主 `delivery.tgwsealed` 文件中包含 `evidence.parts.json` 和证明。 请下载所有部分，并按照下文所述在本地进行组装。
8. 如果撤销操作 未被确认，或者运行进程被终止，请在 Telegram 的“设置”→“设备”中结束临时会话。正常结束时会提示注销，且 运行记录会保存撤销操作是否已被确认。

该仓库必须包含已发布的“固定源代码”和“可重用工作流” 提交。仅有一个本地分支是无法被另一个 GitHub 仓库调用的。

## 会议时间

在收取之前， **计算时间和大小** 根据消息数量和有限样本，估算所选历史数据和文件的 处理时间。显示内容包括已耗费的登录时间、 预估的收集时间以及打包所需的预留时间。对于文件，初始估算 采用 1 MiB/s 的速率和两倍的时间余量；进度条会用实际测得的 速率取代该假设。使用 **仅限消息** 或者，当预估时间超过剩余时间时，请选择较少的聊天记录。

Telegram 报告的“Takeout”等待时间已计入预算。当剩余时间需用于打包时，收集器会停止采集， 保留已采集的数据，并标记为部分 结果。因此，一个 120 分钟的会话会利用其剩余的采集窗口，而非 等到截止时间才开始准备归档。界面会标出那些 无法采样其完整大小的选项。

## 选择此模式或持久化工作区

| 拍摄模式 | 可配置的范围 | 区别 |
| --- | --- | --- |
| Telegram Takeout，默认选项 | 所有可访问的云端聊天记录或选定的聊天记录、日期、账户类别、媒体策略以及 JSON/HTML 视图 | 使用 Telegram 的官方导出机制；可能需要批准或等待。在 Telegram 允许的情况下，Takeout 可以列出剩余的频道/群组，并请求获取额外的个人数据。 |
| 常规 Telegram API | 账户范围和输出选项与常规 API 提供的相同，具体取决于常规 API 支持的方法 | 无法初始化 Takeout；无法枚举左通道/超级群组，也无法获取仅限 Takeout 的个人数据。联系人范围仅限于 Telegram 用户，而非完整的已保存手机通讯录。速率限制仍然适用。 |
| 聊天活动日志 | 一条选定的聊天记录、附件政策和可选头像 | 记录本次运行过程中观察到的历史数据和变化。账户类别、日期筛选器以及与桌面端兼容的视图均不适用。 |

这三种模式均采用相同的 GitHub 认证和加密传输机制。Takeout 会选择数据获取方式，且绝不会被常规 API 访问悄然取代。 TgWitness 会根据捕获的记录生成 JSON/HTML 视图，并在导出时保留 所选的数据获取方式。请参阅 [官方 Takeout API](https://core.telegram.org/api/takeout)。

默认情况下，系统会导出“Takeout”中的内容，包括所有可访问的聊天类型（含存档聊天）、所有 日期、账户资料和联系人、兼容的 JSON 和 HTML 文件，以及文件下载。 初始媒体配额为 4 GiB，各文件类型均有可见的限制；对于较大文件 或下载配额已用尽的情况，系统将在可用时使用服务器哈希值。请在开始收集前查看这些 限制。哈希值无法还原文件。可选的照片、 故事、会话元数据和额外个人数据仍需单独选择。

在已建立的 Telegram 会话中，提取操作可能需要获得批准。Telegram 会设定 延迟时间；新的登录或运行程序无法绕过该延迟。最大捕获时限 为 120 分钟（包括登录和批准时间），因此大型账户或批准 等待时间过长的情况可能无法完成。持久的本地导出可以恢复同一会话，但 不会继承 GitHub 认证。

### 确认并验证

**检查设置和大小**后，请使用**保存设置进行验证**。在 收集前与审核员确认 `sealed-export-settings.json` 与审阅者达成一致后再进行收集。 任何更改都会使已保存的评估失效。收集者对有效的 设置及其 SHA-256 值进行签名，而账户导出收据则绑定相同的选项。 验证者报告实际模式、选项及完整性，并拒绝 日志与嵌套账户导出之间存在不一致的情况。

```
python -m tgwitness.sealed_verify evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness --expected-selection sealed-export-settings.json --require-complete
```

`--expected-selection` 拒绝其他传输方式、聊天范围、过滤器或 附件策略。 `--require-complete` 仅接受已标记为“已完成”的账户导出和聊天 日志。若未设置这些标志，验证过程仍会检查来源和 完整性，同时报告记录的设置及缺失项。在运行前确认预期的 选择范围，并将其与归档文件分开保存。范围和采集间隔用于确定运行期间捕获的 数据；在比较先前版本时，请使用保留的早期观测数据。

| 需求 | 模式 |
| --- | --- |
| 在有限的会话期间导出可访问的账户数据或选定的聊天记录，并向审核人员提供经外部认证的存档 | GitHub Actions 捕获（预览版） |
| 持续关注多个聊天记录，管理账户，搜索并阅读不断扩充的存档 | 本地或 Docker 工作区 |

这将使用新的登录凭据启动一个独立的捕获任务。它不会上传您现有的 本地日志，也不会导出当前打开的工作区，也不会复用其 Telegram 会话。 未完成的云端捕获任务在运行器被销毁后无法继续；新的 工作流将启动一个新的捕获任务。

工作区中的**导出→打开捕获助手**会直接在面板内打开完整的向导。 独立页面使用相同的向导、控件和主题。 两者均将密钥和解密过程保存在您的浏览器中。GitHub 工作流启动和 临时 Telegram 面板会在单独的标签页中打开；向导会提示您何时 返回。锁定工作区会清除向导内存中的密钥。您保存的密钥 文件仍保留在您的设备上。

## 什么是公开的，什么必须保密

收集过程在由 GitHub 托管的标准运行器上运行。GitHub（作为经批准的收集器） 及其依赖项、辅助页面、浏览器和 HTTPS 隧道都是该配置中 值得信赖的组件。临时主机负责处理 Telegram 会话和 明文消息；交付的构建产物会为接收方进行加密。

通过分叉将项目代码复制到你的代码库中。它会 **不** 导出您的 Telegram 账户。接收方的工作流输入是一个公钥。 保留 `sealed-key.json`，从提交记录、工作流输入和公共日志中提取 Telegram 凭据、登录码、双因素认证密码以及 已解密连接 URL。

该工作流会发布一天内的加密连接/结果工件。 请及时下载这两项内容；GitHub Actions 的可用性、账户限制和计费 规则均适用。公开分叉并不意味着可获得无限量的免费计算资源。无需在辅助程序中 输入任何付款信息或 GitHub 访问令牌。

私有解密密钥保存在您的浏览器/文件中。Telegram 会话内容 和明文记录必然存在于临时存储器中。 GitHub 和 HTTPS 隧道仍是可信的基础设施。认证可能会将 归档摘要和工作流标识公开；归档内容不会 包含在认证中。认证时间戳并非消息时间戳。

## 故障排除

| 症状 | 下一步 |
| --- | --- |
| “不**运行”工作流**按钮 | 创建自己的分支，启用“操作”功能，并将其与上游同步 `main`。请勿修改已获批准的上游引脚以绕过失败。 |
| 否 `sealed-connection` 文物 | 检查任务是否已启动并完成了启动/上传步骤。队列、运行器、镜像下载、隧道或仓库策略的故障都可能导致启动失败。 |
| 无法建立连接 | 加载本次运行的已保存密钥，解压下载的构建产物，并选择 `connection.tgwsealed`。此时运行器必须仍处于活动状态。 |
| 历史暂停了 | 检查面板的状态，并在会话仍处于活动状态时使用“继续”功能，或者利用已收集的数据完成操作。Telegram的限制和无法访问的内容可能会导致数据存在缺失。 |
| 不 `sealed-result` | 如果在开始收集之前取消或到期，则不会生成存档；该运行将以**无存档**的提示结束。收集、认证或打包步骤出现失败也会导致无法交付；失败的步骤会注明主管给出的原因，且不包含任何私人数据。无需提交凭证即可进行检查。 |
| 浏览器无法解密大型压缩包 | 对于大于 256 MiB 的包，请使用下面的流式处理 CLI。如果私钥错误或丢失，将无法解密结果。 |
| 验证结果显示签名人被拒绝 | 请使用可信的最新 TgWitness 安装版本以及完全相同的调用者 `OWNER/REPOSITORY`。请勿接受存档中提供的替代策略。 |
| Telegram 仍然显示该临时会话 | 请在“设置”→“设备”中结束该操作。注销可能会失败，且强制终止的工作流可能不会执行清理操作。 |

在依赖此预览版之前，请先进行一次由您控制的小规模测试：创建一条消息 和一个附件，将其收集起来，解密结果，运行验证程序，检查 覆盖范围/媒体结果，并确认 Telegram 会话已被撤销。自动化 检查使用的是合成 Telegram 客户端，并配合单独的真实 GitHub 证书 测试；目前尚未记录到在当前版本上使用真实账户进行的测试。

## 本地解密与验证

请使用来自独立可信安装源的工具，而非 来自未知证据存档的可执行文件：

```
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
```

对于分多部分交付的情况，请先解密主包，并将解压后的 清单文件放在每个加密部分旁边，然后运行：

```
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
```

清单是经过验证的对象，它将所有部分与生成的 ZIP 文件绑定在一起。 使用 `--max-gib` 来为 大型归档文件设置适当的解压验证上限；默认值为 4 GiB。预期选择和完整范围检查 也适用于多部分传输。

Python 3.11 及以上版本、该项目的依赖项，以及支持 `--signer-digest` 和 `--deny-self-hosted-runners` 。此外还提供了一个 CLI 密钥生成器 ： `python -m tgwitness.sealed_crypto keygen sealed-key.json`.

验证器使用 `tgwitness/sealed_policy.json` 来自受信任安装源的数据。 它会检查调用方仓库、上游签名者工作流、已批准签名者的 提交、托管运行器要求、完整的 ZIP 摘要、内部日志和 附件的完整性、最新的 account-key 来源，以及预期的收集器提交。 它会显示历史记录和媒体结果，而非默认所有数据均已保存。 若“已批准发布”列表为空，则验证失败。更新策略是一项明确的 信任决策；切勿自动接受归档文件自身提出的策略。

若需离线使用，请提前从可信环境获取可信根证书：

```
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
```

该证明的时间戳仅涉及存档方的承诺。它并不 对消息的时间戳或收集器的实际时间进行验证。请参阅 [GitHub 的验证选项](https://cli.github.com/manual/gh_attestation_verify)。

## 如何将分叉保持在捕获过程之外

该调用包含对上游可重用工作流的作业级引用，引用基于 一个完整的提交 SHA。该工作流会显式检出 **上游仓库 在固定的收集器 SHA 处**. 默认值 `actions/checkout` 在可重用工作流中 会检出调用者，且该操作是故意不被使用的。

该工作流不会恢复调用者的缓存、消耗调用者的构建产物、执行 调用者的文件，也不会接受源/镜像 URL、shell 命令、预先准备好的 ZIP 文件， 或待签名的哈希值。它仅接受有限的公开接收者和会话时长。 操作、Python 基础镜像和 cloudflared 均通过不可变摘要进行固定； Python 依赖项使用现有的哈希锁定要求。该镜像 从可信来源构建，不使用缓存。

该收集器以非root用户身份运行，使用只读镜像，已移除Linux 能力，设置了资源限制，且不包含Docker套接字或GitHub令牌环境。 其仅挂载了新的配置目录、工作区和输出目录。 该受限的 FastAPI 应用程序提供了登录、对话、可配置的账户或聊天记录收集、 状态、恢复、结束和取消等功能。不存在明文下载路径、 通用管理路径、导入路径或签名端点。

在验证操作 读取最终修复版本之前，管理员会停止面向网络的容器 `evidence.zip` 或 `evidence.parts.json`。打包容器不具备网络连接。 上传步骤仅命名 `connection.tgwsealed` 和 `delivery*.tgwsealed`； 既不上传明文证据，也不上传 Telegram 凭据作为构建产物。 清理操作会移除私有目录和容器，GitHub 会在任务完成后销毁 托管的运行器虚拟机。构建产物保留期限为一天；请在过期前下载。

分支所有者可以替换调用者，或生成另一个签名的文件。 严格验证器必须拒绝由此产生的、**签名者不同的工作流/摘要**。 这种机制仍然依赖于已批准代码中不存在可被利用的漏洞， 以及 GitHub 运行器和签名基础设施的完整性。

## 加密

每个接收方密钥均为 RSA-3072（也接受 RSA-4096 导入），指数为 65537。 每个信封都使用一个全新的随机 AES-256 密钥和 96 位随机数。 采用 SHA-256/MGF1-SHA256 的 RSA-OAEP 对 AES 密钥进行封装。采用 128 位标签的 AES-GCM 对 完整的前缀和有效载荷进行认证。收件人的公钥为 base64 编码的 DER SPKI 格式； 私钥文件包含 base64 编码的 DER PKCS8 格式。

封装字节包括 `TGWSEAL1\n`，包括一个大端序的 uint32 类型的 JSON 头部长度、 头部、密文以及一个 16 字节的 GCM 标记。头部长度恰好为 `algorithm`, `key`，以及 `nonce`；算法为 `RSA-OAEP-256+A256GCM`。从前缀 到头部之间的完整内容均为 GCM 附加认证数据。头部大小上限为 8192 字节。CLI 支持最多 8 GiB 的数据流，并在 安装请求的输出前进行认证；它拒绝覆盖现有目标。 这是一个围绕标准密码学原语构建的项目专用封装： RSA-OAEP 结合 SHA-256 和 AES-256-GCM，可在 OpenSSL 及所有主流 密码学库中使用。

在将证据和 认证信息放入加密的外层包**之前**，会对原始证据字节进行认证。这样可以避免 归档文件的哈希值与其自身包含的证书之间产生循环依赖。 对于公共仓库，认证元数据（仓库、工作流、提交、 工件名称和摘要）是公开的。切勿在公共元数据中包含聊天名称。

## 范围与

此模式使用带签名的日志和账户导出引擎。秘密聊天、 收集前的已删除历史记录以及账户无法访问的数据均 被排除在外。若已选中，私有云聊天也符合条件。聊天选择器 上限为 20,000 个对话；账户导出功能会自动检测其库存。缺失的数据、失败的文件和未完成的 任务都会被记录下来。附件限制以及运行程序的磁盘/时间限制仍然适用。 大文件传输使用加密分段传输，而非固定的 4 GiB 传输上限。 “完成”指已冻结的选定任务已完成，并不意味着所有历史 Telegram 记录都存在于存档中。聊天日志也可观察实时 更新；这两种模式均非原子快照。生成的截图和屏幕 录像不属于此模式的范围。

测试内容涵盖合成新登录、作用域隔离、媒体、取消操作、 部分截止时间完成、注销失败、受限的 API 路径和字段、 预加载工作区拒绝、密钥错误和篡改拒绝、必需的验证器 标志，以及浏览器/Python 加密互操作性。浏览器验收 测试使用了一个明确标记的模拟证明；这不是真正的 Sigstore 测试。 真实的托管运行器、Docker、GitHub 证明以及实时 Telegram 验收 测试的结果必须与本地合成测试的结果分开报告。

[GitHub Actions 条款](https://docs.github.com/en/site-policy/github-terms/github-terms-for-additional-products-and-features#actions) 规定托管运行器的使用仅限于软件项目的生命周期内。分叉操作 不会解除这些限制；不得将此预览版宣传为无限制的 免费生产环境托管服务。[Cloudflare Quick Tunnels](https://developers.cloudflare.com/tunnel/get-started/quick-tunnels/) 同样仅适用于测试和开发。helper/workflows 适合 用于评估此功能；生产环境的适用性仍是另一项 部署要求。

## 维护者发布

1. 提交并审查收集器、监督器、容器定义和测试。
2. 将该收集器提交固定在 `sealed-collector.yml`，然后提交/审查该 可重用工作流。切勿默认从调用者的 SHA 值推导出检出版本。
3. 将可重用工作流的提交固定在 `sealed-witness.yml` ，并将它的 workflow/collector SHA 对添加到 `sealed_policy.json` 可信发布中。
4. 发布所有被引用的提交以及辅助程序，然后测试一个独立的分支 以及真正的 GitHub 证书。除非重新生成并再次发布这些引用，否则请勿将 这些引用的提交合并掉。

有关调用者存储库与上游签名者之间的区别，请参阅[可重用工作流和确认声明](https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/increase-security-rating) 。
