release: v1.2.3

Two new feature areas + hardening + install/UX polish.

New: Servers (managed VPS inventory)
  Separate page from Nodes — tracks the remote VPS hosts that may
  carry one or more proxy outbounds, with their SSH connection,
  provider/region metadata, tags, and a Deployments tab listing which
  protocols/ports are currently set up on each box. Async-SSH probe
  via asyncssh==2.18.0. Optional manual provisioning scripts (Caddy +
  forwardproxy for naive, xray, SSH hardening) over the same SSH link.
  3 new alembic migrations: 008 (server table), 009 (deployments), 010
  (geo URL defaults).

New: full-fidelity JSON Export/Import for Nodes and Servers
  Versioned bundle envelope ({kind, version, exported_at,
  pitun_version, count, items}). Append (default) or replace mode;
  dedup by natural keys (Nodes: protocol+address+port+uuid; Servers:
  name+host+port). Server export defaults to no-secrets, with an
  opt-in checkbox to include passwords/keys for migrations between
  trusted hosts. Distinct from URI/subscription import which only
  carries a single node.

NodeCircle pre-ping with retry + Failover<->Circle integration
  Before switching the active outbound to a candidate, the scheduler
  now TCP-probes it (SO_MARK=0xFF to bypass TPROXY) with a single
  retry to absorb transient SYN drops. Disabled or removed nodes are
  skipped automatically; if every candidate fails, the rotation
  aborts and the active node stays put. Each circle gets its own
  asyncio.Lock and a 20s hard deadline so scheduler ticks and
  manual rotate-now never race.

  When the active node fails its health check repeatedly AND it
  belongs to an enabled circle, the failover handler delegates
  recovery to circle_scheduler.rotate_circle() instead of walking the
  fallback list — reusing the pre-ping logic to skip dead siblings.
  If no circle owns the node (or all siblings are dead), Tier-2
  fallback is the existing list-based path. New "Auto-failover" toggle
  on the NodeCircles page is the master switch.

Comprehensive geo profiles
  Three switchable upstream profiles for geoip.dat / geosite.dat:
  Loyalsoldier (CN-focused, largest geosite:cn coverage), runetfreedom
  (Russian-internet curated, geosite:ru-blocked + clean geosite:ru),
  v2fly (vanilla baseline). UI lets you select + Update; PiTun fetches
  into the xray asset directory and reloads.

Routing rules: comprehensive Proxy streaming preset
  Quick Add 'Proxy streaming' grew from a handful of entries to a
  curated list of 50 (Netflix, Disney+, HBO, Hulu, Spotify, YouTube
  Premium, Twitch, Steam, Epic Games, BBC iPlayer, ChatGPT/OpenAI,
  Anthropic Claude, etc.). Backend auto-prefixes bare domain entries
  with `domain:` on save so users don't have to type the prefix.

Install: autodetect LAN_CIDR + host IP from default-route interface
  install.sh now writes correct INTERFACE, LAN_CIDR, GATEWAY_IP,
  VITE_API_BASE_URL, VITE_WS_BASE_URL, and CORS_ORIGINS into the
  freshly generated .env, derived from the host's primary interface
  (python3 ipaddress for CIDR math, pure-bash bitwise fallback).
  Previously only INTERFACE was autodetected — users on subnets other
  than 192.168.1.0/24 had to edit four places by hand.

  Backend gains a parallel _detect_cidr() runtime fallback in
  GET /settings, mirroring the existing _detect_ip() behavior. Stays
  read-only (does not overwrite a deliberate manual lan_cidr in DB).

  README.md / README.ru.md / .env.example: clarified that GATEWAY_IP
  is a misnomer for the PiTun host's own LAN IP (not the home
  router's IP), and documented the new autodetect + runtime fallback.

UI polish
  - NodeCircles page InfoTips now open downward (position="bottom") to
    avoid clipping at the top of the viewport on narrow screens.
  - Knowledge Base updated: Servers, Geo profiles, JSON Export/Import,
    NodeCircle pre-ping/retry, Failover<->Circle integration, Routing
    Quick Add presets details all documented. Two new sections:
    "Servers (VPS Inventory)" and "Geo Data Profiles".

Routing rules JSON Export/Import (v2ray-style)
  Round-trip rule sets as v2ray routing JSON for backups and migrating
  curated rules between PiTun instances.

Backend versioning is now a single source of truth (APP_VERSION in
config.py); surfaced in /health, /system/status, and the OpenAPI
metadata. 284 backend tests pass. No breaking changes; 3 alembic
migrations apply automatically on first start.

