很多人把 Ollama 容器跑起来后，想给接口加一道 key，于是去翻 Ollama 的启动参数，翻半天发现根本没有这个开关。这篇不绕弯：先说清 Ollama 自身和「加 key 的那一层」分别是什么，再给 Docker 场景下的三种落地做法（前置网关、反向代理、容器编排注入密钥），最后给一份按报错现象定位的排查顺序。适合已经用 docker run 或 compose 跑起 Ollama、准备对外暴露或团队共用的读者。
很多人把 Ollama 容器跑起来之后，第一反应是去翻它的启动参数，想找个 --api-key 之类的开关，翻半天发现压根没有。这不是你用的版本旧，而是这件事本来就不归 Ollama 管。它默认只监听本机回环，设计前提就是「只有这台机器能访问」，鉴权被放到了网络层。
所以给 Ollama 加 key，真正的动作不是「配置 Ollama」，而是「在它前面套一层会校验 key 的东西」。下面先把这个分层讲清楚，再给 Docker 场景下三种能照做的做法，最后给一份按现象定位的排查顺序。适合已经用 docker run 或 compose 跑起来、准备对外暴露或者给同事共用的读者。
先搞清：Ollama 本身为什么没有 API key 开关
把这件事想成「谁负责挡人」。Ollama 的职责是加载模型、跑推理、暴露一个 HTTP 接口，它假设请求来自可信的本机环境。真正决定「谁能进来」的是网络层——端口映射、容器网络、前面的代理。职责分清了，你就不会在 Ollama 自己的配置里继续找了。
- Ollama 容器
- 提供推理接口，默认在容器内部监听，不负责发 key 也不负责验 key
- 鉴权层
- 反向代理、网关或编排平台的密钥注入，负责判断请求头里的 key 对不对
- 端口映射
- 决定外部能不能直接摸到 Ollama，是「要不要加 key」这个问题的分水岭
- 只在单机自己用、端口没有映射出去：加 key 属于给自己添麻烦，跳过
- 把端口映射到了宿主机甚至公网：必须加，否则等于把算力接口敞开
- 给同事或外部程序共用：必须加，而且要能区分是谁在用
- 已经有多套模型服务要一起对外：别自己写鉴权，直接用统一网关
Docker 场景下加 key 的三种做法与选择标准
三种做法的差别不在难度，而在「你后面要不要按人记账、按量限流」。如果只是挡住陌生请求，反向代理足够；如果要给不同同事发不同 key、看谁用了多少，就该上网关。
| 做法 | 适用场景 | 要注意的点 |
|---|---|---|
| 反向代理加鉴权 | 单人调试或小范围共用 | 校验请求头后再转发，别把 key 继续传给 Ollama |
| 网关或 API 管理组件 | 多人共用、要按人记账限流 | 把 Ollama 注册成上游服务，key 由它统一发 |
| 编排层注入密钥 | key 不想写进镜像或 compose | 用 env_file 或平台 secret 挂进代理容器 |
怎么选有个简单标准：只有你自己用，做法一够；只要出现「按人区分」「按量控制」「要看调用日志」这三个需求中的任意一个，就别自己手写鉴权逻辑，直接上做法二。
- 确认监听范围先看 Ollama 容器的端口有没有映射到宿主机。没有映射是最安全的起点，加 key 之前先把这一步做完。
- 选定鉴权层按上表判断自己属于哪种场景，选定代理还是网关，别两套混着用。
- 注入 key 的位置key 放在代理容器的环境变量或密钥文件里，不要写进 Dockerfile，也不要在 compose 文件里明文出现。
落地步骤：从容器网络到 key 校验的一条链路
下面这条链路按顺序做，每一步都能单独验证，出问题也容易定位到是哪一段。核心原则是：Ollama 只在内部网络里待着，对外只有代理容器的端口。
- 让 Ollama 只在内部网络监听compose 里不要给它写 ports 映射到宿主机，只让它和代理在同一个自定义网络里互相可见。验证方式是从代理容器里能连上、从宿主机直连连不上。
- 用服务名而不是 localhost 连接容器之间不走宿主机回环，代理的上游地址填 Ollama 的服务名加容器内部端口。填 localhost 会指向代理容器自己，这是最常见的连不上原因。
- 把 key 挂进代理容器用 env_file 或编排平台的 secret 引用，代理启动时读取。验证方式是进代理容器打印环境变量，确认能看到而日志里不会回显。
- 加透传规则并关掉响应缓冲代理要保留流式响应，把响应缓冲关掉、把超时调长，否则聊天接口会变成一次性吐出或者中途断流。
- 前台重启并看日志改完以后带前台日志方式重启代理容器，发一个请求，确认日志里出现了校验分支的执行记录，而不是直接跳过。
按现象排查：连不上、401、能连但没鉴权
排查的顺序很重要：先确认「通不通」，再确认「挡没挡住」，最后确认「挡得对不对」。反过来查会浪费很多时间在鉴权配置上，而问题其实在容器网络。
| 现象 | 最可能的原因 | 先查什么 |
|---|---|---|
| 连接被拒绝 | 两个容器不在同一网络，或上游填了 localhost | 代理容器里直接连通服务名和端口 |
| 一直返回 401 | key 没匹配上，或 key 被转发给了不认识的 Ollama | 看返回体是代理写的还是上游写的 |
| 不带 key 也能通 | 代理只做了转发没做校验，或绕开代理直连了 Ollama | 用一个无 key 请求打代理端口测 |
| 流式响应卡顿或断流 | 代理开了响应缓冲或超时太短 | 先调超时，再关缓冲 |
还有一种情况值得单独说：你本地测得好好的，同事那边却说用不了。这时候先怀疑对方的客户端有没有真的带上 key 请求头，而不是先改服务端配置。让 TA 把请求头发出来看一眼，通常五分钟就能定位。
- 连不上：先看网络和上游地址，别动鉴权配置
- 一直 401：看返回体是谁写的，判断 key 卡在哪一层
- 不带 key 也能通：说明校验根本没生效，重点查有没有绕开代理
- 流式异常：属于代理的缓冲和超时设置问题，和 key 无关
- 只有别人报错：先确认对方客户端有没有带请求头
配置这件事最怕拍脑袋定数字，比如超时设多长、限流设多少，都和你的实际负载有关。这类参数建议先跑一段时间看真实日志，再回站内页面核对当时的参考值，不要一上来就照抄别人的配置。
Ollama 不负责认人，认人这件事永远在你套在它前面的那一层。下一步想知道你现在用的中转站或自建方案在鉴权和稳定性上是什么水平，可以去站内工具目录看对应的检测项和实测记录，再决定要不要调整架构。→
常见问题
Ollama 就不能自己生成一个 API key 吗？
它本身不提供 key 的签发和校验，你看到的所谓 key 通常是别的组件加的。想要 key，就在容器前面加一层代理或网关，把校验放在那一层做，Ollama 只管推理。
我把端口映射到宿主机就直接能用了，是不是不用配 key？
能用不等于能对外。只要这个端口别人能摸到，等于谁都能调你的模型和算力。要么改成只在内网访问，要么前面加鉴权，二选一，别裸奔。
key 应该写在哪，写进 compose 文件行不行？
临时测试写进去可以，但 compose 文件很容易被提交到仓库。正式环境用 env_file 或编排平台的 secret 挂载，容器里读环境变量，别进镜像层也别进版本库。
