docker trust inspect 命令详解：全面掌握 Docker 镜像签名与密钥信息查询

• 容器运行时
• 云原生

导读：docker trust inspect是 Docker Content Trust（内容信任）体系中用于只读查询镜像仓库签名与密钥信息的核心命令。它以 JSON（默认）或人类可读表格（--pretty）两种格式，输出指定镜像仓库中所有已签名标签的摘要、签名者名单、委托签名者及其密钥 ID、仓库 Root 与 Repository 管理密钥，是安全团队审计镜像供应链、开发者排查签名问题最直接的诊断工具。本文基于 docker-ce 仓库中该命令的官方文档与完整源码实现，系统讲解其用法、JSON 与表格输出语义、底层数据流与常见错误处理，助你彻底掌握docker trust inspect的使用与原理。

命令概览：用法与选项

docker trust inspect属于 Docker CLI 的docker trust命令族，负责返回关于密钥与签名的低层（low-level）信息。其完整用法如下：

Usage: docker trust inspect IMAGE[:TAG] [IMAGE[:TAG]...] Return low-level information about keys and signatures Options: --help Print usage --pretty Print the information in a human friendly format

关键点：

• 参数：至少需要 1 个IMAGE[:TAG]。从源码看，命令通过cli.RequiresMinArgs(1)强制至少一个参数，不提供参数会直接报错requires at least 1 argument（见 inspect.go 与对应测试 inspect_test.go）。
• --pretty：以人类友好的表格格式输出，取代默认的 JSON。prettyPrint布尔标志定义在 inspect.go。
• --help：打印用法说明。

在 cmd.go 中可以看到，inspect与revoke、sign、key、signer一起注册为docker trust的子命令，属于"Manage trust on Docker images"信任管理体系的一部分。

命令用途说明

docker trust inspect为已签名的仓库提供低层 JSON 信息，包括：

• 所有已签名的镜像标签（tags）；
• 这些标签由谁签名（signers）；
• 哪些实体可以为新标签签名（即通过docker trust signer add配置的委托签名者）。

在默认 JSON 输出中，数据按trustRepo结构序列化，其字段在源码 common.go 中定义：

底层实现：inspect 命令的数据流与原理

为了真正理解docker trust inspect输出中每个字段的来源，我们需要进入其源码实现。命令的核心数据获取函数是lookupTrustInfo（common.go），整个数据流如下：

1. 解析镜像引用与鉴权信息

imgRefAndAuth, err := trust.GetImageReferencesAndAuth(ctx, nil, image.AuthResolver(cli), remote)

这一步通过 cli/trust/trust.go 中的GetImageReferencesAndAuth完成：调用reference.ParseNormalizedNamed解析IMAGE[:TAG]，并将仓库名解析为RepositoryInfo，同时解析出tag与digest。测试用例覆盖了非法引用（如ALPINE大写的invalid reference format、纯 SHA 摘要的invalid repository name）。

2. 建立 Notary 客户端（只读）

notaryRepo, err := cli.NotaryClient(imgRefAndAuth, trust.ActionsPullOnly)

docker trust inspect以**只读（pull only）**模式访问 Notary 仓库。GetNotaryRepository（trust.go）会构造带鉴权的 HTTP 传输层：先是GET <server>/v2/的 ping 探测（用于解析 Registry/Notary 的 challenge 鉴权方式），再根据仓库 Index 信息决定信任服务器地址——官方镜像默认使用https://notary.docker.io，非官方镜像使用https://<registry-name>，也可通过环境变量DOCKER_CONTENT_TRUST_SERVER覆盖。密钥与元数据缓存在$DOCKER_CONFIG/trust目录下（GetTrustDirectory）。

3. 清理 changelist 并读取签名

if err = clearChangeList(notaryRepo); err != nil { ... } allSignedTargets, err := notaryRepo.GetAllTargetMetadataByName(tag)

clearChangeList清空 notary 暂存区 changelist（见 helpers.go）。随后通过GetAllTargetMetadataByName(tag)按 tag 拉取全部 targets 元数据。若仓库未初始化或无法访问，返回No signatures or cannot access <remote>；若目标不存在（client.ErrNoSuchTarget），则返回空表。

4. 匹配"已发布"签名

signatureRows := matchReleasedSignatures(allSignedTargets)

matchReleasedSignatures（common.go）是输出语义的关键：

• 只有被签名进入targets或targets/releases这两个"released"角色的标签才会被列入SignedTags；
• 其他所有为同一(tag, digest)组合签名的委托角色（如targets/alice）都会被计入该标签的Signers；
• 若某标签仅由targets/targets/releases签名（没有额外委托签名者），Signers为空，之后在输出阶段统一显示为Repo Admin；
• 输出按标签名做自然排序（natural sort）。

