# Telegram · 帳戶與會話格式

Canonical page: https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/

可透過手機、QR 碼或授權金鑰登入，匯入 Telethon、Pyrogram 或 Telegram Desktop 的會話紀錄，並同時管理多個帳戶。

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

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

可透過手機、QR 碼或授權金鑰登入，匯入 Telethon、Pyrogram 或 Telegram Desktop 的會話紀錄，並同時管理多個帳戶。

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

![開始使用](https://phishdestroy.io/tgwitness/assets/chapter-start.svg?v=443547f9bcd2)

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

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

> [!警告] **請使用專用帳戶。**Telegram 會針對其認為過量的請求量進行限制，甚至可能永久封禁帳戶， 無論客戶端或用途為何，且僅部分公開相關限制規範。 請連接專為觀察準備的帳戶，而非 個人或其他有價值的帳戶，並在專用 帳戶上建立 API ID / API 雜湊值。

- [一覽](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#at-a-glance)
- [開始之前：API ID 與 API 雜湊值](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#before-you-start-api-id-and-api-hash)
- [電話號碼](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#phone-number) · [QR 碼](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#qr-code) · [授權金鑰 + DC 識別碼](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#auth-key--dc-id)
- [帳戶檔案](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#account-files): [Telethon .session](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#telethon-session) · [Pyrogram .session](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#pyrogram-session) · [會話 + JSON 對](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#session--json-pair) · [TData](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#telegram-desktop-tdata) · [StringSession](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#telethon-stringsession) · [授權金鑰與 DC 需置於同一行](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#auth-key-and-dc-in-one-line) · [帳戶 JSON](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#account-json)
- [釐清您所擁有的內容](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#identify-what-you-have) · [不支援的格式](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#unsupported-formats)
- [多個帳戶](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#multiple-accounts) · [確保帳戶檔案安全](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#keeping-account-files-safe) · [疑難排解](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#troubleshooting)

## 一覽

| 您現有的內容 | 「**新增帳戶**」分頁 | 您還需要 |
| --- | --- | --- |
| 電話號碼及其登入代碼的存取權限 | **電話** | 若已啟用，則為雙因素驗證 (2FA) 密碼 |
| Telegram 已在另一台裝置上開啟 | **QR 碼** | 若已啟用，則為雙因素驗證 (2FA) 密碼 |
| `.session` 檔案（Telethon 或 Pyrogram） | **檔案** | 可選的 JSON 檔案，用於應用程式設定 |
| `.session` + `.json`（名稱相同） | **檔案**（請選取兩者） | 通常沒有其他內容 |
| Telegram 桌面版中的「`tdata`」資料夾 | **檔案**（ZIP 壓縮檔） | 若已設定，則為桌面版本機通行碼 |
| 一場 Telethon StringSession（文字、`.txt`、`.tgwitness-session`） | **檔案** | 無需額外配對的 API |
| 授權金鑰與 DC 應合併為一行，格式為 `<512 hex>:<1–5>` | **檔案**（貼上內容或文字檔案） | 無需額外配對的 API |
| 一個附帶會話或認證金鑰的 `.json` | **檔案** | 無需額外配對的 API |
| 一個授權金鑰（512 個十六進位字元）及其 DC 編號 | **授權金鑰** | 可選使用者 ID |

TgWitness 根據檔案**內容**而非檔案名稱來識別檔案。重新命名檔案 絕不會導致其轉換。

## 開始之前：API ID 與 API 雜湊值

您無需建立 Telegram API 應用程式即可登入。當未輸入、 未匯入或工作區中尚未儲存任何密鑰對時，TgWitness 會從其內建的 50 組公開 API 密鑰對池中選取一組（`tgwitness/api_pool.py`），在首次登入時會優先選用 Telegram Desktop 的 密鑰對，並優先保留已儲存的密鑰對；其餘候選密鑰對則會隨機排序。若 Telegram 拒絕某組密鑰對 （`API_ID_INVALID`, `API_ID_PUBLISHED_FLOOD`, `UPDATE_APP_TO_LOGIN`)，系統將嘗試下一組， 每次登入最多嘗試八組；遭拒絕的配對將被跳過，直至重新啟動。成功登入的配對將 與該帳號一同儲存，並供該帳號重複使用。

內建的配對組合是公開的：它們已發佈於 Telegram 客戶端和函式庫的開源程式碼中。**API ID** 和 **API 雜湊**值用於向 Telegram 識別該應用程式，但不會授予存取帳戶資料的權限。登入過程使用帳戶自身的授權機制：登入 碼和雙因素驗證 (2FA) 密碼，或是該帳戶已授權的會話。每 `observation.started` 記錄中皆會標明所使用的密鑰對，因此內建密鑰對在 法庭上的記錄方式，與您自訂的密鑰對相同。您亦可改為透過 my.telegram.org 輸入自訂的密鑰對。 根據本專案的經驗，新增個人密鑰對通常會導致多數帳戶登出，因此請僅在 案件需要您使用自有應用程式時才使用：請使用專用帳戶建立密鑰對，並 在資料蒐集開始前輸入（步驟如下）。

若缺少連線欄位，則使用捆綁的 [opentele2 2.0.0 目錄](https://github.com/DedInc/opentele2/tree/7e973bc71cd7a714ad13ac703c0895a90d36a735)中預設的確定性裝置/作業系統組合： 桌面版 `2040`、Android `6`、Android X `21724`、iOS `10840`、macOS `2834` 以及 Web `2496`。 Android 的原始碼建置 ID `4` 亦採用 Android 目錄，此資訊可於 [Telegram Android 的 BuildVars](https://github.com/DrKLO/Telegram/blob/master/TMessagesProj/src/main/java/org/telegram/messenger/BuildVars.java) 中查證。 Web 預設為 A；若導入 `K` 應用程式版本後綴或 `macos` 語言套件，則選取 K；版本 `0.7.0` 則選取 Webogram。未知應用程式 ID 將維持 Telethon 的主機 預設值。導入的欄位始終具有優先權，包括較舊的應用程式版本及空的 語言套件。目錄絕不會變更 API ID/雜湊值。其版本快照會 經過明確審查，而非於登入時自動擷取。儲存的設定檔在更新後仍保持穩定。

`account.getAuthorizations` 會回報 Telegram 儲存的授權元資料；這 並非每次執行 `initConnection` 時的即時回響。請將其與實際傳送的設定檔進行比對。 連接現有授權並不會驗證其對應的 API 雜湊值： `initConnection` 會傳送 API ID，而雜湊值則用於登入請求。

在進行新的手機或 QR 碼授權後，TgWitness 會依序請求設定檔、最近的資料中心、 線上狀態、語言（當語言套件不為空時）、應用程式更新及 服務條款更新，各次請求間隔為 0.3 至 1.5 秒。 更新狀態 會短暫將帳戶標記為線上。此序列僅在登入完成時執行一次， 不會在資料匯入、重新連線或重新啟動時執行。授權資訊會優先儲存；若請求失敗， 序列將停止執行，不會重試或捨棄該次登入。結果會 記錄為 `account.initialized`，內容為錯誤名稱而非回應正文。 Telegram 的自身政策決定帳戶限制。

對於 `tdesktop` ，若未指定 `tz_offset` ，則會使用伺服器的本地 UTC 偏移量，並透過 [opentele2 演算法](https://github.com/DedInc/opentele2/blob/7e973bc71cd7a714ad13ac703c0895a90d36a735/crates/opentele2-core/src/fingerprint.rs) 四捨五入至 900 秒 （MIT；授權條款見 `tgwitness/client_profiles.LICENSE` ）。此值會在每次 連線時更新，以反映夏令時變更。在所有平台上，已匯入的 `tz_offset` 均具有優先權，且會精確保留（包括零值）。其他 `initConnection.params` 項目則予以保留。 HTTP 登入表單接受檔案匯入所回傳的數值時區； 布林值、小數以及超出支援範圍的偏移量均會被拒絕。

直接、SOCKS5 及 HTTP CONNECT 路由均採用 Telethon 的 `ConnectionTcpObfuscated` （經混淆的簡化版 MTProto）。HTTPS CONNECT 維持與代理伺服器之間的 TLS 連線，並在隧道內使用 相同的混淆傳輸協定。MTProxy 則維持其所需的 隨機化中間傳輸協定與密鑰處理機制。路由切換時亦採用 相同的選項。 混淆處理會改變封包的幀結構；它並不會向 Telegram 隱藏 帳戶或其客戶端元資料，亦不表示能免受限制。

在連線授權客戶端後，TgWitness 會檢查設定、最近的資料中心、 當前授權狀態、已審核的層級基準、語言、應用程式更新 以及服務條款更新。 這些診斷程序會針對每個客戶端實例執行一次， 且在資料蒐集之前進行，並會連同執行時間一併顯示於連線詳細資訊中。 `account.connection_checked` 會記錄結果，但不會包含會話雜湊值、IP 位址、 憑證或 API 雜湊值。這些程序絕不會接受條款或安裝更新。若發生 請求失敗或 FloodWait 狀態，後續請求將停止；若缺少結果，則該項將保持未知狀態。 本地檢查仍可回報其結果，而網路檢查則會被跳過。 若啟用「[嚴格選擇聊天室](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/collection/#strict-chosen-chats)」功能，系統將不會 請求當前授權狀態，且該檢查會顯示為已跳過。

登入後以及每次建立新連線時，TgWitness 會讀取該帳號的敏感 內容設定。 當此設定為關閉狀態，且 Telegram 允許變更時，TgWitness 會將其開啟， 以便將 Telegram 標記為敏感（18+）的內容儲存下來，並記錄 ` `account.content_settings``。此設定屬於該帳號，並適用於所有 Telegram 應用程式。「嚴格選擇的聊天室」功能不會影響此設定；請在登入前開啟該功能。

針對同一工作區的恢復連線請求若同時發生，將共用其客戶端，並 等待該連線設定完成。若某次嘗試失敗或被取消，系統會釋放 該資源，讓下一項請求得以重試。若在設定過程中，儲存的憑證、客戶端或授權狀態 發生變更，較早的嘗試將停止執行，而非回報連線已就緒。

FloodWait 診斷資訊會保留失敗的 TL 方法、任何 Takeout/range 封裝器、 伺服器要求的等待時間，以及 `telegram.backoff` 中的有效截止時間。 當請求暫停時，連線詳細資訊會顯示方法與截止時間。 該診斷資訊包含自該客戶端建立以來 各方法的客戶端呼叫計數器；這些計數器會分別統計嵌套的對等節點解析次數，但不會計入封包 或 Telethon 的內部重試次數。當前計數器亦可透過狀態 API 中的 `collector.rpc_activity` 取得。 不包含任何請求參數、使用者名稱、存取 雜湊值或例外訊息。最後的診斷記錄與完整截止時間 在重新啟動後仍會保留。較早且未記錄方法的等待狀態 無法事後歸因。請參閱來源審查的[匯出限制](https://github.com/phishdestroy/TgWitness/blob/main/docs/EXPORT-LIMITS.md)， 以及「發現」與「歷史資料擷取」之間的區別。

`official_app=True` 或 `False` 是 Telegram 的當前授權標誌。這兩種 值均無法判定該帳號是否受限、受信任或正處於監測狀態。 現有的證據模式 `account.devices` 快照仍保留所有 已登入裝置的歷史紀錄；連線診斷則僅保留當前裝置的描述。

連線前，諮詢性檢查會將 API 平台、語言套件、 裝置／作業系統與應用程式版本格式、行動系統地區設定，以及 Telethon 的實際 架構層，與已審核的目錄基準進行比對。警告會顯示於伺服器 日誌及帳戶狀態元資料中；這些警告絕不會取代匯入的值，也不會變更 架構層。若架構層不同，即表示需檢視相容性；帳戶的 自身連線狀態則顯示其是否正常運作。 無論使用哪種客戶端設定檔，Telegram 皆會自行決定 相關限制。斷線帳戶狀態 會使用已儲存的設定檔，而非重新生成另一份裝置描述。

若要改為使用您自己的應用程式：

1. 開啟 [my.telegram.org](https://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** 欄位，系統便會自動填入兩個欄位。同一組組合可 適用於您所有的帳戶。成功登入後，該組合將以加密形式儲存於 該工作區內，且絕不會傳回瀏覽器。

涉及三種不同的憑證：

| 機密 | 開啟 | 存放位置 |
| --- | --- | --- |
| 面板代幣 | TgWitness 網頁控制面板 | 資料目錄中的 `panel-token.txt`，或 `TGWITNESS_TOKEN` |
| API ID + 雜湊值 | 本身並無特殊含義；僅用於識別該應用程式 | 可透過內建配對、匯入設定，或於 my.telegram.org 建立您專屬的應用程式 |
| 帳戶授權 | Telegram 帳號 | 可透過手機／QR 碼登入建立，或作為會話匯入 |

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

## 電話號碼

1. 開啟「**更多工具」→「帳戶」**，切換至「**電話**」分頁，並以國際格式輸入號碼， 例如 `+44 7700 900123`。空格和連字號會自動移除。
2. 按下「**繼續**」。API ID + Hash 欄位可留空。
3. 請輸入 Telegram 傳送的代碼，通常會傳送至 Telegram 應用程式；是否發送 SMS 由 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](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#account-json)」。

## 帳戶檔案

開啟**「新增帳戶」→「檔案」**，並選取最多四個**屬於同一個帳戶的檔案**（總計 **8 MiB**），按下「**檢查檔案**」，然後按下「**連線帳戶**」。選取檔案或 貼上對話內容並不會傳送任何資料；**按下「檢查檔案」**後，系統會將檔案傳送至您的 TgWitness 伺服器， 該伺服器會在未登入的情況下讀取這些檔案，並顯示其找到的對話紀錄。

「**檔案**」、**「授權金鑰」**及「批量匯入」表單會在連線前顯示 「並行會話」警告。預設情況下，匯入的授權將被重複使用。當其金鑰 在此處使用時，請保持原始 客戶端關閉。**檔案**與**授權金鑰**亦提供 「**建立獨立授權**」功能，詳見下文說明。批量匯入仍使用 直接模式。手機及互動式 QR 碼登入會建立獨立的授權。 警告標題在匯入表單中始終可見；當提供檔案或金鑰／會話字串時，其完整說明會 自動展開。閱讀後可將其收起， 以便在手機上仍能正常使用檔案瀏覽器與連線控制項。

[經確認的部署](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/high-assurance/)（Phala Cloud、Intel TDX）不會針對 匯入的金鑰進行收集。在此情況下，**檔案**與**授權金鑰**僅在選取「**建立獨立 授權」**時才會建立連結；批量匯入將被拒絕。手機與 QR 碼登入功能則如常運作。

- 檔案會在您的 TgWitness 伺服器**記憶體中**進行轉換。上傳的檔案不會被儲存， ZIP 檔案不會解壓縮至磁碟，也不會與任何外部服務進行連線。
- 隨後會將生成的會話記錄與 Telegram 進行比對。若檔案中載明使用者 ID， 則該 ID 必須與 Telegram 回報的帳戶相符。
- 描述不同帳戶或不同 API 憑證的檔案將被拒絕 而非僅選擇其中一個。
- **密碼或會話文字**欄位包含 TData 本地密碼欄位，此處可貼上 StringSession 並**在未登入的情況下讀取檔案**（填寫表單時無需 與 Telegram 連線）。 貼上 StringSession 會清除已選取的檔案，而選擇 檔案則會清除已貼上的文字，因此驗證與連線皆會採用最新的選擇。 變更密碼後，請再次按下「**檢查檔案**」。

### 建立獨立的授權機制

請選擇「在連線前**建立獨立授權」**並匯入檔案，或 選用「授權金鑰」。TgWitness 會短暫連線至匯入的「捐贈者」，利用其核准 新客戶端的 QR 登入憑證，並在核准後立即斷開與「捐贈者」的連線。 新客戶端擁有專屬的授權金鑰，以及獨立選定的桌面 設定檔。「捐贈者」提供的 API 憑證與裝置設定檔僅用於 與「捐贈者」的連線。現有的授權不會被登出或撤銷。

**在此步驟中，請務必將捐贈者的原始客戶端完全關閉。**初始 連線仍使用其複製的金鑰，因此此模式無法消除該初始 並行使用風險。一旦建立新的授權連線，擁有者即可重新開啟 原始客戶端，並同時使用兩者。 互動式 **QR 碼**登入可讓 原始客戶端在無需在此處複製或連接其金鑰的情況下，批准此次登入。

**請勿登出或結束捐贈者的會話。**當批准 QR 登入的會話結束時，Telegram 也會終止其所批准的會話；在實際測試中，新 授權會在捐贈者登出後一秒內停止。匯入記錄會 記錄捐贈者的會話（`session_origin.approved_by`：裝置、API ID 及建立時間）。 「會話清單」會標記該會話；「**結束會話」**會拒絕該會話；而「**結束所有其他會話」** 及「**將此設為唯一會話」**則會讓捐贈者保持登入狀態。

若 Telegram 要求進行雙因素驗證 (2FA)，此模式會 `twoFA` 已選取的 JSON 檔案（若存在）， 否則會要求輸入密碼。若匯入的密碼遭拒絕，系統將返回密碼輸入表單。 密碼不會被儲存。候選金鑰會以加密形式儲存於 `independent_login.enc`，包含資料中心遷移期間的變更。發生 中斷後，請選擇相同的來源帳號並選取此選項，以恢復已儲存的候選金鑰。 來源帳號會在 `help.getAppConfig` 進行驗證；若來源帳戶處於凍結狀態， 則在此處中止。若 Telegram 在批准登入前拒絕該來源帳戶，未獲批准的 候選金鑰將被丟棄，並可重新開始匯入。僅當 Telegram 回報該候選金鑰 尚未登入時，另一來源帳戶才會取代已儲存的候選金鑰；若 候選金鑰已登入或正在等待其雙因素驗證密碼，則會予以保留。 工作區仍會為該帳戶保留；即使完成失敗也不會刪除 新的工作區。請保留其資料目錄和金庫金鑰。最終的憑證及 `account.authorized` 日誌記錄中將包含匯入方法、輸入格式及 捐贈者 API ID，但不會包含捐贈者的金鑰或密碼。

2026年11月5日，一個專用帳戶通過了 Telethon、Pyrogram 及 TData 捐贈者的即時驗證：2 因素驗證（2FA）完成、獨特的新授權金鑰、捐贈者與新客戶端 的並行存取，以及閱讀公開頻道。 Telethon 案例中， 系統亦在密碼輸入步驟中發生中斷後，成功恢復了已儲存的候選帳戶。每個新的 授權皆完成了登入後的六項初始化請求，且其簽署過的 日誌已通過驗證。原始會話在所有四種提供的格式中均保持可用。

Telegram 的 [RPC 錯誤資料庫](https://core.telegram.org/api/errors.json)將 `FRESH_CHANGE_ADMINS_FORBIDDEN` 與變更管理員、`FRESH_CHANGE_PHONE_FORBIDDEN` 與變更電話號碼，以及 `FRESH_RESET_AUTHORISATION_FORBIDDEN` 與 撤銷其他會話、變更其有效期或註冊通行金鑰相關聯。 `SESSION_TOO_FRESH_*` 和 `PASSWORD_TOO_FRESH_*` 涉及所有權轉移以及 收益或禮物提領。這些並非資料擷取操作；新登入並不 意味著全面性的 24 小時讀取禁令。匯出功能可另行返回 `TAKEOUT_INIT_DELAY_*`。TgWitness 會保留伺服器要求的暫停狀態，且不會自動重試 代幣接受或撤銷會話以規避限制。

**更多工具 → 帳戶 → 帳戶安全性 → 此帳戶的連線 → 結束所有其他連線**：應 操作員要求呼叫 `auth.resetAuthorizations`，並將連線 數量（結束前後）記錄於 `account.all_other_sessions_terminated` 中。Telegram 僅接受來自已登入滿 24 小時之連線的此類請求。 當此工作空間透過 QR 碼從匯入的會話登入時，最初核准該會話的 會話將保持登入狀態：TgWitness 會透過 ``account.resetAuthorization`` 逐一終止其他會話，並 記錄 ``kept_approving_session``。**若此為唯一會話**，則以該理由停止操作 且不變更密碼。

**請將此設定為唯一會話**，對透過此工作區登入所建立的金鑰執行相同操作，若帳戶尚未設定兩步驟驗證密碼，則會啟用該功能。控制面板會顯示該密碼一次；TgWitness 僅會將其保留於工作區金庫中直至該次顯示為止。日誌會記錄 `session.exclusive_from`。若 Telegram 稍後列出另一個會話，日誌將記錄 `session.exclusive_ended` ，且面板會發出警示。驗證器會同時輸出這兩項資訊。

**當 Telegram 允許將此設為唯一會話時，即表示**這是基於計時器的相同動作。該 選項會出現在此工作區中建立的金鑰之**「此帳戶的會話」**下方，並 記錄為 `session.exclusive_automatic`。在觀察期間，收集器每五 分鐘檢查一次，自該金鑰的 `account.authorized` 記錄以來是否已過 24 小時 —— 在此之前，Telegram 會回應 `FRESH_RESET_AUTHORISATION_FORBIDDEN` —— 然後執行相同的 操作一次。成功會被記錄為 `session.exclusive_from`，如同手動按鈕一般。 若遭拒絕，則會以 `session.exclusive_postponed` 記錄一次並附上 Telegram 的理由，而 收集器會以逐步增加的延遲時間（最長六小時）進行重試。在此情況下，唯讀權限無效： 結束會話屬於帳戶安全操作，而非聊天操作。

自動執行所產生的兩步驟密碼會在 Telegram 設定該密碼之前，先儲存於工作區金庫中，並以工作區金鑰進行加密。控制面板會從 `POST /api/account/sessions/only/password`，該密碼隨即被刪除，並在您開啟**此帳戶的「會話」**時，與手動流程顯示於同一對話方塊中。連線頁面會提示有密碼待取用。該密碼絕不會寫入日誌，且在顯示之前，即使重新啟動也能保留。

在監測過程中也會通報新的會話：當 Telegram 的會話清單新增一筆記錄時， `account.sessions` 記錄會將其歸類於 `added` 之下，而控制面板會根據該快照中的 裝置、應用程式及國家/地區資訊觸發警示。

### 見證者探針

**更多工具 → 帳戶 → 帳戶安全性 → 「見證者探測」**用於檢查其他客戶端是否接收此帳戶的 更新。新增一個使用不同 Telegram 帳戶登入且擁有專屬 會話金鑰的第二個工作區，建立包含兩個帳戶的私人群組，接著將該群組設為「**探測 聊天室**」，並將第二個工作區設為**「見證者工作區**」，然後啟用探測功能。兩個帳戶 皆需將**「唯讀」**設定關閉，且見證者工作區必須處於「觀察」狀態。

在觀察期間，此工作區每 60–120 秒向群組發送 `probe:<n>:<token>` 並記錄 `probe.sent`。見證者回應 `ack:<n>:<token>` 並記錄 `probe.seen` 以及 `probe.ack_sent`。若確認回執在 20 秒內以即時更新形式送達此會話，則 記錄為 `probe.acked`。否則，工作區將讀取群組的近期歷史紀錄。 若在該處 發現確認回應但未以即時更新形式送達，則記錄為 `coverage.gap`，原因 為 `probe_ack_missed_live`：控制面板會觸發警報，並將事件接收標記為失敗，直至 後續確認回應以即時更新形式送達（`connection.restored`，原因 `probe_ack_live`）。若未記錄任何確認回應，則記錄為 `probe.unanswered`；若在等待期間發生連線中斷或歷史紀錄無法讀取，則記錄為 `probe.inconclusive`。唯讀狀態、Telegram 限制及 FloodWait 暫停均僅記錄一次 ，並標記為 `probe.skipped`。

### Telethon `.session`

|  |  |
| --- | --- |
| 產品簡介 | 由 Telethon 衍生工具所建立的 SQLite 資料庫，例如 `my_account.session` |
| 獲以下機構認可 | 表格 `sessions`（連同 `dc_id`、`server_address`、`port`、`auth_key`）及 `version` = 7 或 8 |
| 要求 | 僅有一筆授權會話記錄；一個封閉且完整的数据庫 |

請先關閉建立該檔案的程式。若其旁邊存在 `my_account.session-journal` 或 `my_account.session-wal`，表示資料庫尚未完成：請正常開啟並 關閉原始客戶端。刪除這些輔助檔案可能會留下損壞的副本。

### Pyrogram `.session`

|  |  |
| --- | --- |
| 產品簡介 | 基於 Pyrogram 的工具所建立的 SQLite 資料庫 |
| 獲以下機構認可 | 表格 `sessions` 包含 `dc_id`、`auth_key`、`test_mode`、`user_id`、`is_bot`；`version` = 2 或 3 |
| 要求 | 生產環境網路中僅允許一個授權**使用者**會話。機器人及測試資料中心（test-DC）的會話將被拒絕 |

登入時，系統會將儲存的用戶 ID 與 Telegram 進行比對。

### 會話 + JSON 對

帳戶資料通常以兩個同名檔案的形式分發，例如 `447700900123.session` 和 `447700900123.json`。請一次選取**兩者**。

- 根據 JSON 資料，TgWitness 使用 `app_id`/`api_id` 及 `app_hash`/`api_hash`，因此您 通常無需手動輸入 API 憑證。
- 連線設定檔使用 `device_model`（別名 `device`）、`system_version` （別名 `sdk`）、`app_version`、`lang_code`、`system_lang_code`（別名 `system_lang_pack`）、 `lang_pack` 以及可選的 `tz_offset`（以秒為單位的 UTC 偏移量，範圍為 -43200 至 50400）。 手動填入的欄位優先於系統生成的預設值及控制面板／瀏覽器的 語言設定。若別名發生衝突，則不予接受。解析後的設定檔將儲存於 加密的工作區憑證中，並在重新啟動後重新使用，其中包含其應用程式版本。
- `phone`、代理伺服器設定及裝置代碼將被**忽略**。`twoFA` 僅在 選取「**建立獨立授權」**時為唯讀；直接匯入則會忽略此項目。
- 若 JSON 缺乏受支援的授權欄位，則僅為元資料。請新增其 會話檔案，或繼續使用手機或 QR 碼登入。若 JSON 包含受支援的會話或 授權金鑰，即可自行完成授權；詳見「[帳戶 JSON](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#account-json)」。

### Telegram 桌面版 (TData)

TData 即是 Telegram Desktop 應用程式（來自 desktop.telegram.org 的跨平台 應用程式）中的 `tdata` 資料夾。

| 系統 | 預設位置：`tdata` |
| --- | --- |
| Windows | `%APPDATA%\Telegram Desktop\tdata`（可攜式 Telegram：位於 `Telegram.exe` 旁邊） |
| Linux | `~/.local/share/TelegramDesktop/tdata` |
| macOS | `~/Library/Application Support/Telegram Desktop/tdata` |

若要導入此工具：

> **並行會話警告。**直接匯入 TData 會重複使用 Telegram Desktop 的授權 金鑰。請勿同時在 Desktop 和 TgWitness 中使用該金鑰。Telegram 可能會透過 `AUTH_KEY_DUPLICATED` 使授權失效，導致兩份副本在重新登入前皆無法使用。
>
>
>
> 請完全關閉 Desktop（包括其系統托盤進程），並在 TgWitness 使用匯入的會話期間保持該副本關閉。**請直接關閉程式，切勿登出或撤銷會話：** 撤銷會話也會使匯入的副本失效。若您需要同時運行兩個客戶端， 請選擇**「建立獨立授權」**，並在 新登入成功前保持 Desktop 關閉，或透過手機或 QR 碼登入 TgWitness。建議使用 專用帳戶，但這並不能確保複製的金鑰在並行使用時是安全的。
>
>
>
> 此規則同樣適用於匯入的 `.session` 檔案、StringSession 文字及 Auth Key HEX。 其他擁有獨立建立之授權的用戶仍可保持登入狀態。 請參閱 [Telegram 的 AUTH_KEY_DUPLICATED 文件](https://core.telegram.org/api/errors#406-not-acceptable)。

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 字串採用不同格式。

### 授權金鑰與 DC 需置於同一行

帳戶清單通常以 `<512 hexadecimal characters>:<DC id>` 的形式載有原始授權資訊， 例如 `a1b2…ef:5`。請將該行貼至**「通行碼」或「會話文字**」下方，以 文字檔案形式載入，或放入帳戶[JSON](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#account-json) 的 `session` 欄位中。TgWitness 將 DC 1–5 映射至與 `auth_key` + `dc_id` JSON 匯入相同的生產環境位址， 並以**「授權金鑰 HEX」和「DC**」格式進行回報。任何其他 DC 編號或金鑰長度均會被拒絕。

### 帳戶 JSON

一個 JSON 物件，大小最多 **64 KiB**，存於副檔名為 **`.json`** 的檔案中。

| 欄位（別名） | 含義 |
| --- | --- |
| `api_id` (`app_id`) | 應用程式 ID，一個正整數 |
| `api_hash` (`app_hash`) | 應用程式雜湊值，32 個十六進位字元 |
| `string_session`（`session_string`、`session_str`；舊版 `session`） | Telethon StringSession 文字，或 `<512 hexadecimal characters>:<DC id>`，並非檔案名稱 |
| `auth_key` (`auth_key_hex`) + `dc_id` | 完整的 512 字元授權金鑰及 DC 1–5 |
| `user_id` (`id`) | 可選；在儲存授權前會與 Telegram 進行比對 |
| `device_model` (`device`) | 連線裝置說明 |
| `system_version` (`sdk`) | 連線作業系統版本 |
| `app_version` | 發送至 Telegram 的應用程式版本 |
| `lang_code`, `system_lang_code` (`system_lang_pack`), `lang_pack` | 客戶端語言、系統語言及客戶端語言套件；允許使用空的 `lang_pack` |
| `tz_offset` | 可選的 UTC 偏移量（以秒為單位），透過 `initConnection.params` 傳送；格式為整數或十進位整數字串 |

若同時存在別名與主名稱，兩者必須一致。顯式的 Telethon 會話欄位優先於其他格式的通用 `session` 二進位資料塊。若 兩者均包含可識別的 Telethon 會話，則必須描述相同的授權。 若無顯式欄位，`session` 必須是有效的 Telethon StringSession，或以 `<512 hexadecimal characters>:<DC id>` 格式呈現的授權金鑰 與 DC。範例：

```
{ "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 陣列）。

## 釐清您所擁有的內容

| 您會看到 | 它是一項 | 使用說明 |
| --- | --- | --- |
| `*.session`；在文字編輯器中開啟時，頂端顯示 `SQLite format 3` | Telethon 或 Pyrogram SQLite | **檔案**（自動偵測） |
| 一個名為 `tdata` 的資料夾，其中包含 `key_datas` | Telegram 桌面版 TData | 將兩個檔案壓縮為 ZIP 檔，然後前往「**檔案」** |
| 以 `1` 開頭的一行文字，約 350 個字元 | Telethon StringSession | **檔案** |
| 一行文字 `512 characters 0-9a-f`，接著是 `:` 以及一個 1 至 5 之間的數字 | 授權金鑰與 DC | **檔案**、箱子**密碼或會話文字** |
| `*.json` 搭配 `app_id`/`app_hash` | 相關元資料 | **檔案**及其對應的會話 |
| `*.json` 搭配 `auth_key` 或 `string_session` | 帳戶 JSON | **檔案** |
| 512 個字元 `0-9a-f` | 授權金鑰 | **授權金鑰** |
| 32 個字元 `0-9a-f` | API 雜湊值 | **API 識別碼 + 雜湊值** |
| 來自 TDLib 應用程式的 `td.binlog` 或 `db.sqlite` | TDLib 儲存 | 不支援 |
| `123456789:AA…` | 機器人代幣 | 不支援 |

## 不支援的格式

| 格式 | 替代版本 |
| --- | --- |
| TDLib 儲存 (`td.binlog`) 及 TDLib 匯出功能 | 透過手機或 QR 碼登入 |
| Pyrogram 會話**字串** | 請使用 Pyrogram `.session` 檔案，或透過手機/QR 碼 |
| TData 附帶多個已登入的帳戶 | 請在 Telegram Desktop 中登出其他帳戶，或使用各帳戶專屬的會話檔案 |
| 機器人代幣 | 不支援：TgWitness 僅以使用者帳戶身分進行監測 |
| 包含多個帳戶的 CSV/JSON 清單 | 透過**帳戶 → 匯入帳戶**匯入受支援的工作階段檔案，或在個別的工作區中透過電話號碼／QR 碼登入 |
| Test-DC 或 機器人會話 | 請使用正式運作的用戶帳戶 |

## 多個帳戶

按下帳戶選擇器旁的 **+** 符號，或開啟 **更多工具 → 帳戶 → 設定 → 連線設定 → 工作區**，輸入標籤並 登入。

- 可建立任意數量的工作區，包含主工作區在內。每個工作區皆擁有獨立的會話、代理 路由、來源、擷取政策、日誌、簽名金鑰、檢查點及匯出設定。
- 切換顯示中的工作區並不會暫停其他工作區的運作。
- 日誌會與建立它的帳戶綁定。若以其他 帳戶登入，則需建立另一個工作區，且一個帳戶無法被指派至兩個 工作區。
- 主面板中的「代幣」功能可控制所有工作區。[所發出的存取權限](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/access/)可將其他使用者限制在選定的帳戶和聊天室中，並可設定獨立的權限與會話限制。
- **帳戶會**重新命名一個工作區，並刪除已新增的工作區，連同其會話、日誌、 來源及簽名金鑰一併刪除。主工作區無法從控制面板中刪除。

### 批次匯入和帳戶群組

請使用「**帳戶」→「匯入帳戶」**來新增多個帳戶，根據檔案基名配對檔案 並查看每個登入結果。每個帳戶都會擁有專屬的工作區。

群組可將相關帳戶彙整在一起，同時不會合併其會話、金鑰或 證據。在「**帳戶」**中**開啟「群組」**將導向其頁面： `/groups/<id>`:

- **帳戶:**每位成員的連線路徑、觀察記錄及最後一則訊息，並附有 「**全部**啟動」與「**全部暫停」功能**。
- **需要注意:**已登出、無法使用，或存在 連線、匯入、來源或媒體問題的帳戶；每個名稱皆可導向其對應的卡片。
- **多個帳戶可查看的聊天內容包含：** 共享來源、正在監看這些來源的帳戶，以及 可用工作區監看期間（最長七天）內的中斷情況。**使用 N 個帳戶進行匯出時，** 系統會將頻道或超級群組的匯出內容分配至各帳戶，並對單一存檔進行簽署。
- **匯出群組:**包含一個 ZIP，其中每個帳戶的簽名匯出檔位於 `accounts/` ，並 `manifest.json` 列出其SHA-256與金鑰指紋，並由主 工作區在 `manifest.signature.json`。請使用 `python -m tgwitness.verify` 並使用該帳戶的可信指紋，分別驗證每個帳戶的存檔。

成員共享群組的設定；每個帳號可保留其自身的設定值。 請參閱「[共享設定](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/settings/#account-groups)」、 [「匯入與群組指南」](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Accounts.md#import-accounts-and-share-settings) 以及 [MTProxy 資料池儀表板](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Proxies.md#pool-dashboard-and-custom-sources)。

## 登出

**更多工具 → 帳戶 → 登出 Telegram**（並暫停觀察）會要求 Telegram 終止該 會話，因此該會話也會從帳戶的**「設定」→「裝置」**中消失，並從 工作區金庫中移除該會話。日誌、來源、設定及簽名金鑰仍會保留，且 日誌會記錄此次登出。 工作區仍歸屬於其帳戶：僅該 帳戶可再次連線至該工作區。若 Telegram 未回應，該連線仍會在此處被移除 ，且面板會顯示此訊息；請在 Telegram 的「**設定」→「裝置」**中終止該連線。

## 當 Telegram 結束連線時

若 Telegram 封禁、凍結或登出該帳號，或從其他裝置終止連線， 日誌會記錄原因、Telegram 錯誤、路由及資料中心。該帳號的 狀態顯示**「下載帳號遺失報告」**：這是一個經過簽名的 JSON 檔案，內含遺失前 24 小時的日誌記錄，包括連線、路由、連線會話、帳號通知及覆蓋 缺口，每項記錄均附有日誌雜湊值與簽名。請透過 `python verify.py tgwitness-account-loss.json --fingerprint COLLECTOR_FP`；證據匯出 中包含完整的雜湊鏈。當被凍結的帳戶嘗試連線時，系統會在監控期間偵測到該狀況，並會 停用其發送訊息及加入群組的功能。

## 確保帳戶檔案安全

- 請將每個 `.session`、TData ZIP、StringSession、Auth Key 及帳戶 JSON 視同 密碼般嚴加保護。TgWitness 會將匯入的授權資訊儲存於其加密金庫中；您可 於事後刪除原始檔案。
- 請勿同時在兩個程式中執行相同的授權。Telegram 可能會撤銷該授權 (`AUTH_KEY_DUPLICATED`)，屆時兩個程式都將無法運作。
- 已過期或遭撤銷的連線無法透過轉換恢復。請重新登入。

## 疑難排解

| 訊息或徵兆 | 操作指南 |
| --- | --- |
| *無法讀取此會話。請關閉其原始客戶端……* | SQLite 檔案目前處於開啟狀態或尚未完成（`-journal`/`-wal` 輔助檔案）。請先正常關閉原始程式，然後重新複製該檔案。 |
| *支援的 Telethon SQLite 資料結構：7 及 8* / *Pyrogram … 2 和 3* | 此檔案是由非常舊或來源不明的函式庫版本所建立。請改用手機號碼／QR 碼登入。 |
| *僅支援經授權的生產環境使用者會話* | 該 Pyrogram 檔案屬於某個機器人或測試網路。 |
| *TData 存檔已超過 512 筆記錄或 32 MiB* | 僅包含 ZIP 檔案 `key_datas` 和 `D877F783D5D3EF8Cs`，而非整個資料夾。 |
| *無法解密 TData。請檢查桌面本機密碼* | 請在「**密碼」或「會話文字」**欄位中輸入 Telegram Desktop 的本地密碼。 |
| *每次僅可匯入一個 TData 帳戶* | Telegram Desktop 擁有多個帳戶；請參閱「[不支援的格式](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#unsupported-formats)」。 |
| *選定的檔案描述了不同的帳戶或 API 憑證* | 僅選取單一帳戶的檔案。 |
| *JSON 內容中未包含任何受支援的 API 憑證或授權資訊* | 請檢查 [Account JSON](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#account-json) 中的欄位名稱。 |
| *僅限 API 元資料* | 該 JSON 檔案未包含會話資訊。請新增 `.session` 檔案，或使用手機/QR 碼。 |
| *授權金鑰的十六進位值必須包含全部 512 個十六進位字元* | 金鑰已被截斷或包含「`…`」。 |
| 帳號 ID 與匯入的帳號不符 | 該檔案的用戶 ID 與 Telegram 所顯示的不符；此檔案屬於另一個帳號。 |
| 該帳號已屬於另一個工作區 | 請開啟該工作區，而非重複新增該帳號兩次。 |
| 已連線，但「**更多工具」→「來源」**中的聊天清單缺少一個私人群組 | 檢查成員資格。揀選器會檢查前1,000個對話；請在「**更多工具」→「參數」**中提高此限制。 |
| 代理連線失敗 | 請檢查路由與 IP 模式。自動模式 MTProxy 會嘗試其他可用的入口。隱藏位址模式會進行等待；「直接」模式作為最後手段，可在設定的延遲時間過後直接連線。請參閱[路由模式說明](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/connection/#ip-modes)。 |

另請參閱：代理伺服器與加密的[連線及安全性](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/connection/)， 以及登入後資料擷取的[運作方式](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/collection/)。
