Mihomo Controller Integration

Relevant source files

The following files were used as context for generating this wiki page:

• internal/dataplane/mihomo/manager.go
• internal/dataplane/mihomo/controller.go
• internal/dataplane/mihomo/nodes.go
• internal/dataplane/mihomo/logs.go
• internal/dataplane/mihomo/overview.go
• AGENTS.md

Mihomo Controller Integration manages the lifecycle and communication between the HX-ProxyGroup control plane and the Mihomo data plane. The system handles process supervision, configuration deployment, and real-time state synchronization through a dedicated Unix socket.

The integration provides a high-level API for the control plane to manipulate proxy groups, monitor traffic, and read logs without exposing the underlying Mihomo REST API directly to the frontend.

Process and Lifecycle Management

The Manager struct supervises the Mihomo process. It supports two operational modes: managing a local sub-process or interacting with an external process (e.g., systemd-managed).

Lifecycle Flow

The following diagram illustrates the Apply logic, which transitions the data plane from a desired state to a running state.

Manager Configuration Options

Option	Description	File Reference
WithEgressInterface	Binds Mihomo traffic to a specific network interface.	manager.go:88
WithProcessMaxProcs	Limits CPU core usage via GOMAXPROCS.	manager.go:96
WithLogRotation	Configures max bytes and backup count for mihomo.log.	manager.go:105
WithExternalProcess	Disables process supervision to use a systemd instance.	manager.go:114

Controller Communication

The control plane communicates with Mihomo using an internal HTTP client bound to a Unix domain socket (mihomo.sock). This socket facilitates hot-reloads and dynamic changes that do not require a full process restart.

Key Operations

• Proxy Selection: The SelectProxy function sends a PUT request to /proxies/{group} to switch the active member of a manual or residential proxy group. Sources: internal/dataplane/mihomo/controller.go:193-231
• Latency Testing: TestProxy triggers a delay measurement against a specific URL (e.g., cp.cloudflare.com) via the /proxies/{name}/delay endpoint. Sources: internal/dataplane/mihomo/controller.go:121-177
• Connection Draining: CloseConnectionsByInboundUser identifies and terminates specific tunnels based on authenticated inbound metadata. Sources: internal/dataplane/mihomo/controller.go:240-291

Traffic and Connection Monitoring

The TrafficSnapshot and OverviewSnapshot functions retrieve real-time statistics by parsing the /connections JSON response.

Real-time Log Streaming

The integration utilizes WebSockets over the Unix socket to stream Mihomo logs. The logReader sanitizes and redacts sensitive information before passing logs to the control plane.

Redaction and Normalization

To prevent credential leaks, the system applies regex patterns to:

1. Redact URLs: Replaces user:pass@host with [redacted]@host.
2. Mask Headers: Masks Authorization, Cookie, and Token values.
3. Anonymize Routes: Replaces specific connection IPs with [source] --> [destination].

Sources: internal/dataplane/mihomo/logs.go:22-27, internal/dataplane/mihomo/logs.go:132-142

Node Configuration Transformation

Mihomo requires specific YAML structures that differ from standard sharing URIs. The nodes.go module convertsHX-ProxyGroup canonical node records into Mihomo-compatible formats.

Protocol Support Matrix

HX-ProxyGroup Type	Mihomo type	Special Handling
https	http	Sets tls: true
socks	socks5	Normalizes protocol name
vmess	vmess	Maps id to uuid, net to network, and scy to cipher
vless	vless	Passes protocol directly
shadow-tls	shadow-tls	Passes protocol directly

Sources: internal/dataplane/mihomo/nodes.go:39-66

WebSocket Early Data Handling

For Cloudflare Worker (BPB/cfnew) compatibility, the system splits early data parameters from the path.

• Input Path: /?ed=2048
• Mihomo Path: /
• Mihomo WS Options: max-early-data: 2048, early-data-header-name: Sec-WebSocket-Protocol.

Sources: internal/dataplane/mihomo/nodes.go:97-124

Reliability and Safety

The integration implements several safeguards to ensure data plane stability:

• Atomic Configuration Deployment: The manager uses a .candidate file and os.Rename to ensure Mihomo never reads a partially written configuration. Sources: internal/dataplane/mihomo/manager.go:429-455
• Port Probing: Before applying a new config, the manager probes TCP ports to catch address-in-use errors before they cause a Mihomo crash. Sources: internal/dataplane/mihomo/manager.go:327-347
• Automatic Rollback: If a new configuration fails to become "Ready" (TCP ports not listening or Unix socket unreachable), the manager restores the .previous configuration and restarts the process. Sources: internal/dataplane/mihomo/manager.go:391-423

Mihomo Controller Integration serves as the bridge between HX-ProxyGroup's management logic and the high-performance traffic forwarding of Mihomo, ensuring configuration consistency and operational observability.