这一"是否 released"的判断在isReleasedTarget（helpers.go）中定义，而 TUF 角色名到人类可读签名者名的转换由notaryRoleToSigner（helpers.go）完成——即去掉targets/前缀，targets与targets/releases显示为Repo Admin。相关的单元测试见 inspect_pretty_test.go 中的TestMatchReleasedSignatureFromTargets、TestMatchOneReleasedMultiSignature等。

5. 获取管理角色与委托角色

adminRolesWithSigs, err := notaryRepo.ListRoles() // Root、Targets 等管理角色 delegationRoles, err := notaryRepo.GetDelegationRoles() // 委托签名角色

• 管理角色（ListRoles）用于生成AdministrativeKeys：data.CanonicalRootRole显示为Root，data.CanonicalTargetsRole显示为Repository（见 inspect.go）。
• 委托角色（GetDelegationRoles）用于生成Signers列表；源码会跳过targets/releases、root、snapshot、targets、timestamp等基础角色，只保留真正的委托签名者（见getDelegationRoleToKeyMap，common.go）。

6. 两条输出路径

runInspect（inspect.go）按--pretty是否开启分叉：

• 默认 JSON 路径：将getRepoTrustInfo得到的trustRepo结构交给通用inspect.Inspect（inspector.go），最终经IndentedInspector以 4 空格缩进的 JSON 数组输出。
• --pretty路径：调用prettyPrintTrustInfo（inspect_pretty.go），按区块输出Signatures for <repo>、List of signers and their keys for <repo>（仅存在委托签名者时）、Administrative keys for <repo>三部分表格。

多镜像查询时，pretty 模式会在每个仓库输出之间插入空行作为分隔（inspect.go）。

实战示例一：查看单个镜像标签的签名细节

查询单个镜像标签的信任信息，直接传入IMAGE[:TAG]即可：

$ docker trust inspect alpine:latest

默认输出为 JSON 数组，每个被查询对象对应数组中的一个元素，例如：

[ { "Name": "alpine:latest", "SignedTags": [ { "SignedTag": "latest", "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", "Signers": [ "Repo Admin" ] } ], "Signers": [], "AdministrativeKeys": [ { "Name": "Repository", "Keys": [ { "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" } ] }, { "Name": "Root", "Keys": [ { "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" } ] } ] } ]

字段解读：

• SignedTags中的每一项列出SignedTag（已签名标签名）、其Digest（唯一的内容寻址摘要）以及为该签名负责的Signers。此处仅有Repo Admin，表示该标签由仓库的targets/targets/releases角色签名，没有额外的委托签名者。
• AdministrativeKeys列出Repository与Root两个管理密钥：Root是信任链的根密钥，Repository是仓库级管理密钥，两者共同负责修改签名者（signers）以及为已签名仓库做密钥轮换（key rotation）。
• Signers为空数组，表示该仓库尚未通过docker trust signer add配置额外的委托签名者。

实战示例二：带委托签名者的仓库

当仓库通过其他docker trust命令（如 docker trust signer add）配置了签名者后，docker trust inspect会额外输出Signers键：

$ docker trust inspect my-image:purple

输出示例：

[ { "Name": "my-image:purple", "SignedTags": [ { "SignedTag": "purple", "Digest": "941d3dba358621ce3c41ef67b47cf80f701ff80cdf46b5cc86587eaebfe45557", "Signers": [ "alice", "bob", "carol" ] } ], "Signers": [ { "Name": "alice", "Keys": [ { "ID": "04dd031411ed671ae1e12f47ddc8646d98f135090b01e54c3561e843084484a3" }, { "ID": "6a11e4898a4014d400332ab0e096308c844584ff70943cdd1d6628d577f45fd8" } ] }, { "Name": "bob", "Keys": [ { "ID": "433e245c656ae9733cdcc504bfa560f90950104442c4528c9616daa45824ccba" } ] }, { "Name": "carol", "Keys": [ { "ID": "d32fa8b5ca08273a2880f455fcb318da3dc80aeae1a30610815140deef8f30d9" }, { "ID": "9a8bbec6ba2af88a5fad6047d428d17e6d05dbdd03d15b4fc8a9a0e8049cd606" } ] } ], "AdministrativeKeys": [ { "Name": "Repository", "Keys": [ { "ID": "27df2c8187e7543345c2e0bf3a1262e0bc63a72754e9a7395eac3f747ec23a44" } ] }, { "Name": "Root", "Keys": [ { "ID": "40b66ccc8b176be8c7d365a17f3e046d1c3494e053dd57cfeacfe2e19c4f8e8f" } ] } ] } ]

