TData）¶

当前支持：

Telethon 压缩包：.json + .session
单个或批量 .session 文件
Telethon StringSession
TData 压缩包：tdata 目录（含 key_datas / D877F783D5D3EF8C*）

适用版本：当前开发版起，导入页支持在上传前选择账号分类、设备指纹、自动分配已有 WARP 或创建一对一受管 WARP；Telegram 客户端连接会按账号和 API 类型稳定选择一组匹配的设备参数。

上传前先选择首次连接出口¶

页面会先要求选择：

已启用的现有代理
逐账号批量代理（仅 Zip）
自动分配已有 WARP
创建一对一 WARP
已配置的全局代理
明确直连
导入后分类（可选）

所选路由会在 Session 验证前生效。验证、读取账号资料、写入 Session 和正式绑定使用同一出口；未选择、代理无效或没有可用 WARP 时，会在连接 Telegram 前停止，不会静默回退为面板直连。

导入完成后路由会持久化到账号：选择“已有代理”会长期绑定所选 ProxyId，选择“全局代理”会保存为全局继承，选择“直连”会明确关闭全局继承。除非在账号管理中手动切换，导入时选择的已有代理不会在后续连接中自动变成直连或换成全局代理。

选择“逐账号批量代理”时，每个账号会长期绑定对应行新增或复用的代理。该模式只适用于 Zip 导入，不适用于 Session 文件和 StringSession 导入。

选择“自动分配已有 WARP”时，系统只会从代理管理中已启用、状态为“运行中”且未被其他首次连接流程占用的 WARP 中选择。优先分配当前绑定账号数较少的 WARP；每个导入条目完成后会重新计算，因此批量导入会在现有 WARP 间尽量均衡分配。该模式不会创建 Docker 容器或数据卷，也不会在无可用 WARP 时回退直连。

选择“创建一对一 WARP”时，系统会在每个账号首次 Telegram 验证前创建一个新的受管 WARP 容器和代理记录，验证成功并入库后把该 ProxyId 长期绑定到账号。单次最多 10 个账号；超过上限会在创建 Docker 资源前拒绝。该模式需要已启用受管 WARP：Linux Docker 环境、Docker Socket 可用，且 WARP Compose 覆盖或 Proxy:Warp:Enabled=true 已生效。TP_WARP_MAX_MANAGED_PROXY_COUNT 和容器资源模板同样会限制导入时的新建容器。

成功判据是导入结果成功、账号保持启用并显示新建 WARP 的代理编号和出口 IP。若 Session 验证、代理绑定或账号保存未完成，未绑定账号的新 WARP 代理会自动删除；运行档案会保留为 deleted 状态用于审计，不再占用代理列表。失败时先检查 Docker Socket、WARP 镜像拉取、端口/网络和数量上限。回滚方式是改选“自动分配已有 WARP”“已有代理”或全局代理；已成功绑定的独立 WARP 可在账号切换到其它出口后到代理管理中手动删除。

更多说明见代理管理与账号出口。

导入时选择分类¶

在导入页的“导入后分类”选择框中，可以选择已有账号分类或保留“未分类”。Zip、Session 文件和 StringSession 三种导入方式都会把该分类随请求提交到服务端；成功导入的新账号会直接写入所选 CategoryId，导入结果表也会显示分类。

前置条件是已在账号列表或分类管理中创建需要的账号分类。分类管理页顶部提供“账号批量改分类”操作栏，可按分类或账号信息筛选、勾选当前筛选结果，再批量改为某个分类或“未分类”；该操作只修改已选账号，不会覆盖某个分类的全部成员。成功判据是导入完成后账号摘要显示所选分类，进入账号列表或分类管理页按该分类筛选能看到新账号。失败排查优先确认分类仍存在、导入请求未被取消、服务端返回的导入结果是否成功；批量改分类失败时确认已勾选账号且目标分类未被删除。回滚方式是在账号列表或分类管理页批量修改分类为“未分类”或其他分类；该功能不涉及数据库迁移。

