TgWitness / 文档

已测试的内容 →

参考 / 证据

Telegram · 独立见证者

运行一个带有独立密钥和机器人的 Witness 实例,将签名后的检查点发布到频道中,并据此验证导出数据。

TgWitness / 文档 · 证据与验证

证据与验证

导出与验证 · 高可信度 · 面板指南

见证者会将已签名的检查点与收集器分开保存。它会检查 收集器的签名和日志连续性,使用自己的密钥对结果进行签名,并 将其发布到 Telegram 频道。请在单独的服务器上运行该程序,并确保该服务器对 收集器的见证端点仅具有只读访问权限。

技术结果包括保留的日志前缀、质询响应、签名检查、Merkle 包含/一致性检查以及签名的连续性结果。对于由其他保管方运行的见证者,请保留保管方信息及带有其指纹的密钥控制记录。独立的密钥和独立的保管描述的是部署的不同部分。验证器会报告第二个密钥保留了日志头部以及保留到哪条记录;保管方的密钥控制记录表明该密钥由谁持有。见证者日志是辅助检查;证据的最低要求是第三方时间。频道帖子增加了外部时间:Telegram 为每条公开帖子标注日期,验证器会自行读取这些日期。

流程图收集器 → 见证人 (签名检查点:记录条数 + 头部哈希值); 见证人 → Witness日志,自有密钥; 见证人 → Telegram 频道 (通过其自有机器人发布的签名帖子); 证据 ZIP → verify.py; Witness日志,自有密钥 → verify.py; Telegram 频道 → verify.py (t.me/s 页面实时阅读,或桌面版导出)收集器见证人Witness日志,自有密钥Telegram 频道证据 ZIPverify.py签名检查点:记录条数 +头部哈希值通过其自有机器人发布的签名帖子t.me/s页面实时阅读,或桌面版导出
图表转为文本
  1. 收集器 → 见证人 (签名检查点:记录条数 + 头部哈希值)
  2. 见证人 → Witness日志,自有密钥
  3. 见证人 → Telegram 频道 (通过其自有机器人发布的签名帖子)
  4. 证据 ZIP → verify.py
  5. Witness日志,自有密钥 → verify.py
  6. Telegram 频道 → verify.py (t.me/s 页面实时阅读,或桌面版导出)
本页内容

见证者保存的内容#

该工具具有 该工具从未
一个工作区的只读见证令牌 采集器的 Telegram 会话或 API 凭据
其专属的 Ed25519 密钥和日志 采集器的存储库、签名密钥或面板令牌
其专属的 Telegram 机器人令牌 消息内容:头部包含记录数量和哈希值

该令牌在更多工具→扩展功能→独立见证人中生成,仅显示一次,且仅以 SHA-256 形式存储。它仅开放一个端点:GET /api/witness/head,该端点返回一个新 签名的检查点,以及经过签名的无内容收集计数器和运行状态。 该令牌无法打开控制面板、读取消息内容或更改设置,且 该处不接受控制面板令牌。可在同一页面上撤销令牌。收集器会记录 新见证密钥开始检查的时间(witness.seen),并显示每个令牌的最后一次检查时间; 在 2.5 个间隔内未进行检查的见证将被标记为逾期。

新见证节点在每次投票时都会发送一个随机挑战; 捕获语句会在收集器签名下方重复该挑战。计数器 与确切的检查点绑定,并包含在签名的见证帖中。旧版头部 仍被独立见证节点接受。仅日志增长本身绝不会被计为新消息。

其检查和记录的内容#

每隔一段时间(默认间隔为 10 分钟),该工具会:

  1. 自行获取头部数据(收集器无法推送或跳过该数据);
  2. 验证收集器的签名、固定的收集器密钥(--collector-fingerprint, 或首个出现的密钥)、一个非递减计数,以及在未改变计数条件下未被修改的头部。 默克尔包含性证明和一致性证明用于验证不断增长的日志是否延伸了 保留的检查点。一旦连续性证明被使用,则拒绝移除它们;
  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 配置文件)。

在面板中打开更多工具→扩展功能→独立见证人→配置 。三个步骤包括 只读访问、您的频道和间隔,然后启动见证人。发布 策略、可选的 HTTP/SOCKS5 代理和自定义机器人 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 隧道之后,请仅通过 单独的 HTTPS 主机名(参考此 Caddy 示例)暴露范围限定后的见证端点。 此时,默认工作区使用 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 并复制其 URL。在 配置面板中,第 2 步选择“Discord Webhook · 您的频道”。在见证人主机上, 将该 URL 保存为 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 等待采集器和机器人 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 机器人 API 地址,例如本地机器人 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,这可防止“secret”出现在进程列表中。

配置文件中,选项名称使用下划线分隔,并包含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 仍会保留其日志。请将见证密钥指纹 (python -m tgwitness.witness fingerprint) 保存在其他地方。

多个工作区的公开验证页面#

python -m tgwitness.proof 该工具最多可同时管理 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 可选路由和机器人 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 ,并按 下文所述使用它。

验证#

在“证人”一侧,导出其日志:

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会检查见证者日志(链和签名),然后验证见证者所见到的每个 头部是否属于导出的日志:该计数处的记录必须具有完全 相同的哈希值。 若某个头部不匹配,则验证失败——说明在 见证者看到日志后,日志被修改了。该脚本还会报告导出后观察到的头部、见证者 记录的异常、失败的响应、导出中存在匹配检查点的时段 (“从 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,直到 验证者独立检查它们为止。