OneUptime 探针出口 IP 白名单指南：手动配置、API 获取与防火墙自动同步-酒店常州论坛

OneUptime 探针出口 IP 白名单指南：手动配置、API 获取与防火墙自动同步

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

OneUptime 的监控探针（Probe）在检测网站、API、端口等资源时，需要从探针所在网络主动发起出站请求。若你的资源部署在防火墙或安全组之后，就需要把 OneUptime 探针的出口 IP 加入白名单，否则监控请求会被拦截。本文以官方文档 IP Address Whitelist for OneUptime.com（及西班牙语版本、简体中文版本）为核心，结合仓库源码讲解白名单 IP 的两种获取方式——手动配置与程序化获取——并给出基于 API 端点自动同步防火墙白名单的实战方案。

为什么需要配置探针出口 IP 白名单

OneUptime 的监控体系依赖分布在不同网络位置的探针（Probe）对目标资源发起真实探测请求。当你的资源设置了入站访问控制（云厂商安全组、本地防火墙、企业网关 ACL 等）时，探针发起的健康检查、网站监控、API 监控请求同样会被访问控制策略过滤。为了在保持资源安全的同时让监控正常工作，官方推荐的做法是：将 OneUptime 探针的出站 IP 加入你的防火墙白名单，使 oneuptime.com 能够按预期触达你的资源。

官方文档明确指出这些 IP 由服务方维护，且并非永久固定：

Estas IPs pueden cambiar; te avisaremos con antelación si esto ocurre. （这些 IP 可能发生变化；如有变化我们会提前通知。）

因此，白名单的维护应当视为一项持续性的运维任务，而非一次性配置——这也是官方提供程序化获取端点的根本原因。

方式一：手动将探针 IP 加入防火墙白名单

对于只有少量 IP、且变更不频繁的场景，可以直接在防火墙或安全组中手动添加 IP。官方文档给出的操作步骤非常直接：

打开你的防火墙或安全组的入站（或对应放行）规则配置界面；
从 OneUptime 官方文档页面获取当前探针出口 IP 列表；
将列表中的每一条 IP 加入白名单，确保 oneuptime.com 可以触达你的资源。

需要注意的是，文档正文中的{{IP_WHITELIST}}是一个渲染期占位符，并非字面内容。文档服务在返回页面之前，会通过 Docs 占位符渲染模块将其替换为真实的 IP 列表。其替换逻辑如下（见 Placeholders.ts）：

从环境变量IP_WHITELIST读取逗号分隔的 IP 字符串；
逐项trim去除首尾空白，并过滤掉空条目；
将每条 IP 渲染为一条 Markdown 无序列表项- <ip>；
若环境变量未配置（默认安装场景），则渲染为- No IP addresses configured.（未配置任何 IP）。

这一行为由 Placeholders.test.ts 中的测试用例锁定：当IP_WHITELIST未设置时，占位符必须被替换为以-开头的提示文本；当配置了 IP 时，渲染结果每一行都必须以-开头。这意味着你在文档页面上看到的，总是当前该实例实际生效的 IP 列表，而不是写死在 Markdown 源文件中的过期数据。

方式二：通过 API 程序化获取 IP 列表

手动维护的痛点是：IP 一旦变更，你需要再次登录防火墙控制台逐一更新。为此，OneUptime 提供了一个公开的只读 API 端点，供用户程序化拉取探针出口 IP 列表：

GET https://oneuptime.com/ip-whitelist

该端点返回一个 JSON 响应：

{ "ipWhitelist": ["<list of IPs>"] }

响应的顶层对象包含一个ipWhitelist数组字段，数组中的每一项即是一条需要放行的 IP 地址。

端点背后的源码实现

这个端点并不神秘，其完整实现位于 IPWhitelistAPI.ts。核心逻辑如下：

路由注册：router.get("/ip-whitelist", ...)挂载GET /ip-whitelist；
从环境配置读取原始 IP 字符串（见 EnvironmentConfig.ts）：
```
export const IpWhitelist: string = process.env["IP_WHITELIST"] || "";
```
对原始字符串做标准化处理：按,分割 → 逐项trim→ 过滤空串，得到干净的 IP 数组；
通过Response.sendJsonObjectResponse返回{ ipWhitelist: [...] }结构。

