dockertag

dockertag

镜像引用看起来似乎固定不变，仔细一看却并非如此。 repo 未指定标签时，实际会默默指向 repo:latest； latest 本身会变动；仓库名称中有大写字母时，推送到要求使用小写名称的镜像仓库会失败；发布的镜像也可能缺少用于说明其源代码位置、所采用许可证，以及 MCP 服务的服务器名称的标签，而 MCP Registry 会检查该服务器名称标签，确认无误后才会列出镜像。dockertag 采用折中方案：你提供引用和找到的标签，它会返回一份审计结果。

每个引用都会以同样谨慎的方式解析。摘要是最后一个 @ 后面的全部内容。只有当最后一个路径段包含 : 时，才存在标签——因此，localhost:5000 中的冒号表示端口，绝不是标签；标签是该路径段中最后一个 : 后面的文本。当第一个路径段包含 . 或 :，或者恰好是 localhost 时，它就是注册表；否则，注册表为 docker.io，整个路径则是仓库。

根据解析出的引用和提供的标签，会按固定顺序执行九项检查：

• INVALID_REFERENCE（错误）——名称部分为空、仓库为空，或存在但为空的标签。该镜像不会继续进行其他检查，解析出的字段均为 null。
• INVALID_DIGEST（错误）——摘要不符合 sha256: 后跟 64 个小写十六进制字符的格式。
• UPPERCASE_REPOSITORY（错误）——仓库名称中任意位置包含大写字母。
• UNPINNED（错误）——既没有标签，也没有摘要，因此该引用会解析为可变的 latest 标签。
• LATEST_TAG（警告）——标签恰好为 latest，且没有摘要将其固定。
• MISSING_SOURCE_LABEL（警告）——缺少 org.opencontainers.image.source 标签。
• MISSING_LICENSE_LABEL（警告）——缺少 org.opencontainers.image.licenses 标签。
• MISSING_SERVER_NAME_LABEL（错误）——仅当你提供 expected_server_name 时才会检查：缺少 io.modelcontextprotocol.server.name 标签。
• SERVER_NAME_MISMATCH（错误）——存在该标签，但其值与预期值不同。

结果包含每个镜像解析出的注册表、仓库、标签和摘要，以及对应的问题代码；还包含按镜像输入顺序、再按检查顺序排列的问题平铺列表（附精确消息），以及镜像、错误、警告和无问题镜像的数量。

dockertag 不会联系注册表，也不会拉取镜像：标签由你提供，因此可在推送任何内容之前，在 CI 中使用该审计。格式错误的输入——例如缺少或空的镜像列表、缺少、为空或重复的引用、不是字符串到字符串映射的标签，以及无效的 expected_server_name——会产生验证错误并指出出错路径（例如 images[1].labels.custom must be a string），且不会生成部分审计结果。

CLI

npx @reneturcios/dockertag audit --input args.json
npx @reneturcios/dockertag --version

args.json 包含完整的参数对象：

{
  "expected_server_name": "io.github.CloudCorpRecords/dockertag",
  "images": [
    {
      "reference": "ghcr.io/cloudcorprecords/dockertag:0.1.0",
      "labels": {
        "org.opencontainers.image.source": "https://github.com/CloudCorpRecords/dockertag",
        "org.opencontainers.image.licenses": "MIT",
        "io.modelcontextprotocol.server.name": "io.github.CloudCorpRecords/dockertag"
      }
    },
    { "reference": "myteam/worker" }
  ]
}

审计结果以 JSON 格式打印：

{
  "images": [
    {
      "reference": "ghcr.io/cloudcorprecords/dockertag:0.1.0",
      "registry": "ghcr.io",
      "repository": "cloudcorprecords/dockertag",
      "tag": "0.1.0",
      "digest": null,
      "findings": []
    },
    {
      "reference": "myteam/worker",
      "registry": "docker.io",
      "repository": "myteam/worker",
      "tag": null,
      "digest": null,
      "findings": ["UNPINNED", "MISSING_SOURCE_LABEL", "MISSING_LICENSE_LABEL", "MISSING_SERVER_NAME_LABEL"]
    }
  ],
  "findings": [
    {
      "reference": "myteam/worker",
      "code": "UNPINNED",
      "severity": "error",
      "message": "no tag or digest: the reference resolves to the mutable latest tag"
    }
  ],
  "counts": { "images": 2, "errors": 2, "warnings": 2, "clean": 1 }
}

（上方的平铺 findings 列表经过了简略处理；其中每个问题都有一条记录。）退出代码：成功时为 0；运行时错误（包括无法读取或无效的输入文件，或无效输入）时为 1；用法错误时为 2。

MCP 服务

npx -y @reneturcios/dockertag mcp

MCP 客户端配置：

{
  "mcpServers": {
    "dockertag": {
      "command": "npx",
      "args": ["-y", "@reneturcios/dockertag", "mcp"]
    }
  }
}

工具

• audit_image_tags — 审计容器镜像引用和 OCI 标签：标签固定、小写仓库名称、源代码和许可证标签，以及 MCP Registry 服务器名称标签。

  • images（数组，必需，至少一个）——镜像对象数组，格式为 {reference, labels?}；reference 是按原样书写的完整镜像引用，且在集合中唯一；labels 是该镜像的 OCI 标签，采用字符串到字符串映射格式
  • expected_server_name（字符串，可选，非空）——io.modelcontextprotocol.server.name 标签的预期值；仅当提供此参数时，才会运行两项服务器名称检查

  返回 {images, findings, counts}。

Docker

docker run -i ghcr.io/cloudcorprecords/dockertag
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/dockertag audit --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios