NODEDC_PLATFORM/services/dc-amd-proxy

DC AMD Proxy

Полный воспроизводимый install/recovery/migration-контракт находится в OPERATIONS.md. Этот README фиксирует краткую runtime-модель; операционные изменения должны одновременно обновлять runbook.

dc-amd-proxy is the dedicated, controllable boundary between NODE.DC Map Gateway and the adjacent AMD VPN machine. It is deliberately independent from the historic proxy-contur service.

After pairing it has no direct Cesium egress: every approved Cesium/Bing request is tunnelled through the authenticated AMD connector (172.22.0.183:8791). The NAS always addresses this stable LAN endpoint; the AMD host alone owns its changing VPN exit.

This is a single restricted transport path, not a per-tile relay chain. The NAS keeps a small, bounded pool of HTTP/1.1 TLS tunnels per approved upstream host, so adjacent tile requests reuse the existing NAS → AMD → VPN channel. The pool is limited to eight active and four idle sockets per host by default; it cannot become a general-purpose proxy or consume an unbounded amount of the workstation's network resources.

/status exposes only safe operational counters: active/idle/queued sockets per approved origin, the retained peak queue, logical/in-flight/terminal requests, tunnels opened, reused sockets, bounded retries, complete and partial response bytes, separate queue/CONNECT+TLS/TTFB/retry/total timing, body-stream failures, client aborts, and the last short error code. Every accepted egress request is accounted exactly once even when the browser disconnects while it is queued, connecting, following a redirect, waiting for headers, or retrying. The status never contains an Ion token, connector token, full URL, or query parameters.

An upstream Authorization header is retained only across same-origin redirects. A redirect from the Cesium API origin to an assets or Bing origin is followed only after that header is removed, so an API/master bearer cannot cross provider credential boundaries.

Only an idempotent GET/HEAD that loses an already reused keep-alive socket is retried, once. The failed reused-socket attempt and the terminal retry attempt are logged separately with numeric transport timings and no URL or credential fields. A response body that makes no progress for 30 seconds is terminated and counted as a stream failure, so a stalled VPN connection cannot occupy one of the eight per-origin sockets forever. These limits are local to Cesium egress and do not modify routing or connectivity of the AMD workstation.

Pairing and operational state

The active service has an explicitly narrow first-pair contract:

• POST /api/pair accepts exactly one connector access token and only from the configured AMD LAN source address;
• the AMD operator invokes a supplied local script; it reads the token inside the AMD installation and sends it without printing it or putting it in chat;
• the NAS writes the paired value only to its private runtime directory, never to .env, SMB inbox, a deploy artifact, browser code, or logs;
• the Map Gateway fetch contract (/proxy/cesium/fetch) remains private to the NAS LAN address and still requires the runner-synchronised map egress token;
• the service follows only the fixed Cesium Ion/Bing host allowlist and cannot fall back to direct NAS Internet egress.

Deployment order

1. Deploy this service and confirm /healthz reports awaiting_pair. Map Gateway remains on its existing egress during this step.
2. On AMD, run the supplied one-time pairing script. It sends the locally-held connector secret directly to the NAS and reports no secret value.
3. Verify the private Map Gateway request through this service.
4. Apply the separate, minimal Map Gateway switch patch. It changes only its private egress hostname from the historical service to dc-amd-proxy.

The initial 001 deployment was intentionally inert. It is superseded by this active configuration; it did not alter NAS routing, the NAS VPN/Tailscale configuration, or the Windows workstation's VPN configuration.

Why host networking is narrow here

Synology's Docker published-port proxy replaces the caller address before it reaches a bridged container. That makes a strict one-time AMD source-address check impossible. This service therefore uses the host network namespace but binds its own HTTP listener only to 172.22.0.222:8790; it is not bound to all NAS interfaces. No host route, VPN, DNS, Tailscale setting or firewall rule is changed. The forwarding code still has one hard-coded outbound path only: the authenticated AMD connector.