Timestamp GIT

← All posts

2026-10-18

GitHub App 区块链时间戳设置:一次安装,永久时间戳

GitHub App 区块链时间戳设置:一次安装,永久时间戳
timestamp git blockchain proof

GitHub App 区块链时间戳设置:一次安装,永久时间戳

用一句话概括任务:在代码仓库上安装 Timestamp GIT GitHub App,这样你推送的每次提交都会在每晚自动锚定到比特币区块链——无需 CLI 工具,无需手动操作,无需改变团队的工作方式。

你完全可以硬着头皮自己来:自己运行 OpenTimestamps 工具、管理日历、构建自己的 Merkle 批处理,还要盯着比特币确认。那简直是一份兼职工作。Timestamp GIT 的存在就是为了让它根本不需要你来操心。本指南将带你走完我们推荐的设置路径:一次安装、一次仓库选择、一个配置界面,然后就是一个你再也不用去想的夜间流水线。

到最后,你将获得每天一份针对你提交的 .ots 凭证、README 中的验证徽章,以及一个公开状态仪表盘,任何人——律师、审计员、客户——无需账户即可查看。

你将设置什么(以及为什么这是一次性的工作)

确切的任务:将一个仓库连接到 GitHub App,使提交检测、哈希批处理、比特币锚定和证明交付全部自动完成,无需你介入。

你能从中得到什么:

  • 每天一份不可篡改的 .ots 凭证——一份加密证明,证明一组特定的提交哈希在特定日期已经存在。
  • 一个验证徽章,你可以放进 README,让证明状态公开可见。
  • 一个状态仪表盘,包含锚定日期、比特币区块和交易数据、每日规律性,以及可下载的审计导出文件。

这种分工值得牢记,因为它解释了为什么设置是一次性的工作:

  1. GitHub App 通过 webhook 检测提交。
  2. Timestamp GIT 在午夜对提交哈希进行批处理,构建 Merkle 树,并使用 OpenTimestamps 协议将 Merkle 根锚定到比特币中。
  3. 清单文件和 .ots 凭证文件被推送回一个专用的 timestamps 分支或你控制的影子仓库。

存在两种部署模式,本指南遵循第一种:

  • 标准模式(GitHub App)——完全托管,CI 中无需代码,仅读取受监控仓库的 HEAD 提交哈希。
  • 企业 ZK 模式——一个在你自己的基础设施上运行的小型 GitHub Action 仅将提交哈希推送到 Timestamp GIT API,并且只需要对目标证明仓库的读写访问权限。

如果你需要关于这一切为何重要的概念背景——专利流氓、员工纠纷、"洁净室"主张——请先阅读什么是加密优先权?。本文假设你已经决定要使用它,现在想让它运行起来。

安装前的先决条件

  • 一个对目标仓库(公开或私有)拥有管理员权限的 GitHub 账户。
  • 一个 Timestamp GIT 账户,其套餐与你的仓库可见性相匹配:开源版(免费,公开仓库)、Pro Agency($49/月,私有仓库)或企业 ZK 版($199/月,GitHub Actions)。
  • 决定证明应该存放在哪里:同一仓库中的专用 timestamps 分支,还是一个独立的影子仓库。
  • 明确权限模型:标准模式需要对源仓库的只读访问权限,以及对目标仓库的读写访问权限。企业 ZK 模式仅需要对目标仓库的读写访问权限,外加在你的源仓库中安装一个 GitHub Action。
  • 基本上没有其他要求。开发者机器上无需安装任何东西。 没有本地配置,没有钩子,没有每个开发者的环境变量。

第 1 步 — 安装 Timestamp GIT GitHub App

  1. 导航到 Timestamp GIT GitHub App 列表页面,点击 Install。
  2. 选择拥有该仓库的 GitHub 账户或组织。
  3. 选择 Only select repositories 并挑选你想要监控的仓库——或者授予对该账户中所有仓库的访问权限。
  4. 批准请求的权限。在标准模式下,这意味着对源仓库的只读访问权限(GitHub 的权限系统没有"仅提交哈希"的范围)以及对写入证明的目标仓库的读写访问权限。
  5. 确认重定向回 Timestamp GIT,并等待成功消息。

