Skip to main content

API Key 防泄漏最佳实践

从缩短凭证暴露时间、收窄权限范围、配置预警与止损三个层面预防 API Key 泄漏,涵盖临时 API Key、定期轮换、IP 白名单、私网连接、预算告警与模型监控告警。

概述

API Key 是调用阿里云百炼模型服务的凭证。一旦泄漏,任何持有者都可以用它调用该 Key 授权范围内的模型并消耗额度。泄漏造成的影响可拆解为四个因子:泄漏概率、暴露时间、单次调用的权限范围、异常持续时长。泄漏概率由贯穿全文的基础实践压缩,其余三个因子分别由以下三个层面压缩:

层面

压缩的因子

关键手段

缩短暴露时间

暴露时间

客户端使用临时 API Key、一次性展示加受控保存、定期轮换与离岗回收

收窄权限范围

单次调用的权限范围

一业务一 Key、业务空间隔离、IP 白名单与模型范围、私网连接

预警与止损

异常持续时长

预算告警与达预算即停、模型监控告警、平台风险检测

贯穿三个层面的基础实践:
  • 应用从环境变量或密钥管理服务读取凭证,不在代码中硬编码;CI/CD 配置敏感信息扫描(可使用 gitleaks 等凭证扫描工具),覆盖 API Key 形态。
  • 维护密钥台账:从一张记录 Key ID、用途、负责人与最近轮换时间的基础表格开始,逐步补齐地域、业务空间、权限范围、预算等字段;台账不保存完整 Key。
  • 将 Key 的管理权限(创建、查看、编辑、删除)限制在必要的管理员范围内。

缩短凭证暴露时间

妥善保管长期 API Key

新建 API Key 仅在创建时完整显示一次,关闭对话框后无法再查看或复制完整明文;若未保存,只能重置或重新创建,参见获取 API Key。 创建成功后,将完整 Key 直接存入受控凭证存储(密钥管理服务或部署平台的 Secret 管理),不要经截图、邮件、聊天工具或普通文档中转;列表中的脱敏值仅用于比对识别。 不要将长期 API Key 放入以下位置:
  • 浏览器脚本、前端构建产物、移动应用安装包
  • 公开或共享的代码仓库(仅添加 .gitignore 不能消除历史提交中的凭证)
  • Notebook 输出、示例代码
  • 截图、录屏
  • 工单、群聊、在线文档
  • Prompt、知识库、Agent 上下文
  • 请求 URL 与查询参数
  • 访问日志与异常堆栈
  • 第三方插件与模型中转服务
  • 共享环境、对外暴露的配置文件、镜像与备份
本地调试时建议通过隐藏输入设置环境变量,避免明文进入命令历史:
read -r -s -p "请输入 API Key:" DASHSCOPE_API_KEY
printf '\n'
export DASHSCOPE_API_KEY
该示例适用于 Linux/macOS 环境。
环境变量可以避免硬编码,但不是加密存储:凭证仍可能经进程诊断信息、容器配置、崩溃转储或运维导出等途径泄漏,调试时避免使用 set -x 等会输出敏感变量的选项。生产环境请使用密钥管理服务或部署平台的 Secret 注入。
若曾将 API Key 提供给不可信的模型中转服务或第三方插件,建议停止向其交付新 Key,改用官方接口或可信服务端集成,并轮换已交付的 Key。

客户端场景使用临时 API Key

浏览器、移动 App、小程序等环境无法可靠保密凭证。这类场景请由已鉴权的后端签发临时 API Key,供前端直连使用:
  1. 长期 API Key 仅保存在您自己的服务器上,不下发到任何客户端。
  2. 前端需要调用模型时,先向您的后端申请临时 Key。
  3. 后端调用生成临时 API Key 接口,签发短有效期的 st- Key 返回给前端。
  4. 前端使用 st- Key 直连百炼调用模型。
临时 API Key 默认有效期 60 秒,可通过 expire_in_seconds 设置 1~1800 秒(按任务所需的最短时长设置,不要无条件使用最大值),到期自动失效,不支持提前删除;它继承签发它的长期 API Key 的全部权限,需要更小权限时应先收窄用于签发的长期 Key。签发接口通过 OpenAPI 以长期 Key 发起调用,应校验调用权限并限制签发频率,避免成为公开的凭证发放入口。接口详情参见生成临时API Key。

定期轮换与离岗回收

长期有效的 Key 配置在代码或 Agent 中,暴露面会随时间累积,应定期轮换:
  1. 创建新 Key,按当前需求重新配置权限与预算。
  2. 更新业务侧的凭证引用。
  3. 验证新 Key 调用正常。
  4. 删除旧 Key,并确认旧 Key 无法发起新调用。
  5. 更新密钥台账。
新 Key 不会自动继承旧 Key 的权限与预算配置,需重新设置。人员离岗或业务下线时,必须单独清点并删除或轮换其名下的 Key:2026 年 3 月 25 日及之后创建的 API Key 不会因删除归属 RAM 用户而级联删除,仍可继续使用(该规则仅在 Key 归属 RAM 子账号时相关),因此不能仅凭 RAM 用户已删除就认定凭证已回收,参见时效性与限制。 若多个 Key 保存在同一台疑似被入侵的服务器、公开配置、代码仓库或第三方环境中,应一并轮换可能受影响的凭据并修复环境:既不必无差别更换全部 Key,也不要只处置单个 Key 而忽略共同暴露的环境。 进阶做法:将 Key 明文托管在密钥管理服务(KMS)中,由应用按凭证名取用,并利用 KMS 的密钥轮转能力定期更新。

