CELERITY-panel

C³ CELERITY

⚡ Fast. Simple. Long-lasting.

English | Русский

C³ CELERITY by Click Connect — modern web panel for managing Hysteria 2 and Xray VLESS proxy servers with centralized authentication, one-click node setup, and flexible user-to-server group mapping.

Built for performance: Lightweight architecture designed for speed at any scale.

Dashboard — real-time server monitoring and statistics

⚡ Quick Start

Updating an existing installation? See Safe Production Updates.

1. Install Docker (if not installed):

curl -fsSL https://get.docker.com | sh

2. Deploy panel (Docker Hub - recommended):

mkdir hysteria-panel && cd hysteria-panel

# Download required files
curl -O https://raw.githubusercontent.com/ClickDevTech/hysteria-panel/main/docker-compose.hub.yml
curl -O https://raw.githubusercontent.com/ClickDevTech/hysteria-panel/main/docker.env.example

# Create Greenlock SSL config (required for HTTPS)
mkdir -p greenlock.d
curl -o greenlock.d/config.json https://raw.githubusercontent.com/ClickDevTech/hysteria-panel/main/greenlock.d/config.json

cp docker.env.example .env
nano .env  # Set your domain, email, and secrets
docker compose -f docker-compose.hub.yml up -d

Alternative: Build from source (for development or customization)

git clone https://github.com/ClickDevTech/hysteria-panel.git
cd hysteria-panel
cp docker.env.example .env
nano .env  # Set your domain, email, and secrets
docker compose up -d

3. Open https://your-domain/panel

Planning to manage the panel from AI assistants? See MCP Setup Guide.

Local development (HTTP only, no domain/SSL):

Want to try the panel on your laptop without a public domain or certificate? Use the local compose file — it sets USE_CADDY=true (plain HTTP, no Greenlock/ACME) and publishes port 3000 directly, with dev defaults so it boots without a .env:

git clone https://github.com/ClickDevTech/hysteria-panel.git
cd hysteria-panel
docker compose -f docker-compose.local.yml up -d
# Open http://localhost:3000/panel

Local mode has no TLS and is not for production. Subscription/share links assume HTTPS, so use it only for UI/API testing.

Required .env variables:

PANEL_DOMAIN=panel.example.com
[email protected]
ENCRYPTION_KEY=your32characterkey  # openssl rand -hex 16
SESSION_SECRET=yoursessionsecret   # openssl rand -hex 32
MONGO_PASSWORD=yourmongopassword   # openssl rand -hex 16

🐳 Dokploy (Development and Release)

Use docker-compose.dokploy.yml when deploying through Dokploy with Traefik.

Development Mode (build from current branch)

1. In Dokploy, create a project from this repository/branch.
2. Set compose path to docker-compose.dokploy.yml.
3. Add env vars from docker.env.example and set at least:
   • MONGO_PASSWORD
   • PANEL_DOMAIN
   • ACME_EMAIL
   • ENCRYPTION_KEY
   • SESSION_SECRET
   • DOKPLOY_PANEL_HOST (domain used in Traefik Host(...) rule)
   • DOKPLOY_TRAEFIK_SERVICE_PORT (Traefik target/backend port, default 3000)
4. Deploy: Dokploy will run build: . and start the stack.

This mode is best when you test branch changes before publishing a release image.

Release Mode (Docker Hub image)

If you want stable deploys from Docker Hub tags (without building), replace backend image source in Dokploy compose with:

backend:
  image: clickdevtech/hysteria-panel:latest
  # or pin a release tag, e.g. clickdevtech/hysteria-panel:v1.2.3
  restart: always
  depends_on:
    mongo:
      condition: service_healthy
    redis:
      condition: service_healthy
  expose:
    - "${DOKPLOY_TRAEFIK_SERVICE_PORT:-3000}"
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.celerity.rule=Host(`${DOKPLOY_PANEL_HOST}`)"
    - "traefik.http.routers.celerity.entrypoints=websecure"
    - "traefik.http.routers.celerity.tls=true"
    - "traefik.http.services.celerity.loadbalancer.server.port=${DOKPLOY_TRAEFIK_SERVICE_PORT:-3000}"
  env_file:
    - .env

