Zot 介绍与选型指南

目标：面向 OCI 原生镜像仓库 Zot（project-zot/zot，官网 zotregistry.dev），依据官方文档与 GitHub 公开数据溯源整理其软件概述、核心架构、功能特性、官方裸机快速开始配方、适用场景与限制，并与 Harbor、distribution（Docker Registry）做量化选型对比。本文全部外部数据查询日期为 2026-11-01，基准版本 v2.1.22（2026-10-06 发布）。

一、环境与溯源信息

本节给出本文的溯源基准：以哪个版本、在什么时间、从哪些权威来源取数，以及一个必须先行澄清的同音名称歧义。

版本自检命令与实测回显（v2.1.22 二进制，日志为 JSON 单行）：

$ zot --version
{"time":"2026-11-01T07:58:07.896165213Z","level":"info","message":"version","distribution-spec":"1.1.1","commit":"v2.1.22-6bbc7e56db2b7a64eee589324efe5813245e3a28","binary-type":"-events-imagetrust-lint-metrics-mgmt-profile-scrub-search-sync-ui-userprefs","go version":"go1.27.1","caller":"zotregistry.dev/zot/v2/pkg/cli/server/root.go:261","func":"zotregistry.dev/zot/v2/pkg/cli/server.NewServerRootCmd.func1","goroutine":1}

回显中 binary-type 字段直接列出了该构建编译进去的全部扩展（events、imagetrust、lint、metrics、mgmt、profile、scrub、search、sync、ui、userprefs），这是后文「核心与扩展分离」架构的直接证据。

⚠️ 名称甄别：本文对象 Zot（OCI 镜像仓库，project-zot/zot）与文献管理软件 Zotero（zotero.org）是两个完全无关的项目，仅名称读音相近。检索、安装、排障时请勿混淆：Zot 的发布物名为 zot-linux-amd64 等，仓库地址为 ghcr.io/project-zot/zot；Zotero 与镜像仓库无任何关系。

二、软件概述

zot 官方文档首页的自我定位一句话是："OCI-native container image registry, simplified … now compatible with docker"（OCI 原生镜像仓库，化繁为简，现已兼容 docker），并已入选 CNCF Sandbox 项目。它要解决的问题是：distribution（即原 docker/distribution 注册表）只提供协议最小实现，UI、搜索、扫描、同步、签名校验等能力需要自行拼装多个组件；而 Harbor 这类企业级平台组件多、部署重。zot 把常用能力编译进单个静态二进制，用一个配置文件驱动全部行为，落地即得一个功能完整的私有镜像仓库。

官方特性页（Key Features）给出的设计要点：

• 严格符合 OCI Distribution Spec API，并以 OCI image layout 作为落盘存储格式；
• 可以把任意一个符合 OCI image layout 的目录直接作为仓库对外服务；
• 单二进制承载全部功能，不要求 root 权限运行；
• 核心 dist-spec 行为与 zot 专有扩展清晰分离；
• 支持 cosign 与 notation 两种镜像签名，支持 helm chart 等 OCI 制品；
• 行为完全由配置文件控制；二进制覆盖多操作系统与架构；
• 兼容 skopeo、cri-o 等生态工具；
• 当前适合本地部署（on-premises，例如与 Kubernetes 同机房部署）。

zot 提供 full 与 minimal 两种构建：full 编译全部扩展；minimal 只保留 dist-spec 核心代码与依赖，缩减攻击面，官方明确其适合「嵌入出货产品」的场景。v2.1.22 发布页实测资产体积（查询日期 2026-11-01）：

官方发布页同时提供 darwin/freebsd、amd64/arm64 组合共 12 个平台二进制；发布镜像位于 GitHub Container Registry：

发布节奏（GitHub Releases 实测，v2.1.17 → v2.1.22 共 6 个版本）：

v2.1.22 2026-10-06T16:50:05Z
v2.1.21 2026-09-06T18:44:38Z
v2.1.20 2026-08-04T17:51:30Z
v2.1.19 2026-08-04T06:46:22Z
v2.1.18 2026-06-24T15:30:19Z
v2.1.17 2026-05-18T05:44:37Z

解读：除 2026-06 一次空窗外基本保持每月一个版本的迭代速度，补丁版本（v2.1.x）持续滚动，生产环境按季度跟进小版本即可。

三、核心架构

zot 的架构可以概括为「协议层 + 文件系统存储层 + 进程内扩展层」三段，全部收敛在一个 Go 静态二进制里，无任何外部数据库或队列依赖。

协议层：完整实现 OCI Distribution Spec 的 /v2/ API（manifest/blob 推拉、_catalog、tags/list、按 digest 删除等），认证走 spec 标准的 401 + WWW-Authenticate 质询流程（realm 默认 zot），因此 docker、podman、skopeo、nerdctl、cri-o 等客户端无需任何适配即可直连。