该路由通过 API/Index.ts 注册到 Express 应用根路径与各服务路径下，与自托管部署同样兼容。也就是说，自托管 OneUptime 的用户可以在自己的实例上配置IP_WHITELIST环境变量后，通过相同路径的端点获取本实例声明的探针出口 IP——这同时驱动了文档页面的占位符渲染与 API 响应，保证两者数据源一致。

用 curl 快速验证

你可以直接用curl验证端点可用性与响应格式：

curl -s https://oneuptime.com/ip-whitelist

如果安装了jq，可以只提取 IP 列表：

curl -s https://oneuptime.com/ip-whitelist | jq -r '.ipWhitelist[]'

实战：自动同步防火墙白名单

官方文档特别说明，该端点正是为"自动保持防火墙白名单更新"而设计的。下面给出一个基于该端点的自动同步思路，你可以按自己的防火墙产品（安全组 API、ufw、iptables、企业防火墙 SDK 等）替换实现细节。

1. 拉取当前 IP 列表并写入本地文件

#!/usr/bin/env bash # sync-oneuptime-ips.sh # 拉取 OneUptime 探针出口 IP 列表并保存，供防火墙规则生成使用。 set -euo pipefail OUT_FILE="/etc/oneuptime/ip-whitelist.json" TMP_FILE="${OUT_FILE}.tmp" curl -fsS --retry 3 https://oneuptime.com/ip-whitelist -o "${TMP_FILE}" mv "${TMP_FILE}" "${OUT_FILE}" echo "IP whitelist saved to ${OUT_FILE}" jq -r '.ipWhitelist[]' "${OUT_FILE}"

2. 将 IP 列表应用到防火墙

以ufw为例（生产环境建议按自身安全组 API 适配）：

#!/usr/bin/env bash # 从 JSON 文件中逐条放行 IP；注意先清理旧的 OneUptime 规则，避免重复添加。 for ip in $(jq -r '.ipWhitelist[]' /etc/oneuptime/ip-whitelist.json); do ufw allow from "${ip}" comment "OneUptime probe egress" done

3. 用 cron 定期同步

由于官方已声明 IP 可能变化，建议把同步脚本加入定时任务，例如每天执行一次：

0 3 * * * /usr/local/bin/sync-oneuptime-ips.sh && /usr/local/bin/apply-oneuptime-ufw.sh

说明：以上脚本是围绕端点返回的{ "ipWhitelist": [...] }结构编写的通用示例，仅演示"拉取 → 解析 → 应用"的完整闭环，具体防火墙命令请以你所在环境的实际产品为准。

注意事项与最佳实践

围绕本文主题，有几点值得在实施时特别注意：

IP 列表会变化：官方明确表示 IP 可能调整并会提前通知。建议保持监控告警，收到变更通知后及时重新执行同步。
文档与 API 数据同源：无论是文档页面的{{IP_WHITELIST}}占位符替换，还是/ip-whitelist端点响应，都来自同一个IP_WHITELIST环境变量（见 EnvironmentConfig.ts），因此以 API 返回值为准即可，无需人工比对文档。
未配置时的行为：对于默认安装且未设置IP_WHITELIST的实例，API 返回{ "ipWhitelist": [] }（空数组），文档页面则显示"未配置任何 IP"。自动化脚本应对空列表做幂等处理，避免误清空防火墙规则。
自动化优于手动：IP 数量少时手动配置尚可接受，一旦涉及多区域探针或频繁变更，强烈建议按上文思路接入 API 做自动化同步，保持安全组与官方列表始终一致。

关键文件索引

如果你希望深入理解本文涉及的实现细节，可进一步阅读以下仓库文件：

IPWhitelistAPI.ts：GET /ip-whitelist端点的完整实现；
EnvironmentConfig.ts：IP_WHITELIST环境变量的定义；
API/Index.ts：端点路由的注册位置；
Placeholders.ts：文档中{{IP_WHITELIST}}占位符的服务端替换逻辑；
Placeholders.test.ts：覆盖占位符替换与未配置场景的测试用例；
英文版文档与西班牙语版文档：本文所依据的官方说明原文。

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析