ollama api key 环境变量

很多人把 Ollama 跑起来后发现两件事对不上：一是官方本地服务压根没有 api key 这个字段，二是想给局域网或容器里的服务加把锁又不知道从哪下手。这篇先把「Ollama 有没有鉴权」这件事说透，再给一套环境变量配置清单，以及用反向代理补鉴权的落地步骤，顺带把改完不生效的排查顺序列出来。

很多人把 Ollama 装好、把模型拉下来、命令行里也能对话了，接着就想干两件事：一是找找有没有 api key 可以填，二是想知道怎么用环境变量把服务配得像样一点。结果一搜就懵——官方文档里翻不到 key 这个字段，社区帖子又到处在讲「ollama api key」，到底哪个是对的？

这篇就把这件事拆开说清楚：先确认 Ollama 本地服务到底有没有原生鉴权，再给一份环境变量该设在哪儿、怎么设的清单，然后讲真需要加 Key 时该走反向代理这条路，最后附一套改完不生效时的排查顺序。全程只讲判断标准和动作，具体数字该查哪里我会指给你。

先认清：Ollama 本地服务没有原生 api key

直说结论：Ollama 的本地服务默认不校验任何密钥。它起一个 HTTP 端口，谁的网络能摸到这个端口，谁就能调模型、列模型、拉模型。所谓「ollama api key 环境变量」，在原生服务这边没有对应的配置项，你设了它也不认。

那为什么到处都在提 api key？因为这个词在实际使用里被套了两层意思。搞清楚你遇到的是哪一层，后面的动作才不会白做。

• 第一种：客户端逼你填。很多接 OpenAI 格式的工具，界面上有必填的 api key 框，不填不让保存。它只是格式要求，Ollama 这边不会真去验，填个固定占位串就能过。
• 第二种：你自己在前面加了一层网关。网关会真校验请求头里的密钥，这时 key 才有实际约束力，也才有「泄露了要轮换」这种操作。
• 还有一种经常被混淆：把 Ollama 暴露给容器网络或局域网后，你感觉「没设密码不对劲」，于是想找个内置开关——这个开关不存在。

要不要加鉴权，判断标准很朴素：只在本机 localhost 自己用、机器不出内网、没有第二个人或第二个服务来连，基本不需要，加了纯属给自己找麻烦；一旦监听从回环改成对外、或者在多租户的容器集群里跑，就必须自己补一层，别指望配置文件里有开关。

环境变量怎么设：先分清宿主服务与客户端

环境变量最常见的一个坑，是设错了地方。你在自己终端里 export 一句，然后重启客户端——没用。因为真正读环境的是跑 ollama 那个服务进程，它跟你的终端可能压根不是一个环境。

所以第一件事是定位「服务是谁在跑」。不同平台落点不同，下面这张对照表可以先对一遍。

记住一个原则：环境变量属于服务进程，不属于你的 shell。验证方法也简单——去看服务进程实际带的环境，而不是回终端里 echo 一下自我安慰。

• 监听地址：决定服务只对回环开放，还是对整个网段开放，这是所有安全讨论的前提。
• 模型存放目录：换盘、换路径、多实例隔离都会用到，改错了直接表现为找不到模型。
• 并发与常驻相关参数：影响显存占用和同时能接多少请求，调之前先看清卡上还剩多少显存。
• 对外暴露时相关的跨域设置：只在浏览器直连场景才会碰到，走服务端转发通常绕得开。

设完必须重启服务进程再验证。很多「改了没用」的抱怨，追下去都是服务还是旧进程、旧环境。具体每类变量当前支持的取值，建议到站内文档页核对当时的说明，别照抄几年前的帖子。

监听地址与网络暴露：先决定谁能连上

鉴权这事的前提是「谁能连上」。默认情况下服务只监听回环地址，也就是只有本机能访问。一旦你把它改成对整个网段监听，等于把端口交给了同网段所有人，这时候再去讨论要不要 Key 才成立。

容器场景要特别小心一个区分：服务自己监听在哪个地址，和端口映射到宿主机哪个地址，是两回事。两者没对齐时，会出现宿主机 curl 得通、容器之间连不上的怪现象。

1. 先确认服务监听在哪在服务所在的那台机器或容器里，用最基础的请求打一下本地端口，通了说明服务在跑；再看监听地址是回环还是全网卡。
2. 再确认映射到哪容器场景看端口映射配置，宿主机能连不代表容器网络里的其他服务能连，反过来也一样。
3. 最后确认防火墙与安全组连接被拒或超时，先查这两处，别一上来就怀疑模型文件或显存不够。

跨域问题基本只在浏览器端直连时出现。解决办法不是去关一堆安全限制，而是让你的后端做一层转发：浏览器只跟你的后端说话，你的后端再跟 Ollama 说话，跨域和请求头丢失的问题一起消失。

