本頁部分內容仍為英文:英文原文在翻譯後已進行修改。
參考資料 / 收集
Telegram · 工作流程與操作
控制面板的日常操作:運作模式、監控類別、參數、通知、匯出、備份及容量。
首次連線時,請使用帳戶與連線格式。 關於儲存版本、事件政策及資料缺口等說明,請參閱 「資料蒐集運作方式」。本指南涵蓋日常操作與資料復原。
受管安裝包含 、START-HERE.html、 及 START-HERE.txt、,以及
其啟動程式,其中儲存庫連結與指令已針對其安裝路徑
進行客製化。透過 SSH 執行 tgwitness guide --print,或執行 tgwitness paths 以定位
實際資料目錄。root 權限的 systemd 安裝會將私有狀態儲存於
/var/lib/tgwitness-…;/opt/tgwitness 則存放程式本体。
對於受管理的臨時 Cloudflare 隧道,tgwitness tunnel off 會關閉公開
存取,同時本地控制面板和資料收集功能仍會繼續運作。tgwitness tunnel on
會啟用公開存取;tgwitness tunnel restart 會建立新的隧道連線。使用
tgwitness open 可查看其當前位址。明確的關閉設定會保留至
服務重新啟動後。tgwitness stop 會同時停止控制面板和資料收集功能。
操作員工作流程#
圖表轉為文字
- 選擇儲存方式與金鑰保護機制 → 使用其憑證開啟控制面板
- 使用其憑證開啟控制面板 → 選擇工作區
- 選擇工作區 → 設定直接連線或代理伺服器路徑
- 設定直接連線或代理伺服器路徑 → 輸入電話號碼或選擇檔案/QR 碼
- 輸入電話號碼或選擇檔案/QR 碼 → 驗證帳號身分並選擇可加入的群組
- 驗證帳號身分並選擇可加入的群組 → 儲存事件與附件政策,然後開始監測
- 儲存事件與附件政策,然後開始監測 → 監控錯誤、存取、佇列及磁碟狀況
- 監控錯誤、存取、佇列及磁碟狀況 → 保留獨立檢查點
- 保留獨立檢查點 → 匯出與驗證資料
授權、傳輸連線狀態、群組存取權限以及傳送完整性 是不同的屬性。連線狀態顯示為綠色,並不表示所有 事件均已被擷取。
在不分享主金鑰的情況下分享工作成果#
開啟「更多工具」→「存取權限」,以向審查員或分析師發放專屬憑證。選擇 其可開啟的帳戶與聊天室,並授予檢視、匯出或操作權限。 負責啟動/停止資料蒐集的操作員需具備整個工作區的存取權限;審查員 的權限則可限制於單一聊天室。會話限制、有效期限及 IP 規則與 Telegram 帳戶授權相互獨立。請參閱「存取權限與權限設定」。
使用「開啟的會話」來終止連線,或撤銷存取權限以終止所有 相關會話。管理員控制台會整合各工作區中 當前進程的活動。關閉會話後,資料蒐集仍會繼續運行。
執行模式#
| 模式 | 操作說明 | 行為 |
|---|---|---|
| 示範 | scripts\Demo.cmd 或 --demo |
合成數據;已停用真實帳戶連結功能 |
| 觀察 | 開始監測 | 記錄所選來源的已發佈更新 |
| 歷史快照 | 聊天 → 聊天操作 → 載入歷史紀錄 | 最多可儲存 500 則當前訊息;不會重建所有過往變更紀錄 |
| 暫停 | 暫停觀察 | 在保留資料與排程任務的同時停止資料蒐集 |
| 審閱/交接 | 匯出功能 | ZIP、JSONL/CSV/HTML、檢查點、處理收據及時間戳記請求 |
| 多個帳戶 | 工作區或頂部的 + 按鈕 | 單一進程中可建立任意數量的獨立工作區 |
本地示範版本會自動開啟,無需手動輸入憑證。其採用 僅限於直接迴路存取隔離式 模擬示範環境的「程序生命週期」權限;主控制面板的憑證不會被揭露。實際工作區以及遠端 或透過代理伺服器存取的示範環境,仍需透過憑證進行驗證。進入示範環境並不授予任何 Telegram 授權。
監控類別#

