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,40 @@
+# gfw.windy.lan — OpenWrt LAN gateway
+
+## Role and access
+
+| Item | Value |
+|---|---|
+| Role | LAN gateway and OpenClash transparent/explicit-proxy host |
+| IPv4 | `192.168.66.1` |
+| SSH | `ssh -4 root@192.168.66.1` |
+| OS | OpenWrt, Linux `6.12.87` |
+
+Do not store the root password in this repository. Prefer a verified SSH key for
+future management access.
+
+## OpenClash
+
+OpenClash runs `/etc/openclash/clash` with configuration
+`/etc/openclash/pass-cat.yaml`.
+
+| Listener | Port |
+|---|---:|
+| HTTP | `7890` |
+| SOCKS | `7891` |
+| Redirect | `7892` |
+| Mixed | `7893` |
+| TPROXY | `7895` |
+| DNS | `7874` |
+
+`8443` is not an OpenClash listener and has no runtime nftables forwarding rule.
+It is included only in OpenClash's common TLS-sniffing port list.
+
+## Operational note
+
+When OpenClash logs a LAN client request such as
+`<client> --> localhost:8443` followed by a connection refusal, it is normally
+an explicit-proxy client sending its own loopback request to the gateway. Fix
+the originating host's `NO_PROXY` / `no_proxy` configuration; do not create a
+listener on this router to mask the problem. See
+[the UniFi localhost proxy note](../docs/unifi-openclash-localhost.md).
+
@@ -0,0 +1,58 @@
+# ubnt — UniFi Network Controller
+
+## Role and access
+
+| Item | Value |
+|---|---|
+| Role | UniFi Network Controller host |
+| IPv4 | `192.168.66.46` |
+| SSH | `ssh -4 windy@192.168.66.46` |
+| Hostname | `ubnt` |
+| Privilege | `windy` has passwordless sudo and is in the `docker` group |
+
+The current SSH ED25519 host-key fingerprint is
+`SHA256:TTZtonJnnnNS6vk4xqo+CJPuZGXwwkf46wR1SLmqc10` (verified 2026-08-03).
+Verify a changed key out of band before accepting it.
+
+## UniFi stack
+
+| Item | Value |
+|---|---|
+| Compose directory | `/home/windy/unifi-9` |
+| Compose file | `/home/windy/unifi-9/compose.yml` |
+| Compose service | `unifi` |
+| Container | `unifi-controller` |
+| Image | `jacobalberty/unifi:v9.5.21` |
+| Network mode | host |
+| HTTPS UI | `https://192.168.66.46:8443` |
+
+The controller binds `*:8443`. A local HTTPS request to
+`https://127.0.0.1:8443/` is the primary quick health check.
+
+## Proxy contract
+
+The container has HTTP/HTTPS proxy environment variables. Its Compose
+`environment` list must keep **both** `NO_PROXY` and `no_proxy` enabled and
+include at least:
+
+```text
+localhost,127.0.0.1,::1,192.168.0.0/16,10.0.0.0/8,172.16.0.0/12
+```
+
+Without this bypass, a controller request to `localhost:8443` can be sent to
+the OpenClash gateway instead of remaining local. Details and verification are
+in [the UniFi localhost proxy note](../docs/unifi-openclash-localhost.md).
+
+## Safe reconciliation and verification
+
+```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/
+```
+
+Recreating the service briefly interrupts the controller. Do not use `docker
+compose down -v`; it can remove persistent data.
+