BroadRouter
开始使用

大模型 API 密钥安全:存储、轮换与 IP 白名单

BroadNet Inference 团队 · 阅读约 6 分钟 · 发布于 · 更新于

大模型 API 密钥要放在密钥管理服务里,绝不能写进代码或交给浏览器。每个应用或智能体各用一个密钥,定期轮换,并用 IP 白名单把密钥锁定到你的服务器。BroadNet Inference 表示,其白名单最多 32 条,吊销后 5 秒内停止新请求,密钥有效期为一年。

要保护大模型 API 密钥,就把它放在密钥管理服务里,并且只从你的服务器调用模型,绝不从浏览器或应用里调用。每个工作负载各用一个密钥,定期轮换,用白名单把密钥锁定到你的服务器 IP;密钥泄露时,先吊销,再调查。

本文介绍保护密钥的习惯做法,以及 BroadNet Inference 提供的具体控制手段。门户中的逐步操作请看 API 密钥与 IP 白名单指南;预算以及防止循环失控的保护,请看大模型 API 支出控制。

大模型 API 密钥应该存放在哪里?

把密钥存放在密钥管理服务或你所用平台的加密密钥存储中,绝不要写进代码。OWASP Secrets Management Cheat Sheet 详细介绍了各种方案。注意它的提醒:环境变量 “are generally accessible to all processes and may be included in logs or system dumps”(译文:通常所有进程都能访问,并且可能被写入日志或系统转储),所以在可以选择时,OWASP 更推荐挂载的密钥文件,或从密钥存储中获取密钥。启动时从密钥管理服务填充环境变量,是常见的折中做法。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],  # fails loudly if missing
)

使用 os.environ[...],而不是带硬编码默认值的 os.getenv(...);密钥往往就是通过这种默认值进了 Git。本地开发时,只要 .env 文件从第一次提交起就在 .gitignore 里,使用它没有问题。打开 Git 托管平台的密钥扫描和推送保护。在 GitHub 上,推送保护会在包含已知密钥格式的推送到达仓库之前将其拦截;面向用户的推送保护默认开启,但仓库级推送保护默认关闭,必须由仓库管理员或组织所有者启用。

可以把 API 密钥放进浏览器或移动应用吗?

不可以。交付到客户端的任何东西都可以被提取出来。前端代码和应用安装包都是公开的,无论怎样压缩或混淆。从你的服务器调用大模型,在服务器上验证你自己的用户,并在转发之前施加你自己的单用户限制。

交给别人使用的桌面工具也是一样。如果同事需要使用编程智能体,就让他们在自己的账户上用自己的密钥,而不是共用一个。

为什么每个工作负载要各用一个密钥?

在 BroadNet Inference 上,一个账户最多可以有 10 个有效密钥。好好利用它们:

密钥标签 使用方
prod-api 生产后端
prod-worker 批处理任务
staging 预发布环境
agent-ci CI 中的编程智能体
dev-laptop-<name> 本地开发

某个密钥泄露时,只需吊销那一个,其他密钥照常工作。标签也让用量一目了然:你能看到每个工作负载花了多少。按使用方给密钥命名,而不是按创建者命名。

IP 白名单怎样保护密钥?

有了 IP 白名单,被盗的密钥离开你自己的基础设施就无法使用。在 BroadNet Inference 上:

  • 账户白名单最多 32 条,每行一个 IPv4 或 IPv6 地址或 CIDR 范围。
  • 列表为空表示不限制。
  • 新密钥继承账户白名单,除非你在创建密钥时指定它自己的 allowed_ips,这会替换该密钥继承的列表。
  • 来自列表之外地址的请求会被拒绝,返回 403(“refused by model, route or IP policy”,译文:被模型、路由或 IP 策略拒绝)。

通过门户 API 创建带独立白名单的密钥:

curl -X POST https://inference.broadnet.ai/portal/keys \
  -H "Authorization: Bearer $BROADNET_PORTAL_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{"label":"prod-worker","allowed_ips":["203.0.113.7","198.51.100.0/24"]}'

响应中只会出现一次原始密钥。请立即把它存进密钥管理服务;之后无法再读取。完整步骤见 IP 白名单指南。

白名单适合出口 IP 固定的服务器:VPS、NAT 网关、固定的办公室 IP。对于网络经常变化的笔记本电脑,使用一个不带白名单的单独密钥,并让它可能造成的余额损失保持在较小范围。

为什么要把推理密钥和管理凭据分开?

BroadNet 使用两种凭据:

