# 架构

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

收集器、控制面板、日志、工作进程和见证程序的组成部分，以及数据在它们之间如何流动。

一个 Python 进程托管 FastAPI 控制面板和任意数量的隔离工作区， 每个工作区都配有一个 Telethon 用户账户客户端。 SQLite 存储着一个仅支持追加的、经过签名的事件日志以及可变的操作设置。 加密保险库中存储着 API 凭据、StringSession 以及签名密钥。 前端采用打包的纯 HTML/CSS/JavaScript 形式：无需 Node 构建、CDN 或运行时 前端下载。

| 模块 | 责任声明 |
| --- | --- |
| collector.py | 授权、对话选择、更新、快照、媒体队列、连接监控 |
| interactions.py / telegram_client.py | 明确的面板操作、带签名的收据、持久的请求 ID 以及针对特定任务的回调/加入重试策略 |
| message_content.py | 可视化消息对比，不包含传输访问元数据 |
| workers.py | 在取消操作前，请等待导出文件处理程序完成 |
| store.py | WAL 事务、有序事件链、查询过滤器、运行设置 |
| 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/<id>/ 目录中。一个承载令牌控制整个安装环境；工作区并非 独立的授权租户。 进程锁保护目录；数据库锁 对事件插入进行序列化。每次追加操作均以FULL同步模式 同步提交至SQLite WAL。事件更新/删除触发器可防止 普通应用程序进行编辑；文件系统管理员始终处于信任边界之内。

API 授权采用承载令牌（bearer token）机制。登录操作经过序列化处理，并受时间限制。 账户上传采用专用的 12 MiB 编码正文限制和 8 MiB 解码文件 限制；普通 API 请求仍保留 16 KiB 的限制。 转换在工作 线程中运行，将上传数据保存在内存中，并将规范化的输入返回给经过身份验证的 浏览器。二维码登录具有每个工作区的候选项、短效标识符、等待任务 以及显式取消机制。仅被接受的授权才会成为活动客户端。 Telegram FloodWait 会返回 Retry-After 值；凭据和原始 RPC 错误消息不会在 API 错误中暴露。导出操作在异步事件 循环之外运行，并按工作区进行序列化。它们流式传输稳定的读取快照，并可 与持续进行的 WAL 写入共存。 工作区收集器共享同一进程/事件循环。

当前的历史快照与实时更新可能存在重叠。两者均为独立的观察记录， 并按来源进行标注；重复内容不会被自动合并。系统不会根据缺失的 ID、伪造的已删除文本、强制成员枚举或自动加入群组 等情况进行推断。

有关面向操作人员的说明，请参阅[“数据采集原理”](https://phishdestroy.github.io/TgWitness/zh/docs/reference/collection/) 以及[“账户与会话格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/accounts/)”。

网络配置存储在加密保险库中。应用路由会关闭旧的 客户端并取消未完成的登录；后续连接将使用该路由，且不 提供直接的备用方案。 新的外部密钥安装会通过 HKDF-SHA256，基于主密钥文件和存储的随机盐值，为每个工作区生成 Fernet 密钥。这将 密钥与数据目录分开保护，而非将日志/媒体内容以明文形式存储。

本地演示入口使用单独生成的进程权限，绝不使用已配置的 面板令牌。签发和接受需明确启用演示模式，使用不包含额外工作区或授权会话的合成根 节点，采用环回对等方/主机，且不包含代理 转发头，也不进行跨源浏览器请求。 正式版 API 保留承载者 身份验证，并在演示模式下拒绝收集更改。