在「更多工具」→「來源」→「記錄」→「選擇要保留的變更」中,可分別選取新訊息、編輯、 刪除通知、反應更新及成員事件。預設 會保留所有類別。「訊息、編輯與刪除」會保留原始上下文, 同時停用獨立的反應/成員更新。「所有可見活動」則會恢復 全部五項。預設值會變更表單;按下「儲存記錄設定」以套用。
儲存的政策適用於該工作區內所有選定的來源。其他 工作區則保留其自身的設定。每次實際變更都會記錄經簽署的「變更前」與「變更後」 數值;當前的政策也會包含在處理收據和觀察 開始記錄中。停用某個類別並不會刪除先前的觀察記錄。重新啟用 也不會找回遺漏的變更。 此版本中不提供按群組類別的覆寫功能。
當先前內容至關重要時,請保持「新訊息」功能啟用:刪除通知無法 恢復從未被擷取過的文字。運作/覆蓋記錄及其他群組 服務事件將始終予以保留。 明確的歷史快照與 即時類別選取功能相互獨立,且可能包含服務訊息。這些設定不會 遮蔽嵌入於已擷取 Telegram 物件中的反應/成員元資料。
歷史快照在暫停期間可能會將附件加入佇列。請啟動監測以處理 這些附件。「已加入佇列」並不代表已下載。若原始檔案不可用,系統不會以 較新的編輯版本取代;相關結果將分別記錄。
點擊「鎖定」按鈕會清除瀏覽器存取權限及隱私欄位,但仍會讓資料收集持續運作。 關閉分頁同樣會讓程序持續運作。停止 Python 程序或服務 將停止資料收集,無論瀏覽器狀態為何。
一旦包含該工作區 日誌及其「案例板」筆記的已簽署 ZIP 或 ASiC-E 容器已完整下載,即可刪除該工作區。僅準備好檔案還 不夠:若存在非設定事件的記錄,或於下載後新增的筆記,則「刪除」 選項將無法使用。
當面板接收到檔案本身時,它會在接收完所有
位元組後才將該檔案計入匯出統計,並將檔案大小回報至 POST /api/exports/{id}/received;若下載過程中斷,
則不會被計入。若使用瀏覽器的儲存選取器(檔案系統存取),面板會在
檔案寫入並關閉後才進行回報。 若未使用此功能,控制面板會將接收到的檔案交由瀏覽器的
下載功能處理,且無法得知瀏覽器是否已保留該檔案(例如當其儲存對話方塊被
取消時);此時控制面板僅會顯示下載已開始,而非檔案已儲存。 由
瀏覽器自行下載的檔案(即大於面板瀏覽器緩衝區的匯出檔案)以及
透過其他 HTTP 客戶端進行的下載,均在伺服器傳送完整回應後才計入。由於
作業系統和反向代理會緩衝數百萬位元的回應資料,因此對於這類
下載,伺服器無法偵測到接近尾聲時的中斷。 除非面板顯示檔案已儲存,
否則請在刪除前檢查已下載的檔案。群組匯出檔案若在
準備完成後立即下載,則會計入該帳戶的統計;若從「已準備的匯出」中再次下載,則不計入。
Before deleting, the panel shows the format, size, preparation time and SHA-256 of the last downloaded
signed archive and asks to confirm that this archive is saved outside the workspace. The server refuses
DELETE /api/profiles/{id} without kept_copy set to that SHA-256 (or to confirmed for an archive
downloaded before the fingerprint was recorded).
刪除額外的工作區將停止其收集器並移除其本地資料。若因
檔案被鎖定或檔案系統錯誤而中斷移除程序,控制面板將回報失敗,並
將該工作區維持為「不可用」(DeletionPending)狀態。請關閉持有該
檔案的程式,並重新嘗試「刪除」。 重新啟動 TgWitness 會使該工作區保持停止狀態,且
不會重建其部分已刪除的日誌或金鑰。只有在目錄被移除後,
才會記錄成功的刪除操作;另行匯出或備份的副本仍
受其自身的保留政策規範。
通知#
開啟「設定」→「通知與站外備份」→「通知目的地」,或 「更多工具」→「進階」→「通知」→「設定」。TgWitness 使用 Apprise 將警示傳送至 Matrix、Telegram、Discord、Slack、ntfy、電子郵件及其他 受支援的服務。您可以在一個工作區中新增多個通知目的地。
- 請每行輸入一個 Apprise 目標網址。請根據您的服務,使用對應的 服務目錄及網址格式。
- 開啟「傳送通知」功能,然後選擇問題警示、監測中 的聊天室變動以及每日摘要。摘要所顯示的時間以伺服器時間為準。
- 若希望在警示中包含已刪除及已編輯訊息的保存內容,請啟用「包含簡短摘錄」選項。 訊息。
- 請按下「儲存通知」,然後點選「發送測試訊息」以檢查訊息是否送達。
若要使用您自己的接收端,請採用 Apprise 的 JSON Webhook。
例如,jsons://notify.example.org/tgwitness 會透過 HTTPS 將 JSON 傳送至該
端點。此為虛構範例;請將其替換為您自己的目的地。
目的地與設定均屬於所選的工作區。變更通知 涵蓋其監測的來源,包括新加入的聊天室。頂部工具列中的鈴鐺圖示 亦會列出近期問題及聊天室變更。
在示範版本中,通知控制項雖可見,但發送功能已停用。請在真實的工作區中設定 傳送方式。通知將使用該工作區的 Direct、SOCKS5 或 HTTP 路由;MTProxy 無法傳輸這些通知。非 HTTP 目的地(例如 SMTP)則需要 直接路由。
面板佈局#

