使用 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,流水线就会自行运行:
- 提交检测。 GitHub App 接收新提交的 webhook,或者——在企业零知识模式下——你的 GitHub Action 将提交哈希推送到 API。
- 哈希队列。 提交哈希进入 Valkey,这是用于批处理的内存键值存储。
- 午夜 cron 工作进程。 每晚,工作进程将所有待处理的哈希分组,为每个仓库写入一个清单
.txt,构建 Merkle 树,使用公共 OTS 日历创建 OpenTimestamps 证明,并将 Merkle 根锚定到比特币中。 - 证明交付。 清单和
.ots收据文件被推回你的仓库中专门的 timestamps 分支或影子仓库。 - 确认。 比特币确认需要几个小时——通常大约三个小时——因此证明写入会在批次运行几小时后完成。
零知识属性是结构性的,而不是政策声明:只处理提交哈希。无论你运行标准模式还是企业零知识模式,你的源代码都不会离开你的网络。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} 提供(需认证),大致如下:
[](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 提供相同的夜间锚定,零设置——而且你以后可以迁移到自托管,而无需改变进入你仓库的内容。