Timestamp GIT

← All posts

2026-10-26

为每次 GitHub 提交自动进行比特币时间戳认证

为每次 GitHub 提交自动进行比特币时间戳认证
timestamp git blockchain proof

为每次 GitHub 提交自动完成比特币时间戳

你已经认定自己的提交值得拥有一份密码学意义上的存在性证明。很好。接下来是枯燥的部分:明天再做一遍,后天再做一遍,为你团队接触的每一个仓库都做一遍。

大多数时间戳尝试正是在这里悄无声息地消亡。原因并非想法本身有错,而是这套手工琐事——批量收集提交哈希、提交给日历服务、盯着证明文件、再把它提交回去——无法在真实的冲刺节奏中存活下来。如果你想为 GitHub 仓库自动化区块链时间戳,时间戳就必须成为 git push 的副作用,而不是某个人记得在周五去做的一项任务。

本文端到端地介绍自动化路径:一次安装、一条你永远不用碰的夜间流水线,以及能告诉你证明是否真正落到比特币上的监控。

为什么手动时间戳无法规模化

给提交打时间戳的笨办法就是每次都手动操作。你需要负责:

  • 判断哪些提交值得打时间戳(它们全都值得,这正是问题所在)。
  • 自己批量处理哈希,以免为每个提交创建一笔比特币交易。
  • 提交到公共日历,并跟踪待处理的证明直到确认。
  • 把生成的证明文件存放到持久位置,并与正确的提交关联。
  • 明天再把这一切重复一遍,而且在每次强制推送、热修复和合并列车之后都要重复。

即使写成脚本,这也是一份兼职工作。总得有人负责脚本、cron 运行器、存储位置,以及处理“上周的证明为什么不见了”这类事故。而一旦这个人换了团队,流水线就会腐烂。

原始的 OpenTimestamps 协议确实很优雅——你可以在 OpenTimestamps 替代方案:为每次提交提供托管的 GitHub App 中了解它的工作原理。本文讨论的是另一个问题:让它无人值守地永远运行下去。

目标是设置后即忘:对受监控仓库的每次提交每晚都会被锚定,无需开发者干预,也无需在任何人的笔记本电脑上安装任何东西。

一次性设置:安装 GitHub App

Timestamp GIT 是一项围绕 GitHub App 构建的托管服务。设置只需几分钟,每个账户或组织只需做一次。

1. 安装应用。 在 Timestamp GIT 仪表盘中,将 GitHub App 安装到你的个人账户或组织上。

2. 选择仓库。 选择所有仓库或特定的子集。之后可以调整选择,无需重新安装。

3. 确认权限。 权限模型被刻意设计得很窄:

访问权限 范围 原因
只读 源仓库 GitHub 权限系统没有“仅提交哈希”的范围,因此应用需要读取权限才能看到 HEAD 提交哈希
读写 目标仓库 证明会以清单文件和 .ots 收据的形式写回专用分支或影子仓库

4. 走开即可。 没有 YAML 要添加,没有密钥要轮换,没有 CLI 要安装。你的开发者继续像现在一样提交;应用在后台响应 webhook。

如果你的仓库是公开的,开源层级开箱即用地覆盖了这一点。私有仓库从 Pro Agency 层级开始——定价明细介绍了哪个层级适合哪种团队形态。

更严格的替代方案:Enterprise ZK 模式

标准模式需要对你源仓库的读取权限。如果你的政策禁止这样做——或者你只是不想让任何第三方能够读取你的代码——Enterprise ZK 模式会反转方向。你的这一侧不再拉取,而是推送:一个 12 行的 GitHub Action 在你自己的基础设施上运行,只把提交哈希发送到 Timestamp GIT API。你的源代码永远不会离开你的环境,服务也完全不需要对源仓库的读取权限。只有目标仓库(写入证明的地方)需要写权限。

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

以下是设置完成后发生的事情,你什么都不用做。

1. 提交检测。 新提交通过 GitHub App 的 webhook(标准模式)或通过你的 GitHub Action 推送的哈希(Enterprise ZK 模式)到达。

2. 哈希队列。 提交哈希进入内存键值存储,等待夜间批次。注意那个存储里没有什么:你的代码。只有哈希。

3. 午夜 cron 工作进程。 每晚一次,一个工作进程会:

  • 将所有待处理的哈希分组。
  • 构建每个仓库的清单(.txt)。
  • 在批次上原生构建 Merkle 树。
  • 针对公共 OTS 日历生成 OpenTimestamps 证明。
  • 将 Merkle 根锚定到比特币区块链。

4. 证明交付。 清单和 .ots 收据文件被推送回你的仓库——要么放在与代码并行的专用 timestamps 分支上,要么放在单独的影子仓库中。

时间预期。 比特币不会立即确认。锚定交易通常在大约三小时内确认,因此预计证明会在 UTC 午夜后几小时出现。如果你在 UTC 00:05 检查而什么都没看到,那并没有出问题。

用于自定义工作流的 API 接口

流水线自行运行,但 API 让你可以把证明数据接入自己的工具。所有端点如注明所示均需认证。

# Last anchored Bitcoin block for a repository (public)
curl -s https://timestampgit.dev/api/statusLast/acme/payments-api

# Total stamped commits (public)
curl -s https://timestampgit.dev/api/statusCount/acme/payments-api

# Combined summary, handy for Shields.io
curl -s https://timestampgit.dev/api/statusSummary/acme/payments-api

# Full Merkle chain data for a specific day, for local verification
curl -s https://timestampgit.dev/api/verify/acme/payments-api/2026-10-25

# Audit ledger as CSV
curl -s -o audit.csv https://timestampgit.dev/api/audit/acme/payments-api

# PDF certificate for one date
curl -s -o certificate.pdf https://timestampgit.dev/api/report/acme/payments-api/2026-10-25

Enterprise ZK 安装还会使用 HMAC 认证的提交端点,其中 {hash} 是你的 Action 请求的签名 URL 所返回的 HMAC 值:

curl -X POST \
  "https://timestampgit.dev/api/timestamp/acme/payments-api/timestamps/<hmac>/<commitId>"

这就是全部集成面。没有需要调度的“启动批次”调用——批处理是服务的职责。

监控与故障处理

你不监控的自动化只是乐观主义。Timestamp GIT 为你提供三种独立方式来确认流水线健康。

公开状态仪表盘

每个仓库都有一个位于 /status/{user}/{repo} 的公开仪表盘,显示:

  • 证明的持久性和最早的锚定日期——你的证明链能追溯到多久以前。
  • 每日规律性,以日历热力图呈现,这样漏掉一晚就一目了然。
  • 每个锚点的比特币区块和交易数据。

验证徽章

在 README 中嵌入 Shields.io 徽章,让证明公开可见:

![Timestamped](https://timestampgit.dev/api/statusSummary/acme/payments-api)

/connected/{user}/{repo} 页面提供一个带实时预览的徽章嵌入组件,包括 markdown 片段。对于私有仓库,状态 URL 携带特定于服务器实例的加密 HMAC——状态只对拥有签名链接的人可见。

自托管健康检查

由于状态端点是纯 JSON,你自己 CI 中的一个小脚本就能在审计员之前发现停滞的流水线:

import requests

BASE = "https://timestampgit.dev"
USER, REPO = "acme", "payments-api"

r = requests.get(f"{BASE}/api/statusLast/{USER}/{REPO}", timeout=15)
r.raise_for_status()

last = r.json()  # last anchored Bitcoin block info for this repository
print(last)
# Compare against yesterday's stored value in your own job to detect a stalled batch.

如果夜间批次没有完成怎么办?在所有情况下可观察到的信号都是一样的:热力图显示空缺,最后锚定的区块停止推进。由于锚定按天分批,漏掉一次运行会在 24 小时内被发现,而不是等到审计时——而且由于哈希队列和清单按日期键控,重新运行会产生一个明确的、带日期的证明,而不是模糊不清的证明。先检查仪表盘,然后检查仓库的 timestamps 分支,确认清单和收据是否已写入。

审计追踪

对于合规审查,有两样产物承担了主要工作:

  • GET /api/audit/{user}/{repo}——完整的 CSV 账本。
  • GET /api/report/{user}/{repo}/{date}——单个日期的 PDF 证书。

当有人想核对计算而不是信任一份 PDF 时,/verification/{user}/{repo}/{date} 页面会逐步展示多级 Merkle 链。所有这些计算都在浏览器本地进行——你验证的内容不会发送到服务器。

自动化时间戳的最佳实践

流水线运行起来后,几个习惯能让证据保持有用:

  • 尽早且频繁地提交。 每次提交都是现有技术的一个数据点。在提交申请前把一个月的工作压缩成一个提交,你得到的是一个锚点而不是四十个。
  • 把证明放在自己的分支上。 自动化的 timestamps 分支是机器写入的;让它与功能分支分开可以保持 git log 可读,并避免合并噪音。
  • 定期验证,而不只是在争议时验证。 每季度通过网页验证器抽查一个最近的日期。在诉讼期间发现验证链断裂,那是最糟糕的发现时机。
  • 随发布一起交付证明。 将发布日期的清单和收据附加到发布产物中,并在法律文档中引用该日期。
  • 为你可能申请专利的任何东西打标签。 提交会被自动捕获;当你开始讨论一个可专利的想法时,确保工作已提交,而不是停留在本地分支中。

使用 Docker 自托管自动化

托管托管是默认选项,但有些环境无法使用它:气隙网络、严格的数据驻留要求,或禁止任何外部服务接触仓库元数据的内部政策。

对于这些情况,Timestamp GIT 以 Docker 镜像形式提供。自动化完全相同——同样的夜间批处理、Merkle 树构建和比特币锚定,只是运行在你的基础设施中。

一个快速入门的 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 许可证页面 申请限时演示许可证——需要姓名、公司、电子邮件和可选的电话号码。可下载限时演示许可证文件,你在本地部署设置阶段上传它。

常见问题

我需要在我开发者的机器上运行任何命令或安装工具吗? 不需要。Timestamp GIT 完全通过 GitHub App 工作。安装后,对受监控仓库的每次提交都会每晚自动打时间戳。没有 CLI 工具,没有 OpenTimestamps 命令,没有手动步骤。

一次提交需要多长时间才能被打上时间戳? 提交每晚批量处理并锚定一次。比特币交易通常在大约 3 小时内确认,因此证明通常在 UTC 午夜后几小时可用。

我可以在不信任 Timestamp GIT 的情况下独立验证时间戳吗? 可以。.ots 收据文件可以使用标准 OpenTimestamps 工具对照比特币区块链进行验证。证明仅依赖 SHA-256 和比特币区块数据,因此即使我们的服务消失,你也可以离线验证。

如果我需要让源代码完全保密怎么办? 使用 Enterprise ZK 模式:你基础设施上的 GitHub Action 只把提交哈希推送到我们的 API。我们永远没有对你源代码的读取权限。或者,使用 Docker 自托管以获得完全控制。

时间戳流水线会接触我的源代码吗? 不会。标准模式读取提交哈希;Enterprise ZK 模式根本看不到你的仓库内容。服务只处理 SHA-256 哈希和比特币区块数据。

你无需操心的时间戳

密码学现有技术的价值来自覆盖范围,而不是单个令人印象深刻的证明。一个英勇下午打上的一个提交几乎证明不了什么;十八个月的夜间锚定证明了一条时间线。这是一个量的问题,而量的问题靠自动化解决。

这就是 Timestamp GIT 的全部卖点:安装一次 GitHub App,选择你的仓库,让夜间任务完成其余工作。证明落在 timestamps 分支上,徽章落在你的 README 中,审计 CSV 在法律部门需要时就在那里。如果你需要隔离,Enterprise ZK 模式或 Docker 可以让你在不放弃自动化的情况下实现。

安装应用,推送一次提交,明天早上检查仪表盘。


相关文章

EU label: AI-generated content