# 工作流程与操作

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

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

首次连接时，请[使用账户和会话格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/)。 有关保存版本、事件策略和数据缺失的说明，请参阅 [“数据采集原理](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/)”。本指南涵盖日常操作和数据恢复。

## 操作员工作流程

流程图 · 选择存储方式和密钥保护方案 → 使用其令牌打开面板; 使用其令牌打开面板 → 选择工作区; 选择工作区 → 配置直连或代理路径; 配置直连或代理路径 → 输入手机号码或选择文件 / 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/)。