Kamal部署中IPv6网络连接问题的解决方案

在使用Kamal部署Rails应用到云服务器时，开发者可能会遇到一个特殊问题：当尝试连接仅支持IPv6的外部数据库（如Supabase的免费版）时，应用容器内会出现"Network Unreachable"错误，而直接在主机上使用相同连接参数却能正常工作。

问题根源分析

这个问题源于Kamal默认创建的Docker网络配置。Kamal在部署过程中会自动创建一个名为"kamal"的Docker网络，但默认情况下这个网络仅支持IPv4协议。当应用容器尝试通过IPv6地址连接外部服务时，由于底层网络不支持IPv6，导致连接失败。

解决方案

Kamal团队确认不会默认启用IPv6支持，因为这可能在某些环境中无法正常工作。但开发者可以通过以下方式自行解决：

1. 手动创建支持IPv6的Docker网络： 在部署前，手动创建一个名为"kamal"且支持IPv6的Docker网络。Kamal在部署时如果发现同名网络已存在，会直接使用而不再创建新网络。

2. 使用pre-deploy钩子自动创建： 更优雅的解决方案是在Kamal的pre-deploy钩子中添加网络创建命令，确保每次部署前网络配置正确：

# .kamal/hooks/pre-deploy
set -e
docker network create --ipv6 kamal || true

实现原理

Kamal的默认网络创建逻辑非常简单，仅执行基本的docker network create kamal命令。通过提前创建同名网络并添加--ipv6参数，我们实际上覆盖了Kamal的默认行为，同时保持了网络名称的一致性。

注意事项

1. 此解决方案需要服务器和Docker环境本身支持IPv6
2. 在某些云服务提供商处，可能需要额外配置才能启用IPv6支持
3. 确保网络名称"kamal"与Kamal配置中使用的网络名称一致

最佳实践建议

对于需要连接IPv6服务的项目，建议将网络创建命令纳入部署流程管理，可以考虑：

1. 在项目文档中明确记录这一配置要求
2. 在CI/CD流程中加入网络检查步骤
3. 对于团队项目，确保所有成员了解这一特殊配置

通过这种方式，开发者可以在保持Kamal简洁性的同时，灵活应对IPv6连接需求。