帳戶與會話格式

TgWitness 透過 MTProto 協議，使用 Telethon 以 Telegram 用戶帳戶（而非機器人）身分登入。每個帳戶皆位於獨立的工作區中（在 API 和命令列工具中稱為「工作區」），並擁有專屬的會話、來源、日誌及簽名金鑰。

會話檔案、會話字串及認證金鑰均屬帳戶授權憑證：凡 持有其中任何一項者，皆可代表該帳戶進行操作。這些資料不包含訊息歷史紀錄。

[!警告] 請勿使用任何您無法承受損失的資料。我們強烈建議不要連結 個人帳戶或其他重要帳戶，也不要使用您重視的帳戶來建立 API ID 或 API 雜湊值。 這並非因為 TgWitness 未經測試：Telegram 會以不可預測的方式限制並 永久封禁帳號——只要其認為請求量 過高，無論使用何種客戶端或出於何種目的，且未提供充分的文件說明。許多封禁 措施皆無法撤銷。 請使用專用帳號。測試能否順利進行取決於 Telegram，而非 軟體本身，且無法保證後續運作無虞。

• 一覽
• 開始之前：API ID 與 API 雜湊值
• 電話號碼 · QR 碼 · 授權金鑰 + DC 識別碼
• 帳戶檔案: 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 個字母），平台選「桌面版」。 網址與描述欄位可留空。
4. 請複製 App api_id（一個數字）和 App api_hash（32 個十六進位字元）。

在登入表單下方的面板中，會顯示「API ID + Hash」。您可將一組 api_id:api_hash 組合貼上至 API ID 欄位，系統便會自動填入兩個欄位。同一組組合可 適用於您所有的帳戶。成功登入後，該組合將以加密形式儲存於 該工作區內，且絕不會傳回瀏覽器。

涉及三種不同的憑證：

若必須透過代理伺服器連線至 Telegram，請先前往「 帳戶」→「設定」→「連線設定」→「變更連線路徑」進行設定。

電話號碼#

1. 開啟「帳戶」頁面，切換至「電話」分頁，並以國際格式輸入號碼， 例如 +44 7700 900123。空格和連字號會自動移除。
2. 按下「繼續」。API ID + Hash 欄位可留空。
3. 請輸入 Telegram 發送的驗證碼（通常發送至 Telegram 應用程式；無法保證會透過簡訊發送）。
4. 若該帳號啟用了兩步驟驗證，請輸入該密碼。此密碼並非控制面板 代幣，亦非裝置通行碼。
5. 登入後請確認顯示的帳號 ID，然後選擇資料來源。

登入代碼與雙因素驗證 (2FA) 密碼絕不會寫入磁碟。

QR 碼#

當該帳號已在手機或另一台電腦上登入時，請使用此功能。

1. 點擊「QR 碼」→ 顯示 QR 碼。API ID + Hash 欄位可留空。
2. 在已登入的裝置上：設定 → 裝置 → 連結桌面裝置，掃描條碼 並確認。
3. 若 Telegram 要求，請在 TgWitness 中輸入雙因素驗證 (2FA) 密碼。

此 QR 碼圖像係於本地端產生。QR 碼會過期；請按「產生另一個 QR 碼」 以重新嘗試。若鎖定面板、切換工作區或啟動另一組登入程序，將取消 待處理的 QR 碼。

授權金鑰 + DC 識別碼#

授權金鑰（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 使用已匯入的會話期間保持該副本關閉。 請直接退出程式，切勿登出或撤銷該會話： 撤銷操作也會使已匯入的副本失效。若您需要同時運行兩個客戶端， 請透過手機或 QR 碼登入 TgWitness 以建立其專屬授權。建議使用專用 帳戶，但這並不能確保複製的金鑰在並行使用時是安全的。

此規則同樣適用於匯入的 .session 檔案、StringSession 文字及 Auth Key HEX。 其他擁有獨立建立之授權的用戶仍可保持登入狀態。 請參閱 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 憑證；您可透過手機或 QR 碼登入，或新增一個會話 檔案。系統不接受批次清單（帳戶的 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)，屆時兩個程式都將無法運作。
• 已過期或遭撤銷的連線無法透過轉換恢復。請重新登入。

疑難排解#

另請參閱：代理伺服器與加密的連線及安全性， 以及登入後資料擷取的運作方式。