Self-hosted Xray proxy management for small teams. Push configs over SSH, detect config drift, and generate multi-format subscriptions from one embedded Go binary.

中文文档

• Node lifecycle management for Xray Reality deployments
• Config drift detection with scheduled SHA256 comparisons
• User and group management for subscription access control
• Subscription generation with health-aware node selection
• SSH-based sync with atomic uploads and remote service reloads
• Single-binary deployment with the frontend embedded via go:embed
• Runtime system settings managed from the web UI and persisted in the database

Place screenshots in docs/screenshots/ with the following naming convention:

• 01-login.png
• 02-dashboard.png
• 03-users.png
• 04-profiles.png
• 05-settings.png
• 06-subscribe.png

Recommended capture order:

1. Login screen
2. Dashboard overview
3. User management
4. Protocol configuration
5. System settings
6. Subscription portal

The current admin UI is primarily Chinese. Keeping README.md in English is still recommended for project discovery, while the screenshots and the Chinese manual provide localized context.

Secure access to the control panel with a lightweight sign-in screen, theme toggle, GitHub link, and clear operator-facing branding.

The dashboard highlights node health, active users, subscription delivery, recent operations, and the current control-plane status in a single view.

Manage subscription users, copy subscription links, open QR codes, assign groups, control expiration, and toggle access with consistent confirmation flows.

Define protocol templates, attach node-specific key material, and keep shared settings separate from node overrides for clearer operations.

Inspect runtime diagnostics, review deployment hints, and manage database-backed system settings without editing config files manually.

Render a browser-friendly subscription page with QR import, node-level copy actions, theme support, and smart fallback links while keeping client access on the same /sub/{token} endpoint.

Linux amd64 and arm64 hosts can install the latest release with:

curl -fsSL https://raw.githubusercontent.com/imrui/xray-pilot/main/install.sh | sudo bash

The installer will:

• detect amd64 or arm64
• download the latest GitHub Release
• verify checksums.txt
• install xray-pilot to /usr/local/bin/xray-pilot
• create /etc/xray-pilot/config.yaml
• create /etc/xray-pilot/ssh/ for service-managed SSH keys
• create and start the xray-pilot.service systemd unit
• generate a random admin password, JWT secret, and crypto master key

Manual installation steps:

1. Download the matching archive and checksums.txt from the latest GitHub Release.
2. Verify the archive with sha256sum -c checksums.txt --ignore-missing.
3. Extract the binary and place it in your preferred location.
4. Copy config.yaml.example to config.yaml and adjust the values.
5. Start the service with ./xray-pilot.

For fresh nodes, use scripts/node-bootstrap.sh to prepare SSH access, install Xray, and optionally enable BBR before adding the node to the panel.

Typical flow:

curl -fsSL https://raw.githubusercontent.com/imrui/xray-pilot/main/scripts/node-bootstrap.sh | sudo bash

The script supports interactive public-key input, or you can provide AUTHORIZED_KEYS up front for non-interactive usage:

curl -fsSL https://raw.githubusercontent.com/imrui/xray-pilot/main/scripts/node-bootstrap.sh | \
sudo AUTHORIZED_KEYS=$'ssh-ed25519 AAAA... admin@main\nssh-ed25519 AAAA... root@main' bash

The script creates a timestamped backup of sshd_config before changing PermitRootLogin.

Existing Linux installations can be upgraded by re-running the installer:

curl -fsSL https://raw.githubusercontent.com/imrui/xray-pilot/main/install.sh | sudo bash

The upgrade process will:

• replace /usr/local/bin/xray-pilot with the latest release binary
• keep the existing /etc/xray-pilot/config.yaml
• keep the existing /etc/xray-pilot/ssh/ key directory
• keep the existing SQLite database or external database settings
• reload and restart xray-pilot.service

After the upgrade, you can confirm the running version with:

journalctl -u xray-pilot -n 20 --no-pager

Prerequisites: Go 1.26.1+, Node.js 24+

git clone https://github.com/imrui/xray-pilot.git
cd xray-pilot

make build

cp config.yaml.example config.yaml
# edit jwt.secret and crypto.master_key before first production run

./xray-pilot

Open http://localhost:2026 and sign in with the administrator account defined in config.yaml.

Copy config.yaml.example to config.yaml.

server:
  port: 2026
  mode: release

database:
  driver: sqlite
  dsn: xray-pilot.db

jwt:
  secret: "change-me-use-a-long-random-string"
  expire: 24

crypto:
  master_key: ""

ssh:
  default_port: 22
  default_user: "root"
  default_key_path: ""
  known_hosts_path: "/var/lib/xray-pilot/known_hosts"

admins:
  - username: admin
    password: "change-me-now"

For Linux service deployments, the recommended SSH key location is /etc/xray-pilot/ssh/id_ed25519. The service-owned known_hosts file is stored at /var/lib/xray-pilot/known_hosts.

Runtime settings such as scheduler intervals, SSH defaults, subscription formatting, and Xray log options are stored in the database-backed system settings table and managed from the web UI.

Environment variable override:

XRAY_PILOT_MASTER_KEY=<hex-key> ./xray-pilot

Priority order:

1. XRAY_PILOT_MASTER_KEY
2. config.yaml -> crypto.master_key
3. auto-generated key on first start

# backend
make dev-backend

# frontend
make dev-frontend

The frontend dev server proxies API requests to http://localhost:2026.

Pushing a tag named v* triggers GitHub Actions to:

1. build the frontend with Node 24
2. compile release binaries with Go 1.26
3. package tar.gz archives for Linux and macOS on amd64 and arm64
4. generate checksums.txt
5. publish a GitHub Release with all artifacts attached

MIT. See LICENSE.