本地模型接入 API 网关连不上？Ollama 与 Docker 地址排查教程
区分宿主机、网关容器和模型容器的地址，按监听、网络、协议和鉴权逐层排查，附有超时限制的只读探针与访问边界验收清单。
本机能访问 Ollama，放进 Docker 的 API 网关却连接失败，首先要检查“请求从哪里发出”。网关容器里的 localhost 通常指它自己，不是你打开浏览器的电脑，也不是另一个模型容器。改模型名、换密钥或增加充值，通常解决不了这一层的问题。
本文以 Ollama 本地服务和普通 Docker 桥接网络为例，按地址、监听、协议、访问权限四层排查。不提供特定网关品牌的界面步骤，不假设所有兼容接口都支持相同功能。使用 host 网络或共享网络命名空间时，回环地址的含义需要按实际拓扑重新判断。
1. 画清客户端、网关和模型服务的位置
先写下这一条链路：客户端 → 网关对外入口 → 模型服务。两段连接的地址和凭证可以不同：客户端使用网关地址与网关密钥；网关使用它自己能访问到的上游地址。不要让浏览器直接拿到上游管理凭证。
| 部署方式 | 网关侧的候选上游主机 | 先确认什么 |
|---|---|---|
| 网关与 Ollama 都直接运行在同一操作系统 | 127.0.0.1:11434 | 服务确实在同一网络环境，且监听该端口 |
| Docker Desktop 网关容器访问宿主机上的 Ollama | host.docker.internal:11434 | 主机名解析、宿主机监听范围、防火墙 |
| Linux Docker Engine 网关容器访问宿主机 | 已确认的宿主机可达地址，或配置 host-gateway 的名称 | 不假设 Desktop 的名称自动存在 |
| 网关和 Ollama 是同一用户自定义网络中的两个容器 | 模型容器名，例如 ollama:11434 | 名称真实存在、网络相同、使用容器内端口 |
| 网关在云服务器，Ollama 在家用电脑 | 经授权的私网或 VPN 地址 | 云端的 localhost 无法指向家中电脑 |
Docker 官方说明，用户自定义网络中的容器可以按容器名称互访；默认桥接网络不能据此假定同样具备名称解析。[2] host.docker.internal 在 Docker Desktop 中自动解析；Docker Engine 的 --add-host 支持特殊值 host-gateway，可在创建容器时建立这项主机映射。[3] 映射只解决“名称指向哪里”，不会自动开放监听、放行防火墙或添加鉴权。
如果宿主机将模型容器的 11434 映射为 18080，宿主机测试用 18080；同一容器网络中的网关通常仍访问模型容器的 11434。不要把“发布到宿主机的端口”和“容器内服务端口”混在一起，也不要硬编码重建后可能变化的容器 IP。
2. 从网关所在环境检查监听和连通
Ollama 默认绑定 127.0.0.1:11434，通过 OLLAMA_HOST 修改监听地址。[1] 因此宿主机浏览器能打开服务，只能证明宿主机这条路径可用，不能证明网关容器也可访问。
按以下顺序操作，每次只改变一个因素：
- 在模型服务所在环境确认服务启动、端口和日志；先排除服务未运行或端口填错。
- 在实际发送上游请求的网关容器里解析目标主机名。若镜像没有诊断工具，可由维护者用共享该容器网络命名空间的临时诊断容器；记录它与原进程的代理、DNS 和权限差异。
- 从同一网络环境请求模型列表端点。宿主机成功、容器失败时，先检查目标地址、监听范围、路由和防火墙。
- 必须修改
OLLAMA_HOST时，先限定允许访问的接口和来源，再按官方平台步骤重启服务。环境变量改在终端里，不代表后台服务已经继承。 - 重复容器侧检查，并从一个不被允许的来源验证访问被拒绝。
0.0.0.0 是监听所有 IPv4 接口的绑定值，不是给客户端填写的目标地址。把服务改为监听所有接口，也不等于已经安全。尤其不要为了排错直接把 11434 放行到公网。
3. 用只读探针分清“连上了”和“能生成”
以下命令查询 Ollama 原生模型列表，不发起生成，不携带 API Key，不跟随重定向。请在有 curl 的环境中运行；Windows PowerShell 如把 curl 解析为别名，应使用 curl.exe。
curl --fail --silent --show-error --connect-timeout 3 --max-time 10 --noproxy '*' http://127.0.0.1:11434/api/tags
此地址用于同机测试。在网关容器里应按第一节替换主机名和端口，保留 /api/tags。--noproxy '*' 只让这一次诊断命令直连目标，避免本地地址误走出站代理；仅用于你已确认的内部目标，不要据此永久关闭组织规定的代理。
命令限制连接等待为 3 秒、总时间为 10 秒；通常 HTTP 4xx/5xx 会返回非零退出码，但 curl 官方也提示，涉及鉴权的 401/407 等场景不能仅依赖 --fail 判断。[5] --fail 会隐藏被其判定为失败的响应正文，需要错误内容时从受控的服务日志补充；不能把空输出直接解释成服务没响应。3xx 不一定产生非零退出码，退出码为 0 也不能独立证明端点正确：遇到 HTML 或异常空白，应查看状态与响应头，不盲目跟随登录跳转。
| 结果或现象 | 下一步 |
|---|---|
| curl 退出码 6：名称解析失败 | 检查服务名、网络与 host-gateway 映射 |
| 退出码 7：无法建立连接 | 核对监听地址、端口、服务状态和拒绝规则 |
| 退出码 28：超时 | 检查路由、丢弃规则、代理与服务负载；不凭超时断言服务宕机 |
| 退出码 22：HTTP 错误 | 查询状态和脱敏日志；404 先查路径，401/403 查访问控制层 |
| 返回 HTML、跳转或不符格式的 JSON | 检查是否连到了网页入口、反向代理默认页或错误服务 |
返回含 models 数组的 JSON | 已取得模型列表；仍须核对数组中的实际名称与后续生成能力 |
Ollama 的 GET /api/tags 返回模型列表。[4] 空数组不代表网络失败；列表中有模型也不代表它已加载、内存充足或所有参数都可用。本教程只用本地模拟 HTTP 服务核验命令的成功、HTTP 错误、重定向与超时行为，没有对真实模型或供应商做性能测试。
4. 网络打通后，再核对协议和模型映射
不要把 Ollama 原生端点 /api/tags 当成网关客户端的通用端点。Ollama 原生聊天使用 /api/chat；其原生聊天接口默认流式返回。[6] 若选择其他兼容适配器，按该适配器对应的文档核对完整请求路径与消息格式，不能只凭“支持本地模型”几个字判断。
记录一张配置表：网关版本、渠道类型、上游主机与端口、最终请求路径、客户端模型别名、映射后的真实模型名称、流式开关。检查的是最终地址，避免某层已经添加路径前缀，另一层又重复追加。
接下来用一个已安装、明确在本地执行的模型做短文本验收；确认客户端与网关不会自动回退到付费云端。先测试非流式请求，再测试流式请求，并在日志中确认选中的上游。不要为测试随意下载巨大模型，也不要拿生产敏感数据做提示词。工具调用、图片或结构化输出应分别验收，普通聊天成功不代表这些功能已通过。
若只在流式模式失败，继续看流式输出排查；若出现模型名或路径错误，参考model not found 与 404 排查。网络可达性确认后，才值得进入这些层次。
5. 保留网关入口的鉴权，阻断绕过路径
Ollama 官方说明，本地 API 请求不要求 API Key。[7] 网关启用了密钥校验，不代表直接访问模型服务也需要同一密钥。如果模型端口能被外部直接访问，调用者可能绕过网关的预算、速率和日志规则。
建议按部署条件执行三个验收：
- 授权客户端经网关能够完成短请求；错误或缺失网关密钥应被拒绝。
- 网关能访问模型服务；不受信任的网络来源不能直接访问模型端口。
- 重启或重建容器后，地址、访问限制和模型映射仍然有效。
修改 Docker 端口发布规则前，确认绑定的是哪个宿主机接口；不显式限定时，端口发布可能暴露到外部网络。[2] 使用私网或 VPN 也仍需控制成员和权限。跨不可信网络传输应采用经过认证的加密通道，不能把内部 HTTP 示例照搬成公网裸露接口。OLLAMA_ORIGINS 处理浏览器跨域来源，不是服务端鉴权或防火墙替代品。[1]
如果网关和模型共用机器，还要检查资源争用；这一问题可继续看网关服务器容量估算。本文解决的是网络路径与访问边界，不承诺某个配置能支撑固定并发数。
官方资料与核验范围
- [1] Ollama FAQ：监听地址、环境变量与来源设置。
- [2] Docker Engine：容器网络、名称解析与端口发布。
- [3] Docker run：host-gateway 与自定义主机映射。
- [4] Ollama：列出模型。
- [5] curl 官方命令手册。
- [6] Ollama：聊天接口。
- [7] Ollama：API 介绍与本地请求鉴权边界。
资料核对日期：2026-10-11。示例面向普通桥接网络和本地 Ollama；不同操作系统、网络模式、网关适配器和版本需要重新核对。不包含付费 API 调用或真实部署跑分。