Bolt项目中使用Ollama本地AI模型的连接问题解决方案

问题背景

在使用Bolt项目连接本地运行的Ollama AI模型时，开发者可能会遇到无法连接到localhost:11434端口的问题。这个问题通常表现为系统能够列出所有可用的模型提供者和模型，但实际连接时却失败。

错误现象

当尝试连接本地模型时，控制台会显示以下典型错误信息：

Failed to get Ollama models: TypeError: fetch failed

错误详情表明系统尝试连接::1:11434（IPv6格式的本地地址）时被拒绝，错误代码为ECONNREFUSED。

根本原因分析

经过排查，这个问题主要由两个因素导致：

1. IPv6与IPv4的兼容性问题：系统默认尝试使用IPv6地址(::1)连接，而某些环境下IPv6可能未正确配置或支持。

2. 环境变量配置不当：在.env文件中配置OLLAMA_API_BASE_URL时使用了"localhost"而非更可靠的"127.0.0.1"。

解决方案

1. 修改环境变量配置

在项目的.env配置文件中，应将OLLAMA_API_BASE_URL设置为：

OLLAMA_API_BASE_URL=http://127.0.0.1:11434

避免使用：

OLLAMA_API_BASE_URL=http://localhost:11434

2. 清除UI中的覆盖设置

在Bolt的用户界面中，确保相关输入字段为空，否则界面上的设置会覆盖.env文件中的配置。

3. 验证连接

完成上述配置后，可以通过以下步骤验证连接是否成功：

1. 确保Ollama服务正在运行并监听11434端口
2. 在浏览器中访问http://127.0.0.1:11434/api/tags测试连接
3. 在Bolt应用中检查模型列表是否正常加载

技术原理

这个问题背后的技术原理涉及网络协议栈的工作方式：

• "localhost"在某些系统环境下可能被解析为IPv6地址::1
• "127.0.0.1"明确指定使用IPv4协议
• 当系统IPv6栈配置不完整时，使用IPv6地址会导致连接失败
• 显式使用IPv4地址可以避免这种不确定性

最佳实践建议

1. 在开发环境中，优先使用127.0.0.1而非localhost
2. 定期检查.env配置文件中的设置
3. 在UI中保持默认设置，避免不必要的覆盖
4. 测试环境应保持与生产环境一致的网络配置

通过以上方法，开发者可以顺利解决Bolt项目连接本地Ollama模型时遇到的连接问题，确保AI功能的正常使用。