在本地部署大模型应用时，Ollama 往往只是推理入口，真正需要保护的敏感信息还包括 Ollama Cloud API Key、向量数据库密码、对象存储凭据以及第三方模型服务令牌。若把这些密钥直接写进环境变量文件、启动脚本或容器镜像，不仅容易泄露，也会让轮换过程依赖人工重启。🔐 本文介绍一种更稳妥的实践：使用 HashiCorp Vault 统一保存密钥，通过 Vault Agent 自动认证、下发和更新凭据，再由业务应用安全调用 Ollama。
一、先明确集成边界
Ollama 本地 API 默认监听在 localhost:11434，本机访问通常不要求身份验证；直接访问 Ollama 云端 API、发布模型或下载私有模型时才涉及认证。云端程序化调用可使用 OLLAMA_API_KEY，并在请求头中携带 Bearer Token。具体规则可参考 Ollama 认证文档。因此，Vault 的价值并不是给本地 Ollama 强行增加认证，而是管理 Ollama 及其上层应用依赖的各种凭据。citeturn1search1
推荐链路：业务应用 → Vault Agent 生成的密钥文件或受控环境变量 → Ollama 本地或云端 API。不要让前端浏览器直接读取 Vault，也不要让 Ollama 服务暴露在公网后仍保持无认证状态。
二、集中存储与最小权限设计
对于 Ollama API Key 这类由外部平台签发、Vault 无法按需生成的凭据，可采用 KV v2 引擎保存。KV v2 支持静态密钥的版本管理，但“保存新版本”不等于外部密钥已经自动轮换；真正的轮换仍需调用外部平台完成创建与撤销，再把新值写回 Vault。Vault 会在持久化前加密数据，KV 适合保存此类任意静态秘密，说明见 Vault 静态密钥文档。citeturn1search9
可以规划路径 kv/ollama/prod，其中存放 api_key、base_url 和密钥版本说明。策略只允许运行 Ollama 客户端的工作负载读取该路径，不授予写入、删除或列举其他路径的权限。开发、测试与生产环境应分别设置路径和策略，避免测试账号意外获得生产密钥。
基础配置步骤
- 启用 KV v2，并将现有 Ollama API Key 写入指定路径。
- 创建只包含目标路径读取权限的 Vault Policy，例如命名为 ollama-prod-read。
- 根据运行环境选择认证方式：虚拟机可使用 AppRole，Kubernetes 可使用 Kubernetes Auth，云主机则优先使用对应云身份。
- 让 Vault Agent 执行自动认证，不在应用配置中长期保存高权限 Vault Token。
- 通过模板把密钥渲染到仅应用用户可读的文件，再由启动脚本加载。
三、使用 Vault Agent 下发凭据
Vault Agent 支持自动认证、令牌续期、缓存和模板渲染，可以在不大幅修改业务代码的情况下，把 Vault 中的秘密写入本地文件；Process Supervisor 模式还可以把秘密注入子进程环境变量。相关能力可查看 Vault Agent 官方说明。citeturn1search11
实践中可让 Agent 将 kv/data/ollama/prod 的 api_key 渲染为 /run/secrets/ollama.env，文件内容采用 OLLAMA_API_KEY=实际值 的形式。目录应位于内存文件系统或受保护的运行目录，并设置严格权限。业务进程启动前读取该文件，调用云端 API 时再把值放入 Authorization 请求头。
模板模式能够处理静态秘密、动态凭据和证书，并根据秘密类型执行相应的续期或重新获取逻辑；Agent 认证失败时也会退避重试。配置细节可参考 Vault Agent Template 文档。citeturn1search7
四、实现可控的动态轮换
需要注意，Ollama API Key 当前属于可撤销但不自动过期的外部静态凭据，因此不能直接套用数据库动态账号那种“到期自动吊销”模式。更可靠的做法是采用双密钥轮换：先在 Ollama 平台创建新 Key，写入 Vault 新版本；确认 Agent 已刷新文件并让应用重新加载；通过健康检查验证新 Key；最后撤销旧 Key。Ollama 关于 API Key 可撤销及当前不过期的说明见 官方认证页面。citeturn1search1
如果业务同时访问数据库、云平台或 PKI，则可对这些资源使用 Vault 动态 Secrets Engine。动态凭据由 Vault 按角色即时生成，带有租约和 TTL，可续期或撤销；这才是严格意义上的动态秘密。Vault 不同秘密引擎既可以保存数据，也可以连接外部服务并按需生成凭据，详见 Secrets Engines 文档。citeturn1search12
让应用感知新密钥
- 支持热加载：应用定期重新读取密钥文件，或监听文件变更，避免每次轮换都重启服务。
- 不支持热加载：在模板更新后执行受控重启或发送进程信号，并确保滚动更新期间至少保留一个可用实例。
- Kubernetes 场景：可使用 Vault Agent Injector 或 Vault Secrets Operator，将密钥同步到 Pod，并在轮换后触发滚动更新。Operator 支持轮换后的 rollout restart，参见 Vault Secrets Operator 文档。citeturn1search10
五、安全与运维检查清单
- Vault 与客户端之间启用 TLS，生产环境不要跳过证书校验。
- 禁止把 API Key 写入 Git、镜像层、Modelfile、日志和异常堆栈。
- 限制本地 Ollama 监听地址；如需跨主机访问，应在前方增加具备认证、TLS 和限流能力的网关。
- 为 Vault 开启审计日志，重点监控异常读取、策略变更、认证失败和大量密钥请求。
- 轮换任务必须具备失败回滚能力：新 Key 验证失败时保留旧 Key，不要立即撤销。
- 对 Agent 渲染文件设置最小权限，并在进程退出后清理临时秘密。
- 定期演练 Vault 不可用、密钥被撤销以及应用未及时加载新版本等故障场景。🛡️
总结
Ollama 接入 Vault 的核心不是简单地“把 Key 换个地方保存”，而是建立从身份认证、最小权限、秘密下发到轮换审计的完整闭环。对于 Ollama API Key，应采用 KV v2、Vault Agent 和双密钥流程实现安全轮换；对于数据库等支持动态凭据的资源，则应优先使用 Vault Secrets Engine 的租约机制。这样既能减少密钥散落和人工操作，也能在不改变 Ollama 推理能力的前提下，提高整个大模型应用链路的安全性与可维护性。✅
