esef/ReVoltVPN
1
0 Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases 9 Wiki Activity

docs: update SERVER_DEPLOYMENT.md for V2 domain-free architecture

Browse Source
This commit is contained in:
esefxdz committed 2026-08-02 15:38:42 +03:00
1 parent 4fde4a9217
commit 2d0628c5bb
1 file changed
+474
Download Patch File Download Diff File Expand all files Collapse all files
SERVER_DEPLOYMENT.md
+474
View File
@@ -0,0 +1,474 @@
# ReVoltVPN — Server Deployment Guide v7.0 (XHTTP + Reality + Domain-Free)
> **Last verified:** 2026-08-02 against live Xray docs at `https://xtls.github.io/en/`
> **Transport:** XHTTP (H2 stream-up) + Reality — NOT TCP, NOT XTLS-Vision
> **Spoof target:** `www.github.com` (single site, Cloudflare-backed)
> **Client:** Domain-free — API routed through tunnel, no domain in APK. See `DOCUMENTATION-ARCHITECTURE-V2.md`.
---
## Connection Flow — End to End
### Step 0: Bootstrap (V2 — domain-free)
Before the normal session flow, the app connects with a hardcoded Reality config
bundled in the APK (`bootstrapVlessUrl`). This bootstrap client is permanently
defined in `xray_config_reality.json` with `email: "bootstrap"`. Xray routing
restricts it to `10.254.254.0/24` — only the internal API, zero internet access.
```
App → bootstrap tunnel (Reality, github.com SNI) → polls 10.254.254.1:5000
↓
Xray "api" outbound
(redirect: 127.0.0.1:5000)
↓
Flask Hivemind
```
The app fetches the real per-session VLESS URL through the bootstrap tunnel,
disconnects, then reconnects with the real config. From now on, ALL API calls
(health, sync, stop) go through `10.254.254.1:5000` inside the tunnel.
**Phone never makes a connection to any domain.**
### Step 1: Client taps Connect
```
App → AdMob SSV → server creates VLESS UUID → app bootstraps → polls inside tunnel
### Step 2: Server returns session config
The `/session/status` response (from `hivemind/api.py`):
```json
{
"active": true,
"vless_uuid": "550e8400-e29b-41d4-a716-446655440000",
"vless_ip": "204.168.246.88",
"vless_port": 8443,
"reality_pbk": "fHyNQm1UbaFD3wRQn4AAx5SdVzDCzlxm8G4xprpWymI=",
"reality_sid": "abc123",
"reality_sni": "www.github.com",
"reality_fp": "chrome",
"xhttp_path": "/revolt",
"expires_in_seconds": 3540,
"nonce": "1234567890-1716480000",
"is_throttled": false
}
```
Every Reality parameter comes from the server — client has no hardcoded SNI or path.
### Step 3: Client builds VLESS URL
From these response fields, `hivemind_service.dart` builds:
```
vless://[email protected]:8443
?security=reality
&type=xhttp
&path=%2Frevolt
&pbk=fHyNQm1UbaFD3wRQn4AAx5SdVzDCzlxm8G4xprpWymI%3D
&sni=www.github.com
&sid=abc123
&fp=chrome
#ReVoltVPN
```
**Every parameter verified against live docs:**
| Parameter | Live doc source | Required? | Value |
|-----------|----------------|-----------|-------|
| `security=reality` | Reality docs: *"REALITY can only be used together with RAW, XHTTP, and gRPC"* | Yes | `reality` |
| `type=xhttp` | XHTTP docs: transport name | Yes | `xhttp` |
| `path=/revolt` | XHTTP docs: *"只需填 path，其它不填即可"* | Yes | server-defined |
| `pbk=...` | Reality docs: *"password: string — Required. The public key corresponding to the server private key."* | Yes | from `xray x25519` |
| `sni=...` | Reality docs: *"serverName: string — One of the server-side serverNames."* | Yes | from `REALITY_SNI_POOL` |
| `sid=...` | Reality docs: *"shortId: string — One of the server-side shortIds."* | Yes | `abc123` |
| `fp=chrome` | Reality docs: *"fingerprint: string — One of chrome, firefox, safari, random..."* | Yes | `chrome` |
| `host=` | XHTTP docs: *"建议没事别设"* (don't set unless needed) | No | intentionally omitted |
| `flow=` | VLESS docs: *"XTLS only available: TCP+TLS/REALITY"* (NOT XHTTP) | No | intentionally omitted |
### Step 4: flutter_vless generates Xray client config
`flutter_vless` 1.1.4 parses the VLESS URL and produces the equivalent of:
```json
{
"outbounds": [{
"protocol": "vless",
"settings": {
"vnext": [{
"address": "204.168.246.88",
"port": 8443,
"users": [{
"id": "550e8400-e29b-41d4-a716-446655440000",
"encryption": "none",
"flow": ""
}]
}]
},
"streamSettings": {
"network": "xhttp",
"security": "reality",
"xhttpSettings": {
"path": "/revolt"
},
"realitySettings": {
"serverName": "www.github.com",
"fingerprint": "chrome",
"publicKey": "fHyNQm1UbaFD3wRQn4AAx5SdVzDCzlxm8G4xprpWymI=",
"shortId": "abc123",
"spiderX": ""
}
}
}]
}
```
### Step 5: TLS handshake (Reality)
```
Client Server (Xray)
| |
|── ClientHello ────────────────────→|
| SNI: www.github.com |
| ALPN: h2 (H2 default w/ Reality) |
| random session ID |
| |
|←── ServerHello ────────────────────|
| Certificate: github.com's REAL |
| cert (fetched from |
| www.github.com:443 by Xray) |
| Signed with Reality privateKey |
| |
|── auth: pbk + shortId ───────────→|
| (embedded in TLS extension) |
| |
|←── TLS 1.3 handshake complete ────|
```
To any DPI box, this looks exactly like a browser connecting to GitHub.
### Step 6: HTTP/2 + VLESS inside the TLS tunnel
```
Inside the TLS tunnel:
┌─────────────────────────────────┐
│ HTTP/2 connection │
│ :method: POST │
│ :path: /revolt │ ← XHTTP path matching
│ :authority: www.github.com │ ← Host header (SNI fallback)
│ │
│ ┌───────────────────────────┐ │
│ │ VLESS payload │ │
│ │ UUID auth: ✓ │ │
│ │ Actual VPN traffic │ │
│ └───────────────────────────┘ │
└─────────────────────────────────┘
```
### Step 7: Xray routes traffic
```
Phone → Xray Reality (8443)
│
├─ dest: 10.254.254.0/24 → api outbound (redirect → Flask 127.0.0.1:5000)
├─ user: bootstrap, other dest → block (blackhole)
├─ port: 25,465,587 → block (SMTP)
├─ port: 135-139,445 → block (NetBIOS)
├─ port: 1900 → block (SSDP)
└─ default → direct (freedom → internet)
```
---
## Will it work? — Answer
**Yes, if these 5 things are true on the server:**
1. ✅ `xray_config_reality.json` deployed to `/usr/local/etc/xray/config.json` with the real private key
2. ✅ `hivemind/config.py` has the matching public key in `REALITY_PUBLIC_KEY`
3. ✅ Bootstrap UUID generated (`xray uuid`) and placed in BOTH `xray_config_reality.json` AND `app_config.dart`
4. ✅ Xray restarted after config deploy
5. ✅ Firewall allows inbound 8443 (and 8444 for throttled)
**The config is internally consistent.** Every parameter flows from a single source:
- `config.py` → API → client → `flutter_vless` → Xray client config
- `config.json` → Xray server inbound
If those match (and they do in this repo), the tunnel will establish.
---
## Server Setup (clean deploy)
### 1. Install Xray
```bash
bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install
```
### 2. Generate Reality keypair
```bash
xray x25519
# Output:
# Private key: <44-char base64> ← goes in xray_config_reality.json
# Public key: <44-char base64> ← goes in hivemind/config.py
```
### 3. Generate bootstrap UUID
```bash
xray uuid
# Output: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
```
Put this UUID in TWO places:
1. `xray_config_reality.json` — replace `BOOTSTRAP-UUID-REPLACE-ME` in the bootstrap client's `"id"` field
2. `lib/logic/app_config.dart` — replace `BOOTSTRAP-UUID-GOES-HERE` in `bootstrapUuid`
### 4. Deploy Xray config
Copy `xray_config_reality.json` from this repo → `/usr/local/etc/xray/config.json` on the server.
Replace the private key with the one you just generated:
```json
"privateKey": "YOUR_GENERATED_PRIVATE_KEY"
```
```bash
chmod 600 /usr/local/etc/xray/config.json
systemctl restart xray
systemctl status xray # verify: active (running)
```
### 5. Verify Xray is listening
```bash
ss -tlnp | grep -E '8443|8444'
# Should show:
# LISTEN 0.0.0.0:8443 (Xray — full speed)
# LISTEN 0.0.0.0:8444 (Xray — throttled)
```
### 6. Verify the spoof cert is reachable
```bash
xray tls ping www.github.com:443
# Should show: certificate size > 3500 bytes (good for Reality)
```
### 7. Deploy Python Hivemind
Upload to `/root/`:
```
server_hivemind_5_0.py ← entry point
hivemind/ ← package (8 files)
├── config.py ← EDIT: public key, server IP
├── sessions.py
├── xray.py
├── admob.py
├── management.py
├── api.py
├── main.py
└── __init__.py
```
### 8. Edit hivemind/config.py
```python
REALITY_PUBLIC_KEY = "YOUR_GENERATED_PUBLIC_KEY" # from xray x25519
VLESS_SERVER_IP = "YOUR_SERVER_IP" # Hetzner/VPS IP
REALITY_SNI_POOL = ["www.github.com"] # spoof target
VLESS_XHTTP_PATH = "/revolt" # must match config.json
```
### 9. Install Python dependencies
```bash
pip install flask requests
```
### 10. Create systemd unit
`/etc/systemd/system/hivemind.service`:
```ini
[Unit]
Description=ReVoltVPN Hivemind
After=network.target xray.service
[Service]
Type=simple
User=root
WorkingDirectory=/root
ExecStart=/usr/bin/python3 -m gunicorn -w 1 -b 127.0.0.1:5000 hivemind.main:app
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
```
```bash
systemctl daemon-reload
systemctl enable --now hivemind
systemctl status hivemind
```
### 11. Firewall
```bash
# Only open what's needed
ufw allow 443/tcp # nginx HTTPS (API)
ufw allow 8443/tcp # Xray Reality (full speed)
ufw allow 8444/tcp # Xray Reality (throttled)
ufw allow 80/tcp # certbot HTTP challenge
ufw enable
# Keep these internal-only
# 5000 — Flask (localhost only, via nginx)
# 10085 — Xray API (localhost only)
```
### 12. nginx (AdMob SSV + website)
nginx now serves only two purposes — the app itself never connects to it:
- AdMob SSV callbacks (`/api/admob/callback`) — Google → your server, not phone → server
- Branding website at the root — user's browser, manually
Xray handles all app-to-server traffic through the Reality tunnel.
`/etc/nginx/sites-available/revolt`:
```nginx
server {
listen 443 ssl http2;
server_name YOUR_DOMAIN;
ssl_certificate /etc/letsencrypt/live/YOUR_DOMAIN/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/YOUR_DOMAIN/privkey.pem;
location /api/ {
proxy_pass http://127.0.0.1:5000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
location / {
root /var/www/revolt;
index index.html;
}
}
server {
listen 80;
server_name YOUR_DOMAIN;
return 301 https://$host$request_uri;
}
```
### 13. certbot (Let's Encrypt)
```bash
apt install certbot python3-certbot-nginx
certbot --nginx -d YOUR_DOMAIN
```
---
## Smoke Test
### From the server:
```bash
# 1. Is Xray running?
systemctl status xray
# 2. Is Hivemind running?
systemctl status hivemind
# 3. Can Hivemind reach Xray API?
curl http://127.0.0.1:10085/stats/query -d '{"pattern":"","reset":false}'
# 4. Is Flask alive internally?
curl http://127.0.0.1:5000/api/health
# → {"ok": true}
# 5. Does the API route through Xray work? (simulate tunnel → 10.254.254.1 → Flask)
curl http://10.254.254.1:5000/api/health
# → should fail (only reachable through Xray tunnel, not directly)
# 6. Does the spoof target work?
xray tls ping www.github.com:443
```
### From a client (after building the Flutter app):
The app no longer hits any domain. All API calls go through the tunnel.
Verify by building and running the app in debug mode (`ADMOB_BYPASS=True`).
```bash
# 7. Tap Connect → app bootstraps → polls inside tunnel → reconnects → timer starts
# 8. Health dot turns green (API reachable through tunnel)
# 9. Session timer syncs (5 second countdown updates)
# 10. Tap Disconnect → timer stops → cleanup POST goes through tunnel → tunnel drops
```
### Full integration test:
```
11. Trigger 4 GB → timer shows port-swap → reconnects through bootstrap → speed reduced
12. Support ad top-up → +30 min +2 GB → timer updates without reconnect
13. Kill app while connected → reopen → timer resumes (startup restoration)
```
---
## Troubleshooting
| Symptom | Check |
|---------|-------|
| App says "Connecting..." forever | Server firewall blocking 8443? `ufw status` |
| App connects but no internet | Xray routing broken? Check `journalctl -u xray -f` |
| `/session/status` returns 500 | Hivemind crashed? `systemctl status hivemind` |
| `xray tls ping` fails | Server can't reach GitHub? DNS? IPv6? |
| Stats show 0 bytes | Users missing `email` field? Check `xray.py:add_client()` |
| Tunnel starts but immediately dies | `providerBundleIdentifier` mismatch? Must be `com.paladinvpn.app` |
| "Session not activated" in app | ADMOB_BYPASS not True? Or SSV callback not firing |
| App stuck on "Establishing secure channel…" | Bootstrap UUID mismatch between APK and xray_config? |
| Health dot gray after tunnel connects | `api` outbound not working? Check Xray routing rules |
| Bootstrap tunnel starts but no config | Hivemind not running on 127.0.0.1:5000? `systemctl status hivemind` |
---
## Changing the spoof target
If you ever want to switch from GitHub to another site:
1. Edit `REALITY_SNI_POOL` in `hivemind/config.py`
2. Edit `serverNames` in **both** inbounds in `config.json` (add site + root domain)
3. Update `dest` in `config.json` to the new target
4. Verify: `xray tls ping NEW_TARGET:443` — cert must be > 3500 bytes
5. `systemctl restart xray`
---
## Differences from old TCP/Vision setup
| What | Old (SERVER_SETUP.md) | New (this doc) |
|------|----------------------|----------------|
| Transport | `tcp` | `xhttp` |
| Flow | `xtls-rprx-vision` | (none — XTLS doesn't work with XHTTP) |
| Spoof target | `www.microsoft.com` | `www.github.com` |
| Path | (none — TCP) | `/revolt` (XHTTP path) |
| Rate limiting | `uplinkOnly: 187500` (wrong) | `uplinkOnly: 2` (correct seconds), real cap via `tc` |
| shortIds | 3 entries | 1 entry matching `REALITY_SHORT_ID` |
| Fallback limits | Not present | Intentionally omitted (fingerprint risk per live docs) |
| `xhttp_path` in API | Not present | Server sends path, client reads it |
| `providerBundleIdentifier` | `com.revoltvpn.app` | `com.paladinvpn.app` |
| API transport | HTTPS to domain | Tunnel-internal to `10.254.254.1:5000` |
| Domain in APK | `getrevolt.app` | **None** — zero domain strings |
| Bootstrap | None (external API polling) | Hardcoded Reality config, tunnel-only API fetch |
| Xray outbounds | `direct` + `block` | `direct` + `block` + `api` (redirect → Flask) |