一个判断标准：报错是连接被拒或超时，属于网络与监听问题；报错是 401，属于鉴权问题；报错是 404，属于路径或模型名对不上。先把错误类型分清，再去查对应的那一层。

要真加 Key，走反向代理这条正路

既然原生没有鉴权，真需要一把锁时，标准做法就是在 Ollama 前面放一层网关，让 Ollama 只听回环或只听内网，所有外部请求都从网关进。这样鉴权、限流、日志都集中在网关这一层，模型服务本身保持干净。

网关这一层要做的事，比单纯校验一个字符串要多。

• 校验请求头里的密钥，不匹配直接拒绝，别把请求透传下去。
• 剥离客户端伪造的同名请求头，否则攻击者直接带上你信任的头就绕过了。
• 按来源、按额度做限流，防止一个人把整个服务占满。
• 记录请求日志，出问题时有据可查，也方便做用量统计。

密钥本身怎么管也很关键：别硬编码在前端代码里，别提交进仓库，用环境变量或专门的密钥管理服务注入，并且准备一个轮换方案——旧密钥替换、新密钥下发、观察期后再停旧的，这三步最好提前写好。

不适用的情况也说清楚：如果只是想给同一台机器上的几个脚本共享服务，加网关属于过度设计。用系统用户权限隔离、只监听回环就够了，省事也省资源。

客户端要填 Key 的那些坑：占位值不等于真鉴权

客户端那侧的坑，基本都集中在「这个 api key 字段到底代表什么」。同一栏输入框，在你直连 Ollama 时是占位值，在你走自建网关时就变成真密钥，两种含义混着用，配置很快就会乱。

几个高频情况，按这个顺序对一遍基本能定位。

如果你用的是 OpenAI 兼容格式的客户端，有三处最容易对不上：路径前缀、模型名映射、请求头写法。这三处任意一处错，都会表现为「连上了但用不了」。建议在配置里写清备注，标明这一栏是占位还是真密钥，隔几周回来看也不会忘。

模型目录、并发这些变量：顺手一起理清

既然已经在动环境变量，不妨把模型目录和并发类参数一起理清，省得下次再折腾一遍。这两类变量的共性是：改错了不报错，只表现为行为不符合预期，查起来比较费时间。

模型目录改完不生效，通常就两个原因：服务进程还是旧环境，或者新目录的权限不对。前者靠重启解决，后者得确认跑服务的那个用户对新目录有读写权限。

• 多实例部署时，让每个实例用不同端口和不同模型目录，避免互相抢同一份权重文件。
• 并发类参数调大前，先按模型大小和卡上剩余显存估算一遍，别等跑起来才发现占不下。
• 改完先用一次最小请求验证，确认服务正常返回，再挂业务流量。
• 把最终生效的变量值记在部署文档里，下次换机器直接照抄，不用重新试一遍。

至于当前各版本具体支持哪些变量名、取值范围是什么，这类会变的信息不建议凭记忆写，到站内文档与资料库页核对当时的说明更稳妥。

改完不生效？按这个顺序排查

环境变量这类问题，最忌讳东一榔头西一棒子。下面这个顺序是从里到外、从服务到客户端，逐层排除，基本能覆盖大多数情况。

1. 看服务实际读到的环境查服务进程的环境或服务定义文件，确认变量确实注入了。不要看你自己终端的 export，那不算数。
2. 确认服务已重启旧进程没退干净会一直用旧配置。确认端口被新进程占用，必要时彻底停掉再起。
3. 用最基础请求确认服务活着先绕开代理直连本地端口，能通再往下走。这一步不通，后面全是白测。
4. 叠加代理层逐段测经网关打一次，带正确密钥打一次，不带密钥打一次，把三组结果对比着看。
5. 看两侧日志代理侧和客户端侧的请求日志一起看，比对请求头、路径和状态码，差异往往一眼就出来。

如果排查完还是不通，建议把问题缩小到一个最小可复现的请求上，拿掉所有中间层，从最里面往外一层层加回来。这样比对着整套配置猜要快得多。

落地清单：按顺序做完再上线

最后给一份可以照着走的清单。顺序别乱，从需求出发，先把「谁要访问」定下来，后面的技术选择才有依据。

• 明确访问范围：仅本机、局域网、还是公网，这三者对鉴权的要求完全不是一个量级。
• 把环境变量写进服务定义文件，而不是临时终端里 export，保证重启后仍然生效。
• 需要 Key 就上反向代理，密钥通过环境变量或密钥管理服务注入，并准备好轮换流程。
• 上线前用最小对照表自测：本地直连、经代理带正确密钥、非授权来源三种情况各测一次。
• 把最终生效的变量和密钥位置记进部署文档，方便交接和排障。

还有一句要提醒：如果你打算把服务放到公网，光加一个密钥远远不够，限流、日志、异常请求监控这几样最好一起上，别等出了问题再补。