TgWitness / 文件說明

已測試的內容 →

本頁部分內容仍為英文:英文原文在翻譯後已進行修改。

參考資料 / 收集

Telegram · 工作流程與操作

控制面板的日常操作:運作模式、監控類別、參數、通知、匯出、備份及容量。

TgWitness / 文件說明 · 部署與復原

部署與復原

首次連線時,請使用帳戶與連線格式。 關於儲存版本、事件政策及資料缺口等說明,請參閱 「資料蒐集運作方式」。本指南涵蓋日常操作與資料復原。

受管安裝包含 、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 碼 → 驗證帳號身分並選擇可加入的群組; 驗證帳號身分並選擇可加入的群組 → 儲存事件與附件政策,然後開始監測; 儲存事件與附件政策,然後開始監測 → 監控錯誤、存取、佇列及磁碟狀況; 監控錯誤、存取、佇列及磁碟狀況 → 保留獨立檢查點; 保留獨立檢查點 → 匯出與驗證資料選擇儲存方式與金鑰保護機制使用其憑證開啟控制面板選擇工作區設定直接連線或代理伺服器路徑輸入電話號碼或選擇檔案/QR 碼驗證帳號身分並選擇可加入的群組儲存事件與附件政策,然後開始監測監控錯誤、存取、佇列及磁碟狀況保留獨立檢查點匯出與驗證資料
圖表轉為文字
  1. 選擇儲存方式與金鑰保護機制 → 使用其憑證開啟控制面板
  2. 使用其憑證開啟控制面板 → 選擇工作區
  3. 選擇工作區 → 設定直接連線或代理伺服器路徑
  4. 設定直接連線或代理伺服器路徑 → 輸入電話號碼或選擇檔案/QR 碼
  5. 輸入電話號碼或選擇檔案/QR 碼 → 驗證帳號身分並選擇可加入的群組
  6. 驗證帳號身分並選擇可加入的群組 → 儲存事件與附件政策,然後開始監測
  7. 儲存事件與附件政策,然後開始監測 → 監控錯誤、存取、佇列及磁碟狀況
  8. 監控錯誤、存取、佇列及磁碟狀況 → 保留獨立檢查點
  9. 保留獨立檢查點 → 匯出與驗證資料

授權、傳輸連線狀態、群組存取權限以及傳送完整性 是不同的屬性。連線狀態顯示為綠色,並不表示所有 事件均已被擷取。

在不分享主金鑰的情況下分享工作成果#

開啟「更多工具」→「存取權限」,以向審查員或分析師發放專屬憑證。選擇 其可開啟的帳戶與聊天室,並授予檢視、匯出或操作權限。 負責啟動/停止資料蒐集的操作員需具備整個工作區的存取權限;審查員 的權限則可限制於單一聊天室。會話限制、有效期限及 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、電子郵件及其他 受支援的服務。您可以在一個工作區中新增多個通知目的地。

  1. 請每行輸入一個 Apprise 目標網址。請根據您的服務,使用對應的 服務目錄及網址格式。
  2. 開啟「傳送通知」功能,然後選擇問題警示、監測中 的聊天室變動以及每日摘要。摘要所顯示的時間以伺服器時間為準。
  3. 若希望在警示中包含已刪除及已編輯訊息的保存內容,請啟用「包含簡短摘錄」選項。 訊息。
  4. 請按下「儲存通知」,然後點選「發送測試訊息」以檢查訊息是否送達。

若要使用您自己的接收端,請採用 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 檔案。

備份、還原與中斷#

  1. 暫停監控並乾淨俐落地終止該程序。
  2. 複製整個資料目錄:資料庫、若存在則包含 WAL/SHM、媒體檔案、 credentials.enc、signing.enc、network.enc、金庫金鑰/元資料、憑證、 檢查點以及每個 profiles/ 目錄。
  3. 對於外部金鑰模式,請將主金鑰與每個 vault.external.json 分開保存。生成新金鑰無法恢復舊的機密資訊。
  4. 在目標端停止運作時進行還原;在恢復運作前,請設定原始金鑰、限制 存取權限,並驗證資料完整性。
  5. 記錄停機時間與驗證結果。停機時間仍維持為已記錄的間隙; 歷史快照則會將其後的狀態加入其中。

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。