Introduction to HX-ProxyGroup

Relevant source files

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

• AGENTS.md
• ref/README.md
• cmd/hx-proxygroupd/main.go
• internal/store/migrations.go
• SECURITY.md
• install.sh
• web/src/App.tsx
• web/src/pages/overview-page.tsx

HX-ProxyGroup is a proxy control plane designed to manage proxy subscriptions, nodes, and routing groups. It manages a separate data plane (Mihomo) to handle actual traffic forwarding. The system provides a web-based management console for configuring listeners, residential proxies, and automated routing rules.

Sources: AGENTS.md:12-14, cmd/hx-proxygroupd/main.go:130-155

System Architecture

The project follows a strict separation between the control plane and the data plane. The control plane handles configuration facts, while the data plane handles network traffic.

Core Components

• Control Plane (hx-proxygroupd): A Go-based service that manages the SQLite database, processes API requests, and compiles configurations for the data plane.
• Data Plane (Mihomo): An independent managed process that performs actual proxy protocol (VMess, VLESS, Trojan, etc.) forwarding based on configurations generated by the control plane.
• Web Console: A React-based single-page application (SPA) providing a user interface for management.
• Terminal Helper: A privileged root PTY helper that enables administrative shell access through the browser.

Sources: AGENTS.md:12-32, SECURITY.md:27-33, cmd/hx-proxygroupd/main.go:48-60

Component Relationship Diagram

The following diagram illustrates the interaction between the management interface, the control plane, and the Mihomo data plane.

Data Model and Storage

The system uses SQLite with Write-Ahead Logging (WAL) as its primary storage. The database schema manages the entire lifecycle of proxy resources.

Key Database Entities

Table	Description
subscriptions	Stores remote, inline, or file-based proxy sources and refresh intervals.
nodes	Stores individual proxy node details, credentials (encrypted), and health states.
proxy_groups	Defines groups of nodes with specific selection strategies (e.g., fallback, load balance).
listeners	Configures inbound ports (HTTP, SOCKS5, Mixed, etc.) and binds them to proxy groups.
residential_channels	Manages dynamic residential IP exit channels and session sticky logic.
traffic_totals	Persists aggregated upload/download bytes and connection counts for resources.

Sources: internal/store/migrations.go:19-150, internal/store/migrations.go:300-330, AGENTS.md:31-33

Logical Data Flow

1. Subscription Refresh: The scheduler fetches node lists from remote URLs.
2. Node Processing: Nodes are parsed, deduplicated via fingerprints, and stored.
3. Config Compilation: The control plane compiles nodes, groups, and listeners into a Mihomo-compatible YAML.
4. Data Plane Apply: The configuration is sent to Mihomo via a Unix Socket or written to an active.yaml file for the data plane to reload.

Sources: internal/store/migrations.go:19-80, cmd/hx-proxygroupd/main.go:160-180, AGENTS.md:82-87

Security and Deployment

HX-ProxyGroup implements several security boundaries to protect sensitive proxy credentials and administrative access.

Security Boundaries

• Network Binding: The management API binds to 127.0.0.1 by default. Exposure to a public network requires an authenticated reverse proxy with TLS.
• Credential Protection: All sensitive data, including node passwords, subscription tokens, and SMTP credentials, are encrypted using AEAD with a master key.
• Terminal Access: The browser-based terminal requires a configured administrator session, TOTP 2FA verification, and is limited to two concurrent sessions.
• Process Isolation: The control plane runs as a non-privileged hx-proxygroup user, while the terminal helper creates a root PTY for system administration.

Sources: SECURITY.md:10-25, SECURITY.md:27-45, install.sh:98-105

Deployment Lifecycle

The system is managed via an installation script (install.sh) which handles:

1. Account Creation: Sets up the hx-proxygroup system user and group.
2. Directory Structure: Creates segregated directories for config, data, logs, and snapshots.
3. Service Management: Deploys systemd units for the control plane, data plane, and terminal helper.
4. Atomic Upgrades: Downloads releases, validates SHA-256 checksums, and performs rollbacks if readiness checks fail.

Sources: install.sh:10-25, install.sh:98-115, install.sh:220-240

Proxy Management Features

Routing and Proxy Groups

Administrators define how traffic is routed by creating Proxy Groups. These groups support multiple selection strategies:

• url-test: Automatically selects the node with the lowest latency.
• fallback: Uses the first available node in the list.
• load-balance: Distributes traffic across nodes.
• manual: Requires manual selection of the active node.

Sources: web/src/pages/routing-page.tsx:32-34, internal/store/migrations.go:76-88

Residential Proxies

The system integrates with residential IP providers (e.g., BestProxy). It supports:

• Sticky Sessions: Maintains a stable client identity while rotating the backend residential exit IP.
• Provider Integration: Supports API-based node extraction and account-based gateway templates.
• Lazy Allocation: Allocates exit IPs only when the first client request arrives to conserve provider quota.

Sources: web/src/pages/residential-page.tsx:15-60, internal/store/migrations.go:500-515, ref/README.md:16-30

Monitoring and Observability

The Web Console provides real-time and historical insights into the system's operation.

• Traffic Charts: Displays sliding window graphs for upload and download rates.
• Resource Monitoring: Tracks host CPU and Memory usage for both the control and data plane processes.
• Live Logs: Streams real-time logs from the Mihomo data plane via SSE.
• Health Checks: Periodically probes nodes for latency and availability, recording failures in the node_quality_checks table.

Sources: web/src/pages/overview-page.tsx:140-180, web/src/components/host-resources.tsx:10-35, internal/store/migrations.go:100-115

HX-ProxyGroup serves as a robust management layer for complex proxy environments, focusing on stability, configuration atomicitiy, and secure administrative access.

Sources: AGENTS.md:12-20, cmd/hx-proxygroupd/main.go:480-500