參考資料 / 設定
Telegram · 帳戶與會話格式
可透過手機、QR 碼或授權金鑰登入,匯入 Telethon、Pyrogram 或 Telegram Desktop 的會話紀錄,並同時管理多個帳戶。
TgWitness 透過 MTProto 協議,使用 Telethon 以 Telegram 用戶帳戶(而非機器人)身分登入。每個帳戶皆位於獨立的工作區中(在 API 和命令列工具中稱為「工作區」),並擁有專屬的會話、來源、日誌及簽名金鑰。
會話檔案、會話字串及認證金鑰均屬帳戶授權憑證:凡 持有其中任何一項者,皆可代表該帳戶進行操作。這些資料不包含訊息歷史紀錄。
[!警告] 請使用專用帳戶。Telegram 會針對其認為過量的請求量進行限制,甚至可能永久封禁帳戶, 無論客戶端或用途為何,且僅部分公開相關限制規範。 請連接專為觀察準備的帳戶,而非 個人或其他有價值的帳戶,並在專用 帳戶上建立 API ID / API 雜湊值。
- 一覽
- 開始之前:API ID 與 API 雜湊值
- 電話號碼 · QR 碼 · 授權金鑰 + DC 識別碼
- 帳戶檔案: Telethon .session · Pyrogram .session · 會話 + JSON 對 · TData · StringSession · 授權金鑰與 DC 需置於同一行 · 帳戶 JSON
- 釐清您所擁有的內容 · 不支援的格式
- 多個帳戶 · 確保帳戶檔案安全 · 疑難排解
一覽#
| 您現有的內容 | 「新增帳戶」分頁 | 您還需要 |
|---|---|---|
| 電話號碼及其登入代碼的存取權限 | 電話 | 若已啟用,則為雙因素驗證 (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 目錄中預設的確定性裝置/作業系統組合:
桌面版 2040、Android 6、Android X 21724、iOS 10840、macOS 2834 以及 Web 2496。
Android 的原始碼建置 ID 4 亦採用 Android 目錄,此資訊可於
Telegram Android 的 BuildVars 中查證。
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 演算法
四捨五入至 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 狀態,後續請求將停止;若缺少結果,則該項將保持未知狀態。
本地檢查仍可回報其結果,而網路檢查則會被跳過。
若啟用「嚴格選擇聊天室」功能,系統將不會
請求當前授權狀態,且該檢查會顯示為已跳過。
登入後以及每次建立新連線時,TgWitness 會讀取該帳號的敏感
內容設定。 當此設定為關閉狀態,且 Telegram 允許變更時,TgWitness 會將其開啟,
以便將 Telegram 標記為敏感(18+)的內容儲存下來,並記錄 `
account.content_settings`。此設定屬於該帳號,並適用於所有
Telegram 應用程式。「嚴格選擇的聊天室」功能不會影響此設定;請在登入前開啟該功能。
針對同一工作區的恢復連線請求若同時發生,將共用其客戶端,並 等待該連線設定完成。若某次嘗試失敗或被取消,系統會釋放 該資源,讓下一項請求得以重試。若在設定過程中,儲存的憑證、客戶端或授權狀態 發生變更,較早的嘗試將停止執行,而非回報連線已就緒。
FloodWait 診斷資訊會保留失敗的 TL 方法、任何 Takeout/range 封裝器、
伺服器要求的等待時間,以及 telegram.backoff 中的有效截止時間。
當請求暫停時,連線詳細資訊會顯示方法與截止時間。
該診斷資訊包含自該客戶端建立以來
各方法的客戶端呼叫計數器;這些計數器會分別統計嵌套的對等節點解析次數,但不會計入封包
或 Telethon 的內部重試次數。當前計數器亦可透過狀態 API 中的
collector.rpc_activity 取得。 不包含任何請求參數、使用者名稱、存取
雜湊值或例外訊息。最後的診斷記錄與完整截止時間
在重新啟動後仍會保留。較早且未記錄方法的等待狀態
無法事後歸因。請參閱來源審查的匯出限制,
以及「發現」與「歷史資料擷取」之間的區別。
official_app=True 或 False 是 Telegram 的當前授權標誌。這兩種
值均無法判定該帳號是否受限、受信任或正處於監測狀態。
現有的證據模式 account.devices 快照仍保留所有
已登入裝置的歷史紀錄;連線診斷則僅保留當前裝置的描述。
連線前,諮詢性檢查會將 API 平台、語言套件、 裝置/作業系統與應用程式版本格式、行動系統地區設定,以及 Telethon 的實際 架構層,與已審核的目錄基準進行比對。警告會顯示於伺服器 日誌及帳戶狀態元資料中;這些警告絕不會取代匯入的值,也不會變更 架構層。若架構層不同,即表示需檢視相容性;帳戶的 自身連線狀態則顯示其是否正常運作。 無論使用哪種客戶端設定檔,Telegram 皆會自行決定 相關限制。斷線帳戶狀態 會使用已儲存的設定檔,而非重新生成另一份裝置描述。
若要改為使用您自己的應用程式:
- 開啟 my.telegram.org 並使用您擁有的任何電話號碼 登入。驗證碼將發送至 Telegram 應用程式,而非透過簡訊。
- 選擇 API 開發工具。
- 建立應用程式:任選標題與簡稱(5–32 個字母),平台選「桌面版」。 網址與描述欄位可留空。
- 請複製 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,請先前往「 更多工具」→「帳戶」→「設定」→「連線設定」→「變更連線路徑」進行設定。
電話號碼#
- 開啟「更多工具」→「帳戶」,切換至「電話」分頁,並以國際格式輸入號碼,
例如
+44 7700 900123。空格和連字號會自動移除。 - 按下「繼續」。API ID + Hash 欄位可留空。
- 請輸入 Telegram 傳送的代碼,通常會傳送至 Telegram 應用程式;是否發送 SMS 由 Telegram 決定。
- 若該帳號啟用了兩步驟驗證,請輸入該密碼。此密碼並非控制面板 代幣,亦非裝置通行碼。
- 登入後請確認顯示的帳號 ID,然後選擇資料來源。
登入代碼與雙因素驗證 (2FA) 密碼絕不會寫入磁碟。
QR 碼#
當該帳號已在手機或另一台電腦上登入時,請使用此功能。
- 點擊「QR 碼」→ 顯示 QR 碼。API ID + Hash 欄位可留空。
- 在已登入的裝置上:設定 → 裝置 → 連結桌面裝置,掃描條碼 並確認。
- 若 Telegram 要求,請在 TgWitness 中輸入雙因素驗證 (2FA) 密碼。
此 QR 碼圖像係於本地端產生。QR 碼會過期;請按「產生另一個 QR 碼」 以重新嘗試。若鎖定面板、切換工作區或啟動另一組登入程序,將取消 待處理的 QR 碼。
授權金鑰 + DC 識別碼#
授權金鑰(Auth Key)是每個 Telegram 連線背後 256 位元的原始授權資料,以 512 個十六進位字元表示,並附有資料中心編號 DC 1–5。
- 「Auth key」分頁。請貼上完整的金鑰;若金鑰中包含「
…」等縮寫,則無法正常運作。 - 請選擇隨金鑰一併提供的 DC ID。
- 可選擇輸入使用者 ID。若 Telegram 回報 帳戶不符,TgWitness 將拒絕連線。
- Press Connect 帳戶。
授權金鑰(512 個字元)並非 API 雜湊值(32 個字元)。同一組金鑰亦可 以 JSON 格式匯入,詳見「帳戶 JSON」。
帳戶檔案#
開啟「新增帳戶」→「檔案」,並選取最多四個屬於同一個帳戶的檔案(總計 8 MiB),按下「檢查檔案」,然後按下「連線帳戶」。選取檔案或 貼上對話內容並不會傳送任何資料;按下「檢查檔案」後,系統會將檔案傳送至您的 TgWitness 伺服器, 該伺服器會在未登入的情況下讀取這些檔案,並顯示其找到的對話紀錄。
「檔案」、「授權金鑰」及「批量匯入」表單會在連線前顯示 「並行會話」警告。預設情況下,匯入的授權將被重複使用。當其金鑰 在此處使用時,請保持原始 客戶端關閉。檔案與授權金鑰亦提供 「建立獨立授權」功能,詳見下文說明。批量匯入仍使用 直接模式。手機及互動式 QR 碼登入會建立獨立的授權。 警告標題在匯入表單中始終可見;當提供檔案或金鑰/會話字串時,其完整說明會 自動展開。閱讀後可將其收起, 以便在手機上仍能正常使用檔案瀏覽器與連線控制項。
經確認的部署(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 錯誤資料庫將
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」。
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 文件。
- 完全退出 Telegram Desktop。
-
請從
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 的 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 或 機器人會話 | 請使用正式運作的用戶帳戶 |
多個帳戶#
按下帳戶選擇器旁的 + 符號,或開啟 更多工具 → 帳戶 → 設定 → 連線設定 → 工作區,輸入標籤並 登入。
- 可建立任意數量的工作區,包含主工作區在內。每個工作區皆擁有獨立的會話、代理 路由、來源、擷取政策、日誌、簽名金鑰、檢查點及匯出設定。
- 切換顯示中的工作區並不會暫停其他工作區的運作。
- 日誌會與建立它的帳戶綁定。若以其他 帳戶登入,則需建立另一個工作區,且一個帳戶無法被指派至兩個 工作區。
- 主面板中的「代幣」功能可控制所有工作區。所發出的存取權限可將其他使用者限制在選定的帳戶和聊天室中,並可設定獨立的權限與會話限制。
- 帳戶會重新命名一個工作區,並刪除已新增的工作區,連同其會話、日誌、 來源及簽名金鑰一併刪除。主工作區無法從控制面板中刪除。
批次匯入和帳戶群組#
請使用「帳戶」→「匯入帳戶」來新增多個帳戶,根據檔案基名配對檔案 並查看每個登入結果。每個帳戶都會擁有專屬的工作區。
群組可將相關帳戶彙整在一起,同時不會合併其會話、金鑰或
證據。在「帳戶」中開啟「群組」將導向其頁面: /groups/<id>:
- 帳戶:每位成員的連線路徑、觀察記錄及最後一則訊息,並附有 「全部啟動」與「全部暫停」功能。
- 需要注意:已登出、無法使用,或存在 連線、匯入、來源或媒體問題的帳戶;每個名稱皆可導向其對應的卡片。
- 多個帳戶可查看的聊天內容包含: 共享來源、正在監看這些來源的帳戶,以及 可用工作區監看期間(最長七天)內的中斷情況。使用 N 個帳戶進行匯出時, 系統會將頻道或超級群組的匯出內容分配至各帳戶,並對單一存檔進行簽署。
- 匯出群組:包含一個 ZIP,其中每個帳戶的簽名匯出檔位於
accounts/,並manifest.json列出其SHA-256與金鑰指紋,並由主 工作區在manifest.signature.json。請使用python -m tgwitness.verify並使用該帳戶的可信指紋,分別驗證每個帳戶的存檔。
成員共享群組的設定;每個帳號可保留其自身的設定值。 請參閱「共享設定」、 「匯入與群組指南」 以及 MTProxy 資料池儀表板。
登出#
更多工具 → 帳戶 → 登出 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 擁有多個帳戶;請參閱「不支援的格式」。 |
| 選定的檔案描述了不同的帳戶或 API 憑證 | 僅選取單一帳戶的檔案。 |
| JSON 內容中未包含任何受支援的 API 憑證或授權資訊 | 請檢查 Account JSON 中的欄位名稱。 |
| 僅限 API 元資料 | 該 JSON 檔案未包含會話資訊。請新增 .session 檔案,或使用手機/QR 碼。 |
| 授權金鑰的十六進位值必須包含全部 512 個十六進位字元 | 金鑰已被截斷或包含「…」。 |
| 帳號 ID 與匯入的帳號不符 | 該檔案的用戶 ID 與 Telegram 所顯示的不符;此檔案屬於另一個帳號。 |
| 該帳號已屬於另一個工作區 | 請開啟該工作區,而非重複新增該帳號兩次。 |
| 已連線,但「更多工具」→「來源」中的聊天清單缺少一個私人群組 | 檢查成員資格。揀選器會檢查前1,000個對話;請在「更多工具」→「參數」中提高此限制。 |
| 代理連線失敗 | 請檢查路由與 IP 模式。自動模式 MTProxy 會嘗試其他可用的入口。隱藏位址模式會進行等待;「直接」模式作為最後手段,可在設定的延遲時間過後直接連線。請參閱路由模式說明。 |