Timestamp GIT

← All posts

2026-11-13

使用 Docker Compose 自托管 Git 时间戳

使用 Docker Compose 自托管 Git 时间戳
timestamp git blockchain proof

使用 Docker Compose 自托管 Git 时间戳

手动打时间戳每次都会以同样的方式失败。有人写了一份操作手册,另一个人把它变成脚本,脚本运行了三周,磁盘满了或者令牌过期了,直到有一天律师要求你证明你的仓库在十八个月前是某个样子,才有人注意到问题。

锚定本身并不是难点。难的是围绕它的整条流水线:检测提交、批量处理哈希、在重启后存活、交付凭证,以及让整件事在多年后仍然可验证。这正是自托管 Compose 栈能为你带来的——一个可重复、可检查的部署,自动化运行在你自己的网络上,数据目录归你所有。

本文介绍如何使用 Docker Compose 在本地部署 Timestamp GIT,一次性连接 GitHub App,然后让自动化的夜间工作进程把你的提交哈希锚定到比特币中。如果你想先了解概念背景,请阅读密码学先验技术:初创企业抵御专利流氓的护盾。

为什么要自托管 Git 时间戳?

手动执行时间戳步骤意味着每个仓库都要记住三件杂事:获取提交哈希的时间戳、收集生成的证明文件,以及把它们存储在持久且可审计的地方。漏掉一件,链条就有缺口;漏掉存储步骤,你就有凭证但没人找得到。

自托管解决的是另一类需求:

  • 数据驻留。 合规团队想知道提交元数据在哪里处理。使用 Docker 镜像,答案就是“在我们的主机上”。
  • 受限网络。 有些团队不会授予任何 SaaS 对源代码仓库的读取权限——即使是只读——无论供应商如何承诺。
  • 接近气隙的部署。 你可以在内部主机上运行镜像;只有锚定步骤需要出站访问公共 OpenTimestamps 日历。
  • 运维控制。 你决定更新节奏、备份计划,以及谁可以访问设置向导。

Docker Compose 很合适,因为整个系统只有两个容器:应用程序和一个用作内存哈希队列的 Valkey 实例。一次 pull 和一次 up -d 就能得到运行中的实例;./data 卷在重启之间保持状态;更新就是 docker compose pull && docker compose up -d。

关键的是,Docker 镜像与托管产品是相同的自动化——GitHub App 驱动的提交检测、夜间比特币锚定、推回你仓库的 .ots 凭证——只是运行在你自己的基础设施上。

一次性设置:Docker Compose 和 GitHub App

前提条件

  • 带有 Compose 插件的 Docker Engine。
  • 一台具有可靠正常运行时间和出站互联网访问的主机(通过公共 OpenTimestamps 日历进行比特币锚定所需)。
  • 一个可以安装到目标仓库的 GitHub App,以及一个目标仓库(或影子仓库),用于写入证明分支。
  • 该实例的许可证文件。

Compose 文件

一个快速入门的 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

在继续之前有两点需要注意。./data:/app/data 绑定挂载是实例的持久状态——把它当作关键数据,而不是缓存。而 restart: unless-stopped 在这里比通常更重要:午夜工作进程必须在午夜时活着。

启动栈:

docker compose pull
docker compose up -d
docker compose logs -f timestampgit

启动后,应用程序可通过 http://localhost:8080 访问。

首次启动

首次启动时,设置向导会引导你连接 GitHub App 并配置实例。在点击之前先规划好权限:

  • 标准模式。 GitHub App 只读取每个受监控仓库的 HEAD 提交哈希,并将证明写入目标仓库。GitHub 的权限模型要求至少对源仓库有只读访问权限,加上对目标仓库的读写访问权限。
  • 企业零知识模式。 一个 12 行的 GitHub Action 在你的基础设施上运行,只将提交哈希推送到 API。你需要对目标仓库的读写访问权限,而不需要源仓库的读取权限。

如果你在 2026 年为已经标准化使用托管 GitHub App 工作流的团队评估此方案,设置步骤会感觉很熟悉——那条路径请参阅使用 GitHub App 自动化 Git 提交时间戳。

许可

通过 Docker 许可证页面提交请求表单(包含你的姓名、公司、电子邮件和可选电话号码),可以获得用于评估的限时演示许可证。你可以下载限时演示许可证文件,并在企业设置期间上传。

如果实例可以从 localhost 以外的任何地方访问,请将其置于终止 TLS 的反向代理之后,并在网络层限制访问。设置向导是一个管理界面。

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

一旦 GitHub App 连接成功,流水线就会自行运行:

  1. 提交检测。 GitHub App 接收新提交的 webhook,或者——在企业零知识模式下——你的 GitHub Action 将提交哈希推送到 API。
  2. 哈希队列。 提交哈希进入 Valkey,这是用于批处理的内存键值存储。
  3. 午夜 cron 工作进程。 每晚工作进程将所有待处理的哈希分组,为每个仓库写入一个清单 .txt,构建 Merkle 树,使用公共 OTS 日历创建 OpenTimestamps 证明,并将 Merkle 根锚定到比特币中。
  4. 证明交付。 清单和 .ots 凭证文件被推回你的仓库中专门的 timestamps 分支或影子仓库。
  5. 确认。 比特币确认需要几个小时——通常大约三个小时——因此证明写入在批次运行后几小时完成。

零知识属性是结构性的,而不是政策声明:只处理提交哈希。无论你运行标准模式还是企业零知识模式,你的源代码都不会离开你的网络。Docker 部署只是将哈希处理步骤也移到了你的边界之内。