存储层：数据直接以 OCI image layout 落在配置的 storage.rootDirectory 下，每个仓库一个目录（blobs/sha256/ 存内容寻址 blob、_manifests/ 存标签索引、index.json 为 OCI 清单）。正因为就是标准 OCI layout，官方特性页强调「任何符合 OCI image layout 的目录都能被 zot 直接作为仓库服务」。存储内建三项优化：GC（回收孤儿 blob）、dedupe（相同内容层用硬链接去重）、scrub（后台校验数据完整性）。

扩展层：search（GraphQL 查询 + Trivy CVE 扫描）、ui（Web 界面）、sync（从上游仓库轮询/按需回源镜像）、trust（cosign/notation 签名公钥托管与验签）、metrics（Prometheus 端点）、lint（推送内容合规检查）、userprefs（用户偏好如加星）、scheduler（后台任务并发度）、cluster（多存储路径/多后端）等扩展编译进 full 二进制，通过 extensions 配置段逐项开关；minimal 二进制则不携带这些代码。扩展与核心的清晰分离正是特性页「Clear separation between core dist-spec and zot-specific extensions」的落点。

进程与运维模型：zot serve <config.json> 单进程启动；支持配置文件热加载（授权相关段）；官方裸机安装配方给出 systemd Type=notify 服务单元与 socket 激活两种托管方式，并提供 zot healthcheck（探测 /readyz、/livez、/startupz）供探针使用。客户端侧有 Web UI 与命令行工具 zli。

💡 技术拓展：「私有镜像仓库」在业界存在多种形态谱系，zot 属于其中「轻量全功能单机型」——

形态	代表	特点	取舍
协议最小实现	distribution（registry）	单二进制、只有 API	UI/扫描/同步全靠自己拼
轻量全功能单机	zot	单二进制内置扩展	无多租户/跨机房复制等企业特性
企业级平台	Harbor	项目空间、RBAC、复制、门户	多组件部署重、资源占用高
制品通用库	JFrog Artifactory	多制品类型、代理能力强	商业授权、重量级
云厂商托管	GHCR/ECR/ACR/DaoCloud 镜像站	免运维	数据在云、配额与出口受限

本文后续实验采用 zot：以单二进制形态获得内置搜索、CVE、同步、验签能力，部署与运维成本接近 registry，功能面接近 Harbor 的常用子集。

四、功能特性

本节把官方特性页与配置参考中的能力整理为分类清单，便于快速核对 zot 是否覆盖需求。

认证方式首现，就地科普：

💡 技术拓展：zot 支持的认证方式不止 htpasswd 一种，常见选型对比——

方式	原理	适用场景
htpasswd（本地）	bcrypt 口令文件，Basic 质询	单机、CI、小规模私有仓库
LDAP	对接企业目录集中管账号	已有 AD/OpenLDAP 的组织
HTTP Bearer	token 服务签发短期令牌	与外部 token 体系/机器人账号集成
OIDC	对接 Keycloak/Authelia 等 IdP	需要 SSO 的团队
mTLS	客户端证书双向认证	机机通信、零信任内网
API Key	长期令牌	自动化脚本（谨慎使用）

本系列实验采用最轻量的 htpasswd（bcrypt），两账号即可覆盖「管理员 + 只读」权限验证。

五、快速开始（官方裸机配方）

官方 Linux 裸机安装指南（页面更新于 2026-10-06）给出六步配方，本节照录并逐项说明；后续两篇实验文档（Compose 部署、配置详解）即在此配方基础上展开。

第 1 步：获取 zot 二进制（下载到 /usr/bin 并改名 zot）：

sudo wget -O /usr/bin/zot https://github.com/project-zot/zot/releases/download/v2.1.22/zot-linux-amd64
sudo chmod +x /usr/bin/zot
sudo chown root:root /usr/bin/zot

第 2 步：创建配置文件 /etc/zot/config.json。官方模板核心段（节选）：

{
  "distSpecVersion": "1.0.1",
  "storage": {
    "rootDirectory": "/data/zot/",
    "dedupe": true,
    "gc": true,
    "gcDelay": "1h",
    "gcInterval": "6h"
  },
  "http": {
    "address": "0.0.0.0",
    "port": "443",
    "realm": "zot",
    "tls": {
      "cert": "/etc/letsencrypt/live/zothub.io/fullchain.pem",
      "key": "/etc/letsencrypt/live/zothub.io/privkey.pem"
    },
    "auth": {
      "htpasswd": { "path": "/etc/zot/htpasswd" },
      "failDelay": 5
    }
  },
  "log": {
    "level": "debug",
    "output": "/var/log/zot/zot.log",
    "audit": "/var/log/zot/zot-audit.log"
  },
  "extensions": {
    "search": { "enable": true, "cve": { "updateInterval": "24h" } },
    "sync": { "enable": false },
    "scrub": { "interval": "24h" }
  }
}

