Home Network Architecture Evolution (v3.0): All-in-One Dockerization & Centralized Configuration

Posted on Views:

Today’s refactor is not just a patch-up; it’s a fundamental overhaul of the underlying runtime architecture. I have containerized all the loosely scattered scripts and binaries, achieving true “Infrastructure as Code” (IaC).

The Core Transformation: The Big Switch to Docker

Previously, my clients (Mac/Windows) were a collection of loose scripts: manually running the frpc process, and coupling it with an X-UI running in Docker.
The Problem: Complex dependency environments (Python versions, FRP versions), messy process management, and scattered logs.

The v3.0 Solution:
I encapsulated all components into a single docker-compose.yml stack. Now, Mac and Windows clients no longer need a Python environment or manual FRP downloads.
Just one command:

1
docker compose up -d

This automatically spins up:

  • X-UI (Proxy Panel)
  • FRPC (Intranet Tunneling)
  • Sync Sidecar (Config Synchronization)
    These three communicate within the same Docker network, completely decoupling them from the host environment.

Architectural Dividends: Centralized Control

With the standardized environment brought by Dockerization, I can finally implement the Master-Slave Architecture I’ve always wanted:

  • Centralized Configuration:
    Previously, configs were scattered everywhere. Now, I introduced global.env and master_config.json.
    The VPS is the single source of truth. When Mac/Android nodes start up, they automatically pull the latest UUID and user lists from the VPS.
  • Automatic Synchronization:
    Leveraging the connectivity between Docker containers, the Sync Sidecar container periodically checks for config updates.
    Result: Change the config once on the VPS, and it takes effect on all family devices after a restart, without needing to SSH into each device.

Stability Boost: Static IP Network

To solve the common 502/Connection Refused issues when Nginx reverse-proxies Docker containers (caused by DNS cache invalidation or config errors when container IPs change on restart), I implemented a Docker Internal Static IP strategy on the VPS.

By explicitly specifying IPs in docker-compose.yml, I ensure absolute stability in the communication links between service components:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
networks:
  vps_net:
    ipam:
      config:
        - subnet: 10.88.0.0/16

services:
  nginx:
    networks:
      vps_net:
        ipv4_address: 10.88.0.4
  
  frps:
    networks:
      vps_net:
        ipv4_address: 10.88.0.2

This makes the VPS internal network topology solid as a rock. No matter how hot-updates occur, Nginx always knows to find FRP at 10.88.0.2 and other services at 10.88.0.x.

Conclusion

The changes in v3.0 are massive (just look at the screen full of refactor in git log), but the benefits are long-term:

  • Deployment: Changed from “Follow these 10 steps” to “Copy folder -> Docker Compose Up”.
  • Maintenance: Changed from “SSH everywhere to fix things” to “Modify Master Config -> Restart”.
  • Experience: Configuration consistency is greatly guaranteed, no longer worrying about connection failures due to missed config updates on a specific node.

This is how modern home proxy should be built.