OneUptime Custom Probe Incoming Request Ingress：让无外网访问的服务也能上报 Heartbeat 与告警

OneUptime Custom Probe Incoming Request Ingress：让无外网访问的服务也能上报 Heartbeat 与告警

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

Incoming Request Ingress 是 OneUptime 自定义探针（Custom Probe）的可选入站监听器：当探针运行在无外网出口的隔离网络中时，它可以在本机绑定一个 HTTP 端口，接收内网服务的heartbeat与incoming-request调用，并代其转发到 OneUptime 实例。读完本文，你将掌握 ingress 的启用方式（Docker / Docker Compose / Kubernetes）、四种请求路径、转发语义与重试退避机制、全部环境变量，以及它的安全边界与故障排查手段。

Overview：Ingress 是什么

默认情况下，Incoming Request Monitor 的探测 URL 指向公网（或自托管）的 OneUptime 地址，例如https://oneuptime.com/heartbeat/<secret-key>。但如果服务位于没有出站互联网访问的私有网络中，它根本无法把请求发到公网。

Ingress 正是为此设计：当探针配置了PROBE_INGRESS_PORT时，它会在该端口上额外绑定一个 HTTP 监听器，接受与公网 OneUptime 端点相同格式的secretkeyURL 路径：

• POST /heartbeat/:secretkey
• GET /heartbeat/:secretkey
• POST /incoming-request/:secretkey
• GET /incoming-request/:secretkey

监听器收到请求后，将请求代理（proxy）到你的 OneUptime 实例，保留方法、请求体与请求头（除Host、Connection、Content-Length等 hop-by-hop 头之外）。探针会自动附加一个OneUptime-Probe-Id请求头，让 OneUptime 知道这条心跳是由哪个探针转发的。

从源码结构看，这个监听器与探针自身的状态/指标端点运行在完全独立的端口上：探针主 HTTP 服务使用PORT（默认3874）承载状态与/metrics指标路由，而 ingress 监听器使用PROBE_INGRESS_PORT单独绑定。这样你只需要把 ingress 端口暴露给私有网络，探针内部端点不会一并泄漏。启动逻辑位于 Probe/Index.ts，核心转发实现位于 Probe/API/IncomingRequestIngress.ts。

何时使用 Ingress

以下场景适合启用 ingress 监听器：

• 服务运行在隔离网段中，没有出站 HTTPS 访问能力；
• 你希望所有监控流量都留在 VPC / 本地网络内部；
• 你希望只有一个出口点——即探针本身——被允许访问 OneUptime；
• 你已经部署了 Custom Probe，希望复用它对内网心跳做入站接收。

如果你的服务本来就能直接访问https://oneuptime.com（或自托管 URL），则不需要该功能——直接从服务调用 heartbeat URL 即可。

启用 Ingress 监听器

设置PROBE_INGRESS_PORT为监听器要绑定的端口即可。任何大于0的值都会启用监听器；不设置（或设为0）则禁用。在 Probe/Config.ts 中可以看到它的解析逻辑：环境变量存在时包装为Port对象并通过NumberUtil.parseNumberWithDefault解析（默认0、最小值0），不存在时为null；随后 Probe/Index.ts 只有在「非 null 且端口大于 0」时才创建并启动独立的 Express 应用。

Docker

使用--network host时，容器直接共享宿主机网络，无需额外映射端口：

docker run --name oneuptime-probe --network host \ -e PROBE_KEY=<probe-key> \ -e PROBE_ID=<probe-id> \ -e ONEUPTIME_URL=https://oneuptime.com \ -e PROBE_INGRESS_PORT=3875 \ -d oneuptime/probe:release

如果未使用--network host，需要显式发布 ingress 端口：

docker run --name oneuptime-probe \ -e PROBE_KEY=<probe-key> \ -e PROBE_ID=<probe-id> \ -e ONEUPTIME_URL=https://oneuptime.com \ -e PROBE_INGRESS_PORT=3875 \ -p 3875:3875 \ -d oneuptime/probe:release

