# Telegram · 访问与权限

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

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

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

[Documentation index](https://phishdestroy.io/tgwitness/zh/llms.txt)

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

[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/quickstart/)

![入门指南](https://phishdestroy.io/tgwitness/assets/chapter-start.svg?v=443547f9bcd2)

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

[账户设置](https://phishdestroy.io/tgwitness/zh/docs/reference/accounts/) · [连接路径](https://phishdestroy.io/tgwitness/zh/docs/reference/connection/) · [安全模型](https://phishdestroy.io/tgwitness/zh/docs/reference/security/)

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

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

访问权限可打开选定的工作区、其中选定的聊天、所有 工作区，或某个 [账户组](https://phishdestroy.io/tgwitness/zh/docs/reference/accounts/#bulk-import-and-account-groups)中的所有账户。**所有工作区， 包括后续添加的工作区**，也涵盖未来的账户。组访问权限同样 涵盖后续添加到该组的账户。若需将某个 案例的访问范围限定在特定工作区内，请明确选择相应的工作区。

## 授予某人访问权限

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

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

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

## 选择权限

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

| 许可 | 功能介绍 |
| --- | --- |
| `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` |

“访问”表单的初始预设还包括“案件看板”：审核员可读取、分析师可读取 和写入，操作员可进行管理。预设仍可编辑，且现有权限不会 自动扩展。有关继承的聊天范围和导出隐私设置，请参阅[“案件看板”](https://phishdestroy.io/tgwitness/zh/docs/reference/case-board/)。

## 限制与会话

| 设置 | 工作原理 |
| --- | --- |
| 并行会议 | 将同时在线会话数限制在 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 会话、签名密钥和数据目录的私密性。见证令牌 是一个独立的检查点/健康凭证，而非面板访问令牌。
