# Key 安全

> 灵眸 API Key IP 白名单 / 黑名单配置指南：限制可调用 IP，防止密钥泄漏被盗刷，支持单 IP 与 CIDR 网段。

URL: https://docs.lmuai.ai/cn/docs/guide/key-security



Key 一旦泄漏，可能被他人盗用消耗你的额度。**IP 白名单**是最直接的防护——只允许你信任的 IP 使用这把 Key。

## 在哪里配置 [#在哪里配置]

**控制台 → API Keys → 编辑（或新建）**，找到 **IP 白名单** 和 **IP 黑名单** 两个输入框。

每行一条规则，支持两种格式：

| 格式      | 示例               | 说明                         |
| ------- | ---------------- | -------------------------- |
| 单个 IP   | `203.0.113.10`   | 精确匹配一个 IP                  |
| CIDR 网段 | `203.0.113.0/24` | 匹配一整段 IP（`/24` = 256 个 IP） |

IPv4 和 IPv6 都支持（IPv6 示例：`2001:db8::/32`）。

## 生效规则 [#生效规则]

* **白名单为空** → 不限制来源，任何 IP 都能用
* **白名单非空** → 只有列表内的 IP 能用，其它一律拒绝
* **黑名单** → 命中即拒绝，**优先级高于白名单**
* 两者可以同时用（先查黑名单再查白名单）

被拒绝时，接口返回 `403 ACCESS_DENIED`。

## 找到你的真实出口 IP（关键！） [#找到你的真实出口-ip关键]

**这是最容易踩的坑**：你在 Key 上配的 IP，必须是灵眸服务器看到的**公网出口 IP**，不是你电脑上 `ipconfig` / `ifconfig` 显示的内网地址。

```bash
# 命令行
curl https://ifconfig.me
# 或
curl https://ip.sb
```

或者在浏览器打开 [ip.sb](https://ip.sb) / [ifconfig.me](https://ifconfig.me) 查看。

<Callout type="warn">
  开了 VPN、公司代理、移动网络切换 Wi-Fi 时，出口 IP 会变。配白名单前先用上面的命令确认一次。
</Callout>

## 常见场景配法 [#常见场景配法]

**场景 1：固定办公 IP**

```
白名单：
203.0.113.10
```

**场景 2：家 + 公司两处办公**

```
白名单：
203.0.113.10      # 公司出口
198.51.100.20     # 家里宽带
```

**场景 3：跑在自己的云服务器上**

```
白名单：
<你云服务器的公网 IP>
```

只允许你的服务器调用，本地开发用另一把 Key（不设白名单）。

**场景 4：只是想临时封掉某个可疑 IP**

```
黑名单：
1.2.3.4
```

其它照常，不影响正常使用。

## 排错 [#排错]

**问：调用返回 403 ACCESS\_DENIED，是不是 IP 限制？**

大概率是。请依次检查：

1. 用 `curl https://ifconfig.me` 确认当前真实出口 IP
2. 对照 Key 的白名单看是否匹配
3. 如果不匹配，把当前 IP 加入白名单，或临时清空白名单测试
4. 依旧被拒，检查是否在黑名单里、Key 是否已停用、额度是否耗尽

**问：白名单填了 IP 但依然被拒？**

* 填的是**内网 IP**（`192.168.x.x` / `10.x.x.x` / `172.16-31.x.x`）？换成公网出口 IP。
* 填的是 IPv6 但你用 IPv4 出网（或反之）？两个都填上。
* 填了 CIDR 但格式错误（如 `1.2.3.4/33`）？错误规则会被静默忽略。

## 建议做法 [#建议做法]

* **生产用的 Key** 强烈建议配 IP 白名单，把攻击面缩到最小
* **开发/调试的 Key** 可以不配白名单，但一定要设**总额度上限**兜底
* 泄漏担忧较大时，配合 [**限流**、**总额度**、**模型白名单**](./how-to-use-token) 一起用，层层设防
* Key 一旦怀疑泄漏，第一时间在控制台**重置或删除**该 Key