账户与会话格式

TgWitness 通过 MTProto 协议以 Telegram 用户账户（而非机器人）身份登录，使用 Telethon 实现。每个账户都位于独立的工作区中（在 API 和命令行工具中称为“工作区”），并拥有独立的会话、消息源、日志和签名密钥。

会话文件、会话字符串和认证密钥均属于账户授权凭证：任何 持有者均可代表该账户进行操作。这些凭证不包含消息历史记录。

[!警告] 请勿使用任何您无法承受损失的内容。我们强烈建议不要连接 个人账户或其他重要账户，也不建议在您珍视的账户上 创建 API ID 或 API 哈希。 这并非因为 TgWitness 未经测试：Telegram 会以不可预测的方式限制并 永久封禁账号——仅因其认为请求量 过大，无论使用何种客户端或出于何种目的，且未提供充分的说明文档。许多封禁 都是不可逆的。 请使用专用账号。测试能否顺利进行取决于 Telegram 自身，而非 软件本身，且无法保证后续使用不会出现问题。

• 一览
• 开始之前：API ID 和 API 哈希值
• 电话号码 · 二维码 · 认证密钥 + DC ID
• 账户文件: Telethon .session · Pyrogram .session · 会话 + JSON 对 · TData · StringSession · 账户 JSON
• 识别您拥有的内容 · 不受支持的格式
• 多个账户 · 确保账户文件的安全 · 故障排除

一览#

TgWitness 根据文件内容而非文件名来识别文件。重命名文件 绝不会导致其被转换。

开始之前：API ID 和 API 哈希值#

您无需创建 Telegram API 应用程序即可登录。当未输入、 未导入或工作区中尚未保存任何密钥对时，TgWitness 会从其内置的 50 组公开 API 密钥对（tgwitness/api_pool.py）中按随机顺序选取一组。 如果 Telegram 拒绝某对密钥 （API_ID_INVALID、API_ID_PUBLISHED_FLOOD、UPDATE_APP_TO_LOGIN），则尝试下一对， 每次登录最多尝试八对；被拒绝的密钥对将被跳过，直至重启。用于登录的密钥对将 与该账户一同保存，并供该账户重复使用。API ID 和 API 哈希用于向 Telegram 标识该应用程序；它们 本身并不对账户进行授权。

若要改用您自己的应用程序（注册该应用的账户将面临风险； 参见 “为何要使用内置 API 池？”）：

1. 打开 my.telegram.org，并使用您拥有的任意手机号码 登录。验证码将发送到 Telegram 应用中，而非通过短信。
2. 选择 API 开发工具。
3. 创建应用程序：任意标题和简称（5–32 个字母），平台为桌面版。 URL 和描述可留空。
4. 复制 App api_id（一个数字）和 App api_hash（32 个十六进制字符）。

在登录表单下方的面板中，有“API ID + 哈希”字段。您可以在 API ID 字段中粘贴一组 api_id:api_hash，两个字段将自动填充。一组 即可用于您所有的账户。成功登录后，该信息将以加密形式保存在 该工作区中，且绝不会发回浏览器。

涉及三种不同的凭证：

如果必须通过代理访问 Telegram，请先在 “账户”→“设置”→“连接设置”→“更改连接路径”中进行设置。

电话号码#

1. 打开“账户”选项卡，选择“手机”标签页，并以国际格式输入号码， 例如 +44 7700 900123。空格和连字符将被自动去除。
2. 点击“继续”。API ID 和哈希值可留空。
3. 输入 Telegram 发送的验证码（通常发送至 Telegram 应用；短信接收无法保证）。
4. 如果该账户启用了双重验证，请输入该密码。这并非控制面板 令牌，也不是设备密码。
5. 登录后查看显示的账户 ID，然后选择消息来源。

登录凭据和双因素认证（2FA）密码绝不会写入磁盘。

二维码#

当该账户已在手机或另一台计算机上登录时，请使用此功能。

1. 点击“QR 码”→ 显示 QR 码。API ID 和哈希值可留空。
2. 在已登录的设备上：设置 → 设备 → 关联桌面设备，扫描二维码 并确认。
3. 若 Telegram 要求输入双因素认证（2FA）密码，请在 TgWitness 中输入该密码。

