TgWitness參考資料 / 安全性與專案
架構
說明收集器、控制面板、日誌、工作節點及見證節點等組件，以及資料在這些組件間的流動方式。
一個 Python 程序負責託管 FastAPI 控制面板以及任意數量的隔離工作區， 每個工作區皆配有 Telethon 使用者帳戶客戶端。 SQLite 儲存僅支援追加的簽名事件日誌及可變更的操作設定。 加密金庫中存放 API 憑證、StringSession 以及簽名金鑰。 前端採用純粹的打包 HTML/CSS/JavaScript 格式：無需 Node 建置、CDN 或 前端執行時下載。
| 模組 | 責任聲明 |
|---|---|
| collector.py | 授權、對話選取、更新、快照、媒體佇列、連線監控 |
| interactions.py / telegram_client.py | 明確的面板操作、簽名收據、持久性請求 ID 以及任務本地的回調／加入重試政策 |
| message_content.py | 可觀察的訊息比對，不包含傳輸存取元資料 |
| workers.py | 在執行取消清理操作前，請先等待匯出檔案工作程序完成 |
| store.py | WAL 交易、有序事件鏈、查詢篩選器、運作設定 |
| security.py | 建立私人檔案、加密儲存庫、Ed25519 簽名、單一進程鎖定 |
| evidence.py | 完整日誌匯出、衍生檔、檢查點、附件驗證 |
| verify.py | 獨立運作、唯讀驗證器（標準函式庫 + 加密技術）：存檔、涵蓋範圍、證據日誌及頻道貼文、個人檔案 |
| app.py | 經認證的 API、生命週期、請求驗證、靜態控制面板 |
| profiles.py | 多帳戶收集器、共用存取控制器、按工作區管理的生命週期 |
| access.py | 範圍限定授權、權限檢查、IP 限制、會話限制及管理員控制台 |
| proxy_catalog.py | 公開頻道快照、傳輸檢查、共享代理伺服器池及基於運作狀態的選擇機制 |
| provenance.py | 經簽署的獲取執行階段身分、程式碼及依賴項測量 |
| network.py | 經驗證的各工作區傳輸路徑；已遮蔽的狀態與證據；Telethon 傳輸選項 |
| sessions.py | 已審核 Telethon SQLite 資料結構的離線唯讀轉換 |
| account_import.py | 對受支援的帳戶檔案及 JSON 進行記憶體內偵測與正規化 |
| tdata.py | 功能有限的現代 TData ZIP 讀取器，具備校驗和／解密驗證功能，不進行檔案解壓縮 |
| doctor.py | 無需資料蒐集、登入或安裝套件即可進行本地就緒性檢查 |
| download.py | 經過驗證的串流匯出下載功能，具備讀取限制且不會覆寫資料 |
| monitoring.py | 經驗證的「按工作區」事件政策與「按類型」附件規則，由處理者、狀態及簽名收據共享 |
| scope.py | 監測範圍（指定聊天室、Telegram 資料夾、整個帳戶）、來源類型、排除項目、重新檢查層級 |
| dossier.py | 根據儲存的記錄建立的每則聊天對話中的人物檔案：包含附有記錄參考的事實、頭像的 SHA-256/pHash 值，以及提及內容的擷取 |
| witness_api.py | 唯讀見證代幣及其可擷取的簽名日誌頭部 |
| witness.py | 獨立見證流程：自有金鑰與日誌、頭部檢查、簽名頻道貼文、匯出 |
| alerts.py | Apprise 通知與控制面板的通知清單 |
| logging_config.py | 無視窗模式啟動時的控制台記錄與輪替式伺服器診斷 |
| static/ | 響應式介面、本地存取閘道、篩選器、詳細資訊、匯出功能、帳戶設定 |
| demo.py | 標示為「合成日誌」，與實際蒐集資料完全隔離 |
監測處理程序須於連線前完成註冊。即時資料蒐集受以下條件限制： 活躍的客戶端身分、明確的執行狀態、已啟用的來源，或監測 範圍（資料夾或整個帳戶模式會在首次更新時將新聊天室新增為來源），以及事件 政策。遭拒絕或已被取代的客戶端無法貢獻即時更新。 原始反應與成員資格更新 均遵循可見性限制。傳入訊息內容及其持久化媒體任務將 一併提交。任務保留原始時間線描述符，並將其雜湊值綁定至 經簽名的訊息觀察記錄。發送者／編輯者／刪除者的語義相互分離。
每個工作區僅接受一個帳戶，並擁有專屬的目錄及簽署身分。 主工作區為維持相容性而保留在根目錄下；額外的工作區則位於 profiles/<id>/ 目錄中。一個攜帶者憑證（bearer token）控制整個安裝環境；工作區並非 獨立的授權租戶。 流程鎖用於保護目錄；資料庫鎖則 用於序列化事件插入。每次追加操作皆會以 FULL 同步模式同步提交至 SQLite WAL。事件更新／刪除觸發器可防止 一般應用程式進行編輯；檔案系統管理員仍處於信任邊界之內。
API 授權採用承載者憑證（bearer token）。登入操作會被序列化並設有時間限制。 帳戶上傳採用專用的 12 MiB 編碼本體限制及 8 MiB 解碼檔案 限制；一般 API 請求則維持 16 KiB 的限制。 轉換在工作 執行緒中執行，將上傳資料保留在記憶體中，並將正規化的輸入傳回已驗證的 瀏覽器。QR 碼登入具備每個工作區專屬的候選識別碼、短效識別碼、等待任務， 以及明確的取消機制。僅接受的授權才會成為活躍的客戶端。 Telegram FloodWait 會回傳 Retry-After 值；憑證與原始 RPC 錯誤訊息不會在 API 錯誤中公開。匯出操作在非同步事件 迴圈外執行，並按工作區進行序列化。它們會串流穩定的讀取快照，且可 與持續進行的 WAL 寫入並存。 工作區收集器共用同一個程序／事件迴圈。
當前的歷史快照與即時更新可能有所重疊。兩者皆為獨立的觀察記錄， 並標註來源；重複項目不會被靜默合併。系統不會根據缺失的 ID、捏造的已刪除文字、強制成員枚舉或自動加入群組 等情況進行推論。
關於面向操作者的說明，請參閱「資料蒐集運作方式」 以及「帳戶與會話格式」。
網路配置儲存於加密金庫中。套用路由會關閉舊的 客戶端並取消未完成的登入；後續連線將使用該路由，且無 直接備用方案。 新的外部金鑰安裝會透過 HKDF-SHA256， 從主金鑰檔案及儲存的隨機鹽值中推導出每個工作區的 Fernet 金鑰。此機制將 機密資訊與資料目錄分開保護，而非以明文形式保護日誌／媒體內容。
本地示範入口使用獨立生成的程序權限，絕不使用已設定的 面板代幣。發行與接受需明確啟用示範模式，並需使用合成根 （無額外工作區或授權會話）、迴路對等方／主機，且不得包含代理 轉發標頭，亦不得進行跨來源瀏覽器請求。 正式版 API 維持承載者 驗證機制，並在示範模式下拒絕收集變更。