maxkb ollama api 域名无效

在 MaxKB 里添加 Ollama 模型，填完地址点保存却提示域名无效，或者测试连接直接报错，这类问题多数不是模型没跑起来，而是地址写法和服务暴露方式不对。这篇按由浅到深的顺序给一套排查动作：先确认 MaxKB 与 Ollama 各自跑在哪里，再决定该填什么地址，最后处理容器隔离和反代这两种容易漏的情况。

在 MaxKB 里添加 Ollama 模型，地址填完一点保存就提示域名无效，或者测试连接直接报错。遇到这种情况先别急着怀疑模型没跑起来，多数时候是地址写法不对，或者服务和 MaxKB 不在同一个网络位置。这篇不聊概念，只给一套由浅入深的排查动作。

思路很简单：先确认地址格式是否合法，再判断 MaxKB 和 Ollama 各自跑在哪里，最后处理容器隔离和服务绑定这两种最容易漏的情况。按顺序走，能省掉大量来回试错的时间。

先看地址写法：域名无效多半是格式不对

MaxKB 的模型地址栏要的是一个完整的 base url，通常以 /v1 或 /api 这样的路径结尾。只填一个裸域名、漏掉协议头、或者多带了查询串，都可能被当成非法地址直接拒掉。先检查这一栏的字符本身，比去调网络快得多。

• 地址栏填完整 base url，带上协议头和端口，例如 http://主机:端口；只写域名或只写 IP 都不完整
• 本机跑 Ollama 时填回环地址，在容器化部署的 MaxKB 里解析不到，要换成宿主机可达的地址
• 确认 Ollama 实际监听的端口，地址里的端口号必须和服务启动参数一致，不能想当然填默认值
• 地址里不要多带路径参数或查询串，多余路径会被当成非法域名处理
• 保存前先复制出来在浏览器或 curl 里打一遍，能返回结果再填回去

分场景定位：MaxKB 和 Ollama 各自跑在哪

地址格式没问题还是连不上，就要看这两个东西各自跑在什么位置。位置决定该填什么地址，这是整个排查里最容易被忽略的一步。下面按三种常见部署形态分开处理。

1. 确认 Ollama 在跑在 Ollama 所在机器上拉一次模型列表，能返回说明服务本身没问题，问题在对外可达性。
2. 在 MaxKB 所在机器上验证用 curl 打一次目标地址的列表接口，不通就回头调网络，不要继续改应用配置。
3. 回 MaxKB 重填并测试按完整 base url 重填保存，再点测试连接，观察报错是否从域名无效变成连接超时。
4. 还不行就看日志抓 MaxKB 的服务日志，看它实际请求的是哪个地址，日志里的地址往往和你以为填的不一样。

服务绑定与反向代理：域名能解析但连不上

有时候域名本身能解析，但连接照样失败。这种情况多半出在服务绑定范围或者中间的反向代理上，报错文案和域名无效很像，容易带偏判断方向。

• Ollama 默认只监听本机，没改绑定地址时外部访问会被拒，改完必须重启服务才生效
• 套了 Nginx 之类的反代时，检查转发规则有没有保留路径前缀，路径被截断会让客户端拿到非预期响应
• 反代里配的 server_name 和证书域名要对得上，自签证书在容器内可能被拒，需要显式信任
• 用 HTTPS 域名但证书链不完整时，部分客户端会直接抛连接层错误，先用 HTTP 直连排除证书因素

绑定地址

服务监听在哪个网卡上，只监听回环意味着只有本机能连

路径前缀

反代转发时是否把原始路径完整传给后端，丢前缀会让接口 404 而不是报域名错

证书信任

容器内默认不认自签证书，要么换正式证书，要么把根证书装进去

一套可照做的排查顺序

把上面的动作串成固定顺序，每次遇到同类报错照着走一遍即可。顺序的核心原则是：从最便宜的检查开始，先排除格式，再排除网络，最后才动应用配置。

• 第一步：确认 Ollama 进程在跑，本地能拉到模型列表
• 第二步：在 MaxKB 所在机器上验证目标地址可达，不通就调网络
• 第三步：回到 MaxKB 按完整 base url 重填，保存后点测试连接
• 第四步：仍失败就抓服务日志，看实际请求地址与填写是否一致
• 第五步：以上都通过还是报错，再检查反代路径前缀和证书信任

需要注意的是，如果你的 MaxKB 和 Ollama 之间还隔着公司的统一网关或内网 DNS，上面这套顺序依然适用，但要额外确认域名在容器内能否解析到正确 IP。解析不了的场景，换成 IP 加端口的写法先跑通，再回头解决 DNS。

另外，具体到某个 Ollama 版本支持哪些接口路径、MaxKB 各版本对地址格式的校验规则，这些细节会随版本变化，别背结论。判断不了的时候，到站内的接口与地址写法对照页核对当前说明，比凭记忆试快得多。