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

# zot 镜像与制品仓库

zot 保存容器镜像与 OCI 制品，底层数据存放于 [SeaweedFS](seaweedfs.md)。
客户端使用 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 后，在可写的工作目录执行源码文档提供的只读示例：

```bash
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 中执行：

```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](gitea-dynamic-runner.md) 提供环境和身份能力，不代办这些业务流程。
这里的 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` 为准。