OSX M1设备使用Colima时Docker端口映射后未监听问题

适用场景 #

同时满足以下条件时，本方案可修复对应问题：

• 设备为M1及后续Apple Silicon系列芯片的Mac电脑
• 运行系统为macOS
• 使用Colima作为Docker容器运行时

典型异常表现 #

• 执行docker port <容器ID/容器名>可查询到正常的端口映射规则
• 启动容器时明确添加了-p端口映射参数，例：docker run -p 80:80 --name mycontainer myimage
• 用netstat、lsof等工具检测宿主机端口时，对应映射端口未处于监听状态，本地无法通过localhost/127.0.0.1访问容器服务

根因说明 #

低版本Colima默认使用Qemu虚拟化模式启动虚拟机时，在Apple Silicon架构下存在已知的端口转发bug，虚拟机侧的Docker端口规则无法自动同步到宿主机网卡，和Docker本身的端口配置无关。

永久修复步骤 #

1. 先将Colima升级到0.5.0及以上稳定版本，使用Homebrew升级执行命令：
   brew upgrade colima
2. 停止当前运行的Colima实例：
   colima stop
3. 删除旧的Colima实例：由于QEMU和VZ虚拟化模式的实例不兼容，无法直接在原有实例上修改虚拟化类型，需要删除旧实例后重建。如果本地容器存有重要数据，建议先通过docker commit保存为镜像、或把容器内数据拷贝到本地目录备份后再执行以下命令：
   colima delete
4. 使用VZ虚拟化模式重新创建并启动Colima实例，明确指定架构与网络配置：
   colima start --arch aarch64 --vm-type vz --network-address
5. 等待实例启动完成后，正常启动带端口映射的容器即可，例：
   docker run -p 80:80 --name mycontainer myimage
6. 验证端口状态，执行以下命令可看到对应端口已被正常监听：
   lsof -i :80

临时修复方案（无需重建Colima实例） #

如果暂时不想重建实例，可通过Colima自带的SSH能力手动做端口转发，该方式在Colima或终端重启后失效，适合紧急调试场景：
colima ssh -- -L <宿主机端口>:localhost:<容器映射端口> -N
例：转发80端口时执行colima ssh -- -L 80:localhost:80 -N，执行后保持终端窗口不关闭即可正常访问。

注意：如果使用上述方案后仍无法访问，请检查容器内服务是否绑定了0.0.0.0地址而非仅绑定127.0.0.1，容器内服务绑定环回地址时外部无法通过映射端口访问。

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