功能與限制

設計參考：2026年10月26日。主要應用場景為連線帳戶可存取的私人 Telegram 群組 及頻道。本文件將 已實作的功能、平台限制與未來工作區分開來。目標架構 項目並不代表該功能已實際存在。

獨立應用程式#

TgWitness 擁有專屬的安裝程序、資料目錄及發行週期。內建的 網頁介面負責設定與檢視；匯出的記錄可獨立使用。

操作者可連結其帳戶、選擇彼此可見的來源，並取得 一份儲存的觀察日誌。控制面板會顯示內容、已儲存的變更、觀察 來源及已知缺漏。其他調查人員可驗證匯出的資料。

有四種不同的狀態至關重要：帳戶授權、對來源的存取權限、可正常運作的 收集器，以及傳送完整性已確立的程度。前三者 均無法自動證明第四項。一個靜默的群組未必 代表收集器已失敗。

共享調查#

管理員可發行範圍限於工作區及 個別聊天室的存取憑證，並具備七項權限、IP 限制、有效期限、登入次數限制 及會話控制功能。唯讀審查員無需取得 Telegram 授權或主控制面板金鑰，即可檢視案件。 僅限特定聊天室的存取權限 與全帳戶設定及完整日誌匯出功能相互獨立。

自動 MTProxy 會從四個公開來源或 營運商目錄中維護可運作的 Telegram 路由。IP 模式決定 當發生故障時，系統是否必須等待另一個代理伺服器，或是可使用明確允許的直接路由。 外部 HTTP 請求擁有獨立的路由及關閉開關。

歸檔工具#

最新版本 main 新增了歷史記錄擷取、檔案庫搜尋與分析、 唯讀 MCP、本地 OCR／轉錄以及 外發 webhook 功能。這些功能需從原始碼檢出，是在 0.7.0 便攜版預覽版之後新增的。分析報告與辨識出的文字仍與 擷取的事件分開儲存。

可選附加功能#

日常設定流程為：帳戶 → 來源 → 監測。額外功能為獨立的目標選項， 包含 Telegram 證據記錄機器人及 GitHub 擷取預覽。各選項會在顯示 設定前，先說明其可用性與需求。點選卡片會開啟操作說明；此動作不會進行註冊或啟動服務。

機器人設定包含三個步驟：建立唯讀存取權限、選擇發佈設定，以及 在 Witness 主機上啟動。網路與發佈選項、現有連線及 驗證指令將依需求顯示。 下載的配置檔與 正在運行的 Witness 實體不同。切換附加功能時會保留草稿；帳戶變更及鎖定 操作則會清除臨時憑證與表單。內建指南包含啟動說明。 GitHub Actions 會從您的 分支啟動一個固定收集器，擷取一個聊天記錄，並產生包含工作流程來源資訊的加密交接檔。

協議與私有來源#

MTProto 是 Telegram 的通訊協定；Telethon 則是 TgWitness 用於 與 MTProto 通訊的 Python 函式庫。這兩者並非替代性的連線方式。「收集」功能使用 MTProto； 而可選的「見證者」則透過 Bot API 發佈經簽名的檢查紀錄。

每個工作區皆擁有專屬的授權客戶端及帳戶更新串流。TgWitness 會從已設定的來源中篩選觀察結果，並針對歷史紀錄快照與媒體下載等功能， 分別發出明確的請求。

私人消息來源無需公開使用者名稱。Telegram 的對等節點類型與數值 ID 才是 識別標識；標題與使用者名稱皆可能變更。存取權限取決於現有的 會員資格與權限設定。TgWitness 不會自動加入消息來源，也不會繞過 加入審核。來自其他帳戶的存取雜湊值並非通用存取憑證。

資料蒐集模型必須涵蓋加入群組前的隱藏歷史紀錄、參與者／管理員 角色、會話撤銷、權限移除或變更、群組轉為超級群組 的遷移、主題／論壇、關聯討論、頻道身分以及無法存取的 附件。並非所有組合皆已通過實際運作驗證。

來源可見性會在收集器啟動時進行檢查。若在限定範圍內的 對話結果中缺少某個來源，表示該來源的存取狀態未經確認，而非已證實遭刪除。即使有一個 來源不可用，也不會影響對其他可存取來源的監測。切勿將邀請 連結或真實會話內容放入公開的測試資料中。

多個帳戶#

該面板支援任意數量的工作區，每個工作區皆具備：

