> For the complete documentation index, see [llms.txt](https://docs.ipcheck.ing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipcheck.ing/developer/zh/configuration/optional-api-keys.md).

# 可选 API 密钥

本页上的这些密钥都不是必需的。MyIP 即使一个都没有也能启动并提供流量服务。每个密钥只是多解锁一项能力。

模式始终相同：

1. 你设置一个环境变量并重启后端。
2. 后端会暴露一个 **布尔值** （从不暴露其值）通过 `GET /api/configs`.
3. 前端读取这些布尔值，并显示、隐藏或禁用相应的界面。

{% hint style="info" %}
`/api/configs` 只会返回 `true` / `false`。你的密钥会保留在服务器上，绝不会发送到浏览器。
{% endhint %}

## 摘要

| 环境变量                                                   | 解锁内容                                              | 成本                     |
| ------------------------------------------------------ | ------------------------------------------------- | ---------------------- |
| `IPINFO_API_KEY`                                       | 将 IPinfo.io 作为可选的 IP 地理定位来源                       | 有免费套餐                  |
| `IPAPIIS_API_KEY`                                      | 将 IPAPI.is 作为可选的 IP 地理定位来源                        | 查看提供商定价                |
| `IP2LOCATION_API_KEY`                                  | 将 IP2Location.io 作为可选的 IP 地理定位来源                  | 有免费套餐                  |
| `GOOGLE_MAP_API_KEY`                                   | IP 详情卡片上的地图按钮（Google Static Maps）                 | 启用了计费的 Google Cloud 账户 |
| `MAC_LOOKUP_API_KEY`                                   | 经身份验证的 MAC Lookup 请求（即使没有它工具也能工作）                 | 有免费套餐                  |
| `CLOUDFLARE_API_KEY`                                   | ASN 信息面板（Cloudflare Radar）——以及在配合下面两个变量时，可生成可分享报告 | 免费的 Cloudflare 账户      |
| `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_KV_NAMESPACE_ID` | 存储在 Workers KV 中的可分享诊断报告                          | 免费的 Cloudflare 账户      |
| `RIPESTAT_SOURCE_APP`                                  | 这不是密钥——它用于向 RIPEstat 标识你的部署                       | 免费，无需注册                |

{% hint style="warning" %}
`/api/configs` 可在边缘缓存一小时。添加密钥并重启后，CDN 或浏览器可能会继续提供旧的功能标志，最长达一小时。若新功能没有出现，请强制刷新或清除缓存。
{% endhint %}

## IP 地理定位来源

MyIP 可以查询多个 IP 数据库。用户在 **偏好设置**中选择当前启用的那个。缺少密钥的来源会以删除线显示，且无法选择；如果先前保存的选项失去了其密钥，它会自动切换到最近可用的来源，并给出提示。

有三个来源受密钥限制：IPinfo.io、IPAPI.is 和 IP2Location.io。其他来源（IP-API.com、IP.sb、MaxMind）不需要密钥——参见 [MaxMind 设置](/developer/zh/getting-started/maxmind-setup.md) 和 [IP 数据来源](/developer/zh/architecture/ip-data-sources.md).

### IPinfo.io — `IPINFO_API_KEY`

* **解锁内容**: `IPinfo.io` 在 IP 来源选择器中，由 `GET /api/ipinfo`.
* **没有它**：该来源在选择器中会被禁用。（接口本身会回退到无需令牌的请求，但界面不会提供它。）
* **在哪里获取**：在 [ipinfo.io](https://ipinfo.io/) 注册，然后从控制台复制访问令牌。

{% hint style="info" %}
旧版写法 `IPINFO_API_TOKEN` 仍会作为回退项读取，因此旧部署在升级后仍可继续工作。新配置应使用 `IPINFO_API_KEY`.
{% endhint %}

### IPAPI.is — `IPAPIIS_API_KEY`

* **解锁内容**: `IPAPI.is` 在 IP 来源选择器中，由 `GET /api/ipapiis`。该来源还会返回主机托管 / 代理标志。
* **没有它**：该来源在选择器中会被禁用。直接调用该接口会返回 500。
* **在哪里获取**：在 [ipapi.is](https://ipapi.is/).

### IP2Location.io — `IP2LOCATION_API_KEY`

* **解锁内容**: `IP2Location.io` 在 IP 来源选择器中，由 `GET /api/ip2location`.
* **没有它**：该来源在选择器中会被禁用。直接调用该接口会返回 500。
* **在哪里获取**：在 [ip2location.io](https://www.ip2location.io/).

{% hint style="success" %}
**已内置密钥轮换。** `IPINFO_API_KEY`, `IPAPIIS_API_KEY`, `IP2LOCATION_API_KEY` 和 `GOOGLE_MAP_API_KEY` 都接受一个 **逗号分隔列表**。每次请求都会随机选取一个密钥，从而把负载分散到多个免费账户上。

```bash
IPINFO_API_KEY="token_one,token_two,token_three"
```

{% endhint %}

## Google Maps — `GOOGLE_MAP_API_KEY`

* **解锁内容**：IP 详情卡片上的地图按钮。它会打开一张以该 IP 坐标为中心的静态地图，由 `GET /api/map`提供，并带有专门的深色模式样式。
* **没有它**：地图按钮不会渲染。卡片上的其他内容不受影响。
* **在哪里获取**：Google Cloud 控制台 → 启用 **Maps Static API** → 创建 API 密钥。需要一个已启用计费的 Google Cloud 项目。

{% hint style="warning" %}
在将密钥放到公开实例之前，请在 Google Cloud 中限制该密钥（按 API 限制，且在可能时按 IP 限制）。后端会代理该图片，因此密钥不会到达访问者手中——但如果密钥从服务器端泄露，仍然会带来计费风险。
{% endhint %}

## MAC Lookup — `MAC_LOOKUP_API_KEY`

* **解锁内容**：对 [maclookup.app](https://maclookup.app/) 的已认证请求（来自 MAC Lookup 工具（`GET /api/macchecker`).
* **没有它**：该工具仍可正常工作。后端会在没有密钥的情况下发送请求，而提供商对匿名流量施加的任何限制，也会适用于你。
* **在哪里获取**：在 [maclookup.app](https://maclookup.app/) 注册并创建一个 API 密钥。

这是本页上唯一一个购买的是吞吐量而不是功能的密钥。

## Cloudflare Radar — `CLOUDFLARE_API_KEY`

* **解锁内容**： **ASN 信息** 按钮位于 IP 详情卡片的 ASN 区块中，由 `GET /api/cfradar`提供。该面板显示 ASN 名称、国家/地区、组织和估计用户数，以及 7 天流量拆分：IPv4 对 IPv6、HTTP 对 HTTPS、桌面端对移动端、机器人对真人。
* **没有它**：ASN 信息按钮会被隐藏。旁边的两个按钮—— **ASN 历史** 和 **ASN 连通性** ——仍可继续工作：它们由 RIPEstat 和本地 CAIDA 快照提供支持，而不是由 Cloudflare 提供。
* **在哪里获取**：Cloudflare 控制台 → **我的个人资料 → API 令牌 → 创建令牌**。该令牌需要对 Radar 的读取权限。

{% hint style="info" %}
旧版写法 `CLOUDFLARE_API` 仍会作为回退项读取。
{% endhint %}

Radar 数据会作为五个独立片段获取。如果其中一些失败，面板会按字段逐步降级，而不是直接报错——较小或私有的 ASN 合理地可能没有流量数据。

## 可分享报告—— `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_KV_NAMESPACE_ID`

MyIP 可以将一次诊断运行转换为由 Cloudflare Workers KV 支持的分享链接。

* **解锁内容**: `POST /api/report` （存储）和 `GET /api/report/:id` （读取），以及报告对话框中的分享链接选项和只读报告页面。
* **需要三者全部满足**: `CLOUDFLARE_API_KEY`, `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_KV_NAMESPACE_ID`。缺少任意一个，该功能都会保持关闭。
* **没有它们**：两个接口都会返回 `503`, `/api/configs` reports `reportSharing: false`，且分享界面永远不会出现。用户仍然可以将报告复制为 Markdown，或下载为 JSON。

<details>

<summary>设置方法</summary>

1. Cloudflare 控制台 → **Workers & Pages → KV** → 创建一个命名空间。
2. 复制该命名空间的 **十六进制 ID** ——不是它的名称。 `CLOUDFLARE_KV_NAMESPACE_ID` 需要的是该 ID。
3. 复制你的 **账户 ID** 从控制台复制到 `CLOUDFLARE_ACCOUNT_ID`.
4. 确保 `CLOUDFLARE_API_KEY` 中的令牌还包含 **Workers KV Storage: Edit** 权限。Radar 和 KV 使用的是同一个令牌。

</details>

存储的报告如何表现：

* 报告正文会根据严格的 schema 白名单进行验证——不能存储自由格式文本。
* 报告 ID 由 16 个随机字节组成，经过 base64url 编码后为 22 个字符，因此链接无法猜测。
* 每份报告都会写入 TTL，并会在 KV 中自行过期。过期的 ID 会返回 `404`.
* 报告在读取或写入时都不会被边缘缓存。

{% hint style="warning" %}
报告接口具有 **没有单独的速率限制**。在公开实例上，请用全局限流器保护它们（参见 [安全选项](/developer/zh/configuration/security-options.md)）或使用边缘规则。
{% endhint %}

## RIPEstat — `RIPESTAT_SOURCE_APP`

这不是 API 密钥，也不需要账户。RIPEstat 要求调用方通过一个 `sourceapp` 参数来自我标识；此变量用于设置它。默认值为 `myip`.

将其设置为能标识你的部署的内容（例如 `myip-yourdomain`），这样如果 RIPE 需要就此联系你，你的流量就能被区分出来。

RIPEstat 为 ASN 历史和 ASN 连通性所使用的组织名称回退提供支持。无论是否设置此变量，它们都能工作。

## 无需配置的内容

* **GitHub 星标** (`GET /api/github-stars`）会未认证地调用 GitHub 的公开 REST API，并会在边缘缓存一天。无需设置令牌。
* **ASN 连通性** 基于本地 CAIDA 快照运行，RIPEstat 仅在组织名称缺失时作为回退。

## 设置变量

{% tabs %}
{% tab title="Node（.env）" %}
{% code title=".env" %}

```bash
IPINFO_API_KEY="your-ipinfo-token"
IPAPIIS_API_KEY="your-ipapi-is-key"
IP2LOCATION_API_KEY="your-ip2location-key"
GOOGLE_MAP_API_KEY="your-google-maps-key"
MAC_LOOKUP_API_KEY="your-maclookup-key"
CLOUDFLARE_API_KEY="your-cloudflare-token"
CLOUDFLARE_ACCOUNT_ID="your-account-id"
CLOUDFLARE_KV_NAMESPACE_ID="your-namespace-hex-id"
RIPESTAT_SOURCE_APP="myip-yourdomain"
```

{% endcode %}

之后重启后端。参见 [使用 Node.js 部署](/developer/zh/getting-started/deploy-with-nodejs.md).
{% endtab %}

{% tab title="Docker" %}

```bash
docker run -d -p 18966:18966 \\
  -e IPINFO_API_KEY="your-ipinfo-token" \\
  -e GOOGLE_MAP_API_KEY="your-google-maps-key" \\
  -e CLOUDFLARE_API_KEY="your-cloudflare-token" \\
  -e CLOUDFLARE_ACCOUNT_ID="your-account-id" \\
  -e CLOUDFLARE_KV_NAMESPACE_ID="your-namespace-hex-id" \\
  -e RIPESTAT_SOURCE_APP="myip-yourdomain" \\
  --name myip \\
  jason5ng32/myip:latest
```

本页上的每个变量都会在运行时读取，因此 `docker run -e` 就足够了——无需重新构建。参见 [使用 Docker 部署](/developer/zh/getting-started/deploy-with-docker.md).
{% endtab %}
{% endtabs %}

## 相关页面

* [环境变量](/developer/zh/reference/environment-variables.md) ——完整列表，包括必需项
* [与 IPCheck.ing 绑定的功能](/developer/zh/configuration/features-tied-to-ipcheck-ing.md) ——依赖私有服务的能力
* [API 端点](/developer/zh/reference/api-endpoints.md) ——每条路由返回什么
* [安全选项](/developer/zh/configuration/security-options.md) ——防止陌生人耗尽你的配额


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ipcheck.ing/developer/zh/configuration/optional-api-keys.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.