What this guide is for (and what “side gateway” means here)
Many home labs already have a NAS or mini PC that stays on 24/7. Running Clash Meta (often referred to as Mihomo upstream) inside Docker on that machine is an attractive compromise: you keep your main router’s firmware boring and supported, while a second Linux box becomes a side gateway—a dedicated hop that applies policy to whichever LAN clients you aim at it. Readers searching for Docker Clash plus 旁路由-style setups usually want two deliverables at once: port mapping that exposes the controller and proxy listeners predictably, and LAN gateway steps that make a TV or console use that box without per-app SOCKS settings.
This article walks that path in order: fix the network diagram, bind ports you can reason about, align YAML with your Docker mode, then set DHCP or static routes on clients. It complements (but does not duplicate) a bare-metal Ubuntu systemd install and the conceptual map in the Clash TUN mode guide—here the operating system contract is Docker’s, not systemd’s, and the failure modes include published ports, forwarded interfaces, and bridge MTUs rather than desktop tray icons.
Step 1: Freeze the LAN topology before you touch YAML
Pick numbers you can write on a sticky note. A common pattern keeps everything on one RFC1918 segment, for example 192.168.1.0/24, where the main router is 192.168.1.1 and your Docker host (the future side gateway) uses a static DHCP reservation such as 192.168.1.10. The crucial idea is that clients that should use Clash must receive 192.168.1.10 as their default gateway and, unless you have a separate resolver plan, the same address (or your router) as DNS.
Avoid mixing VLANs on your first pass. If you later move IoT to another subnet, revisit forwarding and firewall rules explicitly; Docker’s default bridge does not magically route between VLANs. Document which devices are “policy clients” (game console, smart TV, guest tablet) versus “leave alone” (printer, security cameras) so you do not chase DHCP issues that are actually intentional isolation.
Step 2: Choose a Docker networking mode with intent
Three modes cover almost every home deployment:
- Bridge + port publishing (
-p 7890:7890): simplest mental model; the container has its own network namespace and you forward specific ports to the host IP that LAN clients already reach. Best when you primarily need HTTP/SOCKS on a known port and an external-controller port for the dashboard. - Host networking (
--network hoston Linux): the container shares the host’s interfaces and port namespace. Listeners bind like native processes, which removes NAT hairpins but couples the container to host firewall rules and makes “which IP answers ARP” identical to the host—often desirable on a dedicated side-gateway box with a single Ethernet path. - Macvlan/ipvlan (advanced): gives the container its own MAC and L3 address on the LAN. Powerful when you want the gateway to look like a separate appliance, but it complicates host↔container communication and varies by NAS vendor; treat it as a second-phase optimization.
If you are on a consumer NAS GUI, you will usually map ports in the UI; translate those mappings mentally to -p flags. The important part is consistency: the address clients use as gateway must be the interface where your published ports live.
Step 3: Map the ports that matter (and ignore the rest)
Most Mihomo profiles expose a mixed port (HTTP plus SOCKS on one TCP listener), an external-controller for REST or web UIs, and sometimes a dedicated DNS inbound. Before enabling transparent proxy features, decide explicitly:
- Which TCP port is your mixed inbound (commonly
7890, but your YAML decides). - Which address the controller binds to—loopback-only inside the container is safer; if you need a phone on Wi-Fi to open the dashboard, bind to
0.0.0.0and firewall it. - Whether DNS will be answered by Mihomo or forwarded to upstream via your router; mismatch here looks like “everything connects but nothing resolves.”
Example docker run sketch for bridge mode (adjust image name and paths to match your stack):
docker run -d --name mihomo --restart unless-stopped \
-v /path/to/config:/root/.config/mihomo \
-p 7890:7890/tcp \
-p 9090:9090/tcp \
your-mihomo-image:tag
With host networking, omit -p and ensure the profile binds listeners to the host interface you expect. After the container starts, verify from another LAN machine: curl http://192.168.1.10:9090/version (controller) and a SOCKS or HTTP probe against the mixed port using a tool that lets you pick proxy explicitly—before you point default gateways at the box.
Step 4: TUN inside Docker for transparent proxy (privileges and devices)
When you need true transparent proxy—traffic that does not honor application-level proxy settings—TUN mode pushes policy to the IP layer. Inside Docker, that implies kernel cooperation: the container typically needs CAP_NET_ADMIN, access to /dev/net/tun, and sometimes NET_ADMIN plus elevated security_opt depending on your runtime. Synology, QNAP, and Proxmox LXC-backed hosts each wrap these flags differently, but the checklist is universal:
- Mount
/dev/net/tunread-write. - Add capability
NET_ADMIN(and bind service capability if you use low ports). - Confirm the
tun:stack (systemversus userspace) matches what your kernel supports in a container. - Decide whether
auto-routeinside the container should manipulate routes on the host—with host networking, yes; with bridge, usually not in the way bare metal does.
If TUN in Docker fights your NAS kernel or orchestration policy, the pragmatic fallback is still classic redir or iptables rules on the Linux host outside the container, forwarding marked traffic into the published mixed port. That is more moving parts, but it keeps the daemon simple. Re-read the capture-mode trade-offs in the TUN guide before you enable five experimental keys at once.
Step 5: Point LAN clients at the side gateway (DHCP and static)
For televisions and consoles, per-app SOCKS is rarely available; they need a clean default route. On your main router’s DHCP service, create a reservation for each device that should use Clash, then set option 3 (router) to 192.168.1.10 and option 6 (DNS) either to the same host (if Mihomo listens on 53/DoH upstream) or to your router if you prefer the router to recurse. Mixed DNS—some clients on stub resolvers, others on Mihomo—creates “works for five minutes” bugs when fake-ip enters the picture.
If you cannot vary DHCP per host, split Wi-Fi SSIDs or move policy clients into a dedicated SSID whose DHCP scope hands out the side gateway—many routers expose this as “guest network” with custom DNS; repurpose carefully so you do not isolate AirPlay or casting unless that is intended.
After clients renew leases, confirm on the device: gateway IP equals your Docker host, subnet mask matches the LAN, and DNS is what your YAML assumes. Then run a public IP check and a traceroute to verify packets leave via the side box for destinations you expect to proxy, while RFC1918 targets still go direct per your rules.
Step 6: Firewall the controller and think about lateral movement
A side gateway is attractive to anything on the LAN. Restrict who can reach the external-controller port: bind to management VLANs, add iptables or nft rules on the host, or put the dashboard behind SSH port forwarding. Publishing 9090 world-readable on 0.0.0.0 without authentication is how guest Wi-Fi becomes an open REST API to your policy engine.
Likewise, if you enable universal injection features in third-party dashboards, keep the image pinned and verify checksums when you update. The official Clash download page remains the right place to fetch maintained client bundles; treat random container registries like you would treat random shell scripts.
Step 7: Verification sequence that actually catches mistakes
Work top-down so you know which layer failed:
- Container health:
docker psshows stable uptime; logs show listeners bound without privilege errors. - Host port reachability: from a workstation, curl the controller and probe the mixed port with a manual proxy flag—before default-gateway tests.
- Client gateway: on the TV or console, network settings show the side IP; renew DHCP if values are sticky.
- DNS coherence: resolve a domain that should be fake-ip and one that must stay direct; both should match the routing table you expect.
- Policy switching: toggle a policy group and confirm egress changes in Mihomo logs for a canary domain.
Only after those pass is it worth tuning UDP gaming rules or QUIC exceptions. Otherwise you optimize latency for a setup that still blackholes TCP handshakes.
Common symptoms on Docker side gateways
- Works from the host, not from LAN clients: wrong publish flags, firewall on the NAS, or listeners bound to
127.0.0.1inside the container while you expect LAN access. - “Connected” but streaming apps fail: DNS split-brain between router stub and Mihomo; align option 6 with your YAML
dns:section. - TUN starts then exits: missing
/dev/net/tun, insufficient capabilities, or conflict with another VPN container also requesting routes. - Asymmetric speeds on bridge mode: MTU issues through Docker NAT—try host networking for heavy UDP loads or adjust MSS clamping on the router.
Where to go next
Once the container is stable, most “quality of life” improvements live in policy, not Docker: rule ordering, provider refresh intervals, and honest benchmarks between nodes. The Clash documentation hub collects routing concepts that apply equally to containers and bare metal. If you later migrate off Docker to a native service, the YAML you perfected here transfers almost verbatim—only the unit file and capability lines change.
Closing
A side gateway built with Docker Clash wins when you treat it like infrastructure: static addressing, explicit port mapping, guarded management ports, and DNS that matches your transparent proxy story. Compared with bolting random SOCKS ports onto every device, a routed default gateway with Mihomo in the middle usually yields fewer midnight reboots—especially for TVs and consoles that refuse to speak HTTP proxy at all.