关于PROBE_KEY/PROBE_ID的获取方式：在 OneUptime Dashboard 的Monitors > Settings > Probes中创建自定义探针后即可获得，详见 Custom Probes。

Docker Compose

version: "3" services: oneuptime-probe: image: oneuptime/probe:release container_name: oneuptime-probe environment: - PROBE_KEY=<probe-key> - PROBE_ID=<probe-id> - ONEUPTIME_URL=https://oneuptime.com - PROBE_INGRESS_PORT=3875 ports: - "3875:3875" restart: always

Kubernetes

apiVersion: apps/v1 kind: Deployment metadata: name: oneuptime-probe spec: selector: matchLabels: app: oneuptime-probe template: metadata: labels: app: oneuptime-probe spec: containers: - name: oneuptime-probe image: oneuptime/probe:release env: - name: PROBE_KEY value: "<probe-key>" - name: PROBE_ID value: "<probe-id>" - name: ONEUPTIME_URL value: "https://oneuptime.com" - name: PROBE_INGRESS_PORT value: "3875" ports: - name: ingress containerPort: 3875 --- apiVersion: v1 kind: Service metadata: name: oneuptime-probe-ingress spec: selector: app: oneuptime-probe ports: - name: ingress port: 3875 targetPort: 3875 type: ClusterIP

部署后，内网服务即可向http://oneuptime-probe-ingress.<namespace>.svc.cluster.local:3875/heartbeat/<secret-key>发送心跳。注意这里刻意使用了ClusterIP类型的 Service——它只在集群内部可达，是符合下文安全建议的默认做法。

向探针发送请求

只需把公网 heartbeat URL：

https://oneuptime.com/heartbeat/<secret-key>

替换为探针的 ingress URL：

http://<probe-host>:<PROBE_INGRESS_PORT>/heartbeat/<secret-key>

路径、方法、请求体与请求头完全一致，因此任何已有的客户端代码只需要改 base URL，其余逻辑零改动。

示例

# GET heartbeat curl http://probe.internal:3875/heartbeat/YOUR_SECRET_KEY # POST heartbeat with JSON body curl -X POST http://probe.internal:3875/heartbeat/YOUR_SECRET_KEY \ -H "Content-Type: application/json" \ -d '{"status": "healthy", "version": "1.2.3"}' # Cron job */5 * * * * curl -s http://probe.internal:3875/heartbeat/YOUR_SECRET_KEY > /dev/null

转发行为（Forwarding Behavior）

Ingress 的转发语义是本文最核心的部分，以下行为均由 Probe/API/IncomingRequestIngress.ts 的实现与 Probe/Tests/API/IncomingRequestIngress.test.ts 的测试用例共同保证：

• 同步响应、异步转发：探针立即以200应答入站请求，然后在后台把请求转发到 OneUptime。你的服务无需等待转发完成。测试中专门验证了「转发永远不返回时，客户端仍能立刻拿到200」，以及「控制面拒绝转发时，应答依然是200」——转发结果永远不会改变对客户端的应答。
• 请求头保留：除 hop-by-hop 头（Host、Connection、Content-Length、Transfer-Encoding、Keep-Alive、Proxy-Authenticate、Proxy-Authorization、TE、Trailer、Upgrade）之外的所有头都会透传。代码中以HOP_BY_HOP_HEADERS集合（大小写不敏感）逐一过滤，测试还覆盖了「无论客户端如何大小写都会剥离」「重复头合并为逗号分隔的单个值（如a, b）」「空值头被丢弃」等边界情形。探针自身会附加OneUptime-Probe-Id头用于标识转发者。
• 请求体保留：接受 JSON、URL-encoded 以及原始application/octet-stream负载，上限50 MB。对于纯文本 / 原始负载，代码会将其包装在_raw键下转发（例如{ _raw: "backup finished" }），这样 incoming-request 的过滤条件仍能寻址到这段文本；无请求体时转发为空对象{}。
• 带退避的重试：转发失败时，探针最多重试PROBE_INGRESS_FORWARD_RETRY_LIMIT次，采用指数退避（2s、4s、8s……封顶 15s）。实现中退避公式为Math.min(2000 * 2 ** (attempt - 1), 15000)，测试用 mock 断言了实际延迟序列为[2000, 4000]且均不超过15000ms，并验证了「连续失败最终放弃而不是无限循环」「某次成功后立即停止重试」「控制面返回 5xx 也算失败值得重试」等行为。
• 代理感知：如果探针自身配置了HTTP_PROXY_URL/HTTPS_PROXY_URL，转发请求会走代理。这两个变量还支持小写变体（http_proxy等），并可用NO_PROXY指定需要绕过代理的主机列表，解析逻辑见 Probe/Config.ts。

