TgWitness / 文档

已测试的内容 →

参考 / 设置

Telegram · 访问与权限

设置账户和聊天室的访问权限范围,选择权限类型,限制会话和 IP 地址,并撤销访问权限。

TgWitness / 文档 · 入门指南

入门指南

可授予审阅者访问某个聊天记录的权限,授予分析师导出案件的权限,或授予 操作员对选定账户的控制权。每个人都会获得专属令牌。主 控制面板的令牌由管理员持有。

账户设置 · 连接路径 · 安全模型

两个应用场景,两种不同的任务#

采集范围决定了账户的记录内容:选定的聊天、Telegram 文件夹或整个账户。访问范围则决定了其他用户可以查看和使用哪些已记录的 账户和聊天。授予访问权限并不意味着加入 Telegram 聊天、开始采集或授予 Telegram 账户权限。

访问权限可打开选定的工作区、其中选定的聊天、所有 工作区,或某个 账户组中的所有账户。所有工作区, 包括后续添加的工作区,也涵盖未来的账户。组访问权限同样 涵盖后续添加到该组的账户。若需将某个 案例的访问范围限定在特定工作区内,请明确选择相应的工作区。

授予某人访问权限#

  1. 以主管理员身份登录,并打开更多工具→访问。
  2. 在“授予某人访问权限”下,请输入一个您在日志中能认出的名字。
  3. 选择工作区,并在必要时选择具体的聊天室。
  4. 选择此人可能采取的行动。操作视图始终包含在内。
  5. 根据需要设置有效期、登录/会话限制以及允许的地址。
  6. 点击“创建访问权限”。请立即复制该令牌:该令牌仅显示一次。
  7. 请私下发送控制面板地址和令牌。收件人只需在常规登录页面输入该令牌 即可;他们无需您的主控制面板令牌,也无需 Telegram 会话。

请在单独的浏览器会话中打开包含已生成令牌的面板,并在移交前检查 可见的聊天记录及允许的操作。

访问名称保存在加密的本地存储中,并由管理员面板进行解析。 新创建的访问和工作区审计记录中省略名称;现有的签名记录保留其原始字段。

选择权限#

如需进行纯文本的公开演示,请使用“公开展示”而非普通 审阅者访问权限。它会显示明确选定的公开频道、保留的编辑和 删除记录,以及经过签名的统计数据,其中作者字段将被遮盖,文件将在 API 边界处关闭。创建并验证展示内容。

许可 功能介绍
view 可查阅获准访问的聊天记录、捕获的消息、个人资料、文件以及经过筛选的日志记录。这些内容始终包含在内。
export 允许导出聊天记录和档案。导出整个工作区的证据需要具备对整个工作区的访问权限。
sources 管理消息源、快照和个人资料捕获。受聊天限制的访问权限仅限于允许的聊天;全账户范围的消息源发现和范围设置保持关闭状态。
collect 启动或停止采集器。由于采集操作会影响该账户,因此需要整个工作区的访问权限。
interact 在访问权限范围内执行受支持的 Telegram 交互操作。受限于聊天范围的访问权限无法使用全账户范围的链接预览功能。
settings 可更改采集设置、时间戳、通知、异地副本及各项参数。需具备整个工作区的访问权限。
account 登录或退出 Telegram 并管理连接路径。需要整个工作区的访问权限。
board.read 仅在允许的工作区和聊天记录内阅读“案件板”笔记。
board.write 可添加书签、高亮标记、片段、评论以及“已打开”/“已审查”状态。此外还需使用 `board.read` 功能。
board.manage 管理数据集、团队最终状态以及其他参与者的卡片。此外还需要对白板的读写权限。

只有主管理员才能下载异地副本恢复密钥。 被授权的settings或account访问权限不会授予该密钥。

权限和范围将一并核查。勾选某项权限不会 打开其他聊天记录,也不会为仅限特定聊天记录的访问权限解锁工作区范围的操作。 若要进行并行导出,访问权限必须涵盖所有选定 账户中的被导出聊天。已授予的访问权限无法创建新访问权限、管理他人的 会话或打开管理员控制台。

