Docker Registry 离线部署与私有镜像仓库运维指南-北京尧图网络

简介这份 registry.tar.gz 面向无法访问外网的 Docker 使用场景提供可离线导入的 Registry 镜像文件帮助运维与开发人员在内网快速搭建私有镜像仓库。包内共 18 个文件以 json 清单、tar 层数据、version 版本标记及 repositories 仓库索引为主分别用于描述镜像元信息、承载分层内容与记录版本和仓库映射压缩包整体约 25.15MB体积适中便于通过U盘或内网传输分发。已有 437 人学习下载说明其在离线部署需求中具有一定参考价值。使用者可借助该镜像包完成私有仓库的基础搭建与本地镜像集中管理减少对外网拉取的依赖同时可通过包内清单与层结构了解 Registry 镜像的组织方式为后续版本核对、离线迁移和内网仓库维护提供可操作的素材。适合具备一定 Docker 基础、需要在内网环境部署镜像服务的技术人员参考使用。1. registry.tar.gz 到手先判断二进制包还是镜像包内网 CI 的最后一步永远是docker push但出口封着只能自己搭一个。registry.tar.gz 就是干这件事的Docker Registry 2.x 的离线部署包解压、改一份 config.yml、起个进程5000 端口就成了一个既能 push 又能 pull 的私有镜像仓库。它解决的是没有外网、或者拉到一半被限速拉断的那类问题——镜像分发从「每台机器自己去公网拉」变成「内网一次进、全网分发」。这份包在实务里通常是两种形态官方 release 的 Go 二进制包解压出来只有一个registry可执行文件或者docker save导出的镜像包里面有 manifest.json 和一层层 layer.tar。形态判断错后面所有命令都是白费力气。适合自己搭 CI 缓存、做离线交付、或者要给几十台边缘机器一个统一镜像源的人。2. 解包与启动把 registry 从压缩包跑成能用服务2.1 用 tar -tzf 先看清包里装的是什么拿到包的第一件事不是解压是看目录。一条命令就能分辨形态别急着tar -xzf解到当前目录几十个 hash 目录铺满家目录的场景我见过不止一次。# 只看前 20 行不落盘 tar -tzf registry.tar.gz | head -n 20两种输出对应两条完全不同的落地路线输出特征形态落地方式只有registry、LICENSE、VERSION三个文件二进制包解压到 /opt/registrysystemd 托管出现manifest.json、repositories、64位hash/layer.tar镜像包docker load后以容器运行出现docker/registry/v2/blobs/...仓库数据目录不是部署包是备份走第 6 章迁移顺手把校验和记下来内网传文件走 U 盘、跳板机的中转次数多了包被截断的概率不低# 记录原始大小与 sha256后续任何异常先回来对这两个数 ls -l registry.tar.gz sha256sum registry.tar.gzhead的作用是防止大包刷屏-z表示按 gzip 解如果报not in gzip format说明包其实是未压缩的 tar 或者传坏了换tar -tf再试一次。校验这一步别省后面docker load报unexpected EOF十有八九就是包不完整。2.2 二进制方式五步起一个可写仓库二进制包的好处是没有容器依赖坏处是所有路径、用户、权限都得自己管。按顺序走这五步。# 1. 目录规划程序、数据、配置分开升级时只动 /opt install -d /opt/registry /var/lib/registry /etc/registry # 2. 解包并确认可执行 tar -xzf registry.tar.gz -C /opt/registry chmod x /opt/registry/registry /opt/registry/registry --version # 3. 专用低权限用户数据目录交给他 useradd --system --no-create-home --shell /usr/sbin/nologin registry chown -R registry:registry /var/lib/registry /opt/registry第 2 步的--version是必须的它能顺带验证这个二进制和当前内核架构是否匹配cannot execute binary file这种错在这一步就能拦住而不是等到 systemd 里看半天status203/EXEC。配置文件先写最小可用版# /etc/registry/config.yml version: 0.1 log: level: info formatter: text fields: service: registry storage: filesystem: rootdirectory: /var/lib/registry delete: enabled: true http: addr: :5000 health: storagedriver: enabled: true interval: 10s threshold: 3version: 0.1是配置格式版本不是软件版本别改。delete.enabled默认不开意味着删除镜像的 API 会直接返回 UNSUPPORTED很多人第一次删镜像失败就是漏了这一行。health.storagedriver打开后/debug/health会真的去写一次存储比单纯看端口通不通靠谱。然后交给 systemd别用nohup ./registry serve 这种跑法——SSH 一断进程就没了日志也跟着没# /etc/systemd/system/registry.service [Unit] DescriptionDocker Registry Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple Userregistry Groupregistry ExecStart/opt/registry/registry serve /etc/registry/config.yml Restartalways RestartSec3 LimitNOFILE65536 [Install] WantedBymulti-user.targetsystemctl daemon-reload systemctl enable --now registry systemctl status registry --no-pager curl -s http://127.0.0.1:5000/v2/ # 期望返回 {}LimitNOFILE65536不是凑数大镜像并发推的时候默认 1024 的文件描述符很容易打满表现是 push 到 80% 突然connection reset。Restartalways保证磁盘抖动导致的崩溃能自己起来配合RestartSec3避免疯狂重启刷日志。2.3 镜像方式docker load 之后别急着 docker run如果确认是镜像包先导入再看 tag不要凭印象写registry:2# 导入并确认实际 tag docker load -i registry.tar.gz docker images | grep -i registry# 起容器两个挂载点必须对数据目录和配置文件 docker run -d --name registry --restartalways \ -p 5000:5000 \ -v /srv/registry/data:/var/lib/registry \ -v /srv/registry/config.yml:/etc/docker/registry/config.yml:ro \ registry:2两个挂载路径是镜像内约定死的镜像里的默认配置指向/var/lib/registry和/etc/docker/registry/config.yml。只挂数据不挂配置你改的 config.yml 根本不会生效人在宿主机上改了半小时容器里跑的还是默认值——这种黑匣子式的困惑用docker exec registry cat /etc/docker/registry/config.yml一比就原形毕露。配置文件冒号后加:ro防止容器进程意外回写。数据目录/srv/registry/data要提前mkdir -pDocker 自动创建的空目录属主是 root容器内如果换了非 root 用户会写不进去。2.4 第一次 push 闭环三条命令验证到底通没通服务起来不等于能用最小闭环是 push 一个真实镜像再拉回来。# 打本地 tag注意仓库名格式是 host:port/name:tag docker tag nginx:1.25 127.0.0.1:5000/demo/nginx:1.25 # 推 docker push 127.0.0.1:5000/demo/nginx:1.25 # 从 API 侧确认别只信 docker 的返回 curl -s http://127.0.0.1:5000/v2/_catalog curl -s http://127.0.0.1:5000/v2/demo/nginx/tags/list期望看到{repositories:[demo/nginx]}和{name:demo/nginx,tags:[1.25]}。_catalog在仓库条目多的时候会分页加?n100并读响应头里的Link才能翻全。镜像名里的127.0.0.1:5000不能省成demo/nginx少了 host 部分 Docker 会默认往 Docker Hub 推。另外第一次 push 如果卡在Waiting很久先在宿主机curl一下/v2/服务端没起来和网络不通是两回事别混在一起查。3. config.yml 逐项拆解存储、监听、日志的参数怎么定3.1 log 段先让日志能对上号多实例或者多环境的时候日志里没有标识是最难受的——出问题翻日志一堆一模一样的行分不清是测试环境还是生产。log: accesslog: disabled: false # 打开访问日志push/pull 的每条请求都有记录 level: info # debug 会打出每次 blob 校验只在排障时开 formatter: text # 要接日志系统就换 json fields: service: registry environment: prod region: internalaccesslog.disabled: false是最值得开的一项默认它是关的导致客户端报 4xx/5xx 时服务端一片安静。开完之后每行包含 method、path、status、duration定位「谁在什么时候推了什么」非常直接。level调到debug会输出 blob 层的 digest 校验信息能查出「明明推上去了为什么 pull 下来 digest 不一致」这类问题但量极大日常别开。formatter: json配合 filebeat 之类的采集器更省事纯文本人眼看更舒服按团队习惯选。fields下挂的键值会附加到每一行日志值建议跟着部署环境走不要写死成某个具体业务名。3.2 storage 段目录布局与删除开关存储是 registry 最容易出事的地方参数不多但每个都影响数据安全。storage: filesystem: rootdirectory: /var/lib/registry maxthreads: 100 # 并发读写文件的上限机械盘要调低 delete: enabled: true # 不开则 DELETE API 全部返回 UNSUPPORTED cache: blobdescriptor: inmemory # 缓存 blob 描述符减少重复 stat maintenance: uploadpurging: enabled: true age: 168h # 超过 7 天的未完成上传视为垃圾 interval: 24h dryrun: falserootdirectory落盘后的结构是固定的docker/registry/v2/blobs/sha256/ab/abcdef.../data存实际层数据docker/registry/v2/repositories/name/_manifests/存清单引用。这个布局只能由 registry 自己维护手工 mv 或 rm 会把引用关系搞断之后 pull 报manifest unknown而 blobs 明明还在。maintenance.uploadpurging默认就开着但dryrun一定要确认是false。有人为了「安全」把它设成 true 又忘了改回来结果是每次 CI 中断留下的半截上传永远堆在磁盘里一年后磁盘告警才发现里面全是没用的 chunk。cache.blobdescriptor: inmemory对单机够用重启后缓存重建只影响启动后第一波请求的延迟。仓库规模上了几十万 blob 之后可以考虑换成redis但那是另一个量级的运维成本别一上来就上。3.3 http 段addr、host 与反代下的坑http: addr: :5000 host: https://registry.local:5000 # 影响响应里的 Location 头 headers: X-Content-Type-Options: [nosniff] http2: disabled: falseaddr: :5000表示监听所有网卡的 5000只给本机反代用的话写127.0.0.1:5000更安全。host这个字段很多人不填后果是 registry 在做分块上传时返回的Location用的是客户端请求里的 Host一旦中间隔了一层反代并改写 Host客户端就会去访问内网地址而失败报错通常是no such host或者莫名的重定向。headers下的X-Content-Type-Options: [nosniff]是官方默认值保留即可别删。http2.disabled保持 false但要注意如果前面挂的 nginx 已经做了 TLS 终止registry 自身就该跑 HTTPTLS 相关配置全部交给反代两边都配 TLS 会出现「反代连不上后端」这种低级的 502。3.4 用环境变量覆盖配置不动文件改参数容器化部署时改文件要重建镜像或者多挂一份配置环境变量覆盖更顺手。# 规则REGISTRY_ 前缀配置路径的层级点换成下划线全大写 REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY/srv/registry/data REGISTRY_HTTP_ADDR0.0.0.0:5000 REGISTRY_LOG_LEVELdebug REGISTRY_STORAGE_DELETE_ENABLEDtrue# 验证覆盖是否生效容器内看最终配置 docker exec registry cat /etc/docker/registry/config.yml docker logs registry 21 | head -n 20映射逻辑就是storage.filesystem.rootdirectory→REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY中间每一层用单个下划线连接。有一个边界要注意如果某个配置键本身名字里带下划线用环境变量表达会产生歧义这种情况别硬套老老实实改配置文件。环境变量只在启动时读一次改完必须docker restart或systemctl restart。还有一种情况是同时写了配置文件和环境变量环境变量优先级更高排查时先确认有没有残留的REGISTRY_*在.env或者 compose 文件里——docker inspect registry | grep -A20 Env一眼就能看出来。4. 认证与 TLS把裸奔的 5000 端口收口内网不等于可信网络一个没有任何认证的 registry 意味着任何能连上 5000 端口的人都能删你的镜像。4.1 htpasswd一行命令生成凭证文件registry 只认 htpasswd 格式认 bcrypt不认明文。# 有系统自带工具就用这套httpd-tools / apache2-utils htpasswd -Bbn deploy ChangeMe_2024 /etc/registry/htpasswd # 没装的话用官方 httpd 镜像里的 htpasswd效果一样 docker run --rm --entrypoint htpasswd httpd:2 \ -Bbn deploy ChangeMe_2024 /etc/registry/htpasswd chmod 640 /etc/registry/htpasswd chown root:registry /etc/registry/htpasswd三个参数各有含义-B指定 bcrypt不加就是 MD5 cryptregistry 直接拒绝-b表示密码从命令行给不加则交互输入-n表示结果打印到标准输出而不是写文件。生产环境建议去掉-b走交互输入避免密码进 shell 历史。密码用单引号包住含$、!、的密码在双引号里会被 shell 展开生成出来的 hash 对不上登录一直 401查半天以为是配置问题。挂进配置auth: htpasswd: realm: basic-realm # 401 响应里 WWW-Authenticate 的值 path: /etc/registry/htpasswdbcrypt 对超过 72 字节的密码会静默截断超长密码设了等于没设后半段密码策略里限制一下长度更稳。4.2 自签证书CN 和 SAN 两个都得对内网没有公网证书自签是常规操作但签发参数错了客户端一定翻车。install -d /etc/registry/certs openssl req -x509 -nodes -newkey rsa:4096 -days 3650 -sha256 \ -keyout /etc/registry/certs/registry.key \ -out /etc/registry/certs/registry.crt \ -subj /CCN/Ointernal/CNregistry.local \ -addext subjectAltNameDNS:registry.local,IP192.168.10.20 chmod 600 /etc/registry/certs/registry.key openssl x509 -in /etc/registry/certs/registry.crt -noout -text | grep -A2 Subject Alternative Name关键在-addext subjectAltName...。现代 Docker 客户端只看 SAN不看 CN只写 CN 的证书在客户端眼里就是「证书与主机名不匹配」。用 IP 访问就得把 IP 写进 SAN用域名访问就写 DNS两个都要就都列上逗号分隔。-days 3650是十年内网自签图省事可以但一定要在日历上记一笔证书过期那天的报错是certificate has expired or is not yet valid跟配置错误长得完全不一样。-addext需要 OpenSSL 1.1.1 以上老系统上没有这个参数得写一份带[v3_req]段的 openssl.cnf 用-config指定思路一样只是啰嗦。服务端挂上http: addr: :5000 host: https://registry.local:5000 tls: certificate: /etc/registry/certs/registry.crt key: /etc/registry/certs/registry.key4.3 客户端信任certs.d 目录名必须带端口服务端配好 TLS 只是第一步每台要 push 的机器都得信任这张自签证书。# 目录名必须是 host:port 的完整形式缺端口不生效 install -d /etc/docker/certs.d/registry.local:5000 cp /etc/registry/certs/registry.crt /etc/docker/certs.d/registry.local:5000/ca.crt systemctl restart docker文件名固定叫ca.crt不能改。目录名里端口是硬性要求——/etc/docker/certs.d/registry.local/这种写法对registry.local:5000完全不生效这是最典型的静默失败目录建了、证书拷了、docker 也重启了push 还是x509: certificate signed by unknown authority。用 IP 访问的场景目录名就写192.168.10.20:5000并且这个 IP 必须在证书 SAN 里。两者对不上证书信任链会卡在主机名校验这一关。证书要分发给所有节点不要指望每人手工cpCI 镜像构建节点统一走配置管理或者初始化脚本下发改动一处、全部生效。4.4 反向代理收口nginx 三处必须改想让 registry 走 443、走统一域名、顺便加访问控制就得挂反代。下面这份配置里三个参数是关键server { listen 443 ssl; server_name registry.local; ssl_certificate /etc/nginx/certs/registry.crt; ssl_certificate_key /etc/nginx/certs/registry.key; client_max_body_size 0; # 0 不限制大镜像必需 chunked_transfer_encoding on; # registry 分块上传依赖这个 location /v2/ { proxy_pass http://127.0.0.1:5000; proxy_set_header Host $http_host; # 透传带端口的 Host proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 900; # 大层上传别 60 秒就断 proxy_request_buffering off; # 边收边转发省磁盘 } }client_max_body_size 0不设默认 1MB推一个基础镜像立刻 413。chunked_transfer_encoding on不开分块上传协议走不通表现为 push 卡在某一层反复重试。proxy_set_header Host $http_host必须用$http_host而不是$host后者会丢掉端口registry 返回的 Location 头就少了:5000客户端跟着去连 443 之外的端口失败。proxy_request_buffering off加上之后上传的大层不会先在 nginx 落一份临时文件再转发省一半磁盘 IO。代价是后端必须撑得住慢速客户端registry 本身没问题。5. 避坑与排查五个把私有仓库搞挂的现场5.1 推送侧的三个经典报错现象docker push报http: server gave HTTP response to HTTPS client服务端日志里一条请求都没有。原因Docker 客户端默认只走 HTTPS 访问非 localhost 的仓库服务端跑的是明文 HTTP握手阶段就断了请求根本没到 registry。解决两条路要么按 4.2、4.3 上 TLS要么明确告诉客户端这是不安全仓库在/etc/docker/daemon.json里加{ insecure-registries: [192.168.10.20:5000] }改完systemctl reload docker再用docker info | grep -A5 Insecure Registries确认生效。注意这个字段是覆盖写已有配置要保留别整个文件重写。现象改完 daemon.jsonsystemctl restart docker直接失败所有容器停摆。原因JSON 里写了注释、末尾多了逗号、或者insecure-registries写成了下划线。Docker 启动时解析失败会拒绝启动而很多人是在生产机上直接改的。解决改之前先备份改完用python3 -m json.tool /etc/docker/daemon.json或jq . /etc/docker/daemon.json校验语法通过了再重启。远程操作时留一条回滚命令在手边别把自己关在门外。现象大镜像推送到 90% 左右断掉重试还是断在同一位置。原因反代的client_max_body_size或proxy_read_timeout卡住了也可能是服务端LimitNOFILE太小高并发时 fd 耗尽。解决按 4.4 把 nginx 三个参数改掉服务端 systemd unit 里加LimitNOFILE65536然后看journalctl -u registry有没有too many open files。磁盘满也会表现成类似症状df -h一起看。5.2 存储侧的坑删了镜像磁盘不降现象从仓库删了 tag、删了 manifestdu -sh /var/lib/registry一点没变。原因registry 的删除是软删除。删 manifest 只是把引用摘掉blobs/sha256/下的实际数据原封不动留在磁盘上必须跑垃圾回收才真正释放。解决按第 6 章顺序走删 tag → 删 manifest → 停写 →registry garbage-collect。另外注意共享层多个镜像共用同一个 base layer 时删掉其中一个镜像那一层也不会被回收因为还有别的 manifest 引用它。指望删一个镜像腾出 2GB 是不现实的。现象磁盘写满之后 push 全部失败清出空间了还是失败。原因上传中断留下的临时 chunk 还在registry 启动时扫描存储会报错退出或者清理逻辑把整个上传目录拖垮。解决先df -h确认清空间然后检查uploadpurging是否dryrun: false。恢复后先curl /v2/确认服务活着再跑一次 GC 清掉半截上传。5.3 排查顺序三条命令定位到底卡在哪一层遇到 push 失败别从代码改起按从近到远三层确认# 1. 服务端本身活没活 curl -sv http://127.0.0.1:5000/v2/ 21 | tail -n 20 # 2. 服务端日志有没有收到请求 journalctl -u registry -n 100 --no-pager | tail -n 30 # 3. 客户端认可不认可这个仓库 docker info 2/dev/null | grep -A5 Insecure Registries docker info 2/dev/null | grep -A5 Registry Mirrors第 1 条返回{}说明服务正常问题在客户端或网络返回connection refused说明进程没起来直接看第 2 条返回 TLS 相关错误说明证书链有问题回去查 4.2、4.3。第 3 条用来排除「配置没生效」——改完配置没重启 Docker、或者改的是另一个 daemon.json比如 systemd unit 里用--config-file指了别的路径这两种情况docker info一眼能看出来。日志里 401 说明认证没通过503 说明存储层有问题磁盘满、权限不对、目录不存在400 多半是路径或参数不规范。把状态码和后端日志对上比翻客户端那一句denied: requested access to the resource is denied有用得多。6. 垃圾回收与迁移验证把数据目录当成一等公民删除和回收必须拆开做顺序错了就是数据损坏。# 1. 拿 digest注意 Accept 头否则拿到的是 schema1 的清单 curl -sI -u deploy:pass \ -H Accept: application/vnd.docker.distribution.manifest.v2json \ https://registry.local/v2/demo/nginx/manifests/1.25 | grep -i docker-content-digest # 2. 删 manifest curl -X DELETE -u deploy:pass \ https://registry.local/v2/demo/nginx/manifests/sha256:xxxx # 3. 停写窗口内做 GC--dry-run 先跑一遍看清单 systemctl stop registry /opt/registry/registry garbage-collect --dry-run /etc/registry/config.yml | head -n 40 /opt/registry/registry garbage-collect --delete-untagged /etc/registry/config.yml systemctl start registryGC 期间绝对不能有写入边写边扫会让扫描器把正在被引用的 blob 判成孤儿删掉后果是部分镜像永远拉不全而且报错信息完全指不到根因。--delete-untagged顺手清掉没有 tag 的清单--dry-run先看一遍输出确认规模别在高峰期直接扫。迁移换机器时直接rsync -a整个rootdirectory保持属主和权限rsync -aHAX --delete /var/lib/registry/ newhost:/var/lib/registry/-H保硬链接、-A保 ACL缺了这两个标志blob 的硬链接会被展开成独立文件体积翻好几倍。迁完先跑 GC 的--dry-run能正常扫完不报错基本就说明数据完整。我踩过一次最疼的坑为了「省事」在业务高峰期跑 GC第二天有三分之一的镜像拉不下来回滚备份花了大半天。从那以后我每次动存储之前都强制走一遍「备份目录 → dry-run → 停写窗口 → 正式 GC → 抽查 pull」这五步一步不跳宁可多停五分钟。希望帮到你。本文还有配套的精品资源点击获取

Docker Registry 离线部署与私有镜像仓库运维指南

相关推荐

基于ATmega324PA与DRV8818PWPR的工业步进电机驱动方案设计与调试

DRV8818+STM32双极步进电机控制：硬件软件全解析

DRV8818PWPR与PIC32MX664F064L步进电机驱动方案实战

更多资讯

启动报Port 8088 was already in use？先查是谁占的

担心文档上云？本地运行的办公AI才敢放心用

先能用，再好用：从烂尾复盘到两周上线，全栈项目的‘原型—快速迭代‘方法论

深度思考模式把 ARC-AGI-2 从 17.6% 拉到 45.1%：对照 Gemini 3 Pro 的三份能力评测，看‘会思考‘改写了哪些边界

1.c++入门篇

《江灯合声》：有可行的分框版，也仍可以选择连续鸣谢

今日更新

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

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