Use latest for fast updates, or pin an explicit tag for predictable production rollouts.

✨ Features

• 🖥 Web Panel — Full UI for managing nodes and users
• 🔐 Dual Protocol — Hysteria 2 and Xray VLESS on one panel
• 🛡️ Panel 2FA (TOTP) — Unified TOTP verification flow for admin login and sensitive security actions
• 🚀 Auto Node Setup — Install Hysteria/Xray, certs, port hopping in one click
• 👥 Server Groups — Flexible user-to-node mapping
• ⚖️ Load Balancing — Distribute users by server load
• 🚫 Traffic Filtering (ACL) — Block ads, domains, IPs; route through custom proxies
• 🧩 Advanced Hysteria Config — optional ACME challenge options, masquerade modes, resolver, speed test, sniffing, and QUIC tuning
• 📊 Statistics — Online users, traffic, server status
• 📱 Subscriptions — Auto-format for Clash, Sing-box, Shadowrocket, Hiddify
• 🔄 Backup/Restore — Automatic backups with S3 support
• 💻 SSH Terminal — Direct node access from browser
• 🔑 API Keys — Secure external access with scopes, IP allowlist, rate limiting
• 🪝 Webhooks — Real-time event notifications with HMAC-SHA256 signing
• 🗺 Network Map — Visual cascade topology with Forward/Reverse chain routing (beta)
• 🤖 MCP Integration — Native AI assistant support (Claude, Cursor, etc.) for panel management
• 📡 External Probes — A standalone agent with a real sing-box core verifies node connectivity from real networks (guide)
• ☁️ Generic CDN Nodes — Publish Xray WebSocket, gRPC, or XHTTP inbounds through a domain or pinned edge addresses (guide)

⚠️ Beta Features

Network Map & Cascade Topology

Status: beta — fully functional, but manual verification after deploy is recommended.

Cascade topology allows building server chains where clients connect to one node while traffic exits through another. This is useful in scenarios where the entry point must reside in a specific network or jurisdiction — for example, when connections must originate from local cloud provider IP ranges.

Why Use This

Many corporate and carrier networks apply IP-range filtering. Traffic to well-known local hosting providers may pass unrestricted, while connections to foreign IPs are blocked or throttled. Cascade topology solves this: clients connect to a server in a “trusted” IP range, and traffic is transparently proxied to an external server.

Xray Mechanisms Used

The panel generates Xray-core configurations using the following mechanisms:

Link Modes

Reverse Proxy — Xray VLESS Reverse Proxy (always VLESS, VMess is not available). The Bridge server (typically abroad) initiates a persistent connection to the Portal server. Clients connect to Portal, traffic exits through Bridge.

Client ──▶ Portal (entry) ◀── tunnel ── Bridge (exit) ──▶ Internet
                           (bridge initiates connection)

• Portal can be behind NAT or firewall — no incoming connections required
• Suitable for scenarios where the entry point must be in a specific network

Forward Chain — direct outbound chain. Portal establishes connections through relay nodes to the exit Bridge.

Client ──▶ Portal ──▶ Relay (opt.) ──▶ Bridge (exit) ──▶ Internet
           (chained outbounds)

• All nodes in the chain must have a public IP
• REALITY is supported on each hop to encrypt inter-server traffic

REALITY Between Nodes

Tunnel-REALITY is configured independently from the client-facing REALITY on the Portal node. This enables:

• Encrypting inter-server traffic without drawing attention
• Using different SNI/destination for clients vs. tunnels
• Auto-generating x25519 keys and shortIds when creating links

Tunnel Security and Xray Versions

Both ends of a link need at least Xray 25.9.11 for reverse links, 25.9.5 for forward VLESS links with security none, and 26.6.1 for mKCP. The panel refuses to deploy a link on an older core and refuses an Xray version change (single or bulk) below what the node’s links need.

