工作流程與操作

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

操作員工作流程#

圖表轉為文字

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

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

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

開放存取功能可讓審閱者或分析師擁有專屬的存取憑證。選擇 他們可開啟的帳戶與聊天室，並授予檢視、匯出或執行操作的權限。 負責啟動／停止資料蒐集的操作員需具備整個工作區的存取權限；審閱者 則可限制為僅能存取單一聊天室。會話限制、有效期限及 IP 規則與 Telegram 帳戶授權相互獨立。請參閱存取權限與授權設定。

使用「開啟的會話」來終止連線，或撤銷存取權限以終止所有 相關會話。管理員控制台會整合各工作區中 當前進程的活動。關閉會話後，資料蒐集仍會繼續運行。

執行模式#

本地示範版本會自動開啟，無需手動輸入憑證。其採用 僅限於直接迴路存取隔離式 模擬示範環境的「程序生命週期」權限；主控制面板的憑證不會被揭露。實際工作區以及遠端 或透過代理伺服器存取的示範環境，仍需透過憑證進行驗證。進入示範環境並不授予任何 Telegram 授權。

監控類別#

在「來源」→「擷取設定」→「選擇要保留的變更」中，可分別選取新訊息、編輯、 刪除通知、反應更新及成員事件。預設 會保留所有類別。「訊息、編輯與刪除」模式會保留原始上下文， 同時停用獨立的反應／成員更新。 「所有可見活動」選項將 同時保留上述五類項目。預設值會變更呈現形式；請按下「儲存監控設定」以套用變更。

儲存的政策適用於該工作區內所有選定的來源。其他 工作區則保留其自身的設定。每次實際變更都會記錄經簽署的「變更前」與「變更後」 數值；當前的政策也會包含在處理收據和觀察 開始記錄中。停用某個類別並不會刪除先前的觀察記錄。重新啟用 也不會找回遺漏的變更。 此版本中不提供按群組類別的覆寫功能。

當先前內容至關重要時，請保持「新訊息」功能啟用：刪除通知無法 恢復從未被擷取過的文字。運作／覆蓋記錄及其他群組 服務事件將始終予以保留。 明確的歷史快照與 即時類別選取功能相互獨立，且可能包含服務訊息。這些設定不會 遮蔽嵌入於已擷取 Telegram 物件中的反應／成員元資料。

歷史快照在暫停期間可能會將附件加入佇列。請啟動監測以處理 這些附件。「已加入佇列」並不代表已下載。若原始檔案不可用，系統不會以 較新的編輯版本取代；相關結果將分別記錄。

點擊「鎖定」按鈕會清除瀏覽器存取權限及隱私欄位，但仍會讓資料收集持續運作。 關閉分頁同樣會讓程序持續運作。停止 Python 程序或服務 將停止資料收集，無論瀏覽器狀態為何。

刪除額外的工作區將停止其收集器並移除其本地資料。若因 檔案被鎖定或檔案系統錯誤而中斷移除程序，控制面板將回報失敗，並 將該工作區維持為「不可用」（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 選取的，不包含公開連結。「存取狀態」描述的是最近一次檢查結果，而非永久權限。

篩選來源並勾選其核取方塊，即可一併啟用、暫停或標記為優先項目。在可用對話清單中，加入所選項目會套用您的選取項目；加入所有符合項目則會套用目前的搜尋條件與類型篩選器。

「聊天室」→「人員」列出所有已儲存訊息的使用者；若該聊天室已啟用 使用者個人檔案功能，點擊即可開啟該使用者的個人檔案，其中包含連結至日誌記錄的連結。

Witness 會建立唯讀的「見證代幣」，顯示每個見證者最後一次檢查的時間， 並提供執行單一（獨立見證者）所需的指令與選項。

「參數」頁面收錄了所有未列於其他頁面的工作區限制與節奏設定： 已讀對話數、聊天清單重新讀取頻率、心跳訊號與檢查點 間隔、啟動緩衝區、重新檢查請求的分散方式（首次延遲、每次 ），聊天間的暫停時間、已恢復與重新請求的訊息數量），磁碟預留空間、下載的超時與 重試設定，使用者個人檔案的搜尋條件（包含您自訂的正規表達式）， 通知的大小與頻率，快照、ZIP 及瀏覽器下載限制，以及 Telegram 客戶端的超時與重試設定。 每個欄位皆顯示其範圍與預設值；已變更的欄位會 被標記，並可逐一或全部還原。每項變更皆會以 「parameters.changed」的形式記錄，並附上變更前後的數值，而觀察起始記錄則會標明 當時生效的數值。 設定值將自下次使用時生效；客戶端超時與重試則自 下次連線時生效。重新檢查間隔、附件類型與大小、證據及站外副本 間隔仍保留在各自的頁面中，且可設定為其範圍內的任何值，而不僅限於預設值。