账号编号¶

导入或手动登录成功后，面板会为账号分配用户可见的账号编号，并在账号列表、账号分类、任务账号选择器、任务详情和风控确认中显示为 #编号。支持账号来源切换的任务表单会先选择“账号分类选择”或“账号编号填写”，切到“账号编号填写”后可填写这些编号；支持每行一个，也支持英文逗号 ,、中文逗号 ，、顿号 、 或分号分隔。该模式与账号分类二选一，不再合并执行。内部接口路径和数据库关联仍使用账号 Id。删除账号后空出的编号可被后续新账号复用，因此不要把编号当作长期不可变外部主键。

成功判据是导入/登录成功摘要和账号列表都显示同一个 #编号，按 #编号 搜索能定位账号，任务表单切到“账号编号填写”并填写该编号时不会提示“账号编号不存在或不可操作”。失败排查先确认数据库迁移已执行，且账号仍为启用状态；回滚方式是恢复到 v1.31.56 或更早版本，旧版会继续使用内部账号 ID，不展示 #编号。

Telegram 设备参数¶

面板创建导出独立 session 时，先读取该账号当前 Telegram 授权的 app_version、device_model 和 system_version，并把这三个值注入导出客户端；因此导出的新授权会沿用当前设备指纹，不再因为 WTelegram 默认值变成 PC 64bit。若当前授权读取失败或字段为空，才按账号 ApiId 和 Session 路径使用同客户端族的安全回退画像。

前置条件是账号 Session 有效，且面板能读取 account.getAuthorizations。成功判据是在账号详情的“在线设备”中，新导出授权的应用、设备型号和系统版本与导出前当前授权一致。失败排查先确认当前设备列表能正常加载，再检查账号代理和 Session；回滚方式是恢复到 v1.31.65，导出将恢复为按 ApiId/Session 稳定选择回退画像，不涉及现有 Session 文件格式迁移。

导入时选择设备指纹¶

导入页的“导入后设备指纹”会列出侧栏「设备指纹」中的启用画像。选择结果会随 Zip、Session 文件和 StringSession 请求提交，并保存到账号的 DeviceProfileKey；留空时账号连接使用系统默认画像。手机号登录和二维码登录也会在首次连接前提供“本次登录设备指纹”选择，成功入库后保存到账号。

前置条件是已在侧栏「设备指纹」确认可用画像。成功判据是导入或手动登录结果成功后进入账号详情，仍显示所选画像；清空账号画像并保存后，详情显示“跟随系统默认”。失败排查检查画像 key 是否被停用、数据库迁移是否完成和客户端缓存是否已清理；回滚方式是改回系统默认或恢复到迁移前版本并保留数据库备份。画像变更不会改写现有 Session，下一次创建 Telegram 客户端时生效。

Zip 逐账号批量代理¶

批量 Zip 可以同时提交一组 HTTP 或 SOCKS5 代理。每行一个地址，例如：

http://user-a:password-a@proxy-a.example.com:8080
socks5://user-b:password-b@proxy-b.example.com:1080
# 空行和以 # 开头的行仅用于分隔或备注
http://proxy-c.example.com:3128

配对规则如下：

空行和以 # 开头的注释行不计入代理数量。
有效代理行按输入顺序形成槽位；重复地址不会去重，仍分别占用一个槽位。
Telethon 包按 .json 文件的规范化 Zip 相对路径稳定排序；纯 TData 包按 tdata 目录的规范化 Zip 相对路径稳定排序。路径分隔符统一为 /。
排序后的第 1 个账号使用第 1 个代理槽位，依次一对一配对。账号数与有效代理行数必须完全一致，否则整个请求失败。
输入仅支持 HTTP 和 SOCKS5。相同端点和认证信息可以复用已有代理；相同端点但认证信息不同会停止导入，不会覆盖可能已被其他账号使用的代理。

