One-API 连接 Ollama 服务的 IPv6 访问问题分析与解决方案

问题背景

在使用 One-API 作为大模型 API 统一管理平台时，许多开发者会选择将其与本地部署的 Ollama 服务集成。然而，在实际部署过程中，一个常见的技术问题出现了：当 One-API 运行在 Docker 容器中时，尝试通过 localhost 访问宿主机的 Ollama 服务会导致连接失败。

问题现象

具体表现为在 One-API 管理界面配置 Ollama 渠道后，进行连接测试时会收到如下错误信息：

do request failed: Post "http://localhost:11434/api/chat": dial tcp [::1]:11434: connect: connection refused

这个错误表明 One-API 容器尝试通过 IPv6 地址 [::1]（即 localhost 的 IPv6 表示）访问端口 11434 时连接被拒绝。

技术分析

1. 网络隔离机制

Docker 容器默认具有独立的网络命名空间。当在容器内部使用 "localhost" 时，它指向的是容器自身的环回接口，而非宿主机的环回接口。这是 Docker 设计的默认安全特性。

2. IPv6 优先问题

现代操作系统和网络库通常会优先尝试 IPv6 连接。当容器尝试解析 "localhost" 时，系统会优先返回 IPv6 地址 [::1]，如果连接失败，才会回退到 IPv4 的 127.0.0.1。

3. 服务绑定差异

Ollama 服务默认可能只绑定在 IPv4 的 127.0.0.1 地址上，或者宿主机的防火墙可能阻止了 IPv6 的访问请求。

解决方案

方案一：使用宿主机网络模式（推荐）

修改 Docker 运行命令，让容器直接使用宿主机的网络栈：

docker run --network=host -d --name one-api ...

这种模式下，容器中的 "localhost" 将直接指向宿主机，无需额外配置。

方案二：使用宿主机特殊 DNS 名称

在容器内部，可以使用以下特殊DNS名称访问宿主机：

• Docker for Linux: host.docker.internal
• Docker for Mac/Windows: 同上

在 One-API 的 Ollama 渠道配置中，将地址改为：

http://host.docker.internal:11434

方案三：显式指定 IPv4 地址

如果宿主机IP是静态的，可以直接使用宿主机的局域网IP：

http://192.168.x.x:11434

方案四：修改 Ollama 绑定配置

确保 Ollama 服务监听所有接口：

OLLAMA_HOST=0.0.0.0 ollama serve

然后使用宿主机的实际IP进行连接。

最佳实践建议

1. 生产环境：建议使用方案一（host网络模式）或方案三（显式IP），确保连接的稳定性。

2. 开发环境：可以使用方案二，便于在不同环境中迁移。

3. 安全考虑：如果使用显式IP，确保配置适当的防火墙规则，限制只有One-API容器可以访问Ollama端口。

4. 性能优化：对于高频访问场景，可以考虑在宿主机和容器之间建立专用网络桥接，减少网络开销。

故障排查步骤

如果按照上述方案仍然无法连接，可以按以下步骤排查：

1. 在宿主机上验证Ollama服务是否正常运行：

   curl http://localhost:11434/api/tags
   

2. 检查容器网络配置：

   docker exec -it one-api curl http://host.docker.internal:11434/api/tags
   

3. 检查端口映射是否正确：

   docker port one-api
   

4. 检查防火墙设置：

   sudo ufw status
   

通过系统化的分析和解决方案，开发者可以快速解决One-API与Ollama集成时的连接问题，确保大模型服务的稳定运行。