TgWitness / 文件說明

已測試的內容 →

參考資料 / 設定

Telegram · 快速入門

安裝與啟動 TgWitness 的各種方式:Windows 套件、Python、Docker 以及合成示範,並包含初步檢查步驟。

TgWitness / 文件說明

開始使用

英文 · 俄語 · 烏克蘭語 · 西班牙語 · 葡萄牙語(巴西) · 土耳其語 · 阿拉伯語 · 波斯語 · 烏爾都語 · 印地語 · 印尼語 · 越南語 · 簡體中文

TgWitness 是一款用於監控您帳戶可存取之 Telegram 群組與頻道的獨立應用程式, 它於本地端運行,並擁有專屬的資料目錄。

初次造訪?請先瀏覽示範,再連結您的帳戶。 選擇代理伺服器、見證者、匯出或伺服器設定的指南。 GitHub Actions 擷取(預覽)功能會在您自己的 GitHub 分支中執行擷取,而非在本地端安裝環境中執行。

安裝與啟動#

引導式安裝程式內建 Python 環境,並會在安裝前檢查套件雜湊值與發行 簽名。再次執行該程式將更新現有安裝。

Linux / macOS:

curl -fsSL https://get.destroy.tools/install.sh | bash

Windows(PowerShell 或 命令提示字元):

powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://get.destroy.tools/install.ps1 | iex"

在 Ubuntu 伺服器上,請以 root 身分執行以安裝背景服務;在桌面電腦上,請 以您的一般使用者身分執行。在 Ubuntu 上,安裝程式會顯示控制面板網址與存取金鑰; 在 macOS 和 Windows 上,本地控制面板會直接在您的瀏覽器中開啟。請繼續進行下方的「連線至 Telegram」 步驟。安裝、驗證與更新部分涵蓋了伺服器存取選項、 執行腳本前的檢查、更新及移除等內容。

其他方法#

GitHub 發行版、原始碼及 Docker 皆可作為安裝程式的替代方案。可攜式 下載檔將於發行版建置發布後提供:

主機 無需安裝任何軟體 來源:Python 3.11+ Docker:Engine/Desktop 搭配 Compose 2.20 以上版本
Windows 從 GitHub Releases 中提取 TgWitness-<version>-windows-amd64-portable.zip,雙擊 TgWitness.cmd 雙擊 Start.cmd 雙擊 scripts\Docker.cmd
Linux / macOS — sh start.sh sh scripts/docker-start.sh

若採用原始碼方式,請下載並解壓縮目前的 main,或複製儲存庫:

git clone https://github.com/phishdestroy/TgWitness.git
cd TgWitness

如果找不到合適的 Python,Start.cmd 會提議為您的 Windows 使用者安裝 Python 3.12(透過 winget 或經過簽署的 python.org 安裝程式)。若缺少 Python,start.sh 會印出適用於您的 Linux 發行版或 macOS 的確切安裝指令。首次從原始碼啟動時,會自動建立 .venv 並安裝相依套件。

Docker 會編譯應用程式並在背景中啟動它;無需主機端的 Python 環境。 當容器運作正常時,scripts\Docker.cmd 和 scripts/docker-start.sh 會輸出控制面板位址與代幣。 在所有受支援的主機上,對應的 Docker 指令如下:

docker compose up -d --build --wait
docker compose exec tgwitness cat /data/panel-token.txt

開啟 http://127.0.0.1:8787。使用 Docker 輔助程式或第二個 Docker 指令所產生的憑證,或針對可攜式或原始碼安裝版本,從 data/live/panel-token.txt 讀取憑證。接著請前往 下方的「連線至 Telegram」步驟。 原生安裝與 Docker 安裝使用各自的儲存空間; 啟動 Docker 並不會匯入現有的原生日誌。

針對伺服器,部署內容涵蓋自動啟用 HTTPS、重新啟動、 發佈的圖片、更新及備份。

探索介面#

  1. 請在可攜式套件中執行 TgWitness-Demo.cmd ,在 Windows 原始碼 資料夾中執行 scripts\Demo.cmd ,或在 Linux/macOS 上執行 sh start.sh --demo 。首次從原始碼啟動時,系統會先建立 .venv 並安裝依賴項。
  2. 開啟 http://127.0.0.1:8787。
  3. 本地示範版本會自動開啟範例日誌。無需複製存取憑證即可直接進行本地存取。

