# Telegram · 工作流程与操作

Canonical page: https://phishdestroy.io/tgwitness/zh/docs/reference/operations/

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

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

[Documentation index](https://phishdestroy.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.io/tgwitness/zh/docs/reference/deployment/)

![部署与恢复](https://phishdestroy.io/tgwitness/assets/chapter-operate.svg?v=7039a376d47f)

首次连接时，请[使用账户和会话格式](https://phishdestroy.io/tgwitness/zh/docs/reference/accounts/)。 有关保存版本、事件策略和数据缺失的说明，请参阅 [“数据采集原理](https://phishdestroy.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.io/tgwitness/zh/docs/reference/operations/#operator-workflow)
- [在不共享主密钥的情况下共享工作成果](https://phishdestroy.io/tgwitness/zh/docs/reference/operations/#share-work-without-sharing-the-main-key)
- [运行模式](https://phishdestroy.io/tgwitness/zh/docs/reference/operations/#runtime-modes)
- [监控类别](https://phishdestroy.io/tgwitness/zh/docs/reference/operations/#monitoring-categories)
- [通知](https://phishdestroy.io/tgwitness/zh/docs/reference/operations/#notifications)
- [面板布局](https://phishdestroy.io/tgwitness/zh/docs/reference/operations/#panel-layout)
- [部署环境](https://phishdestroy.io/tgwitness/zh/docs/reference/operations/#deployment-environments)
- [启动检查与导出](https://phishdestroy.io/tgwitness/zh/docs/reference/operations/#startup-checks-and-exports)
- [备份、恢复和中断](https://phishdestroy.io/tgwitness/zh/docs/reference/operations/#backup-restore-and-interruptions)
- [容量与保留期限](https://phishdestroy.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.io/tgwitness/zh/docs/reference/access/)。

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

## 运行模式

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

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

## 监控类别

![支持按账户设置监控参数，并提供合成源数据](https://phishdestroy.io/tgwitness/assets/sources.png?v=761b8bfa296c)

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

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

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

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

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

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

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

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

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

## 通知

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

1. 每行输入一个 Apprise 目标 URL。请根据您使用的服务 [，参考服务目录和 URL 格式](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.io/tgwitness/assets/connection.png?v=c8781089fe29)

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

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

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

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

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

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

**更多工具 → 扩展功能 → 独立见证人**会生成只读的见证令牌，显示每个见证人上次检查的时间，并 提供运行[独立](https://phishdestroy.io/tgwitness/zh/docs/reference/witness/)见证人的命令和选项。

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

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

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

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

在“收集器状态”面板中，会显示收集器状态、排队/失败的媒体文件、最旧的待处理媒体文件、可用 磁盘空间、请求暂停情况，以及访问状态未确认的来源。**这些**详细信息初始状态为折叠状态，并在“账户”页面中被隐藏。一个设置 卡片会显示下一步操作：连接账户、选择来源或开始监控。 账户列表为加载时的快照； 所选工作区会定期刷新。这并非多进程 SLA 监控工具。

界面使用本地资源，并以文本方式呈现源内容。已测试 Chromium 中的桌面布局和窄屏布局。

## 部署环境

| 环境 | 安装 | 验证状态 |
| --- | --- | --- |
| Windows 个人电脑/服务器 | Python 3.11+、scripts\Setup.cmd/Start.cmd、私有数据目录 | 已在 Windows/Python 3.12 环境下本地测试 |
| Linux 服务器/VPS | Python venv、专用服务用户、HTTPS/SSH | 提供了代码、持续集成（CI）及 systemd 示例；未在此主机上运行 |
| macOS | Python venv、前台进程或用户代理 | 提供了 launchd 示例；需单独进行安装验证 |
| Docker/Compose | 持久卷，一个工作节点 | 提供定义和 CI 运行时检查；本地无法使用 Docker |
| 手机浏览器 | 连接到正在运行的服务器上的受保护控制面板 | 已测试窄屏 Chromium 布局；数据采集器不支持 iOS/Android 系统 |

可移植性意味着无需强制使用云服务或构建前端。每个目标系统仍 需要兼容的 Python/加密依赖项、本地磁盘及网络访问权限。请参阅 [DEPLOYMENT.md](https://phishdestroy.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. 记录停机时间及验证结果。停机时间始终作为记录中的间隔存在； 历史快照则会添加其后的状态。

Evidence ZIPs exclude sessions/private keys and are not full service backups. `tgwitness backup FOLDER` makes the same copy while the panel keeps running and leaves out the search index, which rebuilds itself; see [Updates and backups](https://phishdestroy.io/tgwitness/zh/docs/reference/deployment/#updates-and-backups). Four things are protected differently:

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

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

在连接恢复事件发生后，收集器会从 已保存的更新位置请求缺失的更新。持久化媒体任务和 Telegram 更新位置在重启后仍会保留；参见 [证据格式](https://phishdestroy.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` 目录。

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

优先复查已经可用：带星标的来源默认每 15 分钟复查一次，其他来源每 6 小时复查一次（参见[复查层级](https://phishdestroy.io/tgwitness/zh/docs/reference/collection/#recheck-tiers)）。受密码保护的导出按上文所述工作。限定范围的访问记录在[访问与权限](https://phishdestroy.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.io/tgwitness/zh/docs/reference/verification/)。