• 授權機制、加密儲存庫及連線路徑。
• SQLite 日誌及 Ed25519 簽名憑證。
• 精選來源、媒體佇列及擷取設定。
• 監測狀態、錯誤、檢查點及匯出功能。

切換顯示的工作區並不會停止其他資料擷取器的運作。跨工作區的重複帳戶 授權將被拒絕。已綁定至某個 Telegram 帳戶的日誌無法重新指派給其他帳戶；但允許重新連線至同一帳戶。 此舉可確保帳戶身分及相關訊息 ID 範圍的完整性。

沒有固定的數量限制，亦不保證特定吞吐量。各工作區共用一個 Python 程序和事件迴圈。獨立的帳戶處理程序仍屬未來開發計畫。若要 實現當前的程序隔離，請使用獨立的安裝、埠號及資料目錄。

請為每個帳戶指派其可存取的來源。不同帳戶可能監測同一個 群組，但其監測記錄仍屬獨立，並保留原始來源。同一台由操作者控制的機器上的兩個帳戶 並不構成兩個獨立的證人。匯出功能 以工作區為單位；目前尚未實作合併案件資料包或全域 Telegram 時間軸功能。

擷取與來源標示#

「來源」功能提供針對各帳戶的新訊息、編輯、刪除、反應 及成員資格的切換選項。預設設定可選擇保留所有類別，或僅保留訊息／編輯／刪除記錄。 此政策適用於工作區中選定的群組，重啟後仍會保留，並會 以變更前／後的狀態進行簽署。預設設定為保留所有類別。 關閉某個類別 不會移除舊記錄；重新開啟該類別也不會重建遺漏的事件。 操作記錄、其他群組服務事件以及明確的歷史快照均屬 獨立項目。擷取的 Telegram 物件可能會保留內嵌的元資料，無論 「獨立更新」開關的設定為何。目前尚無針對各群組的類別覆寫功能。

只有當來源確實指明該行為者時，才會將某項行動歸因於某人。 否則，介面會報告歸因資訊缺失。使用者名稱與姓名僅為 觀察到的屬性，並非真實世界身分的證明。

儲存容量與 Telegram 限制#

目前尚無能保證監控品質的通用聊天室數量標準。 監控容量取決於每秒的峰值事件數量、附件數量與大小、額外的 RPC 請求、活躍帳戶數量、磁碟延遲／可用空間、網路狀況、Telegram 的限制、 可接受的延遲以及佇列深度。

Telegram 將「被動傳送」與「主動短輪詢」區分開來。其更新 文件中說明，針對公開 頻道／超級群組會產生額外的 updates.getChannelDifference 呼叫，並建議同時進行短輪詢的 來源最多為十個。這並非指僅能選取十個群組，亦非完整性保證。

任意的高頻率輪詢、忽略 FloodWait 設定，或假設額外帳戶具備線性處理能力， 均非有效的規模估算模型。預設限制為 前 1,000 個列出的對話，每個歷史快照最多 500 則訊息， 每種類型的收集檔案為 1–2,000 MiB，以及 4 GiB 未壓縮的簽名 ZIP 內容；各項 限制皆可於「參數」中針對各工作區進行調整。匯出資料無固定事件數上限。 瀏覽器備用模式預設上限為 128 MiB；串流 CLI 具有可配置的 傳輸限制，預設為 5 GiB。

tools/check_capacity.py 用於測量本地合成資料的匯入與匯出。其結果 並非 Telegram 訊息傳送量的測量數據，亦非保證真實的聊天次數。請參閱 VERIFICATION.md 以了解測量版本與工作負載。

可靠性與資料復原#

已實作的功能包括 SQLite WAL／同步交易；原子性訊息 與媒體處理任務寫入；持久化任務與重試延遲；原始版本描述符； 有限重試；媒體 FloodWait 的持久化；在文字事件的 網路等待之外進行媒體下載；在後續寫入持續進行時進行穩定前綴匯出；原子設定與 稽核記錄；在替換登入失敗後保留有效授權； 受損附加工作區的隔離；顯式重新連線嘗試；明確的 授權喪失通報；以及使用單調時鐘進行的實時時鐘變更偵測。

帳戶與頻道的 pts/qts/seq 值會在重新啟動後保留並恢復，且受監控的聊天室 會定期重新檢查；詳見證據格式。定期儲存位置 並非對日誌接受的原子性、無損確認。

