参考 / 设置
Telegram · 连接、代理和数据保护
身份验证、自动代理池、IP 模式、备用策略、外部请求及密钥存储。
本文档描述了 TgWitness 0.9.3 的行为及其限制。身份验证、 源访问、网络连接和捕获完整性是独立的状态。 有关登录步骤、文件格式和多账户信息,请先参阅 账户和会话格式。有关事件策略和重启 行为,请参阅采集原理。
连接设置指南#
在更多工具→账户→连接路径中,管理员可选择此账户、账户 组或所有账户,然后选择一条路径。查看选择会列出 受影响的账户。准备并检查功能可在不更改 已保存路径的情况下测试建议的路径。应用已检查的连接会验证预览结果,在 必要时暂停监控,保存路径并恢复已运行的监控。 系统绝不会在先前处于空闲状态的账户中启动数据采集。历史数据下载将保持 暂停状态,并可单独恢复。切换前请暂停正在进行的导出操作。
群组更改默认会为每个账户保留其独立路径。仅当预览列表中显示了您期望的更改时, 才应清除该选项。 应用程序会报告每个 账户的结果;这并非跨数据库的“全有或全无”式操作。若 切换失败,该账户将恢复之前的设置。恢复失败的情况会 明确显示。预览有效期为十分钟,且连接 设置或群组成员资格的更改需要重新检查。
当“Apply”的路线、 模式和策略保持不变时,它会将成功的预检结果重复使用,有效时长最长为90秒。受管隧道仍必须保持相同的运行 进程。较早的检查结果、已更改的隧道进程以及自动MTProxy池路线 将重新进行检查。签名的应用程序记录会保留原始检查时间, 并记录重复使用情况及其有效期。每次预检都会关闭其临时未认证的 客户端;收集器则使用其自身的授权会话进行连接。
| 路径 | TgWitness 管理的内容 |
|---|---|
| 直接 | 来自主机的连接;未检测到外部主机 VPN,也未强制执行。 |
| VPN | 每个账户仅有一个全隧道 WireGuard 配置文件,由本地用户空间中的 SOCKS5 进程承载。不安装任何主机接口或驱动程序。 |
| 我的代理 | SOCKS5、HTTP CONNECT 或 MTProxy 凭据。SOCKS5/HTTP 字段可填写 URL。选择多个账户时,将共享此处输入的代理。 |
| 公开版 MTProto | 现有池分配Telegram路由。在高级设置中配置单独的合适代理之前,外部请求将被禁用。 |
| WARP | 为每个选定的账户建立独立的本地隧道,并将 WARP 注册信息和 WireGuard 配置文件保存在该账户的保险库中。 |
当前路由检查使用的是一个全新的、未经身份验证的 Telegram 传输通道,而非
该账户的会话。它通过该路由向
该账户的数据中心建立传输连接,并进行一次未经身份验证的 MTProto 往返通信
(req_pq_multi);该过程不会生成授权密钥,也不使用任何账户。
报告的延迟值等于连接时间加上往返时间,且该检查
会分别记录这两部分。对于支持 HTTP 的路由,它还会请求
通过该路由对 Cloudflare 的 HTTPS 追踪进行请求,并显示其报告的出口 IP、
国家/地区、WARP 状态和检查时间。除非追踪
报告 WARP 处于活动状态,否则 WARP 准备将失败。这些预检会报告路由连通性及
观察到的出口。请通过存档的采集和
验证结果审查捕获的记录。仅凭本地进程正在运行并不代表出口检查成功。
该面板会计算最近五次检查的移动平均值。当
该平均值超过5秒,或者连续三次检查超过该值时,该路由即被视为速度较慢;
若连续两次检查失败,则该路由被视为不可用; network.slow_route 并
network.route_recovered 记录这些变化。对于速度较慢的WARP路由,“重新掷骰WARP”
会重启该账户与其他Cloudflare WARP端点之间的隧道连接,保留
最快的连接,并记录 network.warp_rerolled 并记录其前后时间;
“新 WARP 身份”会注册一个新的 WARP 设备,并仅在该设备
速度更快时保留它。本地代理地址、Telegram 账户及其会话保持
不变;Telegram 连接将通过重启后的隧道重新建立。速度较慢的 WARP
路由最多每 30 分钟自动重启一次;若此举
无效,后续重启将等待操作员处理。
便携版 WARP 和 WireGuard#
这是一个 非官方的 WARP 集成 ,使用 wgcf 2.3.1 和 wireproxy 1.1.3 。 管理员需在首次下载或 WARP 注册之前明确接受该设置。 这些设置连接会直接连接到 GitHub 和 Cloudflare,并 泄露设备的 IP 地址。普通账户的流量在应用该设置前 仍保持原有路由。Cloudflare 会选择出口地址和国家;不同的隧道 可以共享同一个出口地址。该功能不提供国家选择、周期性 IP 轮换以及全主机范围的 VPN 杀开关功能。
支持下载的辅助程序:Linux 和 macOS x86-64/ARM64,以及 Windows x86-64。
会根据已审核源代码中捆绑的 SHA-256 哈希值对构建产物进行校验,
并在启动前再次对缓存的可执行文件进行校验。 任何辅助程序均不会被添加到
PATH 环境变量中,也不会作为系统服务安装,或配置为公开监听器。所有文件均位于
工作区下的 portable-routes/ 目录中,并存储在加密的保险库条目内。
环回监听器 SOCKS5 需要独立生成的凭据。
私有配置文件和 WARP 账户凭据使用现有的 工作区保险库进行加密。运行期间,辅助程序需要一份仅所有者可见的明文配置文件; 正常停止时该文件会被删除。主机崩溃可能会导致该文件残留在 仅所有者可见的数据文件夹中。这不会对磁盘进行加密,也无法防止 管理员访问。 如果面板的父管道 消失,监督程序将关闭隧道。失败的隧道绝不会启用直接回退。面板重启 将恢复选定的隧道;启动失败时,将在限定延迟后重试。 停止 隧道 也会暂停监视并保持已停止状态。 启动隧道 启动隧道;准备就绪后需单独恢复监视。
上传的 WireGuard 配置文件必须包含一个接口和一个对等节点、完整的 IPv4 和 IPv6 路由,且不得包含钩子、包含语句、环境变量替换或额外的 监听器。公共端点地址将在启动前解析并固定。 请使用外部 VPN 或 SOCKS5 网关来连接 OpenVPN/IPsec 及私有端点。
认证方法#
API ID 和 API 哈希用于标识应用程序;它们不能替代账户登录。 在 TgWitness 中,它们是可选的。优先级顺序为:表单中输入的一组,然后是来自 导入的账户 JSON 文件中的一组,接着是保存在工作区中的一组,最后是内置的 50 个 对,当Telegram拒绝某组时,系统将按随机顺序尝试并自动轮换。只有 Telegram Desktop密钥对(2040)会随匹配的Telegram Desktop客户端描述一同发送。 您可在my.telegram. org的API开发工具中生成的自有密钥对可用于所有账户;每个账户仍拥有独立的授权。
| 方法 | 要求 | TgWitness 支持 |
|---|---|---|
| 手机号、代码、可选的双因素认证 | 账户访问;API 对(可选) | 面板登录 |
| 认证密钥 HEX + DC ID | 完整的 512 个字符密钥和 DC 1–5 | “直接授权密钥”选项卡;在保存授权前,可选的“用户 ID”字段需先进行验证 |
| Telethon StringSession | 一个有效的会话字符串 | 面板登录 |
Telethon SQLite .session |
封闭式、连贯的文案 | 支持直接导入 7/8 版本的模式;可选离线命令行界面 (CLI) |
Pyrogram SQLite .session |
已关闭的生产环境用户会话 | 直接通过面板导入模式 2/3 |
| Telegram 桌面版 TData ZIP | 一个现代账户;若设有保护,则需输入本地密码 | 带校验和/解密校验的内存内转换 |
| 账户 JSON | 支持的 API/会话/密钥字段 | 仅凭元数据即可自动填充 API 凭据;但仍需通过会话/密钥或手机/二维码登录 |
| 二维码登录 | 来自授权 Telegram 应用的确认 | 本地 QR 码生成、过期/重试功能,可选双因素认证 |
| TDLib / Pyrogram StringSession | 其他特定于库的格式 | 不支持 |
| 机器人令牌 | 一个拥有独立访问/更新模型的机器人 | 此收集器未使用该工具 |
Telegram 负责选择代码交付方式,包括是否发送短信。API 哈希无法修复 已被撤销的会话,也无法替换遗忘的 2FA 密码。TgWitness 不会将 登录码或 Telegram 2FA 密码持久化到磁盘上。
对于私有源,该账户必须已具备访问权限。无需提供群组用户名。 代理或会话导入既不授予成员资格,也不授予管理员 权限。成员能否查看加入群组之前的聊天记录,由聊天设置决定。
导入 Telethon 会话文件#
Telethon SQLite、Pyrogram SQLite 和 Telegram Desktop TData 采用不同的格式。 该面板会检测并转换受支持的结构;重命名文件并不属于 转换操作。在文件下选择一个会话及其对应的 JSON 文件,点击检查文件,然后点击连接账户。最多接受四个匹配的文件, 总大小不超过 8 MiB。 有关 TData/JSON 的详细信息,请参阅格式限制。 不提供密码恢复功能。通过手机/双因素认证或二维码登录将创建独立的授权。
仅限 Telethon 的可选命令行路径仍然可用:
- 停止客户端使用原始会话,并制作一份一致的副本。该 转换器会拒绝包含未完成 WAL/日志的文件。请正确关闭原始 客户端,而非通过删除这些文件来绕过检查。
- 在 TgWitness 环境中,运行:
python -m tgwitness.sessions account.session --out account.tgwitness-session
- 在“添加账户”→“文件”下,加载结果或 粘贴其字符串,然后继续。
- 请核对显示的数字账户 ID,选择数据源并开始监控。
转换后的文件是一个未加密的账户访问密钥。 请将其保存在受保护的 存储位置,切勿将其提交或发送给第三方转换服务。TgWitness 会将其授权会话保存在加密保险库中。复制会话不会 创建单独的授权:请勿使用克隆的授权密钥运行多个客户端, 并假设它们能独立接收更新。
转换操作仅传递授权,而非原始消息、实体缓存或 持久化更新游标。它无法解决进程重启后的更新恢复问题。
MTProto、Telethon 和代理服务器#
MTProto 是 Telegram 的协议。Telethon 是 TgWitness 使用的 Python 客户端库。 MTProxy 是一个 Telegram 传输代理;SOCKS5 和 HTTP CONNECT 提供通用 隧道。这些均无法替代账户身份验证。
请在 更多工具 → 账户 → 设置 → 连接设置 → 更改连接路径 在 登录之前。新工作区默认设置为 自动 MTProxy · 公共列表 with 隐藏地址. 已显式使用直接模式的现有工作区将保留允许该模式的设置。
文件的读取是通过与读取消息不同的独立连接进行的,这与官方 应用的做法一致。在该账户所属的数据中心内,系统会复用该账户的授权密钥并 建立新的 MTProto 会话;对于其他数据中心,则在 账户连接期间生成并授权一个密钥,且该密钥仅保存在内存中。每个文件连接都使用与该账户相同的 路由。每个数据中心中的文件连接数量受“参数 → 性能 → “每个 Telegram 数据中心的文件连接数”所限制;若设置为 0,则仅通过账户的主 连接读取文件。同一安装环境下的所有账户 最多可同时建立五个 Telegram 连接。
IP 模式#
路由决定连接方式。面板中“账户” 部分的 IP 模式和 IP 保护功能,决定了服务器地址何时可能被暴露。这些控制功能不会 安装 VPN,也不会将设备的所有流量都通过该路由传输。
| 模式 | Telegram | 外部请求 |
|---|---|---|
隐藏地址(hide) |
请使用代理;若均无法连接,请稍候。无直接备用方案。 | 要求使用 SOCKS5/HTTP;拒绝未通过适用代理的请求。 |
直接操作仅作为最后手段(fallback) |
自动 MTProxy 可能会在配置的延迟时间过后使用 Direct,随后恢复使用正常工作的代理。 | 建议使用已配置的外部代理或该账户的 SOCKS5/HTTP 路由;否则允许使用“Direct”模式。 |
服务器位于隧道或 VPN 之后(tunnel) |
允许使用直连路径,并支持即时自动切换至备用池。 | 若未配置相应的代理服务器,则允许直接连接。 |
隧道或 VPN 模式假设您单独管理该网络。如果没有可用的 隧道,目标端将能看到服务器本身的地址。请根据 您的实际网络环境选择模式,而非仅依据选项名称。
选择路径#
| 路径 | 设置 | 边界 |
|---|---|---|
| 自动 MTProxy | 内置列表或运算符目录 | 维护一条可用的 Telegram 路由;直接备用方案取决于 IP 模式 |
| 直接 | 隧道或 VPN 模式 | Telethon 使用主机的网络路由 |
| SOCKS5 | 主机、端口、可选的用户名/密码 | python-socks,已启用远程目标 DNS 功能 |
| HTTP CONNECT | 主机、端口、可选的用户名/密码 | 仅支持纯 HTTP CONNECT;尚未实现与代理服务器本身的 TLS 连接 |
| MTProxy | 主机、端口、密钥 | 实验性 Telethon 传输协议;32 位十六进制数字或 dd + 32 位十六进制数字 |
虚假 TLS ee 密钥将被拒绝。Telethon 1.45 的规范化处理可去除前缀
和域名,但这并不实现虚假 TLS 功能。请粘贴 tg://proxy?server=…&port=…&secret=…
或 https://t.me/proxy?server=…&port=…&secret=…,并选择“从链接填充字段”。
这将在不建立连接或保存的情况下验证并填充字段;请单独审查并保存
路由。手动字段仍可使用。参见 Telegram 代理链接。
由您的安装环境提供的公共代理#
该内置列表整合了七个来源: SoliSpirit/mtproto、 zakky8/mtproto-proxy-pro、 kort0881/telegram-proxy-collector、 3yed-61/MTP-Collector、 Therealwh/MTPproxyLIST、 KhodeJav/telegram-proxy-collector 以及 tgmtproxy/telegram-mtproto-proxy-list。 该打包快照包含端点信息、来源归属及下载日期。 列表仅作为输入;下文的连通性检查将决定使用哪些代理。
自动 MTProxy 会检查 Telegram 传输连接状态,维持一个可用的代理, 并在代理失败时切换至另一个。当有足够多的 可用条目时,工作区会优先选择不同的代理;代理可以共享出口地址。失败的代理 会在再次尝试前进入休眠状态。如果所有代理均不可用,IP 模式将决定收集操作 是必须等待还是可以使用直接连接。 更换代理不会更改账户 也不会清除其日志。路由选择和变更都会记录在签名日志中。
当自动路由处于活动状态时,列表每小时刷新一次,传输检查默认 每十分钟运行一次。这些间隔时间均可配置。更新公共列表 会触发刷新;仅查看列表不会更改已保存的手动路由。
Telegram 流量和 HTTPS 请求使用不同的路由。列表下载使用
独立的 HTTPS 连接以及提供的外部请求路由。
TGWITNESS_PROXY_FEED_PROXY 会通过 HTTP/SOCKS5 代理显式覆盖该路由;
两种 Compose 收集器变体均会转发该路由。后台池遵循主工作区。
不会向数据源提供商发送任何 Telegram 会话、API 凭据、控制面板令牌或机器人令牌。
提供商名称、快照日期和下载路径会显示在“列表来源”部分。
MTProxy仅承载Telegram流量。工作区的HTTP操作(如时间戳、 通知、站外副本和源代码验证)在 已配置时会使用独立的SOCKS5/HTTP代理,否则则使用该账户的SOCKS5/HTTP路由。若两者均未配置,"隐藏地址"功能将拒绝 该请求;其他模式则允许"直接"连接。外部请求可被禁用。显式 配置的订阅源下载代理仍由操作员单独覆盖。 独立的见证服务保持其自身的路由。
对于由操作员管理的私有服务,现有的服务器环境设置
TGWITNESS_ALLOW_PRIVATE_DESTINATIONS=1 允许私有目标,并保持
代理端的主机名解析。该设置无法通过控制面板启用。仅限公共
模式会在查询公共解析器之前拒绝 .onion 目标;Tor 洋葱
服务需要明确的私有目标设置以及合适的代理。
此 DNS 行为适用于外部 HTTP 操作,不适用于 Telegram 的传输协议。
Cloudflare 提供了关于 JSON DNS 端点的文档。
自动池参数
在更多工具→参数→自动 MTProxy下,配置故障阈值、冷却时间、 计划轮换、代理共享和允许的备用延迟。
| 控制 | 默认 |
|---|---|
| 替换前断开连接 | 3 项,耗时 10 分钟 |
| 每次连接尝试中尝试的代理数量 | 3 |
| 首次 / 故障后最大恢复时间 | 10分钟 / 6小时 |
| 计划轮换 | 已禁用;失败时启用 |
| 每个代理的账户数量 | 0:优先单独条目,必要时合并。设置为 1 以等待独占条目。 |
| 允许直接回退前的延迟时间 | 10分钟;隐藏地址仍被直接拒绝 |
| 数据源刷新/传输检查 | 60 / 10 分钟;主工作区值适用于共享池 |
不同的代理可以共享一个出口地址。Telegram 的限制适用于每条路由。
若要用您自己的运营商目录替换公共列表,请配置以下覆盖设置。
这将完全禁用外部订阅,包括当其 proxies 数组为空时。
将空目录
复制到 proxy-config/proxies.json
,并添加您已部署的公共端点:
{"format": "tgwitness-proxy-catalog-v1", "proxies": [
{"id": "project-eu", "label": "Project EU",
"link": "tg://proxy?server=REPLACE_HOST&port=443&secret=REPLACE_SECRET"}
]}
必须替换示例值。最多接受 32 个不同的条目。 经过身份验证的列表会返回标签/主机/端口,无需共享密钥;选择其中一个 会将其凭据保存到工作区保险库中。在进行 明确的传输测试之前,可用性尚未经过测试。如果目录格式不正确,则可进行手动配置。
本地运行:将 TGWITNESS_PROXY_CATALOG 设置为本地 JSON 路径。Docker:
docker compose -f compose.yaml -f deploy/compose/compose.proxies.yaml up -d --build
该覆盖层以只读方式挂载 proxy-config;文件必须可被容器 UID 10001 读取。
该目录被排除在 Git、Docker 构建上下文和源代码归档之外。此
目录用于配置收集账户;Witness 机器人使用其自身的
HTTP/SOCKS5 路由,而非 MTProxy。
直接备用方案由上文所述的 IP 模式决定。在 更改路由前请暂停监控。保存操作将断开旧客户端的连接并取消未完成的登录;新 客户端将使用已保存的路由。该账户的日志/会话绑定关系保持不变。 设置将覆盖之前的路由:编辑时请重新输入代理凭据。
凭据采用network.enc加密。API不会返回用户名、
密码或密钥。签名记录包含路由类型以及凭据
是否存在,但不包含端点和密钥。操作员可在控制面板中查看端点。
密钥字段在保存、锁定或切换工作区后将被清空。
测试 Telegram 连接(登录前也可使用),通过该路径建立并关闭一个临时 未经授权的 Telegram 连接。该操作不会联系任何 IP 检测 网站。测试成功仅表示传输连接已建立,并不代表群组访问权限、消息 完整送达或匿名性。
该代理适用于 Telegram 客户端的连接,包括 Telegram 数据中心(DC)的媒体
下载。浏览器、pip、SSH 以及手动调用的 TSA 工具则采用独立路径。
代理主机名可在本地解析。rdns 影响目标主机名;
Telegram 通常提供数据中心(DC)的数值 IP 地址。
SOCKS5 和普通 HTTP CONNECT 本身不会对代理凭据或 客户端到代理的隧道进行加密。MTProto 会单独保护 Telegram 流量。在不可信网络上,请使用 适当的安全通道连接到代理。私人群组 是传输过程中受 MTProto 保护的云聊天;端到端秘密聊天是一种独立的聊天 类型,由秘密聊天模块进行记录。
加密与签名#
| 层级 | 已实现 | 操作员责任 |
|---|---|---|
| Telegram 流量 | Telethon MTProto | 平台可信度、传输路径及可用性 |
| Web 控制面板 | 持有人令牌、默认回环设置、请求限制 | 通过 HTTPS 或 SSH 隧道进行远程访问 |
| 秘密 | Fernet 用于管理 API 凭据、会话、代理凭据及签名私钥 | 保护解密密钥和运行主机 |
| 保险库密钥 | 新安装时使用本地密钥或外部主密钥 | 独立的受保护存储空间和密钥备份 |
| 消息和附件 | 明文应用程序存储 | 加密磁盘/卷 |
| ZIP/JSONL/CSV/HTML | 完整性校验,不进行内容加密 | 保护导出的副本和传输内容 |
| 来源与时间 | 签名日志、流程收据、RFC 3161 工具 | 可信密钥、独立检查点/TSA 及保管流程 |
“账户”中的存储保护功能会显示这些状态。面板令牌是一种 访问密钥,而非加密密码。它授予管理员访问权限; 已签发的令牌可限定在特定账户和聊天群组范围内。工作区共享 主机进程,并非独立的租户。
BitLocker、LUKS、FileVault 或受管加密卷可在 各自的威胁模型下保护存储数据。 已解锁且正在运行的机器的管理员 仍然可以读取数据。在存储规划中应将 SQLite WAL/SHM、媒体文件、临时导出文件、交换文件、备份 以及浏览器下载内容纳入考虑范围。Docker 卷仅因其 是卷这一事实,并不意味着它已被加密。
外部主密钥#
对于新安装,请将主密钥放置在数据目录之外。 此操作不会自动迁移现有的本地密钥库。请准备一个 仅服务身份可访问的密钥目录,然后运行:
python -m tgwitness.security create-master-key /private/keys/tgwitness-master.key
export TGWITNESS_VAULT_KEY_FILE=/private/keys/tgwitness-master.key
python -m tgwitness --data-dir /private/observations/new-case
PowerShell,使用已安装的项目环境:
python -m tgwitness.security create-master-key E:\PrivateKeys\tgwitness-master.key
$env:TGWITNESS_VAULT_KEY_FILE = 'E:\PrivateKeys\tgwitness-master.key'
python -m tgwitness --data-dir E:\PrivateData\new-case
在 Docker 中,将文件以只读方式挂载到 /data 之外(例如
/run/secrets/tgwitness-master.key),并将环境变量设置为该路径。
该服务的 UID 必须具备读取权限。请通过
环境/配置文件传递路径,而非密钥字节。
每个工作区都会获得一个随机的公共盐值,以及通过
HKDF-SHA256 派生出的专属 Fernet 密钥。vault.external.json 仅存储派生元数据,而非主密钥。
若密钥缺失或错误,系统将无法启动,且不会在后台自动替换密钥。请同时保留
盐值元数据和主密钥以备恢复之用。
所有工作区均源自同一主密钥;若主密钥遭泄露,将影响整个 安装环境。运行中的进程可解密机密信息。本工具并非硬件安全模块(HSM)或 密码密钥派生函数(KDF)。不接受使用任意人工设置的密码代替随机密钥。
在有计划的迁移
实施并验证之前,请保留现有安装中的现有密钥。删除 vault.key 或替换主密钥可能会导致
无法访问会话/签名密钥。请将加密备份与密钥分开存放,并
在隔离的环境中测试恢复功能。