日誌顯示觀察結果、搜尋功能及篩選條件。編輯操作會開啟已擷取的版本; 刪除操作則會開啟先前內容(如有)。來源不明之內容將明確標示。 統計數據可在「概覽」中查閱;資料擷取詳情則收錄於本地指南中。
開啟已編輯的訊息,即可使用文字內差異或並排比較來比對不同版本;原始資料則會顯示已儲存的欄位。隱藏連結與機器人按鈕的變更會分開顯示。開啟附件預覽即可檢查已儲存的圖片、音訊或影片;下載按鈕可讓您隨時取得所保留的原始檔案。
Live 會在記錄送達時即時更新日誌與對話。您可以在檢閱時將其暫停,或於準備好時使用新事件按鈕;資料收集仍會在背景持續運作。按 Ctrl/Cmd+K 可尋找面板操作並搜尋日誌。
更多工具 → 「來源」包含觀察範圍(選定的聊天室、Telegram 資料夾或整個 帳戶)、各類可存取的聊天室、標有優先級星號的選定來源、附件 與重新檢查設定,以及歷史快照。私人來源是透過對話/ID 選取的,沒有公開連結。存取狀態描述的是最近一次檢查結果,而非永久權限。
篩選來源並勾選其核取方塊,即可一併啟用、暫停或標記為優先項目。在可用對話清單中,加入所選項目會套用您的選取項目;加入所有符合項目則會套用目前的搜尋條件與類型篩選器。
「聊天室」→「人員」列出所有已儲存訊息的使用者;若該聊天室已啟用 使用者個人檔案功能,點擊即可開啟該使用者的個人檔案,其中包含連結至日誌記錄的連結。
更多工具 → 附加功能 → 「獨立見證人」會建立唯讀的見證人代幣,顯示各見證人上次檢查的時間,並 提供執行獨立見證人的指令與選項。
更多工具 → 「參數」包含工作區中未列於其他頁面的所有限制與節奏:
已讀對話數、聊天清單重新讀取頻率、心跳與檢查點
間隔、啟動緩衝區、重新檢查如何分散其請求(首次延遲、每次
,聊天間的暫停時間、已恢復及重新請求的訊息),磁碟預留空間、下載的超時與
重試設定、使用者檔案的搜尋條件(包含您自訂的正規表達式),
通知的大小與頻率、快照、ZIP 及瀏覽器下載限制,以及 Telegram
客戶端的超時與重試設定。每個欄位皆顯示其範圍與預設值;已變更的欄位會
被標記,並可逐一或全部還原。 每項變更都會以
parameters.changed 的形式記錄,並包含變更前與變更後的數值;而監測起始記錄則會標示
當前生效的數值。數值將從下次使用時生效;客戶端超時與重試則從
下次連線時生效。重新檢查間隔、附件類型與大小、證據及站外副本
間隔仍保留在各自的頁面中,且可設定為其範圍內的任何數值,而不僅限於預設值。
頂部工具列中的鈴鐺圖示會列出受監控聊天室中的近期問題與變更;未讀項目 會持續計數,直至被標記為已讀。變更會按聊天室和小時分組顯示(「12 則刪除、 1 則編輯、0 則未找到」),而諸如登出或磁碟空間已滿等問題,無論聊天室 有多繁忙,都會持續保留在清單中。
更多工具 → 帳戶 設定從「電話號碼」欄位開始。點擊「繼續」 將直接進入 程式碼輸入頁面,僅在缺少 API 憑證時才會要求提供。QR 碼與檔案匯入是 替代選項標籤頁。已儲存的 API 憑證僅限於其所屬的工作區內重複使用。 登入畫面沒有側邊欄、統計資料或設定說明。點擊「設定 」圖示可開啟 API、代理伺服器、儲存空間及新增帳戶的控制選項。建立新工作區時會開啟 首次設定畫面 ;登入後,包含已儲存來源與記錄的工作區會開啟「聊天」功能 。 變更路徑需先暫停監測,並會取消未完成的登入程序。現有的 日誌無法在未經使用者知情的情況下重新綁定至其他 Telegram 帳戶。
匯出功能會檢查日誌完整性並產生可攜式檔案。其工作區 ID 可傳遞給下載命令列介面 (CLI)。每次匯出都會鎖定完整的日誌前綴;後續 事件將納入下一次匯出。搜尋篩選器不會改變套件範圍。 詳細的簽名與覆蓋範圍資訊請參閱「驗證與證據」章節。
在「收集器狀態」面板中,會顯示收集器狀態、排隊中/失敗的媒體、最舊的待處理媒體、可用 磁碟空間、請求暫停,以及存取狀態未確認的來源。 這些詳細資訊預設為收合狀態,並在「帳戶」頁面中隱藏。設定 卡片會顯示下一步驟:連結帳戶、選擇來源,或開始監測。 帳戶清單為載入時的快照; 所選工作區會定期刷新。此非多進程 SLA 監控工具。
介面使用本機資源,並以文字方式呈現來源內容。已測試 Chromium 中的桌面版面與窄版面。
部署環境#
| 環境 | 安裝 | 驗證狀態 |
|---|---|---|
| Windows 個人電腦/伺服器 | Python 3.11 以上版本,腳本位於 Setup.cmd/Start.cmd,私人資料目錄 | 已於 Windows/Python 3.12 環境下進行本地測試 |
| Linux 伺服器/VPS | Python venv、專用服務使用者、HTTPS/SSH | 提供程式碼、持續整合(CI)及 systemd 範例;未在此主機上執行 |
| macOS | Python venv、前台程序或使用者代理程式 | 提供 launchd 範例;需另行進行安裝檢查 |
| Docker/Compose | 持續性儲存容量,單一工作節點 | 提供定義及 CI 執行時檢查;本地端無法使用 Docker |
| 手機瀏覽器 | 連線至正在運行的伺服器上的受保護控制面板 | 已針對 Chromium 瀏覽器進行狹幅版面配置測試;此資料擷取工具無法在 iOS/Android 系統上運行 |
可移植性意味著無需強制使用雲端服務或前端建置。每個目標系統仍 需要相容的 Python/加密套件、本地磁碟及網路存取權限。請參閱 DEPLOYMENT.md 及服務範本。
工作區會共用 CPU、記憶體及事件迴圈。若需進行程序隔離,請使用不同的 執行個體、連接埠、資料目錄及帳戶授權。不同執行個體之間並無統一的 控制面板。切勿讓多個工作執行個體指向同一個資料庫。
啟動檢查與匯出功能#
在啟動預先準備好的環境之前,請執行 python start.py --check。若需進行機器可讀的檢查,請添加 --json
,或傳入預設的 --data-dir、--host 及 --port。
此指令會在無需登入 Telegram 或建立日誌的情況下,檢查先決條件。
日誌驗證會在應用程式啟動時執行,且就緒狀態會顯示
在控制面板上。若端口已被佔用,可能是因已有實例正在運行所致。
支援「檔案系統存取 API」的瀏覽器會透過可寫入的 串流儲存匯出資料。其他瀏覽器最多僅能緩衝 128 MiB。若需匯出較大 的資料量,或使用不支援檔案串流的瀏覽器,請使用串流命令列介面 (CLI):
python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip
從「Exports」中新增 --profile ID
以建立子工作區。使用 --url https://server
進行遠端存取。僅接受用於迴路目的地之純 HTTP 連線。該憑證
會從檔案中讀取並透過標頭傳送,不會被輸出或放入 URL 中。不接受
重定向。現有目的地不會被覆寫。 傳輸失敗時,其
臨時部分檔案將被移除。報告的 SHA-256 為傳輸校驗和;請使用可信的指紋/檢查點,
另行驗證已簽名的 ZIP 檔案。
備份、還原與中斷#
- 暫停監控並乾淨俐落地終止該程序。
- 複製整個資料目錄:資料庫、若存在則包含 WAL/SHM、媒體檔案、
credentials.enc、signing.enc、network.enc、金庫金鑰/元資料、憑證、 檢查點以及每個profiles/目錄。 - 對於外部金鑰模式,請將主金鑰與每個
vault.external.json分開保存。生成新金鑰無法恢復舊的機密資訊。 - 在目標端停止運作時進行還原;在恢復運作前,請設定原始金鑰、限制 存取權限,並驗證資料完整性。
- 記錄停機時間與驗證結果。停機時間仍維持為已記錄的間隙; 歷史快照則會將其後的狀態加入其中。
Evidence ZIPs exclude sessions/private keys and are not full service backups.
tgwitness backup FOLDER makes the same copy while the panel keeps running and leaves out the
search index, which rebuilds itself; see Updates and backups.
Four things are protected differently:
| 什麼 | 保護 |
|---|---|
| 無需密碼即可匯出檔案(預設設定) | 已簽名,因此可偵測到任何變更;設定密碼即可加密匯出檔案 |
| 以密碼保護的檔案進行匯出 | 若您設定了密碼,導出的檔案將以未經修改的狀態封裝成 WinZip AES-256 ZIP 檔案,該檔案可透過 7-Zip 和 WinRAR 開啟;密碼不會被儲存(以符合證據處理規範) |
| 記錄本資料庫及儲存於磁碟上的附件 | 加密磁碟或磁碟區以及資料夾權限 |
| Telegram 會話與簽名金鑰 | 資料目錄中以加密形式儲存(credentials.enc、signing.enc、network.enc) |
所謂的「完整服務備份」是指上述所述的已暫停資料目錄,而非匯出檔案。
兩者皆應使用受保護的儲存空間及經過周詳設計的傳輸機制。臨時伺服器匯出檔案存放於各工作區的
temporary-exports/ 中;已完成的回應會被清理,而中斷的匯出
檔案則會在下次啟動時,於該工作區的實例鎖定期間被移除。
在「連線恢復」事件發生後,收集器會從 已儲存的更新位置請求遺漏的更新。持久性媒體工作與 Telegram 更新位置在重新啟動後仍會保留;請參閱 證據格式。
儲存容量與保留期限#
預設限制(皆可於「更多工具」→「參數」中變更):前 1,000 個對話框、每張快照 500 則訊息
、4 GiB 未壓縮的簽名 ZIP 內容(較大的壓縮檔需
verify.py --max-gib N 並使用 128 MiB 瀏覽器備用方案。附件每種類型佔用 1–2,000 MiB
,設定路徑為「更多工具」→「來源」→「記錄」→「附件」。下載命令列介面預設傳輸量為 5 GiB。可用磁碟空間可能為
下限。 請預留空間供日誌、媒體、WAL、臨時匯出檔及備份使用。
匯出作業會使用資料卷,而非 Compose 的 512 MiB /tmp 目錄。
應測量每秒事件數、佇列年齡、媒體位元組數及磁碟延遲,而非僅統計 群組數量。即時傳送的測量是在運行的收集器上進行。 系統不具備自動保留刪除機制。移除日誌尾端將使其 與已保留檢查點的關聯失效。
優先複查已經可用:加星號的來源預設每 15 分鐘複查一次,其他來源每 6 小時複查一次(參見複查層級)。受密碼保護的匯出依上文所述運作。限定範圍的存取記載於存取與權限。參見 READINESS.md、LIVE_ACCEPTANCE.md 與 VERIFICATION.md。