Document UniFi OpenClash proxy bypass

2026-08-03 21:10:57 +08:00
parent efe1d30ff1
commit 64484cd484
5 changed files with 163 additions and 0 deletions
@@ -0,0 +1,60 @@
+# UniFi local HTTPS through OpenClash — proxy bypass contract
+
+## Symptom
+
+OpenClash on `gfw.windy.lan` can log:
+
+```text
+[TCP] dial DIRECT (match IPCIDR/127.0.0.0/8) 192.168.66.46:<port> --> localhost:8443
+error: dial tcp 127.0.0.1:8443: connect: connection refused
+```
+
+This does **not** mean OpenClash should listen on port 8443. The gateway's
+loopback interface has no UniFi service.
+
+## Cause
+
+`ubnt` runs the UniFi controller locally on `*:8443`. Its container also uses
+HTTP/HTTPS proxy variables. If `NO_PROXY` / `no_proxy` omit loopback addresses,
+a request for its own `localhost:8443` is sent to the OpenClash HTTP proxy.
+OpenClash correctly applies its loopback direct rule, but that direct request is
+then made from the gateway, where port 8443 is not open.
+
+## Required configuration
+
+In `/home/windy/unifi-9/compose.yml`, keep both environment entries enabled:
+
+```yaml
+environment:
+  - NO_PROXY=localhost,127.0.0.1,::1,192.168.0.0/16,10.0.0.0/8,172.16.0.0/12
+  - no_proxy=localhost,127.0.0.1,::1,192.168.0.0/16,10.0.0.0/8,172.16.0.0/12
+```
+
+Keep the upper- and lowercase forms because different processes and libraries
+consult different spellings.
+
+## Apply and verify
+
+```bash
+cd /home/windy/unifi-9
+docker compose config -q
+docker compose up -d --force-recreate unifi
+docker inspect --format '{{.State.Health.Status}}' unifi-controller
+curl -k -sS -o /dev/null -w '%{http_code}\n' https://127.0.0.1:8443/
+```
+
+Expected result: Docker health is `healthy` and the local HTTPS request returns
+an HTTP success or redirect response. Recheck OpenClash logs afterwards; the
+`localhost:8443` connection-refused entries should stop.
+
+## Safety
+
+- Do not add a dummy listener on the gateway's `127.0.0.1:8443`.
+- Do not solve this with a router redirect rule; that would hide a client-side
+  proxy error and could send local controller traffic to the wrong host.
+- Back up `compose.yml` before changing it and avoid `docker compose down -v`.
+
+## References
+
+- [gfw.windy.lan host facts](../hosts/gfw.windy.lan.md)
+- [ubnt host facts](../hosts/ubnt.md)