連線、代理伺服器與資料保護

本文檔說明 TgWitness 0.7.0 的運作方式及其限制。驗證、 來源存取、網路連線及擷取完整性均為獨立的狀態。 關於登入步驟、檔案格式及多重帳戶，請先參閱「 帳戶與會話格式」；關於事件政策及重新啟動 行為，請參閱「資料擷取運作方式」。

驗證方法#

API ID 和 API 雜湊值用於識別應用程式；它們並不能取代帳戶登入。 在 TgWitness 中，這些資訊為選用項目。優先順序如下：首先是表單中輸入的一組值，其次是來自 匯入帳戶 JSON 檔案的一組值，接著是儲存於工作區的一組值，最後是內建的 50 組 公開配對組，當 Telegram 拒絕某組時，系統會以隨機順序嘗試並自動輪替。僅 Telegram Desktop 配對組 (2040) 會隨附相應的 Telegram Desktop 客戶端描述一併傳送。 您可將從 my.telegram.org 的 API 開發工具取得的專屬配對組用於所有帳戶；每個帳戶仍保有各自的授權。

Telegram 採用代碼傳送方式；簡訊傳送無法保證成功。API 雜湊值無法修復 已被撤銷的連線，亦無法取代遺忘的雙因素驗證 (2FA) 密碼。TgWitness 不會將 登入代碼或 Telegram 雙因素驗證 (2FA) 密碼儲存至磁碟。

若為私人來源，該帳號必須已具備存取權限。群組使用者名稱 並非必要。透過代理或會話匯入，既不會授予成員資格，也不會授予管理員 權限。目前的成員資格並不能保證能存取加入群組前的歷史紀錄。

匯入 Telethon 會話檔案#

Telethon SQLite、Pyrogram SQLite 以及 Telegram Desktop TData 採用不同的格式。 此面板會偵測並轉換受支援的結構；重新命名檔案並不 屬於轉換範疇。請在「檔案」選項中選取一個會話及其對應的 JSON 檔案，然後按下「連線帳戶」。最多可接受四個符合條件的檔案， 總大小不得超過 8 MiB。 有關 TData/JSON 的詳細資訊，請參閱格式限制。 不提供密碼恢復功能。透過手機/雙因素驗證 (2FA) 或 QR 碼登入將建立獨立的授權。

僅限 Telethon 的可選命令列路徑仍可使用：

1. 請停止使用原始連線的客戶端，並建立一份一致的副本。該 轉換器會拒絕處理 WAL/日誌未完成的檔案。請正確關閉原始 客戶端，而非刪除這些檔案以繞過檢查。
2. 在 TgWitness 環境中，執行：

python -m tgwitness.sessions account.session --out account.tgwitness-session

3. 在「新增帳戶」→「檔案」下，載入結果或 貼上其字串，然後繼續。
4. 請確認顯示的數字帳號 ID，選擇來源並開始監測。

此轉換器以唯讀模式開啟 SQLite，不會執行任何資料結構升級或網路請求， 也不會輸出該會話內容。它會檢查資料結構版本、資料表類型、單一 會話列、IP/埠/資料中心以及金鑰長度。命令列介面 (CLI) 輸入限制為 64 MiB；StringSession 文字限制為 4 KiB。 面板轉換會將檔案上傳至已驗證的 TgWitness 伺服器，在記憶體中進行處理，並將標準化的憑證傳回該 瀏覽器，且不會儲存上傳的原始檔案。若使用遠端伺服器，請採用 HTTPS。

轉換後的檔案為未加密的帳戶存取密鑰。 請將其存放在受保護的 儲存空間中，切勿將其提交至版本控制系統或傳送給第三方轉換服務。TgWitness 會將授權會話儲存於其加密金庫中。複製會話並不會 建立獨立的授權：請勿同時執行使用克隆授權金鑰的 客戶端，並假設其能獨立接收更新。

轉換操作僅傳遞授權，而非原始訊息、實體快取或 持久性更新游標。此操作不會解決跨程序重啟時的更新復原問題。

MTProto、Telethon 及代理伺服器#

MTProto 是 Telegram 的通訊協定。Telethon 是 TgWitness 所使用的 Python 客戶端函式庫。 MTProxy 是一款 Telegram 傳輸代理伺服器；SOCKS5 和 HTTP CONNECT 提供一般性的 隧道。上述方式均無法取代帳戶驗證。

