TgWitness / 文件說明

已測試的內容 →

參考資料 / 設定

Telegram · 存取與權限

針對帳戶和聊天室設定權限範圍、選擇權限、限制連線數與 IP 位址,並撤銷存取權限。

TgWitness / 文件說明 · 開始使用

開始使用

可授予審閱者存取單一聊天室的權限、分析師匯出個案的權限,或 操作員對選定帳戶的控制權。每位使用者皆擁有專屬的憑證。主 控制面板的憑證則由管理員持有。

帳戶設定 · 連線路徑 · 安全模型

兩個應用範圍,兩種不同的任務#

收集範圍決定了帳戶的記錄內容:選定的聊天室、Telegram 資料夾或整個帳戶。存取範圍則決定其他使用者能查看及使用哪些 已記錄的帳戶與聊天室。授予存取權限並不代表加入 Telegram 聊天室、啟動資料收集,亦不會授予 Telegram 帳戶權限。

某項存取權限可開啟選定的工作區、其中選定的聊天室、所有 工作區,或某個 帳戶群組中的每個帳戶。所有工作區, 包括日後新增的工作區,亦涵蓋未來的帳戶。群組存取權限同樣 涵蓋日後新增至該群組的帳戶。若需將案件範圍 限定於特定工作區內,請明確選取該等工作區。

授予某人存取權限#

  1. 請以主要管理員身分登入,並開啟「更多工具」→「存取權限」。
  2. 在「授予某人存取權限」下方,請輸入一個您在日誌中能認出的名稱。
  3. 請選擇工作區,並在必要時選擇個別聊天室。
  4. 請選擇此人可能採取的行動。選項中始終包含「檢視」。
  5. 請根據需求設定有效期限、登入/會話限制及允許的地址。
  6. 按下「建立存取權限」。請立即複製該代碼:此代碼僅顯示一次。
  7. 請私下傳送控制台位址和代碼。收件者只需在 標準登入頁面輸入該代碼;無需您的主控制台代碼或 Telegram 會話。

請在另一個瀏覽器視窗中開啟包含已發行代幣的面板,並在移交前檢查 可見的聊天室及允許執行的操作。

存取名稱保留在加密的本地儲存空間中,並由管理員控制台進行解析。 新建立的存取及工作區建立稽核記錄中將省略名稱;現有的簽名記錄則保留其原始欄位。

選擇權限#

若需進行純文字的公開展示,請使用「公開展示」而非一般的 審閱者存取權限。該功能會顯示明確選定的公開頻道、保留的編輯與 刪除紀錄,以及經簽名的統計資料,其中作者欄位將被遮蔽,且檔案會在 API 邊界處關閉。建立並驗證展示內容。

授權 功能說明
view 查閱獲准的聊天紀錄、擷取的訊息、個人檔案、檔案以及經過篩選的日誌記錄。這些內容始終包含在內。
export 可匯出獲准的聊天紀錄及檔案。若要匯出整個工作區的證據,則需具備該工作區的存取權限。
sources 管理來源、快照及個人檔案擷取。受限於特定聊天室的存取權限僅能針對允許的聊天室進行操作;全帳戶範圍的來源偵測與範圍設定則保持關閉狀態。
collect 啟動或停止收集器。由於收集操作會影響該帳號,因此需要整個工作區的存取權限。
interact 請在存取範圍內執行受支援的 Telegram 互動。僅限聊天室的存取權限無法使用全帳戶範圍的連結預覽功能。
settings 可變更資料收集設定、時間戳記、通知、異地備份及各項參數。需具備整個工作區的存取權限。
account 登入或登出 Telegram,並管理連線路徑。需具備整個工作區的存取權限。
board.read 僅可在允許的工作區及聊天室內閱讀「案件看板」的筆記。
board.write 可新增書籤、標註、片段、註解,以及開啟/檢閱狀態。此外還需 board.read 權限。
board.manage 管理資料集、團隊最終狀態及其他參與者的卡片。此外還需具備對看板的讀寫權限。

僅有主要管理員可下載異地副本的恢復金鑰。 委派settings或account存取權限並不會授予該金鑰。

權限與範圍會一併進行檢查。勾選某項權限並不會開啟 其他聊天室,也不會為僅限特定聊天室的存取權限解鎖工作區範圍的操作。 若要進行並行匯出,存取權限必須涵蓋每個已選取 帳戶中的匯出聊天室。已授予的存取權限無法建立新的存取權限、管理他人的 會話,亦無法開啟管理員控制台。

