无需任何 CLI 的自动 Git 提交时间戳
大多数希望获得加密时间戳作为在先技术的团队最终都没能实现,而原因几乎从来不是技术层面的,而是运营层面的。时间戳习惯只有在有人记得在正确的时刻对正确的提交运行工具,并把收据存到审计员十八个月后能找到的地方时才有效。在截止日期的压力下,这种习惯往往最先被放弃。
本文讲的是彻底消除这种习惯。不是"如何更频繁地运行时间戳命令",而是如何让受监控仓库中的每一次提交都自动锚定到比特币区块链上,每晚执行,团队中无需任何人输入任何命令。如果你正在评估是学习原始协议还是使用托管的 GitHub App,我们在 OpenTimestamps vs Timestamp GIT:手动证明还是 GitHub App? 中单独讨论了这一权衡。这里我们假设你已经决定要采用自动化。
手动时间戳的陷阱(以及为什么你想摆脱它)
想象一下手动时间戳实际上是如何进行的:
- 有人完成了一个功能分支,然后想起来——通常是在事后——这个提交应该被打上时间戳。
- 他们运行一个工具,等待,然后拿回一个收据文件。
- 收据被重命名,放进
proofs/文件夹,提交,或者更糟,通过电子邮件发给经理。 - 接下来的四十个提交没人再这么做,因为冲刺变得忙碌了。
原始 OpenTimestamps CLI 确实存在,但那是硬核做法:它是一条面向专家的路径,你需要自己负责批处理、证明文件、日历交互和归档系统。它能用。但它依赖于一个人永远保持自律,而且它不会留下任何审计线索来解释为什么提交 4f9c1ab 有证明而提交 8d2e0f3 没有。
合规失败模式比不便更糟糕。一份有漏洞的在先技术记录是律师可以挑刺的记录。如果对方问"证明你的代码库在 3 月 14 日的样子",而你的回答是一张电子表格加上开发者的记忆,你在框架上就已经输了。手动流程也很难审计:没有一致的产物,没有规律的节奏,合规审查员也无法在不要求工程师重建自己历史的情况下确认覆盖率。
自动化的承诺在性质上不同,而非程度上不同:安装一次,从那一刻起,受监控仓库的每一次提交都会被指纹化并每晚锚定。无需学习 CLI,无需手动归档收据,开发者机器上无需安装任何东西。证明记录成为仓库的属性,而不是某人勤奋程度的属性。
一次性设置:安装 GitHub App 然后忘掉它
主要路径是 GitHub App。你将其安装在一个仓库或整个组织上,设置是真正一次性的——没有逐仓库脚本,没有开发者入职步骤。
标准模式(GitHub App)。 App 自动读取每个受监控仓库的 HEAD 提交哈希。GitHub 的权限模型不提供"仅提交哈希"的范围,因此 App 至少需要对源仓库的只读访问权限。它还需要对目标仓库的读写访问权限,因为证明写在那里:一个专用的时间戳分支,可以在与源相同的仓库中,也可以在一个单独的影子仓库中。
企业 ZK 模式。 一个 12 行的 GitHub Action 在你自己的基础设施上运行,只将提交哈希推送到 Timestamp GIT API。在这种模式下,服务完全不需要对源仓库的读取权限——只需要对目标仓库的读写权限来交付证明——你在工作流中安装该 Action。当出于政策原因源代码读取权限完全不可行时,或者当你的安全审查要求哈希源自你的边界内部时,选择此模式。当你想要绝对最少的活动部件时,选择标准模式。
| 标准(GitHub App) | 企业 ZK(GitHub Action) | |
|---|---|---|
| 源仓库访问 | 只读 | 无 |
| 目标仓库访问 | 读写 | 读写 |
| 哈希来源 | App | 你的 CI 运行器 |
| 设置工作量 | 安装 App | 安装 App + 添加 Action |
在两种模式下,开发者机器上都不安装任何东西。工程师完全像今天一样提交,整个流水线在服务器端运行。服务从不查看、复制或存储你的源代码——它只处理提交哈希。
如果你需要在自己的网络内运行整个系统,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 页面申请用于评估的限时演示许可证。我们在 使用 Docker Compose 自托管 Git 时间戳 中更深入地讨论了部署。
自动化流水线:从提交到比特币锚定
一旦安装了 App,以下是你无需参与就会发生的事情:
- 提交检测。 GitHub App 通过 webhook 获取新提交,或者你的 GitHub Action 将提交哈希推送到 API。只有哈希在移动。
- 哈希队列。 提交哈希进入内存键值存储,等待夜间批次。
- 午夜 cron 工作器。 每晚,一个工作器将所有待处理的哈希分组,为每个仓库写入一个清单文本文件,原生构建 Merkle 树,使用公共 OTS 日历创建 OpenTimestamps 证明,并将 Merkle 根锚定到比特币区块链中。
- 证明交付。 清单和
.ots收据文件被推回你的仓库——一个专用的时间戳分支或影子仓库——这样证明就与它们所描述的代码放在一起。
一个实用的时间说明:比特币确认需要几个小时,通常大约三个小时。因此周二做出的提交会在周三早上获得最终证明,而不是周二晚上。这是锚定到公共、不可变账本的代价,而且值得付出。
你不必凭空相信这一切。每个受监控仓库都有一个公共状态仪表板,显示证明寿命、最早锚定日期、每日规律性、每个锚定背后的比特币区块和交易数据,以及一个你可以用肉眼检查漏洞的日历热力图。同一页面提供可下载的审计 CSV 和 PDF 证书。验证本身发生在 /verification/{user}/{repo}/{date},它逐步遍历多级 Merkle 链——所有这些计算都在浏览器本地进行,所以没有人能看到你验证了什么。
对于 README,可嵌入徽章公开显示验证状态,任何人都可以点击徽章链接在网站上验证时间戳或下载 PDF 报告。
要将状态接入你自己的仪表板,公共 API 刻意保持简单:
# 最后锚定的比特币区块信息
curl -s https://timestampgit.dev/api/statusLast/acme/payments-api
# 已提交/已盖章的提交总数
curl -s https://timestampgit.dev/api/statusCount/acme/payments-api
# 组合摘要(Shields.io 徽章所消费的内容)
curl -s https://timestampgit.dev/api/statusSummary/acme/payments-api
当合规部门要求提供产物时,不要在周五下午 5 点点击 UI:
# 完整审计账本 CSV
curl -sL -o audit-acme-payments-api.csv \
https://timestampgit.dev/api/audit/acme/payments-api
# 特定日期的 PDF 证书
curl -sL -o certificate-2026-11-14.pdf \
https://timestampgit.dev/api/report/acme/payments-api/2026-11-14
徽章 URL 和可直接粘贴的 markdown 来自 /api/badgeLink/{user}/{repo}(需认证)。对于私有仓库,状态 URL 带有特定于你的服务器实例的加密 HMAC,因此只有授权用户才能读取它们。
监控与故障处理:让自动化保持诚实
你不关注的自动化是你不知道是否在工作的自动化。有三件事值得养成习惯。
关注漏洞,而不是错误。 如果夜间运行失败,系统会重试,待处理的哈希会留在内存队列中而不是被丢弃。但队列深度和重试是内部的;状态页面上的日历热力图才是你真正能读的东西。缺失的一天会立即在网格中显示为一个洞。
轮询并告警。 一个小的定时任务将最新状态负载与昨天的快照进行比较,会在审计员之前发现停滞的流水线:
import json, pathlib, requests
REPO = "acme/payments-api"
URL = f"https://timestampgit.dev/api/statusSummary/{REPO}"
snapshot = pathlib.Path("last-status.json")
r = requests.get(URL, timeout=30)
r.raise_for_status()
current = r.json()
previous = json.loads(snapshot.read_text()) if snapshot.exists() else None
if previous == current:
print("WARNING: status unchanged since last poll - check the repo status page")
else:
print("new anchor data:", json.dumps(current))
snapshot.write_text(json.dumps(current, indent=2))
在 CI 中每小时运行一次,或者在 cron 窗口之后每天运行一次,并将警告路由到人们会看的地方。
围绕确认延迟规划审计。 由于锚定到比特币在 cron 工作器运行后需要几个小时,"给昨晚发布的所有内容打时间戳,我十分钟内需要证书"不是任何人能满足的请求。给合规部门一个简单的规则:第 N 天的证明在第 N+1 天之前最终确定。
故障处理中令人安心的部分是,如果服务完全不可用会发生什么。验证不需要我们。.ots 收据文件可以使用标准 OpenTimestamps 验证工具离线对照比特币区块链进行检查,因为证明只依赖于 SHA-256 和比特币区块数据——没有专有技术,没有锁定。即使供应商消失了,证明依然成立。
无接触时间戳的最佳实践
- 尽早且频繁地提交。 每次提交都会自动被指纹化,因此密集的提交历史会产生密集的在先技术记录。在专利申请前一晚将一个月的压缩成一个提交,你得到的是一个锚定而不是两百个。
- 选择符合你安全姿态的模式。 如果源仓库读取权限不可行,使用企业 ZK 模式:只有提交哈希离开你的基础设施,由 GitHub Action 推送。
- 按计划导出审计账本和证书。 合规档案不应依赖于某人记得一个下载链接。每月访问
/api/audit/{user}/{repo},对于里程碑日期访问/api/report/{user}/{repo}/{date},并将结果存储在你的法律产物所在的地方。 - 将徽章放入你的 README。 除了向客户发出的信号之外,实时验证徽章是对"我们独立开发了这个"主张的廉价威慑。
- 将证明保存在它们自己的分支或影子仓库中。 每日证明提交落在专用的时间戳分支中,可以保持你的主历史可读,同时将证据附加到同一仓库。
- 写下流程。 对于审计员,记录谁安装了 GitHub App、哪些仓库受监控以及时间戳分支所在的位置。数学是可验证的;保管链仍然需要一段文字。
常见问题
我需要在开发者机器上安装任何软件吗?
不需要。Timestamp GIT 是一个托管服务,通过 GitHub App 完全在服务器端运行。开发者只需像往常一样提交;不需要 CLI 工具或本地安装。
提交被打上时间戳需要多长时间?
提交每晚批量处理并锚定到比特币。比特币确认通常需要大约 3 小时,因此证明通常在夜间 cron 运行后几小时内可用。
我可以在没有服务的情况下验证证明吗?
可以。你会收到一个不可变的 .ots 收据文件,可以使用标准 OpenTimestamps 工具对照比特币区块链离线验证。证明是供应商无关的,仅依赖于 SHA-256 和比特币区块数据。
如果我使用私有仓库怎么办?
GitHub App 适用于私有仓库。私有仓库的状态 URL 包含特定于你的服务器实例的加密 HMAC,因此只有授权用户才能查看状态。
结论
在先技术记录的全部价值在于它在你需要时存在,这意味着它不能依赖于人类记住一个命令。安装一次 GitHub App,受监控仓库中的每一次提交都会被排队、在午夜批量处理、Merkle 根化并锚定到比特币——证明被推回你拥有的分支,有一个你可以检查的状态仪表板,以及为审计员准备的 CSV 和 PDF 导出。
如果你一直没有为代码打时间戳的原因是因为它看起来总是件苦差事,那个原因刚刚消失了。从 timestampgit.dev 开始——连接一个仓库,让第一批夜间批次运行,第二天早上查看日历热力图。
相关文章
- OpenTimestamps vs Timestamp GIT:手动证明还是 GitHub App?
- 使用 Docker Compose 自托管 Git 时间戳
- 加密在先技术:初创公司抵御专利流氓的盾牌