> 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/getting-started/maxmind-setup.md).
# MaxMind 設定（必需）
設定 IP 地理定位與 ASN 查詢所需的 MaxMind GeoLite2 資料庫。
MyIP 讀取兩個免費 **GeoLite2** 來自 MaxMind 的資料庫 — `GeoLite2-City.mmdb` 以及 `GeoLite2-ASN.mmdb` — 用於本機、離線的 IP 地理定位與 ASN 查詢。
它們是 **不** 在儲存庫中，且 **不** 在 Docker 映像中。MaxMind 的 GeoLite2 授權不允許重新散布，因此每個部署都必須自行攜帶一份副本。
## 缺少它們會造成什麼問題
伺服器仍會啟動。但：
* `/api/maxmind` 回傳 **503** 於每個請求，因此 MaxMind IP 來源不會產生任何結果。
* 建立在該來源上的功能——包括為 WebRTC ICE 候選項顯示的國家徽章——都會保持空白。
* 每次啟動都會記錄 `❌ 在資料庫成功載入之前，MaxMind API 會回傳 503`.
其他 IP 來源仍會正常運作，所以應用程式看起來是半壞掉，而不是真的壞掉。這正是本頁必讀的原因。
## 取得憑證
{% stepper %}
{% step %}
#### 建立免費的 GeoLite2 帳號
在以下網址註冊： [maxmind.com/en/geolite2/signup](https://www.maxmind.com/en/geolite2/signup)。不需要付款資訊。
{% endstep %}
{% step %}
#### 記下你的帳號 ID
MaxMind 會在你的帳號儀表板中顯示它。那是一個數字，不是你的電子郵件地址。
{% endstep %}
{% step %}
#### 產生授權金鑰
開啟 **管理授權金鑰** 並建立新的金鑰。請立即複製——MaxMind 只會顯示一次。
{% endstep %}
{% endstepper %}
## 選項 A — 自動下載（建議）
設定三個變數，讓 MyIP 自行抓取並更新資料庫。
{% code title=".env" %}
```bash
MAXMIND_ACCOUNT_ID="your-account-id"
MAXMIND_LICENSE_KEY="your-license-key"
MAXMIND_AUTO_UPDATE="true"
```
{% endcode %}
在 Docker 中，使用以下方式傳入相同的三個變數： `-e` ——請參見 [使用 Docker 部署](/developer/zh-tw/getting-started/deploy-with-docker.md).
接著會發生什麼：
| 當 | 會發生什麼 |
| --------- | ------------------------------------------------------------------------------- |
| 啟動時，檔案不存在 | 後端會下載兩個資料庫 **在開始監聽之前**，最長 5 分鐘。只要憑證存在就會執行，即使 `MAXMIND_AUTO_UPDATE` 是 `"false"`. |
| 啟動時，檔案已存在 | 不會下載任何內容；現有檔案會立即載入。 |
| 啟動後約 60 秒 | 更新程式會執行第一次排程檢查。 |
| 之後每 24 小時 | 它會再次檢查，並且只下載 MaxMind 實際更新的內容。 |
{% hint style="success" %}
**更新在設計上就是安全的。** 新檔案會下載到暫存目錄，開啟並驗證後，再以原子方式搭配 `.bak` 作為回退。之後檔案監看器會重新載入記憶體中的讀取器，因此資料庫更新不會重新啟動伺服器，也不會提供半寫入的檔案。鎖定檔可防止兩個程序（例如兩個 pm2 實例）同時更新。
{% endhint %}
{% hint style="warning" %}
**Docker 部署者必須使用選項 A。** 新的容器完全沒有 `.mmdb` 任何檔案，除非你自己建置映像，否則也沒有地方可供複製。
{% endhint %}
## 選項 B — 手動放置
適用於離線網路主機，或如果你不想讓應用程式對 MaxMind 擁有外連存取權。這只有在你 [從原始碼部署](/developer/zh-tw/getting-started/deploy-with-nodejs.md).
{% stepper %}
{% step %}
#### 下載資料庫
從你的 MaxMind 帳號下載 **GeoLite2 City** 以及 **GeoLite2 ASN** 以 `.mmdb` （二進位）形式的封存檔，並將它們解壓。
{% endstep %}
{% step %}
#### 放到正確位置
將兩個檔案複製到 `common/maxmind-db/`，並保留完全相同的名稱：
```
common/maxmind-db/GeoLite2-City.mmdb
common/maxmind-db/GeoLite2-ASN.mmdb
```
{% endstep %}
{% step %}
#### 關閉自動更新
```bash
MAXMIND_AUTO_UPDATE="false"
```
然後啟動後端。它會找到這些檔案並載入。
{% endstep %}
{% endstepper %}
{% hint style="info" %}
使用選項 B 時，你需要在 MaxMind 發布新版本時自行更新這些檔案。替換後不需要重新啟動伺服器——檔案監看器會偵測到變更，並在幾秒內重新載入讀取器。
{% endhint %}
## 驗證
正常啟動會記錄：
```
📦 MaxMind 資料庫已載入（啟動）
```
開啟自動更新後，你還會看到排程：
```
🗓️ MaxMind 自動更新計畫：下次檢查時間為 ...，之後每 24 小時一次
```
## 疑難排解
❌ 在資料庫成功載入之前，MaxMind API 會回傳 503
後端無法開啟兩個 `.mmdb` 檔案。往上查看日誌——在這一行上方總會有更具體的一行告訴你原因。常見原因：
* 憑證缺失，所以從未下載任何內容。
* 下載失敗（請見下方項目）。
* 兩個檔案中只有一個存在。MyIP 需要 **兩個** City 和 ASN。
⚠️ MaxMind 資料庫遺失，且未設定 MAXMIND_ACCOUNT_ID / MAXMIND_LICENSE_KEY
這些變數從未傳到程序。請檢查：
* 你的 `.env` 位於專案根目錄，而且你在編輯後已重新啟動。
* 在 Docker 中， `-e` 旗標位於 `docker run` 指令（或在 `environment:` 區塊）——而不是在 `docker exec`.
* 變數名稱的拼法必須與上面完全一致。
檢查 GeoLite2-City 失敗：HTTP 401
MaxMind 拒絕了這些憑證。帳號 ID 和授權金鑰會作為 HTTP Basic 驗證，用於 `download.maxmind.com`，所以 401 代表其中一個有誤。
* 請確認帳號 ID 是數字 ID，而不是你的電子郵件。
* 重新產生授權金鑰——金鑰可能被撤銷，而且少複製一個字元的複製/貼上內容看起來會與有效金鑰完全相同。
* 請確認該金鑰是為 **GeoLite2**，且位於同一帳號下。
MaxMind 初始下載失敗：下載未能在 5 分鐘內完成
啟動下載已達時間上限。這是網路問題，不是憑證問題——請檢查主機是否能連上 `download.maxmind.com` （防火牆、外連規則、代理伺服器）。伺服器仍會照常啟動，而排程更新程式會再次嘗試。
MaxMind 自動更新計畫：已停用
`MAXMIND_AUTO_UPDATE` 並非完全是 `"true"`。只有這個字面值才會啟用週期性更新。
請注意，這只會影響 **24 小時更新** 而已。當檔案缺失且憑證存在時，啟動下載仍會執行。
MaxMind 自動更新已略過：缺少 MAXMIND_ACCOUNT_ID 或 MAXMIND_LICENSE_KEY
已要求自動更新，但兩個憑證中有一個是空的。兩者都必須提供。
MaxMind 更新已略過：另一個程序正在更新資料庫
當你執行多個後端執行個體時這是預期行為——其中一個持有更新鎖，其餘會讓開。無害。
如果你每次嘗試都看到它，前一次執行很可能當掉並遺留了鎖。當它滿 2 小時後會自動清除；若要現在清除，請刪除 `.maxmind-update.lock` 以 fire-and-forget 方式填入，來源是 `common/maxmind-db/`.
## 後續步驟
* [使用 Docker 部署](/developer/zh-tw/getting-started/deploy-with-docker.md) — 資料庫在容器內所在的位置
* [選用 API 金鑰](/developer/zh-tw/configuration/optional-api-keys.md) — 除 MaxMind 之外的額外 IP 資料來源
* [IP 資料來源](/developer/zh-tw/architecture/ip-data-sources.md) — MyIP 如何整合其來源
---
# 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/getting-started/maxmind-setup.md?ask=&goal=
```
`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.