參考資料 / 設定
Telegram · 存取與權限
針對帳戶和聊天室設定權限範圍、選擇權限、限制連線數與 IP 位址,並撤銷存取權限。
可授予審閱者存取單一聊天室的權限、分析師匯出個案的權限,或 操作員對選定帳戶的控制權。每位使用者皆擁有專屬的憑證。主 控制面板的憑證則由管理員持有。
兩個應用範圍,兩種不同的任務#
收集範圍決定了帳戶的記錄內容:選定的聊天室、Telegram 資料夾或整個帳戶。存取範圍則決定其他使用者能查看及使用哪些 已記錄的帳戶與聊天室。授予存取權限並不代表加入 Telegram 聊天室、啟動資料收集,亦不會授予 Telegram 帳戶權限。
某項存取權限可開啟選定的工作區、其中選定的聊天室、所有 工作區,或某個 帳戶群組中的每個帳戶。所有工作區, 包括日後新增的工作區,亦涵蓋未來的帳戶。群組存取權限同樣 涵蓋日後新增至該群組的帳戶。若需將案件範圍 限定於特定工作區內,請明確選取該等工作區。
授予某人存取權限#
- 請以主要管理員身分登入,並開啟「更多工具」→「存取權限」。
- 在「授予某人存取權限」下方,請輸入一個您在日誌中能認出的名稱。
- 請選擇工作區,並在必要時選擇個別聊天室。
- 請選擇此人可能採取的行動。選項中始終包含「檢視」。
- 請根據需求設定有效期限、登入/會話限制及允許的地址。
- 按下「建立存取權限」。請立即複製該代碼:此代碼僅顯示一次。
- 請私下傳送控制台位址和代碼。收件者只需在 標準登入頁面輸入該代碼;無需您的主控制台代碼或 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 連線、簽名金鑰及資料目錄保密。見證憑證 是一種獨立的檢查點/狀態憑證,並非面板存取憑證。