Mihomo Configuration Compiler
Relevant source files
The following files were used as context for generating this wiki page:
The Mihomo Configuration Compiler transforms domain-specific configuration records from the system database into valid YAML manifests for the Mihomo data plane. It serves as the bridge between the HX-ProxyGroup control plane and the underlying proxy engine. The compiler handles the complexity of decrypting node credentials, resolving proxy group dependencies, and mapping residential client routes to data plane rules.
Sources: internal/dataplane/mihomo/compiler.go:1-68, internal/dataplane/mihomo/manager.go:10-50
Architecture and Data Flow
The compiler implements a pipeline that fetches data from a Repository, processes it through various transformation stages, and outputs a Compiled struct containing the final YAML and metadata.
The compiler utilizes an internal Repository interface to decouple the data access layer from the transformation logic. It also requires a Cipher to handle the decryption of sensitive node and listener authentication data.
Sources: internal/dataplane/mihomo/compiler.go:21-65
Key Data Structures
The compilation process relies on several core structures to manage the state and output of the manifest generation.
| Structure | Purpose |
|---|---|
Compiler | The primary coordinator holding repository, cipher, and socket information. |
Compiled | Holds the final YAML bytes, detected endpoints, and proxy counts. |
Endpoint | Represents a specific bind address and port pair used by a listener. |
compiledNode | Internal map containing the Mihomo-ready node name and configuration map. |
Sources: internal/dataplane/mihomo/compiler.go:40-65
Node Configuration Transformation
The compiler translates internal node records into Mihomo's specific proxy format. This involves decrypting encrypted configuration blobs and mapping fields to protocol-specific keys.
Protocol Mapping
The system normalizes various incoming proxy protocols to ensure compatibility with Mihomo's expected syntax:
httpsis converted totype: httpwithtls: true.socksis converted totype: socks5.vmessfields likeid,scy, andnetare mapped touuid,cipher, andnetwork.
Sources: internal/dataplane/mihomo/nodes.go:46-75
WebSocket and Transport Compatibility
The compiler includes specialized logic for Cloudflare Worker VLESS (BPB/cfnew) compatibility. It splits early-data parameters from WebSocket paths and maps them to Mihomo's ws-opts.
Proxy Group and Chain Resolution
The compiler resolves dependencies between proxy groups to ensure stable YAML output. It uses a topological sort to emit referenced groups before their dependants.
- Dependency Sorting: Groups are ordered so that a group referenced as a
dialer-proxyor a member is defined earlier in the manifest. - Derived Proxies: When a proxy group uses a
dialer-proxy, the compiler generates derived proxy entries that dial through the specified group.
Sources: internal/dataplane/mihomo/compiler.go:284-315, internal/dataplane/mihomo/compiler_chain_live_test.go:20-45
Shared Inbound and Routing Rules
The compiler supports a "Shared Inbound" mode where multiple services multiplex over a single port. It differentiates users based on their authenticated credentials (IN-USER).
Rule Compilation Order
- Residential Client Rules: Direct mapping of users to specific proxy groups.
- Shared Inbound Rules: Rules for demultiplexing shared ports.
- Site Routing: Administrator-defined rules for specific domains or IP ranges.
- Residential Fallback: Default groups for specific listeners.
- Match Direct: Final catch-all rule.
Sources: internal/dataplane/mihomo/compiler.go:167-200, internal/dataplane/mihomo/compiler_shared_inbound_live_test.go:25-45
Validation and Safety Checks
Before finalizing the configuration, the compiler performs safety checks to prevent runtime failures:
- Listener Loops: Ensures no proxy entry points back to a local listener managed by the same instance.
- Endpoint Collision: Validates that two listeners do not attempt to bind to the same IP and port.
- Port Availability: The
Managerprobes target ports before applying new configurations to catch port ownership issues.
Sources: internal/dataplane/mihomo/compiler.go:244-270, internal/dataplane/mihomo/manager.go:345-370
Summary
The Mihomo Configuration Compiler is a critical component that ensures the abstract configuration state is correctly and safely applied to the data plane. By handling protocol normalization, dependency resolution, and multi-user multiplexing, it allows the HX-ProxyGroup system to provide a simplified management interface while leveraging the full capabilities of the Mihomo proxy engine.