Author: DaveBugg

.env.example

@@ -13,6 +13,17 @@ XRAY_GEOSITE_PATH=/usr/local/share/xray/geosite.dat
 XRAY_LOG_LEVEL=warning
 
 # Network
+#
+# Tip: when you generate this file via `install.sh`, INTERFACE,
+# LAN_CIDR, and GATEWAY_IP are autodetected from the host's
+# default-route interface — these example values are only used as a
+# fallback when autodetect fails or you copy this file by hand.
+#
+# GATEWAY_IP: misnomer kept for backward compat — this is the LAN IP
+# of the PiTun host itself (what your devices set as their default
+# gateway), NOT your home router's IP. The backend will also sync
+# the live interface IP to the database on the first `GET /settings`,
+# so even a stale value here is corrected at runtime.
 TPROXY_PORT_TCP=7893
 TPROXY_PORT_UDP=7894
 DNS_PORT=5353

.gitignore

@@ -28,6 +28,16 @@ build/
 dist/
 backend/dist/
 frontend/dist/
+
+# Maintainer-side scratch space — Claude Code uses this for throwaway
+# helpers (SSH runners, deploy tarballs, ad-hoc test scripts) during
+# interactive work. Never committed; safe to wipe between sessions.
+.claude_temp/
+
+# Internal product/business roadmap, monetization plans, decisions log.
+# Lives in the repo for convenient editing alongside code, but never
+# committed — these are private notes not suitable for the public repo.
+roadmap/
 docs/design/
 
 # Node

README.md

@@ -154,7 +154,10 @@ Frontend is a single-page React app served by nginx.
   through node #5")
 
 **Health & resilience**
-- Background liveness probe with auto-failover to a fallback node
+- Background liveness probe with two-tier auto-failover: if the failed
+  node belongs to an enabled NodeCircle, the failover handler delegates
+  recovery to the circle (which skips dead siblings via pre-ping +
+  retry); otherwise it walks a configurable fallback list
 - Speed test per node via short-lived isolated xray instance
 - Naive sidecar supervisor — auto-restarts crashed Naive containers
   with a sliding-window rate limiter
@@ -164,7 +167,9 @@ Frontend is a single-page React app served by nginx.
 **Balancing & rotation**
 - Balancer groups (xray's `leastPing` or `random` strategies)
 - Node Circles — automatically rotate the active node on a schedule,
-  seamlessly via xray's gRPC API (no dropped connections)
+  seamlessly via xray's gRPC API (no dropped connections); each
+  candidate is TCP-pinged with a single retry before switching, so
+  dead siblings are skipped without a connection blip
 
 **Subscriptions**
 - Periodic refresh from VLESS / VMess / Trojan / SS / Hysteria2 /
@@ -179,8 +184,19 @@ Frontend is a single-page React app served by nginx.
 - FakeDNS pool for sniffing-friendly geoip resolution
 - DNS query log with stats
 
+**Servers & deployments**
+- Inventory of remote VPS hosts (host, SSH credentials, tags) separate
+  from runtime nodes — async-SSH probe, deployment records track which
+  protocol/port is set up on which box, optional manual provisioning
+  scripts (Caddy + naive, xray, SSH hardening) over the same SSH link
+
 **Operations**
-- One-click GeoIP / GeoSite refresh from Loyalsoldier's dataset
+- One-click GeoIP / GeoSite refresh — three switchable upstream
+  profiles: Loyalsoldier (CN-focused community list), runetfreedom
+  (Russian-internet curated list), v2fly (vanilla baseline)
+- Full-fidelity JSON Export/Import for Nodes and Servers — versioned
+  bundle envelope, append/replace modes, optional secret redaction
+  (separate from URI/subscription import which is single-node only)
 - Built-in diagnostics page (DNS reachability, gateway, xray status,
   resource usage)
 - Streaming xray log viewer
@@ -258,10 +274,12 @@ Useful flags (after `bash -s --`):
 After the script finishes:
 - Web UI is at `http://<this-host-ip>/`, login `admin` / `password`
   (**change it on first login** via *Settings → Account*).
-- `/opt/pitun/.env` was generated with a random `SECRET_KEY` and your
-  default LAN interface autodetected. Edit it to set `LAN_CIDR` /
-  `GATEWAY_IP` matching your network, then `docker compose -f
-  /opt/pitun/docker-compose.yml restart`.
+- `/opt/pitun/.env` was generated with a random `SECRET_KEY` and the
+  network block autodetected from your default-route interface:
+  `INTERFACE`, `LAN_CIDR`, `GATEWAY_IP` (the PiTun host's own LAN IP),
+  `VITE_API_BASE_URL`, `VITE_WS_BASE_URL`, `CORS_ORIGINS`. Verify with
+  `head -30 /opt/pitun/.env` before going to production; if anything
+  looks off, edit and `docker compose -f /opt/pitun/docker-compose.yml restart`.
 
 > See [`install.sh --help`](install.sh) for the full option list.
 
@@ -282,8 +300,14 @@ cd pitun
 sudo bash scripts/setup.sh
 
 cp .env.example .env
-# Edit .env — at minimum set SECRET_KEY, INTERFACE, LAN_CIDR, GATEWAY_IP.
-# A random SECRET_KEY: openssl rand -hex 32
+# Edit .env — at minimum set SECRET_KEY, INTERFACE, LAN_CIDR,
+# GATEWAY_IP (the PiTun host's own LAN IP — what devices will use as
+# their default gateway). A random SECRET_KEY: openssl rand -hex 32
+#
+# Tip: instead of editing manually, run `sudo bash install.sh
+# --skip-host-prep` from the same checkout — it autodetects all the
+# network values from your default-route interface and writes them
+# into .env (only on first generation).
 
 docker compose up -d --build
 ```
@@ -378,8 +402,8 @@ must be set before first start, via `.env`:
 |---|---|---|
 | `SECRET_KEY` | `changeme-…` | JWT signing key — `openssl rand -hex 32` |
 | `INTERFACE` | `eth0` | LAN interface name on the host |
-| `LAN_CIDR` | `192.168.1.0/24` | Your LAN subnet |
-| `GATEWAY_IP` | `192.168.1.1` | Your home router's IP (used for `direct` traffic) |
+| `LAN_CIDR` | `192.168.1.0/24` | Your LAN subnet (autodetected by `install.sh`) |
+| `GATEWAY_IP` | `192.168.1.100` | **The PiTun host's own LAN IP** — devices set this as their default gateway. (Misnomer kept for backward compat; *not* the router's IP.) Autodetected by `install.sh`. |
 | `BACKEND_PORT` | `8000` | Backend listen port (behind nginx) |
 | `TPROXY_PORT_TCP` | `7893` | TPROXY TCP listener |
 | `DNS_PORT` | `5353` | Internal DNS forwarder port |
@@ -388,6 +412,13 @@ must be set before first start, via `.env`:
 
 Full annotated example: [`.env.example`](.env.example).
 
+> **About `GATEWAY_IP`:** the variable name predates the LAN-gateway
+> feature and refers to the PiTun host itself, not your home router.
+> If the .env value disagrees with the actual interface IP, the backend
+> auto-syncs the live IP into the database on the first `GET /settings`,
+> so the UI always shows the truth. `LAN_CIDR` has the same runtime
+> fallback as of 1.2.3.
+
 ## Development
 
 ```bash

README.ru.md

@@ -152,7 +152,10 @@ xray-core, набором правил nftables и SQLite-базой со все
   через ноду #5»)
 
 **Здоровье и устойчивость**
-- Фоновая проверка живости с автоматическим failover на резервную ноду
+- Фоновая проверка живости с двухуровневым auto-failover: если упавшая
+  нода входит в активный NodeCircle — failover делегирует
+  восстановление кругу (он пропускает мёртвых соседей через pre-ping +
+  retry); иначе идёт по настраиваемому списку fallback-нод
 - Speed test для каждой ноды через короткоживущий изолированный xray
 - Supervisor для Naive sidecars — авторестарт упавших контейнеров с
   rate-limiter (sliding window)
@@ -162,7 +165,9 @@ xray-core, набором правил nftables и SQLite-базой со все
 **Балансировка и ротация**
 - Группы балансировки (стратегии xray `leastPing` / `random`)
 - Node Circles — автоматическая ротация активной ноды по расписанию,
-  бесшовно через xray gRPC API (соединения не рвутся)
+  бесшовно через xray gRPC API (соединения не рвутся); каждый
+  кандидат проверяется TCP-пингом с одним повтором перед
+  переключением — мёртвые соседи пропускаются без обрыва
 
 **Подписки**
 - Периодическое обновление с VLESS / VMess / Trojan / SS / Hysteria2 /
@@ -178,8 +183,21 @@ xray-core, набором правил nftables и SQLite-базой со все
 - FakeDNS-пул для sniffing-friendly geoip-резолва
 - Лог DNS-запросов со статистикой
 
+**Серверы и развёртывания**
+- Инвентарь удалённых VPS (host, SSH-доступы, теги) отдельно от runtime-
+  нод — async-SSH probe, записи о развёртываниях помнят какой
+  протокол/порт настроен на какой машине, опционально — manual
+  provisioning скрипты (Caddy + naive, xray, харднинг SSH) по тому же
+  SSH-каналу
+
 **Эксплуатация**
-- One-click обновление GeoIP / GeoSite из dataset Loyalsoldier
+- One-click обновление GeoIP / GeoSite — три переключаемых upstream-
+  профиля: Loyalsoldier (CN-ориентированный community-список),
+  runetfreedom (курируемый список для рунета), v2fly (vanilla baseline)
+- Полноформатный JSON Export/Import для Nodes и Servers — версионный
+  конверт, режимы append/replace, опциональная редактирование секретов
+  (отдельно от URI/subscription импорта, который работает только на
+  одну ноду)
 - Встроенная страница диагностики (DNS, шлюз, статус xray, ресурсы)
 - Стриминг логов xray
 - Многоязычный UI (English / Русский)
@@ -257,8 +275,11 @@ curl -fsSL https://raw.githubusercontent.com/DaveBugg/PiTun/master/install.sh |
 - Web UI на `http://<ip-хоста>/`, логин `admin` / `password`
   (**смени при первом входе** через *Settings → Account*).
 - `/opt/pitun/.env` сгенерирован со случайным `SECRET_KEY` и
-  авто-детектом LAN-интерфейса. Отредактируй чтобы выставить `LAN_CIDR`
-  / `GATEWAY_IP` под свою сеть, потом `docker compose -f
+  авто-детектом сетевого блока с интерфейса дефолтного маршрута:
+  `INTERFACE`, `LAN_CIDR`, `GATEWAY_IP` (это LAN-IP самого PiTun, не
+  роутера), `VITE_API_BASE_URL`, `VITE_WS_BASE_URL`, `CORS_ORIGINS`.
+  Проверь через `head -30 /opt/pitun/.env` перед боевым запуском; если
+  что-то не так — отредактируй и `docker compose -f
   /opt/pitun/docker-compose.yml restart`.
 
 > Полный список опций — [`install.sh --help`](install.sh).
@@ -278,8 +299,15 @@ cd pitun
 sudo bash scripts/setup.sh
 
 cp .env.example .env
-# Отредактируйте .env — минимум: SECRET_KEY, INTERFACE, LAN_CIDR, GATEWAY_IP.
-# Случайный SECRET_KEY: openssl rand -hex 32
+# Отредактируйте .env — минимум: SECRET_KEY, INTERFACE, LAN_CIDR,
+# GATEWAY_IP (это LAN-IP самого PiTun — то, что устройства будут
+# использовать как default gateway). Случайный SECRET_KEY:
+# openssl rand -hex 32
+#
+# Совет: вместо ручной правки можно запустить `sudo bash install.sh
+# --skip-host-prep` из этого же checkout — оно автодетектит все
+# сетевые значения с дефолтного интерфейса и пишет в .env (только при
+# первой генерации).
 
 docker compose up -d --build
 ```
@@ -373,8 +401,8 @@ docker compose up -d
 |---|---|---|
 | `SECRET_KEY` | `changeme-…` | Ключ подписи JWT — `openssl rand -hex 32` |
 | `INTERFACE` | `eth0` | Имя LAN-интерфейса на хосте |
-| `LAN_CIDR` | `192.168.1.0/24` | Ваша LAN-подсеть |
-| `GATEWAY_IP` | `192.168.1.1` | IP домашнего роутера (для `direct` трафика) |
+| `LAN_CIDR` | `192.168.1.0/24` | Ваша LAN-подсеть (автодетектится `install.sh`) |
+| `GATEWAY_IP` | `192.168.1.100` | **LAN-IP самого PiTun** — устройства задают это как default gateway. (Имя оставлено для обратной совместимости; это *не* IP роутера.) Автодетектится `install.sh`. |
 | `BACKEND_PORT` | `8000` | Порт бэкенда (за nginx) |
 | `TPROXY_PORT_TCP` | `7893` | TCP-листенер TPROXY |
 | `DNS_PORT` | `5353` | Внутренний DNS-форвардер |
@@ -383,6 +411,13 @@ docker compose up -d
 
 Полный аннотированный пример: [`.env.example`](.env.example).
 
+> **О `GATEWAY_IP`:** имя переменной осталось с тех времён когда LAN-
+> gateway фичи ещё не было, и относится к самому PiTun-хосту, а не к
+> роутеру. Если в .env лежит несовпадающий с реальным IP интерфейса —
+> бэкенд автоматически синкнет живой IP в БД при первом `GET /settings`,
+> так что в UI всегда будет правда. У `LAN_CIDR` такой же runtime-
+> fallback с версии 1.2.3.
+
 ## Разработка
 
 ```bash

backend/alembic/versions/008_add_server_table.py

@@ -0,0 +1,66 @@
+"""Add server table + node.server_id link.
+
+Introduces the Servers feature: a catalogue of SSH-reachable VPS instances
+that the user manages from PiTun. Each server can be referenced by zero or
+more nodes (1:N) — the link is purely informational and survives an empty
+delete via ON DELETE SET NULL.
+
+Plain-text credential storage is intentional and matches existing Node
+password storage. Threat model is documented in SECURITY.md (LAN-only
+deployment, do not expose to public internet).
+
+Revision ID: 008
+Revises: 007
+Create Date: 2026-05-02
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = "008"
+down_revision: Union[str, None] = "007"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "server",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("description", sa.String(), nullable=True),
+        sa.Column("host", sa.String(), nullable=False),
+        sa.Column("port", sa.Integer(), nullable=False, server_default="22"),
+        sa.Column("user", sa.String(), nullable=False, server_default="root"),
+        sa.Column("auth_type", sa.String(), nullable=False, server_default="password"),
+        sa.Column("password", sa.String(), nullable=True),
+        sa.Column("private_key", sa.Text(), nullable=True),
+        sa.Column("passphrase", sa.String(), nullable=True),
+        sa.Column("status", sa.String(), nullable=False, server_default="unknown"),
+        sa.Column("last_check", sa.DateTime(), nullable=True),
+        sa.Column("last_check_error", sa.String(), nullable=True),
+        sa.Column("latency_ms", sa.Integer(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+    # Add server_id FK to node table. Use batch_alter_table so SQLite (no
+    # native ALTER) gets the table-rename + recreate dance for free.
+    with op.batch_alter_table("node") as batch:
+        batch.add_column(sa.Column("server_id", sa.Integer(), nullable=True))
+        batch.create_foreign_key(
+            "fk_node_server_id",
+            "server",
+            ["server_id"],
+            ["id"],
+            ondelete="SET NULL",
+        )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("node") as batch:
+        batch.drop_constraint("fk_node_server_id", type_="foreignkey")
+        batch.drop_column("server_id")
+    op.drop_table("server")

backend/alembic/versions/009_add_server_deployment.py

@@ -0,0 +1,61 @@
+"""Add server_deployment table.
+
+Persists "what credentials did the user pick last time they generated a
+NaiveProxy install script for this server", so:
+  - Re-opening the script generator pre-fills with last values
+  - The auto-generated naive password isn't lost when the modal closes
+  - One-click "Create Node from this deployment" pre-populates a Node
+    row with the right host / user / password
+
+Unique on (server_id, protocol) — one deployment plan per protocol per
+server. Re-saving updates the existing row.
+
+Revision ID: 009
+Revises: 008
+Create Date: 2026-05-06
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = "009"
+down_revision: Union[str, None] = "008"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "serverdeployment",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("server_id", sa.Integer(), nullable=False),
+        sa.Column("protocol", sa.String(), nullable=False),
+        sa.Column("config_json", sa.Text(), nullable=False),
+        sa.Column("status", sa.String(), nullable=False, server_default="configured"),
+        sa.Column("last_node_id", sa.Integer(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["server_id"], ["server.id"],
+            name="fk_deployment_server_id",
+            ondelete="CASCADE",  # delete server → drop its deployments
+        ),
+        sa.ForeignKeyConstraint(
+            ["last_node_id"], ["node.id"],
+            name="fk_deployment_last_node_id",
+            ondelete="SET NULL",  # delete node → keep deployment, drop link
+        ),
+        sa.UniqueConstraint("server_id", "protocol", name="uq_server_protocol"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "ix_serverdeployment_server_id",
+        "serverdeployment",
+        ["server_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_serverdeployment_server_id", table_name="serverdeployment")
+    op.drop_table("serverdeployment")