系统会先解析完整 Zip、校验数量并检测全部代理出口。只有全部检测成功且代理记录已经持久化后，才会向第一个 Telegram 账号发起连接。任一代理格式、数量、凭据冲突或出口检测预检失败时，不会新增任何代理、不会连接任何 Telegram 账号，也绝不会回退到面板直连。

代理预检完成后，各账号仍会独立验证 Session 或 TData。某个账号后续验证失败时，其他账号可继续处理；已经持久化但没有成功绑定账号的对应代理会保留在代理管理中，并显示为未使用，方便检查、复用或手动清理。

导入 Telethon 压缩包¶

单账号结构¶

account.zip
  ├─ 8613111111111.json
  ├─ 8613111111111.session
  └─ 2fa.txt            # 可选，内容为二级密码

批量结构¶

accounts.zip
  ├─ 8613111111111
  │   ├─ 8613111111111.json
  │   ├─ 8613111111111.session
  │   └─ 2fa.txt
  └─ 8615119714541
      ├─ 8615119714541.json
      └─ 8615119714541.session

规则说明：

每个账号目录内只要能找到 1 个 .json + 1 个 .session 即可导入
2fa.txt 为可选；若存在则会优先作为该账号二级密码
目录名、文件名建议使用手机号，便于排查

导入 Session 文件或 StringSession¶

.session 文件支持一次选择多个；StringSession 通过页面文本框导入。这两种方式使用 GET /api/panel/settings 返回的有效 Telegram API 池：内置官方 API 默认排在最顶上，也可以在「系统设置」添加自建 API；导入成功后，账号会保存本次分配到的 ApiId/ApiHash，后续不会被全局池子覆盖。

只提供 .session 时，系统会尝试从会话读取账号身份；如果 Session 已失效或格式不兼容，该条目会导入失败，不会写入一个看似成功但无法连接的账号。

导入 TData 压缩包¶

支持 Zip 内包含 tdata 目录（可单账号，也可批量多目录）。

示例（单账号）：

tdata-account.zip
  └─ tdata
      ├─ key_datas
      ├─ D877F783D5D3EF8C
      └─ ...

示例（批量）：

tdata-accounts.zip
  ├─ acc-a
  │   └─ tdata
  │       ├─ key_datas
  │       └─ D877F783D5D3EF8C
  └─ acc-b
      └─ tdata
          ├─ key_datas
          └─ D877F783D5D3EF8C

注意：

导入 TData 前，系统会使用当前有效 Telegram API 池；未关闭内置官方 API 时可直接回退使用，批量 TData 会按启用的 API 池轮询分配
首次导入 TData 时会自动准备解析依赖，耗时会比普通导入长一点

查看导入结果¶

结果分为成功、部分成功和失败。部分成功表示账号资料已经完成验证，但正式代理绑定或托管资源收尾失败；账号会保持停用并显示具体错误，不会在未知出口上继续连接。

逐账号批量代理的结果还会显示 Zip 内账号来源、代理原始行号、代理 ID、脱敏代理名称和检测到的出口 IP。响应不会返回 proxyText 原文、代理用户名、密码或 Secret。

导入后操作入口¶

导入页只展示本次导入结果和已导入账号摘要，不提供刷新状态、踢设备、加群、改资料、换绑邮箱等批量操作入口。导入成功后必须进入账号列表，按分类、Telegram 状态和代理出口确认后再执行批量操作。

成功判据是导入结果出现账号摘要，且页面只显示“去账号列表操作”和“清空”；如果需要继续处理账号，点击“去账号列表操作”。若发现入口缺失，刷新页面或直接访问 /accounts。回滚该页面行为只需恢复导入页批量操作模板，不涉及数据库、Session 或接口迁移。

Docker 部署下导入文件存储位置¶

导入成功后，会话文件统一写入：

./docker-data/sessions/

不要手工改名或删除该目录中的文件，避免账号会话失效。