Docker 镜像在传输过程中默认不做来源校验，只要拿到镜像摘要，任何人都可以重新打标签分发一个伪造镜像。Docker Notary 就是为了解决这个问题而生的：它实现了 The Update Framework（TUF）规范，通过数字签名让客户端在拉取镜像时验证发布者身份和内容完整性。这篇文章围绕 Notary 的架构原理和内容信任的完整配置流程展开，包含客户端启用、签名推送、密钥管理和自建服务端几个部分。
Notary 内容信任的工作原理
Notary 由客户端和服务端两部分组成。服务端负责存储签名元数据和公钥信息，客户端负责签名、验证和密钥管理。Docker 客户端从 1.8 版本开始内置了 Notary 客户端的裁剪版，只要环境变量 DOCKER_CONTENT_TRUST 打开，执行 docker pull 时就会自动向签名服务端（默认是 Docker Hub 的 Notary 服务）查询该镜像的签名元数据，校验通过后才允许下载。
TUF 模型的核心是四类密钥的分工协作。root 密钥是信任链的根，负责认证其他密钥，离线保存，一个开发者通常只需要一个；targets 密钥负责签名镜像的 tag 列表，也就是实际发布内容；snapshot 密钥负责对整个元数据文件集合做快照签名；timestamp 密钥由服务端持有，用较短的有效期保证客户端拿到的是最新的元数据，防止回滚攻击。这种分层设计把单点风险分散开，即使某个密钥泄露，root 密钥也可以将其撤销并轮换。
签名信息默认存储在本地 ~/.docker/trust/private 目录下，以密钥的哈希值命名。理解这个目录的结构很重要，因为后续的备份、迁移、恢复操作都围绕它展开。
启用内容信任并完成镜像签名
最简单的启用方式是设置环境变量，设置后所有会修改镜像状态的命令（push、build、pull、create）都会强制走信任流程：
# 临时启用 export DOCKER_CONTENT_TRUST=1 # 推送镜像，首次推送会引导生成 root 密钥（需要设置强口令） docker push yourname/myapp:1.0 # 拉取时自动验证签名，无签名或校验失败的镜像会被拒绝 docker pull yourname/myapp:1.0
第一次 push 时客户端会依次提示设置 root 密钥、repository 的 passphrase（也就是 targets、snapshot 密钥的口令）。这些口令丢失后无法找回，只能重建信任数据，所以务必用密码管理工具保存。完成签名后可以用 docker trust inspect 查看签名详情：
docker trust inspect yourname/myapp:1.0 --pretty
输出中会列出签名的 tag、摘要值以及签名者的公钥信息。如果只想对发布操作启用信任而不影响日常开发，可以按命令单独使用 --disable-content-trust 参数，或者只针对 CI 流水线的发布阶段导出环境变量，这样开发环境的构建速度不会受签名流程影响。
离线签名的思路是使用 delegation 机制：发布者先用 docker trust signer add 添加一个委托方，构建机器持有 targets 发布权限的委托私钥，签名动作在构建机上完成，而 root 密钥始终离线。即使构建机被入侵，攻击者拿到的也只是委托密钥，发布者可以随时用 root 密钥撤销它。
自建 Notary 服务端与密钥运维
私有化部署场景下通常需要自建 Notary 服务。官方推荐用 compose 方式部署，代码仓库中提供了 server 和 signer 两个服务的配置模板。server 对外提供 API，signer 持有 timestamp 和 snapshot 私钥负责实际签名，两者之间用 TLS 加密通信。部署后需要修改 Docker daemon 或客户端的信任服务地址：
export DOCKER_CONTENT_TRUST=1 export DOCKER_CONTENT_TRUST_SERVER=https://notary.ippipp.com:4443
服务端的数据存储支持 MySQL 和 PostgreSQL，生产环境建议使用 PostgreSQL 并做好定时备份。备份内容除了数据库，还要包括 /var/lib/notary 下的密钥目录，两者缺一不可，只备份数据库而没有密钥，历史签名将全部无法验证。
密钥丢失是最常见的运维事故。root 密钥丢失意味着整个仓库的信任链报废，只能先删除远端签名数据再重新初始化。而 targets 委托密钥丢失则相对可控，用 root 密钥添加新的委托方即可恢复发布能力。日常运维中建议做三件事：把 ~/.docker/trust/private 纳入加密备份；给 root 密钥设置轮换计划；在 CI 中用 docker trust key generate 为每条流水线生成独立的委托密钥，做到权限最小化。
排查签名失败时，可以先用 notary -s https://notary.ippipp.com:4443 list yourname/myapp 确认服务端元数据是否正常，再检查客户端系统时间是否准确。TUF 的 timestamp 元数据有效期很短，本机时钟偏差超过阈值就会报元数据过期错误，这是新手最常踩的坑之一。
需要注意的是，Kubernetes 从镜像仓库拉取时并不会自动做 Notary 验证，需要在准入层做集成，比如借助策略引擎对镜像签名做准入校验。内容信任是一整条链路的工程，客户端启用只是第一步，密钥管理和服务端运维才是长期可靠运行的根基。
Docker Notary镜像内容信任content trust修改时间：2026-09-08 04:22:26