值得注意的一个实现细节：无论是heartbeat还是incoming-request路径，探针都会把请求转发到 OneUptime 的/incoming-request/:secretkey路由——因为服务端把 heartbeat 视为 incoming-request 的一种，测试专门固定了这一行为，防止将来被「好心」改成服务端并不存在的/heartbeat路由。

环境变量

变量	默认值	说明
PROBE_INGRESS_PORT	未设置（禁用）	入站监听器绑定的端口。任何> 0的值都会启用 ingress。
PROBE_INGRESS_FORWARD_TIMEOUT_MS	10000	每次向 OneUptime 转发尝试的超时时间（毫秒）。最小值1000。
PROBE_INGRESS_FORWARD_RETRY_LIMIT	3	放弃转发前的重试次数。设为0可禁用重试。

这三个变量的解析位于 Probe/Config.ts，均通过parseNumberWithDefault校验上下限（timeout 最小值 1000ms、retry 最小值 0）。

探针的标准变量（PROBE_KEY、PROBE_ID、ONEUPTIME_URL、代理变量等）同样适用，完整列表见 Custom Probes。其中ONEUPTIME_URL同时决定了转发目标：转发 URL 由ONEUPTIME_BASE_URL拼接/incoming-request/<secret-key>得到（见 IncomingRequestIngress.ts）。

安全注意事项

• 端点本身不鉴权——这是设计使然：URL 路径中的 secret key 就是认证凭据，与公网oneuptime.com端点一致。请把 secret key 当作机密对待。
• 只绑定私有接口：ingress 监听器不应被公网访问。请使用网络策略、防火墙规则或ClusterIPService 限制访问范围。
• 如需传输加密，请做 HTTPS 终结：探针监听器说的是明文 HTTP。如果你要求入站一跳启用 TLS，应把它放在内网负载均衡器 / ingress controller 后面。探针 → OneUptime 的转发一跳始终使用 HTTPS（前提是ONEUPTIME_URL为https://）。
• 资源限制：监听器接受最大 50 MB 的请求体。如果需要更紧的上限，请在前面放置反向代理。

故障排查

• 探针启动日志中出现Probe ingress listener started on port <port>即表示监听器已就绪。若看不到这行日志，说明PROBE_INGRESS_PORT未设置、为0或无效。
• Probe ingress: failed to forward to <url> after N attempts：探针无法到达 OneUptime。请检查探针的出站连通性、代理设置以及ONEUPTIME_URL的值。
• Probe ingress: probe ID not available, forwarding without it：探针尚未注册完成。转发仍会成功，只是该心跳不会归属到某个探针名下（测试同样覆盖了这一场景，确保「探针暂时无法自报身份时不丢弃请求、不丢心跳」）。
• Heartbeat 在 OneUptime 中出现，但并非经由探针：确认你的服务访问的是http://<probe-host>:<port>/...而非公网 URL。DNS 配置错误或/etc/hosts条目是最常见的原因。

相关文档

• Custom Probes —— 自定义探针的部署方式与全部环境变量
• Incoming Request Monitor —— 入站请求监控器的 URL 格式、监控条件与告警接收方式

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