OneUptime IP 地址白名单配置实战探针出口 IP 放行与 /ip-whitelist 程序化同步【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeOneUptime 是一款开源的监控与可观测性平台。当使用其托管服务 oneuptime.com或自托管部署时探针Probe会从平台侧发起的出口请求去访问你的网站、API、数据库等受监控资源。若你的防火墙/安全组对这些入站流量有严格管控就需要把 OneUptime 探针的出口 IP 加入白名单否则监控会因网络不可达而失败。本文以仓库中的官方配置文档App/FeatureSet/Docs/Content/en/configuration/ip-addresses.md及对应的波斯语版本为核心骨架结合仓库源码与测试讲清楚「放行哪些 IP、如何手工配置、如何通过/ip-whitelistAPI 程序化同步」并深入解析这条白名单链路在代码中的完整实现。一、适用场景为什么需要放行 OneUptime 探针出口 IP托管版的 oneuptime.com 探针在完成以下监控任务时需要从平台侧主动连接你的资源HTTP/HTTPS 网站与 API 的可用性、响应时间探测TCP/UDP 端口连通性检查Ping/ICMP 等网络层探测其他需要从探针侧发起的主动式监控。如果你的资源部署在云厂商安全组、自建防火墙或 IDC 访问控制列表ACL之后且策略是「默认拒绝、显式放行」那么 OneUptime 探针的出口 IP 就必须出现在白名单中否则探测请求会被拦截监控会持续报错或误报。官方文档的核心指引很明确在你的防火墙中把下列 OneUptime 出口 IP 加入白名单以允许 oneuptime.com 访问你的资源。同时文档强调这些 IP 地址可能变化若有变更官方会提前通知——这正是「程序化获取 IP 列表」这一能力存在的前提。二、如何获取当前需要放行的 IP 列表2.1 手动方式文档中的占位符仓库内的文档页面并不硬编码 IP 列表而是使用一个占位符{{IP_WHITELIST}}Please whitelist the following IPs in your firewall to allow oneuptime.com to reach your resources. {{IP_WHITELIST}}该占位符由服务端在渲染文档时动态替换为「当前实例配置的 IP 列表」。替换逻辑位于 App/FeatureSet/Docs/Utils/Placeholders.tsexport 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) { // - alone means the entry was blank (trailing comma, empty segment). return line.length 2; }); if (lines.length 0) { return - No IP addresses configured.; } return lines.join(\n); }关键行为IP 列表来自环境变量IP_WHITELIST以英文逗号分隔渲染时逐个trim后生成 Markdown 无序列表若环境变量未配置文档会呈现「No IP addresses configured.」空段如结尾逗号、连续逗号会被过滤掉不会输出空列表项。2.2 程序化方式/ip-whitelistAPI 端点对于需要自动化同步防火墙规则的场景官方文档提供了专用端点GET https://oneuptime.com/ip-whitelist该端点返回 JSON 响应{ ipWhitelist: [list of IPs] }ipWhitelist字段是一个字符串数组每一项就是一个探针出口 IP 或网段。你可以在防火墙同步脚本中定期调用该端点将返回列表与现有规则做差集增量更新实现白名单的自动保鲜避免因 IP 变更导致监控中断。三、端点底层实现从环境变量到 JSON 响应/ip-whitelist端点的实现位于 Common/Server/API/IPWhitelistAPI.tsimport Express, { ExpressRequest, ExpressResponse, ExpressRouter, } from ../Utils/Express; import Response from ../Utils/Response; import { IpWhitelist } from ../EnvironmentConfig; export default class IPWhitelistAPI { public static init(): ExpressRouter { const router: ExpressRouter Express.getRouter(); 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, }); }); return router; } }几个值得注意的实现细节数据来源与文档渲染保持一致端点与文档占位符读取同一个IpWhitelist环境配置只是输出形态不同——文档渲染成 Markdown 列表API 输出成 JSON 数组两者不会漂移。解析规则split(,)→ 逐项trim()→ 过滤空串。因此配置IP_WHITELIST1.2.3.4, 5.6.7.8, ,9.10.11.12会得到[1.2.3.4, 5.6.7.8, 9.10.11.12]多余空格与空段均被安全处理。未配置时返回空数组IpWhitelist为空时返回{ipWhitelist: []}调用方应按「无放行条目」处理。3.1 环境变量的定义IpWhitelist的定义在 Common/Server/EnvironmentConfig.ts 第 892 行export const IpWhitelist: string process.env[IP_WHITELIST] || ;即该配置来自环境变量IP_WHITELIST逗号分隔多个 IP 或 CIDR 网段未设置时默认为空字符串。自托管部署时可通过该环境变量为你的实例配置探针出口白名单列表。3.2 端点的挂载位置该路由通过 Common/Server/API/Index.ts 统一挂载到应用根路径与 appName 前缀路径下app.use([/${data.appName}, /], IPWhitelistAPI.init());从源码结构看无论是托管版的https://oneuptime.com/ip-whitelist还是自托管实例的https://your-domain/ip-whitelist以及带appName前缀的路径均会命中同一路由。这也解释了为何文档中直接给出根路径的 URL 即可访问。四、白名单判定的客户端契约IP.isInWhitelist拿到 IP 列表只是第一步探针侧真正做「是否放行」判断的是 IP 匹配工具函数。该函数的契约在 Common/Tests/Types/IP/IPWhitelist.test.ts 中被完整定义测试覆盖了以下行为这些约定也适用于你在自己防火墙脚本中解析列表时的预期精确匹配IPv4 单地址精确匹配10.0.0.1命中[10.0.0.1]10.0.0.2不命中IPv6 单地址精确匹配2001:db8::1命中[2001:db8::1]列表条目顺序无关条目前后空白、结尾\r会被容忍对应环境变量以逗号分隔、textarea 换行分隔等来源场景。CIDR 网段命中范围内地址10.4.5.6命中[10.0.0.0/8]192.168.1.55命中[192.168.1.0/24]范围边界被正确判定192.168.1.0与192.168.1.255命中192.168.1.0/24192.168.0.255与192.168.2.0不命中/32视为精确匹配IPv6 地址不会误命中 IPv4 网段如2001:db8::1不命中0.0.0.0/1畸形 CIDR10.0.0.0/、10.0.0.0/33、10.0.0.0/abc、not-an-ip/8会被跳过而不产生匹配且不会中断对后续条目的检查。空列表与非法输入fail-closed 语义白名单为空或仅含空白条目时一律拒绝返回false传入的地址本身非法如unknown、10.0.0、10.0.0.256时抛出BadDataException调用方将异常视为拒绝特别的若白名单为空则先返回false不再校验地址合法性安全关键点该函数只接受单个地址作为待判对象不接受X-Forwarded-For链式多地址输入——历史上「任一成员命中即放行」的做法会让调用方伪造链头绕过校验因此被改为「精确校验传入的那个地址」。从测试注释看这一判定工具被用于服务端的访问控制fail-closed任何异常都按拒绝处理是白名单安全模型的核心。五、服务端访问控制中的 IP 白名单公共状态页与仪表盘除探针出口 IP 白名单外仓库中还存在另一类 IP 白名单按 IP 限制对公共状态页StatusPage与公共仪表盘Dashboard的访问。相关模型字段为Common/Models/DatabaseModels/StatusPage.ts 第 3367 行public ipWhitelist?: string undefined;Common/Models/DatabaseModels/Dashboard.ts 第 907 行public ipWhitelist?: string undefined;在服务端访问控制中见 Common/Server/Services/StatusPageService.ts 与 Common/Server/Services/DashboardService.ts该字段以换行分隔的形式存储多条目并在命中ipWhitelist时启用whitelist校验。这与探针出口 IP 列表的「逗号分隔」约定不同——前者面向 API/环境配置后者面向 UI 表单文本域输入两者读取后都会交由上文的 IP 匹配逻辑统一判定。六、自动同步白名单的实战方案官方文档建议「用该端点自动更新防火墙白名单」。以下是一个可直接落地的同步思路伪代码按你的防火墙厂商 API 适配# 1. 拉取当前白名单含 IPv4/IPv6 与 CIDR 网段 curl -s https://oneuptime.com/ip-whitelist # 2. 响应示例 # {ipWhitelist:[203.0.113.10,198.51.100.0/24]} # 3. 将数组解析后与现有防火墙规则做差集 # - 新增列表中有、规则中无的条目 → 添加放行规则 # - 规则中有、列表已移除的条目 → 按需删除建议保留观察窗口再清理实际落地时建议关注同步频率与幂等性用 cron/定时任务每小时或每天拉取一次规则更新需幂等重复添加同一 IP 不产生冲突协议与端口范围探针出口 IP 通常需要放行的不仅是 443还可能涉及你监控项所用端口如自定义 TCP 端口、数据库端口等白名单应针对「源 IP 目标端口」组合配置变更窗口由于 IP 会变化且官方会提前通知自动化同步脚本应记录最近一次成功同步的时间与内容便于变更回溯fail-closed 意识参考上文测试契约解析非法条目时应跳过而非中断避免单条坏数据导致整个同步脚本崩溃自托管实例若使用自托管部署则该端点的内容由你自身配置的IP_WHITELIST环境变量决定白名单的维护责任在己方。七、占位符渲染机制的工程意义为什么文档不直接写死 IP 列表而是采用{{IP_WHITELIST}}占位符 服务端替换App/FeatureSet/Docs/Utils/Placeholders.ts 的注释给出了设计原因内容随实例配置变化IP 白名单依赖当前实例的环境配置无法在静态文档中写死渲染链路全覆盖所有提供文档 markdown 的路径HTML 页面、raw markdown 端点、llms-full.txt都会先经过DocsPlaceholders.render()避免「只有 HTML 页面做了替换、raw markdown 端点却返回字面量{{IP_WHITELIST}}」的不一致允许列表式替换而非全局扫荡文档中合法的其他双花括号 token如网站监控页面的{{timestamp}}、工作流页面的{{variable}}语法必须原样保留因此替换只针对白名单允许的 token 列表逐次replaceAll全部替换而非仅第一处。这套机制保证了读者在文档页、raw markdown、LLM 抓取内容中看到的白名单永远与当前实例实际配置一致。八、相关参考文件速查文档原文英文App/FeatureSet/Docs/Content/en/configuration/ip-addresses.md文档原文波斯语App/FeatureSet/Docs/Content/fa/configuration/ip-addresses.md占位符渲染{{IP_WHITELIST}}由 App/FeatureSet/Docs/Utils/Placeholders.ts 在渲染时填充API 端点实现Common/Server/API/IPWhitelistAPI.ts端点挂载Common/Server/API/Index.ts环境变量定义Common/Server/EnvironmentConfig.tsIP_WHITELISTIP 匹配契约测试Common/Tests/Types/IP/IPWhitelist.test.ts访问控制中的 IP 白名单公共状态页/仪表盘的ipWhitelist字段分别定义于 Common/Models/DatabaseModels/StatusPage.ts 与 Common/Models/DatabaseModels/Dashboard.ts结语OneUptime 的 IP 白名单能力由「三层」协同构成文档层通过{{IP_WHITELIST}}占位符动态展示当前 IP 列表API 层通过GET /ip-whitelist以 JSON 形态提供同一份数据供程序化消费判定层由IP.isInWhitelist提供精确、CIDR、IPv6 全覆盖且 fail-closed 的匹配语义。对使用 oneuptime.com 托管服务的团队把/ip-whitelist纳入防火墙同步流水线是最稳妥的运维方式对自托管用户则可通过IP_WHITELIST环境变量自行定义出口白名单。理解这条链路既能保证监控探针稳定触达资源也能在 IP 变更时做到无感过渡。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考