凭据 能做什么 存放位置
推理密钥 向 /v1/* 发送模型请求 应用运行的地方
门户凭据 创建和吊销密钥、修改允许的 IP、购买 只放在你的自动化或管理工具中

文档要求把每个门户凭据都视为拥有账户的全部权限。绝不要把门户凭据和应用部署在一起。即使应用服务器被攻破,攻击者拿到的也应该只是一个推理密钥,而不是整个账户的控制权。

API 密钥应该多久轮换一次?

OWASP 建议定期轮换,“so that any stolen credentials will only work for a short time.”(译文:这样任何被盗的凭据都只能在短时间内有效。)BroadNet 的密钥自创建起有效一年,所以每个密钥无论如何都需要更换。把轮换变成例行工作:

  1. 用相同的标签规则和白名单创建一个新密钥。
  2. 与旧密钥并行部署,或者替换密钥后重启。
  3. 观察流量迁移到新密钥。
  4. 用 DELETE /portal/keys/{alias} 吊销旧密钥。

因为一个账户最多可以有 10 个有效密钥,你可以让新旧密钥重叠几分钟,不会停机。对于离职成员接触过的密钥,要提前轮换。

密钥泄露了怎么办?

密钥泄露时,先吊销,再调查。在 BroadNet Inference 上,吊销密钥或修改白名单后,新请求会在5 秒内停止;文档解释说,授权结果可能会在复制缓存中保留这段有限的时间。

吊销之后:

  • 在账户页面或通过 GET /portal/usage 检查该密钥的用量;
  • 找出泄露途径(提交历史、CI 日志、分享出去的截图);
  • 轮换存放在同一位置的其他密钥。

已吊销或被拦截的密钥会返回 401 或 403;请参阅错误指南,避免监控系统把这些当成暂时性错误。

密钥是怎样通过日志泄露的?

日志是一个容易被忽视的泄露途径。在 HTTP 调试日志、错误上报工具和代理访问日志中,屏蔽 Authorization 头。联系技术支持时,提供 X-Request-ID、时间戳、路由、状态码和密钥的别名,绝不要发送密钥本身。BroadNet 的文档说,门户只保存每个密钥的哈希值,所以丢失的密钥它也无法再显示给你。

尚未发现的泄露,怎样把损失降到最低?

即使做到了上面所有习惯,也要假设密钥总有一天可能泄露。缩小影响范围:

  • 把按量付费余额保持在你能接受损失的水平,需要时再充值。
  • 重度使用的智能体用固定价格套餐:套餐会话价格固定,所以被盗的套餐密钥不会产生按 token 计费的账单。参见“不限量”到底是什么意思。
  • 针对每个密钥的异常支出或请求速率设置告警;大模型 API 费用计算器能给出一个正常的月度数字,作为告警基准。我们关于大模型 API 支出控制的文章介绍了预算和告警。

BroadNet Inference 提供哪些密钥控制?

控制项 BroadNet Inference
密钥只显示一次,以哈希形式保存 是
每个账户的有效密钥数 最多 10 个
密钥有效期 一年
IP 白名单 最多 32 条 IPv4、IPv6 或 CIDR 条目
单个密钥的白名单 支持,创建时指定 allowed_ips
吊销生效时间 5 秒内
独立的管理凭据 门户凭据

密钥保护你的账户;零数据保留保护你通过账户发送的内容。上线前两者都要读一读。

常见问题

大模型 API Key 应该存放在哪里?

放在密钥管理服务或你所用平台的加密密钥存储中,以环境变量(例如 BROADNET_API_KEY)的形式注入进程。不要写进源代码,不要放在提交到仓库的 .env 文件里,也绝不能放进前端代码。

BroadNet Inference 的密钥多快能吊销?

BroadNet 的文档说,吊销密钥或修改白名单后 5 秒内会停止新请求,因为授权结果可能会在复制缓存中保留这段有限的时间。

BroadNet Inference 的密钥有效期多长?

按量付费密钥自创建起有效一年。一个账户最多可以有 10 个有效密钥,所以你可以在旧密钥过期前先创建替换用的新密钥。

密钥丢了,BroadNet 能再显示一次吗?

不能。BroadNet 的文档说,原始密钥只返回一次,门户只保存它的哈希值。请创建新密钥并吊销旧密钥。

OpenAI 兼容 API 的密钥泄露了怎么办?

先吊销,再调查。检查该密钥的用量中有没有陌生流量,找出泄露途径(提交历史、CI 日志、截图),轮换存放在同一位置的其他密钥,然后签发一个带 IP 白名单的新密钥。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity