要保护大模型 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 的密钥自创建起有效一年,所以每个密钥无论如何都需要更换。把轮换变成例行工作:
- 用相同的标签规则和白名单创建一个新密钥。
- 与旧密钥并行部署,或者替换密钥后重启。
- 观察流量迁移到新密钥。
- 用
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 秒内 |
| 独立的管理凭据 | 门户凭据 |
密钥保护你的账户;零数据保留保护你通过账户发送的内容。上线前两者都要读一读。