請在登入前，前往「帳戶」→「設定」→「連線設定」→「變更連線路徑」，為每個工作區儲存路徑。 新建立的工作區預設為「自動 MTProxy」模式，並採用具備「隱藏 IP」功能的公開清單。 現有工作區若曾明確使用「直接連線」模式，將保留允許此模式的設定。

IP 模式#

路由決定連線方式。IP 模式則決定伺服器位址 何時可能被曝光。這些控制功能不會安裝 VPN，也不會將所有裝置流量進行路由。

隧道／VPN 模式假設您會另行管理該網路。若無運作中的 隧道，目標端將能看見伺服器本身的位址。請根據 您的實際網路環境選擇模式，而非僅依據選項名稱。

選擇路徑#

偽 TLS ee 密鑰將被拒絕。Telethon 1.45 的正規化功能可移除前綴 與網域，但並未實作偽 TLS 功能。請貼上 tg://proxy?server=…&port=…&secret=… 或 https://t.me/proxy?server=…&port=…&secret=…，並選擇「從連結填入欄位」。 此操作會在不建立連線或儲存的情況下驗證並填入欄位；請另行檢視並儲存 路由。手動填寫欄位仍可使用。請參閱 Telegram 代理連結。

由您的安裝環境提供的公開代理伺服器#

內建清單整合了四個來源： SoliSpirit/mtproto、 zakky8/mtproto-proxy-pro、 kort0881/telegram-proxy-collector 以及 3yed-61/MTP-Collector。 捆綁的快照包含端點資訊、來源歸屬及下載日期。 供應商名單並不代表該代理伺服器運作正常，亦不保證能傳遞每項 Telegram 更新。

MTProxy 會自動檢查 Telegram 的傳輸連線狀態，維持一個可運作的代理伺服器， 並在連線失敗時切換至另一個。當有足夠 可運作的代理伺服器時，工作區會優先選用不同的代理伺服器；無法保證會使用唯一的出口位址。 失敗的代理伺服器 會暫停一段時間後再次嘗試。若無任何代理伺服器可用，則由 IP 模式決定 是否必須等待，或可改用直接連線。更換代理伺服器不會變更帳戶 或刪除其日誌。路由選擇與變更皆記錄於簽名日誌中。

當自動路由處於啟用狀態時，清單預設每小時刷新一次，傳輸檢查則 每十分鐘執行一次。這些間隔時間均可自行設定。更新公開清單 會觸發刷新；僅瀏覽清單並不會變更已儲存的手動路由。

每個資料源的回應限制為 1 MiB，請求超時為 8 秒， 整體下載時限為 20 秒；重定向 將被拒絕。每個來源最多保留 64 筆相容的條目，並進行去重處理。 解析器支援十六進位數、base64url 密鑰以及 JSON 資料源。 偽造的 TLS ee、無效連結、私有／保留的 IP 字面量以及本機主機名稱將被 跳過。主機名稱會在使用前進行解析與檢查，且所選的 IP 地址將被 固定用於該連線。自動重新取得會再次解析主機名稱；若要再次解析，請重新套用 手動輸入的項目。

若饋送回應失敗、為空或不相容，系統將保留先前的來源快照。 更新操作具有原子性與序列化特性，且每分鐘每個工作區僅限嘗試一次。 成功的傳輸探測僅代表連線已建立，並不代表匿名性或擷取完整性。

Telegram 流量與 HTTPS 請求使用不同的路由。清單下載會使用 獨立的 HTTPS 連線，並透過提供的外部請求路由進行。 TGWITNESS_PROXY_FEED_PROXY 會明確地以 HTTP/SOCKS5 代理伺服器覆寫該路由； 兩種 Compose 版本的收集器皆會轉發該路由。背景池會跟隨主要工作區。 不會將任何 Telegram 會話、API 憑證、控制面板代幣或機器人代幣傳送給資料來源提供者。 提供者名稱、快照日期及下載路徑會顯示於「清單來源」欄位下。

