---
title: API Key 管理
sidebarTitle: API Key
description: 创建、轮换、额度与白名单最佳实践
---

# API Key 管理

在控制台侧栏 **API Key** 中管理所有调用凭证。创建与管理前需完成 **实名认证**。

## 创建

1. 点击 **创建**
2. 填写名称（建议包含环境与用途，如 `prod-report-agent`）
3. 可选配置：
   - **可用模型**：限制该 Key 只能调用指定模型
   - **额度上限 / 剩余额度**：控制总消耗
   - **过期时间**：到期后 Key 自动失效
   - **IP 白名单**：仅允许 listed IP 调用（留空表示不限制，生产环境建议配置）

创建成功后请 **立即复制并保存** 完整密钥；之后列表仅显示脱敏前缀。

## 鉴权方式

HTTP 请求头：

```http
Authorization: Bearer <你的 API Key>
Content-Type: application/json
```

OpenAI SDK 中将该 Key 设为 `apiKey`，`baseURL` 设为 `https://api.haiyushuke.com/v1`（见 [OpenAI 兼容 SDK](/docs/guides/openai_compatible)）。

## 存储

- 环境变量：如 `HAIYUSHUKE_API_KEY`
- 密钥管理系统（KMS / Vault），勿提交至 Git 或镜像层

## 轮换流程

1. 创建新 Key（可先绑定相同模型与 IP 策略）
2. 在应用配置中灰度切换
3. 观察 **使用记录** 确认旧 Key 无流量后 **禁用** 旧 Key

## 泄露应急

1. 控制台中 **禁用** 泄露的 Key  
2. 新建 Key 并更新部署  
3. 检查 Git 历史、CI 日志、前端 bundle 是否残留  
4. 若曾未设 IP 白名单，建议新 Key 启用白名单  

## 相关文档

- [快速开始](/docs/getting-started)
- [常见问题：401 与 Key](/docs/faq#返回-401-unauthorized)