此例展示了完整的信任模型：purple标签由alice、bob、carol三个委托签名者共同签名；Signers区块列出每个签名者对应的密钥 ID（同一签名者可持有多个密钥，对应 TUF 委托角色targets/alice等的 KeyIDs）。这些 ID 在源码中取自委托角色的KeyIDs字段（见 inspect.go），并按名称排序输出。

实战示例三：未签名标签的行为差异

情况 A：仓库本身没有签名数据，或镜像不可访问。此时docker trust inspect不会显示任何签名标签，而是直接报错：

$ docker trust inspect unsigned-img No signatures or cannot access unsigned-img

这正是源码中lookupTrustInfo在无法访问仓库、或仓库未初始化（notary 元数据缺失）时返回的错误信息No signatures or cannot access %s（common.go）。相关的 offline / uninitialized 场景均有单元测试覆盖（inspect_test.go）。

情况 B：标签本身未签名，但同一仓库的其他标签已签名。此时docker trust inspect仍会报告相关的密钥信息（因为仓库级管理密钥与委托签名者信息是存在的），只是SignedTags为空：

$ docker trust inspect alpine:unsigned

[ { "Name": "alpine:unsigned", "Signers": [], "AdministrativeKeys": [ { "Name": "Repository", "Keys": [ { "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" } ] }, { "Name": "Root", "Keys": [ { "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" } ] } ] } ]

该行为对应测试用例UnsignedTagInSignedRepo（inspect_test.go），golden 期望输出见 trust-inspect-unsigned-tag-with-signers.golden：

[ { "Name": "signed-repo:unsigned", "SignedTags": [], "Signers": [ { "Name": "bob", "Keys": [ { "ID": "B" } ] }, { "Name": "alice", "Keys": [ { "ID": "A" } ] } ], "AdministrativeKeys": [ { "Name": "Root", "Keys": [ { "ID": "rootID" } ] }, { "Name": "Repository", "Keys": [ { "ID": "targetsID" } ] } ] } ]

注意：此时虽然该 tag 未签名，但仓库中配置的委托签名者alice、bob及其密钥仍会被列出，说明这些信息属于仓库级别而非某个 tag 级别。

实战示例四：查看仓库内全部已签名标签

不带 tag 时，docker trust inspect会报告仓库内所有已签名标签的细节：

$ docker trust inspect alpine

[ { "Name": "alpine", "SignedTags": [ { "SignedTag": "3.5", "Digest": "b007a354427e1880de9cdba533e8e57382b7f2853a68a478a17d447b302c219c", "Signers": [ "Repo Admin" ] }, { "SignedTag": "3.6", "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", "Signers": [ "Repo Admin" ] }, { "SignedTag": "edge", "Digest": "23e7d843e63a3eee29b6b8cfcd10e23dd1ef28f47251a985606a31040bf8e096", "Signers": [ "Repo Admin" ] }, { "SignedTag": "latest", "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", "Signers": [ "Repo Admin" ] } ], "Signers": [], "AdministrativeKeys": [ { "Name": "Repository", "Keys": [ { "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" } ] }, { "Name": "Root", "Keys": [ { "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" } ] } ] } ]

输出按 tag 名称自然排序。可以观察到3.6与latest指向同一个 digest（d6bfc3baf615...），即内容寻址摘要相同——这正是matchReleasedSignatures以(tag, digest)二元组为键聚合签名者的原因（common.go）。

实战示例五：一次查询多个仓库/镜像

docker trust inspect接受多个仓库与镜像作为参数，结果按参数顺序组织为一个有序列表：

$ docker trust inspect alpine notary