頂部工具列中的鈴鐺圖示會列出受監控聊天室中的近期問題與變更；未讀項目 會持續計數，直至被標記為已讀。變更會按聊天室和小時分組顯示（「12 則刪除、 1 則編輯、0 則未找到」），而諸如登出或磁碟空間已滿等問題，無論聊天室 有多繁忙，都會持續保留在清單中。

帳戶設定從「電話號碼」欄位開始。繼續操作將直接進入 驗證碼輸入頁面，僅在缺少 API 憑證時才會要求輸入。QR 碼與檔案匯入為 替代選項標籤頁。已儲存的 API 憑證僅限於其所屬的工作區內重複使用。 登入畫面不包含側邊欄、統計資料或設定說明段落。 點擊「設定」 圖示可開啟 API、代理伺服器、儲存空間及額外帳戶的控制選項。新安裝 程序由此開始；已連線但未選取來源的帳戶則從「選擇聊天室」開始。 變更監測路徑需暫停監測，並會取消未完成的登入程序。現有的 日誌無法在未經通知的情況下重新綁定至其他 Telegram 帳戶。

匯出功能會檢查日誌的完整性，並產生可攜式檔案。其工作區 ID 可傳遞至下載命令列介面 (CLI)。每次匯出都會鎖定完整的日誌前綴；後續 事件將納入下一次匯出。搜尋篩選條件不會改變封裝範圍。 詳細的簽名與涵蓋範圍資訊請參閱「驗證與限制」部分。

在「收集器狀態」面板中，會顯示收集器狀態、排隊中／失敗的媒體、最舊的待處理媒體、可用 磁碟空間、請求暫停，以及存取狀態未確認的來源。 這些詳細資訊預設為收合狀態，並在「帳戶」頁面中隱藏。設定 卡片會顯示下一步驟：連結帳戶、選擇來源，或開始監測。 帳戶清單為載入時的快照； 所選工作區會定期刷新。此非多進程 SLA 監控工具。

使用者介面採用本地資源及文字渲染技術來呈現原始內容。已針對桌面版及窄版 Chromium 版面配置進行測試。此並非完整的無障礙認證； 螢幕閱讀器及人機互動可用性評估仍屬獨立工作項目。

部署環境#

可移植性意味著無需強制使用雲端服務或前端建置。每個目標系統仍 需要相容的 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. 記錄系統停機時間及驗證結果。歷史快照無法證明 在中斷期間未曾發生刪除行為。

證據 ZIP 檔案不包含會話資料／私密金鑰，且並非完整服務備份。 以下四項內容的保護方式有所不同：

所謂的「完整服務備份」是指上述所述的已暫停資料目錄，而非匯出檔案。 兩者皆應使用受保護的儲存空間及經過周詳設計的傳輸機制。臨時伺服器匯出檔案存放於各工作區的 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。

應以每秒事件數、佇列存留時間、媒體資料位元組數及磁碟延遲為衡量標準，而非僅統計 群組數量。合成式本地基準測試無法保證 Telegram 訊息的送達成功率。 本工具不具備自動保留與刪除功能。移除日誌尾端將使其 與已保留檢查點的關聯性失效。

現已具備優先重新檢查機制：標記為星號的來源預設每 15 分鐘重新檢查一次， 其餘來源則每 6 小時重新檢查一次（參見重新檢查層級）。如上所述， 提供受密碼保護的匯出功能。 Telegram／代理伺服器的即時接收、持久性重播、 管理員日誌與反應汲取、隔離式工作節點、由 TgWitness 自身執行 的本地日誌與媒體加密，以及獨立審查，目前仍屬獨立開發項目。範圍式存取權限 詳見「存取與權限」文件。 請參閱 READINESS.md、LIVE_ACCEPTANCE.md 及 VERIFICATION.md。