Portainer Agent Offline behind a reverse proxy: is 'websocket: bad handshake' a header-forwarding failure?

Symptom

Consider a Portainer CE 2.19.x deployment where the Server and Agent run on separate hosts. Connecting from the Server host directly to the Agent port reports the Agent as Online, but in production — where traffic passes through a reverse proxy — the environment list shows the Agent as Offline, and the Server logs record a WebSocket handshake failure ('websocket: bad handshake', as noted in Portainer's troubleshooting documentation).

Suspected cause and uncertainty

The suspicion is that the proxy does not forward the HTTP Upgrade and Connection headers required for the Server–Agent tunnel, so the handshake is rejected before TLS validation plays any role. The open uncertainty is the production path itself: it may include more than one hop, for example an NGINX front end in front of a cloud load balancer, and it is unclear whether every hop must preserve those headers.

The goal is for the Agent to report Online through the production proxy path, without bypassing the proxy.

Open questions

• Do all intermediate proxies and load balancers in the path need to forward the Upgrade and Connection headers, or only the hop that terminates the request?
• Is this handshake failure fully independent of TLS and certificate configuration, as the documentation implies?
• How can a header-forwarding failure be distinguished from a genuinely unreachable Agent, when both surface as Offline in the UI?