From ba23cf6f574682bec32ffd3688d9f73de15ca406 Mon Sep 17 00:00:00 2001 From: wuyangfan <1102042793@qq.com> Date: Sun, 17 May 2026 19:23:00 +0800 Subject: [PATCH] docs: add reverse proxy guidance for Prometheus UI Document nginx headers for general proxying and SSE settings for /api/v1/notifications/live. Link from the security page. Fixes #2950 Co-authored-by: Cursor --- docs/operating/reverse_proxy.md | 64 +++++++++++++++++++++++++++++++++ docs/operating/security.md | 4 ++- 2 files changed, 67 insertions(+), 1 deletion(-) create mode 100644 docs/operating/reverse_proxy.md diff --git a/docs/operating/reverse_proxy.md b/docs/operating/reverse_proxy.md new file mode 100644 index 000000000..7591ef76d --- /dev/null +++ b/docs/operating/reverse_proxy.md @@ -0,0 +1,64 @@ +--- +title: Reverse proxy +sort_rank: 6 +--- + +Prometheus is often exposed through a reverse proxy (for example nginx, Caddy, +or Envoy) for TLS termination, authentication, or path-based routing. This page +collects practical proxy settings; adjust them for your environment. + +## General HTTP proxying + +Forward the original host and scheme so generated links and redirects stay +correct when Prometheus is not reached directly: + +```nginx +proxy_set_header Host $host; +proxy_set_header X-Real-IP $remote_addr; +proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; +proxy_set_header X-Forwarded-Proto $scheme; +``` + +Use `proxy_pass` to the Prometheus listen address (for example +`http://127.0.0.1:9090`). If the proxy and Prometheus run on the same host, +binding Prometheus to localhost and proxying only on the public interface reduces +exposure. + +See also [Security](/docs/operating/security/) for CSRF and CORS considerations +when administrative API paths are reachable through the proxy. + +## Live notifications (Server-Sent Events) + +The UI endpoint `/api/v1/notifications/live` uses +[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events). +Many proxies buffer responses by default, which breaks the stream and produces +**Real-time notifications interrupted** in the Prometheus UI. + +Configure a dedicated `location` for that path with buffering disabled and a +long read timeout, for example: + +```nginx +location = /api/v1/notifications/live { + proxy_pass http://127.0.0.1:9090; + proxy_http_version 1.1; + proxy_set_header Connection ""; + proxy_buffering off; + proxy_cache off; + proxy_read_timeout 600s; + proxy_send_timeout 600s; + gzip off; + + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; +} +``` + +Keep the general `location /` block for the rest of the UI and API. Test live +notifications after deploying proxy changes. + +## Related documentation + +- [HTTP API](/docs/prometheus/latest/querying/api/) — includes live notifications +- [Security](/docs/operating/security/) — authentication and API exposure diff --git a/docs/operating/security.md b/docs/operating/security.md index fbfd773ee..fa851c7ab 100644 --- a/docs/operating/security.md +++ b/docs/operating/security.md @@ -202,7 +202,9 @@ As administrative and mutating endpoints are intended to be accessed via simple tools such as cURL, there is no built in [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) protection as that would break such use cases. Accordingly when using a reverse proxy, you -may wish to block such paths to prevent CSRF. +may wish to block such paths to prevent CSRF. See +[Reverse proxy](/docs/operating/reverse_proxy/) for nginx settings (including +the live notifications SSE endpoint). For non-mutating endpoints, you may wish to set [CORS headers](https://fetch.spec.whatwg.org/#http-cors-protocol) such as