[ { "Name": "alpine", "SignedTags": [ { "SignedTag": "3.5", "Digest": "b007a354427e1880de9cdba533e8e57382b7f2853a68a478a17d447b302c219c", "Signers": [ "Repo Admin" ] }, { "SignedTag": "3.6", "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", "Signers": [ "Repo Admin" ] }, { "SignedTag": "edge", "Digest": "23e7d843e63a3eee29b6b8cfcd10e23dd1ef28f47251a985606a31040bf8e096", "Signers": [ "Repo Admin" ] }, { "SignedTag": "integ-test-base", "Digest": "3952dc48dcc4136ccdde37fbef7e250346538a55a0366e3fccc683336377e372", "Signers": [ "Repo Admin" ] }, { "SignedTag": "latest", "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", "Signers": [ "Repo Admin" ] } ], "Signers": [], "AdministrativeKeys": [ { "Name": "Repository", "Keys": [ { "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" } ] }, { "Name": "Root", "Keys": [ { "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" } ] } ] }, { "Name": "notary", "SignedTags": [ { "SignedTag": "server", "Digest": "71f64ab718a3331dee103bc5afc6bc492914738ce37c2d2f127a8133714ecf5c", "Signers": [ "Repo Admin" ] }, { "SignedTag": "signer", "Digest": "a6122d79b1e74f70b5dd933b18a6d1f99329a4728011079f06b245205f158fe8", "Signers": [ "Repo Admin" ] } ], "Signers": [], "AdministrativeKeys": [ { "Name": "Root", "Keys": [ { "ID": "8cdcdef5bd039f4ab5a029126951b5985eebf57cabdcdc4d21f5b3be8bb4ce92" } ] }, { "Name": "Repository", "Keys": [ { "ID": "85bfd031017722f950d480a721f845a2944db26a3dc084040a70f1b0d9bbb3df" } ] } ] } ]

从源码看，多对象场景由通用inspect.Inspect循环调用getRef完成（inspector.go），任一对象出错时错误信息会被收集，最终以StatusError形式返回。测试用例MultipleFullReposWithSigners也验证了多仓库顺序输出（inspect_test.go）。

--pretty 模式：人类可读输出

默认 JSON 之外，--pretty选项可将输出转为更易读的表格形式。

单个标签

$ docker trust inspect --pretty alpine:latest SIGNED TAG DIGEST SIGNERS latest 1072e499f3f655a032e88542330cf75b02e7bdf673278f701d7ba61629ee3ebe (Repo Admin) Administrative keys for alpine:latest: Repository Key: 5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd Root Key: a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce

表格三列的含义：

• SIGNED TAG：已签名的镜像标签名；
• DIGEST：该标签唯一的内容寻址摘要（content-addressable digest）；
• SIGNERS：所有对该标签签名的实体列表。仅由targets/targets/releases签名的标签显示为(Repo Admin)，括号即表示这是仓库管理员级别的签名（见 inspect_pretty.go）。

Administrative keys列出的管理密钥分别指定了信任根密钥（Root Key）与仓库管理密钥（Repository Key），它们是修改签名者列表与对已签名仓库做密钥轮换的权威密钥。表格格式化逻辑在 formatter.go 中定义，表头依次为SIGNED TAG、DIGEST、SIGNERS。

带委托签名者的仓库（--pretty）

$ docker trust inspect --pretty my-image:purple SIGNED TAG DIGEST SIGNERS purple 941d3dba358621ce3c41ef67b47cf80f701ff80cdf46b5cc86587eaebfe45557 alice, bob, carol List of signers and their keys: SIGNER KEYS alice 47caae5b3e61, a85aab9d20a4 bob 034370bcbd77, 82a66673242c carol b6f9f8e1aab0 Administrative keys for my-image: Repository Key: 27df2c8187e7543345c2e0bf3a1262e0bc63a72754e9a7395eac3f747ec23a44 Root Key: 40b66ccc8b176be8c7d365a17f3e046d1c3494e053dd57cfeacfe2e19c4f8e8f

当仓库配置了委托签名者时，--pretty会额外输出List of signers and their keys区块，展示每个SIGNER及其KEYS。注意 pretty 模式下密钥 ID 被截断为 12 位短 ID（源码中printSignerInfo使用Trunc: true，配合stringid.TruncateID，见 formatter.go），而 JSON 模式输出完整 ID——这一点在实际排查时需注意区分。

未签名标签（--pretty）

$ docker trust inspect --pretty alpine:unsigned No signatures for alpine:unsigned Administrative keys for alpine:unsigned: Repository Key: 5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd Root Key: a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce

此时没有SIGNED TAG表格，而是直接提示No signatures for <repo>，随后仍然列出管理密钥。对应的 golden 期望输出见 trust-inspect-pretty-unsigned-tag-with-signers.golden：

No signatures for signed-repo:unsigned List of signers and their keys for signed-repo:unsigned SIGNER KEYS alice A bob B Administrative keys for signed-repo:unsigned Repository Key: targetsID Root Key: rootID

如果仓库中其他标签已签名，--pretty模式同样会报告相关的密钥信息。

仓库全部标签（--pretty）