三种实用的配置方案#

人物 范围 权限
审稿人 某案例的记录聊天内容 view
分析师正在准备工作交接 待调查和导出的聊天记录 view、export;仅当需要通过 Telegram 进行操作时才添加 interact
采集操作员 精选完整工作区 view、sources、collect;仅在需要时添加 settings 或 account

“访问”表单的初始预设还包括“案件看板”:审核员可读取、分析师可读取 和写入,操作员可进行管理。预设仍可编辑,且现有权限不会 自动扩展。有关继承的聊天范围和导出隐私设置,请参阅“案件看板”。

限制与会话#

设置 工作原理
并行会议 将同时在线会话数限制在 1–100 之间。达到上限时,拒绝下一次登录请求或终止最旧的会话。
允许登录 限制使用该令牌成功启动会话的次数。即使最后一次允许的登录已被使用,现有会话也不会因此终止。
有效期至 访问权限设有绝对有效期。过期的访问权限无法登录或继续发起请求。
无活动记录 会话闲置超时,范围从 5 分钟到 30 天。成功请求会延长该时限;打开的面板可通过轮询保持活动状态。
允许的地址 接受特定的 IP 地址或 CIDR 子网。若未填写,则允许任何地址,除非已启用首次登录绑定功能。
绑定至首次登录 首次成功登录后,系统将锁定该访问的授权地址。

IP 地址是应用程序所识别的客户端地址。若位于反向代理或 隧道之后,请在依赖 IP 规则之前,先检查“打开的会话”中显示的地址: 否则,可能会出现多名用户看似共享同一代理地址的情况。

更改或撤销访问权限#

在“已授予的访问权限”下编辑某条目,以更改其作用域、权限或限制。 后续请求(包括 来自已打开会话的请求)将验证作用域和权限的变更。撤销访问权限将终止其会话 并使已签发的令牌失效。通过“打开的会话”,管理员还可以 在不撤销整个访问权限的情况下终止单个会话。

已保存的导出副本保留其创建者、工作区、聊天范围及所需权限。 已授予访问权限的用户仅在相关权限仍有效期间,才能列出或下载其自身的副本; 包含案例看板的副本还需具备board.read权限。管理员可检索所有副本。 不包含此元数据且无组打包的旧副本仅限管理员访问。下载凭证 和预备文件响应会在文件准备就绪后、发送字节之前重新验证访问权限。 每个访问者(包括管理员)在每个工作区中最多可持有十个待处理下载凭证; 工作区范围内的上限为1,000个。凭证在120秒后过期,且仅限一次性使用。

撤销操作无法召回用户已下载的文件。注销、 锁定面板或结束会话均不会停止正在运行的收集器。

管理员可见的内容#

审核员和分析师收到的数据采集进度信息中不包含代理端点、 池诊断信息、服务器路径或原始连接错误。连接诊断 需要对整个工作区拥有account权限。读取通知、 异地副本和参数设置需要settings权限。

访问会话中不会保留完整的浏览器User-Agent字符串。升级后, 这些字符串也会从可变会话缓存中移除。控制面板进程日志会屏蔽 IP字面量、URL凭据和标记机密。本地服务日志和 先前已签名的日志记录不会被重写。访问规则和已签名的 登录记录仍使用客户端地址。

替换主密钥#

请使用更多工具→访问→我的限制→重新签发管理员密钥,或在控制面板运行期间,从受管安装环境中运行 tgwitness token rotate。 所有现有浏览器会话都将终止,包括使用同事 令牌打开的会话。请求的浏览器将获得一个新会话;请在隐藏新管理员 密钥之前将其保存下来。已签发的同事令牌在被单独撤销前始终有效。 使用TGWITNESS_TOKEN的安装环境必须修改该环境变量并重启。

请求与代理边界#

