家用住宅主机Linux私有仓库内网加速镜像拉取

为什么家庭环境需要私有仓库

当你家里有多台设备（笔记本、树莓派、NAS）都运行Docker，每台机器从Docker Hub拉取同一个镜像时，既占用外网带宽又慢。
少量镜像还能忍受，但如果经常更新或部署，等待时间就会成倍增加。
自建一个内网私有仓库，先把常用镜像拉到本机，再让其他设备从内网拉取，速度直接满速跑满局域网带宽。

搭建前的准备

• 一台长时间开机的Linux主机（建议至少2GB内存、50GB空闲磁盘），系统推荐Ubuntu 20.04+或Debian 11+。
• 已安装Docker Engine（如果没装，先执行 curl -fsSL https://get.docker.com | sh）。
• Docker服务运行中，确认 docker info 无错误。
• 知道这台主机的局域网IP，例如 192.168.1.100。

搭建私有仓库的详细步骤

1. 拉取并启动Registry镜像

Docker官方提供了registry镜像，一行命令就能启动：

docker run -d \
  --name local-registry \
  --restart=unless-stopped \
  -p 5000:5000 \
  -v /opt/docker-registry:/var/lib/registry \
  registry:2

• -p 5000:5000 将本机的5000端口映射到容器。
• -v /opt/docker-registry:/var/lib/registry 是把持久化存储挂载到宿主机目录，避免容器删除后镜像丢失。
• --restart=unless-stopped 确保主机重启后容器自动启动。

2. 验证仓库是否正常运行

curl http://localhost:5000/v2/

如果返回 {} 或类似响应，说明仓库已启动。

3. 配置其他机器信任这个内网仓库

因为使用HTTP而非HTTPS，其他Docker客户端需要显式将该仓库列为insecure-registry，否则会报错。

在需要从内网拉镜像的机器上（包括本机），编辑 /etc/docker/daemon.json（如不存在则新建）：

{
  "insecure-registries": ["192.168.1.100:5000"]
}

保存后重启Docker服务：

sudo systemctl restart docker

4. 将公网镜像推送到私有仓库

在本机上先拉一个常用镜像（比如nginx），再标记并推送：

docker pull nginx:latest
docker tag nginx:latest 192.168.1.100:5000/nginx:latest
docker push 192.168.1.100:5000/nginx:latest

推送成功后，其他设备就可以通过 docker pull 192.168.1.100:5000/nginx:latest 从内网高速拉取。

容易踩的坑

• 防火墙阻挡：确保宿主机防火墙放行5000端口。Ubuntu使用 sudo ufw allow 5000/tcp。
• Docker daemon.json 配置错误：如果文件已有其他配置，请合并JSON，不要覆盖。重启Docker后才生效。
• 镜像命名必须含仓库地址：注意 tag 时必须加完整地址 主机IP:端口/镜像名:标签，否则push时会被当作Docker Hub的镜像。
• 磁盘空间不足：registry默认存储路径是容器内 /var/lib/registry，映射到宿主机时确保所在分区有足够空间。可以使用 du -sh /opt/docker-registry 检查大小。
• 重启后容器丢失：使用 --restart=unless-stopped 后，即使主机重启容器也会自动启动。如果不放心，可用 docker update --restart=unless-stopped local-registry 确保。

验证加速效果

在一台未拉取过nginx的其他设备上执行：

time docker pull 192.168.1.100:5000/nginx:latest

如果镜像已经在本地仓库，拉取几乎瞬间完成（几兆的速度取决于内网带宽）。
对比从公网拉取同镜像的时间，差异很明显。

你也可以用 docker system df 查看本机镜像占用，或定期清理不需要的旧镜像释放空间。

高频问题解答

Q：我的主机IP不固定怎么办？ 可以在路由器上为这台主机绑定静态IP或使用DHCP固定分配。
如果连主机名都记不住，也可以在每台机器的 /etc/hosts 里写一条记录，比如 192.168.1.100 myregistry，然后push/pull时用 myregistry:5000。

Q：能不能让仓库支持HTTPS？ 内网环境下不一定需要，但如果想避免改insecure-registries，可以申请内网CA证书或使用Let's Encrypt（需要公网域名和访问）。
家庭内网建议直接用HTTP加排除列表即可。

Q：如何迁移已经存在的镜像？ 在旧机器上 docker push 到新仓库，或者用 docker save/load 打包后拷过去再push。

如果你正在按本文步骤操作，建议先完整执行一遍，再根据实际环境微调。
遇到报错时，优先检查Docker daemon配置和防火墙。