homelab-wiki/services/zot.md

title, lifecycle, evidence, last_reviewed, last_verified

title	lifecycle	evidence	last_reviewed	last_verified
zot 镜像与制品仓库使用指南	active	documented	2026-09-16	null

zot 镜像与制品仓库

zot 保存容器镜像与 OCI 制品，底层数据存放于 SeaweedFS。 客户端使用 Registry API，不需要直接访问 S3 bucket。

本页依据 homelab-infra 工作区 apps/zot/README.md 的 2026-09-16 记录整理。 源文档记录双入口已上线并验收、由 Flux 管理；本轮未查询现场或执行下面的示例。

两个入口

入口	用途	认证
zot.ad.ddupan.top	内网拉取镜像或制品	匿名只读
zot-push.ad.ddupan.top	鉴权访问及已授权发布	SPIRE JWT-SVID，audience 为 zot；写权限按 SPIFFE ID 和 repository 分配

需要到 LAN 的路由与内网 DNS。两个入口对应相同制品数据，例如推送 zot-push.ad.ddupan.top/team/image:tag 后，可从 zot.ad.ddupan.top/team/image:tag 拉取，无需再复制一份镜像。

第一次拉取

安装 crane 后，在可写的工作目录执行源码文档提供的只读示例：

crane pull zot.ad.ddupan.top/verification/anonymous-spire:smoke image.tar --format oci

预期得到本地 image.tar OCI archive。该验证制品仅含测试内容，没有可执行入口， 用于验证拉取链路，不要把它当作能运行的业务镜像。 日常部署使用发布方提供的真实镜像路径和 tag/digest；匿名拉取不需要登录推送入口。

发布自己的镜像

发布前需要同时具备：

1. 执行环境能通过 Workload API 获取自己的 SPIFFE 身份。
2. workflow 获取 aud=zot 的短期 JWT-SVID。
3. zot 已为该 SPIFFE ID 授予目标 repository 所需的 read/create/update 权限。

根据所读源文档，当前持久配置没有常驻 publisher 或删除授权，曾用于验收的临时写权限 已经撤回。因此以下是获授权后的使用模板，不能仅登录成功就假定可以推送。

假定 workflow 已将 JWT-SVID 放入当前进程的 ZOT_JWT，准备好自己的 image.tar， 并将示例目标替换为已授权的 repository/tag，在 Bash 中执行：

(
  set +x
  set -euo pipefail
  : "${ZOT_JWT:?workflow 必须先取得 aud=zot 的 JWT-SVID}"
  export DOCKER_CONFIG="$(mktemp -d)"
  trap 'rm -rf -- "$DOCKER_CONFIG"' EXIT
  printf '%s' "$ZOT_JWT" | crane auth login zot-push.ad.ddupan.top \
    --username zot --password-stdin
  crane push image.tar zot-push.ad.ddupan.top/team/image:tag
)
unset ZOT_JWT

临时配置目录退出时删除。登录、token 获取和刷新由 workflow 负责， Dynamic Runner 提供环境和身份能力，不代办这些业务流程。 这里的 token 交换不会延长原 SVID 的有效期。

常见问题与数据边界

• 拉取域名不能推送：它只提供匿名读取，发布应使用推送域名。
• 401：检查 issuer、audience、有效期，以及 workflow 是否实际取得了 JWT-SVID。
• 登录成功但推送被拒绝：检查具体 SPIFFE ID 的 repository policy；身份与写权限分开配置。
• S3 后端报错：检查 zot 到 SeaweedFS 的连接与受管凭据，不能用客户端的 JWT 代替后端 AK/SK。

zot 的持久数据在 SeaweedFS zot bucket 的 registry/ 前缀；zot Pod 的临时目录不是备份。 恢复需要完整 bucket 数据、OpenBao 专用凭据与部署配置。源文档记录独立异机/离线备份尚未建立， 不能将同一 SeaweedFS 的副本视为独立灾备；重装 zot 不得删除该 bucket。

部署、授权变更、凭据轮换及验收细节以 homelab-infra apps/zot/README.md 为准。