三種實用的設定方式#

人物 範圍 權限
審閱者 某個案例的聊天記錄 view
分析師正在準備交接事宜 待調查與匯出的聊天紀錄 view、export;僅當需透過 Telegram 進行操作時,才需新增 interact
資料擷取操作員 精選完整工作區 view、sources、collect;僅在需要時才添加 settings 或 account

「存取表單」的預設設定亦包含「案件看板」:審閱者可讀取、分析師可讀取 與寫入,操作員可進行管理。預設設定仍可編輯,且現有的權限授予不會 自動擴展。有關繼承的聊天範圍及匯出隱私設定,請參閱「案件看板」。

限制與會話#

設定 運作原理
平行會議 將同時連線數限制在 1 至 100 之間。達到上限時,將拒絕下一次登入,或終止最舊的連線。
允許登入 限制使用該憑證成功建立會話的次數。即使已使用最後一次允許的登入次數,現有會話也不會因此終止。
有效期至 存取權限設有絕對有效期限。過期的存取權限將無法登入或繼續發出請求。
無活動的分鐘數 會話閒置超時設定,範圍為 5 分鐘至 30 天。成功請求將延長此時間;開啟的面板可透過輪詢機制維持其活躍狀態。
允許的網址 接受特定的 IP 位址或 CIDR 子網。若未填寫,則允許任何位址,除非已啟用「首次登入綁定」功能。
綁定至首次登入 首次成功登入後,系統將為該次存取設定允許的位址。

IP 是指應用程式所偵測到的客戶端位址。若位於反向代理伺服器或 隧道之後,請在依賴 IP 規則之前,先檢查「開放連線」中顯示的位址: 否則可能會出現多名使用者看似共用同一代理伺服器位址的情況。

變更或撤銷存取權限#

在「已授予存取權限」下編輯一項條目,以變更其範圍、權限或限制。 範圍與權限的變更將在後續請求中生效,包括 來自已開啟的連線所發出的請求。撤銷存取權限將終止其連線 並使已發出的憑證失效。透過「開啟的連線」,管理員亦可 終止個別連線,而無需撤銷整個存取權限。

已儲存的匯出副本會保留其建立者、工作區、聊天範圍及所需權限。 已授予存取權限者僅能在該權限仍有效期間,列出或下載其自身的副本; 包含「案例看板」(Case Board)的副本還需具備 board.read 權限。管理員可檢索所有副本。 較舊且未包含此元資料及群組封裝的副本,僅限管理員存取。下載憑證 及預先準備的檔案回應,會在準備檔案後、傳送位元組前重新檢查存取權限。 每個存取者(包括管理員)在每個工作區中可持有十張待處理的下載憑證; 工作區整體上限為 1,000 張。憑證在 120 秒後失效,且僅限使用一次。

撤銷操作無法召回他人已下載的檔案。登出、 鎖定面板或結束會話,均不會停止正在運行的收集器。

管理員可查看的內容#

審查員和分析師接收的資料蒐集進度中,不包含代理端點、 彙總診斷資訊、伺服器路徑或原始連線錯誤。連線診斷 需具備整個工作區的 account 權限。讀取通知、 異地副本及參數設定則需具備 settings 權限。

瀏覽器中的完整 User-Agent 字串不會保留在存取會話中。升級後 亦會將其從可變會話快取中移除。控制面板的處理程序日誌會遮罩 IP 字面值、URL 憑證及標記機密資訊。本地服務日誌與 先前已簽名的日誌記錄不會被重寫。存取規則與已簽名的 登入記錄仍會使用客戶端位址。

更換主金鑰#

請使用「更多工具」→「存取」→「我的限制」→「重新發行管理員金鑰」,或在控制面板運行期間,從受管安裝環境執行 tgwitness token rotate。 所有現有瀏覽器會話將終止,包括使用同事 金鑰開啟的會話。發出請求的瀏覽器將收到新的會話;請在隱藏新管理員 金鑰之前先將其儲存下來。已發行的同事金鑰在未被單獨撤銷前仍保持有效。 使用 TGWITNESS_TOKEN 的安裝環境必須變更該環境設定並重新啟動。

請求與代理伺服器邊界#

此 API 允許每個客戶端及憑證類別(包括: 控制面板、存檔/MCP 或見證者)每分鐘最多發出 600 次請求。這些類別的驗證冷卻時間各自獨立。 若一分鐘內有十次驗證遭拒,將觸發指數級冷卻機制,時間從一秒 起,最長可達五分鐘。 冷卻期結束後若發生一次失敗嘗試,將延長冷卻時間;若十分鐘 內未發生失敗嘗試,則重置延長狀態。拒絕請求將返回 HTTP 429 狀態碼及 Retry-After 標頭。限制值儲存在記憶體中,並在同一個面板進程內的工作區之間共享; 重新啟動將清除這些限制。即時串流每個承載者憑證限四組,每個面板進程限 32 組。開啟串流也會消耗 API 請求配額。

請求正文的接收截止時間為 60 秒,若涉及登入、示範存取、 存檔 API 及見證者頭部路徑,則縮短至 10 秒;若為 MCP 傳輸,則縮短至 8 秒。每個應用程式允許 每個客戶端位址擁有四個未完成的請求正文,且預留的 路由配額總上限分別為 32 和 64 MiB。不含正文的請求不會佔用這些配額。正文超限將返回 413 狀態碼,超時正文將返回 408 狀態碼,而超過客戶端容量則返回 429 狀態碼並附帶 Retry-After: 1。 當整體正文容量耗盡時,將回傳 503 狀態碼,並附帶 Retry-After 標籤。

轉發的 IP 標頭將被忽略,除非實際的 TCP 對等端屬於 TGWITNESS_TRUSTED_PROXIES(以逗號分隔的 IP 或 CIDR)。將 TGWITNESS_PROXY_HEADER 設定為 x-forwarded-for 或 cf-connecting-ip。XFF 會從 最近的代理伺服器朝向第一個不可信的對等端進行遍歷。 格式錯誤或重複的 可信地址元資料將被拒絕,因此無法繼承白名單中的代理 地址。受管理的快速隧道 信任本機的 Cloudflare 連接器;自有網域的設定則信任本機的 Caddy。 直接部署預設不信任任何代理。若您自行啟動 Uvicorn, 請停用其代理標頭處理功能,以便此邊界能接收實際的對等節點。

TGWITNESS_PANEL_ALLOWED_IPS 將所有控制面板存取權限(包括管理員) 限制為列出的 IP 或 CIDR 範圍。安裝程式的路由識別探測保持公開狀態, 且不會回傳任何帳戶資料。在啟用白名單之前, 請先包含所需的本地管理路由。受管安裝的 START-HERE 指南包含 服務配置與復原說明。

API 中的 ws 查詢選擇器必須在請求路徑中識別工作區; 未知、不匹配及重複的選擇器將被拒絕並返回 404 錯誤。

面板腳本與樣式包含 SHA-384 完整性元資料。匯入映射亦 涵蓋在支援 import-map 完整性的瀏覽器中本地匯入的 JS 模組。 動態生成的語言回應是獨立的。這些檢查可偵測 相對於傳送頁面所發生的資產替換;頁面本身及其雜湊值 來自面板伺服器,因此請保護該伺服器及其傳輸路徑。

自啟動以來,此日誌會將程序日誌與每個 工作區的日誌活動整合:登入、拒絕、路由變更及操作員動作。這是一個 針對當前程序的內存控制台,而非每則訊息的永久副本。 頻繁發生的訊息事件會保留在日誌中,而非填滿控制台。

授予、變更及撤銷存取權限,以及啟動或結束會話,亦會產生 經簽名的 access.* 日誌記錄。這些記錄中不包含代幣。 已發行的代幣與會話憑證將以雜湊值形式保留於加密保管庫中。

待處理的 QR 登入屬於啟動該登入的面板會話。 終止或 撤銷該會話,或輪替主面板憑證,將取消伺服器上的待處理 QR 客戶端。當瀏覽器無法發送自身的 取消請求時,此規則同樣適用。憑證輪替亦會取消直接 使用主面板憑證啟動的 QR 登入。正在等待其他操作的 QR 請求,會在開始前 再次檢查存取權限。已完成的 Telegram 授權以及由其他面板會話 啟動的待處理登入將予以保留。

主要管理員與信任邊界

主面板憑證不受任何限制。透過該憑證進行瀏覽器登入所建立的會話, 將受限於管理員所設定的會話限制。直接傳送 主憑證的腳本將保留完整存取權限,且不被計入瀏覽器會話中。

這是單一安裝環境中的應用層級存取控制。所有工作區皆共用 伺服器程序;這並非與主機管理員隔離。請將主 憑證、Telegram 連線、簽名金鑰及資料目錄保密。見證憑證 是一種獨立的檢查點/狀態憑證,並非面板存取憑證。