Links deployed by an older panel version (legacy reverse section, plain VLESS tunnels) are redeployed on both ends automatically the first time one of their nodes is synced. A link whose redeploy fails is shown as an error on the Network Map; deploy it manually after fixing the cause.

Post-Deploy Recommendations

1. Check hop statuses on the Network Map
2. Verify traffic exits through the expected Bridge (check exit IP)
3. For Forward Chain — confirm each relay is reachable on its tunnelPort

Limitations

🏗 Architecture

                              ┌─────────────────┐
                              │     CLIENTS     │
                              │ Clash, Sing-box │
                              │   Shadowrocket  │
                              └────────┬────────┘
                                       │
                     hysteria2:// or vless://
                                       │
              ┌────────────────────────┼────────────────────────┐
              ▼                        ▼                        ▼
     ┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
     │  Hysteria Node  │      │   Xray Node     │      │  Hysteria Node  │
     │   :443 + hop    │      │  VLESS Reality  │      │   :443 + hop    │
     └────────┬────────┘      └────────┬────────┘      └────────┬────────┘
              │                        │                        │
              │    POST /api/auth      │   CC Agent API         │
              │    GET /online         │                        │
              └────────────────────────┼────────────────────────┘
                                       ▼
                          ┌────────────────────────┐
                          │    HYSTERIA PANEL      │
                          │                        │
                          │  • Web UI (/panel)     │
                          │  • HTTP Auth API       │
                          │  • Subscriptions       │
                          │  • SSH Terminal        │
                          │  • Stats Collector     │
                          └───────────┬────────────┘
                                      │
                                      ▼
                          ┌────────────────────────┐
                          │       MongoDB          │
                          └────────────────────────┘

How Authentication Works

Hysteria:

1. Client connects to node with userId:password
2. Node sends POST /api/auth to panel
3. Panel validates user and returns { "ok": true/false }

Xray:

1. Client connects with UUID (xrayUuid)
2. CC Agent on node manages user list via API
3. Panel syncs users to node without restarting Xray

Server Groups

Instead of rigid “plans”, use flexible groups:

• Create group (e.g., “Europe”, “Premium”)
• Assign nodes to group
• Assign users to group
• User gets only nodes from their groups in subscription

🔧 Node Types

Hysteria 2

Fast UDP protocol based on QUIC with port hopping and obfuscation support.

Advantages:

• High speed on unstable networks
• Port hopping to bypass blocks
• Salamander and Gecko obfuscation (Gecko requires Hysteria 2.9.x)

Settings:

• Port, port range for hopping
• ACME or self-signed certificates
• Obfs (salamander or gecko) with password

Advanced Hysteria settings in panel:

• Port Hopping interval (hopInterval)
• ACME advanced options (challenge type, alt ports, DNS challenge provider and config)
• Masquerade modes: proxy and string
• Bandwidth limits (up / down) and ignoreClientBandwidth
• Built-in speedTest, disableUDP, udpIdleTimeout
• Protocol sniffing (sniff) and QUIC parameters (quic)
• Custom DNS resolver (resolver)
• ACL source mode (inline or file) + GeoIP/GeoSite paths
• Advanced sections are optional and omitted from generated config until enabled in UI

Xray VLESS

Modern protocol with Reality support and various transports.

Advantages:

• Reality — disguise as legitimate HTTPS traffic
• Multiple transports (TCP, WebSocket, gRPC, XHTTP)
• No domain required for Reality

Transports:

*XHTTP is not supported by all clients. sing-box forks that implement it get the full framing; Mihomo’s xhttp-opts carries path, mode and host only, so an inbound that negotiates framing is omitted from the Clash subscription instead of being published as a proxy that fails on every request.

Security:

🚀 Xray Node Setup

Automatic Setup (Recommended)

1. Add node in panel:

   • Type: Xray
   • IP, SSH credentials
   • Security: Reality (recommended)
   • Transport: TCP (recommended for Reality)

2. Click “⚙️ Auto Setup”

3. Panel will automatically:

   • Install Xray-core
   • Generate Reality keys (x25519)
   • Upload config
   • Install CC Agent for user management
   • Open firewall ports
   • Start services