该 API 允许每个客户端和凭据类别(包括: 面板、存档/MCP 或见证)每分钟最多发起 600 次请求。这些类别的身份验证冷却时间是分开计算的。 一分钟内十次身份验证被拒绝将触发指数级冷却时间,从一秒 起,最长可达五分钟。冷却时间结束后若尝试失败,冷却时间将延长;若十分钟 内未发生失败尝试,则重置递增机制。拒绝请求将返回 HTTP 429 状态码, Retry-After。配额存储在内存中,由同一面板进程内的各个工作区共享; 重启后配额将被清零。实时流每个承载令牌限开四个, 每个面板进程限开32个。打开流也会消耗API请求配额。

请求正文的接收时限为60秒,登录、演示访问、 归档API和witness-head路径的时限缩短至10秒, MCP传输的时限为8秒。每个应用程序允许 每个客户端地址拥有四个未完成的请求正文,预留 路由配额的总体限制分别为32和64 MiB。 无正文的请求不占用这些配额。正文超大将返回 413,超时将返回408,超过客户端容量将返回429并附带Retry-After: 1。 当整体正文容量耗尽时,将返回状态码503,并包含Retry-After字段。

除非实际的 TCP 对等方属于 TGWITNESS_TRUSTED_PROXIES(以逗号分隔的 IP 地址或 CIDR 范围),否则将忽略转发 IP 报头。将 TGWITNESS_PROXY_HEADER 设置为 x-forwarded-for 或 cf-connecting-ip。XFF 将 从最近的代理向第一个不受信任的对等方进行遍历。 格式错误或重复的 受信任地址元数据将被拒绝,因此无法继承白名单中的代理 地址。受管理的快速隧道 信任本地 Cloudflare 连接器;自有域配置则信任本地 Caddy。 直接部署默认不信任任何代理。如果您自行启动 Uvicorn, 请禁用其代理标头处理功能,以便该边界能接收实际的对等节点。

TGWITNESS_PANEL_ALLOWED_IPS 将所有控制面板访问权限(包括管理员权限) 限制为列出的 IP 地址或 CIDR 范围。安装程序的路由标识探针保持公开状态, 且不返回任何账户数据。在 启用白名单之前,请包含所需的本地管理路由。受管安装的 START-HERE 指南包含 服务配置和恢复说明。

API 中的 ws 查询选择器必须在请求路径中标识工作区; 未知、不匹配或重复的选择器将被拒绝并返回 404 状态码。

面板脚本和样式包含 SHA-384 完整性元数据。导入映射还 涵盖了在支持 import-map 完整性的浏览器中本地导入的 JS 模块。 动态生成的语言响应是独立的。这些检查可检测 相对于交付页面的资源替换;页面本身及其哈希值 来自面板服务器,因此请保护该服务器及其交付路径。

自启动以来生成的日志将进程日志与每个 工作区的日志活动相结合:登录、拒绝、路由变更和操作员操作。这是一个 针对当前进程的内存控制台,而非每条消息的永久副本。 高频消息事件会保留在日志中,而非填满控制台。

授予、更改和撤销访问权限,以及启动或结束会话,也会生成 经过签名的access.*日志记录。这些记录中不包含令牌。 已发放的令牌和会话凭据将作为哈希值保存在加密保险库中。

待处理的 QR 登录属于发起该登录的面板会话。 终止或 撤销该会话,或轮换主面板令牌,将取消服务器上的待处理 QR 客户端。当浏览器无法发送其自身的 取消请求时,此规则同样适用。令牌轮换还会取消直接 使用主面板令牌启动的 QR 登录。正在等待另一项操作的 QR 请求会在开始前 再次检查访问权限。已完成的 Telegram 授权以及由另一个面板会话 启动的待处理登录将予以保留。

主要管理员与信任边界

主面板令牌不受限制。使用该令牌进行浏览器登录会创建会话, 这些会话受管理员配置的会话限制约束。直接发送 主令牌的脚本仍保留完全访问权限,且不计入浏览器会话。

这是单个安装环境中的应用层访问控制。所有工作区共享 服务器进程;这并不意味着与主机管理员隔离。请确保主 令牌、Telegram 会话、签名密钥和数据目录的私密性。见证令牌 是一个独立的检查点/健康凭证,而非面板访问令牌。