English

L-UI is a control-plane dashboard for managing remote VPS nodes and their Xray instances. The hub does not run Xray itself — it provisions nodes over SSH, installs a lightweight agent, and controls nodes through HMAC-signed HTTP APIs.

┌────────────┐     SSH/SCP       ┌──────────────┐
│            │ ────────────────> │              │
│   HUB      │     bootstrap     │   AGENT      │
│  (Fiber)   │                   │  (Fiber)     │
│            │ <──────────────── │              │
│            │  HMAC-signed HTTP │   runs Xray  │
│ SQLite/    │   api/v1/*       │              │
│ Postgres   │                   └──────────────┘
│            │
│ React 19   │
│ Ant Design │
└────────────┘

• Hub — Go + Fiber v3 backend with embedded React 19 + Ant Design 6 frontend. Manages nodes, inbounds, clients, routing, and assignments. Stores data in SQLite / Postgres / MySQL. Never runs Xray.
• Agent — lightweight standalone binary deployed to each VPS node. Exposes a management API signed with HMAC-SHA256. Runs and manages Xray locally.
• Frontend — single-page React 19 app built with Vite, embedded into the hub binary.

bash <(curl -Ls https://raw.githubusercontent.com/drunkleen/l-ui/master/install.sh)

make dev is the preferred local development path. It prints backend compile progress, waits for readiness, and then starts Vite.

Local development login: admin / admin.

• install.sh is the production installer. Downloads a release bundle, installs the service, and prints a command reference.
• The hub binary supports run, agent, migrate, migrate-db, setting, and cert subcommands.
• The agent binary starts directly on the configured port — no subcommands.

The hub l-ui wrapper supports: start, stop, restart, status, settings, enable, disable, log, banlog, update, legacy, install, uninstall.

• make build produces frontend assets under hub/web/dist/ and both Go binaries under bin/
• GitHub Actions runs CI on pushes to main and pull requests
• Tagged pushes like v1.2.3 trigger release packaging and published artifacts

• ci.yml — validates Go tests, frontend lint/typecheck/tests, and a frontend build on PRs and main
• release.yml — builds release tarballs (l-ui-hub-*.tar.gz, l-ui-agent-*.tar.gz) and Windows zip assets
• docker.yml — publishes production container images for version tags

• SQLite is the default (zero config)
• Postgres is supported for hosted or multi-node deployments
• MySQL/MariaDB is supported through the shared GORM storage layer

See docs/install.md for the deployment model and storage layout.

• Node bootstrap — SSH-based provisioning with retry logic, Caddy TLS support, async job tracking, and a real-time horizontal progress timeline
• Node monitoring — heartbeat polling (every 5s), CPU/MEM/network/disk sparkline charts, configurable alert thresholds with Telegram notifications
• Xray management — config push with atomic apply+restart, remote xray binary installation (agent downloads from GitHub), running status checks
• Config push — push Xray config and client lists to nodes with version tracking. Agent writes config to disk and restarts Xray atomically
• TLS certificates — built-in CA for agent certificate generation, push, and daily auto-renewal
• UFW firewall management — view, add, delete rules on nodes; auto-open/close ports for Xray inbounds; port group management
• Node registration tokens — one-time curl | sh registration flow for nodes without SSH
• Subscription endpoints — standard Xray subscription URL generation
• Telegram bot — notifications for node down, resource thresholds, login events, and database backup

• docs/architecture.md
• docs/bootstrap.md
• docs/install.md
• docs/node-api.md
• docs/troubleshooting.md
• CONTRIBUTING.md

• BTC: bc1qsmvxpn79g6wkel3w67k37r9nvzm5jnggeltxl6
• ETH (ERC20): 0x8613aD01910d17Bc922D95cf16Dc233B92cd32d6
• USDT (TRC20): 0x8613aD01910d17Bc922D95cf16Dc233B92cd32d6
• DOGE: D8U25FjxdxdQ7pEH37cMSw8HXBdY1qZ7n3
• TRX: TGNru3vuDfPh5zBJ31DKzcVVvFgfMK9J48