參考資料 / 設定
Telegram · 部署
可在 Windows、Linux、macOS 或 Docker 環境中,透過 HTTPS 運行 TgWitness 服務,並具備備份與更新功能。
英文 · 俄語 · 烏克蘭語 · 西班牙語 · 葡萄牙語(巴西) · 土耳其語 · 阿拉伯語 · 波斯語 · 烏爾都語 · 印地語 · 印尼語 · 越南語 · 簡體中文
選擇安裝方式#
若要取得可攜式套件,請從
GitHub Releases 解壓縮 TgWitness-<version>-windows-amd64-portable.zip。若採用其他方法,請下載並解壓縮原始碼 ZIP 檔,或克隆
儲存庫,然後在專案目錄中執行以下指令:
| 安裝 | 開始 | 會在背景執行嗎? |
|---|---|---|
| Windows 便攜版套件 | TgWitness.cmd |
不;請保持視窗開啟。 |
| 原生 Windows 版本 | Start.cmd |
不;請使用可選的登入任務以進行背景運作。 |
| 原生支援 Linux/macOS | sh start.sh |
不;請使用 systemd/launchd 進行背景執行。 |
| 在任何受支援的主機上運行 Docker | docker compose up -d --build --wait |
是的,只要 Docker 守護程式正在運行。 |
| Windows 版 Docker 輔助工具 | scripts\Docker.cmd |
是的;該輔助程式會監控網頁伺服器的運作狀態。 |
| 適用於 Linux/macOS 的 Docker 輔助工具 | sh scripts/docker-start.sh |
是的;該輔助程式會監控網頁伺服器的運作狀態。 |
若需部署可由第三方驗證的雲端伺服器——該伺服器透過 服務供應商的 API 建立,不使用 SSH,且僅能透過 Cloudflare Tunnel 存取——請參閱 「高保障部署」說明。
原生啟動程序會建立一個私有 .venv,並安裝已固定(pinned)的依賴項。
Docker 會在映像檔內建置這些組件,無需主機端的 Python。首次
設定需要網路連線。 若未偵測到 Python 3.11 以上版本,Start.cmd 會先徵求確認,
再為當前 Windows 使用者安裝 Python 3.12(若使用 winget,否則在驗證 Python 軟體基金會簽章後,
將使用 python.org 安裝程式);此過程絕不會要求
管理員權限。Docker 及作業系統服務仍為先決條件。
原生及可攜式安裝會在其資料夾內使用 data/live。Docker 則使用名為 tgwitness-data 的卷
,位置為 /data。在您刻意遷移
完整資料目錄之前,這兩者屬於獨立的安裝。請勿預期新的 Docker 容器會自動偵測到原生
帳戶。
安裝需求#
原生安裝需具備 Python 3.11 或更新版本,並包含 venv 和 ensurepip;首次安裝依賴項時需有網際網路
連線,且需為
.venv 準備可寫入的專案目錄。內建的控制面板無需 Node.js 或前端建置。請從
您的一般作業系統帳戶執行啟動程式;TgWitness 無需管理員/root 權限。
- Windows:
Start.cmd會先檢查py -3,接著檢查python,然後檢查預設的「使用者專用」及 「Program Files」安裝資料夾,並需要 3.11 版或更新版本。若以上皆無法運作,它 會提供上述所述的自動「使用者專用」安裝選項。py -3 start.py亦可運作。 可攜式套件完全不需要 Python。 - Linux:
start.sh會依序嘗試python3.13、python3.12、python3.11、python3及python,若均不符合條件,則會輸出適用於 apt、dnf、pacman、zypper、apk 或 Homebrew 的安裝指令。 Debian/Ubuntu 系統的安裝可能需要與所選解釋器相符的python3-venv套件。 發行版的舊版 預設 Python 必須被 Python 3.11 以上版本取代或補充。 - macOS:請安裝最新的 Python 3.11+ 發行版;請勿假設作業系統預設提供的
解釋器符合要求。請使用專案目錄中的
python3 start.py。 - Docker:請使用搭配 Compose v2.20 或更新版本的 Docker Engine/Desktop。在 Windows 系統上,Docker Desktop 必須使用 Linux 容器。該容器會自行安裝 所需的 Python 依賴項;主機無需另行安裝 Python。
本地電腦#
請在 Windows 系統上使用 Start.cmd,或在 Linux/macOS 系統上使用 sh start.sh。scripts\Setup.cmd 或
sh start.sh --setup-only 會預先
設定環境。啟動程式在首次使用時會安裝所需依賴項;後續啟動時
則會重複使用該環境。設定及 Telegram 訊息收集過程需要網路連線,
但瀏覽現有記錄及建立匯出檔則可在離線狀態下進行。
設定完成後執行 python start.py --check,以檢查本機依賴項、Ed25519、
儲存空間、金鑰設定及監聽位址,此過程不會啟動資料收集器。
若需結構化輸出,請使用 --json。傳入預期的 --data-dir、--host 及
--port。此檢查不會安裝套件、建立日誌或連線至 Telegram;
亦非完整性或覆蓋範圍的驗證。啟動時會另行驗證
現有日誌。python start.py --help 亦會跳過安裝步驟。
執行 start.py 後,請在 Windows 系統上使用 .venv\Scripts\python.exe,或在 Linux/macOS 系統上使用 .venv/bin/python 來執行輔助指令,亦可先啟用該環境。
以下 python -m ... 範例假設該環境已啟用。
python -m tgwitness --data-dir /path/to/private/data --host 127.0.0.1 --port 8787
環境變數:TGWITNESS_DATA、TGWITNESS_HOST、TGWITNESS_PORT、TGWITNESS_TOKEN。 TGWITNESS_VAULT_KEY_FILE 用於為新安裝選擇外部金鑰模式;請參閱「外部主金鑰」。 若提供 TGWITNESS_TOKEN,其長度必須至少為 24 個字元;請使用加密級 隨機值。若未提供,應用程式會於 panel-token.txt 檔案中產生一個 256 位元的隨機憑證。 環境變數的覆寫設定不會重新寫入該檔案。請重新啟動以輪替憑證。
僅允許一個進程擁有資料目錄。跨平台作業系統檔案鎖定機制可防止 意外的並發寫入。請使用一個 Uvicorn 工作程序。控制面板可管理任意數量的 工作區,額外的工作區目錄位於 profiles/<id>/ 之下。 若需獨立的服務實例,請使用獨立的目錄與埠號。SQLite WAL 檔案應存放於本機持久性 儲存裝置,而非網路檔案系統。請勿在複本之間共用同一個卷宗。
Windows 便攜版套件#
每個 GitHub 發行版本均包含 TgWitness-<version>-windows-amd64-portable.zip 及其
.sha256。其中包含來自 python.org 的官方可嵌入式 Python 3.12 執行環境
(校驗和固定於 tools/build_portable.py 中)、TgWitness 及其固定依賴項,
以及三個啟動程式:
| 檔案 | 目的 |
|---|---|
TgWitness.cmd |
啟動控制面板;額外選項將被直接傳遞,例如:TgWitness.cmd --port 8790 |
TgWitness-Demo.cmd |
在 data\demo 啟動合成示範 |
TgWitness-Check.cmd |
在不啟動的情況下執行就緒檢查 |
已將釘選的俄語形態學辭典與 PDF 色彩設定檔打包,供
離線使用。打包機制僅允許在依賴項的
data 目錄內放置已知的檔案路徑;若該目錄中出現預期之外的檔案,將導致建置失敗。
將整個壓縮檔解壓縮至可寫入的資料夾(例如 Documents\TgWitness);請勿
直接從 ZIP 檔案內部或 Program Files 資料夾執行。執行環境採用隔離的模組路徑,
因此其他 Python 安裝程式及 PYTHONPATH 皆不會影響其運作。 資料會儲存於
套件的 data 資料夾中。若要更新,請先停止 TgWitness,將新版本解壓縮至新的
資料夾,並將 data 資料夾複製過去。
請在 64 位元 Windows 系統上使用 Python 3.12 自行建置:
python tools/build_portable.py
容器#
docker compose up -d --build --wait
這會為 /data 建立一個命名持久化卷。
Web 埠號映射至 127.0.0.1:8787。該程序以 UID 10001 執行,並具備
已移除的權能、唯讀的根檔案系統,以及可寫入的 /data 和 /tmp 目錄。
--wait 會在返回前檢查 Web 伺服器的運作狀態;Telegram 授權與
傳送狀態會顯示在控制面板中。提供的輔助程式在建置完成後會採用 180 秒的就緒超時
設定。初始依賴項的下載時間可能比這更長。
兩個基礎 Compose 檔案均使用專案名稱 tgwitness,因此將新版本
解壓縮至其他目錄時,系統不會自動選取新的資料卷。請僅保留一個
該專案的部署處於活躍狀態。若為獨立安裝,請使用唯一的
docker compose -p NAME ... 以及不同的主機埠,並在更新時保留兩者。
若為使用不同專案名稱的舊版部署,請繼續使用其原始
名稱並搭配 -p;docker compose ls 會列出現有專案。
將 deploy/env.example 複製到 .env,並將 TGWITNESS_PORT 修改為使用不同的迴路
埠。例如,TGWITNESS_PORT=8788 會將控制面板公開於
http://127.0.0.1:8788;容器仍會監聽 8787 埠。.env 已被 Git 忽略。
取得初始代幣:
docker compose exec tgwitness cat /data/panel-token.txt
實用指令:
docker compose ps
docker compose logs --tail 100 -f
docker compose stop
docker compose up -d --wait
restart: unless-stopped 會在發生當機或 Docker 守護程式
重新啟動後,重新啟動資料擷取器。在 Linux 伺服器上,請使用您所使用的發行版的服務
管理程式(通常為 sudo systemctl enable --now docker)啟用開機自動啟動 Docker。在 Windows/macOS 上,請啟用
Docker Desktop 的「登入時啟動」設定。當桌面登出、進入睡眠狀態,或 Docker
Docker 守護程式都可能中斷資料收集。明確停止的容器將保持
停止狀態,直到您再次啟動它為止。
在範例配置中,/tmp 卷的上限為 512 MiB。匯出建置
改為使用各工作區位於持久化 /data 目錄下的 temporary-exports/ 目錄。請在該處預留空間
以因應同時進行的匯出作業、日誌/WAL 增長、媒體檔案及備份需求。
啟動器會使用 deploy/constraints.txt 來鎖定符合資格的執行時依賴項版本。
Docker 及高保障伺服器會依據 deploy/requirements.lock 和
deploy/build.lock 透過 pip --require-hashes 進行安裝:每個套件檔案都必須與提交紀錄中儲存的 SHA-256
值相符,因此若檔案在 PyPI 或鏡像站上被替換,系統將拒絕該檔案。 僅提供
原始碼的套件(如 jieba、pyaes)會由啟動程式、Windows 可攜式建置工具及 Dockerfile
根據 deploy/build.lock 中鎖定的 setuptools(--no-build-isolation)進行建置,
因此 pip 不會解析另一個未鎖定的建置環境。 Python 基礎
映像檔與作業系統套件仍需通過獨立的發行資格認證。
除非您打算銷毀日誌和金鑰,否則請勿使用 `docker compose down -v` 指令。 容器狀態報告僅顯示網頁伺服器的可用性,而非 Telegram 擷取是否成功。 請檢查控制面板中的收集器狀態、心跳訊號、錯誤及覆蓋事件。
獨立見證者簡介#
可選的 witness 服務會在其專屬的
容器中運行獨立見證者,其專屬金鑰與日誌存放於 witness-data 卷中,並僅對收集器提供
唯讀的見證者代幣。請在控制面板的「更多工具」→「額外功能」→「獨立見證者」中建立該代幣,並將其
連同機器人代幣與頻道一併新增至 .env,然後啟動配置檔:
docker compose --profile witness up -d # deploy/compose/compose.image.yaml: same flag
docker compose logs witness # witness key fingerprint
此服務可透過 Compose 網路內的收集器存取,網址為 http://tgwitness:8787
(TGWITNESS_WITNESS_COLLECTOR
會覆寫此設定,例如 /profiles/<workspace ID>
適用於
另一個工作區)。若要使用由他人運作的獨立伺服器上的證據日誌,請在該處使用
deploy/compose/compose.witness.yaml
,並將 TGWITNESS_WITNESS_COLLECTOR
設定為收集器的 HTTPS
位址;該檔案僅包含證據日誌。
安裝已發佈的映像檔#
將 deploy/env.example 複製到 .env。將 TGWITNESS_IMAGE 設定為已發布的版本,並使用
小寫的儲存庫路徑,例如:
TGWITNESS_IMAGE=ghcr.io/your-owner/your-repository:0.9.3
TGWITNESS_PORT=8787
請直接執行此檔案,而非執行 `compose.yaml`:
docker compose --project-directory . -f deploy/compose/compose.image.yaml pull
docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait
docker compose --project-directory . -f deploy/compose/compose.image.yaml exec tgwitness cat /data/panel-token.txt
主機端無需進行原始碼編譯、Python 環境或編譯器。發行工作流程
針對 Linux AMD64 和 ARM64 容器,包括 Docker Desktop 的 Linux 虛擬機器。
請使用版本標籤或工作流程摘要中的「ghcr.io/owner/repository@sha256:...」。
未配置動態標籤「latest」或無人值守的應用程式升級。當
專案名稱相同時,映像檔與原始碼變體將共用同一個資料卷。
伺服器上的自動 HTTPS 功能#
請使用配備 Docker 的伺服器、您所掌控的網域,以及持久的本地儲存空間。 將網域的 A/AAAA 記錄指向該伺服器;僅當 IPv6 可連達該伺服器時,才發布 AAAA 記錄。 允許傳入的 TCP 80 和 443 連接,以及用於憑證簽發的傳出 DNS/HTTPS 連線。 其他服務不得已佔用這些埠號。
將 deploy/env.example 複製到 .env,並設定主機名稱(不包含方案或路徑):
TGWITNESS_DOMAIN=watch.your-domain.org
使用 HTTPS 覆蓋層開始建置原始碼:
docker compose -f compose.yaml -f deploy/compose/compose.https.yaml up -d --build --wait
docker compose -f compose.yaml -f deploy/compose/compose.https.yaml exec tgwitness cat /data/panel-token.txt
docker compose --project-directory . -f deploy/compose/compose.image.yaml -f deploy/compose/compose.https.yaml up -d --wait
若要發布圖片,請改以 deploy/compose/compose.image.yaml 作為第一個檔案。請保留
兩個 -f 參數,以便日後執行狀態查詢、日誌檢視、更新及停止指令。
Caddy 負責取得並更新憑證、將 HTTP 重定向至 HTTPS,並將 請求轉發至私有 Compose 網路上的收集器。憑證狀態 擁有專屬的持久化儲存區。收集器的直接主機埠僅限於迴路連接。 提供的 Caddy 設定未啟用存取記錄功能。
開啟 https://watch.your-domain.org 並輸入控制面板代幣。準備就緒性評估
涵蓋儲存容器;憑證簽發與外部可達性取決於 DNS
及防火牆。若 HTTPS 尚未就緒,請檢查 DNS、防火牆規則,以及:
docker compose -f compose.yaml -f deploy/compose/compose.https.yaml logs --tail 100 caddy
提供的 Caddy 映像檔遵循其 2-alpine 標籤。拉取操作會更新該映像檔;
若需固定基礎架構版本,請在您的部署中固定一個已測試的摘要。
更新與備份#
在更新過程中,請保留 Compose 專案名稱及資料量。首先停止 收集器,並執行完整備份。針對預設的基於來源的部署:
docker compose stop
docker compose cp tgwitness:/data ../tgwitness-backup-before-update
每次請使用位於儲存庫之外的新備份目的地,並將其視為 需受帳戶存取權限保護的資料。範例路徑僅供說明;請使用您自己的私人備份 位置。複製整個目錄,包括隱藏檔案、所有工作區、金鑰、 日誌及媒體檔案。若已設定外部金庫主金鑰,請另行備份。 證據 ZIP 檔並非可還原的應用程式備份。若使用 HTTPS,且需保留其憑證/帳戶狀態時, 請一併保留 Caddy 卷宗。
若要進行原始碼部署,請取得最新發行版本的檔案,並執行:
docker compose up -d --build --wait
若要進行圖像部署,請將 TGWITNESS_IMAGE 改為所需版本,然後執行:
docker compose --project-directory . -f deploy/compose/compose.image.yaml pull
docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait
請亦使用您安裝環境中的 Compose 檔案來執行前述的停止/複製指令。
請保留 .env、自訂設定以及相同的專案名稱。down 會保留命名
的資料卷;down -v 則會刪除它們。請勿在不同作業系統
或 Python 版本之間複製 .venv。若要進行原生更新,請先停止 TgWitness,備份其完整的資料
目錄,替換原始檔案,並在啟動前執行 python start.py --setup-only。
在更新後檢查面板存取權限、帳戶身分、觀察狀態及覆蓋範圍。 重新啟動後,TgWitness 將恢復儲存的 Telegram 更新位置,並 請求更新過程中遺漏的更新內容。若未來版本變更儲存格式, 回滾操作可能需要使用更新前的備份。
遠端伺服器#
請將服務限制在迴路連接並使用 SSH 隧道,或讓 HTTPS 連線在
反向代理伺服器處終止。基礎 Compose 檔案僅限本地使用;可選的
deploy/compose/compose.https.yaml 覆蓋層會提供 Caddy 以支援已設定的網域。
請勿讓承載者憑證出現在 URL 及代理伺服器日誌中。反向代理伺服器應限制
請求大小與連線頻率。請勿將明文 HTTP 暴露於網際網路。
deploy/ 目錄中提供了 systemd、Windows 登入任務、macOS 使用者代理程式以及 Caddy 的範例, 請在安裝前檢視並調整其路徑。 這些僅為範本,並非在本地端執行的平台設定。 標準啟動程式不會註冊任何背景服務或任務。
在 Windows 系統上,以無視窗模式啟動 pythonw.exe 時,會將啟動/伺服器診斷記錄儲存於
資料目錄下的 logs/server.log 中(每檔 5 MiB,包含兩份輪替備份)。
以控制台模式啟動時,則會保留控制台日誌。兩種模式下
皆已停用 HTTP 存取日誌。請透過資料目錄保護日誌,並在分享前進行審閱。
重新啟動與資料缺口#
系統會保留上次請求的監測狀態。若監測處於活躍狀態, 啟動時系統會嘗試重新連線並恢復已選定的來源。手動暫停會清除 此設定。重啟失敗的紀錄將被保存並顯示於控制面板中。
TgWitness 會將該帳戶及各頻道的 Telegram 更新位置 (pts、qts、seq 及日期)儲存於工作區金庫中,並於下次啟動時還原。 接著,客戶端會請求在程序停止期間錯過的更新,而 定期重新檢查則會恢復錯過的訊息,並記錄那些 Telegram 已 不再回傳的已儲存訊息。對話視窗會在啟動時重新載入。 每次啟動時,系統都會記錄前一次的 日誌頭、離線邊界以及恢復時的更新位置。 監控程式每10秒檢查一次連線狀態,並每分鐘發送一次心跳訊號 (更多工具 → 參數 → 每隔 X 秒記錄存活狀態)。 斷線和靜默期間會連同原因一併記錄為覆蓋缺口。 歷史快照會作為獨立的「當前歷史」觀察結果,與即時記錄並列儲存。
媒體佇列儲存於各工作區的 SQLite 資料庫中。訊息及其工作 會以原子方式提交。中斷的執行中工作將在啟動時恢復並重新嘗試。 每次下載有120 秒的基本超時,加上以 256 KiB/s 速度下載其大小所需的時間,以及 每種附件類型設有 1–2,000 MiB 的限制;超時、速度及重試設定位於「更多工具 → 參數」中。收集器 會跳過大小未知的檔案。暫停操作會保留排程中的工作。重試會使用原始 觀察到的檔案描述符,絕不會使用後續編輯訊息的最新版本。 暫時性失敗有重試次數上限;媒體 FloodWait 暫停狀態在重新啟動後仍會保留。 媒體恢復與 Telegram 更新恢復是分開的,且無法重建已消失的檔案。
備份、還原與儲存容量#
tgwitness backup FOLDER
會在控制面板持續運作的同時複製資料目錄:
首先複製檢查點,接著透過線上備份 API 複製 SQLite 檔案,然後是金鑰、媒體和
設定檔,因此任何複製的檢查點都不會比複製的日誌更新。backup-manifest.json
列出了每個檔案的 SHA-256 值以及日誌頭。 要還原時,請停止 TgWitness 並將
整個資料目錄替換為該資料夾。下次啟動時會記錄日誌是從
較舊的副本還原而來。該記錄會將日誌與儲存於
TGWITNESS_STATE_DIR
(位於資料目錄外的資料夾)中的日誌頭進行比對:若在
Compose 中的 tgwitness-state
卷、systemd 單元中的 /var/lib/tgwitness-state
,以及其他情況下的使用者本機狀態資料夾
。若無可寫入的狀態資料夾,系統將無法偵測到還原操作,且日誌會記錄此情況一次。
若未執行此指令,請在複製整個資料目錄(包括 vault.key、 signing.enc、credentials.enc、SQLite 資料庫/WAL 檔案、媒體檔案、憑證、檢查點, 以及所有 profiles/ 子目錄)之前,先停止該程序。 請在 目標服務停止運作時還原完整的副本。若金庫金鑰遺失或 簽署金鑰不匹配,將導致啟動失敗;請勿重新產生金鑰以強行存取。
請將秘密備份進行加密並實施存取控制。證據 ZIP 檔具有可攜性, 請檢視的是證據檔案,而非應用程式備份或 Telegram 會話備份。 本工具不具備自動保留與刪除功能。請預留足夠的磁碟空間,以存放所有訊息、原始 元資料、媒體檔案、臨時匯出檔及備份。
啟動驗證並匯出串流記錄,而非載入整個日誌。
匯出操作會鎖定一個讀取快照,同時新的 WAL 寫入仍可繼續;長時間執行的匯出
可能會保留 WAL 頁面,因此磁碟容量仍至關重要。 ZIP 檔案的上限為 4 GiB
(未壓縮),以符合獨立驗證器的預設值;透過「更多工具 → 參數 → 最大簽名 ZIP」
可提高上限,此類存檔可透過 verify.py --max-gib N 進行驗證。其他格式則無事件數上限。
受支援的瀏覽器會將回應區塊串流傳輸至使用者選定的檔案。其他瀏覽器
最多緩衝 128 MiB,並將較大的傳輸導向經認證的 CLI:
python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip
若要使用其他工作區,請從「Exports → Workspace ID」中選用 --profile ID;
若要使用遠端伺服器,請選用 --format zip|jsonl|csv|html 或 --url https://your-server;
若要變更 5 GiB 的傳輸限制,請選用 --max-mib。僅允許在
迴圈連接(loopback)中使用純 HTTP。憑證透過標頭傳輸,拒絕重定向,現有檔案
不會被覆寫,且未完成的下載不會被發布為已完成檔案。
若 TGWITNESS_TOKEN 覆寫了生成的憑證,請使用一個獨立受保護的檔案
來存放該有效值:panel-token.txt 不會因覆寫而被改寫。
該指令的 SHA-256 僅為傳輸校驗和;請獨立驗證已簽名的 ZIP 檔案。
該面板顯示排隊中/失敗的媒體檔案、最舊的待處理媒體檔案、可用磁碟空間、Telegram 請求暫停狀態,以及存取權限未經確認的來源。這些診斷資訊並非 完整的端對端傳輸監控。工作區共用同一個程序;若某個帳戶活動頻繁, 仍可能影響其他帳戶。 獨立的工作程序、資料保留/輪替、持久性更新 恢復以及完整的部署認證仍維持不變。控制面板的範圍式存取權限已記錄於 「存取與權限」文件中;獨立檢查點則由「 見證指南」涵蓋。