由于 Merkle 根通过 OpenTimestamps 锚定在比特币区块中,时间戳一旦确认就变得不可变。任何实体都无法更改或伪造它——包括供应商,也包括你自己。

监控和故障处理

时间戳流水线会悄无声息地失败。提交哈希排队,没有任何错误,你在审计时才发现缺口。把监控当作部署的一部分。

容器和队列健康。 最有用的检查是应用程序对已知仓库的自身状态。将你的正常运行时间监控指向它:

#!/usr/bin/env bash
set -euo pipefail
BASE="http://localhost:8080"
USER="acme"
REPO="platform"

docker compose ps --status running --quiet timestampgit >/dev/null \
  || { echo "timestampgit container is not running"; exit 1; }

curl -fsS "$BASE/api/statusLast/$USER/$REPO" | jq .

GET /api/statusLast/{user}/{repo} 返回最后锚定的比特币区块信息。如果该区块停止前进,工作进程就卡住了。

公开验证徽章。 对于每个受监控的仓库,徽章小部件会生成可嵌入 README 的 Shields.io markdown。该片段由 GET /api/badgeLink/{user}/{repo} 提供(需认证),大致如下:

[![Timestamped in Bitcoin](https://img.shields.io/endpoint?url=https://timestampgit.dev/api/statusSummary/acme/platform)](https://timestampgit.dev/status/acme/platform)

任何人都可以通过链接在网站上验证时间戳。对于私有仓库,状态 URL 带有特定于你服务器实例的加密 HMAC,因此只有授权用户才能读取状态。

审计和报告。 按计划而非按需拉取账本:

curl -fsS -o audit-$(date +%F).csv  "$BASE/api/audit/$USER/$REPO"
curl -fsS -o report-$(date -d yesterday +%F).pdf \
  "$BASE/api/report/$USER/$REPO/$(date -d yesterday +%F)"

这样你就得到了一个 CSV 审计账本和按日期生成的 PDF 证书,法律和合规团队可以直接归档,无需自己接触 API。

确认延迟。 锚定通常在大约三小时内完成。延迟会发生;工作进程会重试,并在锚定确认后交付 .ots 证明。对“清单已写入但 24 小时后仍无凭证”告警,而不是对短暂延迟告警,否则你会因为正常的比特币区块波动而给自己发警报。

备份和恢复。 按计划备份 ./data,如果你想在容器重建后保留排队的哈希,请为 Valkey 的 /data 目录挂载一个命名卷。Valkey 按设计是内存存储——丢失它只会损失一晚的批次,而不是已有的证明,因为已交付的证明存在于 timestamps 分支中。

自托管时间戳的最佳实践

  • 专用主机。 工作进程在午夜运行,需要稳定的正常运行时间和出站连接。与嘈杂的构建农场共享主机就是在自找错过批次。
  • 将数据卷排除在临时存储之外。 将 ./data 绑定挂载到持久磁盘,并将其纳入备份轮换。
  • 限制管理界面。 将向导和需认证的 API 置于 VPN 或具有强认证的反向代理之后。不要将 8080 端口暴露到公共互联网。
  • 有意识地更新。 在你控制的计划上运行 docker compose pull;在拉取新的 :prod 镜像之前阅读变更日志。
  • 当权限存在争议时优先选择企业零知识模式。 如果你的安全团队不会授予对源仓库的读取权限,GitHub Action 路径可以在不改变自动化的情况下满足他们。
  • 为审计人员记录流程。 写下实例运行在哪里、谁管理它、如何验证备份,以及 .ots 凭证存储在哪里。证明是密码学的;保管链仍然需要一段文字说明。
  • 端到端测试一次验证。 选择一个已锚定的日期,在你需要在争议中使用之前走一遍验证流程,而不是在争议期间。法律框架请参阅比特币时间戳可以作为证据采纳吗?合规指南。

常见问题

我需要将源代码暴露给 Timestamp GIT 吗? 不需要。Timestamp GIT 只处理提交哈希。在标准模式下,GitHub App 读取 HEAD 提交哈希;在企业零知识模式下,GitHub Action 只从你的基础设施推送哈希。你的源代码永远不会离开你的网络。

如果比特币确认时间比预期长怎么办? 午夜 cron 工作进程通过 OpenTimestamps 将 Merkle 根锚定到比特币中。确认通常需要大约 3 小时。如果确认延迟,工作进程会重试并在确认后交付 .ots 证明。

我可以在气隙环境中使用吗? 可以,Docker 镜像可以在气隙环境中运行,但通过公共 OpenTimestamps 日历进行比特币锚定需要出站互联网访问。你可以相应地配置网络访问。

如何独立验证时间戳? 你可以下载 .ots 文件,并使用标准 OpenTimestamps 验证工具对照比特币区块链进行验证。或者,使用 Timestamp GIT 提供的验证页面,它在你的浏览器中进行本地验证——没有人能看到你验证的内容。

结论

自托管 git 时间戳不是为了不信任供应商;而是为了将自动化、可审计的流水线放在你的合规团队已经接受的边界之内。两个容器、一个许可证文件、一个 GitHub App——之后午夜工作进程完成重复性工作,而你得到一个充满 .ots 凭证的仓库和一个公开状态页面。

首先在 Docker 许可证页面请求演示许可证,在暂存主机上启动 Compose 栈,并端到端验证一个已锚定的日期。如果你更愿意跳过基础设施,托管的 Timestamp GIT GitHub App 提供相同的夜间锚定且零设置——而且你以后可以迁移到自托管,而无需改变落入你仓库的内容。

相关文章

EU label: AI-generated content