Timestamp GIT

← All posts

2026-10-22

自动化 Git 时间戳:将提交锚定到比特币

自动化 Git 时间戳:将提交锚定到比特币
timestamp git blockchain proof

自动化 Git 时间戳:将提交锚定到比特币

如果你的在先技术保护依赖于有人在每次提交后记得运行某个工具,那你拥有的不是在先技术保护——而是一个习惯。而习惯会在审计前一周、发布冲刺期间,或者那个“总是做这件事”的人换团队之后立刻崩塌。

手动打时间戳有一个可预见的失败循环。你提交,然后你记得去打戳。你把收据复制到某个不会丢的地方。你明天再做一遍,后天再做一遍,对每一个重要的仓库都如此——而当你进入分支密集的冲刺阶段时,这个循环会悄无声息地停止。一个仓库还能撑住。五个仓库、每个三个贡献者就不行了。

本文讲的是如何彻底消除这个循环:在比特币上进行自动化 Git 时间戳,其中唯一重复的动作就是你本来就要做的提交。

你可以用笨办法,自己运行 OpenTimestamps 工具并照看收据文件。Timestamp GIT 的存在就是为了让你不必这么做。它是一个托管服务,把协议完全隐藏起来:安装一次 GitHub App,被监控仓库的每一次提交都会每晚自动锚定到比特币。没有 CLI 工具,没有协议命令,没有每日清单。安装过程本身请参见 GitHub App 区块链时间戳设置:安装一次,永久打戳——本文关注的是安装之后会发生什么。

你可以消除的重复性手动任务

在决定采用自动化之前,值得明确指出究竟从你的一周中移除了什么:

  • 每次提交的仪式。 每一次值得留证的提交之后都必须运行某些东西。这意味着每一次提交、永远,都需要人在循环中。
  • 收据散落。 证明文件最终散落在个人文件夹、共享驱动器或 Slack 线程里。六个月后,没人能把收据对应到某个日期或某个仓库。
  • 覆盖衰减。 你保护了旗舰仓库。内部工具仓库、客户端库、商业秘密服务——没人给它们打戳,而这些恰恰经常是争议中真正重要的。
  • 静默缺口。 漏掉一天在你需要证明之前是看不见的,而那正是发现时间线有洞的最糟糕时刻。

这里“自动化了什么”的含义是狭窄而具体的。你在想要监控的仓库上安装一次 GitHub App。从那时起,每一次提交都会被检测、批处理,并每晚锚定到比特币区块链,无需开发者做任何操作。开发者完全像今天一样继续提交。他们的机器上没有任何东西需要安装,没有 pre-commit 钩子,没有新工作流要学。

这就是流程与仓库后台属性之间的区别。

一次性设置:安装 GitHub App 然后忘掉它

Timestamp GIT 提供两种连接仓库的方式,两者都是一次性配置。

标准模式(GitHub App)。 在你想监控的仓库上安装 GitHub App。它会自动只读取每个被监控仓库的 HEAD 提交哈希。证明会被写入一个专用 Git 分支——既可以与源仓库相同,也可以放在单独仓库中。

权限模型值得直白地理解,因为它比人们预期的要少:

  • 对源仓库的只读访问。 GitHub 权限系统没有“仅提交哈希”这一范围,因此只读是 App 为了看到 HEAD 哈希所能请求的最低权限。
  • 对目标仓库的读写访问,清单和收据文件会被推送到那里。

企业 ZK 模式。 一个 12 行的 GitHub Action 在你自己的基础设施上运行,只把提交哈希推送到 Timestamp GIT API。该配置只需要对目标仓库的读写访问——不需要对源仓库的读访问,你的源代码永远不会离开你的环境。

无论选择哪种模式,团队的开发者体验都是一样的:开发者机器上无需安装任何东西,任何人分支、提交或合并的方式都不变。

如果你需要自托管。 为了最高安全性或气隙环境,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 并配置实例。许可、演示许可证申请表单以及完整的自托管演练见 自托管 Git 时间戳:Docker 设置与许可证指南。

自动化流水线:从提交到比特币锚定

连接之后,流水线无需你干预即可运行。以下是实际顺序。

1. 提交检测。 要么 GitHub App 通过 webhook 检测到新提交,要么——在企业 ZK 模式下——你的 GitHub Action 把提交哈希推送到 API。

2. 哈希队列。 提交哈希进入内存键值存储以进行批处理。除此之外不存储任何东西,因为没有发送任何其他东西。

3. 午夜 cron worker。 每晚,一个 worker 会:

  • 将所有待处理哈希分组
  • 创建按仓库划分的清单文件(.txt)
  • 原生构建 Merkle 树
  • 使用公共 OTS 日历创建 OpenTimestamps 证明
  • 将 Merkle 根锚定到比特币区块链

4. 证明交付。 清单和 .ots 收据文件会被推送回你的仓库,放在专用的 timestamps 分支或影子仓库中。

整个流程如下:

commit ──▶ hash queue ──▶ midnight cron ──▶ Merkle root ──▶ Bitcoin block
                                                 │
                                                 └──▶ manifest.txt + .ots receipt
                                                              │
                                                              ▼
                                                  timestamps branch / shadow repo

在企业 ZK 模式下,你的 GitHub Action 与 ZK Commit API 通信,该 API 使用 API 为你的仓库返回的签名 URL 中的 HMAC 进行认证:

# The signed URL (and its HMAC) is returned by the API for your repo.
# {target} is the destination repo, {hash} is the HMAC from that URL.
curl -X POST \
  "https://timestampgit.dev/api/timestamp/acme/payments-api/timestamps/<hmac>/<commitHash>/<commitId>"

