OneUptime 防火墙配置指南IP 白名单与 /ip-whitelist API 接口解析【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本文为 OneUptime 的官方文档App/FeatureSet/Docs/Content/de/configuration/ip-addresses.md该文档同时存在英文版本 ip-addresses.md的完整技术解读当您部署防火墙或安全组策略、又需要放行 OneUptime 探测节点Probe对您资源的出站访问时本篇将说明需要白名单化哪些 IP、如何从文档页面获取该列表以及如何通过/ip-whitelist公共 API 端点以编程方式持续拉取最新的出站 IP 列表从而把防火墙白名单的维护变成一条自动化流水线。为什么需要给 OneUptime 配置出站 IP 白名单OneUptime 是一款开源的监控与可观测性平台其探测能力由分布在多地的 Probe 节点执行HTTP/HTTPS 探测、Ping、TCP、DNS、端口检查等都会从 Probe 的出口 IP 发出然后访问您配置的被监控目标。如果您所在网络使用严格的入站策略例如仅允许已知来源访问业务系统、数据库端口、管理接口OneUptime 的探测流量就会被拦截导致监控结果全部为失败甚至触发误报告警。官方文档给出的做法是请在您的防火墙中白名单化下列 IP 地址使 oneuptime.com 的 Probe 能够到达您的资源。这些 IP 可能会发生变化如有变更我们会提前通知。也就是说白名单化 Probe 的出口egressIP是让 OneUptime 主动探测类监控正常工作的前提。获取当前 Probe 出口 IP 列表文档页面中的 IP 列表并不是写死在 Markdown 文件里的。观察源文档可以发现IP 列表位置只是一个占位符{{IP_WHITELIST}}这个占位符由服务端在渲染文档时动态替换。替换逻辑位于 DocsPlaceholders 中import { IpWhitelist } from Common/Server/EnvironmentConfig; export const IP_WHITELIST_PLACEHOLDER: string {{IP_WHITELIST}}; function getIpWhitelistMarkdown(): string { if (!IpWhitelist) { return - No IP addresses configured.; } const lines: Arraystring IpWhitelist.split(,) .map((ip: string) { return - ${ip.trim()}; }) .filter((line: string) { // 仅有 - 前缀说明该段是空条目例如尾随逗号需要过滤掉 return line.length 2; }); if (lines.length 0) { return - No IP addresses configured.; } return lines.join(\n); }渲染流程的关键事实均可从源码确认数据源是环境变量IP_WHITELIST在 EnvironmentConfig.ts 中定义为逗号分隔的字符串export const IpWhitelist: string process.env[IP_WHITELIST] || ;占位符替换是白名单式的只处理{{IP_WHITELIST}}和权限表等少数已知 token而不会做无差别的{{...}}全局替换——因为文档正文中还有其他双花括号内容例如网站监控页面文档中的{{timestamp}}插值、工作流文档中的{{variable}}语法这些必须原样保留。替换发生在所有文档输出通路上HTML 页面、原始 Markdown 端点以及llms-full.txt。源码注释特别提到如果只在 HTML 页面上替换直接请求原始 Markdown 文件的人会看到字面量的{{IP_WHITELIST}}——这正是该模块存在的背景。替换采用split(token).join(value)实现的replaceAll确保同一页面上出现多次的占位符全部被替换原生String.replace传入字符串参数只会替换第一次出现。如果实例没有配置IP_WHITELIST页面会显示- No IP addresses configured.而不会留下未替换的占位符。因此对于托管的 oneuptime.com您直接打开该文档页面即可看到当前生效的 IP 列表对于自建实例文档页面显示的 IP 取决于该实例自身的IP_WHITELIST配置。编程式获取GET /ip-whitelist 端点文档提供的第二个、也是更可靠的获取方式是公共 API 端点它无需登录即可调用GET https://oneuptime.com/ip-whitelist返回 JSON 结构如下{ ipWhitelist: [list of IPs] }该端点的完整实现在 IPWhitelistAPI.ts 中全文很短值得完整阅读router.get(/ip-whitelist, (req: ExpressRequest, res: ExpressResponse) { const ipList: Arraystring IpWhitelist ? IpWhitelist.split(,) .map((ip: string) { return ip.trim(); }) .filter((ip: string) { return ip.length 0; }) : []; Response.sendJsonObjectResponse(req, res, { ipWhitelist: ipList, }); });从源码可以确认以下行为细节请求IP_WHITELIST环境变量按逗号切分后逐项trim并过滤空段若未配置IP_WHITELIST返回ipWhitelist: []空数组而不是报错路由挂载在应用主路由下端点路径即文档中给出的/ip-whitelist。用 curl 拉取并解析 IP 列表结合上述 JSON 结构一个典型的校验脚本如下curl -s https://oneuptime.com/ip-whitelist \ | python3 -c import sys, json; [print(ip) for ip in json.load(sys.stdin)[ipWhitelist]]如果您使用的是自建 OneUptime 实例只需把域名替换为实例地址。把白名单维护做成自动化文档最后一句点明了这个端点的设计意图您可以使用这个端点来自动保持防火墙白名单的更新。典型做法是定时任务拉取/ip-whitelist与本地记录的 IP 列表做 diff出现新增或移除时通过云厂商 CLI、Ansible 或 Terraform 更新防火墙规则。由于列表本身可能随基础设施迁移而变化文档明确说明“这些 IP 可能会变化”以 API 为单一事实来源、而不是把 IP 硬编码在文档或脚本里是保持监控可用性的关键。自托管前提与注意事项该端点和文档占位符都依赖实例启动时的IP_WHITELIST环境变量见 EnvironmentConfig.ts。自建部署时请根据您的探测节点实际出口 IP 配置该变量否则文档会显示“No IP addresses configured”、API 返回空数组。白名单的是Probe 的出口 IPOneUptime 主动探测您的资源方向。与之容易混淆的是状态页 / Dashboard 模型上同名的ipWhitelist字段——例如 StatusPage.ts 和 Dashboard.ts 中定义的可选字段由 StatusPageService.ts 按行切分后用于限制访问状态页/Dashboard 的来源 IP。方向恰好相反入站访问控制且格式为每行一个 IP。两者同名但用途不同配置防火墙时不要混用。该端点不要求鉴权仅返回 IP 列表这一低敏感度信息可以安全地暴露给自动化系统。小结OneUptime 的 IP 白名单机制由三部分组成且每一部分都能在仓库中找到对应实现静态文档App/FeatureSet/Docs/Content/de/configuration/ip-addresses.md德文与App/FeatureSet/Docs/Content/en/configuration/ip-addresses.md英文使用{{IP_WHITELIST}}占位符由 Placeholders.ts 在渲染时替换为当前实例的 IP 列表API 端点GET /ip-whitelist实现在 IPWhitelistAPI.ts返回{ipWhitelist: [...]}JSON配置源实例级环境变量IP_WHITELIST逗号分隔定义于 EnvironmentConfig.ts。掌握这套机制后您可以为防火墙准确放行 OneUptime 探测流量并用 API 端点把白名单同步纳入自动运维流程避免因 IP 漂移造成的监控盲区。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/17 21:09:03 · 阅读 1.2k OneUptime 防火墙配置指南：IP 白名单与 /ip-whitelist API 接口解析
OneUptime 防火墙配置指南IP 白名单与 /ip-whitelist API 接口解析【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本文为 OneUptime 的官方文档App/FeatureSet/Docs/Content/de/configuration/ip-addresses.md该文档同时存在英文版本 ip-addresses.md的完整技术解读当您部署防火墙或安全组策略、又需要放行 OneUptime 探测节点Probe对您资源的出站访问时本篇将说明需要白名单化哪些 IP、如何从文档页面获取该列表以及如何通过/ip-whitelist公共 API 端点以编程方式持续拉取最新的出站 IP 列表从而把防火墙白名单的维护变成一条自动化流水线。为什么需要给 OneUptime 配置出站 IP 白名单OneUptime 是一款开源的监控与可观测性平台其探测能力由分布在多地的 Probe 节点执行HTTP/HTTPS 探测、Ping、TCP、DNS、端口检查等都会从 Probe 的出口 IP 发出然后访问您配置的被监控目标。如果您所在网络使用严格的入站策略例如仅允许已知来源访问业务系统、数据库端口、管理接口OneUptime 的探测流量就会被拦截导致监控结果全部为失败甚至触发误报告警。官方文档给出的做法是请在您的防火墙中白名单化下列 IP 地址使 oneuptime.com 的 Probe 能够到达您的资源。这些 IP 可能会发生变化如有变更我们会提前通知。也就是说白名单化 Probe 的出口egressIP是让 OneUptime 主动探测类监控正常工作的前提。获取当前 Probe 出口 IP 列表文档页面中的 IP 列表并不是写死在 Markdown 文件里的。观察源文档可以发现IP 列表位置只是一个占位符{{IP_WHITELIST}}这个占位符由服务端在渲染文档时动态替换。替换逻辑位于 DocsPlaceholders 中import { IpWhitelist } from Common/Server/EnvironmentConfig; export const IP_WHITELIST_PLACEHOLDER: string {{IP_WHITELIST}}; function getIpWhitelistMarkdown(): string { if (!IpWhitelist) { return - No IP addresses configured.; } const lines: Arraystring IpWhitelist.split(,) .map((ip: string) { return - ${ip.trim()}; }) .filter((line: string) { // 仅有 - 前缀说明该段是空条目例如尾随逗号需要过滤掉 return line.length 2; }); if (lines.length 0) { return - No IP addresses configured.; } return lines.join(\n); }渲染流程的关键事实均可从源码确认数据源是环境变量IP_WHITELIST在 EnvironmentConfig.ts 中定义为逗号分隔的字符串export const IpWhitelist: string process.env[IP_WHITELIST] || ;占位符替换是白名单式的只处理{{IP_WHITELIST}}和权限表等少数已知 token而不会做无差别的{{...}}全局替换——因为文档正文中还有其他双花括号内容例如网站监控页面文档中的{{timestamp}}插值、工作流文档中的{{variable}}语法这些必须原样保留。替换发生在所有文档输出通路上HTML 页面、原始 Markdown 端点以及llms-full.txt。源码注释特别提到如果只在 HTML 页面上替换直接请求原始 Markdown 文件的人会看到字面量的{{IP_WHITELIST}}——这正是该模块存在的背景。替换采用split(token).join(value)实现的replaceAll确保同一页面上出现多次的占位符全部被替换原生String.replace传入字符串参数只会替换第一次出现。如果实例没有配置IP_WHITELIST页面会显示- No IP addresses configured.而不会留下未替换的占位符。因此对于托管的 oneuptime.com您直接打开该文档页面即可看到当前生效的 IP 列表对于自建实例文档页面显示的 IP 取决于该实例自身的IP_WHITELIST配置。编程式获取GET /ip-whitelist 端点文档提供的第二个、也是更可靠的获取方式是公共 API 端点它无需登录即可调用GET https://oneuptime.com/ip-whitelist返回 JSON 结构如下{ ipWhitelist: [list of IPs] }该端点的完整实现在 IPWhitelistAPI.ts 中全文很短值得完整阅读router.get(/ip-whitelist, (req: ExpressRequest, res: ExpressResponse) { const ipList: Arraystring IpWhitelist ? IpWhitelist.split(,) .map((ip: string) { return ip.trim(); }) .filter((ip: string) { return ip.length 0; }) : []; Response.sendJsonObjectResponse(req, res, { ipWhitelist: ipList, }); });从源码可以确认以下行为细节请求IP_WHITELIST环境变量按逗号切分后逐项trim并过滤空段若未配置IP_WHITELIST返回ipWhitelist: []空数组而不是报错路由挂载在应用主路由下端点路径即文档中给出的/ip-whitelist。用 curl 拉取并解析 IP 列表结合上述 JSON 结构一个典型的校验脚本如下curl -s https://oneuptime.com/ip-whitelist \ | python3 -c import sys, json; [print(ip) for ip in json.load(sys.stdin)[ipWhitelist]]如果您使用的是自建 OneUptime 实例只需把域名替换为实例地址。把白名单维护做成自动化文档最后一句点明了这个端点的设计意图您可以使用这个端点来自动保持防火墙白名单的更新。典型做法是定时任务拉取/ip-whitelist与本地记录的 IP 列表做 diff出现新增或移除时通过云厂商 CLI、Ansible 或 Terraform 更新防火墙规则。由于列表本身可能随基础设施迁移而变化文档明确说明“这些 IP 可能会变化”以 API 为单一事实来源、而不是把 IP 硬编码在文档或脚本里是保持监控可用性的关键。自托管前提与注意事项该端点和文档占位符都依赖实例启动时的IP_WHITELIST环境变量见 EnvironmentConfig.ts。自建部署时请根据您的探测节点实际出口 IP 配置该变量否则文档会显示“No IP addresses configured”、API 返回空数组。白名单的是Probe 的出口 IPOneUptime 主动探测您的资源方向。与之容易混淆的是状态页 / Dashboard 模型上同名的ipWhitelist字段——例如 StatusPage.ts 和 Dashboard.ts 中定义的可选字段由 StatusPageService.ts 按行切分后用于限制访问状态页/Dashboard 的来源 IP。方向恰好相反入站访问控制且格式为每行一个 IP。两者同名但用途不同配置防火墙时不要混用。该端点不要求鉴权仅返回 IP 列表这一低敏感度信息可以安全地暴露给自动化系统。小结OneUptime 的 IP 白名单机制由三部分组成且每一部分都能在仓库中找到对应实现静态文档App/FeatureSet/Docs/Content/de/configuration/ip-addresses.md德文与App/FeatureSet/Docs/Content/en/configuration/ip-addresses.md英文使用{{IP_WHITELIST}}占位符由 Placeholders.ts 在渲染时替换为当前实例的 IP 列表API 端点GET /ip-whitelist实现在 IPWhitelistAPI.ts返回{ipWhitelist: [...]}JSON配置源实例级环境变量IP_WHITELIST逗号分隔定义于 EnvironmentConfig.ts。掌握这套机制后您可以为防火墙准确放行 OneUptime 探测流量并用 API 端点把白名单同步纳入自动运维流程避免因 IP 漂移造成的监控盲区。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考