Reality Settings

CC Agent

CC Agent is a lightweight HTTP service on the node for managing Xray users without restart.

Features:

• Add/remove users on the fly
• Traffic stats collection
• Health check

Agent is installed automatically during Xray node auto-setup.

🔧 Hysteria Node Setup

Understanding Node Configuration

Ports

• Main port (443) — Port Hysteria listens on
• Port hopping range (20000-50000) — UDP ports for hopping
• Stats port (9999) — Internal port for stats collection

Domain vs SNI

Scenarios:

1. Simple setup: Set domain, leave SNI empty
2. Domain fronting: Set domain for certs, SNI as popular domain
3. No domain: Leave empty — self-signed certificate will be used

Automatic Setup (Recommended)

1. Add node in panel (IP, SSH credentials)
2. Click “⚙️ Auto Setup”
3. Panel will automatically:
   • Install Hysteria 2
   • Configure ACME or self-signed certificates
   • Set up port hopping
   • Open firewall ports
   • Start service

Obfuscation (Salamander / Gecko)

Hysteria supports obfuscation to disguise traffic:

1. Enable Obfs in node settings
2. Select Salamander or Gecko (gecko requires Hysteria 2.9.x)
3. Set obfuscation password
4. Save and update config

Clients will automatically receive the selected obfs type and password in subscription.

Single VPS Setup (Panel + Node)

You can run panel and node on the same VPS (panel TCP, node UDP on 443).

Option 1: Use panel domain (recommended)

• Set node domain same as panel domain
• Panel certificates will be copied automatically

Option 2: No domain (self-signed)

• Leave domain field empty
• Self-signed certificate will be generated

📖 API Reference

API Key Authentication