这就是安装过程。这是一个普通的 GitHub App OAuth 式流程,大约需要一分钟。

第 2 步 — 连接并配置你的仓库

前往 Your Repositories(/repos),确认新可访问的仓库出现在列表中。如果没有显示出来,你几乎肯定是在安装时选错了账户。

然后打开仓库连接页面,配置证明的目标位置:

  • 同一仓库,专用分支——证明与你的代码一起存放在 timestamps 分支上。简单、自包含、易于查找。
  • 独立的影子仓库——证明存放在你选择的仓库中。当源仓库的受众受限,或者你想在多个项目之间使用一个中央证明账本时,这很有用。

如果你使用影子仓库,请创建或选择它,并确认 Timestamp GIT 对其拥有读写访问权限。这里权限缺失或被撤销是日后出现"为什么什么都没显示"的最常见原因。

在这个页面上,启用 README 徽章。连接页面会渲染一个 Shields.io 徽章的实时预览,并给你确切的 markdown 片段——不要手写 URL,因为私有仓库需要特定于实例的 HMAC 组件。

保存配置。应用现在已就绪:从此刻起,webhook 会告知它在受监控分支上的每一次新提交。

第 3 步 — 让夜间锚定运行(并了解预期结果)

你不需要再做其他任何事情。以下是午夜发生的事情:

  1. 提交检测——GitHub App 已经通过 webhook 捕获了新的提交哈希。
  2. 哈希队列——哈希存放在内存键值存储中,等待批处理窗口。
  3. 午夜 cron 工作进程——待处理的哈希被分组,每个仓库生成一个清单 .txt 文件,原生构建 Merkle 树,使用公共 OTS 日历创建 OpenTimestamps 证明,并将 Merkle 根锚定到比特币区块链中。
  4. 证明交付——清单文件和 .ots 凭证文件被推送回你仓库的 timestamps 分支或影子仓库。

目标仓库中出现的内容大致如下:

timestamps/
  manifests/
    2026-10-18.txt        # 当天批处理的提交哈希
  proofs/
    2026-10-18.txt.ots    # 该清单的 OpenTimestamps 凭证

时间预期。 批处理在午夜运行,比特币确认需要几个小时——通常大约三个小时。所以如果你在 09:00 推送,预计证明会在第二天上午中段到达。这是比特币的特性,不是流水线的缺陷。

离开你仓库的内容: 只有提交哈希。Timestamp GIT 从不读取、复制或存储你的源代码。源代码留在 GitHub(或者在企业 ZK 模式下,完全留在你自己的环境中),只有哈希被盖上时间戳。

然后它会重复。每晚,永远,针对每一次未来的提交。你安装了一次;流水线处理其余的一切。

第 4 步 — 将验证徽章添加到你的 README

从仓库连接页面获取 markdown 片段——相同的数据也可以通过经过身份验证的 GET /api/badgeLink/{user}/{repo} 端点以编程方式获取,该端点返回徽章 URL 和 markdown 片段。

该片段具有这种形式(使用复制按钮;实际 URL 是特定于实例和仓库的,尤其是对于私有仓库):

[![Bitcoin timestamped](<badge-url-from-badgeLink>)](<status-page-url>)

将其粘贴到你的 README 中,提交并推送。任何点击徽章的人都会进入公开验证视图——无需账户,无需登录,无需特殊知识。

关于私有仓库的说明。 私有仓库的状态 URL 会附加一个加密的 HMAC。这意味着只有授权用户才能看到证明状态,而底层的比特币锚定仍然可以被任何持有 .ots 文件的人公开验证。HMAC 特定于你的服务器实例,这就是为什么你应该复制徽章 URL 而不是自己构造它。

可选但不错:将相同的徽章嵌入内部文档站点或工程仪表盘。它只是一个图片 URL 加一个链接。

第 5 步 —(可选)使用 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-license)提交请求表单获得,需提供你的姓名、公司、电子邮件和可选的电话号码。批准后即可下载限时演示许可证文件。

