1. 为什么一个环境变量能卡住大半天的部署进度刚接触本地大模型部署的朋友十有八九会在OLLAMA_HOST这个环境变量上栽跟头。我自己第一次把 Ollama 装到一台带显卡的台式机上本意是让同一间办公室的笔记本也能调用这台机器的模型结果折腾了整整一个下午——服务在宿主机上跑得好好的curl http://127.0.0.1:11434一切正常可换到另一台机器上就是连不上。后来才发现问题根本不在防火墙也不在路由器而是 Ollama 默认只监听回环地址压根没打算让外部设备访问。这篇文章就是把我踩过的坑、试过的配置、以及最后稳定跑起来的方案完整梳理一遍。核心围绕OLLAMA_HOST这个环境变量展开讲清楚它到底控制什么、为什么默认值是127.0.0.1、怎么改成局域网可访问、改完之后又会遇到哪些新问题。内容适合三类人一是刚装好 Ollama 想在本机调用的新手二是想把模型服务共享给团队或家里其他设备的进阶用户三是被bind: only one usage of each socket address这类报错折磨过的运维同学。不管你现在处于哪个阶段读完都能找到可以直接抄的配置。需要先明确一点OLLAMA_HOST不是 Ollama 独有的概念它是很多服务端程序通用的环境变量命名习惯用来指定服务绑定的网络地址和端口。理解它的本质比死记某个命令重要得多。下面我会从设计逻辑讲起再一步步落到实操。2. 搞懂 OLLAMA_HOST 到底在控制什么2.1 回环地址与监听地址的本质区别很多人把127.0.0.1和localhost当成一回事其实在服务监听这个场景下它们的含义需要更精确地理解。127.0.0.1是 IPv4 的回环地址数据包发到这个地址操作系统网络栈会直接把它转回本机不会经过任何物理网卡。这意味着只有运行在同一台机器上的程序才能访问它。Ollama 默认把OLLAMA_HOST设为127.0.0.1:11434背后的考量是安全。本地模型服务通常不需要对外暴露默认只允许本机访问能最大程度避免被局域网内其他设备误调用也减少了被扫描的风险。这个设计思路和很多数据库的默认配置一致——比如 MySQL 默认只监听127.0.0.1Redis 默认绑定回环地址都是同一个逻辑。当你把OLLAMA_HOST改成0.0.0.0:11434含义就完全变了。0.0.0.0不是一个具体地址而是一个通配符表示“监听本机所有网络接口”。这时候无论是回环地址、局域网 IP还是如果有公网 IP 的话服务都会接受连接。这就是局域网共享的关键一步。注意0.0.0.0和127.0.0.1是互斥的监听策略不能同时生效。你设了0.0.0.0本机访问依然可以用127.0.0.1因为回环接口也被包含在内了。2.2 端口 11434 的来龙去脉11434 是 Ollama 的默认端口这个数字本身没有特殊含义属于注册端口范围内的随机选择。但正因为它是默认值很多工具和客户端在连接时如果不显式指定端口就会默认往 11434 发请求。所以除非有端口冲突一般不建议改端口号。端口冲突是另一个常见问题。如果你之前跑过其他服务占用了 11434Ollama 启动时会直接报bind: only one usage of each socket address。这个报错的字面意思是“每个套接字地址只能被使用一次”翻译成人话就是这个端口已经被别的程序占了我绑不上去。解决办法要么是找到占用端口的程序并停掉要么是给 Ollama 换一个端口。在 Windows 上查端口占用可以用netstat -ano | findstr 11434Linux 和 macOS 用lsof -i :11434或ss -tlnp | grep 11434。找到进程号之后再决定是杀掉进程还是换端口。2.3 环境变量在不同系统上的生效逻辑环境变量的生效范围是个容易被忽略的细节。在 Linux 和 macOS 上你在终端里执行export OLLAMA_HOST0.0.0.0:11434这个变量只对当前终端会话有效关掉终端就没了。要让它在每次启动时都生效得写进 shell 的配置文件比如~/.bashrc、~/.zshrc或者~/.profile。Windows 上分两种情况。如果你是在 PowerShell 里临时设置用$env:OLLAMA_HOST0.0.0.0:11434同样只对当前窗口有效。要永久生效得通过“系统属性 - 高级 - 环境变量”图形界面添加或者用setx OLLAMA_HOST 0.0.0.0:11434命令。这里有个坑setx设置的环境变量不会在当前已经打开的终端里生效必须新开一个窗口才能读到。还有一个更隐蔽的坑如果你把 Ollama 装成了系统服务比如 Linux 的 systemd 服务或者 Windows 的服务那么你在用户终端里设的环境变量对它完全不起作用。系统服务有自己的环境变量加载机制需要单独配置。这一点后面会专门讲。3. 分场景配置实操从本机到局域网3.1 本机开发场景保持默认最省心如果你只是在自己电脑上跑模型用命令行或者本机的客户端调用那什么都不用改。Ollama 装好之后默认就是127.0.0.1:11434直接ollama run就能用。这种情况下改OLLAMA_HOST反而可能引入不必要的风险。我见过一些教程一上来就让人改成0.0.0.0说是“方便以后扩展”。这个建议我不认同。默认配置是经过安全考量的没有明确需求就不要动。等你真的需要局域网访问了再改改的时候也知道自己在改什么。本机场景下唯一可能需要调整的是端口。比如你本机已经有一个服务占了 11434那就把 Ollama 换到 11435export OLLAMA_HOST127.0.0.1:11435 ollama serve注意这里ollama serve是前台启动方便看日志。如果你是用ollama run直接跑模型它内部会自动拉起服务这时候环境变量要在执行ollama run之前就设好。3.2 局域网共享场景改成 0.0.0.0 并放行防火墙这是本文的重点场景。假设你有一台性能较强的机器叫它“服务机”想让它上面的 Ollama 服务被同一局域网内的其他设备“客户机”调用。步骤分三步改监听地址、放行防火墙、验证连通性。第一步在服务机上设置环境变量。Linux 和 macOSexport OLLAMA_HOST0.0.0.0:11434 ollama serveWindows PowerShell$env:OLLAMA_HOST0.0.0.0:11434 ollama serve第二步放行防火墙。这一步是很多人卡住的地方——环境变量改对了但防火墙把外部请求拦了。Linux 上用ufw的话sudo ufw allow 11434/tcp用firewalld的话sudo firewall-cmd --add-port11434/tcp --permanent sudo firewall-cmd --reloadWindows 上第一次启动监听0.0.0.0的服务时系统通常会弹出一个防火墙提示框问你是否允许该程序通过防火墙。一定要勾选“专用网络”如果客户机在同一局域网专用网络就够了。如果当时点了“取消”后面可以手动到“Windows Defender 防火墙 - 允许应用通过防火墙”里找到 Ollama 并勾选。第三步验证。先在服务机上确认监听状态# Linux/macOS ss -tlnp | grep 11434 # 应该看到 0.0.0.0:11434 或 *:11434然后在客户机上测试curl http://服务机的局域网IP:11434/api/tags如果返回了模型列表的 JSON说明通了。如果报Connection refused说明服务没监听对地址或者防火墙没放行如果报Connection timed out大概率是防火墙或网络隔离的问题。3.3 服务机 IP 会变怎么办固定 IP 或使用主机名局域网里服务机的 IP 如果是 DHCP 动态分配的过一段时间可能会变客户机的配置就得跟着改很烦。两个解决办法一是给服务机设静态 IP 或在路由器里做 DHCP 保留二是用主机名访问。主机名方案在支持 mDNS 的网络里很好用。比如服务机的主机名叫ai-server客户机可以直接用http://ai-server.local:11434访问。Windows 上如果 mDNS 不好使可以在客户机的 hosts 文件里加一条静态映射192.168.1.100 ai-server这样客户机就能用http://ai-server:11434访问了。hosts 文件的位置Windows 在C:\Windows\System32\drivers\etc\hostsLinux 和 macOS 在/etc/hosts。改完需要刷新 DNS 缓存Windows 用ipconfig /flushdns。3.4 系统服务方式安装的配置方法如果你是用官方安装脚本装的 Ollama在 Linux 上它通常会被注册成 systemd 服务。这种情况下你在终端里export的环境变量对服务无效因为服务是由 systemd 启动的读的是它自己的配置。正确的做法是编辑 systemd 的服务文件sudo systemctl edit ollama.service这会打开一个覆盖配置文件在里面加上[Service] EnvironmentOLLAMA_HOST0.0.0.0:11434保存后重载并重启sudo systemctl daemon-reload sudo systemctl restart ollama验证服务实际读到的环境变量sudo systemctl show ollama.service | grep EnvironmentWindows 上如果 Ollama 是作为服务运行的需要用nssm之类的工具修改服务配置或者重新安装服务时指定环境变量。更简单的办法是卸载服务版改用用户态启动这样环境变量就好控制了。4. 配置完成后的验证与客户端接入4.1 用 curl 和 ollama 命令行双重验证配置改完之后别急着上客户端先用最原始的方式验证服务本身是通的。在服务机上curl http://127.0.0.1:11434/api/tags在客户机上curl http://192.168.1.100:11434/api/tags两个都返回 JSON 才算真正通了。如果服务机通、客户机不通问题一定在监听地址或防火墙上跟 Ollama 本身无关。还有一个验证技巧用ollama命令行工具指定远程地址。较新版本的 Ollama 支持通过OLLAMA_HOST环境变量让客户端连接远程服务export OLLAMA_HOST192.168.1.100:11434 ollama list如果这个命令能列出服务机上的模型说明客户端配置也对了。4.2 常见客户端接入配置不同客户端接入远程 Ollama 的方式不太一样但核心都是把 base URL 从http://127.0.0.1:11434改成http://服务机IP:11434。以常见的 OpenAI 兼容接口为例很多工具支持自定义 base URL。配置项通常长这样Base URL: http://192.168.1.100:11434/v1 API Key: ollamaAPI Key 随便填Ollama 默认不校验。模型名称填你在服务机上ollama list看到的模型名。如果你用的是浏览器插件类的客户端注意浏览器可能会对http的跨域请求做限制。有些插件需要你在 Ollama 启动时额外设置OLLAMA_ORIGINS环境变量来允许跨域export OLLAMA_ORIGINS*这个变量和OLLAMA_HOST是配合使用的前者控制谁能跨域访问后者控制监听哪个地址。生产环境不建议设成*应该指定具体的来源。4.3 局域网内多设备并发调用的注意事项当多个设备同时调用同一台服务机上的 Ollama 时有几个现实问题要考虑。第一是显存和内存。Ollama 默认会根据可用显存决定是否把模型加载到 GPU。如果同时来了多个请求而模型又比较大可能会出现排队或者显存不足的情况。可以在服务机上观察nvidia-smiN 卡或rocm-smiA 卡的输出看显存占用。第二是并发数。Ollama 默认的并发处理能力有限可以通过OLLAMA_NUM_PARALLEL环境变量调整。但这个值不是越大越好设太大反而会因为显存碎片导致性能下降。一般设成 2 到 4 比较稳妥具体要看显卡显存和模型大小。第三是网络带宽。如果客户机和服务机之间是千兆局域网传输模型推理的请求和响应数据问题不大。但如果是 Wi-Fi 且信号不好长文本生成时可能会感觉到明显的延迟。这种情况建议客户机和服务机尽量走有线连接。5. 踩坑实录那些报错信息背后的真相5.1 bind: only one usage of each socket address这个报错我遇到过至少三次每次原因都不一样。字面意思是端口被占用但实际排查下来有几种情况。第一种是真的有另一个 Ollama 实例在跑。比如你之前用ollama serve启动了一个忘了关又启动一个就会报这个错。解决办法是找到并停掉旧进程# Linux/macOS ps aux | grep ollama kill PID # Windows tasklist | findstr ollama taskkill /PID PID /F第二种是端口被其他程序占用。用前面说的netstat或lsof查一下就知道是谁。第三种比较隐蔽你设置了OLLAMA_HOST0.0.0.0:11434但系统里已经有一个服务监听了127.0.0.1:11434。这两个地址虽然不同但在某些系统上会被认为是冲突的。解决办法是先停掉监听127.0.0.1的那个再启动0.0.0.0的。5.2 502 Bad Gateway 与 127.0.0.1 拒绝连接这两个报错经常一起出现尤其是在你用某个中间层比如反向代理或者某个客户端框架去调用 Ollama 的时候。127.0.0.1 拒绝了我们的连接请求通常意味着客户端试图连接本机的 11434但本机根本没有服务在监听。可能的原因Ollama 服务没启动或者启动时监听的地址不是127.0.0.1比如你设成了0.0.0.0但客户端配置里写的是别的地址。502 Bad Gateway 则多出现在反向代理场景。比如你用 Nginx 做代理Nginx 配置里proxy_pass指向http://127.0.0.1:11434但 Ollama 实际监听的是0.0.0.0:11434或者换了端口Nginx 就连不上后端返回 502。排查方法是先确认 Ollama 实际监听的地址和端口再检查代理配置是否一致。5.3 改了环境变量但不生效的几种情况这是最让人抓狂的一类问题明明改了echo $OLLAMA_HOST也显示新值但服务行为没变。原因通常有这几种。一是服务是系统服务不读用户环境变量。前面讲过要用systemctl edit改。二是改了配置文件但没重载。比如改了~/.bashrc但当前终端还是旧的环境需要source ~/.bashrc或者新开终端。三是 Windows 上用setx设置后没新开窗口。setx写的是注册表里的持久环境变量当前进程读不到。四是环境变量名拼错了。OLLAMA_HOST不是OLLAMA_HOSTS也不是OLLAMA_HOSTNAME。这种低级错误在深夜调试时特别容易犯。5.4 常见问题速查表现象可能原因排查命令解决办法客户机连不上服务机服务监听在 127.0.0.1ss -tlnp | grep 11434改 OLLAMA_HOST 为 0.0.0.0客户机连不上服务机防火墙拦截ufw status放行 11434 端口启动报 bind 错误端口被占用lsof -i :11434停掉占用进程或换端口改了变量不生效服务由 systemd 管理systemctl show ollama用 systemctl edit 配置502 Bad Gateway代理指向错误检查 Nginx 配置对齐代理和后端地址浏览器插件连不上跨域被拦看浏览器控制台设置 OLLAMA_ORIGINS6. 几个让配置更稳的进阶技巧6.1 用启动脚本固化配置与其每次手动 export不如写个启动脚本。Linux 和 macOS 上可以写一个start-ollama.sh#!/bin/bash export OLLAMA_HOST0.0.0.0:11434 export OLLAMA_ORIGINS* export OLLAMA_NUM_PARALLEL2 ollama serve给执行权限chmod x start-ollama.sh以后直接跑这个脚本就行。Windows 上可以写个.bat或.ps1脚本逻辑一样。这样做的好处是配置集中、可版本管理换机器时把脚本拷过去就行不用回忆当初设了哪些变量。6.2 日志排查的正确姿势Ollama 的日志默认输出到标准输出前台启动时直接能看到。如果是以服务方式运行日志会进系统日志。Linux 上用journalctl -u ollama -f这个命令能实时看服务日志排查启动失败、请求异常时非常有用。Windows 上如果用的是用户态启动日志就在启动窗口里如果是服务得看服务管理器里的日志或者配置日志文件输出。看日志时重点关注几个关键词Listening on确认监听地址、error错误、bind绑定问题。启动成功时通常会打印类似Listening on 0.0.0.0:11434的信息这一行就能确认环境变量是否生效。6.3 安全边界局域网共享不等于公网开放最后必须强调一点0.0.0.0监听意味着本机所有网络接口都开放如果你的机器同时有公网 IP那这个服务就暴露在公网上了。Ollama 默认没有任何认证机制任何人都能调用你的模型甚至可能通过某些接口读取文件。所以局域网共享的前提是服务机没有公网 IP或者有防火墙规则确保 11434 端口只对局域网开放。如果你确实需要从外网访问正确做法是通过反向代理加认证而不是直接把 Ollama 暴露出去。这一点在配置OLLAMA_HOST时就要想清楚不要图省事设了0.0.0.0就不管了。我自己现在的做法是服务机固定局域网 IP防火墙只放行局域网网段OLLAMA_HOST设0.0.0.0但配合防火墙规则这样既方便团队内共享又不会意外暴露。这套配置跑了小半年没出过问题。