> 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/getting-started/maxmind-setup.md).
# MaxMind 设置（必需）
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="你的账户 ID"
MAXMIND_LICENSE_KEY="你的许可密钥"
MAXMIND_AUTO_UPDATE="true"
```
{% endcode %}
在 Docker 中，使用 `-e` ——参见 [使用 Docker 部署](/developer/zh/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/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` 来自 `common/maxmind-db/`.
## 下一步
* [使用 Docker 部署](/developer/zh/getting-started/deploy-with-docker.md) ——数据库在容器内部存放的位置
* [可选 API 密钥](/developer/zh/configuration/optional-api-keys.md) ——除 MaxMind 之外的其他 IP 数据源
* [IP 数据源](/developer/zh/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/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.