每次流程啟動時，都會記錄前一個頭部位置與離線邊界。當前的歷史紀錄 不被視為缺口修復。Telegram 的差異保留容量是有限的； differenceTooLong 無法重建所有已消失的內容。即使後續的歷史快照成功，不可恢復的缺口仍須 明確標示。

證據模型#

每項事件皆記錄事件序列、當地 UTC 觀察時間、來源時間（若提供）、 事件類型、來源、行為者（若提供）、原始載荷、前次雜湊值及簽名。 訊息觀察記錄亦會保留收集者帳戶／執行上下文。

該簽署的處理收據包含隨機生成的執行 ID；TgWitness/Python/OS/依賴項 版本；原始檔的 SHA-256 值與彙總指紋；初始帳戶、 範圍及設定；UTC/單調讀數；以及前一則日誌的開頭。 設定變更、啟動／停止及錯誤訊息均會記錄於同一日誌中。檢查點會 於啟動時、監測期間每五分鐘（可調整）以及正常停止時保留。 保留的本地檢查點可偵測是否回滾至較早的日誌前綴。

已實作 RFC 3161 請求準備及 OpenSSL 回應驗證功能。 自動提交功能尚未實作。攜帶機器 時間的請求或本機簽名並非獨立的時間戳記。請參閱 TIMESTAMP.md。

掌控資料收集器與簽署金鑰的操作者，可偽造新的簽署 觀察紀錄。這些簽署並不能證明訊息源自 Telegram、其真實性，亦不代表自動 具備法律可採納性。若要確保更強的證據保存，需具備獨立的檢查點／時間戳記儲存、 金鑰存取控制、傳輸紀錄，以及由可信賴軟體進行的驗證。

匯出、部署與移交#

經簽名的 ZIP 檔案包含原始的 JSONL、CSV、HTML 檔案、保留的附件、雜湊值、一份 經簽名的清單以及一個便捷驗證工具。其涵蓋一個工作區及一個固定的完整 日誌前綴。面板搜尋篩選器不會在未經提示的情況下移除記錄。 密鑰、 憑證及 Telegram 會話均不包含在內；原始記錄仍可能包含 個人資訊及 Telegram 元資料。

請將 ZIP 摘要、可信指紋、檢查點、處理收據及交接 記錄分別保存。應使用來自可信安裝來源的驗證器，而非僅因可執行 程式碼出現在被檢查的 ZIP 檔案中，就直接信任該程式碼。

瀏覽器介面可本地部署，無需 Node.js、CDN 或外部字型。一個 操作員憑證即可控制整個安裝過程。遠端存取需透過 HTTPS 或 SSH 隧道進行。 提供原生 Python 程式碼及容器定義，部署範例位於 deploy/ 目錄下；已執行的平台檢查項目則另行列出。

預設工作區使用資料根目錄；額外的工作區則使用 profiles/<id>/。 備份需先停止程序，並備妥完整的資料／金鑰組。證據 ZIP 檔 並非應用程式備份。機密資料可使用外部主金鑰來建立新的資料 目錄；日誌／媒體加密則由操作者的磁碟／磁碟區提供。 請參閱 CONNECTION-SECURITY.md 及 OPERATIONS.md。

穩定版本發布標準#

在穩定版發布前，請補充說明：

1. 真實的私人群組、超級群組、論壇及頻道，包含成員／管理員角色，以及 隱藏／可見的歷史紀錄，涵蓋登入／雙因素驗證、權限撤銷及存取權限喪失等資訊。
2. 針對已知行為，對編輯、刪除、反應、成員資格及媒體內容進行監控。
3. 流程／主機當機、磁碟故障／磁碟空間已滿、檔案參照過期、FloodWait、 網路中斷、檔案損毀及資料庫回滾。
4. 支援持續的多帳號使用，並可控制延遲、佇列、記憶體及磁碟資源，包含 同時處理靜態與動態資料來源。
5. MTProto 狀態推進與日誌接受之間的間斷。
6. 在目標作業系統／容器組合上進行乾淨安裝，並驗證備份與還原功能。
7. 針對安全性、簽名以及來源歸屬／證據主張的獨立審查。

管理日誌擷取、額外的反應器清單、優先級擷取、獨立工作程序， 以及全應用程式的加密功能，仍屬未來開發工作。範圍限定的面板存取權限說明 請參閱「存取與權限」章節。0.6 版支援 如 ACCOUNTS.md 所述的「有限單一帳戶 TData」及「帳戶檔案匯入」功能。 發布前請詳閱 Telegram API 條款。研究參考文獻與平台 調查結果請參閱 RESEARCH.md。