> 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-tw/configuration/optional-api-keys.md).

# 選用 API 金鑰

可選的第三方 API 金鑰，以及各自解鎖的功能。

本頁上的金鑰沒有任何一個是必需的。MyIP 會在沒有其中任何一個的情況下啟動並提供流量服務。每一把金鑰只是多開啟一項能力。

模式永遠都一樣：

1. 你設定一個環境變數，然後重新啟動後端。
2. 後端會透過 **布林值** （從不回傳值本身）來公開該變數，透過 `GET /api/configs`.
3. 前端讀取這些布林值，並顯示、隱藏或停用對應的 UI。

{% hint style="info" %}
`/api/configs` 只會回覆 `true` / `false`。你的金鑰會留在伺服器上，永遠不會送到瀏覽器。
{% endhint %}

## 摘要

| 環境變數                                                   | 解鎖                                                                        | 成本                      |
| ------------------------------------------------------ | ------------------------------------------------------------------------- | ----------------------- |
| `IPINFO_API_KEY`                                       | 可選的 IP 地理定位來源：IPinfo.io                                                   | 提供免費方案                  |
| `IPAPIIS_API_KEY`                                      | 可選的 IP 地理定位來源：IPAPI.is                                                    | 請參閱供應商定價                |
| `IP2LOCATION_API_KEY`                                  | 可選的 IP 地理定位來源：IP2Location.io                                              | 提供免費方案                  |
| `GOOGLE_MAP_API_KEY`                                   | IP 詳細資料卡上的地圖按鈕（Google Static Maps）                                        | 具有計費功能的 Google Cloud 帳戶 |
| `MAC_LOOKUP_API_KEY`                                   | 已驗證的 MAC Lookup 請求（沒有它工具也能運作）                                             | 提供免費方案                  |
| `CLOUDFLARE_API_KEY`                                   | ASN 資訊面板（Cloudflare Radar）、國家線上活動熱圖、Earth Online 中斷資訊流——以及再加上下方兩項時，可分享的報告 | 免費的 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-tw/getting-started/maxmind-setup.md) 與 [IP 資料來源](/developer/zh-tw/architecture/ip-data-sources.md).

### IPinfo.io — `IPINFO_API_KEY`

