UPDATE
This commit is contained in:
@@ -1,67 +1,164 @@
|
||||
# Nexuma
|
||||
# Nexuma Documentation
|
||||
|
||||
Nexuma is a multi-node VPN and proxy management platform. It lets you deploy VPN servers, manage users and subscriptions, and control everything from a single web interface.
|
||||
Nexuma is a multi-node VPN and proxy management platform. It provides a central web panel, a control API, and node agents that run on VPN/proxy servers.
|
||||
|
||||
## Features
|
||||
This documentation repository is self-contained. The examples below use published container images and do not require access to the application source repositories.
|
||||
|
||||
- **Multi-node** — connect unlimited VPN servers, manage them from one place
|
||||
- **Subscriptions** — per-user links with traffic limits, expiry, and auto-renewal
|
||||
- **Multiple protocols** — VLESS, VMess, Trojan, Shadowsocks, Hysteria2, MTProto
|
||||
- **Balance system** — user balance with deposits, withdrawals, and auto-charge on renewal
|
||||
- **Traffic accounting** — per-subscription usage analytics
|
||||
- **Telegram integration** — OAuth login, user approval flow, admin notifications
|
||||
- **Routing rules** — xray-native rule sets and load balancers per node
|
||||
- **Config builder** — guided wizard for protocol and stream configuration
|
||||
- **Double VPN** — proxy chain support via node outbounds
|
||||
- **External subscriptions** — aggregate external VPN share links into user subscriptions
|
||||
## What Nexuma Provides
|
||||
|
||||
## Architecture
|
||||
- Central management for users, tariffs, subscriptions, nodes, routing, and audit logs.
|
||||
- Public subscription links for VPN clients.
|
||||
- Per-user traffic limits, expiry, balance, and auto-renewal.
|
||||
- Multi-node deployment with per-node protocol configuration.
|
||||
- Supported subscription exports: `v2ray`, `clash`, and `singbox`.
|
||||
- Supported protocols: VLESS, VMess, Trojan, Shadowsocks, HTTP, SOCKS, WireGuard, Hysteria, and MTProto.
|
||||
- Routing rule sets, traffic blocking options, and node outbounds for proxy chains.
|
||||
- External subscription sources that can be appended to user subscriptions.
|
||||
- Telegram login, approval flow, and notifications when configured.
|
||||
|
||||
```
|
||||
┌───────────────────────────────────┐
|
||||
│ Panel │
|
||||
│ (Admin Web Interface) │
|
||||
└────────────────┬──────────────────┘
|
||||
│
|
||||
┌────────────────▼──────────────────┐
|
||||
│ Core │
|
||||
│ (Control Plane API) │
|
||||
│ PostgreSQL ◄────────► Redis │
|
||||
└──────┬────────────────────────────┘
|
||||
│
|
||||
┌────┴──────────────┐
|
||||
▼ ▼
|
||||
Node 1 . . . Node N
|
||||
## Main Components
|
||||
|
||||
```text
|
||||
Users and admins
|
||||
|
|
||||
v
|
||||
Panel - web interface and public subscription page
|
||||
|
|
||||
v
|
||||
Core - API, state, subscription generation, node coordination
|
||||
|
|
||||
v
|
||||
Nodes - VPN/proxy servers that apply configs and report usage
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Deploy Core and Panel
|
||||
|
||||
Download [`docker-compose.base.yml`](./docker-compose.base.yml), fill in your values, and run:
|
||||
Create a `docker-compose.yml` from the base example:
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.base.yml up -d
|
||||
```yaml
|
||||
version: '3.9'
|
||||
|
||||
services:
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
container_name: nexuma-redis
|
||||
restart: unless-stopped
|
||||
volumes:
|
||||
- redis_data:/data
|
||||
networks:
|
||||
- nexuma
|
||||
|
||||
core:
|
||||
image: nexuma/core:latest
|
||||
container_name: nexuma-core
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
PORT: 3000
|
||||
DB_HOST: your-postgres-host
|
||||
DB_PORT: 5432
|
||||
DB_USER: postgres
|
||||
DB_PASSWORD: change-me
|
||||
DB_NAME: nexuma
|
||||
REDIS_HOST: redis
|
||||
REDIS_PORT: 6379
|
||||
JWT_SECRET: replace-with-long-random-secret
|
||||
JWT_REFRESH_SECRET: replace-with-another-long-random-secret
|
||||
JWT_EXPIRES_IN: 15m
|
||||
JWT_REFRESH_EXPIRES_IN: 7d
|
||||
CORS_ORIGINS: https://panel.example.com
|
||||
ports:
|
||||
- "3000:3000"
|
||||
depends_on:
|
||||
- redis
|
||||
networks:
|
||||
- nexuma
|
||||
|
||||
panel:
|
||||
image: nexuma/panel:latest
|
||||
container_name: nexuma-panel
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
NUXT_CORE_URL: http://core:3000
|
||||
NUXT_PUBLIC_API_BASE: /api
|
||||
ports:
|
||||
- "3010:3000"
|
||||
depends_on:
|
||||
- core
|
||||
networks:
|
||||
- nexuma
|
||||
|
||||
volumes:
|
||||
redis_data:
|
||||
|
||||
networks:
|
||||
nexuma:
|
||||
driver: bridge
|
||||
```
|
||||
|
||||
Open `http://your-server:3010` — the first registered account becomes admin.
|
||||
|
||||
### 2. Deploy a Node
|
||||
|
||||
On each VPN server, download [`docker-compose.node.yml`](./docker-compose.node.yml).
|
||||
|
||||
1. In the admin panel, open **Nodes** and generate a registration code.
|
||||
2. Set `CORE_URL` and `REGISTRATION_CODE` in the file.
|
||||
3. Run:
|
||||
Run:
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.node.yml up -d
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
The node registers with Core automatically on first start. After that, remove the `REGISTRATION_CODE` line.
|
||||
Open `http://your-server:3010`.
|
||||
|
||||
## Documentation
|
||||
### 2. Create the First Admin
|
||||
|
||||
- [Core](./core.md) — configuration and API reference
|
||||
- [Node](./node.md) — setup and registration
|
||||
- [Panel](./panel.md) — features overview
|
||||
Register the first user in the panel. Promote or seed an admin according to your deployment policy before exposing the system publicly.
|
||||
|
||||
### 3. Deploy a Node
|
||||
|
||||
In the panel, open `Nodes` and generate a registration code. Then deploy a node on the VPN/proxy server:
|
||||
|
||||
```yaml
|
||||
version: '3.9'
|
||||
|
||||
services:
|
||||
node:
|
||||
image: nexuma/node:latest
|
||||
container_name: nexuma-node
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
PORT: 3001
|
||||
CORE_URL: https://core.example.com
|
||||
REGISTRATION_CODE: paste-one-time-code-here
|
||||
HEARTBEAT_INTERVAL_SEC: 30
|
||||
volumes:
|
||||
- node_data:/var/lib/vpnnode
|
||||
ports:
|
||||
- "3001:3001"
|
||||
cap_add:
|
||||
- NET_ADMIN
|
||||
|
||||
volumes:
|
||||
node_data:
|
||||
```
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
After the node registers successfully, remove `REGISTRATION_CODE` and redeploy. Keep the `node_data` volume; it contains the persistent node auth key and local service state.
|
||||
|
||||
## Documentation Index
|
||||
|
||||
- [Core](./core.md) - control API, environment, Docker, public/user/admin API, and node-private API overview.
|
||||
- [Panel](./panel.md) - operator UI, self-service UI, routes, environment, Docker, and API behavior.
|
||||
- [Node](./node.md) - node agent setup, registration, environment, Docker, local endpoints, and operations.
|
||||
- [Core API routes](./core-routes.md) - detailed Core route table.
|
||||
- [Core private node routes](./core-private-routes.md) - node-to-Core private API contract.
|
||||
|
||||
## Security Checklist
|
||||
|
||||
- Replace all example secrets before production.
|
||||
- Use HTTPS for public panel and Core endpoints.
|
||||
- Restrict Core API exposure with firewall or reverse-proxy rules.
|
||||
- Restrict node agent ports to trusted networks.
|
||||
- Remove one-time node registration codes after successful registration.
|
||||
- Rotate node auth keys when a node is rebuilt or compromised.
|
||||
- Keep database and Redis inaccessible from the public internet.
|
||||
|
||||
Reference in New Issue
Block a user