# 工作流程與操作

Canonical page: https://phishdestroy.github.io/TgWitness/zh-Hant/docs/reference/operations/

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

首次連線時，請[使用帳戶與連線格式](https://phishdestroy.github.io/TgWitness/zh-Hant/docs/reference/accounts/)。 關於儲存版本、事件政策及資料缺口等說明，請參閱 [「資料蒐集運作方式](https://phishdestroy.github.io/TgWitness/zh-Hant/docs/reference/collection/)」。本指南涵蓋日常操作與資料復原。

## 操作員工作流程

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

**圖表轉為文字**

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

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

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

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

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

## 執行模式

| 模式 | 操作說明 | 行為 |
| --- | --- | --- |
| 示範 | scripts\Demo.cmd 或 `--demo` | 合成數據；已停用真實帳戶連結功能 |
| 觀察 | 開始監測 | 記錄所選來源的已發佈更新 |
| 歷史快照 | 來源 → 歷史快照 | 最多可儲存 500 則當前訊息；不會重建所有過往變更紀錄 |
| 暫停 | 暫停觀察 | 在保留資料與排程任務的同時停止資料蒐集 |
| 審閱／交接 | 匯出功能 | ZIP、JSONL/CSV/HTML、檢查點、處理收據及時間戳記請求 |
| 多個帳戶 | 工作區或頂部的 **+** 按鈕 | 單一進程中可建立任意數量的獨立工作區 |

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

## 監控類別

![支援按帳戶設定監控選項，並提供合成來源資料](https://phishdestroy.github.io/TgWitness/assets/sources.png)

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

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

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

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

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

刪除額外的工作區將停止其收集器並移除其本地資料。若因 檔案被鎖定或檔案系統錯誤而中斷移除程序，控制面板將回報失敗，並 將該工作區維持為「不可用」（`DeletionPending`）狀態。請關閉持有該 檔案的程式，並重新嘗試**「刪除」**。 重新啟動 TgWitness 會使該工作區保持停止狀態，且 不會重建其部分已刪除的日誌或金鑰。只有在目錄被移除後， 才會記錄成功的刪除操作；另行匯出或備份的副本仍 受其自身的保留政策規範。

## 通知

開放**來源 → 通知 → 警示與每日摘要**。TgWitness 採用 Apprise 將警示發送至 Matrix、Telegram、Discord、Slack、ntfy、電子郵件及其他 受支援的服務。您可將多個接收端新增至同一個工作區。

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

若要使用您自己的接收端，請採用 Apprise 的 [JSON Webhook](https://appriseit.com/services/json/)。 例如，`jsons://notify.example.org/tgwitness` 會透過 HTTPS 將 JSON 傳送至該 端點。此為虛構範例；請將其替換為您自己的目的地。

目的地與設定均屬於所選的工作區。變更通知 涵蓋其監測的來源，包括新加入的聊天室。頂部工具列中的鈴鐺圖示 亦會列出近期問題及聊天室變更。

在示範版本中，通知控制項雖可見，但發送功能已停用。請在真實的工作區中設定 傳送方式。通知將使用該工作區的 Direct、SOCKS5 或 HTTP 路由；MTProxy 無法傳輸這些通知。非 HTTP 目的地（例如 SMTP）則需要 直接路由。

## 面板佈局

![使用合成資料建立連接工作區](https://phishdestroy.github.io/TgWitness/assets/connection.png)

**日誌**顯示觀察結果、搜尋功能及篩選條件。編輯操作會開啟已擷取的版本； 刪除操作則會開啟先前內容（如有）。來源不明之內容將明確標示。 統計數據可在「**概覽**」中查閱；資料擷取詳情則收錄於本地指南中。

開啟已編輯的訊息，即可使用**文字內差異**或**並排比較**來比對不同版本；**原始資料**則會顯示已儲存的欄位。隱藏連結與機器人按鈕的變更會分開顯示。開啟附件預覽即可檢查已儲存的圖片、音訊或影片；下載按鈕可讓您隨時取得所保留的原始檔案。

**Live** 會在記錄送達時即時更新日誌與對話。您可以在檢閱時將其暫停，或於準備好時使用新事件按鈕；資料收集仍會在背景持續運作。按 **Ctrl/Cmd+K** 可尋找面板操作並搜尋日誌。

**「來源」**部分包含監測範圍（選定的聊天室、Telegram 資料夾或整個 帳戶）、各類可存取的聊天室、標有優先星號的選定來源、附件 及重新檢查設定，以及歷史快照。私人來源是透過對話/ID 選取的，不包含公開連結。「存取狀態」描述的是最近一次檢查結果，而非永久權限。

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

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

**Witness** 會建立唯讀的「見證代幣」，顯示每個見證者最後一次檢查的時間， 並提供執行單一（[獨立見證者](https://phishdestroy.github.io/TgWitness/zh-Hant/docs/reference/witness/)）所需的指令與選項。

**「參數」**頁面收錄了所有未列於其他頁面的工作區限制與節奏設定： 已讀對話數、聊天清單重新讀取頻率、心跳訊號與檢查點 間隔、啟動緩衝區、重新檢查請求的分散方式（首次延遲、每次 ），聊天間的暫停時間、已恢復與重新請求的訊息數量），磁碟預留空間、下載的超時與 重試設定，使用者個人檔案的搜尋條件（包含您自訂的正規表達式）， 通知的大小與頻率，快照、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](https://phishdestroy.github.io/TgWitness/zh-Hant/docs/reference/deployment/) 及[服務範本](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.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 檔案不包含會話資料／私密金鑰，且並非完整服務備份。 以下四項內容的保護方式有所不同：

| 什麼 | 保護 |
| --- | --- |
| 無需密碼即可匯出檔案（預設設定） | 未經加密。由於經過簽名，因此可偵測到任何變更，但任何持有該檔案的人皆可閱讀其內容 |
| 以密碼保護的檔案進行匯出 | 若您設定了密碼，導出的檔案將以未經修改的狀態封裝成 WinZip AES-256 ZIP 檔案，該檔案可透過 7-Zip 和 WinRAR 開啟；密碼不會被儲存（[以符合證據處理規範](https://phishdestroy.github.io/TgWitness/zh-Hant/docs/reference/evidence/)） |
| 記錄本資料庫及儲存於磁碟上的附件 | TgWitness 本身不提供加密功能；請使用加密磁碟或磁碟區 |
| Telegram 會話與簽名金鑰 | 資料目錄中以加密形式儲存（`credentials.enc`、`signing.enc`、`network.enc`） |

所謂的「完整服務備份」是指上述所述的已暫停資料目錄，而非匯出檔案。 兩者皆應使用受保護的儲存空間及經過周詳設計的傳輸機制。臨時伺服器匯出檔案存放於各工作區的 `temporary-exports/` 中；已完成的回應會被清理，而中斷的匯出 檔案則會在下次啟動時，於該工作區的實例鎖定期間被移除。

連線恢復事件並不保證能恢復期間的變更。 持久性媒體處理任務及 Telegram 更新狀態在重新啟動後仍會保留；詳見 [證據格式](https://phishdestroy.github.io/TgWitness/zh-Hant/docs/reference/evidence/#durable-collection-and-process-receipts-02)說明。

## 儲存容量與保留期限

預設限制，皆可於**「參數」**中調整：前 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 小時重新檢查一次（參見[重新檢查層級](https://phishdestroy.github.io/TgWitness/zh-Hant/docs/reference/collection/#recheck-tiers)）。如上所述， 提供受密碼保護的匯出功能。 Telegram／代理伺服器的即時接收、持久性重播、 管理員日誌與反應汲取、隔離式工作節點、由 TgWitness 自身執行 的本地日誌與媒體加密，以及獨立審查，目前仍屬獨立開發項目。範圍式存取權限 詳見「[存取與權限](https://phishdestroy.github.io/TgWitness/zh-Hant/docs/reference/access/)」文件。 請參閱 [READINESS.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/READINESS.md)、[LIVE_ACCEPTANCE.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/LIVE_ACCEPTANCE.md) 及 [VERIFICATION.md](https://phishdestroy.github.io/TgWitness/zh-Hant/docs/reference/verification/)。