逐项说明：storage.rootDirectory 为唯一数据落盘点；dedupe/gc/gcDelay/gcInterval 开启硬链接去重与延迟 GC；http.port 官方模板直接按公网 443 + Let's Encrypt 证书编写；auth.failDelay 在认证失败后延时响应以抵抗口令爆破；log.audit 单独记录审计流水；search.cve.updateInterval 缺省 2h、最小值 2h，启用 CVE 扫描前需保证存储目录可写且 /tmp 有足够空间下载 Trivy 库。

第 3 步：创建本地认证账号：

htpasswd -bnB myUserName myPassword > /etc/zot/htpasswd
htpasswd -bnB myUserName2 myPassword2 >> /etc/zot/htpasswd

-B 指定 bcrypt 算法，-n 输出到标准输出、-b 命令行传密码。

第 4 步：定义 systemd 服务 /etc/systemd/system/zot.service（官方示例）：

[Unit]
Description=OCI Distribution Registry
Documentation=https://zotregistry.dev/
After=network.target auditd.service local-fs.target

[Service]
Type=notify
NotifyAccess=main
TimeoutStartSec=5min
ExecStart=/usr/bin/zot serve /etc/zot/config.json
Restart=on-failure
User=zot
Group=zot
LimitNOFILE=500000
MemoryHigh=30G
MemoryMax=32G

[Install]
WantedBy=multi-user.target

Type=notify 让 zot 启动完成时向 systemd 上报 READY=1，依赖它的单元会等待仓库就绪；官方注明若使用不发就绪通知的旧二进制应改用 Type=simple。另有 socket 激活方案（zot.socket 监听 443，服务单元加 Sockets=zot.socket），可让非 root 进程占用特权端口。

第 5 步：创建专用运行账号并初始化目录：

sudo adduser --no-create-home --disabled-password --gecos --disabled-login zot
sudo mkdir -p /data/zot && sudo chown -R zot:zot /data/zot
sudo mkdir -p /var/log/zot && sudo chown -R zot:zot /var/log/zot
sudo chown -R root:root /etc/zot/

第 6 步：启动并校验：

sudo systemctl daemon-reload
sudo systemctl enable zot
sudo systemctl start zot
sudo -u zot zot verify /etc/zot/config.json
sudo systemctl status zot

zot verify 实测回显（合法配置）：

{"time":"2026-11-01T07:58:07.986926299Z","level":"info","message":"config file is valid","config":"/etc/zot/config.json","caller":"zotregistry.dev/zot/v2/pkg/cli/server/root.go:224","func":"zotregistry.dev/zot/v2/pkg/cli/server.newVerifyCmd.func1","goroutine":1}

zot verify 实测回显（非法配置，exit=1）：

{"time":"2026-11-01T07:58:08.075688224Z","level":"error","message":"failed to read configuration","error":"While parsing config: unexpected end of JSON input","path":"/tmp/bad.json","caller":"zotregistry.dev/zot/v2/pkg/cli/server/root.go:1347","func":"zotregistry.dev/zot/v2/pkg/cli/server.LoadConfiguration","goroutine":1}
{"time":"2026-11-01T07:58:08.075739504Z","level":"error","message":"invalid config file","config":"/tmp/bad.json","caller":"zotregistry.dev/zot/v2/pkg/cli/server/root.go:219","func":"zotregistry.dev/zot/v2/pkg/cli/server.newVerifyCmd.func1","goroutine":1}
Error: While parsing config: unexpected end of JSON input
exit=1

健康检查用 zot healthcheck /etc/zot/config.json（别名 zot ready，默认探测 /readyz，也支持 --url https://registry.example.com/startupz --timeout 5s），2xx 响应退出码 0。

⚠️ 说明：第 4～6 步的 systemd 托管需要带 systemd 的 Linux 真机；若采用 Compose 方式部署，可参考配套部署实践篇（见文末链接），配置字段与裸机完全一致。

六、适用场景与限制

适用场景：

• 私有云 / 与 Kubernetes 同机房部署：官方特性页明确 zot 当前定位于 on-premises 部署（例如与 K8s 集群 colocated），作为集群内外的镜像分发点；
• CI/CD 镜像缓存与回源代理：sync 扩展支持轮询同步与按需回源（on-demand pull-through），把上游公共仓库的镜像拉取收敛到内网出口；
• 安全合规要求高的团队：内置 Trivy CVE 扫描、cosign/notation 验签、audit 审计日志、failDelay 爆破防护、按方法限流；
• 资源受限或嵌入式场景：minimal 构建 + zxp exporter，或直接把已有 OCI layout 目录挂给 zot 对外服务；
• 多制品轻量仓库：helm chart、cosign 签名等 OCI 制品均可存放。

