> 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/reference/environment-variables.md).
# 环境变量
这是权威列表。下面每个变量都会在代码中的某处被读取（`process.env.*` 在服务器端， `import.meta.env.*` 在浏览器包中）。这里未列出的内容都会被忽略。
复制 `.env.example` 到 `.env` 以启动：
{% code title="shell" %}
```bash
cp .env.example .env
```
{% endcode %}
`dotenv` 会从 `.env` 仓库根目录加载 `backend-server.js`, `frontend-server.js`, `common/logger.js`, `sentry-instrument.js`，以及 `vite.config.js`.
## 构建时 vs 运行时
MyIP 有两类变量，混淆它们是最常见的部署错误。
| 类型 | 前缀 | 由以下组件读取 | 何时生效 |
| --- | ------- | -------------------------------------------------------------- | ----- |
| 运行时 | 无前缀 | Node.js 进程（`backend-server.js`, `frontend-server.js`，API 处理程序） | 进程重启时 |
| 构建时 | `VITE_` | Vite，在 `pnpm run build` | 后才生效 |
`VITE_*` 值会在 **构建时被 Vite 内联进 JavaScript 包中** 。当应用在浏览器中运行时，不会从环境变量中读取它们。更改一个 `VITE_*` 变量并重启服务器都不会有任何效果——你必须重新构建。
{% hint style="warning" %}
**对 Docker 的影响。** 官方的 `jason5ng32/myip:latest` 镜像是在 `pnpm run build` 镜像构建时运行的，当时没有 `.env` 存在（`.env` 已列在 `.dockerignore`中）。向该镜像传入 `-e VITE_CURL_IPV4_DOMAIN=...` 对前端包 **没有影响**。要在 Docker 中使用构建时变量，你必须在构建时让这些值存在，并自行构建镜像。
{% endhint %}
## 一览所有变量
点击变量名可跳转到完整说明。
| 变量 | 默认值 | 范围 | 必需 |
| ------------------------------------------------------------------------- | -------------- | -------- | -------------- |
| [MAXMIND\_ACCOUNT\_ID](#maxmind-account-id) | `""` | 运行时 | MaxMind 功能 |
| [MAXMIND\_LICENSE\_KEY](#maxmind-license-key) | `""` | 运行时 | MaxMind 功能 |
| [MAXMIND\_AUTO\_UPDATE](#maxmind-auto-update) | `"false"` | 运行时 | — |
| [CAIDA\_AUTO\_UPDATE](#caida-auto-update) | `"false"` | 运行时 | — |
| [BACKEND\_PORT](#backend-port) | `11966` | 运行时 | — |
| [FRONTEND\_PORT](#frontend-port) | `18966` | 运行时 | — |
| [ALLOWED\_DOMAINS](#allowed-domains) | `""` | 运行时 | 非 localhost 部署 |
| [SECURITY\_RATE\_LIMIT](#security-rate-limit) | `0` | 运行时 | — |
| [SECURITY\_DELAY\_AFTER](#security-delay-after) | `0` | 运行时 | — |
| [SECURITY\_BLACKLIST\_LOG\_FILE\_PATH](#security-blacklist-log-file-path) | `""` | 运行时 | — |
| [LOG\_LEVEL](#log-level) | `"info"` | 运行时 | — |
| [LOG\_FORMAT](#log-format) | pretty | 运行时 | — |
| [LOG\_HTTP](#log-http) | `"false"` | 运行时 | — |
| [VITE\_SENTRY\_DSN\_FRONTEND](#vite-sentry-dsn-frontend) | `""` | 构建 + 运行时 | — |
| [SENTRY\_DSN\_BACKEND](#sentry-dsn-backend) | `""` | 运行时 | — |
| [SENTRY\_ENVIRONMENT](#sentry-environment) | `"production"` | 运行时 + 构建 | — |
| [SENTRY\_ORG](#sentry-org) | `""` | 构建 | — |
| [SENTRY\_PROJECT\_FRONTEND](#sentry-project-frontend) | `""` | 构建 | — |
| [SENTRY\_AUTH\_TOKEN](#sentry-auth-token) | `""` | 构建 | — |
| [GOOGLE\_MAP\_API\_KEY](#google-map-api-key) | `""` | 运行时 | — |
| [IPINFO\_API\_KEY](#ipinfo-api-key) | `""` | 运行时 | — |
| [IPAPIIS\_API\_KEY](#ipapiis-api-key) | `""` | 运行时 | — |
| [IP2LOCATION\_API\_KEY](#ip2location-api-key) | `""` | 运行时 | — |
| [CLOUDFLARE\_API\_KEY](#cloudflare-api-key) | `""` | 运行时 | 报告共享 |
| [MAC\_LOOKUP\_API\_KEY](#mac-lookup-api-key) | `""` | 运行时 | — |
| [RIPESTAT\_SOURCE\_APP](#ripestat-source-app) | `"myip"` | 运行时 | — |
| [CLOUDFLARE\_ACCOUNT\_ID](#cloudflare-account-id) | `""` | 运行时 | 报告共享 |
| [CLOUDFLARE\_KV\_NAMESPACE\_ID](#cloudflare-kv-namespace-id) | `""` | 运行时 | 报告共享 |
| [VITE\_CURL\_IPV4\_DOMAIN](#vite-curl-ipv4-domain) | `""` | 构建 | 三者全设或全不设 |
| [VITE\_CURL\_IPV6\_DOMAIN](#vite-curl-ipv6-domain) | `""` | 构建 | 三者全设或全不设 |
| [VITE\_CURL\_IPV64\_DOMAIN](#vite-curl-ipv64-domain) | `""` | 构建 | 三者全设或全不设 |
| [VITE\_SITE\_URL](#vite-site-url) | `""` | 构建 + 运行时 | — |
| [VITE\_DOCS\_URL](#vite-docs-url) | `""` | 构建 | — |
| [VITE\_GOOGLE\_ANALYTICS\_ID](#vite-google-analytics-id) | `""` | 构建 | — |
| [VITE\_INVISIBILITY\_TEST\_KEY](#vite-invisibility-test-key) | `""` | 构建 | — |
| [IPCHECKING\_API\_KEY](#ipchecking-api-key) | `""` | 运行时 | — |
| [IPCHECKING\_API\_ENDPOINT](#ipchecking-api-endpoint) | `""` | 运行时 | — |
## 必需 — MaxMind 与离线数据集
MyIP 自有的 IP 地理定位来源以及整个 UI 中的国家徽章都由本地 MaxMind GeoLite2 数据库提供。没有它们， `GET /api/maxmind` 会返回 **503**。参见 [MaxMind 设置](/developer/zh/getting-started/maxmind-setup.md).
#### `MAXMIND_ACCOUNT_ID`
默认值 `""` · 运行时 · **MaxMind 功能所必需**
MaxMind 账户 ID。与 `MAXMIND_LICENSE_KEY` 配对后，会在下载 GeoLite2 数据库时作为 HTTP Basic 凭据。
#### `MAXMIND_LICENSE_KEY`
默认值 `""` · 运行时 · **MaxMind 功能所必需**
MaxMind 许可证密钥，从你账户的“管理许可证密钥”页面生成。
#### `MAXMIND_AUTO_UPDATE`
默认值 `"false"` · 运行时 · 可选
`"true"` 启动定期更新器：启动 60 秒后先检查一次，然后每 24 小时一次。
#### `CAIDA_AUTO_UPDATE`
默认值 `"false"` · 运行时 · 可选
`"true"` 每 24 小时刷新一次 CAIDA 数据集——as2org 用于 ASN 组织名称，as-rel2 用于 ASN 连接图。
{% hint style="info" %}
`MAXMIND_AUTO_UPDATE` 仅控制 **定期调度器**。启动时“如果数据库缺失则下载”的路径不会检查它——只要存在有效凭据，数据库仍会在首次启动时获取（最多 5 分钟超时）。同样， `CAIDA_AUTO_UPDATE=false` 仍会在启动时下载缺失的 CAIDA 快照；它只会禁用每日刷新。
{% endhint %}
后端绝不会因为缺少数据库而拒绝启动。它只会记录警告，然后照常监听。
## 端口
#### `BACKEND_PORT`
默认值 `11966` · 运行时 · 可选
Express API 服务器绑定的端口。也被 `frontend-server.js` 以及 Vite 开发服务器的 `/api` 代理
#### `FRONTEND_PORT`
默认值 `18966` · 运行时 · 可选
在生产环境中绑定静态/SPA 服务器的端口，以及开发环境中 Vite 开发服务器的端口。
两者都通过 `parseInt(..., 10)`解析。Dockerfile 的 `EXPOSE` 仅 `18966` ；后端端口仍然只在容器内部可见。
## 安全
参见 [安全选项](/developer/zh/configuration/security-options.md) 和 [反向代理与域名](/developer/zh/getting-started/reverse-proxy-and-domains.md).
#### `ALLOWED_DOMAINS`
默认值 `""` · 运行时 · **对于非 localhost 部署实际上是必需的**
全局 `Referer` 在 `/api/*`. `localhost` 始终允许；否则必须把所有服务域名列在这里，否则来自你域名的每一次 API 调用都会返回 403。
#### `SECURITY_RATE_LIMIT`
默认值 `0` （已禁用）· 运行时 · 可选
每个客户端 IP 每 `/api/*` 的最大请求数 **20 分钟** 窗口内。超过限制 → `429 {"message":"请求过多"}`. `0` 或不设置会完全禁用限流器。
#### `SECURITY_DELAY_AFTER`
默认值 `0` （已禁用）· 运行时 · 可选
在一个 IP 于 `/api/*` 分钟内发出这么多 **60 分钟** 窗口后，之后每个请求都会延迟 `命中次数 × 400 毫秒`. `0` ，或不设置则禁用。
#### `SECURITY_BLACKLIST_LOG_FILE_PATH`
默认值 `""` · 运行时 · 可选
可选择写入磁盘的限流 IP 账本，例如 `"logs/blacklist-ip.log"`，按仓库根目录解析。空值表示不写入文件； `IP 被限流` 警告无论如何都会记录。
代码里的行为说明：
* **Referer 匹配就是精确的主机名匹配。** `ALLOWED_DOMAINS=example.com` 不会 **允许** sub.example.com `——把你提供服务的每个主机名都列出来。` 一个
* 没有 **头的请求会被拒绝，并返回** `Referer` 403 {"error":"你在干什么？"} `。带有不允许的`的请求会得到 `Referer` 返回 `403 {"error":"访问被拒绝"}`.
* 两个限流器都会 **跳过** `/api/monitoring`；Sentry 隧道有自己固定的限流器（每个 IP 每 20 分钟 600 个请求）。
* 限流器只会在进入限流状态时记录日志，不会对每个被阻止的请求都记录。
* `app.set('trust proxy', 1)` 已设置，所以前面要放且只放一个受信任的代理。客户端 IP 的解析顺序是 `cf-connecting-ip`，然后是 `x-forwarded-for` （第一个条目），然后是 `cf-connecting-ipv6`，最后是套接字地址。
## 日志
参见 [日志](/developer/zh/configuration/logging.md).
#### `LOG_LEVEL`
默认值 `"info"` · 运行时 · 可选
pino 最低级别： `debug` / `info` / `warn` / `error`。更低级别的消息会被丢弃——包括它们向 Sentry 的镜像。
#### `LOG_FORMAT`
默认 pretty · 运行时 · 可选
`"json"` 会为日志转运器每行输出一个 JSON 事件。其他任何值（或不设置）都使用带颜色的 `pino-pretty` 输出。
#### `LOG_HTTP`
默认值 `"false"` · 运行时 · 可选
`"true"` 挂载 `pino-http` 在 `/api/*`：每个请求一行，包含方法、URL 和状态。在限流器之前挂载，所以 429 也会被记录。
## Sentry
全部可选。若未设置 DSN，则不会加载任何 Sentry SDK，也不会有任何 Sentry 代码被打包进最终包。参见 [错误监控（Sentry）](/developer/zh/configuration/error-monitoring.md).
#### `VITE_SENTRY_DSN_FRONTEND`
默认值 `""` · 构建 **和** 运行时 · 可选
前端 DSN，在构建时烘焙进包里。 **运行时也会被** 读取， `backend-server.js` — `POST /api/monitoring` （第一方 envelope 隧道）只有在服务器进程上设置了它时才会挂载。
#### `SENTRY_DSN_BACKEND`
默认值 `""` · 运行时 · 可选
后端 DSN，由 `sentry-instrument.js` 读取（通过 `node --import`加载）以及由 `common/logger.js`读取，它会将 `warn+` 级别的行镜像到 Sentry Logs，并将 `error+` 提升为 Issues。
#### `SENTRY_ENVIRONMENT`
默认值 `"production"` · 运行时 + 构建 · 可选
后端 Sentry 事件上的环境标签。也会控制 source map 上传：只有当它未设置或为 `production`.
#### `SENTRY_ORG`
默认值 `""` · 构建 · 可选
用于构建时 source map 上传的 Sentry 组织 slug。
#### `SENTRY_PROJECT_FRONTEND`
默认值 `""` · 构建 · 可选
用于构建时 source map 上传的 Sentry 项目 slug。
#### `SENTRY_AUTH_TOKEN`
默认值 `""` · 构建 · 可选
用于构建时 source map 上传的认证令牌。未设置时，Vite 完全不会生成 source map，因此它们不会最终被公开提供自 `dist/`。构建时密钥——绝不会暴露给浏览器。
{% hint style="warning" %}
如果你自建 Docker 镜像并把 `VITE_SENTRY_DSN_FRONTEND` 烘焙进去，运行时也要把同样的值传给容器。否则包会把 envelope 发布到 `/api/monitoring`，而后端从未挂载该路由，每份报告都会 404。
{% endhint %}
## 可选 API 密钥
每个密钥都会解锁一个 IP 数据源或工具。 `GET /api/configs` 会报告这些项中哪些已设置——只返回布尔值，绝不返回具体值——前端在缺少某个密钥时会隐藏对应 UI。参见 [可选 API 密钥](/developer/zh/configuration/optional-api-keys.md) 和 [IP 数据源](/developer/zh/architecture/ip-data-sources.md).
#### `GOOGLE_MAP_API_KEY`
默认值 `""` · 运行时 · 可选
Google Static Maps 密钥，由 `/api/map`使用。接受以逗号分隔的列表；每个请求会随机选取一个密钥。
#### `IPINFO_API_KEY`
默认值 `""` · 运行时 · 可选
ipinfo.io 的令牌，用于 `/api/ipinfo`。支持逗号分隔列表。即使没有密钥，该端点仍可工作，但会使用 ipinfo.io 的匿名速率。
#### `IPAPIIS_API_KEY`
默认值 `""` · 运行时 · 可选
api.ipapi.is 的密钥，用于 `/api/ipapiis`。支持逗号分隔列表。
#### `IP2LOCATION_API_KEY`
默认值 `""` · 运行时 · 可选
ip2location.io 的密钥，用于 `/api/ip2location`。支持逗号分隔列表。
#### `CLOUDFLARE_API_KEY`
默认值 `""` · 运行时 · **报告共享所需**
Cloudflare API 令牌具有两个角色：作为 Cloudflare Radar（`/api/cfradar`）的 Bearer 令牌，以及——与 [报告共享](#report-sharing-cloudflare-kv) 中的两个变量一起——用于将可共享报告存储到 Workers KV 的凭据。KV 角色还需要令牌上的 **Workers KV Storage: Edit** 权限。
#### `MAC_LOOKUP_API_KEY`
默认值 `""` · 运行时 · 可选
maclookup.app 的密钥，用于 `/api/macchecker`。该端点在匿名速率下即使没有它也能工作。
#### `RIPESTAT_SOURCE_APP`
默认值 `"myip"` · 运行时 · 可选
作为 RIPEstat 的 `sourceapp` 查询参数发送，因此 RIPE 可以将流量归因于你的部署。
{% hint style="info" %}
`/api/ipapiis` 和 `/api/ip2location` 通过调用 `.split(',')` 来构建其上游 URL，而不做空值检查。若未设置该密钥，处理程序会抛错并返回 500。前端在该状态下不会调用它们，因为 `/api/configs` 会报告该数据源不可用，UI 也会将其隐藏。
{% endhint %}
## 报告共享（Cloudflare KV）
可共享的诊断报告通过 REST API 存储在 Cloudflare Workers KV 中。 **这三个** 变量—— [`CLOUDFLARE_API_KEY`](#cloudflare-api-key) 加上下方这两个——都必须设置，否则 `POST /api/report` 和 `GET /api/report/:id` 都会返回 `503 {"error":"报告共享未配置"}` 和 `/api/configs` 报告 `reportSharing: false`，这会隐藏共享 UI。
#### `CLOUDFLARE_ACCOUNT_ID`
默认值 `""` · 运行时 · **报告共享所需**
拥有该 KV 命名空间的 Cloudflare 账户 ID。
#### `CLOUDFLARE_KV_NAMESPACE_ID`
默认值 `""` · 运行时 · **报告共享所需**
该命名空间的 **十六进制 ID** ，来自控制面板——不是它的显示名称。
报告限制，来源于 `common/report-schema.js`：可选保留期为 1、3 或 7 天（其他值都会被强制降为 1 天），存储的有效载荷上限为 256 KB（`413` 超出部分）。Express JSON 请求体限制为 500 KB，刻意高于报告上限。
## Curl API
#### `VITE_CURL_IPV4_DOMAIN`
默认值 `""` · 构建 · 三者全有或全无
在 curl API 卡片中显示的仅 IPv4 主机名。
#### `VITE_CURL_IPV6_DOMAIN`
默认值 `""` · 构建 · 三者全有或全无
仅 IPv6 主机名。
#### `VITE_CURL_IPV64_DOMAIN`
默认值 `""` · 构建 · 三者全有或全无
双栈主机名。
{% hint style="warning" %}
curl API 卡片仅在 **三者全部** 均非空时—— `curlDomainsHadSet` 在 `frontend/store.js` 时会将它们进行 AND 组合。设置一个或两个都不会显示任何内容。而且由于这些是 `VITE_*`，它们必须在构建时就存在。
{% endhint %}
这些变量只会提供显示给用户的主机名。MyIP 本身不会提供这些端点——你需要把 DNS 记录指向你运行的任何纯文本 IP 回显服务。
## 杂项
#### `VITE_SITE_URL`
默认值 `""` · 构建 **和** 运行时 · 可选
你的部署的绝对源。在构建时，它会填充 `__SITE_URL__` 在 `index.html` （规范 / OG 标签）；当为空时，整个标记块都会被移除。运行时，它会成为上游的最后一段 `User-Agent` (`MyIP/v7.2.0/https://example.com`），因此分叉版会向上游 API 表明自己的身份，而不是冒充 ipcheck.ing。末尾斜杠会被去除。
#### `VITE_DOCS_URL`
默认值 `""` · 构建 · 可选
支撑应用内文档助手以及页脚中的帮助中心链接的 GitBook 文档站点源地址，例如 `https://docs.ipcheck.ing`。末尾斜杠会被去除；嵌入脚本从 `/~gitbook/embed/script.js` 在首次使用时加载，绝不会在页面加载时加载。
当为空时，助手和页脚链接都不会被打包进 bundle。导航入口点还要求使用规范部署——参见 [与 IPCheck.ing 绑定的功能](/developer/zh/configuration/features-tied-to-ipcheck-ing.md).
#### `VITE_GOOGLE_ANALYTICS_ID`
默认值 `""` · 构建 · 可选
Google Analytics 衡量 ID。为空时， `gtag.js` 不会注入，隐私页面会将分析报告为已禁用。自托管者应将其留空。
#### `VITE_INVISIBILITY_TEST_KEY`
默认值 `""` · 构建 · 可选
作为 `pdKey` 传给不可见性测试所使用的第三方代理检测脚本。仅在同时具备 `IPCHECKING_API_KEY`的部署中才有意义。不在 `.env.example`.
#### `IPCHECKING_API_KEY`
默认值 `""` · 运行时 · 可选
私有 IPCheck.ing 伴生 API 的 API 密钥。用于控制 `/api/ipchecking`, `/api/getuserinfo`, `PUT /api/updateuserachievement`, `/api/invisibility`，以及 `/api/dnsleaktest/session/:token` ——没有它，这些路由会返回 `500 {"error":"缺少 API 密钥"}`。也以 `ipChecking` 在 `/api/configs`的名称公开。未在 `.env.example`.
#### `IPCHECKING_API_ENDPOINT`
默认值 `""` · 运行时 · 可选
该伴生 API 的基础 URL，与 `IPCHECKING_API_KEY`的名称公开。未在 `.env.example`.
{% hint style="info" %}
`IPCHECKING_API_KEY` / `IPCHECKING_API_ENDPOINT` 和 `VITE_INVISIBILITY_TEST_KEY` 一起使用。它们属于闭源伴生服务。自托管分支无法获取它们，而它们所控制的功能会在非`ipcheck.ing` 部署中隐藏。参见 [与 IPCheck.ing 绑定的功能](/developer/zh/configuration/features-tied-to-ipcheck-ing.md).
{% endhint %}
## 旧别名
有两个变量已更名。旧拼写仍会作为回退读取，因此现有部署在升级时不会丢失功能。优先使用新名称。
| 旧名称 | 当前名称 | 读取位置 |
| ------------------ | -------------------- | ---------------------------------------------------------- |
| `IPINFO_API_TOKEN` | `IPINFO_API_KEY` | `api/ipinfo-io.js`, `api/configs.js` |
| `CLOUDFLARE_API` | `CLOUDFLARE_API_KEY` | `api/cf-radar.js`, `api/share-report.js`, `api/configs.js` |
解析顺序为 `NEW || OLD` ——如果两者都设置了，则新名称生效。
## 最小可用配置
{% code title=".env" %}
```bash
BACKEND_PORT=11966
FRONTEND_PORT=18966
ALLOWED_DOMAINS="myip.example.com"
MAXMIND_ACCOUNT_ID="your-account-id"
MAXMIND_LICENSE_KEY="your-license-key"
MAXMIND_AUTO_UPDATE="true"
```
{% endcode %}
其余内容均为可选项，只会增加数据源或工具。参见 [快速开始](/developer/zh/getting-started/quickstart.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/reference/environment-variables.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.