參考資料 / 證據
Telegram · 獨立見證人
請使用具備專屬金鑰與機器人的「Witness」執行程序,將簽署過的檢查點發佈至頻道,並據此核對匯出資料。
見證者會將已簽名的檢查點與收集器分開保存。它會檢查 收集器的簽名與日誌連續性,使用自身的金鑰對結果進行簽名,並 將其發佈至 Telegram 頻道。請在具備對 收集器見證端點唯讀存取權限的獨立伺服器上執行此工具。
技術結果包括保留的日誌前綴、挑戰回應、簽章檢查、Merkle 包含/一致性檢查,以及簽署的連續性結果。對於由其他保管方營運的見證者,請保留保管方資訊及附有其指紋的金鑰控管記錄。分開的金鑰與分開的保管描述的是部署的不同部分。驗證器會回報第二把金鑰保留了日誌頭部,以及保留到哪一筆記錄;保管方的金鑰控管記錄顯示該金鑰由誰持有。見證者日誌是輔助檢查;證據的最低要求是第三方時間。頻道貼文增加了外部時間:Telegram 為每則公開貼文標註日期,驗證器會自行讀取這些日期。
圖表轉為文字
- 收集器 → 見證者 (簽名檢查點:記錄數 + 頭部雜湊值)
- 見證者 → Witness 日誌,自有金鑰
- 見證者 → Telegram 頻道 (透過其自有機器人發布的簽名貼文)
- 證據 ZIP 檔案 → verify.py
- Witness 日誌,自有金鑰 → verify.py
- Telegram 頻道 → verify.py (t.me/s 頁面即時閱讀,或桌面版匯出)
本頁內容
見證者保存的內容#
| 該證據日誌具備 | 該證人從未 |
|---|---|
| 適用於單一工作區的唯讀見證代幣 | 資料收集者的 Telegram 會話或 API 憑證 |
| 其專屬的 Ed25519 金鑰與日誌 | 收集器的儲存庫、簽名金鑰或面板憑證 |
| 專屬的 Telegram 機器人代幣 | 訊息內容:開頭為記錄數量及雜湊值 |
該憑證是在「更多工具」→「進階功能」→「獨立見證者」中建立,僅顯示一次,且僅以
SHA-256 格式儲存。它僅開啟一個端點:GET /api/witness/head,該端點會返回一個剛
簽署的檢查點,以及經簽署的無內容收集計數器和運作狀態。
該憑證無法開啟控制面板、讀取訊息內容或變更設定,且
該處不接受控制面板憑證。可在同一頁面撤銷憑證。收集器會記錄
新見證金鑰開始檢查的時間(witness.seen),並顯示每個憑證的最後檢查時間;
若見證金鑰在 2.5 個間隔內未進行檢查,則會被標記為逾期。
新見證者會在 每次投票時發送一個隨機挑戰;擷取陳述會於收集器簽名下方重複該挑戰。計數器 與確切的檢查點綁定,並包含在簽名的見證貼文中。舊版見證者 仍可被獨立見證者接受。僅日誌的增長絕不會被計為新訊息。
其檢查與記錄的內容#
每隔一段時間(預設為 10 分鐘),Witness 會:
- 自行擷取頭部資料(收集器無法推送或跳過該部分);
- 驗證收集器的簽名、固定收集器金鑰(
--collector-fingerprint, 或首個偵測到的金鑰)、一個非遞減的計數,以及在未變更計數下未變更的頭節點。 Merkle 包含性與一致性證明可驗證,日益增長的日誌是否延伸至 保留的檢查點。一旦使用過連續性證明,便會拒絕移除該證明; - 將一份經簽署的記錄附加至其自身的日誌中:
witness.anchor,狀態為ok、key_changed、rollback(記錄數量少於先前)、fork(長度相同,但 標頭不同)或invalid(回應未能通過驗證),或當 收集器未回應時為witness.no_response; - 將結果發佈至頻道,並附有簽名,包含「無回應」的情況,只要 TgWitness
正在運行且能連線至 Bot API。發佈 ID 已記錄(
witness.posted), 發佈失敗的情況亦同(witness.post_failed)。
一則貼文的樣貌如下;最後一行載有經簽署的聲明:
TgWitness witness #42 · journal head
Collector 3fa9c2d1e0b4a7f6: 18234 records
Head 9b1f…c07e
2026-10-28T19:40:00.123+00:00
TGW1.eyJhdCI6…<statement>.<signature>
執行 TgWitness#
您需要一個 Telegram 機器人(可透過 @BotFather 建立),一個由該機器人擔任 管理員的頻道,以及一個可從證人端存取的收集器位址——需透過 HTTPS 連線,且位於 私有網路之外(請參閱部署章節中的 HTTPS 設定檔)。
在面板中開啟「更多工具」→「進階功能」→「獨立見證者」→「設定」
。三個步驟涵蓋
唯讀存取權限、您的頻道與間隔時間,然後啟動見證者。發佈
政策、可選的 HTTP/SOCKS5 代理伺服器以及自訂 Bot API 位址均位於「進階設定」
中。此表單
會下載包含此工作區固定收集器金鑰的 witness.json
。 請將新
建立的唯讀憑證以「儲存存取檔案
為 witness-token.txt
」的方式下載;將該檔案與在見證主機上建立的 bot-token.txt
放置在該 JSON 檔案旁邊。收集器絕不會收到機器人憑證。
下載操作不會啟動任何服務,也不會發佈任何訊息。任何託管專案的見證者均不會
被隱含地註冊。
python -m tgwitness.witness run --config witness.json --check-config
python -m tgwitness.witness run --config witness.json
python -m tgwitness.witness fingerprint --config witness.json
第一個指令會檢查配置檔和密鑰檔案,過程中不會發出網路請求或建立金鑰。 JSON 中的路徑是以該檔案為基準的相對路徑;CLI/環境路徑則是以 工作目錄為基準的相對路徑。 將見證者的指紋保留在其主機之外。收集器的 「最後輪詢」指標僅用於確認請求;發布狀況則由 Proof 回報,或可透過 見證者日誌及頻道進行查核。
若控制面板位於 SSH 隧道後方,請參照此 Caddy 範例,僅在
獨立的 HTTPS 主機名稱上公開範圍限定的 Witness 端點。
預設工作區將使用 https://witness.example.org,其他工作區則使用
https://witness.example.org/profiles/ID。仍需提供存取憑證;該虛擬主機不會轉發控制面板及其
其他 API 路由。
選擇 all 以獲取定期發布的檢查點。五分鐘的間隔意味著每個工作區每天約有 288
則貼文。changes/problems 會刻意不發布部分檢查點。
MTProxy 適用於資料收集者的 Telegram 客戶端。Witness 的 HTTP 輪詢與 Telegram 的 HTTPS
Bot API 會使用各自的直接連線/HTTP/SOCKS5 路由(Bot API)。
在收集器旁邊,使用 Docker(同一主機——獨立的程序和金鑰,但
由同一位操作員管理):將數值填入 .env 並啟動該設定檔。
TGWITNESS_WITNESS_TOKEN=tgww_...
TGWITNESS_WITNESS_BOT_TOKEN=123456:ABC...
TGWITNESS_WITNESS_CHANNEL=@your_witness_channel
# another workspace: TGWITNESS_WITNESS_COLLECTOR=http://tgwitness:8787/profiles/<workspace ID>
docker compose --profile witness up -d
docker compose logs witness # prints the witness key fingerprint
若使用已發布的圖片,請標註 docker compose --project-directory . -f deploy/compose/compose.image.yaml --profile witness up -d。
在其他人的伺服器上(獨立託管):將儲存庫複製至該處,並在
TGWITNESS_WITNESS_COLLECTOR=https://your-collector.example.org 中加上上述三個值
至 .env,然後
docker compose --project-directory . -f deploy/compose/compose.witness.yaml up -d
或不使用 Docker:
python -m tgwitness.witness run --collector https://your-collector.example.org \
--token-file witness-token.txt --bot-token-file bot-token.txt --channel @your_witness_channel
發佈至 Discord#
見證者可選擇在 Discord 頻道而非 Telegram 上發文。在 Discord 中,開啟
「編輯頻道」→「整合」→「Webhook」,建立一個 Webhook 並複製其網址。在
設定面板中,於步驟 2 選擇「Discord Webhook · 您的頻道」。在見證者主機上,
將該網址儲存為 discord-webhook.txt 旁 witness.json;該連結絕不會傳送至
收集器。
python -m tgwitness.witness run --collector https://your-collector.example.org \
--token-file witness-token.txt --discord-webhook-file discord-webhook.txt
一名見證者僅有一個發布者:Telegram 頻道或 Discord Webhook,不可同時使用兩者。貼文
均攜帶相同的簽名聲明,且無法向任何人發送通知。長度超過 Discord
2,000
字元的貼文將被替換為一行簡短文字,並將完整的驗證碼附加為
witness-check.txt
。每個貼文 ID 皆記錄為 witness.posted
。verify.py --channel
僅讀取 Telegram 頻道,因此針對 Discord 請保留見證者日誌:其中包含所有
驗證碼。Discord 貼文不會為驗證者提供外部時間資訊。
選項#
| 選項 | 環境 | 預設 | 含義 |
|---|---|---|---|
--interval |
TGWITNESS_WITNESS_INTERVAL |
10 | 檢查間隔時間,1–1440 |
--timeout |
_TIMEOUT |
30 | 等待資料收集器與 Bot API 的時間為 5 至 600 秒 |
--post |
_POST |
all |
all:每項檢查;changes:新進展或新問題;problems:盡是問題與未解之謎 |
--title |
_TITLE |
TgWitness witness |
每個頻道貼文的開頭字句 |
--collector-fingerprint |
_COLLECTOR_FINGERPRINT |
– | 請將收集器金鑰固定,而非直接採信第一個答案 |
--proxy |
_PROXY |
直接 | socks5://host:port 或 http://host:port |
--bot-api |
_BOT_API |
https://api.telegram.org |
Bot API 位址,例如本地的 Bot API 伺服器 |
--data-dir |
_DATA |
witness-data |
Witness 金鑰與日誌 |
--config |
_CONFIG |
– | 包含上述任一選項的 JSON 檔案 |
收集器的地址、代幣及頻道來自 --collector, --token 或
--token-file, --bot-token 或 --bot-token-file, --discord-webhook-file 以及 --channel,
或 _COLLECTOR, _TOKEN, _TOKEN_FILE, _BOT_TOKEN, _BOT_TOKEN_FILE,
_DISCORD_WEBHOOK_FILE 以及 _CHANNEL,這能防止機密項目出現在程序清單中。
配置檔採用帶有底線的選項名稱,並加上texts,該代碼會替換頻道貼文中的
文字:
{"collector": "https://your-collector.example.org", "token_file": "witness-token.txt",
"bot_token_file": "bot-token.txt", "channel": "@your_witness_channel",
"interval": 5, "timeout": 30, "post": "changes", "title": "Partner witness",
"texts": {"ok": "journal head", "no_response": "no answer from the collector", "records": "records"}}
texts 鍵值:ok、key_changed、rollback、fork、invalid、no_response、collector、
records、head。命令列優先於環境變數,環境變數優先於檔案設定。
未知選項或文字鍵值會觸發訊息並中止見證者運作,而非被忽略。
文字表述絕不會影響驗證:verify.py 會在每次
發佈結束時檢查簽名代幣。使用 --post changes 或 problems 時,未發佈的檢查仍會保留在
見證日誌中,且 verify.py 會將其列為「從未發佈」;起始記錄會標明
政策名稱。每項檢查仍會出現在日誌中,因此發佈次數減少僅表示由 Telegram 標記日期的
次數減少,而非檢查次數減少。
即使沒有頻道,Witness 仍會持續維護其日誌。請將 Witness 金鑰指紋
(python -m tgwitness.witness fingerprint) 存放在其他地方。
多個工作區的公開驗證頁面#
python -m tgwitness.proof TgWitness 最多可同時監控 32 個工作區,並提供一個唯讀
頁面,顯示每個工作區最新的簽名檢查結果。每個工作區在 data 資料夾下都有專屬的見證金鑰和
日誌,以及一個固定收藏金鑰;是否發佈至 Telegram 頻道
則可針對每個工作區自行選擇。請從
proof.config.example 開始:
| 領域 | 含義 |
|---|---|
title |
頁面標題,1–100 個字元 |
data_dir |
與檔案相關的 Witness 金鑰和日誌;預設值 proof-data |
interval, timeout |
檢查間隔(分鐘,範圍 1–1440,預設值 5);等待時間(秒,範圍 5–600,預設值 20) |
workspaces[].id, label |
簡短的小寫別名與顯示名稱 |
workspaces[].collector |
收集器地址;其他工作區的結尾為 /profiles/<workspace ID> |
workspaces[].collector_fingerprint |
必備項目,每個工作區各不相同 |
workspaces[].token_file |
包含該工作區唯讀見證代幣的檔案 |
workspaces[].channel, bot_token_file |
可選功能:將每次檢查結果發佈至頻道 |
workspaces[].proxy, bot_api |
可選的路徑與 Bot API 位址 |
python -m tgwitness.proof --config proof.json --check-config
python -m tgwitness.proof --config proof.json --host 127.0.0.1 --port 8790
第一個指令會在不建立連線的情況下,驗證檔案及代幣檔案。 該頁面僅回應 GET 和 HEAD 請求:
/顯示所有工作區;若某個工作區在 2.5 個間隔內未被檢查,則會被標記為過期。/api/proof回傳的結果與 JSON 相同。/api/proof/<id>下載最新的簽署聲明(tgwitness-public-proof-v1): 見證記錄編號與雜湊值、狀態、固定收藏器金鑰、檢查點、收集 計數器,以及頻道發文是否成功,並由該工作區的見證金鑰簽署。/healthz當工作區的監控程式停止運作時,會回傳 503 錯誤。
請為該頁面設定專屬的主機名稱,例如
Caddyfile.proof.example。為進行驗證,請使用
以下說明中的方法匯出
工作區的見證日誌,
python -m tgwitness.witness export --data-dir proof-data/<id> --out witness.zip ,並依照
以下說明使用該日誌。
驗證#
在「witness」端,匯出其日誌:
python -m tgwitness.witness export --out witness.zip
# Docker (add -f deploy/compose/compose.witness.yaml on a witness server):
docker compose exec witness python -m tgwitness.witness export --out /witness/witness.zip
docker compose cp witness:/witness/witness.zip .
接著,無論身在何處,只要擁有收集器的簽名 ZIP 檔以及公開頻道的網址:
python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \
--witness witness.zip --witness-fingerprint WITNESS_SHA256 --channel https://t.me/s/your_witness_channel
--channel 亦接受 Telegram Desktop 的匯出檔案(「匯出聊天記錄 → JSON」會產生
result.json)或頁面的儲存副本;這些檔案會檢查貼文內容,但不會提供
外部時間戳記。
verify.py會檢查見證者日誌(區塊鏈與簽名),接著確認見證者所見的每個
頭部(head)是否皆屬於匯出日誌的一部分:該計數處的記錄必須擁有精確
相同的雜湊值。 若某個頭節點不匹配,則驗證失敗——表示日誌在
見證者觀察後遭到篡改。該程式還會回報出口後觀察到的頭節點、見證者
記錄的異常情況、失敗的回應、其匹配檢查點存在於本次
出口中的期間(「從 X 到 Y 期間已見證」),以及缺口。後續的檢查點不會延長這些期間。
結果包含最後一個匹配的記錄編號,以及沒有匹配檢查點的
後續記錄數量。 僅計入由該匯出檔自身金鑰簽署的回應:若匯出檔由
見證者從未見過的金鑰簽署,則會被報告為未經見證;若未使用--fingerprint參數,其
簽署者將保持未釘定狀態。使用--channel時,每個簽署的貼文必須與見證者日誌
逐筆匹配:遭修改的貼文將驗證失敗,缺失的貼文則會被列出。透過
代幣的匹配來驗證內容;日期則不包含在簽署的代幣範圍內。
驗證者透過有效的 https://t.me/s/… 或 https://telegram.me/s/… 網址,
在驗證時從頁面讀取每則貼文的日期。 Telegram 設定該日期;
已編輯貼文的日期不予採用。在匯出起點處,貼文的最早日期即為
最後一筆符合「最低證據要求」條件的記錄之外部時間。來自
任何其他來源的日期(例如提供的 result.json、已儲存的頁面或另一個網頁
網址),均屬元資料,而非獨立時間;結果會標明其貼文
日期來源(post_date_verification)。
需設定經見證的匯出範圍#
若需進行必須包含經見證之最終紀錄的交接,請加入 --require-witness:
python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \
--witness witness.zip --witness-fingerprint WITNESS_SHA256 --require-witness
這需要獨立保留的見證者指紋、一個與
收集器金鑰不同的金鑰,以及位於此匯出檔案精確末端的匹配檢查點。僅涵蓋較早前綴的檢查點
是不夠的。暫停收集,讓見證者
觀察最終狀態,並在日誌進一步寫入前進行匯出;若日誌發生變更,請保留另一個檢查點並
匯出該狀態。僅憑較晚的檢查點無法驗證較短匯出檔案的最終雜湊值。
當同時提供--channel時,若缺少聲稱的貼文或匹配集為空,將導致此
嚴格檢查失敗。若未使用此標誌,一般的完整性檢查仍會報告未經見證的
記錄,但不會因此拒絕一個除此之外完整的存檔。
請將見證日誌及其固定金鑰分開存放。線上檢查用於驗證各檢查點之間的連續性; 離線驗證則會將每個保留的檢查點與 匯出檔進行比對。缺乏連續性證明之舊版見證節點仍會保留離線比對結果,並 在未進行線上連續性驗證的情況下提交報告。報告會按時間區間列出見證節點的停機時間及 發布失敗的紀錄。
每日印章與不可用的時間戳日曆#
見證人會對前一天(UTC)的日誌邊界進行封存,並將 該簽名封印的雜湊值提交至 OpenTimestamps。日曆提交屬於待確認的證據; 僅經獨立核查的比特幣承諾才會獲得驗證器的確認。
若所有日曆皆失敗,簽名印章與未成功的嘗試仍會保留在 日誌中。每小時的維護循環會重新嘗試處理該原始記錄,包括 在重新啟動或變更日期之後。它最多會掃描 32 個印章,最多 提交兩項缺失的提交,且每次循環在重試上最多耗時 60 秒。一個 持久游標會輪流處理較舊的印章。保留的提交將遵循 現有的證明升級路徑。
重試不會重寫封印、更改其原始日期,也不會聲稱
日曆系統較早收到該封印。較晚的比特幣承諾仍屬較晚的外部
確認。缺失的證明仍為 none;待處理的證明則維持 pending 狀態,直至
驗證者獨立檢查為止。