收窄凭证权限范围

一业务一 Key 与业务空间隔离

为不同应用和不同环境(生产、测试、个人调试)分配独立的 API Key:既缩小单个 Key 泄漏的影响面,也便于按 Key 定位问题与单独轮换。需要权限隔离、精细化模型访问控制或独立成本核算时,为业务分配非默认业务空间(业务空间是百炼中隔离权限与成本的容器,账号默认已有默认业务空间),Key 的基础调用范围受归属业务空间约束,参见权限管理。 同时将 Key 的管理权限限制在必要的管理员范围内;可登录控制台管理凭证的账号应采用最小权限并按组织要求启用多因素认证。

配置 IP 白名单与模型范围

在 API Key 的创建或编辑面板中将权限设为自定义后,可进一步收窄 Key 的调用范围:
  • IP 白名单:仅放通业务实际使用的公网出口 IP 或网段,最多 20 个(可通过 curl ifconfig.me 等方式查询公网出口)。默认放通全部 IPv4 地址,仅创建 Key 不等于已启用来源限制。经 NAT、代理或网关调用时,请填写百炼实际看到的公网出口地址,而非服务器内网地址。
  • 访问模型范围:开启后该 Key 仅能调用已勾选的模型(最多 30 个,受业务空间已授权模型约束),防止泄漏后被用于高成本模型。
配置后建议验证收窄是否生效:仅允许的网络与模型可调用、未授权的不可调用;验证时不要输出完整 Key。操作入口与完整规则参见如何管理 API Key 的权限。
IP 白名单不能替代凭证保密:能从同一出口网络发起调用的人员或被入侵的主机,仍可能滥用泄漏的 Key。

通过私网连接调用

对网络安全要求较高的场景,可在您的 VPC 与百炼之间建立私网连接(PrivateLink):调用不经公网,即使 Key 泄漏,网络不连通的外部攻击者也无法调用。配置方法参见通过终端节点私网访问阿里云百炼模型或应用 API。

配置预警与止损

预算告警与达预算即停

为账号、业务空间或单个 API Key 设置月度预算与告警阈值,优先为开发测试、演示、第三方接入等高风险 Key 设置独立预算。费用达到阈值与预算用尽时会通过站内信、短信、邮件或机器人通知;开启“达到预算后立即停止”后,预算耗尽将限制该维度按量调用并返回 429。配置方法参见预算管理。
“达到预算后立即停止”存在生效延迟,延迟期间费用仍会计取;预置吞吐(PTU)溢出部分与应用产生的调用暂不支持自动停止。生产关键业务不建议开启自动停止,优先预警加受控处置。

模型监控告警

模型监控按业务空间统计调用次数、Token 用量、失败次数、失败率等指标,支持按 API Key 筛选,并可基于预置告警模板或自定义模板创建告警规则,通知到联系人或联系人组。建议为高风险 Key 配置调用量、调用次数突增类告警:异常在调用发生后分钟级可见,非工作时段触发即人工介入。首次配置告警需先在数据投递中授权云监控服务角色,配置方法参见告警。

平台风险检测

平台会周期性扫描公开代码库等公网环境,识别泄漏的 API Key 并主动告知,具体渠道以实际启用的为准(可能包括短信、邮件、站内信等);同时识别非常用 IP 登录、夜间突发流量、费用异常激增等异常行为。 平台风险检测与告警是平台为提升使用体验而主动提供的异常检测与预警能力,不在 SLA 约定的服务范围内;受风险场景复杂性所限,不承诺绝对的告警覆盖率,告警的识别与送达也可能存在时延。API Key 等凭据的安全保管与合规使用属于您的责任范畴,请以自行配置的预算告警、模型监控告警与定期轮换作为主要防线;未收到平台告警不代表没有泄漏风险。发现疑似泄漏或收到告警后,请按 API Key 泄漏排查定位并处置。

上线前检查清单

个人开发者或小团队可先完成最小起步:为 Key 设置预算与告警通知、凭证仅存于环境变量、定期轮换。完整检查清单如下:
  • 生产、测试及第三方接入不共用同一个 API Key,Key 负责人和用途明确。
  • 归属地域、业务空间、模型范围和请求出口 IP 已核对,权限仅覆盖必要范围。
  • 长期 Key 仅保存在受控后端,不进入客户端、源码、Prompt、共享文档或日志。
  • Key 未交付不可信的第三方中转服务或插件环境;如曾交付,已停止交付并轮换。
  • 凭证通过环境变量或 Secret 注入,敏感文件与构建产物不含明文。
  • 客户端直连场景由已鉴权后端签发短期 Key,签发用的长期 Key 权限已收窄。
  • 新版 Key 已受控保存;旧版 Key、闲置 Key 和离岗人员相关 Key 已核对。
  • 账号、业务空间及 Key 级预算与告警已配置,通知渠道与责任人明确。
  • “达到预算后立即停止”的可用性影响与生效延迟已评估。
  • 轮换与泄漏处置流程已明确,排查步骤参见 API Key 泄漏排查。

常见问题

不小。临时 API Key 继承签发它的长期 API Key 的全部权限,仅有效期更短。需要更小权限时,应先收窄用于签发的长期 API Key。
需要。IP 白名单只能限制调用来源网络,泄漏到同一出口网络内的 Key 仍可能被滥用。请结合最小权限、预算告警与定期轮换使用。
停止向该服务交付新 Key,轮换已交付的 Key,并改用官方接口或可信服务端集成。已泄漏 Key 的处置步骤参见 API Key 泄漏排查。