如何确认它奏效了

给它一个完整的周期(午夜批处理加上大约三个小时),然后验证:

  • 状态仪表盘——打开 /status/{user}/{repo}。你应该看到证明存续时间、最早锚定日期、每日规律性、比特币区块和交易数据,以及一个日历热力图。
  • 审计 CSV——GET /api/audit/{user}/{repo} 下载完整的审计账本。
  • PDF 证书——GET /api/report/{user}/{repo}/{date} 为特定日期生成证书。
  • Merkle 链遍历——/verification/{user}/{repo}/{date} 逐步展示多级验证过程。所有计算都在你的浏览器中本地进行,所以没有人——包括我们——能看到你验证了什么。
  • 公开状态端点——快速健全性检查:
curl -s https://timestampgit.dev/api/statusLast/{user}/{repo}
curl -s https://timestampgit.dev/api/statusCount/{user}/{repo}
curl -s https://timestampgit.dev/api/statusSummary/{user}/{repo}

statusLast 返回最后锚定的比特币区块,statusCount 返回已提交和已盖章提交的总数,statusSummary 为 Shields.io 打包数据。

如果你想要更深入的离线演练,了解如何将 .ots 文件转换为经过验证的比特币区块高度,我们在如何在本地验证比特币时间戳证明中单独介绍。

常见设置问题排查

24 小时后没有出现证明。 确认应用确实有权访问正确的仓库(检查 /repos),并确认在安装之后至少推送了一次提交。早于安装的提交从未被发送到哈希队列。

徽章显示为"unknown"。 检查徽章 URL 中的仓库 slug。对于私有仓库,确保加密的 HMAC 组件存在——一个被删减的 URL 将无法通过授权并返回无状态。

影子仓库推送失败。 Timestamp GIT 需要对目标仓库的读写访问权限。重新检查影子仓库的安装权限;源仓库的权限不会延伸到它。

企业 ZK 模式没有产生任何东西。 在该模式下没有基于 webhook 的提交检测。如果 GitHub Action 没有安装在源仓库中并主动将哈希推送到 API,那么任何哈希都不会到达服务。

证明晚了几个小时。 这是预期内的。批处理在午夜运行,比特币确认通常需要大约三个小时。这里的延迟是区块链时间问题,不是故障。

常见问题

我需要安装任何 CLI 工具或运行 OpenTimestamps 命令吗?

不需要。Timestamp GIT 是一个托管的 GitHub App:你安装一次,对受监控仓库的每次提交都会每晚自动锚定到比特币中。没有 CLI 工具,没有 OpenTimestamps 命令,开发者机器上无需安装任何东西。

我可以将 GitHub App 用于私有仓库吗?

可以。Pro Agency 套餐支持私有仓库。私有仓库的状态 URL 会附加一个加密的 HMAC,因此只有授权用户才能查看证明状态。

我的第一份时间戳证明需要多长时间才会出现?

提交由午夜 cron 工作进程进行批处理和锚定。比特币确认通常需要大约三个小时,因此清单文件和 .ots 凭证文件会在批处理运行几小时后推送回你的仓库。

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

这些证明与供应商无关。它们仅依赖 SHA-256 和通过 OpenTimestamps 协议的比特币区块数据,因此即使服务不再存在,你也可以使用标准工具离线验证它们。

结论

GitHub App 区块链时间戳设置的全部意义在于它应该是无聊的:安装一次,选择一个仓库,选择证明的去向,然后让夜间任务完成其余的工作。第 2 步之后的一切都是等待比特币确认。

到那时,你就拥有了大多数团队没有的东西——关于你的代码何时存在的数学上不可否认的证明,可离线验证,而你的源代码从未离开你的仓库。这是你可以交给律师、审计员或客户的优先权证明,而无需任何开发者改变他们的工作流程。

先在你最有价值的仓库上安装 GitHub App,然后从那里扩展。如果你更愿意在自己的边界内运行它,Docker 自托管许可证是相同的产品,只是底层是你的基础设施。

相关文章

EU label: AI-generated content