示範訊息均為虛構。示範模式無法連線至真實的 Telegram 帳號。

連接 Telegram#

[!警告] 請使用專用帳號。Telegram 可能會因請求 量過大而限制或永久封禁帳號,無論使用何種客戶端。請連接專為 觀察準備的帳號,而非個人或重要帳號,並在 專用帳號上建立 API ID / 雜湊值。

  1. 若原生示範程式正在執行,請停止它並執行 Start.cmd 或 sh start.sh。 否則,請讓上述啟動的即時安裝版本繼續運行。
  2. 請使用面板代幣登入。開啟後將出現工作區初始設定畫面。 選擇「僅下載」、「追蹤聊天室」或「案件證據」。
  3. 請檢查連線狀態。如有需要,請自行設定代理伺服器;連線 設定在設定完成後仍可使用。
  4. 在 Connect Telegram 中,請選擇一個電話號碼、一個 QR 碼、帳戶檔案(TData、 .session、StringSession、帳號 JSON)或完整的授權金鑰。當系統要求時,請完成 Telegram 確認、驗證碼及雙步驟驗證密碼。
  5. 請確認顯示的帳戶、選擇聊天室並檢視您的設定。從最後一個畫面 完成操作。若僅選擇「下載」,「開始匯出」將啟動一次性的 匯出作業,並開啟「匯出」頁面以顯示進度;此操作不會啟用持續監測功能。

設定完成後,點選「對話 → 選擇」可變更選取的對話。設定選項可控制 資料蒐集與檔案;「更多工具 → 來源」提供詳細的來源清單 (標準或專家級別)。面板指南說明了六個主要 區段及其情境式控制項。

API ID + Hash 為選填項目:工作區會使用其儲存或匯入的配對組合, 或從內建池中選取可用的配對組合。若要使用您自己的應用程式,請將一組 API ID:API Hash 配對組合貼入 API ID 欄位。針對 Auth key,請貼上全部 512 個十六進位 字元,並選取提供的 DC ID。User ID 為選填項目,若輸入則會進行驗證。

API 憑證用於識別您的應用程式;它們本身並不會 授權任何帳戶。私人群組無需公開使用者名稱,但您的帳戶必須具備存取權限。

針對現有帳戶,請參閱帳戶與會話格式:此 面板支援 Telethon StringSession、Telethon/Pyrogram SQLite、單一帳戶 TData ZIP,以及受支援的帳戶 JSON 格式。請同時選取一個會話及其對應的 JSON 檔案, 按下「檢查檔案」,然後點選「連線帳戶」。QR 碼登入功能亦 可使用,且具備相同的可選 API 設定。 TDLib、機器人會話以及 CSV/JSON 帳戶清單均不支援。

若有多個帳戶,請使用帳戶 → 匯入帳戶並選取其受支援的工作階段檔案。隨附的 JSON 檔案會依主檔名自動配對;每個匯入的帳戶都會獲得各自的工作區。請參閱大量匯入與帳戶群組。

若要新增另一個帳戶,請按帳戶選取器旁的 + 符號,或使用 「帳戶」→「新增帳戶」。各工作區擁有獨立的會話、 日誌、金鑰、來源及佇列。切換檢視畫面時,其他收集器仍會繼續運作。 在此安裝環境中,同一個 Telegram 帳戶無法指派給兩個工作區。 工作區數量並無限制;由於它們共用同一個程序,因此容量取決於機器效能。

即時面板代幣用於保護您對 Telegram 授權及儲存 資料的存取權限;它與 Telegram API 憑證是分開的。僅有明確啟動且 直接存取的本地示範版本才會自動獲得存取權限。遠端/透過代理伺服器存取的示範版本仍會使用 data/demo/panel-token.txt。

