macOS使用Colima时无法连接Docker daemon如何排查解决

问题现象 #

长期在Mac设备使用Docker Desktop出现频繁启动异常后，切换Colima（Container on Linux on Mac）作为容器运行时，通过homebrew安装Docker客户端并完成账号登录后，执行docker info返回连接报错：

$ docker info
Client:
 Context:    default
 Debug Mode: false

Server:
ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
errors pretty printing info

涉及环境信息：

• 操作系统：macOS Monterey 12.3.1 (21E258)
• Colima版本：0.4.2，runtime为docker，架构x86_64
• Docker客户端版本v20.10.17，服务端版本v20.10.11
• 内置Kubernetes版本：Client v1.24.1，Kustomize v4.5.4，Server v1.23.6+k3s1

排查解决步骤 #

按优先级依次操作：

• 确认Colima实例正常运行
  执行colima status查看实例运行状态，如果返回实例未启动，直接执行colima start启动实例即可。
  如果启动时报错、或存在之前异常退出的残留记录，可执行colima delete删除损坏的实例后重新执行colima start初始化。注意：该操作会清空Colima实例内存储的本地容器、镜像数据，请提前做好备份。
• 切换Docker上下文到Colima
  之前使用Docker Desktop时会生成专用的Docker上下文，卸载Docker相关组件后Docker客户端会默认回到default上下文，该上下文默认读取/var/run/docker.sock路径，和Colima默认的socket路径不匹配，是该报错最常见的诱因：
  • 执行docker context ls查看现有上下文列表，确认存在名为colima的上下文
  • 执行docker context use colima切换到Colima对应上下文
  • 如果没有自动生成colima上下文，可手动添加环境变量指定socket路径：执行export DOCKER_HOST="unix://$HOME/.colima/default/docker.sock"，将该行写入对应shell配置文件（~/.zshrc适配zsh、~/.bashrc适配bash）即可实现永久生效，避免每次打开终端重复配置。
• 清理Docker Desktop残留配置
  Docker Desktop卸载后可能残留无效的socket软链接、旧配置文件，导致连接路径异常：
  • 先备份~/.docker/config.json文件，该文件存储了docker login生成的账号凭证，避免配置丢失
  • 执行sudo rm -f /var/run/docker.sock删除残留的无效软链接
  • 执行colima restart重启Colima实例，重启过程会自动重新建立正确的socket映射。
• 修复socket文件权限
  执行ls -l ~/.colima/default/docker.sock查看socket文件权限配置，确认当前登录用户对该文件持有读写权限，如果权限配置异常，执行sudo chown $(whoami) ~/.colima/default/docker.sock修正权限即可。
• 升级Colima版本
  环境中使用的Colima 0.4.2为较早发布版本，存在x86架构下socket映射偶发失效的已知bug，上述步骤都无法解决问题时，可执行brew upgrade colima升级到最新稳定版后重新初始化实例。

验证方法 #

所有操作完成后执行docker info，如果可以正常返回Server端的运行时信息，无连接报错，即说明问题修复。

内容的提问来源于stack exchange，提问作者Siddiqui Noor