ollama_host 环境变量

本地跑通 Ollama 之后，只要换台机器调用、或者想让局域网同事也能连上，多半就会撞上 OLLAMA_HOST 这个变量：写不写、写在哪、写成什么格式，报错信息都不一样。这篇把它拆成三块讲：这个变量到底管什么、不同系统各写在哪、以及连不上时按什么顺序排查。只讲判断标准和可执行动作，不写死任何数值。

本地把 Ollama 跑通之后，真正让人卡住的通常不是模型加载，而是「换台机器连不上」。这时候十有八九会撞上 OLLAMA_HOST 这个环境变量：写不写、写在哪、写成什么格式，报错信息长得完全不一样，有人拿到的是连接被拒绝，有人拿到的是超时，还有人压根没被告知哪里错了。

这篇只讲三件事：这个变量到底管什么、不同系统和容器里各写在哪、以及连不上时按什么顺序排查。都是判断标准和可执行动作，不给绝对值，涉及具体数字一律去站内对应页面核对。部署前看一眼，能少绕几圈。

OLLAMA_HOST 到底管什么

先记住一句话：它决定的是 Ollama 服务进程监听在哪个地址和端口，也就是「服务端对谁开门」。不设置时，它只绑本机回环地址，外部机器连不上属于预期行为，不是 bug。很多人第一次配错，就是把它当成「客户端要去连谁」来填，方向从第一步就反了。

• 它管服务端监听，不管客户端请求目标；客户端配置里要填的是实际能连通的服务地址，不是照抄服务端这一行
• 只绑回环就是本机自用，绑到本机对外 IP 或通配地址，才轮到同网段机器访问
• 容器与宿主机是两套网络命名空间，容器里的这个变量只影响容器内部，宿主机能不能连要另看端口映射
• 监听放开到什么范围，就对应多大的暴露面，这一点比变量怎么写更值得先想清楚

写法与放的位置：几种常见形态

格式本身不复杂，就是「地址:端口」。只想放宽访问范围、不改端口时，地址部分写成通配形式，端口保持与服务默认一致即可。真正容易出问题的是「放在哪」——同一份配置写在不同层，生效范围完全不同，改错层会看着像没生效。下面按部署方式拆开讲。

系统级（Linux systemd 服务配置）

改完要重载服务再重启，只改 shell 里的导出对已启动的服务不生效

用户级（shell 配置文件里的导出）

只影响从这个终端拉起的进程，桌面端或开机自启的服务读不到

容器编排文件的环境变量段

随容器创建写入，重建容器才生效，改文件不重启等于没改

启动命令里的参数

优先级通常高于编排文件里的环境变量，两者同时存在时以此为准

Windows 图形界面的环境变量面板

加完必须重开终端甚至重新登录，已开的窗口读的是旧环境

1. 确认改动落在哪一层先想清楚这个 Ollama 是手动在终端起的、由 systemd 管理的，还是跑在容器里。三种情况配置文件不在一处，先确定位置再动手。
2. 改完做一次完整重启环境变量是进程启动时读取的，运行中的服务不会自动感知。systemd 场景先重载再重启，容器场景重建容器，不要只改文件就以为生效。
3. 开一个新终端做对照在旧终端里 echo 出来的环境变量可能是老的。新开一个窗口再查，能区分「没配对」还是「没刷新」。

改完怎么验证、连不上按什么顺序排查

验证要分两步走，别一上来就从别的机器试，那样连不上时你分不清是服务没起来还是网络不通。先在本机用回环地址访问服务状态端点，通了说明进程活着，问题就在监听范围或网络；然后再从另一台机器验证，先在发起端确认能不能解析并连通目标地址。

1. 本机自检用回环地址访问服务状态端点，确认进程在跑、能响应，排除模型或进程本身的问题。
2. 检查监听是否真的生效查看服务实际监听的地址与端口，确认和你写进配置的一致，而不是只有配置文件里改了。
3. 从发起端测连通在另一台机器上先确认能解析目标地址、再确认端口可连，区分是监听没放开还是被中间设备挡了。
4. 逐层放行按系统防火墙、云主机安全组、容器端口映射的顺序检查，每一层都要单独确认，别只看其中一处。

什么情况下这套不适用：跨公网直连、多机协同或需要鉴权的场景，别靠裸放监听端口解决。这类需求应该走反向代理并加上访问控制，把「谁能连」这件事交给代理层管，而不是把无鉴权的推理接口直接挂出去。至于反代和工具选型，可以到 /tools/speed-test 一带的目录里对照着挑。

几个反复踩的坑

• 改了变量却没重启：环境变量是进程启动时读取的，运行中的服务不会自动感知
• 把监听地址和请求地址混填：客户端配置里应该填实际能连到的服务地址，不是照抄服务端那一行
• 只改了一处、另一处覆盖：shell 导出、服务配置、容器编排可能同时存在，以优先级最高的那份为准
• 公网暴露风险：监听放开到通配地址后又直接映射到公网，等于把无鉴权的推理接口挂出去，务必配合代理与访问控制
• 排查完落到记录上：地址、端口、生效位置写进部署笔记，下次换机器少绕一圈