檢視與匯出#

  • 日誌:可依來源及事件類型搜尋並篩選觀察記錄。
  • 選擇一項事件,以檢視其原始記錄、來源資訊及儲存的版本。
  • 編輯詳情會顯示可用的「編輯前」與「編輯後」內容。刪除詳情則會顯示 最後擷取的內容(如有);若為未知行為者,其身分仍屬未知。
  • 匯出格式:簽名 ZIP、JSONL、CSV 及離線 HTML。
  • 完整聊天記錄匯出(聊天 → 匯出聊天,或匯出 → 擷取或匯出單一 聊天):將單一聊天的完整可見 歷史記錄下載為簽名封包,其中包含 chat.json(Telegram 匯出風格)以及可讀的 chat.html。若帳戶為該私人聊天室成員,則可執行此操作。此為當前的 快照,並非已刪除或先前編輯過的訊息之重建。請使用 python verify.py chat-export.zip --fingerprint TRUSTED_SHA256 驗證 副本。
  • 儲存檢查點:將簽名日誌的邊界維持在收集器之外。
  • 下載簽名執行收據:保留收集器的程式/版本記錄。
  • 準備時間戳記請求:向時間戳記授權機構提交離線請求; 請參照 TIMESTAMP.md 文件以取得並驗證回應。
  • 驗證日誌:檢查事件簽名與鏈結。ZIP 匯出功能亦會檢查媒體檔案。

受支援的瀏覽器可將大型匯出檔直接儲存至指定檔案。其他瀏覽器 最多僅能緩衝 128 MiB。當伺服器正在運行時,串流命令列介面 (CLI) 支援 更大容量的下載,且無需緩衝整個回應:

python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip

若要使用其他工作區,請透過「匯出 → 工作區 ID」新增 --profile ID。 若要連線至遠端伺服器,請新增 --url https://your-server。預設傳輸限制為 5 GiB;可透過 --max-mib 調整此限制。 經簽署的 ZIP 內容預設有獨立的 4 GiB 未壓縮 驗證限制(透過「更多工具 → 參數」可提高此限制;請使用 verify.py --max-gib N 驗證此類檔案)。請使用可信的驗證器副本、 獨立保留的金鑰指紋,以及作為最低取證標準的時間戳記 授權機構的根憑證(--tsa-ca)來驗證該檔案。

查看安裝說明#

python start.py --setup-only
python start.py --check
python start.py --check --json

--check 會偵測本地依賴項、簽名支援、儲存空間、金鑰設定以及 監聽位址。此工具不會安裝任何軟體,也不會連線至 Telegram。若端口 處於繁忙狀態,可能表示另有實例正在運行。請改用其他 --port,或先停止該實例。

啟動程式會安裝至 .venv。輔助的 python -m tgwitness... 指令必須 在 Windows 上使用 .venv\Scripts\python.exe,或在 Linux/macOS 上使用 .venv/bin/python, 除非該環境已啟用。

會話、保護與操作#

封閉且一致的 Telethon SQLite .session 檔案可透過 python -m tgwitness.sessions account.session --out account.tgwitness-session 在本地端轉換,隨後 於「更多工具」→「帳戶」→「檔案」中載入。亦支援直接匯入檔案及 QR 碼登入。有關登入格式、SOCKS5、 HTTP CONNECT、MTProxy 及外部主金鑰的詳細資訊,請參閱 CONNECTION-SECURITY.md。

暫停監測將停止資料收集。鎖定僅會關閉瀏覽器存取權限。 關閉分頁後,收集程序仍會繼續運行。停止該程序才會中斷 資料收集;歷史快照無法還原所有遺漏的編輯或刪除紀錄。 了解資料收集在事件政策、附件佇列、 帳戶隔離及重新啟動行為方面的運作方式。

會話與機密資訊均經過加密。訊息內容、媒體檔案及匯出資料需存放於 加密磁碟或磁碟區中。應使用可信賴的金鑰驗證日誌簽名,並將檢查點分開儲存。 請針對所選的收集模式,審查擷取記錄、外部時間收據及環境證明。

請參閱 OPERATIONS.md 了解備份/還原操作,DEPLOYMENT.md 了解託管設定,以及 deploy/ 中的服務範例。已安裝的 控制面板中亦包含一份離線設定指南,網址為 /guide.html。

實際的驗證結果與現存的限制 詳載於 VERIFICATION.md 及 READINESS.md 文件中。