* **解鎖**: `IPinfo.io` 在 IP 來源選擇器中，由 `GET /api/ipinfo`.
* **沒有它**：該來源會在選擇器中停用。（端點本身會回退為無 token 的請求，但介面不會提供它。）
* **取得位置**：在 [ipinfo.io](https://ipinfo.io/) 註冊，然後從你的儀表板複製存取 token。

{% 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 地圖 — `GOOGLE_MAP_API_KEY`

* **解鎖**：IP 詳細資料卡上的地圖按鈕。它會打開一張以 IP 座標為中心的靜態地圖，由 `GET /api/map`提供，並有專用的深色模式樣式。
* **沒有它**：地圖按鈕永遠不會渲染。卡片上的其他內容都不受影響。
* **取得位置**：Google Cloud Console → 啟用 **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`

* **解鎖**：單一 `GET /api/cfradar` 路由的三種視圖。 **ASN 資訊** 按鈕，位於 IP 詳細資料卡的 ASN 區塊中（`?view=asn`）：面板會顯示 ASN 名稱、國家、組織與預估使用者數；已宣告的 IPv4 / IPv6 前綴數量；上游、下游與對等 AS 數量；平均連線品質（下載／上傳頻寬、延遲、抖動），彙整自針對該 ASN 執行的 Cloudflare 速度測試；以及 7 日流量拆分——IPv4 對 IPv6、HTTP 對 HTTPS、桌面對行動、機器人對真人。 **國家線上活動熱圖** 在 IP 詳細資料卡上（`?view=country-traffic`）——一個 7×24 的一週小時網格，根據 Radar 28 天的每小時 HTTP 請求時間序列建立，預設顯示疑似真人流量，並可切換為全部流量。而 **Earth Online** 全球中斷資訊流（`?view=outages`）——單靠它就足以顯示該面板的導覽項目；在沒有 pulse beacon 後端的 fork 上，則只顯示中斷內容。請參見 [與 IPCheck.ing 綁定的功能](/developer/zh-tw/configuration/features-tied-to-ipcheck-ing.md).
* **沒有它**：ASN Info 按鈕會隱藏，國家熱圖的入口永遠不會出現（它藏在相同的 `cloudFlare` 標記中 `/api/configs` 和 ASN Info 按鈕一樣），而且中斷資訊流維持關閉——在沒有 pulse beacon 後端的 fork 上，Earth Online 面板完全不會出現。兩個相鄰的按鈕—— **ASN History** 與 **ASN Connectivity** ——仍可正常運作：它們由 RIPEstat 和本機 CAIDA 快照提供支援，而不是由 Cloudflare。
* **取得位置**：Cloudflare 儀表板 → **我的個人檔案 → API Tokens → Create Token**。這個 token 需要具有 Radar 的讀取權限。

{% hint style="info" %}
舊式拼法 `CLOUDFLARE_API` 仍會被讀取作為備援。
{% endhint %}

Radar 提供給 ASN 資訊面板的資料會以八個獨立片段抓取。若其中部分失敗，面板會逐欄位降級，而不是整體錯誤——小型或私有 ASN 本來就可能沒有流量資料。關係數量多一層備援：當 Radar 的關係片段失敗或回傳空白時，會改由本機 CAIDA 快照計算。國家熱圖則不同：每個國家只會送出一個請求，該請求要麼回傳矩陣，要麼回傳有效且可快取的 `trafficMatrix: null`.

## 可分享的報告 — `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` 報告 `reportSharing: false`，而分享 UI 永遠不會出現。使用者仍然可以將報告複製成 Markdown 或下載為 JSON。

<details>

<summary>設定方式</summary>

1. Cloudflare 儀表板 → **Workers & Pages → KV** → 建立命名空間。
2. 複製該命名空間的 **十六進位 ID** ——不是名稱。 `CLOUDFLARE_KV_NAMESPACE_ID` 需要的是 ID。
3. 將你的 **Account ID** 從儀表板複製到 `CLOUDFLARE_ACCOUNT_ID`.
4. 請確認中的 token `CLOUDFLARE_API_KEY` 也具備 **Workers KV Storage: Edit** 權限。相同的 token 同時用於 Radar 和 KV。

</details>

已儲存報告的行為如下：

* 報告內容會依嚴格的 schema 白名單進行驗證——不能儲存自由格式文字。
* 報告 ID 是 16 個隨機位元組，經 base64url 編碼（22 個字元），因此連結無法猜測。
* 每份報告都會寫入 TTL，並會自行從 KV 到期。過期的 ID 會回應 `404`.
* 報告在讀取或寫入時都不會進行邊緣快取。

{% hint style="warning" %}
報告端點具有 **沒有專屬的速率限制**。在公開執行個體上，請用全域限流器保護它們（見 [安全選項](/developer/zh-tw/configuration/security-options.md)）或邊緣規則。
{% endhint %}

## RIPEstat — `RIPESTAT_SOURCE_APP`

這不是 API 金鑰，也不需要帳戶。RIPEstat 要求呼叫端透過 `sourceapp` 參數來表明身分；這個變數就是用來設定它。預設值是 `myip`.

把它設成能識別你部署的名稱（例如 `myip-yourdomain`），這樣如果 RIPE 需要就此聯繫你，你的流量就能被區分開來。

RIPEstat 為 ASN History 以及 ASN Connectivity 使用的組織名稱備援提供支援。無論有沒有設定這個變數，兩者都能正常運作。

## 不需要設定的項目

* **GitHub stars** (`GET /api/github-stars`）會未經驗證呼叫 GitHub 的公開 REST API，並在邊緣快取一天。沒有可設定的 token。
* **ASN Connectivity** 完全依賴本機 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-tw/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-tw/getting-started/deploy-with-docker.md).
{% endtab %}
{% endtabs %}

## 相關頁面

* [環境變數](/developer/zh-tw/reference/environment-variables.md) ——完整清單，包括必需項目
* [與 IPCheck.ing 綁定的功能](/developer/zh-tw/configuration/features-tied-to-ipcheck-ing.md) ——依賴私有服務的功能
* [API 端點](/developer/zh-tw/reference/api-endpoints.md) ——各路由回傳什麼
* [安全選項](/developer/zh-tw/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-tw/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.