MTProxy 僅傳輸 Telegram 流量。工作區的 HTTP 操作（例如時間戳記、 通知、站外副本及來源檢查）在 已設定的情況下，會使用獨立的 SOCKS5/HTTP 代理伺服器， 隨後則使用該帳戶的 SOCKS5/HTTP 路由。若未設定上述任一項，Hide IP 將拒絕 該請求；其他模式則允許直接連線。 外部請求可被停用。經明確 設定的資訊源下載代理仍屬操作員可獨立覆寫的項目。 獨立的見證服務則維持其專屬路由。

自動池參數

在 **參數 → 自動 MTProxy** 下，設定失敗閾值、冷卻時間、 預定輪替、代理伺服器共享及允許的備用延遲。 | 控制項 | 預設值 | | --- | --- | | 替換前斷線次數 | 10 分鐘內 3 次 | | 每次連線嘗試的代理伺服器嘗試次數 | 3 | | 失敗後的首次／最長休息時間 | 10 分鐘／6 小時 | | 預定輪替 | 已停用；失敗時切換 | | 每個代理的帳戶數 | 0：優先使用獨立條目，必要時共享。設定為 1 則會等待專用條目。 | | 允許直接回退前的延遲 | 10 分鐘；Hide IP 仍拒絕直接連線 | | 資訊源刷新／傳輸檢查 | 60 / 10 分鐘；主工作區的設定值適用於共用池 | 不同的代理伺服器並不保證會產生不同的出口位址。這些設定不會 覆寫 Telegram 的限制，亦無法證明匿名性。

若要將公開清單替換為您自己的營運商目錄，請配置以下覆寫設定。 此設定將完全停用外部訂閱功能，即使其 proxies 陣列為空時亦然。

將空目錄 複製到 proxy-config/proxies.json ，並新增您已部署的公開端點：

{"format": "tgwitness-proxy-catalog-v1", "proxies": [
  {"id": "project-eu", "label": "Project EU",
   "link": "tg://proxy?server=REPLACE_HOST&port=443&secret=REPLACE_SECRET"}
]}

必須替換範例值。最多可接受 32 筆不同的條目。 經驗證的清單會回傳標籤／主機／埠號，且不包含共享密鑰；選取其中一項 將把其憑證儲存至工作區金庫中。在進行 明確的傳輸測試之前，可用性尚未經過測試。若目錄格式不正確，則可進行手動設定。

原生啟動：將 TGWITNESS_PROXY_CATALOG 設定為本機 JSON 路徑。Docker：

docker compose -f compose.yaml -f deploy/compose/compose.proxies.yaml up -d --build

該覆蓋層以唯讀模式掛載 proxy-config；檔案必須可被容器 UID 10001 讀取。 該目錄不包含在 Git、Docker 建置環境及原始碼存檔中。此 目錄用於配置收集帳戶；witness 機器人使用其自身的 HTTP/SOCKS5 路由，而非 MTProxy。

直接備用方案受上述 IP 模式規範。變更路徑前，請先 暫停監測。儲存設定會斷開舊客戶端連線並取消未完成的登入；新 客戶端將使用已儲存的路徑。該帳戶的日誌／會話綁定關係將維持不變。 設定會取代先前路徑：編輯時請重新輸入代理伺服器憑證。

憑證採用 network.enc 加密。API 不會回傳使用者名稱、 密碼或機密金鑰。簽名紀錄包含路由類型及是否包含憑證， 但不包含端點與機密金鑰。操作者可在控制面板中查看端點。 機密欄位會在儲存、鎖定或切換工作區後清空。

「測試 Telegram 連線」功能（登入前亦可使用），會透過該路徑開啟並關閉一個臨時 且未經授權的 Telegram 連線。此功能不會聯繫任何 IP 檢查 網站。測試成功僅表示傳輸連線已建立，並不代表群組存取權限、訊息 完整傳送或匿名性。

此代理適用於 Telegram 客戶端的連線，包括 Telegram 數據中心（DC）的媒體 下載。瀏覽器、pip、SSH 以及手動調用的 TSA 工具則有獨立的路由。 代理主機名稱可於本地解析。rdns 會影響目標主機名稱； Telegram 通常會提供數據中心的數值 IP 位址。

SOCKS5 和純 HTTP CONNECT 本身並不會加密代理憑證或 客戶端至代理的隧道。MTProto 會另行保護 Telegram 流量。 在不可信的網路環境中，請使用 適當的安全通道連線至代理伺服器。私人群組 屬於雲端聊天；MTProto 並不會將其轉變為端對端加密的「秘密聊天」。

