# Telegram · 存取與權限

Canonical page: https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/access/

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

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/zh-Hant/llms.txt)

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

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文件說明](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [開始使用](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/quickstart/)

![開始使用](https://phishdestroy.io/tgwitness/assets/chapter-start.svg?v=443547f9bcd2)

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

[帳戶設定](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/) · [連線路徑](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/connection/) · [安全模型](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/security/)

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

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

某項存取權限可開啟選定的工作區、其中選定的聊天室、所有 工作區，或某個 [帳戶群組](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/accounts/#bulk-import-and-account-groups)中的每個帳戶。**所有工作區， 包括日後新增的工作區**，亦涵蓋未來的帳戶。群組存取權限同樣 涵蓋日後新增至該群組的帳戶。若需將案件範圍 限定於特定工作區內，請明確選取該等工作區。

## 授予某人存取權限

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

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

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

## 選擇權限

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

| 授權 | 功能說明 |
| --- | --- |
| `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` |

「存取表單」的預設設定亦包含「案件看板」：審閱者可讀取、分析師可讀取 與寫入，操作員可進行管理。預設設定仍可編輯，且現有的權限授予不會 自動擴展。有關繼承的聊天範圍及匯出隱私設定，請參閱[「案件看板」](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/case-board/)。

## 限制與會話

| 設定 | 運作原理 |
| --- | --- |
| 平行會議 | 將同時連線數限制在 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 連線、簽名金鑰及資料目錄保密。見證憑證 是一種獨立的檢查點／狀態憑證，並非面板存取憑證。