该二维码是在本地生成的。二维码会过期；请点击“生成另一个二维码 ”重新尝试。锁定面板、切换工作区或开始另一轮登录操作将取消 待处理的二维码。

认证密钥 + DC ID#

授权密钥（Auth Key）是每个 Telegram 会话背后的 256 字节原始授权数据，以 512 个十六进制字符的形式表示，并附带数据中心编号 DC 1–5。

1. “Auth key”选项卡。请粘贴完整的密钥；包含“…”的缩短版密钥无法使用。
2. 请选择随密钥提供的 DC ID。
3. 可选输入用户 ID。若 Telegram 报告的 账户信息不一致，TgWitness 将拒绝连接。
4. Press Connect 账号。

授权密钥（512 个字符）并非 API 哈希（32 个字符）。同一密钥也可 以 JSON 格式导入，详见“账户 JSON”。

账户文件#

打开“添加账户”→“文件”，选择最多四个属于同一账户的文件（总大小不超过 8 MiB），然后点击“连接账户”。

• 文件在您的 TgWitness 服务器内存中进行转换。上传内容不会被存储， ZIP 文件不会解压到磁盘，也不会连接任何外部服务。
• 生成的会话记录随后将与 Telegram 进行核对。如果文件中包含用户 ID， 则该 ID 必须与 Telegram 报告的账户信息一致。
• 描述不同账户或不同 API 凭据的文件将被拒绝 而非仅选择其中一个。
• “密码”或“会话文本”字段包含 TData 本地密码字段，该字段用于粘贴 StringSession 以及在未登录的情况下读取文件（无需 联系 Telegram 即可填写表单）。

Telethon .session#

请先关闭创建该文件的程序。如果其旁边存在 my_account.session-journal 或 my_account.session-wal，则表示数据库尚未最终确定：请正常打开并 关闭原始客户端。删除这些辅助文件可能会导致副本损坏。

Pyrogram .session#

登录时，系统会将存储的用户 ID 与 Telegram 进行比对。

会话 + JSON 对#

账户通常以两个同名文件的形式分发，例如 447700900123.session 和 447700900123.json。请同时选中这两个文件。

• 根据 JSON 信息，TgWitness 使用 app_id/api_id 和 app_hash/api_hash，因此您 通常无需手动输入 API 凭据。
• 其他字段（如 phone、device、sdk、app_version、lang_pack 或已保存的 twoFA 密码）将被忽略。如果该账户启用了双因素认证（2FA），TgWitness 会要求输入验证码。
• 单个 JSON 文件仅为元数据。若无会话文件，请继续通过手机 或 QR 码登录。

Telegram 桌面版 (TData)#

TData 是 Telegram Desktop 应用程序（来自 desktop.telegram.org 的跨平台 应用程序）中的 tdata 文件夹。

导入方法：

并行会话警告。导入 TData 会复用 Telegram Desktop 的授权 密钥；它不会创建独立的登录账号。请勿在 Desktop 和 TgWitness 中同时使用该密钥。Telegram 可能会因 AUTH_KEY_DUPLICATED 导致授权失效，使两个副本均无法使用，直至进行新的登录。

请完全退出 Desktop 程序（包括其系统托盘进程），并在 TgWitness 使用导入的会话期间保持该程序关闭。 请退出程序，切勿注销或撤销会话： 撤销操作也会使导入的副本失效。如果您需要同时运行两个客户端， 请通过手机或二维码登录 TgWitness 以创建其独立的授权。建议使用 专用账户，但这并不能确保克隆密钥在并行使用时是安全的。

这同样适用于导入的 .session 文件、StringSession文本及认证密钥十六进制值。 其他拥有独立创建的授权的客户端可以保持登录状态。 请参阅Telegram的AUTH_KEY_DUPLICATED文档。

1. 完全退出 Telegram Desktop。

2. 从 tdata 中提取仅包含以下两项内容的 ZIP 压缩包：

   • key_datas
   • 其旁以 s 结尾的 16 个字符的文件，通常为 D877F783D5D3EF8Cs

   将整个文件夹及其媒体缓存打包为 ZIP 文件通常会超出限制 （512 条记录，解压后 32 MiB）。 3. 在“文件”中选择该 ZIP 文件。如果 Telegram Desktop 设置了本地密码，请先在 “密码”或“会话文本”栏中输入该密码。这并非双因素认证（2FA）密码。

