快速入門

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

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

初次造訪？請先瀏覽示範版本，再進行帳戶連結。 請選擇相關指南，內容涵蓋代理伺服器、Witness、資料匯出或伺服器設定。

安裝與啟動#

透過 GitHub Actions 擷取（預覽版）

請選擇一種方式。可攜式下載檔將於發行版本發布後提供：

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

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

目前的原始碼包含批次匯入帳戶、MTProxy 儀表板，以及可續傳的歷史記錄載入功能。0.7.0 免安裝預覽版及其發行版原始碼壓縮檔早於這些新增功能。請參閱更新日誌以了解版本差異。

如果找不到合適的 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#

[!警告] 請勿使用任何您無法承受損失的資源。我們強烈建議您不要連結 個人或重要帳戶，也不要在您重視的帳戶上建立 API ID / 雜湊值。 Telegram 會不預警且經常永久封禁帳戶，無論使用何種客戶端。 測試能否順利進行取決於 Telegram 本身，而非 TgWitness，且無法保證後續運作的穩定性。

1. 若原生示範程式正在執行，請停止它並執行 Start.cmd 或 sh start.sh。 否則，請讓上述啟動的即時安裝版本繼續運行。
2. 請使用您所採用安裝方式對應的控制面板代碼來開啟控制面板。
3. 若您需要使用代理伺服器，請前往「帳戶」→「設定」→「連線設定」→「變更連線路徑」進行設定。
4. 在「帳戶」中，輸入您的電話號碼並按下「繼續」，選擇 「QR 碼」→「顯示 QR 碼」，或選取檔案並按下「連結帳戶」。 API ID + Hash 為選填項目：工作區會使用其儲存或匯入的配對組合， 或從內建池中選取一組可用的配對組合。若要使用您自己的應用程式，請將一組 API ID:API Hash 配對組合貼上至 API ID 欄位。 若需完整的授權金鑰，請選擇「授權金鑰」，貼上全部 512 個十六進位 字元，並選取提供的 DC ID。使用者 ID 為選填項目，若輸入則會被勾選。
5. 請完成您所選的登入方式：手機號碼／驗證碼／雙因素驗證（2FA），或透過 已登入的 Telegram 應用程式掃描 QR 碼進行確認，亦可匯入受支援的授權會話。
6. 請確認顯示的帳號 ID。開放來源：您的聊天記錄會自動載入；請手動新增您的群組。
7. 在「選擇要保留的變更」下，請選取事件類別或「 訊息、編輯與刪除」預設值，然後儲存監控設定。
8. 請分別選擇附件設定，然後按下「開始監測」。

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

對於現有帳戶，請參閱帳戶與工作階段格式：面板接受 Telethon StringSession、Telethon/Pyrogram SQLite、單一帳戶 TData ZIP，以及受支援的帳戶 JSON。請同時選取工作階段及其隨附的 JSON，然後按下連結帳戶。也可以使用相同的選用 API 設定進行 QR 碼登入。不支援 TDLib、機器人工作階段，以及 CSV/JSON 帳戶清單。

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

若要新增另一個帳戶，請按帳戶選擇器旁的 +，或開啟 「帳戶」→「設定」→「連線設定」→「工作區」，亦可使用「帳戶」功能。各工作區擁有獨立的會話、 日誌、金鑰、來源及佇列。切換檢視畫面時，其他資料擷取程式仍會繼續執行。 在此安裝環境中，同一個 Telegram 帳戶無法指派給兩個工作區。 工作區數量沒有限制；由於它們共用同一個程序，因此容量取決於電腦的效能。

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

檢視與匯出#

• 日誌：可依來源及事件類型搜尋並篩選觀察記錄。
• 選擇一項事件，以檢視其原始記錄、來源資訊及儲存的版本。
• 編輯詳情會顯示可用的「編輯前」與「編輯後」內容。刪除詳情則會顯示 最後擷取的內容（如有）；若為未知行為者，其身分仍屬未知。
• 匯出格式：簽名 ZIP、JSONL、CSV 及離線 HTML。
• 完整聊天記錄匯出（來源 → 完整聊天記錄匯出）：將單一聊天室的完整可見 歷史記錄下載為包含 chat.json（Telegram-export 風格）及可讀取 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 驗證此類檔案）。請使用可信賴的驗證器副本以及 獨立保存的金鑰指紋／檢查點來驗證該檔案。

查看安裝說明#

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 在本地端轉換，隨後 載入至 Account。亦支援直接檔案匯入及 QR 碼登入。有關登入格式、SOCKS5、 HTTP CONNECT、MTProxy 及外部主金鑰的詳細資訊，請參閱 CONNECTION-SECURITY.md。

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

會話與機密資料均經過加密。訊息內容、媒體檔案及匯出檔案需儲存於 加密磁碟或磁碟區中。簽名僅能依據可信密鑰驗證資料的完整性； 無法驗證訊息源自 Telegram，亦無法防止由 控制資料收集器及其密鑰的操作者進行偽造。

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

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