加密與簽名#

「帳戶」中的儲存保護功能會顯示這些狀態。面板憑證是一種 存取密鑰，而非加密密碼。它授予管理員存取權限； 已發行的憑證可限定於特定帳戶和聊天室。工作區共享 主進程，並非獨立的租戶。

一個明確啟動且隔離的合成示範環境，可透過直接 迴路連接自動開啟。此功能採用獨立的進程生命週期機制；既不會 洩露已設定的面板憑證，也不會授予存取真實工作區的權限。遠端、 代理或跨來源的請求均無法取得或使用此自動進入功能。 此便利功能並不會消除針對真實帳戶資料的驗證邊界。

BitLocker、LUKS、FileVault 或受管加密卷宗皆可在 各自的威脅模型下保護儲存裝置。 已解鎖且正在運行的機器之管理員 仍可讀取資料。在儲存規劃中，應納入 SQLite WAL/SHM、媒體檔案、臨時匯出檔案、交換檔、備份 以及瀏覽器下載檔案。Docker 卷宗並非僅因 其為卷宗而自動加密。TgWitness 未實作 SQLCipher 或物件加密功能。

外部主金鑰#

若要進行新安裝，請將主金鑰放置於資料目錄之外。 此操作不會自動遷移現有的本機金鑰保管庫。請準備一個 僅限服務身分存取的金鑰目錄，然後執行：

python -m tgwitness.security create-master-key /private/keys/tgwitness-master.key
export TGWITNESS_VAULT_KEY_FILE=/private/keys/tgwitness-master.key
python -m tgwitness --data-dir /private/observations/new-case

PowerShell，使用已安裝的專案環境：

python -m tgwitness.security create-master-key E:\PrivateKeys\tgwitness-master.key
$env:TGWITNESS_VAULT_KEY_FILE = 'E:\PrivateKeys\tgwitness-master.key'
python -m tgwitness --data-dir E:\PrivateData\new-case

在 Docker 中，請將檔案以唯讀方式掛載至 /data 之外的目錄（例如 /run/secrets/tgwitness-master.key），並將環境變數設定為該路徑。 該服務的 UID 必須具備讀取權限。請透過 環境變數／設定檔傳遞路徑，而非金鑰位元組。

每個工作區都會獲得一個隨機的公開鹽值，以及透過 HKDF-SHA256 衍生的專屬 Fernet 金鑰。vault.external.json 僅儲存衍生元數據，而非主金鑰。 若金鑰遺失或錯誤，系統將無法啟動，且不會在後台自動替換金鑰。請同時保留 鹽值元數據與主金鑰，以備復原之用。

所有工作區均源自同一主金鑰；若主金鑰遭洩露，將影響整個 安裝環境。正在執行的程序可解密機密資料。此工具並非 HSM 或 密碼 KDF。不接受以任意人為設定的密碼取代隨機金鑰。

在刻意規劃的遷移方案 實施並驗證完成之前，請保留現有安裝環境中的現有金鑰。刪除 vault.key 或更換主金鑰可能會導致 無法存取會話／簽署金鑰。請將加密備份與金鑰分開存放，並 在隔離的實例中測試還原功能。

資料來源與驗證範圍#

審閱日期：2026年10月26日：

• https://core.telegram.org/api/auth
• https://core.telegram.org/api/obtaining_api_id
• https://docs.telethon.dev/en/stable/basic/signing-in.html
• https://docs.telethon.dev/en/stable/concepts/sessions.html
• https://core.telegram.org/mtproto/mtproto-transports
• https://github.com/telegramdesktop/tdesktop/blob/dev/Telegram/SourceFiles/storage/storage_account.cpp
• Telethon 1.45.0：SQLiteSession、StringSession、Connection._proxy_connect、 TcpMTProxy.normalize_secret 及下載方法。

本地測試涵蓋迴路 SOCKS5/HTTP CONNECT 測試案例、模擬的 SQLite 會話、 路由隔離、機密資料排除以及缺失金鑰時的拒絕機制。這些測試並未建立 真實的 Telegram/代理伺服器互通性，亦未模擬 MTProxy 的實際運作行為。請參閱 VERIFICATION.md 及 LIVE_ACCEPTANCE.md。