aaPanel Docker manager bridge network conflicting with local host IP subnets

Root Cause Diagnosis

When aaPanel initializes its Docker Manager plugin, Docker automatically assigns default IP subnets (typically 172.17.0.0/16 or sequentially picked 172.X.0.0/16 blocks) to the default bridge interface (docker0) and custom panel-managed networks. If these automatically generated CIDR pools overlap with existing local host interfaces, LAN ranges, or VPN subnets, the host’s routing table prioritizes local Docker interface routes over external gateway interfaces. Consequently, packets destined for local network resources or incoming management traffic are misrouted into Docker’s virtual bridge, causing immediate SSH lockouts, dropped host connectivity, or unresolvable internal IP conflicts.

Quick Fix

Modify Docker’s global daemon configuration to force default bridge allocation into a non-conflicting IP range, prune existing conflicting bridge networks, and restart the Docker service:

cat <<EOF > /etc/docker/daemon.json
{
  "bip": "192.168.240.1/24",
  "default-address-pools": [
    {"base": "192.168.241.0/20", "size": 24}
  ]
}
EOF
systemctl restart docker && docker network prune -f

Step-by-Step Resolution

1. Identify Overlapping Subnets and Interface Routes

Examine your system routing table alongside active Docker networks to confirm subnet collisions.

# Check host interfaces and routing table
ip route show

# List active Docker networks and their assigned subnets
docker network ls --format "{{.ID}} {{.Name}} {{.Driver}}" | xargs -n 3 docker network inspect --format '{{.Name}}: {{range .IPAM.Config}}{{.Subnet}}{{end}}'

2. Reconfigure Global Docker Address Pools

Edit or create /etc/docker/daemon.json to enforce non-overlapping CIDR blocks for both the default docker0 bridge and any dynamic user networks created via aaPanel’s UI.

{
  "bip": "10.200.0.1/24",
  "default-address-pools": [
    {
      "base": "10.200.10.0/20",
      "size": 24
    }
  ]
}

Note: Replace 10.200.0.0 CIDR blocks with an unassigned private IP space distinct from your LAN, WAN, or VPN ranges.

3. Reconfigure aaPanel Docker Plugin Specific Networks

If aaPanel deployed a custom Compose stack or standalone bridge network via its Web Manager, locate and update the network definitions in aaPanel’s project files, typically located under /www/server/panel/plugin/docker or project compose root directories:

networks:
  default:
    driver: bridge
    ipam:
      config:
        - subnet: 10.200.20.0/24

4. Remove Conflicting Docker Networks

Stop aaPanel-managed container stacks and purge the conflicting virtual bridge interfaces.

# Stop running containers managed by aaPanel
docker stop $(docker ps -a -q)

# Remove unused and dangling networks
docker network prune -f

# Re-initialize Docker daemon with new configuration
systemctl restart docker

5. Verify Network Isolation and Host Routes

Confirm that the host routing table has been cleared of conflicting routes and that docker0 is using the newly defined pool.

ip route | grep docker
docker network inspect bridge --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}'

Why This Fails for Some Users

Persistent Custom Compose Networks: Updating /etc/docker/daemon.json only affects newly created networks and the default docker0 bridge. Existing custom networks created by aaPanel before editing daemon.json retain their hardcoded IP subnets until manually removed and recreated via docker network rm.
IPTables Rule Persistence: aaPanel installs explicit firewall management scripts (bt CLI, iptables, or firewalld). Even after resetting Docker bridge interfaces, stale FORWARD chain or MASQUERADE rules pointing to the old 172.17.X.X subnets can remain cached in memory, requiring a complete firewall flush (iptables -F && systemctl restart docker).
Overlap with WireGuard/Tailscale Interfaces: Virtual private network adapters dynamically assign interfaces at boot time. If aaPanel or Docker starts prior to the VPN service initializing its interface, Docker may claim a range (e.g., 172.20.0.0/16) that a VPN subsequently attempts to use, breaking encrypted tunnel routes.
Hardcoded aaPanel Plugin Scripts: Older versions of aaPanel’s Docker Manager plugin contain Python setup scripts that explicitly instantiate bridges using 172.18.0.1/16 without checking system routing tables. In these environments, running a container deployment directly from aaPanel’s App Store overrides global Docker daemon settings unless the plugin files are manually updated.