工作流程与操作

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

操作员工作流程#

图表转为文本

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

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

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

开放访问功能可为审核员或分析师分配专属令牌。选择其可访问的 账户和聊天群组，随后授予查看、导出或操作权限。 负责启动/停止数据收集的操作员需要整个工作区的访问权限；审核员 的访问范围可限制为单个聊天群组。会话限制、有效期和 IP 规则与 Telegram 账户授权相互独立。请参阅访问与权限。

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

运行模式#

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

监控类别#

在“来源”→“捕获设置”→“选择要保留的更改”中，可独立选择新消息、编辑、 删除通知、反应更新和成员事件。默认 设置保留所有类别。“消息、编辑和删除”选项在保留原始上下文的同时， 会禁用单独的反应/成员更新。 “所有可见活动”选项将恢复 全部五类记录。预设会更改显示形式；点击“保存监控设置”以应用更改。

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

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

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

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

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

通知#

打开“来源”→“通知”→“警报”即可查看每日摘要。TgWitness 使用 Apprise 将警报发送至 Matrix、Telegram、Discord、Slack、ntfy、电子邮件及其他 受支持的服务。您可以在一个工作区中添加多个目标。

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

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

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

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

面板布局#

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

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

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

“来源”部分包含监控范围（选定的聊天、Telegram文件夹或整个 账户）、各类可访问的聊天、带有优先级星标标记的选定来源、附件 及重新检查设置，以及历史快照。私有来源通过对话/ID 进行选择，不包含公开链接。“访问状态”描述的是最近一次检查结果，而非永久权限。

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

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

Witness 会生成只读的见证令牌，显示每个见证者最后一次检查的时间，并 提供运行一个（独立见证者）所需的命令和选项。

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

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

账户注册从手机号码字段开始。继续操作将直接进入 验证码输入环节，仅在缺少 API 凭据时才会要求输入。二维码和文件导入是 其他选项卡。已保存的 API 凭据仅在所属工作区内重复使用。 登录界面没有侧边栏、统计数据或设置说明。 “设置” 图标可打开 API、代理、存储及附加账户控制选项。新安装 从这里开始；已连接但未选择消息源的账户则从“选择聊天”开始。 更改路径需要暂停监控，并会取消未完成的登录操作。现有 日志无法在用户不知情的情况下重新绑定到其他 Telegram 账户。

导出功能会检查日志的完整性，并生成可移植文件。其工作区 ID 可传递给下载命令行界面（CLI）。每次导出都会锁定完整的日志前缀；后续 事件将进入下一次导出。搜索过滤器不会改变包的范围。 详细的签名和覆盖范围信息请参见“验证与限制”部分。

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

用户界面采用本地资源和文本渲染来呈现源内容。已对桌面版和窄屏 Chromium 布局进行了测试。这并非完整的无障碍认证； 屏幕阅读器及人工可用性评估仍需另行进行。

部署环境#

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

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

启动检查与导出#

在启动预配置环境之前，请运行 python start.py --check。添加 --json 以进行机器可读的检查，或传入预期的 --data-dir、--host 和 --port。 该命令会在无需登录 Telegram 或创建日志的情况下检查先决条件。 它不会验证日志或证明捕获准备就绪；日志验证将在 应用程序启动时进行。已占用的端口可能只是现有实例。

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

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

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

备份、恢复与中断#

1. 暂停监控并干净利落地终止该进程。
2. 复制整个数据目录：数据库、WAL/SHM（如有）、媒体文件、 credentials.enc、signing.enc、network.enc、保险库密钥/元数据、令牌、 检查点以及所有profiles/目录。
3. 对于外部密钥模式，请将主密钥单独保存，并保留每个 vault.external.json。生成新密钥无法恢复旧的密钥。
4. 在目标端停止运行时进行恢复；配置原始密钥、限制 访问权限，并在恢复运行前验证完整性。
5. 记录系统停机时间及验证结果。历史快照无法证明 在中断期间未发生任何删除操作。

证据 ZIP 文件不包含会话数据/私钥，且并非完整的服务备份。 以下四类内容采用不同的保护方式：

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

连接恢复事件并不保证能够恢复期间的更改。 持久化媒体任务和 Telegram 更新位置在重启后仍会保留；请参阅 证据格式。

容量与保留期限#

默认限制（均可在“参数”中修改）：前 1,000 个对话，每个快照 500 条消息 ，4 GiB 未压缩的签名 ZIP 内容（更大压缩包需使用 verify.py --max-gib N），以及 128 MiB 的浏览器备用方案。 附件在“来源 → 附件”下，每种类型占用 1–2,000 MiB。 下载 CLI 的默认传输量为 5 GiB。可用磁盘空间可能为 下限。请为日志、媒体、WAL、临时导出和备份预留空间。 导出使用数据卷，而非 Compose 的 512 MiB /tmp。

应测量每秒事件数、队列年龄、媒体数据字节数和磁盘延迟，而非仅统计 群组数量。合成本地基准测试无法保证 Telegram 的消息送达。 系统不支持自动保留和删除。删除日志尾部将使其 与已保留检查点之间的关联失效。

优先级重新检查功能已存在：默认情况下，标星的来源每 15 分钟重新检查一次， 其他来源每 6 小时重新检查一次（参见重新检查级别）。如上所述， 提供受密码保护的导出功能。 Telegram/代理实时接收、持久回放、 管理员日志和反应轮询、隔离工作进程、由 TgWitness 自身对本地日志和媒体 进行的加密以及独立审查仍属独立工作。范围限定访问权限 详见“访问与权限”文档。 请参阅 READINESS.md、LIVE_ACCEPTANCE.md 和 VERIFICATION.md。