$ docker trust inspect --pretty alpine SIGNED TAG DIGEST SIGNERS 2.6 9ace551613070689a12857d62c30ef0daa9a376107ec0fff0e34786cedb3399b (Repo Admin) 2.7 9f08005dff552038f0ad2f46b8e65ff3d25641747d3912e3ea8da6785046561a (Repo Admin) 3.1 d9477888b78e8c6392e0be8b2e73f8c67e2894ff9d4b8e467d1488fcceec21c8 (Repo Admin) 3.2 19826d59171c2eb7e90ce52bfd822993bef6a6fe3ae6bb4a49f8c1d0a01e99c7 (Repo Admin) 3.3 8fd4b76819e1e5baac82bd0a3d03abfe3906e034cc5ee32100d12aaaf3956dc7 (Repo Admin) 3.4 833ad81ace8277324f3ca8c91c02bdcf1d13988d8ecf8a3f97ecdd69d0390ce9 (Repo Admin) 3.5 af2a5bd2f8de8fc1ecabf1c76611cdc6a5f1ada1a2bdd7d3816e121b70300308 (Repo Admin) 3.6 1072e499f3f655a032e88542330cf75b02e7bdf673278f701d7ba61629ee3ebe (Repo Admin) edge 79d50d15bd7ea48ea00cf3dd343b0e740c1afaa8e899bee475236ef338e1b53b (Repo Admin) latest 1072e499f3f655a032e88542330cf75b02e7bdf673278f701d7ba61629ee3ebe (Repo Admin) Administrative keys for alpine: Repository Key: 5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd Root Key: a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce

带委托签名者的多标签仓库（--pretty）

$ docker trust inspect --pretty my-image SIGNED TAG DIGEST SIGNERS red 852cc04935f930a857b630edc4ed6131e91b22073bcc216698842e44f64d2943 alice blue f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197 alice, bob green cae8fedc840f90c8057e1c24637d11865743ab1e61a972c1c9da06ec2de9a139 alice, bob yellow 9cc65fc3126790e683d1b92f307a71f48f75fa7dd47a7b03145a123eaf0b45ba carol purple 941d3dba358621ce3c41ef67b47cf80f701ff80cdf46b5cc86587eaebfe45557 alice, bob, carol orange d6c271baa6d271bcc24ef1cbd65abf39123c17d2e83455bdab545a1a9093fc1c alice List of signers and their keys for my-image: SIGNER KEYS alice 47caae5b3e61, a85aab9d20a4 bob 034370bcbd77, 82a66673242c carol b6f9f8e1aab0 Administrative keys for my-image: Repository Key: 27df2c8187e7543345c2e0bf3a1262e0bc63a72754e9a7395eac3f747ec23a44 Root Key: 40b66ccc8b176be8c7d365a17f3e046d1c3494e053dd57cfeacfe2e19c4f8e8f

这个示例最直观地展示了委托签名机制的实际效果：同一个仓库内，不同标签的签名者组合各不相同——red仅由alice签名，blue/green由alice与bob共同签名，yellow由carol签名，purple则需要全部三位签名者。这正是多签名者协作发布流程（可通过 docker trust sign 触发）的可视化呈现。

常见错误信息与排查建议

基于底层NotaryError的错误分类逻辑（trust.go）以及lookupTrustInfo的错误处理，常见报错及其含义如下：

需要说明的是：docker trust inspect是一个只读查询命令（以ActionsPullOnly即pull权限访问 Notary），它不会修改任何信任数据；所有写入类操作（签名、增删签名者、吊销、生成/加载密钥）分别由 docker trust sign、docker trust signer add、docker trust signer remove、docker trust revoke、docker trust key generate 与 docker trust key load 承担。同时，docker trust inspect的查询结果与docker pull/docker push在DOCKER_CONTENT_TRUST=1时校验签名所依赖的信任数据（TUF 元数据、密钥、委托角色）来自同一套 Notary 数据源，因此它也是排查"为什么某个镜像 pull 时无法通过信任校验"的第一现场。

总结

docker trust inspect是 Docker Content Trust 生态中面向审计与排障的核心只读命令：

• JSON 模式输出机器可读的完整信任状态：SignedTags聚合已发布标签及其签名者，Signers罗列委托签名者与密钥 ID，AdministrativeKeys给出Repository与Root两级管理密钥；
• --pretty模式以表格呈现同一信息，密钥 ID 截断为短 ID，适合人工快速浏览；
• 底层原理依托 Notary 客户端：lookupTrustInfo通过GetAllTargetMetadataByName获取全部 targets 元数据，以(tag, digest)为键、以是否进入targets/targets/releases角色判定"已发布"，再聚合委托角色的签名者名单（源码见 common.go、inspect.go、inspect_pretty.go）。

掌握docker trust inspect，即可随时查看"谁签了哪些标签、用什么密钥签的、哪些实体有权继续签名"，为镜像供应链的可信审计提供最直接的事实依据。

• 容器运行时
• 云原生