限制与边界（选型时务必对照自身需求）：

• 单进程单机模型：zot 没有内建多副本集群或跨机房异步复制，高可用需依赖外部手段（负载均衡 + 多实例只读、或上层平台），企业级多节点复制是 Harbor 的强项；
• 授权粒度为策略级而非 RBAC 角色：accessControl 提供用户/组/命名空间/仓库级 allow/deny 与 defaultPolicy/adminPolicy，但没有 Harbor 式「项目 + 角色」多租户体系；
• UI 是浏览型门户而非运维平台：无用户自助管理、配额、Webhook 等企业门户特性；
• CVE 扫描有环境成本：需要下载 Trivy 漏洞库（官方建议保证存储目录可写与 /tmp 空间），内网环境需为库下载配置可达的镜像源；
• FreeBSD 仅提供二进制发布，不提供 ghcr 发布镜像；
• 项目处于 CNCF Sandbox 阶段，生态集成（如与 K8s 认证体系联动）不如 CNCF 毕业项目丰富。

七、同类选型对比

本节用可复核的量化数据对比三个最常见的 OCI 仓库实现：zot、Harbor、distribution。数据来自 GitHub API 与 shields.io 徽章，查询日期 2026-11-01。

Stars 实测（GitHub API）：

$ curl -s https://api.github.com/repos/project-zot/zot | python3 -c "import json,sys;print('zot stars:', json.load(sys.stdin)['stargazers_count'])"
zot stars: 2936
$ curl -s https://api.github.com/repos/goharbor/harbor | python3 -c "import json,sys;print('harbor stars:', json.load(sys.stdin)['stargazers_count'])"
harbor stars: 29654
$ curl -s https://api.github.com/repos/distribution/distribution | python3 -c "import json,sys;print('distribution stars:', json.load(sys.stdin)['stargazers_count'])"
distribution stars: 10669

shields.io 徽章同步复核：Harbor 显示 >30k，zot 显示 2.9k，与 API 数值一致。

版本与发布节奏（GitHub Releases API 实测）：

能力矩阵：

解读与选型建议：

• stars 反映社区势能：Harbor（29654）> distribution（10669）> zot（2936），但 zot 近 6 个版本保持月度发布，维护活跃度并不缺席；
• 选 zot：需要单机部署、免外部依赖、开箱即得 UI/搜索/CVE/验签/回源代理，典型如 K8s 同机房私有仓库、CI 镜像缓存、边缘节点；
• 选 Harbor：需要多租户项目空间、细粒度 RBAC、跨集群/跨机房复制、企业门户运维流程，且接受多组件部署与数据库运维成本；
• 选 distribution：只需要协议层仓库能力、上层自建控制台（不少云厂商与商业产品的底座即它），或作为临时/一次性仓库；
• 三者 API 层面同为 OCI Distribution Spec 实现，客户端工具（docker/skopeo/oras/cosign）可无缝复用，迁移成本主要在配置与权限模型。

八、参考链接

以下来源查询/核对日期均为 2026-11-01：

• 官网与文档：https://zotregistry.dev/v2.1.22/ （文档版本页）
• 代码仓库：https://github.com/project-zot/zot
• 发布页（v2.1.22，2026-10-06）：https://github.com/project-zot/zot/releases
• 关键特性：https://zotregistry.dev/v2.1.22/general/features/
• 发布镜像与平台矩阵：https://zotregistry.dev/v2.1.22/general/releases/
• Linux 裸机安装：https://zotregistry.dev/v2.1.22/install-guides/install-guide-linux/
• 配置参考：https://zotregistry.dev/v2.1.22/admin-guide/admin-configuration/
• 认证与授权：https://zotregistry.dev/v2.1.22/articles/authn-authz/
• 镜像同步（mirroring）：https://zotregistry.dev/v2.1.22/articles/mirroring/
• 签名验证：https://zotregistry.dev/v2.1.22/articles/verifying-signatures/
• zli 命令行指南：https://zotregistry.dev/v2.1.22/user-guides/zli/
• GitHub API 仓库元数据：https://api.github.com/repos/project-zot/zot 、 https://api.github.com/repos/goharbor/harbor 、 https://api.github.com/repos/distribution/distribution
• 徽章复核：https://img.shields.io/github/stars/goharbor/harbor 、 https://img.shields.io/github/stars/project-zot/zot

配套实验文档：部署实践见《Zot 2.1.22 Docker Compose 部署指南》，参数逐项详解见《Zot 2.1.22 配置参数详解》，客户端操作与签名校验实测见《Zot 2.1.22 客户端操作与签名校验指南》。