All /api/* endpoints (except /api/auth and /api/files) require authentication.

Create a key: Settings → Security → API Keys → Create Key

Usage:

# Option 1 — header
X-API-Key: ck_your_key_here

# Option 2 — Bearer token
Authorization: Bearer ck_your_key_here

Scopes

Rate Limiting

Each key has a configurable rate limit (default: 60 req/min).
Exceeded requests return 429 with X-RateLimit-Limit / X-RateLimit-Remaining headers.

Authentication (for nodes)

POST /api/auth

Validates user on Hysteria node connection.

// Request
{ "addr": "1.2.3.4:12345", "auth": "userId:password" }

// Response (success)
{ "ok": true, "id": "userId" }

// Response (error)
{ "ok": false }

Subscriptions

GET /api/files/:token

Universal subscription endpoint. Auto-detects format by User-Agent.

Query params: ?format=clash, ?format=singbox, ?format=uri

GET /api/files/info/:token

Subscription info (status, traffic, expiry).

Users

Required scope: users:read (GET) / users:write (POST, PUT, DELETE)

Nodes

Required scope: nodes:read (GET) / nodes:write (POST, PUT, DELETE)

Stats & Sync

🪝 Webhooks

Send real-time event notifications to any HTTP endpoint.

Configure: Settings → Security → Webhooks

Request Format

POST https://your-endpoint.com/webhook
Content-Type: application/json
X-Webhook-Event: user.created
X-Webhook-Timestamp: 1700000000
X-Webhook-Signature: sha256=<hmac>
User-Agent: C3-Celerity-Webhook/1.0

{
  "event": "user.created",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "data": { ... }
}

Signature Verification

const crypto = require('crypto');
const expected = 'sha256=' + crypto
  .createHmac('sha256', YOUR_SECRET)
  .update(`${timestamp}.${rawBody}`)
  .digest('hex');
// compare with X-Webhook-Signature header

Events

Disk alert thresholds are configured under Settings → Security → Webhooks (Warning: free space below % and Critical: free space below GB). Alerts fire once per threshold crossing with hysteresis to avoid spam, and a recovery event is sent once free space climbs back above the warning level.

📡 External Diagnostic Probes

A probe is a separate Go binary installed on your own server. It receives a hidden subscription, runs a real sing-box core and connects to your nodes the same way a customer does, which shows whether a node is reachable from that particular network.

Enable it under Settings → Probes, then add a probe and run the generated install command on the host you want to check from. Every result is stored per vantage point and never overrides node.status, since a failure can also come from the probe’s own uplink.

Each failure code points at a specific cause: net_unreachable (port filtered on the path), handshake_failed (dead REALITY destination or DPI), auth_rejected (user not pushed to the running core), tunnel_no_data (broken outbound or ACL), degraded, and core_down for a failure of the probe’s own core.

📖 Full guide: English · Русский

🧹 Disk Space & Maintenance

MongoDB and the panel stop working when the host runs out of disk, so keep an eye on free space (the dashboard shows a Disk chart and webhooks can alert you — see above). The most common cause of a full disk is Docker accumulating unused images, containers and logs over time.

Cap container log size (prevents logs from filling the disk). Add to each service in your docker-compose.yml:

    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Periodically reclaim space used by dangling/unused Docker data:

# Safe: remove only dangling images and build cache
docker image prune -f
docker builder prune -f

# Aggressive: also removes ALL unused images (next deploy re-pulls them)
docker system prune -a -f

A weekly cron job running docker image prune -f is usually enough to keep disk usage in check.

📊 Data Models

User

Node

Xray Settings (node.xray)

ServerGroup

🚫 Traffic Filtering (ACL)

Control traffic routing on each Hysteria node. Access: Panel → Node → Traffic Filtering.

Built-in Actions

Rule Examples

reject(suffix:doubleclick.net)     # Block ads
reject(suffix:googlesyndication.com)
reject(geoip:cn)                   # Block Chinese IPs
reject(geoip:private)              # Block private IPs
direct(all)                        # Allow everything else

Custom Proxy Routing

1. Add proxy (e.g., my-proxy, SOCKS5, 1.2.3.4:1080)
2. Use in rules: my-proxy(geoip:ru)

⚖️ Load Balancing

Configure in Settings:

• Enable balancing — Sort nodes by current load
• Hide overloaded — Exclude nodes at capacity

Algorithm:

1. Get user’s nodes from groups
2. Sort by load % (online/max)
3. Filter overloaded if enabled
4. Fall back to rankingCoefficient

🔒 Device Limits

Priority:

1. User’s personal limit (maxDevices > 0)
2. Minimum limit from user’s groups
3. -1 = unlimited

Device Grace Period — delay (in seconds) before counting a disconnected device, to avoid false triggers during reconnections.

📱 Subscription Page Customization

Customize the HTML subscription page in Settings → Subscription:

The subscription page automatically shows:

• QR code for app import
• Traffic stats and expiration
• Location list with copy buttons

💾 Backups

Auto Backups

Configure in Settings → Backups:

• Interval (in hours)
• Number of local copies to keep

Manual Backup

Dashboard button — file auto-downloads.

Restore

Upload .tar.gz archive via interface.

S3-Compatible Storage

Backups can be automatically uploaded to S3-compatible storage (AWS S3, MinIO, Backblaze B2, Cloudflare R2, etc.).

Configure: Settings → Backups → S3

Configuration examples:

# AWS S3
Endpoint: (empty)
Region: eu-central-1
Bucket: my-backups

# MinIO
Endpoint: https://minio.example.com
Region: us-east-1
Bucket: backups

# Cloudflare R2
Endpoint: https://<account-id>.r2.cloudflarestorage.com
Region: auto
Bucket: my-backups

🐳 Docker Compose

version: '3.8'

services:
  mongo:
    image: mongo:7
    restart: always
    volumes:
      - mongo_data:/data/db
    environment:
      MONGO_INITDB_ROOT_USERNAME: ${MONGO_USER:-hysteria}
      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD}

  backend:
    image: clickdevtech/hysteria-panel:latest
    restart: always
    depends_on:
      - mongo
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./logs:/app/logs
      - ./greenlock.d:/app/greenlock.d
      - ./backups:/app/backups
    env_file:
      - .env

volumes:
  mongo_data:

📝 Environment Variables

🤝 Contributing

Pull requests welcome!

📄 License

MIT