时间预期。 比特币确认需要几个小时——通常约 3 小时——所以证明写入会在夜间运行后几小时完成,而不是午夜整点。如果你在 00:05 查看 timestamps 分支却什么也没看到,那是预期行为,不是失败。

监控与故障处理

你无法观察的自动化,与已经停止工作的自动化无法区分。Timestamp GIT 暴露了公共状态端点,因此你无需登录即可观察流水线:

# Last anchored Bitcoin block
curl -s https://timestampgit.dev/api/statusLast/acme/payments-api

# Total committed / stamped commit count
curl -s https://timestampgit.dev/api/statusCount/acme/payments-api

# Combined summary (Shields.io friendly)
curl -s https://timestampgit.dev/api/statusSummary/acme/payments-api

徽章。 可嵌入的验证徽章可用于你的 README,因此任何浏览仓库的人都能看到锚定状态。任何人都可以点击徽章链接来验证时间戳——有一个专用查看器和一个 PDF 报告。私有仓库也受支持:其状态 URL 会附加一个特定于服务器实例的加密 HMAC,因此只有授权用户才能看到状态。

仓库状态仪表盘。 在 /status/{user}/{repo} 你可以获得证明寿命、最早锚定日期、每日规律性、比特币区块与交易数据,以及日历热力图——这是以视觉方式发现覆盖缺口的最快方法。

审计与报告端点。 当你需要证据而不是仪表盘时:

# Full audit ledger as CSV
curl -sO https://timestampgit.dev/api/audit/acme/payments-api

# PDF certificate for one specific date
curl -sO https://timestampgit.dev/api/report/acme/payments-api/2026-10-21

当某一夜看起来缺失时,按以下顺序排查:

  1. 检查 statusLast 和 statusCount。如果最后一次锚定比预期旧了几个小时,确认可能仍在进行中。
  2. 确认 GitHub App 仍然拥有仓库访问权限。卸载的 App、被撤销的权限或重命名的仓库都会静默停止检测。
  3. 在企业 ZK 模式下,检查你这边 Action 的运行历史——推送到 API 是唯一可能在本地断开的环节。
  4. 在比特币确认完成后再重新检查,不要在此之前就假设任何东西丢失了。

自动化时间戳的最佳实践

  • 监控每一个重要的仓库,而不仅仅是旗舰仓库。覆盖范围是自动化的全部价值;只保护一个仓库仍然会让你其余的工作暴露在外。
  • 保持提交有意义。 自动化会为你提交的内容打时间戳,因此提交卫生仍然塑造着你被锚定的历史所讲述的故事。一百个“wip”提交能证明的东西,比一段干净、描述清晰的历史要少。
  • 把徽章放进 README,并将审计 CSV 和按日期的 PDF 报告与你的知识产权记录放在一起。这些产物才是你交给审计师或对方律师的东西。
  • 在关键时独立验证。 下载 .ots 文件,并用标准 OpenTimestamps 工具对照比特币进行检查。该证明在设计上就是厂商无关的——它只使用 SHA-256 和比特币区块数据。分步演练见 如何在本地验证比特币时间戳证明。
  • 记住零知识保证。 只有提交哈希被打戳,源代码永远不会,因此跨所有仓库自动化完全不会扩大你的暴露面——无论你有一个仓库还是五十个,哈希都是一样的。

常见问题

自动化 Git 时间戳会读取或存储我的源代码吗?

不会。Timestamp GIT 只处理提交哈希。在标准模式下,GitHub App 读取 HEAD 提交哈希;在企业 ZK 模式下,你基础设施上的 GitHub Action 只把哈希推送到 API。在 ZK 模式下,你的源代码永远不会离开你的环境,也永远不会被该服务复制或存储。

我提交后多久比特币锚定会被确认?

提交会由夜间 cron worker 批处理并锚定。比特币确认需要几个小时,通常约 3 小时,因此 .ots 收据和清单文件会在夜间运行后几小时出现在你的 timestamps 分支或影子仓库中。

如果 Timestamp GIT 关闭,我的证明会怎样?

证明仍然有效。它们仅通过 OpenTimestamps 协议依赖 SHA-256 和比特币区块数据,因此任何人都可以下载 .ots 文件,并使用标准 OpenTimestamps 工具对照比特币区块链独立验证——没有专有技术,没有锁定。

我可以在私有仓库上使用自动化时间戳吗?

可以。私有仓库受支持,状态 URL 会附加一个特定于服务器实例的加密 HMAC,因此只有授权用户才能查看状态。一旦授予访问权限,公共验证徽章和状态仪表盘的工作方式相同。

结论:设置一次,永久证明

这里的转变在投入上很小,在结果上很大。你不再维护一项每日杂务,而是开始拥有仓库的一项属性:每一次提交,每晚自动锚定到比特币,并附带一份你可以交给律师、审计师或法庭的收据。证明嵌入在比特币中,可直接用于法庭,任何人都可以用非专有工具验证——而且这一切都由后端的 Timestamp GIT 驱动,而不是由你的开发者驱动。

如果你的团队完全无法使用托管服务,Docker 自托管选项通过上面展示的 Compose 配置覆盖最高安全性和气隙环境。

今天就在你的第一个仓库上安装 GitHub App,让流水线今晚运行。明天,检查 statusLast——你将拥有一个否则要花一年时间试图记得去创建的锚定。

相关文章

EU label: AI-generated content