离线环境搭建私有镜像仓库：registry.tar.gz 安装与避坑指南-北京尧图网络

简介面向无法访问外网的内网环境这份资源提供了一套可直接导入的 Docker Registry 镜像文件帮助运维与开发人员在隔离网络中快速搭建私有镜像仓库免去在线拉取镜像的困扰。压缩包共 18 个文件以 json 元数据、tar 层数据、version 版本标识及 repositories 仓库索引为主完整保留了镜像的分层结构与清单信息整体约 25.15MB体积轻量便于内网传输与分发。已有 436 人学习下载适合需要离线部署容器基础设施的中级技术人员参考。借助这些文件读者可省去自行导出镜像的步骤直接获得可用的 Registry 镜像素材理解镜像分层与清单组织方式并据此完成私有仓库的导入与启动为内网镜像托管、团队协作与后续运维排错打下基础。1. 拿到 registry.tar.gz 先别急着 docker load一个离线镜像仓库的安装现场上周帮一个做内网交付的朋友处理环境对方甩过来一个registry.tar.gz说“装个私有镜像仓库机器不能出网”。我第一反应不是解压而是先问清楚三件事目标机器有没有 Docker、这个包是镜像 tar 还是仓库数据目录、端口 5000 有没有被占。因为registry.tar.gz这个名字太容易让人误会——它可能是docker save出来的镜像归档也可能是整个 registry 存储目录的打包甚至可能是别人把二进制和配置一起塞进去的混合包。装错方向后面全是无用功。私有 registry 在离线交付、内网 CI、多机镜像分发里几乎是标配装不好会怎样轻则docker push报http: server gave HTTP response to HTTPS client重则仓库起来但数据目录权限不对重启一次镜像全丢。这篇笔记按“先验包、再装 Docker、再起 registry、最后验证推送拉取”的顺序走适合第一次在内网搭 registry 的开发者也适合已经装过但被 TLS 和存储路径坑过的熟手。2. 装前环境核对Docker 版本、端口与磁盘先过一遍2.1 确认 registry.tar.gz 到底是什么拿到包先别tar -xzf一把梭先看文件列表和大小。常见做法是先tar -tzf只列内容不解压判断它是镜像归档还是目录打包。# 只看包内前 30 个条目判断包的类型 tar -tzf registry.tar.gz | head -30 # 看包大小镜像 tar 通常几百 MB 起纯配置包很小 ls -lh registry.tar.gz如果列表里出现manifest.json、repositories、若干layer.tar或sha/layer.tar基本是docker save出来的镜像归档后面走docker load。如果出现docker/registry/v2/这种路径说明是 registry 的存储目录打包解压后要挂到容器的/var/lib/registry。如果出现registry二进制加config.yml那是二进制部署方式和容器方式不能混着来。这一步判断错后面所有命令都是白费。提示包名带.tar.gz不代表一定是镜像归档内网交付里把存储目录打包的情况很常见先tar -tzf看一眼能省半小时。2.2 Docker 版本与内核参数核对registry 官方镜像对 Docker 版本要求不苛刻但太老的 Docker比如 1.x 早期在docker load大镜像时容易出问题。我一般要求目标机 Docker 不低于 20.10用下面两条命令确认版本和存储驱动。# 确认 Docker 客户端与服务端都在跑版本不低于 20.10 docker version --format {{.Server.Version}} # 看存储驱动overlay2 是当前主流devicemapper 老环境要留意 docker info --format {{.Driver}}docker version --format {{.Server.Version}}只取服务端版本比整段输出干净。如果这条命令报Cannot connect to the Docker daemon说明 Docker 没起或者当前用户不在 docker 组先解决这个再谈 registry。存储驱动如果是overlay2就放心走如果是vfs镜像层多的时候磁盘会涨得很快内网小机器要提前算空间。端口方面registry 默认监听 5000先确认没被占# 检查 5000 端口占用有输出说明已被别的服务占了 ss -lntp | grep :5000如果 5000 被占起 registry 时把宿主端口换成 5001 之类容器内仍是 5000映射写-p 5001:5000即可。磁盘至少留出镜像总量两倍的空间registry 的 blob 存储和临时解压都会吃盘。2.3 离线环境的前置依赖不能出网的机器docker load本身不需要外网但如果包是二进制方式可能缺ca-certificates之类的基础包。我一般先确认两件事系统时间是否准确TLS 证书校验依赖时间以及curl是否可用后面验证要用。# 时间偏差太大会导致后续 TLS 校验失败先看一眼 date # 确认 curl 存在验证 registry 接口时要用 command -v curl || echo curl missing时间偏差超过几分钟后面配 HTTPS 时证书会直接报 not yet valid 或 expired这种问题排查起来很玄学不如装之前就对齐。curl缺失的话用wget替代也行但 registry 的/v2/接口用curl -I看响应头最直观。3. 安装 Docker 与加载 registry 镜像load、tag、run 三步别跳3.1 安装或确认 Docker 可用如果目标机还没装 Docker离线环境一般用系统包管理器装本地 rpm/deb或者用官方静态二进制。这里不展开系统包细节重点确认装完后systemctl能拉起服务。# 启动并设开机自启老系统没有 systemctl 的用 service docker start systemctl enable --now docker # 确认服务状态active (running) 才算过 systemctl is-active dockerenable --now一条命令同时做开机自启和立即启动比先enable再start少一步。is-active返回active就继续返回inactive或failed先看journalctl -u docker -n 50的日志常见是存储目录权限或 SELinux 拦截。3.2 加载镜像归档并确认 tag如果 2.1 判断是镜像归档直接docker load。加载完镜像的 tag 可能是registry:2也可能是别人重新 tag 过的名字用docker images确认。# 加载镜像归档输出会显示 Loaded image: xxx docker load -i registry.tar.gz # 过滤出 registry 相关镜像确认 tag 和镜像 ID docker images | grep -i registrydocker load -i指定输入文件比docker load registry.tar.gz更明确。加载后如果 tag 是none说明归档里没带 tag需要手动docker tag IMAGE_ID registry:2补一个。我一般统一 tag 成registry:2后面docker run引用方便也避免不同人环境里 tag 不一致。如果 2.1 判断是存储目录打包这一步跳过docker load改为解压到宿主机目录# 存储目录方式解压到 /data/registry-data注意保留目录结构 mkdir -p /data/registry-data tar -xzf registry.tar.gz -C /data/registry-data # 确认解压后能看到 docker/registry/v2 结构 ls /data/registry-data-C指定解压目标目录避免污染当前目录。解压后如果多了一层顶层目录挂载时路径要跟着调整这一点后面 4.2 会讲。3.3 启动 registry 容器的最小命令先用最小参数把容器跑起来确认能起再补配置。最小命令只做端口映射和存储挂载# 最小启动宿主 5000 映射容器 5000数据挂到 /data/registry docker run -d \ --name registry \ --restartalways \ -p 5000:5000 \ -v /data/registry:/var/lib/registry \ registry:2-d后台运行--restartalways保证机器重启后容器自动拉起内网仓库最怕重启后没人手动起。-v /data/registry:/var/lib/registry把容器内存储目录挂到宿主机容器删了数据还在。如果 3.2 是存储目录方式这里-v的宿主路径要指向解压出来的实际数据目录比如/data/registry-data/docker/registry/v2的上一级具体看解压结构。启动后立刻看日志# 看容器日志正常会输出 listening on [::]:5000 docker logs --tail 20 registry日志里出现listening on和version基本就起来了。如果容器秒退docker logs会给出原因常见是端口占用或挂载路径权限不对。4. 配置 registry端口、存储、TLS 与认证的取舍4.1 用配置文件替代一长串环境变量最小命令能跑但生产内网一般要调存储删除、日志级别、TLS。registry 支持-v config.yml:/etc/docker/registry/config.yml挂配置文件比堆环境变量清晰。先写一个基础版version: 0.1 log: level: info storage: filesystem: rootdirectory: /var/lib/registry delete: enabled: true http: addr: :5000 headers: X-Content-Type-Options: [nosniff]delete.enabled: true允许通过 API 删除镜像不开的话docker push覆盖同名 tag 会留垃圾 blob磁盘只涨不降。rootdirectory要和容器挂载路径一致改这里不改挂载等于白改。http.addr: :5000监听所有网卡 5000 端口只在内网用可以保持 HTTP后面 4.3 再讲 TLS。启动时挂配置# 先删旧容器再按配置重启数据在宿主机不受影响 docker rm -f registry docker run -d \ --name registry \ --restartalways \ -p 5000:5000 \ -v /data/registry:/var/lib/registry \ -v /data/registry-config/config.yml:/etc/docker/registry/config.yml \ registry:2docker rm -f强制删旧容器因为数据在宿主机卷里删容器不丢镜像。配置文件路径我习惯放/data/registry-config/和存储目录分开备份时清楚哪些是配置哪些是数据。4.2 存储路径与权限最容易翻车的一处registry 容器默认以 root 跑挂载目录权限一般不是问题但如果宿主机开了 SELinux 或用了非 root 运行就会出permission denied。常见做法是先给目录放权再确认 SELinux 状态。# 建目录并给足权限内网环境图省事直接 755 mkdir -p /data/registry chmod -R 755 /data/registry # 看 SELinux 是否 enforcingenforcing 时挂载要加 :z 标签 getenforce如果getenforce返回Enforcing-v挂载要写成-v /data/registry:/var/lib/registry:z让容器有写权限。返回Permissive或Disabled就不用加。这一条血泪经验来自一次内网机器容器日志一直报mkdir /var/lib/registry/docker: permission denied查了半天是 SELinux 拦的加:z立刻好。另外存储目录不要放在/tmp或会被清理的路径registry 数据被清等于镜像全丢。我一般固定/data/registry并在部署文档里写死避免不同人换路径导致数据分散。4.3 HTTP 还是 TLS内网环境的实际取舍registry 默认走 HTTPDocker 客户端对非 localhost 的 HTTP registry 默认拒绝会报http: server gave HTTP response to HTTPS client。内网两种做法配insecure-registries走 HTTP或者上自签 TLS。前者快后者规范看交付要求。走 HTTP 的话在每台要推拉的机器上改 Docker 配置{ insecure-registries: [192.168.1.10:5000] }把这段写进/etc/docker/daemon.json然后systemctl reload docker或重启 Docker。注意 IP 和端口要写实际 registry 地址写localhost只对本机生效。改完用docker info看Insecure Registries段是否包含该地址。走 TLS 的话需要证书和私钥配置里加http: addr: :5000 tls: certificate: /etc/docker/registry/certs/domain.crt key: /etc/docker/registry/certs/domain.key证书路径要挂进容器且客户端要信任该 CA。内网自签证书的常见坑是证书 SAN 没写 IPDocker 校验主机名失败生成证书时subjectAltName要把 IP 写进去。这一块比 HTTP 多不少步骤如果只是内网几台机器用insecure-registries更省事如果交付要求加密传输再上 TLS。4.4 加一层基础认证裸 registry 谁都能推镜像内网也不该完全裸奔。registry 自带 htpasswd 认证先生成密码文件# 安装 htpasswd 工具httpd-tools 或 apache2-utils生成密码文件 htpasswd -Bbn admin YourStrongPass /data/registry-config/htpasswd-B用 bcrypt 加密-b从命令行取密码-n输出到标准输出。生成后配置里加auth: htpasswd: realm: basic-realm path: /etc/docker/registry/htpasswd挂载时把 htpasswd 文件挂到对应路径重启容器。之后docker login 192.168.1.10:5000输入账号密码才能推拉。密码文件权限建议 600别让普通用户读到。5. 避坑与排查registry 起不来、推不上去的常见现场5.1 容器起来但 docker push 报 HTTPS 错误现象docker push报http: server gave HTTP response to HTTPS client。原因客户端把 registry 当 HTTPS 访问但服务端是 HTTP。解决在客户端/etc/docker/daemon.json加insecure-registries重启 Docker再docker info确认生效。注意改的是推拉镜像那台机器的配置不是 registry 宿主机的。5.2 日志报 permission denied 但目录权限看着没问题现象容器日志mkdir /var/lib/registry/docker: permission deniedls -l看目录是 755。原因SELinux enforcing 拦截了容器挂载写入。解决getenforce确认挂载加:z标签或临时setenforce 0验证验证完记得改回。长期方案是加标签而不是关 SELinux。5.3 重启后镜像全没了现象容器重启或重建后docker pull拉不到之前推的镜像。原因启动时没挂-v数据写在容器层容器删了数据跟着没。解决确认-v /data/registry:/var/lib/registry存在且config.yml里rootdirectory和挂载路径一致。已经丢了的只能重新推所以第一次启动就要把挂载写对。5.4 磁盘只涨不降删了镜像空间不释放现象docker push覆盖同名 tag 后磁盘持续增长删镜像也不降。原因delete.enabled没开或者开了但没跑垃圾回收。解决配置里开delete.enabled: true删镜像后进容器跑registry garbage-collect /etc/docker/registry/config.yml。注意 GC 期间最好停写内网低峰期做。5.5 5000 端口被占导致容器秒退现象docker run后容器立刻退出docker logs报listen tcp :5000: bind: address already in use。原因宿主机 5000 被别的服务占用。解决ss -lntp | grep :5000找到占用进程换端口映射-p 5001:5000客户端地址跟着改成 5001。别直接杀占用进程先确认那是什么服务。6. 装完怎么验证从 /v2/ 接口到一次完整推拉registry 装完不能只看容器Up就收工要按“接口通、能推、能拉、重启还在”四步验。先验接口# 无认证时返回 200有认证时返回 401 也算接口通 curl -I http://192.168.1.10:5000/v2/ # 有认证时带账号密码验返回 200 说明认证也通 curl -u admin:YourStrongPass -I http://192.168.1.10:5000/v2//v2/是 registry 的健康检查接口返回 200 或 401 都说明服务在监听401 只是没带认证。返回connection refused说明容器没起或端口没映射对。然后做一次完整推拉用一个小镜像避免传大文件# 拉一个小镜像重新 tag 到私有仓库地址 docker pull busybox:latest docker tag busybox:latest 192.168.1.10:5000/demo/busybox:v1 # 推送成功会显示 pushed docker push 192.168.1.10:5000/demo/busybox:v1 # 删本地镜像再从仓库拉验证真的存进去了 docker rmi 192.168.1.10:5000/demo/busybox:v1 docker pull 192.168.1.10:5000/demo/busybox:v1docker tag的仓库地址必须和客户端insecure-registries里写的一致差一个端口都推不上去。docker rmi删本地再pull能拉下来才说明数据真在 registry 里而不是本地缓存骗人。最后验重启存活# 重启容器再拉一次确认数据没丢 docker restart registry docker pull 192.168.1.10:5000/demo/busybox:v1重启后还能拉说明挂载和--restartalways都生效。我一般还会看一眼存储目录里有没有 blob# 确认宿主机存储目录下有数据不是空目录 du -sh /data/registrydu -sh有几百 KB 以上说明数据落盘了。从那以后我每次装完 registry都强制走一遍“接口 → 推 → 删本地 → 拉 → 重启再拉”这条链少一步都可能在上线当天才发现问题。希望帮到你。本文还有配套的精品资源点击获取

离线环境搭建私有镜像仓库：registry.tar.gz 安装与避坑指南

相关推荐

C# PACS源码拆解：DICOM收片归档与WinForms阅片端

C# 连接 Excel 报错 Microsoft.Office.Core 缺失？office.dll 引用配置指南

Windows上运行APK全攻略：兼容层与模拟器方案对比及故障排查

更多资讯

协同克里金法原理与ArcGIS实战：破解多变量空间插值失效之谜

MQL4编程入门：从变量、数组到自定义指标的核心避坑指南

MATLAB信号处理实验全流程：从序列生成到FFT频谱分析与采样定理验证

麦语言函数实战避坑指南：REF、#IMPORT与L2盘口的正确用法

WPF+Socket六轴机器人通讯调试器：粘包拆包与心跳保活

GROMACS蛋白-小分子模拟NPT崩溃排查与全流程闭环方案

今日更新

Verilog实现FPGA密码锁：矩阵键盘与状态机设计实战

数据服务监控运维实战：从指标体系到告警治理与故障排查

FreeRTOS任务通知实战详解：内核原理、API与避坑指南

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？