为每次 Git 提交自动添加比特币时间戳
手动添加时间戳和手动备份有着相同的失败模式:在你忙碌的那一周之前,它一直运行完美。而你忙碌的那一周,恰恰就是你发布那个日后需要证明自己确实发布过的功能的那一周。
本文要讲的,就是把人从这个循环中移除。不是"记得在合并前打时间戳",也不是发布运行手册里的一个检查项——而是一次性安装,之后受监控仓库中的每一次提交都会自动变成经 Merkle 批量处理、锚定到比特币的证明,每晚自动运行,无论团队里有没有人想着知识产权保护这件事。
如果你还在决定密码学先有技术证明对你的情况是否重要,请参阅申请前证明先有技术:创始人指南。本文假设你已经做出了决定,现在希望它自动运行。
手动时间戳的陷阱(以及为什么自动化更胜一筹)
手动操作看起来简单得具有欺骗性。实际上,手动工作流意味着团队中必须有人:
- 在每次有意义的提交之后记得打时间戳——赶在分支被重写、压缩或强制推送之前。
- 在本地管理密钥材料和证明文件,放在能经受笔记本损坏和人员流动的地方。
- 把生成的收据存放在持久、有版本控制、两年后尽职调查时还能找到的地方。
- 对每个仓库的每次提交都重复这一过程,永远如此。
最后一条正是手动流程的致命之处。覆盖率会变得不一致,而不一致的覆盖率比听起来更糟:在纠纷中,证据链上的缺口会招来这样的论点——这一次提交,也就是真正重要的那一次,是个例外。周五下午一次忘记推送,就能把一条干净的时间线变成一个问号。
底层的 OpenTimestamps 协议设计得确实很好,你可以用原始命令行工具和手动比特币锚定自己驱动它——但那是艰难的方式,花自己的钱、自己的时间。对于一个每天发布、没有专职加密人员的团队来说,那是一个伪装成安全控制的维护项目。
自动化之所以胜出,是因为它把一项反复出现的决策变成了一次性配置。安装一次 GitHub App,从那一刻起,受监控仓库的每一次提交都会被捕获、排队、批量处理、锚定,并归档回你的仓库,开发者无需触碰任何东西。
一次性设置:安装 GitHub App,然后忘掉它
设置是本文最短的部分,而这正是重点。
- 安装 Timestamp GIT GitHub App。 选择一个仓库,或授权给整个组织——每个受监控的仓库都会获得自己独立的证明。
- 选择源和目标。 App 从源仓库读取提交哈希,并将证明写入目标仓库,可以是同一仓库中专门的
timestamps分支,也可以是一个独立的影子仓库。 - 确认权限。 标准模式需要对源仓库的只读访问权限,因为 GitHub 的权限模型没有"仅提交哈希"这一范围。需要对目标仓库的写访问权限,以便将证明提交回去。这就是全部的权限范围。
开发者机器上什么都不用安装。没有 CLI 工具,没有 pre-commit 钩子,没有要分发的密钥文件,新员工也没有任何入门步骤。开发者照常运行 git commit 和 git push。
对于不希望托管服务对源代码有任何读取权限的组织,还有 Enterprise ZK 模式:一个简短的 GitHub Action(12 行)在你自己的基础设施内运行,只把提交哈希发送到 API,因此源代码永远不会离开你的环境。在这种模式下,App 不需要对源仓库的读访问权限——你只需安装该 Action。大多数团队从标准托管模式开始,把 ZK 模式作为最敏感仓库的选项。完整的权限说明见通过一次 GitHub App 安装设置 IP 保护。
自动化流水线内部:从提交到比特币锚定
安装完成后,流水线按自己的时间表运行。以下是从你的 git push 到可验证证明之间发生的事情:
- 提交检测。 GitHub App 通过 webhook 获取新提交。在 Enterprise ZK 模式下,由你的 GitHub Action 将提交哈希推送到 API。
- 哈希队列。 提交哈希进入内存键值存储,等待夜间批次。注意这里到达的是什么:哈希,而不是代码。
- 午夜 cron worker。 一个 worker 醒来,将所有待处理的哈希分组,并为每个仓库写一个清单
.txt文件。 - 构建 Merkle 树。 worker 在当天的批次上原生构建一棵 Merkle 树,然后针对公共 OTS 日历生成 OpenTimestamps 证明。
- 比特币锚定。 Merkle 根被锚定到一个比特币区块中。确认通常需要约三个小时,因此证明交付会在批次运行几小时后进行。
- 证明交付。 清单和
.ots收据文件会自动提交回你的目标仓库。
这个设计有两个特性比具体机制更重要:
- 构造上零知识。 服务从不查看、复制或存储你的源代码。它处理的是提交哈希和 Merkle 根。你的仓库状态永远不会进入流水线。
- 供应商独立性。 证明仅依赖 SHA-256 和比特币区块数据。如果 Timestamp GIT 明天消失,你仓库中的收据仍可使用标准 OpenTimestamps 工具对照比特币区块链进行检查。日常工作中,你会改用验证页面或 API——参见如何验证代码的比特币时间戳证明。
监控与故障处理:确保每次提交都被锚定
你不监控的自动化,只是一个充满希望的 cron 任务。Timestamp GIT 暴露了足够的接口面,让覆盖率变得可观察。
状态仪表盘。 每个受监控的仓库都有一个公共状态页,位于 https://timestampgit.dev/status/{user}/{repo},显示证明存续时间、最早锚定日期、每日规律性、比特币区块和交易数据、已锚定日期的日历热图,以及可下载的审计导出。
可嵌入徽章。 Shields.io 徽章可以直接放进你的 README,连接仓库后即可生成 markdown 片段。任何人都可以点击查看并公开验证时间戳。
用于自定义告警的 API。 从你自己的工具中轮询状态并核对计数:
# Latest anchored Bitcoin block for a repo
curl -s https://timestampgit.dev/api/statusLast/acme/payments-api | jq
# Total committed / stamped commit count
curl -s https://timestampgit.dev/api/statusCount/acme/payments-api | jq
# Combined summary (what the badge uses)
curl -s https://timestampgit.dev/api/statusSummary/acme/payments-api | jq
一个最小的夜间检查,在缺口变成证据问题之前将其标记出来:
import datetime, requests
REPO = "https://timestampgit.dev/api"
USER, SLUG = "acme", "payments-api"
summary = requests.get(f"{REPO}/statusSummary/{USER}/{SLUG}", timeout=30).json()
last = requests.get(f"{REPO}/statusLast/{USER}/{SLUG}", timeout=30).json()
# Alert if nothing has been anchored in the last 48 hours
print("summary:", summary)
print("last anchor:", last)
把它指向你的告警渠道,你就闭环了——漏掉的一天会变成一条通知,而不是尽职调查时才发现的问题。
故障场景。 webhook 会丢失,日历偶尔会宕机,网络会抖动。由于哈希是放在队列中而不是内联打时间戳,未锚定的哈希只会滚入下一个夜间批次。什么都不会丢失,只是被推迟了。可见的症状是热图上缺失的一天或 statusLast 值停滞,而这正是上述检查能捕获的。
合规导出。 对于审计,可以拉取完整账本为 CSV 或按天的 PDF 证书:
curl -sO https://timestampgit.dev/api/audit/acme/payments-api
curl -sO https://timestampgit.dev/api/report/acme/payments-api/2026-11-22
私有仓库会在其状态 URL 后附加加密的 HMAC,因此只有授权用户才能读取其状态——HMAC 特定于服务器实例。
自动时间戳的最佳实践
- 关注 timestamps 分支,而不仅仅是仪表盘。 新的清单和
.ots文件出现,是交付端到端成功的真实依据。 - 尽可能为证明使用专门的目标仓库。 它能让你的源代码历史保持干净,并让证据易于交给律师,而无需导出你的代码库。
- 定期验证,而不是只验证一次。 安排每季度对照公共验证页面或
/api/verify/{user}/{repo}/{date}进行检查。所有验证计算都在浏览器本地进行——没有人能看到你验证了什么。 - 把覆盖率锚定在你的流程中,而不是你的记忆中。 如果某个仓库对业务至关重要,就在整个组织范围安装 App,而不是逐个仓库安装;选择性安装的失败模式是,有一个仓库没人记得去接入。
- 让部署方式匹配你的威胁模型。 对于气隙或最高安全环境,Timestamp GIT 以自托管 Docker 镜像运行。一个快速开始的 Docker Compose 配置如下:
services:
timestampgit:
image: rue1401/timestampgit:prod
ports:
- "8080:8080"
volumes:
- ./data:/app/data
restart: unless-stopped
valkey:
image: valkey/valkey:8
restart: unless-stopped
docker compose pull
docker compose up -d
docker compose logs -f timestampgit
实例可通过 http://localhost:8080 访问,首次启动向导会引导你连接 GitHub App。可通过 Docker License 页面上的请求表单(姓名、公司、邮箱、可选电话)获取限时演示许可证。
常见问题
我需要开发者的机器上安装任何软件吗? 不需要。Timestamp GIT 完全通过 GitHub App 或 GitHub Action 工作。开发者照常提交;自动化处理其余一切。
如果提交是在夜间截止时间之后做出的,会怎样? 它会被纳入下一晚的批次。系统会排队所有待处理的哈希,并将它们一起锚定。
我可以为多个仓库自动添加时间戳吗? 可以。你可以在多个仓库或整个组织上安装 GitHub App,每个仓库都会获得自己的证明。
我如何验证一次提交已被添加时间戳? 你可以使用公共验证页面或 API,对照比特币区块链检查 Merkle 证明。徽章也会显示状态。
如果我在一天内推送多次提交,会怎样? 它们都会被收集到当天的批次中,折叠进一棵 Merkle 树,并一起锚定在一个比特币交易下。你仍然会获得每个仓库的清单,因此单个提交哈希在批次内仍可追溯。
我可以为私有仓库的提交添加时间戳吗? 可以——私有仓库在 Pro Agency 计划($49/月)和 Enterprise ZK($199/月,GitHub Actions)上受支持。公共仓库在 Open Source 层级免费。
一次提交被锚定需要多长时间? 通常在夜间批次运行后几小时。比特币确认本身通常需要约三个小时,因此证明会在午夜后几小时落到你的仓库中。
没有 Timestamp GIT,证明还能验证吗? 可以。证明仅依赖 SHA-256 和比特币区块数据,因此可以独立对照区块链进行检查——没有专有技术,也没有锁定。
结论
先有技术证明的价值来自覆盖率,而覆盖率来自自动化。一个依赖人记得去运行某些东西的时间戳流程必然会有漏洞,而漏洞正是对方律师要找的东西。
Timestamp GIT 为你处理 OpenTimestamps 协议:安装一次 GitHub App,让夜间 cron 将每次提交锚定到比特币,关注徽章和状态端点,并把 .ots 收据保存在你控制的仓库中。设置只需几分钟;之后,唯一持续的任务就是瞥一眼那条本不该触发的告警。
从公共仓库上的免费 Open Source 层级开始,或在 Pro Agency 上连接一个私有仓库,让第一批今晚就运行。想更全面地了解这相比自行搭建的成本,请阅读代码时间戳成本对比:托管 vs 自建。