返回博客列表

30分钟用zot搭建私有OCI镜像仓库

38 次阅读 0 点赞 0 评论 8 分钟原创技术教程

本文带你快速部署 zot 私有镜像仓库，完成基础认证、镜像推送/拉取、按需同步与垃圾回收配置。解决内网镜像管理痛点，适合需轻量级替代方案的团队。

#Docker #镜像仓库 #OCI #zot #DevOps #私有仓库

30分钟用zot搭建私有OCI镜像仓库

开篇：你还在被镜像仓库折磨吗？

团队迁移服务时遇到了典型问题：Docker Hub公开仓库拉取慢，Harbor依赖和配置太重。实际需求很简单：内网搭建私有镜像仓库，能推能拉、支持基础认证与同步。

zot 是纯 Go 编写的 OCI-native 容器镜像仓库，完全遵循 OCI 规范，提供轻量、可扩展的替代方案。本文将带你完成从部署到核心功能配置的全流程。

你将完成以下实操任务：

  1. 在 Linux 机器上部署 zot 并启动服务
  2. 配置基础认证和文件存储路径
  3. 成功推送和拉取私有容器镜像
  4. 掌握镜像同步与垃圾回收配置方法

前置条件

确保环境满足以下基础要求：

  • 操作系统：Linux（以 Ubuntu 22.04 为例，其他发行版操作逻辑相同）
  • Docker：已安装并正常运行（用于镜像测试）
  • 网络：可访问 GitHub 下载资源
  • 知识储备：了解 Docker 基础命令和容器镜像概念即可

无需 Go 语言经验，zot 提供开箱即用的预编译二进制文件。

快速部署 zot 实例

下载与安装

zot 采用静态编译，单个二进制即可运行：

bash 复制代码 
## 下载 Linux amd64 版本（按需替换架构标识）
wget https://github.com/project-zot/zot/releases/latest/download/zot-linux-amd64

## 赋予权限并安装到系统路径
chmod +x zot-linux-amd64
sudo mv zot-linux-amd64 /usr/local/bin/zot

## 验证版本
zot --version

macOS 用户替换为 zot-darwin-amd64，ARM 架构使用 zot-linux-arm64。

创建配置目录与文件

bash 复制代码 
mkdir -p /opt/zot/config /opt/zot/data

生成 /opt/zot/config/zot.json 基础配置：

json 复制代码 
{
  "storage": {
    "rootDirectory": "/opt/zot/data"
  },
  "http": {
    "address": "0.0.0.0",
    "port": "5000"
  },
  "log": {
    "level": "info"
  }
}

配置要点：

  • rootDirectory：镜像实际存储路径，预留充足磁盘空间
  • address 设为 0.0.0.0 开放外部访问，本地调试可改 127.0.0.1
  • 端口 5000 与 Docker Registry 默认端口一致，便于后续替换

启动服务

bash 复制代码 
## 前台启动（调试模式）
zot serve /opt/zot/config/zot.json

## 生产环境后台运行
nohup zot serve /opt/zot/config/zot.json > /opt/zot/zot.log 2>&1 &

访问 http://<IP>:5000/v2/ 返回 {} 即表示 OCI API 就绪。

镜像推送与拉取实战

配置 Docker 信任

未配置 HTTPS 时 Docker 会拒绝连接，需添加信任策略：

bash 复制代码 
sudo vim /etc/docker/daemon.json

追加配置：

json 复制代码 
{
  "insecure-registries": ["<你的IP地址>:5000"]
}

重启 Docker 生效：

bash 复制代码 
sudo systemctl restart docker

安全提醒： 生产环境必须配置 TLS 证书，zot 支持 http.tls 字段指定 cert 和 key 路径。

推送测试镜像

bash 复制代码 
## 拉取公开镜像
docker pull nginx:alpine

## 重定向标签
docker tag nginx:alpine <你的IP地址>:5000/my-nginx:1.0

## 推送到 zot
docker push <你的IP地址>:5000/my-nginx:1.0

成功时显示类似输出：

复制代码 
The push refers to repository [<IP>:5000/my-nginx]
xxxxx: Pushed
1.0: digest: sha256:xxxxx size: xxx

验证拉取功能

bash 复制代码 
## 清理本地镜像
docker rmi <你的IP地址>:5000/my-nginx:1.0

## 重新拉取
docker pull <你的IP地址>:5000/my-nginx:1.0

## 验证存在
docker images | grep my-nginx

进阶配置指南

Htpasswd 认证

bash 复制代码 
## 安装工具
sudo apt-get install apache2-utils -y

## 创建认证文件
cd /opt/zot/config
htpasswd -Bbc htpasswd admin password123

更新 zot.json 添加认证：

json 复制代码 
{
  "http": {
    "address": "0.0.0.0",
    "port": "5000",
    "auth": {
      "htpasswd": {
        "path": "/opt/zot/config/htpasswd"
      }
    }
  }
}

重启后操作需通过 docker login <IP>:5000 认证。

镜像按需同步

配置 sync 字段实现拉取缓存：

json 复制代码 
{
  "sync": {
    "credentialsFile": "/opt/zot/config/credentials.json",
    "registries": [
      {
        "urls": ["https://index.docker.io/v1/"],
        "onDemand": true,
        "tlsVerify": true,
        "maxRetries": 3,
        "content": [
          {
            "destination": "local-nginx",
            "tags": {
              "regex": "alpine"
            }
          }
        ]
      }
    ]
  }
}

注意：同步功能需使用带 sync tag 的预编译版本（文件名含 -sync 后缀）。

垃圾回收（GC）

定期清理未引用镜像层释放空间：

bash 复制代码 
zot gc /opt/zot/config/zot.json

建议配置 cron 定时任务在低峰期执行。

常见问题排查

  1. 推送报证书错误：确认已添加 insecure-registries 或配置有效 TLS 证书
  2. 403 认证失败：检查 htpasswd 路径权限及密码正确性
  3. 磁盘空间告急：优先执行 GC 清理，配置存储监控阈值（建议 80%）
  4. 同步功能不可用：确认使用的二进制包含 sync tag（文件名后缀 -sync）

总结

通过单二进制部署、JSON 配置与标准 OCI 协议支持，zot 大幅降低了私有镜像仓库的运维门槛。对比传统方案，其轻量特性完美契合中小团队的内网镜像管理需求。

延伸探索方向：

  • 使用 Nginx/Traefik 配置反向代理与 HTTPS
  • 集成 cosign 实现镜像签名验证
  • 通过 systemd 或 Docker Compose 管理生产级部署

仓库地址：https://github.com/project-zot/zot
官方文档：https://zotregistry.dev

遇到具体问题欢迎在评论区讨论交流！

最后更新：2026-09-05T10:02:09

评论 (0)

发表评论

blog.comments.form.loading
0/500
加载评论中...