支持功能：每个存档仅限一个账户，采用现代key_datas/key_data0/key_data1存储技术， 本地密码保护。不支持功能：包含多个已登录账户的文件夹、旧版桌面 布局、受密码保护的ZIP文件，以及独立的原生macOS应用“Telegram for macOS”。

Telethon StringSession#

一行文本，通常以 1 开头，长度约为 350 个字符。请将其 作为 .txt 或 .tgwitness-session 文件（最大 4 KiB）加载，或将其粘贴到 “通行码”或“会话文本”下方。仅接受 Telethon 字符串；Pyrogram 和 TDLib 字符串采用不同的格式。

账户 JSON#

一个 JSON 对象，大小不超过 64 KiB，存储在以 .json 结尾的文件中。

如果同时存在别名和主名称，两者必须一致。示例：

{ "app_id": 1234567, "app_hash": "0123456789abcdef0123456789abcdef" }

{
  "api_id": 1234567,
  "api_hash": "0123456789abcdef0123456789abcdef",
  "auth_key": "REPLACE_WITH_ALL_512_HEXADECIMAL_CHARACTERS",
  "dc_id": 2,
  "user_id": 123456789
}

第一个示例仅需填写 API 凭据；您可通过手机或二维码登录，或添加会话 文件。不支持批量列表（即账户的 JSON 数组）。

识别您拥有的内容#

不受支持的格式#

多个账户#

点击账户选择器旁边的 +，或打开 “账户” → “设置” → “连接设置” → “工作区”，输入标签并 登录。

• 支持任意数量的工作区，包括主工作区。每个工作区都有独立的会话、代理 路由、消息源、捕获策略、日志、签名密钥、检查点和导出功能。
• 切换显示的工作区不会暂停其他工作区。
• 日志始终与创建它的账户绑定。使用其他 账户登录需要另一个工作区，且一个账户不能分配给两个 工作区。
• 主面板令牌可控制所有工作区。授予的访问权限可将其他用户的访问范围限制在选定的账户和聊天群组内，并可设置独立的权限和会话限制。
• 账户会重命名一个工作区，并删除一个已添加的工作区，连同其会话、日志、 来源和签名密钥一并删除。主工作区无法从面板中删除。

批量导入和账户分组#

使用 账户 → 导入账户 添加多个账户，按基本文件名配对文件，并查看每次登录的结果。每个账户都有独立的工作区。分组可从模板复制选定的设置，而不会合并会话、密钥或证据。请参阅导入和分组指南和MTProxy 池控制面板。

退出登录#

“账户 → 退出 Telegram（暂停监控）”会要求 Telegram 结束该 会话，因此该会话也会从账户的“设置 → 设备”中消失，并从 工作区保险库中移除。日志、来源、设置和签名密钥将保留，且 日志会记录此次退出操作。 该工作区仍归属于其账户：只有该 账户才能再次连接到它。如果 Telegram 没有响应，该会话仍会在此处被移除， 面板上也会显示相应提示；请在 Telegram 的“设置”→“设备”中结束该会话。

将 Telethon 会话转换为离线格式#

该面板可直接导入 .session 文件。若需离线转换为 StringSession 文件，请在项目文件夹中运行：

.venv\Scripts\python.exe -m tgwitness.sessions account.session --out account.tgwitness-session   # Windows

.venv/bin/python -m tgwitness.sessions account.session --out account.tgwitness-session          # Linux/macOS

该转换器仅读取 Telethon SQLite 文件（最大 64 MiB），绝不修改输入内容， 不进行任何网络请求，且拒绝覆盖现有的输出文件。

确保账户文件的安全#

• 请将每个 .session、TData ZIP、StringSession、Auth Key 和账户 JSON 视为 密码。TgWitness 会将导入的授权信息保存在其加密保险库中；您可以在 之后删除原始文件。
• 请勿在两个程序中同时运行同一授权。Telegram 可能会撤销该授权 (AUTH_KEY_DUPLICATED)，导致两个程序均无法运行。
• 已过期或被撤销的会话无法通过转换恢复。请重新登录。

故障排除#

另请参阅：代理和加密的连接与安全设置， 以及登录后数据采集的具体工作原理。