# Telegram · 獨立見證人

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

請使用具備專屬金鑰與機器人的「Witness」執行程序，將簽署過的檢查點發佈至頻道，並據此核對匯出資料。

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

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

請使用具備專屬金鑰與機器人的「Witness」執行程序，將簽署過的檢查點發佈至頻道，並據此核對匯出資料。

[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/evidence/)

![證據與驗證](https://phishdestroy.io/tgwitness/assets/chapter-evidence.svg?v=e49c65feab6c)

[匯出與驗證](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/evidence/) · [高可信度](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/high-assurance/) · [面板指南](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/panel/#extras)

見證者會將已簽名的檢查點與收集器分開保存。它會檢查 收集器的簽名與日誌連續性，使用自身的金鑰對結果進行簽名，並 將其發佈至 Telegram 頻道。請在具備對 收集器見證端點唯讀存取權限的獨立伺服器上執行此工具。

技術結果包括保留的日誌前綴、挑戰回應、簽章檢查、Merkle 包含/一致性檢查，以及簽署的連續性結果。對於由其他保管方營運的見證者，請保留保管方資訊及附有其指紋的金鑰控管記錄。分開的金鑰與分開的保管描述的是部署的不同部分。驗證器會回報第二把金鑰保留了日誌頭部，以及保留到哪一筆記錄；保管方的金鑰控管記錄顯示該金鑰由誰持有。見證者日誌是輔助檢查；證據的最低要求是第三方時間。頻道貼文增加了外部時間：Telegram 為每則公開貼文標註日期，驗證器會自行讀取這些日期。

流程圖 · 收集器 → 見證者 (簽名檢查點：記錄數 + 頭部雜湊值); 見證者 → Witness 日誌，自有金鑰; 見證者 → Telegram 頻道 (透過其自有機器人發布的簽名貼文); 證據 ZIP 檔案 → verify.py; Witness 日誌，自有金鑰 → verify.py; Telegram 頻道 → verify.py (t.me/s 頁面即時閱讀，或桌面版匯出) · 收集器 · 見證者 · Witness 日誌，自有金鑰 · Telegram 頻道 · 證據 ZIP 檔案 · verify.py · 簽名檢查點：記錄數 + · 頭部雜湊值 · 透過其自有機器人發布的簽名貼 · 文 · t.me/s · 頁面即時閱讀，或桌面版匯出

**圖表轉為文字**

1. 收集器 → 見證者 (簽名檢查點：記錄數 + 頭部雜湊值)
2. 見證者 → Witness 日誌，自有金鑰
3. 見證者 → Telegram 頻道 (透過其自有機器人發布的簽名貼文)
4. 證據 ZIP 檔案 → verify.py
5. Witness 日誌，自有金鑰 → verify.py
6. Telegram 頻道 → verify.py (t.me/s 頁面即時閱讀，或桌面版匯出)

**本頁內容**

- [見證者保存的內容](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/witness/#what-the-witness-holds)
- [其檢查與記錄的內容](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/witness/#what-it-checks-and-records)
- [執行見證](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/witness/#run-a-witness)
- [多個工作區的公開證明頁面](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/witness/#public-proof-page-for-several-workspaces)
- [驗證](https://phishdestroy.io/tgwitness/zh-Hant/docs/reference/witness/#verify)

## 見證者保存的內容

| 該證據日誌具備 | 該證人從未 |
| --- | --- |
| 適用於單一工作區的唯讀**見證代幣** | 資料收集者的 Telegram 會話或 API 憑證 |
| 其專屬的 Ed25519 金鑰與日誌 | 收集器的儲存庫、簽名金鑰或面板憑證 |
| 專屬的 Telegram 機器人代幣 | 訊息內容：開頭為記錄數量及雜湊值 |

該憑證是在「**更多工具」→「進階功能」→「獨立見證者**」中建立，僅顯示一次，且僅以 SHA-256 格式儲存。它僅開啟一個端點：`GET /api/witness/head`，該端點會返回一個剛 簽署的檢查點，以及經簽署的無內容收集計數器和運作狀態。 該憑證無法開啟控制面板、讀取訊息內容或變更設定，且 該處不接受控制面板憑證。可在同一頁面撤銷憑證。收集器會記錄 新見證金鑰開始檢查的時間（`witness.seen`），並顯示每個憑證的最後檢查時間； 若見證金鑰在 2.5 個間隔內未進行檢查，則會被標記為逾期。

新見證者會在 每次投票時發送一個隨機挑戰；擷取陳述會於收集器簽名下方重複該挑戰。計數器 與確切的檢查點綁定，並包含在簽名的見證貼文中。舊版見證者 仍可被獨立見證者接受。僅日誌的增長絕不會被計為新訊息。

## 其檢查與記錄的內容

每隔一段時間（預設為 10 分鐘），Witness 會：

1. 自行擷取頭部資料（收集器無法推送或跳過該部分）；
2. 驗證收集器的簽名、固定收集器金鑰（`--collector-fingerprint`， 或首個偵測到的金鑰）、一個非遞減的計數，以及在未變更計數下未變更的頭節點。 Merkle 包含性與一致性證明可驗證，日益增長的日誌是否延伸至 保留的檢查點。一旦使用過連續性證明，便會拒絕移除該證明；
3. 將一份經簽署的記錄附加至其自身的日誌中：`witness.anchor`，狀態為 `ok`、 `key_changed`、`rollback`（記錄數量少於先前）、`fork`（長度相同，但 標頭不同）或 `invalid`（回應未能通過驗證），或當 收集器未回應時為 `witness.no_response`；
4. 將結果發佈至頻道，並附有簽名，包含「無回應」的情況，只要 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://phishdestroy.io/tgwitness/zh-Hant/docs/reference/deployment/)章節中的 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://github.com/phishdestroy/TgWitness/blob/main/deploy/Caddyfile.witness.example)，僅在 獨立的 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](https://core.telegram.org/bots/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](https://github.com/phishdestroy/TgWitness/blob/main/deploy/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](https://github.com/phishdestroy/TgWitness/blob/main/deploy/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` 狀態，直至 驗證者獨立檢查為止。
