參考資料 / 設定
Telegram · 快速入門
安裝與啟動 TgWitness 的各種方式:Windows 套件、Python、Docker 以及合成示範,並包含初步檢查步驟。
英文 · 俄語 · 烏克蘭語 · 西班牙語 · 葡萄牙語(巴西) · 土耳其語 · 阿拉伯語 · 波斯語 · 烏爾都語 · 印地語 · 印尼語 · 越南語 · 簡體中文
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、重新啟動、 發佈的圖片、更新及備份。
探索介面#
- 請在可攜式套件中執行 TgWitness-Demo.cmd
,在 Windows 原始碼
資料夾中執行 scripts\Demo.cmd
,或在 Linux/macOS 上執行
sh start.sh --demo。首次從原始碼啟動時,系統會先建立.venv並安裝依賴項。 - 開啟 http://127.0.0.1:8787。
- 本地示範版本會自動開啟範例日誌。無需複製存取憑證即可直接進行本地存取。
示範訊息均為虛構。示範模式無法連線至真實的 Telegram 帳號。
連接 Telegram#
[!警告] 請使用專用帳號。Telegram 可能會因請求 量過大而限制或永久封禁帳號,無論使用何種客戶端。請連接專為 觀察準備的帳號,而非個人或重要帳號,並在 專用帳號上建立 API ID / 雜湊值。
- 若原生示範程式正在執行,請停止它並執行 Start.cmd 或
sh start.sh。 否則,請讓上述啟動的即時安裝版本繼續運行。 - 請使用面板代幣登入。開啟後將出現工作區初始設定畫面。 選擇「僅下載」、「追蹤聊天室」或「案件證據」。
- 請檢查連線狀態。如有需要,請自行設定代理伺服器;連線 設定在設定完成後仍可使用。
- 在 Connect Telegram 中,請選擇一個電話號碼、一個 QR 碼、帳戶檔案(TData、
.session、StringSession、帳號 JSON)或完整的授權金鑰。當系統要求時,請完成 Telegram 確認、驗證碼及雙步驟驗證密碼。 - 請確認顯示的帳戶、選擇聊天室並檢視您的設定。從最後一個畫面 完成操作。若僅選擇「下載」,「開始匯出」將啟動一次性的 匯出作業,並開啟「匯出」頁面以顯示進度;此操作不會啟用持續監測功能。
設定完成後,點選「對話 → 選擇」可變更選取的對話。設定選項可控制 資料蒐集與檔案;「更多工具 → 來源」提供詳細的來源清單 (標準或專家級別)。面板指南說明了六個主要 區段及其情境式控制項。
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 文件中。