k3s配置内网非TLS私有registry后拉镜像仍跳转Docker Hub报错
你遇到的拉取跳转Docker Hub、镜像拉取失败的核心原因有三个:
- containerd的镜像地址解析规则触发了自动fallback:k3s内置的containerd判定镜像名时,如果第一个斜杠前的部分(也就是通常写registry地址的位置)既不包含端口号、也没有点分隔的域名结构(比如类似
192.168.1.100:10000、my-registry.local这种),会直接把这部分当成Docker Hub上的个人命名空间,自动拼接成docker.io/xxx路径,根本不会去匹配你写的mirror规则——这就是你日志里出现拉取docker.io/pwlaptopregistry/xxx报错的直接原因。 - 非加密HTTP的私有registry没有在配置里标记跳过TLS校验:containerd默认会尝试用HTTPS连接外部registry,你的私有registry是纯HTTP服务,就算匹配到规则也无法完成加密握手。
- 常规Docker的
daemon.json配置在k3s场景完全无效:k3s托管的内置containerd不会读取系统独立Docker的配置文件,所有registry访问规则全部由/etc/rancher/k3s/registries.yaml管控,不需要在节点上安装Docker、也不需要修改daemon.json。
1. 修正私有registry配置文件
编辑树莓派上的/etc/rancher/k3s/registries.yaml,替换成如下内容(把<笔记本服务器IP>换成实际的局域网IP,比如192.168.1.100):
mirrors: # 键名和后续镜像地址的registry部分保持一致 "<笔记本服务器IP>:10000": endpoint: - "http://<笔记本服务器IP>:10000" # 配置对应registry的访问规则,跳过TLS校验 configs: "<笔记本服务器IP>:10000": tls: insecure_skip_verify: true
如果你想保留自定义的registry域名前缀,不需要每次写IP和端口,需要满足containerd的外部registry识别规则:前缀必须是带点的域名格式(比如
pwlaptopregistry.local),然后在树莓派的/etc/hosts文件里加一行映射:<笔记本服务器IP> pwlaptopregistry.local,再把registries.yaml里的配置键、Deployment里的镜像地址里的registry部分全部替换成pwlaptopregistry.local:10000,避免被containerd误判成Docker Hub的命名空间。
2. 修正Deployment里的镜像地址
把Deployment里的镜像值,从原来的pwlaptopregistry/tcpserialpassthrough:vers1.3-arm,替换成对应配置里的registry地址:
- 直接用IP访问的写法:
image: <笔记本服务器IP>:10000/tcpserialpassthrough:vers1.3-arm - 用自定义域名映射的写法:
image: pwlaptopregistry.local:10000/tcpserialpassthrough:vers1.3-arm
3. 让配置生效
重启k3s服务,让内置containerd重新加载registry规则:sudo systemctl restart k3s
可以执行sudo crictl info | grep -A 10 registry检查containerd的registry配置是否正常加载,确认规则已经生效。
4. 解决之前的调度端口报错
你的日志里存在端口占用导致的调度失败提示:1 node(s) didn't have free ports for the requested pod ports,执行以下命令检查树莓派上的8001端口占用情况,杀掉占用进程或者清理残留的旧Pod:ss -tulpn | grep 8001
- 你之前配置的Basic Auth鉴权如果对应的registry服务本身没有开启鉴权逻辑,直接删掉对应配置即可,额外的鉴权配置反而会导致握手失败。
- 不要额外在节点上安装Docker,k3s使用内置的containerd作为容器运行时,和独立安装的Docker配置完全隔离,装了Docker也不会帮你解决镜像拉取的问题。
- 配置完成后可以手动执行拉取测试:
sudo crictl pull <笔记本服务器IP>:10000/tcpserialpassthrough:vers1.3-arm,确认可以正常拉取后再重新部署Deployment。
内容的提问来源于stack exchange,提问作者Paul

