---
title: "API Key 安全：环境变量、密钥轮换与 IP 白名单 | BroadRouter"
description: "不把大模型 API 密钥写进代码和日志，每个工作负载一个密钥，定期轮换，把密钥锁定到服务器 IP，泄露时几秒内吊销。"
url: https://broadrouter.com/zh/blog/llm-api-key-security/
lang: zh-Hans
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

本页由英文原文借助 AI 翻译。 [阅读英文原文](https://broadrouter.com/blog/llm-api-key-security/) (2026-11-15 更新).

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

BroadNet Inference 团队 · 阅读约 6 分钟 · 发布于 2026-11-14 · 更新于 2026-11-15

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

## 要点

-   绝不要把密钥打包进浏览器或移动应用；从你的服务器调用大模型。
-   每个工作负载一个密钥：每个 BroadNet 账户最多 10 个有效密钥，泄露时容易隔离。
-   IP 白名单让被盗的密钥在别处无法使用。BroadNet 最多支持 32 条 IPv4、IPv6 或 CIDR 条目。
-   在 BroadNet Inference 上，吊销密钥和修改白名单都会在5 秒内生效。
-   密钥在创建一年后过期，所以轮换必须是例行工作，而不是紧急处理。

**本页内容**

1.  大模型 API 密钥应该存放在哪里？
2.  可以把 API 密钥放进浏览器或移动应用吗？
3.  为什么每个工作负载要各用一个密钥？
4.  IP 白名单怎样保护密钥？
5.  为什么要把推理密钥和管理凭据分开？
6.  API 密钥应该多久轮换一次？
7.  密钥泄露了怎么办？
8.  密钥是怎样通过日志泄露的？
9.  尚未发现的泄露，怎样把损失降到最低？
10.  BroadNet Inference 提供哪些密钥控制？

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

本文介绍保护密钥的习惯做法，以及 BroadNet Inference 提供的具体控制手段。门户中的逐步操作请看 [API 密钥与 IP 白名单指南](https://broadrouter.com/zh/guides/api-keys-ip-allow-lists/)；预算以及防止循环失控的保护，请看[大模型 API 支出控制](https://broadrouter.com/zh/blog/llm-api-spend-control/)。

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

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

```python
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 上，[推送保护](https://docs.github.com/en/code-security/secret-scanning/introduction/about-push-protection)会在包含已知密钥格式的推送到达仓库之前将其拦截；面向用户的推送保护默认开启，但仓库级推送保护默认关闭，必须由仓库管理员或组织所有者启用。

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

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

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

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

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

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

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

## IP 白名单怎样保护密钥？

有了 [IP 白名单](https://broadrouter.com/zh/glossary/ip-allow-list/)，被盗的密钥离开你自己的基础设施就无法使用。在 BroadNet Inference 上：

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

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

```bash
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 白名单指南](https://broadrouter.com/zh/guides/api-keys-ip-allow-lists/)。

白名单适合出口 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；请参阅[错误指南](https://broadrouter.com/zh/guides/errors-and-retries/)，避免监控系统把这些当成暂时性错误。

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

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

## 尚未发现的泄露，怎样把损失降到最低？

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

-   把按量付费余额保持在你能接受损失的水平，需要时再充值。
-   重度使用的智能体用固定价格套餐：套餐会话价格固定，所以被盗的套餐密钥不会产生按 token 计费的账单。参见[“不限量”到底是什么意思](https://broadrouter.com/zh/blog/what-unlimited-llm-api-really-means/)。
-   针对每个密钥的异常支出或请求速率设置告警；[大模型 API 费用计算器](https://broadrouter.com/tools/llm-api-cost-calculator/)能给出一个正常的月度数字，作为告警基准。我们关于[大模型 API 支出控制](https://broadrouter.com/zh/blog/llm-api-spend-control/)的文章介绍了预算和告警。

## BroadNet Inference 提供哪些密钥控制？

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

密钥保护你的账户；[零数据保留](https://broadrouter.com/zh/privacy/)保护你通过账户发送的内容。上线前两者都要读一读。

相关免费工具 （英文）

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[免费工具 （英文）](https://broadrouter.com/tools/)

## 本文涉及的术语

[IP 白名单（IP allow list）](https://broadrouter.com/zh/glossary/ip-allow-list/)

IP 白名单是一种安全控制：只接受来自列出的 IP 地址或 CIDR 网段的请求，拒绝其他所有请求。用在 API 上，它能限制密钥泄露造成的损失，因为密钥在不在列表中的网络上无法使用。

[AI 智能体（AI agent）](https://broadrouter.com/zh/glossary/agent/)

AI 智能体是由语言模型自主决定步骤、朝目标推进的系统：它决定调用哪些工具、读取结果，然后重复，直到给出最终回答或触及上限。在固定位置调用模型的固定脚本，通常称为工作流（workflow）。

[API 密钥（API key）](https://broadrouter.com/zh/glossary/api-key/)

API 密钥是一串用于识别和授权 API 调用方的秘密字符串。大模型 API 通常要求把它放在 Authorization: Bearer 请求头里，任何持有该密钥的人都能发起请求，费用记在拥有该密钥的账户上。

[AI 编程智能体（AI coding agent）](https://broadrouter.com/zh/glossary/coding-agent/)

AI 编程智能体是一种软件工具，其中的语言模型在循环中处理代码库：读取文件、编辑文件、运行测试等命令、读取输出并决定下一步，直到任务完成或达到某个上限。

[按量付费（pay-as-you-go）](https://broadrouter.com/zh/glossary/pay-as-you-go/)

按量付费是一种计价模式：你只为实际用量付费，按 token、请求次数或音频分钟等单位计量，没有订阅费，也没有最低消费承诺。大多数大模型 API 都这样计费，从预付余额中扣减或定期开具账单。

[大模型包月套餐（flat-rate LLM plan）](https://broadrouter.com/zh/glossary/flat-rate-llm-plan/)

大模型包月套餐（固定价格套餐）是按一个周期（如一个月）收取固定费用、提供大模型 API 使用权的计价方式，不按 token 计费。这类套餐通常会限制别的东西，如并发、速度、模型或使用时间窗口，所以限制条件和价格同样重要。

[工具调用（tool calling / function calling）](https://broadrouter.com/zh/glossary/tool-calling/)

工具调用（也叫函数调用，function calling）是大模型 API 的一项功能：模型返回一个结构化请求，要求执行开发者定义的某个函数，并附上 JSON 参数。应用执行该函数并把结果发回；模型自己从不执行代码。

[Token（词元）](https://broadrouter.com/zh/glossary/token/)

token（词元）是大语言模型读写文本的基本单位：由模型的分词器切分出的一个词、词的一部分、一个标点或一段字节序列。大模型 API 按 token 计数、设定限制，通常也按 token 计费。

## 常见问题

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

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

### BroadNet Inference 的密钥多快能吊销？

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

### BroadNet Inference 的密钥有效期多长？

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

### 密钥丢了，BroadNet 能再显示一次吗？

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

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

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

## 继续阅读

-   [大模型 API 费用控制：预算、密钥限制与死循环防护](https://broadrouter.com/zh/blog/llm-api-spend-control/)
-   [把敏感数据发给大模型 API：脱敏、最小化、少记日志](https://broadrouter.com/zh/blog/llm-api-sensitive-data/)
-   [大模型 API 报 429 错误怎么办：退避、抖动与并发限制](https://broadrouter.com/zh/blog/handle-llm-api-429-rate-limits/)
-   [GDPR 与大模型 API：要问服务商的 15 个问题](https://broadrouter.com/zh/blog/gdpr-llm-api-checklist/)
-   [BroadNet 的 GPU 硬件与推理部署方式（据 BroadNet 自述）](https://broadrouter.com/zh/blog/broadnet-gpu-fleet-and-serving/)
-   [缓存大模型 API 响应以降低成本：用 Python 实现精确匹配缓存](https://broadrouter.com/zh/blog/cache-llm-responses-cut-cost/)
-   [指南：用 IP 白名单把 API 密钥锁定到你的服务器](https://broadrouter.com/zh/guides/api-keys-ip-allow-lists/)
-   [指南：BroadNet Inference 错误码，以及什么时候该重试](https://broadrouter.com/zh/guides/errors-and-retries/)
-   [指南：用 OpenAI Python SDK 调用 BroadNet Inference](https://broadrouter.com/zh/guides/openai-python-sdk/)

用你的真实业务负载试一试。 新账户可获得 US$5 初始额度，用于 Gemma和转写。DeepSeek、GLM和Qwen3.8 需要先充值。

[开始使用](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-blog-llm-api-key-security&utm_content=page-cta) ·

**来源**

-   [BroadNet Inference API 参考：限制（密钥有效期、有效密钥数）（2026-11-14 获取） （英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-blog-llm-api-key-security&utm_content=sources#limits)
-   [BroadNet Inference API 参考：IP 白名单与门户密钥（2026-11-14 获取） （英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-blog-llm-api-key-security&utm_content=sources#ip-allow-lists)
-   [OWASP Secrets Management Cheat Sheet（2026-11-14 获取）](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)
-   [GitHub 文档：密钥扫描（2026-11-14 获取）](https://docs.github.com/en/code-security/secret-scanning/about-secret-scanning)
-   [GitHub 文档：关于推送保护（2026-11-14 获取）](https://docs.github.com/en/code-security/secret-scanning/introduction/about-push-protection)
