mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-07-09 14:16:07 +00:00
Sanaei
6214ff4edc
* fix(mtproto): split the mtg fingerprint into structural and secrets parts A reordered clients array in the stored settings used to read as a config change because the fingerprint concatenated secrets in array order, and one opaque fingerprint could not tell a restart-worthy change (bind address, fronting, throttle) from a secret-set change a reload-capable mtg can absorb in place. Sort the secret pairs so order stops mattering, and split the value so the upcoming hot-reload path can decide between keeping, reloading, and restarting the process. * fix(mtproto): stop restarting mtg on every inbound edit Saving an mtproto inbound tore down and respawned its mtg sidecar even when nothing material changed, dropping every live Telegram connection: the update path pushed DelInbound+AddInbound, and Remove deletes the manager's map entry, so Ensure's fingerprint no-op gate could never fire. Route mtproto updates through a single Ensure call so an edit that leaves the generated TOML alone keeps the process, and only real config changes restart it. Capturing the pre-edit protocol also fixes a latent leak: changing an inbound's protocol away from mtproto never stopped the sidecar, because the snapshot handed to the runtime already carried the new protocol and the removal took the xray branch, leaving an orphaned mtg holding the port. An mtproto push failure no longer requests an xray restart - xray cannot fix the sidecar, and the 10s reconcile job self-heals it. The regression test fakes mtg by re-executing the test binary, counting spawns through a pid file: an unchanged save and a remark-only edit must keep the process, a re-keyed secret must restart it. * fix(mtproto): exclude depleted clients from the reconcile job to match the sync push The 10s reconcile job derived mtg secret sets from raw inbound settings while the interactive push filtered clients through buildRuntimeInboundForAPI, which drops client_traffics-disabled (depleted or expired) clients. The two paths therefore disagreed on the fingerprint - each disagreement one needless mtg restart dropping live connections - and worse, the job kept serving depleted clients' secrets indefinitely, so running out of traffic never actually cut an mtproto client's access. DesiredMtprotoInstances now builds the job's desired state with the same depletion overlay the push uses (one bulk client_traffics query), drops inbounds whose every secret is filtered away so their sidecar stops, and AddInbound pushes the filtered payload too so an imported inbound carrying disabled stats does not seed a fingerprint the next reconcile disagrees with. * feat(mtproto): hot-reload mtg secrets in place instead of restarting A client add, removal, re-key, or enable-toggle changes only the [secrets] section of the generated config, yet the panel could apply it only by killing and respawning the mtg sidecar, dropping every Telegram connection on that inbound. Split the ensure decision three ways: an identical config is a no-op, a secrets-only change rewrites the TOML on the same api port and asks mtg to hot-swap it via POST /reload, and a structural change (or a failed reload) falls back to the full stop-and-start. The reload endpoint is served by the mhsanaei/mtg-multi fork; against an older binary the POST 404s and the manager restarts exactly as before, so panel and binary upgrades stay order-independent. * feat(mtproto): apply single-client edits to the sidecar immediately Client CRUD on an mtproto inbound was a runtime no-op, so an add, delete, re-key, or enable-toggle only reached mtg on the next 10s reconcile. With the sidecar now able to hot-reload, push the change straight after the edit commits: applyLocalMtproto rebuilds the inbound's filtered client set and re-applies it, so a new client works within a moment (and, on a reload-capable binary, without disturbing the others) and deleting the last client stops the process. The three interactive single-client paths (add, update, delete) call it; bulk operations still ride the reconcile job, which converges to the same state. * chore(mtproto): pin mtg-multi to the mhsanaei fork v1.13.3 The reload endpoint the panel now uses lives in the mhsanaei/mtg-multi fork, so point the source-build pin (DockerInit.sh + both release.yml matrices) at it and bump to v1.13.3. The install still produces the same mtg-multi binary name, so the mtg-<os>-<arch> rename and everything downstream are unchanged. Docs and the package comment note the hot-reload path and its restart fallback. * feat(mtproto): apply live secret updates via the management API and add ad-tag Two capabilities the mhsanaei/mtg-multi v1.13.3 fork exposes are now surfaced by the sidecar manager. Live updates go through PUT /secrets on the fork's management API instead of POST /reload: the panel already holds the whole desired set per inbound, so it sends secrets and the advertising tag as one JSON call that mtg applies atomically, keeping every unchanged connection and closing only removed or re-keyed ones. The config file is still written first so a restart or crash recovery reproduces the state, and any non-200 (an older binary, a refused connection) still falls back to a full restart. Per-inbound ad-tag adds an optional 32-hex Telegram advertising tag plus public-ipv4/public-ipv6 overrides. The ad-tag rides the reloadable secrets fingerprint, so changing it hot-applies without dropping connections; the public IPs are proxy-construction parameters and sit in the structural fingerprint, so a change there restarts the process. Empty public IPs are omitted so mtg auto-detects the reachable address. * feat(inbounds): expose the mtproto ad-tag and public IP in the inbound form Adds an Ad-tag field (validated as 32 hex characters) plus optional Public IPv4 and Public IPv6 overrides to the MTProto inbound form, backed by the same-named settings the sidecar writes into the mtg config. The public IPs are optional — left blank, mtg auto-detects the reachable address the ad-tag middle proxy needs. English strings are added to every locale; the non-English ones carry the English text until translated and fall back to it meanwhile. * ci(mtproto): install mtg-multi from prebuilt release binaries The fork now publishes release archives for every platform we package, so download and unpack the matching mtg-multi-<ver>-<os>-<arch> binary instead of compiling it from source with go install. Faster builds and no toolchain step, and the archive's platform labels line up with our matrix; the produced mtg-<os>-<arch> filenames are unchanged. * i18n(mtproto): localize the ad-tag and public IP strings The six mtgAdTag*/mtgPublicIp* keys shipped with English text in every locale as a placeholder. Translate them into the twelve non-English locales (Arabic, Spanish, Persian, Indonesian, Japanese, Portuguese-BR, Russian, Turkish, Ukrainian, Vietnamese, and Simplified/Traditional Chinese); en-US is unchanged. * retired goreportcard.com
586 lines
40 KiB
Markdown
586 lines
40 KiB
Markdown
# 3x-ui — Architecture & Code Map
|
|
|
|
> Navigation map for contributors and AI coding agents (referenced from `CLAUDE.md`).
|
|
> Goal: jump to the right file in one hop instead of grepping the whole tree.
|
|
> Tracks the `main` branch — paths reflect the latest changes, so verify against the live
|
|
> tree rather than a pinned release (Go module `github.com/mhsanaei/3x-ui/v3`).
|
|
>
|
|
> **How to use this file:** read "Mental model" + "Request lifecycle" first, then
|
|
> use the **Symptom → File index** to locate work. Respect the **Layering rules**
|
|
> when adding code. Verify with the commands in **Build / Test / Lint**.
|
|
|
|
---
|
|
|
|
## 1. Mental model (the 30-second version)
|
|
|
|
3x-ui is a **web control panel for [Xray-core](https://github.com/XTLS/Xray-core)**. The Go
|
|
backend is the source of truth: it stores inbounds/clients/settings in a DB, renders an
|
|
Xray JSON config from that state, supervises the Xray child process, and exposes a REST +
|
|
WebSocket API. A React SPA (built by Vite, embedded into the Go binary) is the UI. A second,
|
|
separate HTTP server serves **subscription links** to end users.
|
|
|
|
The panel supervises **two managed child processes**: Xray-core itself and — when MTProto
|
|
inbounds exist — the `mtg-multi` Telegram-proxy binary (`github.com/mhsanaei/mtg-multi`, a
|
|
multi-secret fork built from source; `internal/mtproto/`). One process per inbound serves
|
|
every attached client's FakeTLS secret through the fork's `[secrets]` section. A client edit
|
|
is hot-applied via the fork's `POST /reload` endpoint (connections survive), with a process
|
|
restart as the fallback on older binaries.
|
|
|
|
Servers and processes, all launched from `main.go`:
|
|
|
|
| Server / process | Package | Purpose | Default port |
|
|
|---|---|---|---|
|
|
| **Panel** | `internal/web` | Admin REST/WS API + serves the embedded SPA | 2053 |
|
|
| **Subscription** | `internal/sub` | Public endpoint that hands out client configs (raw / JSON / Clash) | `subPort` setting |
|
|
| **Xray-core** | supervised via `internal/xray` | The actual proxy engine; a child process, not Go code | `inbounds[].port` |
|
|
| **mtg-multi** | supervised via `internal/mtproto` | MTProto proxy child process for MTProto inbounds (multi-secret) | per inbound |
|
|
|
|
Two key ideas that explain most of the complexity:
|
|
|
|
1. **The DB → Xray config pipeline.** Inbounds/clients live in the DB. On every change the
|
|
backend regenerates the Xray config and applies it — preferring a *hot diff* (live gRPC
|
|
API mutation) over a full process restart. See §5.1.
|
|
2. **The Runtime abstraction (multi-node).** A panel can manage remote "nodes" (other 3x-ui
|
|
instances). Every state-changing inbound/client operation is dispatched through a
|
|
`runtime.Runtime` interface that is either **`Local`** (this box's Xray gRPC API) or
|
|
**`Remote`** (HTTPS call to a child node, with `verify`/`skip`/`pin`/`mtls` TLS modes).
|
|
This is the single most important abstraction in the project. See §5.2.
|
|
|
|
---
|
|
|
|
## 2. Tech stack
|
|
|
|
**Backend (Go 1.26):**
|
|
- Web framework: **Gin** (`gin-gonic/gin`) + sessions (cookie store), gzip.
|
|
- ORM: **GORM** with **SQLite** (default) or **PostgreSQL** (`XUI_DB_TYPE=postgres`).
|
|
- Scheduler: **robfig/cron/v3** (seconds-precision) for all background jobs.
|
|
- Xray: **xtls/xray-core** vendored as a library; the panel talks to the running core over
|
|
its **gRPC API** and also shells out to manage the process.
|
|
- Telegram bot: **mymmrac/telego**. i18n: **nicksnyder/go-i18n**.
|
|
- Misc: gorilla/websocket, gopsutil (system stats), go-qrcode, gotp (2FA TOTP).
|
|
|
|
**Frontend (`frontend/`):**
|
|
- **React 19** + **Ant Design 6** + **Vite 8** + **TypeScript**.
|
|
- Data layer: **TanStack Query** (`@tanstack/react-query`) over **axios**; **Zod 4** schemas.
|
|
- Router: **react-router-dom 7**. Charts: **recharts**. Editor: **CodeMirror 6**.
|
|
- **Build output goes to `internal/web/dist/`** (see `vite.config.js` → `outDir`) and is
|
|
embedded into the Go binary with `go:embed`. Three HTML entries: `index.html` (panel SPA),
|
|
`login.html`, `subpage.html`. The Go server serves the SPA; there is no separate frontend
|
|
deployment.
|
|
|
|
**Important:** the legacy Go-template UI and `web/assets/` are **gone**. All HTML/JS comes
|
|
from the embedded Vite `dist/`. Don't look for `.html` templates in `internal/web`.
|
|
|
|
---
|
|
|
|
## 3. Request lifecycle (follow the data)
|
|
|
|
### 3.1 Admin API request (e.g. "add a client")
|
|
|
|
```
|
|
Browser (React, axios)
|
|
→ POST {basePath}/panel/api/...
|
|
→ Gin engine (internal/web/web.go: initRouter)
|
|
→ middleware chain: SecurityHeaders → MaxBodyBytes (10 MiB; importDB exempt)
|
|
→ [DomainValidator, if webDomain set] → gzip → sessions("3x-ui")
|
|
→ base-path/cache-control context → Localizer
|
|
→ API routes add: ConfigEnvelope (zstd + SHA-256) → CSRF
|
|
→ Controller (internal/web/controller/*.go) // HTTP concerns only: bind, validate, respond
|
|
→ Service (internal/web/service/*.go) // business logic + transactions
|
|
→ GORM → DB (internal/database) // persistence
|
|
→ runtime.Runtime dispatch // apply to Xray (Local) or node (Remote)
|
|
→ Local: internal/xray (gRPC API or config regen + restart)
|
|
→ Remote: internal/web/runtime/remote.go → HTTPS → child node's API
|
|
```
|
|
|
|
The controller layer is thin. **Business logic lives in services.** When something is wrong
|
|
with *behavior*, the bug is almost always in a service file, not a controller.
|
|
|
|
### 3.2 Subscription request (end-user fetching their config)
|
|
|
|
```
|
|
End user → GET {subPath}/{subId} (separate server, internal/sub)
|
|
→ internal/sub/controller.go (routes: raw / JSON / Clash variants, feature-flagged)
|
|
→ internal/sub/service.go (~2.5k lines — the link/config builder)
|
|
→ reads inbounds+clients+hosts from DB, renders per-protocol share links /
|
|
Clash YAML / JSON (Host rows can override address/SNI/path per inbound)
|
|
```
|
|
|
|
### 3.3 Background work (cron jobs)
|
|
|
|
Scheduled in `internal/web/web.go` → `startTask()`. Each job is a struct in
|
|
`internal/web/job/`. Examples: poll Xray traffic every 5s, check client IP limits every 10s,
|
|
node heartbeat every 5s, periodic traffic resets (hourly/daily/weekly/monthly). See §5.4.
|
|
|
|
---
|
|
|
|
## 4. Directory map (what lives where)
|
|
|
|
```
|
|
3x-ui/
|
|
├── main.go # Entry point: CLI (run / migrate / migrate-db / setting / cert),
|
|
│ # bootstrap, signal handling, restart loop
|
|
├── go.mod / go.sum # Go deps (module path ends in /v3)
|
|
│
|
|
├── internal/ # ALL backend Go code (private packages)
|
|
│ ├── config/ # Env-var config: paths, DB kind/DSN, log level, version
|
|
│ │ # Every XUI_* env var is read here (config.go)
|
|
│ ├── database/
|
|
│ │ ├── db.go # InitDB: connect, AutoMigrate, seeders (~1.4k lines). DB hotspot.
|
|
│ │ ├── migrate_data.go # Data migrations (seeders/normalizers beyond AutoMigrate)
|
|
│ │ ├── dialect.go # SQLite vs Postgres SQL differences
|
|
│ │ ├── dump_sqlite.go # DB export/backup
|
|
│ │ └── model/ # **ALL GORM models** (model.go ~1.1k lines + siblings:
|
|
│ │ # node_client_traffic.go, node_client_ip.go,
|
|
│ │ # client_global_traffic.go). ⭐ Start here for data shape.
|
|
│ ├── eventbus/ # In-process pub/sub (buffered channel): outbound.down|up,
|
|
│ │ # xray.crash, node.down|up, cpu.high, memory.high, login.attempt
|
|
│ ├── tunnelmonitor/ # Optional tunnel health probe (XUI_TUNNEL_HEALTH_* env vars):
|
|
│ │ # HTTP probe (default Cloudflare trace); repeated failures
|
|
│ │ # trigger an Xray restart hook. Independent of panel settings.
|
|
│ ├── xray/ # Xray-core integration (the proxy engine wrapper)
|
|
│ │ ├── process.go # Spawn/supervise the Xray child process (~750 lines)
|
|
│ │ ├── api.go # gRPC client to a running Xray (add/remove user, stats) (~800 lines)
|
|
│ │ ├── hot_diff.go # ⭐ Compute minimal live changes to avoid full restart (~500 lines)
|
|
│ │ ├── config.go # Xray config object model
|
|
│ │ ├── inbound.go # Inbound JSON shaping
|
|
│ │ ├── client_traffic.go # ClientTraffic model (persisted as client_traffics)
|
|
│ │ ├── traffic.go # Traffic type helpers
|
|
│ │ └── log_writer.go # Pipe Xray stdout/stderr into the panel logger
|
|
│ │
|
|
│ ├── web/ # The panel server
|
|
│ │ ├── web.go # ⭐ Server bootstrap: initRouter (all routes) + startTask (all cron jobs)
|
|
│ │ ├── controller/ # HTTP handlers (thin). One file per resource:
|
|
│ │ │ ├── inbound.go # /panel/api/inbounds
|
|
│ │ │ ├── client.go # /panel/api/clients (CRUD + bulk + ips + onlines)
|
|
│ │ │ ├── group.go # client-group endpoints
|
|
│ │ │ ├── node.go # /panel/api/nodes (multi-node management)
|
|
│ │ │ ├── host.go # /panel/api/hosts (per-inbound subscription host overrides)
|
|
│ │ │ ├── server.go # /panel/api/server (status, xray version, certs, logs, DB import/export)
|
|
│ │ │ ├── setting.go # /panel/api/setting (settings + API tokens)
|
|
│ │ │ ├── xray_setting.go # /panel/api/xray (raw Xray config editor, WARP/Nord)
|
|
│ │ │ ├── api.go # /panel/api gateway (token auth, envelope + CSRF wiring)
|
|
│ │ │ ├── index.go # login/logout/csrf/2FA
|
|
│ │ │ ├── spa.go # SPA fallback for /panel UI routes
|
|
│ │ │ └── websocket.go # WS upgrade endpoint
|
|
│ │ ├── service/ # ⭐⭐ Business logic. This is where most real work happens.
|
|
│ │ │ ├── inbound.go # Inbound CRUD core (~1.4k lines)
|
|
│ │ │ ├── inbound_node.go # ⭐ Node sync for inbounds: reconcile, traffic merge (~1.1k lines)
|
|
│ │ │ ├── inbound_traffic.go # Per-client traffic accounting (~1.1k lines)
|
|
│ │ │ ├── inbound_clients.go # Client-within-inbound operations
|
|
│ │ │ ├── inbound_sublink.go # Inbound-level subscription link helpers
|
|
│ │ │ ├── inbound_migration.go # Inbound schema/format migrations
|
|
│ │ │ ├── client_crud.go # Client create/read/update/delete
|
|
│ │ │ ├── client_bulk.go # Bulk client ops (~1.6k lines)
|
|
│ │ │ ├── client_inbound_apply.go # ⭐ Apply client changes to runtime (Local/Remote) (~1.2k lines)
|
|
│ │ │ ├── client_groups.go # Client grouping
|
|
│ │ │ ├── client_link.go # Per-client share-link generation
|
|
│ │ │ ├── client_external_link.go # External links attached to clients
|
|
│ │ │ ├── client_wireguard.go # WireGuard client specifics
|
|
│ │ │ ├── client_paging.go # Server-side pagination/sort/filter for client lists
|
|
│ │ │ ├── node.go # ⭐ NodeService: CRUD, probe, heartbeat, dirty-tracking (~1.1k lines)
|
|
│ │ │ ├── node_mtls.go # Node mTLS certificate management (master side)
|
|
│ │ │ ├── node_tree.go # Node hierarchy / descendants
|
|
│ │ │ ├── host.go # Host rows (subscription output overrides)
|
|
│ │ │ ├── server.go # ServerService: status, certs, xray install, DB ops (~2.2k lines)
|
|
│ │ │ ├── setting.go # SettingService: all panel settings + defaults (~1.3k lines)
|
|
│ │ │ ├── setting_mtls.go # mTLS settings (node hardening)
|
|
│ │ │ ├── traffic_writer.go # Batched persistence of traffic deltas to the DB
|
|
│ │ │ ├── xray.go # ⭐ XrayService: config gen + restart/hot-apply (~1.2k lines)
|
|
│ │ │ ├── xray_setting.go # Raw Xray config persistence
|
|
│ │ │ ├── xray_metrics.go # Xray observability metrics
|
|
│ │ │ ├── metric_history.go # Historical system/xray metrics
|
|
│ │ │ ├── reality_scan.go # REALITY target scanner
|
|
│ │ │ ├── url_safety.go # Outbound URL validation (SSRF guards)
|
|
│ │ │ ├── outbound_subscription.go# Outbound subscription (e.g. Warp/Nord provider configs)
|
|
│ │ │ ├── port_conflict.go # Detect inbound port collisions
|
|
│ │ │ ├── fallback.go # Xray fallback (SNI/ALPN routing on shared port)
|
|
│ │ │ ├── email/ # Email notification service (SMTP)
|
|
│ │ │ ├── integration/ # External providers: warp.go (Cloudflare WARP), nord.go (NordVPN)
|
|
│ │ │ ├── outbound/ # Outbound config service
|
|
│ │ │ ├── panel/ # Cross-cutting panel services:
|
|
│ │ │ │ ├── panel.go # panel-level helpers
|
|
│ │ │ │ ├── user.go # admin user auth (bcrypt)
|
|
│ │ │ │ ├── api_token.go # API token CRUD (SHA-256 hashed)
|
|
│ │ │ │ └── websocket.go # WS hub / push service
|
|
│ │ │ └── tgbot/ # Telegram bot command handlers
|
|
│ │ ├── runtime/ # ⭐⭐ The Local/Remote node abstraction (see §5.2)
|
|
│ │ │ ├── runtime.go # the Runtime interface (the contract)
|
|
│ │ │ ├── local.go # Local impl → this box's Xray gRPC API
|
|
│ │ │ ├── remote.go # Remote impl → HTTPS calls to a child node
|
|
│ │ │ ├── tls_client.go # per-node HTTP client: verify / skip / pin / mtls
|
|
│ │ │ └── manager.go # RuntimeFor(nodeID) → picks Local or Remote
|
|
│ │ ├── job/ # Cron job structs (one file per job — see §5.4)
|
|
│ │ ├── middleware/ # Gin middleware: security.go (headers/HSTS), bodylimit.go,
|
|
│ │ │ # domainValidator.go, validate.go (CSRF), config_envelope.go
|
|
│ │ ├── global/ # Global singletons: web server + sub server handles, restart hook
|
|
│ │ ├── network/ # Custom net listeners (e.g. proxy-protocol aware)
|
|
│ │ ├── session/ # Session/cookie helpers
|
|
│ │ ├── websocket/ # WS hub implementation
|
|
│ │ ├── locale/ + translation/ # i18n middleware + 13 locale JSON catalogs
|
|
│ │ ├── entity/ # Shared request/response DTOs
|
|
│ │ └── dist/ # ⚠️ Vite build output, embedded via go:embed (generated — do not hand-edit)
|
|
│ │
|
|
│ ├── sub/ # The subscription server (separate from panel)
|
|
│ │ ├── sub.go # server bootstrap
|
|
│ │ ├── controller.go # routes for raw / JSON / Clash subscription formats
|
|
│ │ ├── service.go # ⭐ The link/config builder (~2.5k lines — share-link logic lives here)
|
|
│ │ ├── json_service.go # JSON subscription format
|
|
│ │ ├── clash_service.go # Clash/Mihomo YAML format
|
|
│ │ ├── clash_external.go # external Clash config integration
|
|
│ │ ├── external_subscription.go / external_config.go # external sub import/aggregation
|
|
│ │ ├── host_sub.go # Host-row overrides applied to subscription output
|
|
│ │ ├── endpoint.go # subscription endpoint configuration
|
|
│ │ ├── vless_route.go # VLESS route shaping
|
|
│ │ ├── remark_vars.go # remark variable expansion
|
|
│ │ └── links.go # link helpers
|
|
│ │
|
|
│ ├── mtproto/ # Embedded MTProto (Telegram) proxy: manager.go + per-OS
|
|
│ │ # process supervision + orphan cleanup
|
|
│ ├── logger/ # App logger (op/go-logging + lumberjack rotation)
|
|
│ └── util/ # Leaf helpers (no business logic):
|
|
│ ├── common/ # errors, misc
|
|
│ ├── crypto/ # key/cert generation (x25519, ML-KEM/ML-DSA, ECH)
|
|
│ ├── link/ # outbound share-link building primitives
|
|
│ ├── wirecodec/ + wireguard/ # WireGuard codec + integration helpers
|
|
│ └── random/, json_util/, reflect_util/, sys/, netproxy/, netsafe/, ldap/
|
|
│
|
|
├── frontend/ # React SPA (built into internal/web/dist)
|
|
│ ├── vite.config.js # ⭐ Build config: outDir → ../internal/web/dist, dev on :5173
|
|
│ │ # (strict) proxying to :2053, entries index/login/subpage.html
|
|
│ ├── package.json # scripts: dev / build / preview / lint / typecheck / test / gen
|
|
│ └── src/
|
|
│ ├── main.tsx / routes.tsx / queryClient.ts # SPA entry, router, query client
|
|
│ ├── entries/ # Extra HTML entry points: login.tsx, subpage.tsx
|
|
│ ├── pages/ # ⭐ Route screens. Mirrors the panel's feature areas:
|
|
│ │ ├── inbounds/ # inbound list + the big inbound form (protocols/security/transport)
|
|
│ │ ├── clients/ # client management screens
|
|
│ │ ├── nodes/ # multi-node UI
|
|
│ │ ├── hosts/ # subscription host-override UI
|
|
│ │ ├── xray/ # raw Xray config UI (routing, dns, outbounds, balancers, overrides)
|
|
│ │ ├── index/ # dashboard/home
|
|
│ │ └── settings/, groups/, sub/, login/, api-docs/
|
|
│ ├── api/ # ⭐ Data layer: axios-init, QueryProvider, queryKeys, websocket bridge
|
|
│ │ └── queries/ # TanStack Query hooks (useNodesQuery, useStatusQuery, …)
|
|
│ ├── schemas/ # Zod schemas: protocols, forms, api, primitives
|
|
│ ├── generated/ # ⚠️ GENERATED from Go (see §5.5): schemas.ts, types.ts, zod.ts, examples.ts
|
|
│ ├── components/ # Reusable UI (clients/ form/ ui/ viz/ feedback/ utility/)
|
|
│ ├── lib/ # Frontend domain logic (xray/ inbounds/ clients/)
|
|
│ ├── hooks/, models/, layouts/, i18n/, utils/, styles/
|
|
│ └── test/ # Vitest + golden fixtures (config-generation snapshot tests)
|
|
│
|
|
├── tools/openapigen/ # ⭐ Go program that emits frontend/src/generated/* from Go types (§5.5)
|
|
├── docs/ # Markdown docs (this file, custom-subscription-templates.md, …)
|
|
├── media/ # README images
|
|
│
|
|
├── Dockerfile / docker-compose.yml / DockerEntrypoint.sh / DockerInit.sh # Container build/run
|
|
├── install.sh / update.sh / x-ui.sh # VPS install + management CLI
|
|
├── x-ui.service.* / x-ui.rc # systemd units (debian/rhel/arch) + rc script
|
|
├── windows_files/ # Windows service support
|
|
└── .github/workflows/ # CI: ci.yml, codeql.yml, docker.yml, release.yml, smoke.yml,
|
|
# mutation.yml, cleanup_caches.yml, claude-bot.yml
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Cross-cutting subsystems (the parts that span many files)
|
|
|
|
### 5.1 DB → Xray config pipeline (config generation & application)
|
|
|
|
The panel never edits Xray's running config directly from controllers. The flow is:
|
|
|
|
1. A service mutates DB state (inbound/client/setting).
|
|
2. `XrayService` (`service/xray.go`) builds a fresh `xray.Config` from DB state
|
|
(`GetXrayConfig`).
|
|
3. It tries a **hot apply** (`tryHotApply` → `xray/hot_diff.go`): diff old vs new config and
|
|
push only the deltas over the Xray gRPC API (add/remove inbound, add/remove user) — **no
|
|
process restart**, so live connections survive.
|
|
4. If the diff isn't hot-applicable (structural change), it falls back to a **full restart**
|
|
of the Xray process (`xray/process.go`).
|
|
|
|
Restart is debounced via an atomic "need restart" flag (`SetToNeedRestart` /
|
|
`IsNeedRestartAndSetFalse`), consumed by a `@every 30s` cron task registered in `startTask()`
|
|
— any number of mutations inside the window causes at most one restart.
|
|
|
|
**Key files:** `service/xray.go` (orchestration), `xray/hot_diff.go` (the diff algorithm),
|
|
`xray/process.go` (process lifecycle), `xray/api.go` (gRPC calls), `xray/config.go` (config model).
|
|
|
|
### 5.2 Runtime abstraction — Local vs Remote (multi-node) ⭐ most important
|
|
|
|
A "node" (`model.Node`) is another 3x-ui instance this panel controls. Every state-changing
|
|
inbound/client operation goes through the `runtime.Runtime` interface so the *same service
|
|
code* works whether the target is the local Xray or a remote node.
|
|
|
|
- **Interface:** `internal/web/runtime/runtime.go` — `Name`, `AddInbound`, `DelInbound`,
|
|
`UpdateInbound`, `AddUser`, `RemoveUser`, `UpdateUser`, `DeleteUser`, `AddClient`,
|
|
`RestartXray`, `ResetClientTraffic`, `ResetInboundTraffic`, `ResetAllTraffics`.
|
|
- **`Local`** (`local.go`): calls this box's Xray gRPC API directly.
|
|
- **`Remote`** (`remote.go`): serializes the operation and sends it over HTTPS to the child
|
|
node's API.
|
|
- **TLS modes** (`tls_client.go`, per-node `TlsVerifyMode`):
|
|
`verify` (system CAs, default) / `skip` (no validation) / `pin` (leaf cert SHA-256 must
|
|
match `PinnedCertSha256`) / `mtls` (master presents a client certificate; node cert checked
|
|
against system roots; API token optional). Master-side cert management:
|
|
`service/node_mtls.go` + `service/setting_mtls.go`.
|
|
- **Dispatch:** `manager.go` → `Manager.RuntimeFor(nodeID *int)`; `nil` nodeID → `Local`,
|
|
otherwise a cached/lazy-loaded `Remote`. `InvalidateNode(id)` drops a cached remote client.
|
|
|
|
**Node identity & attribution (the hard part).** Inbounds carry a `NodeID` *and* an
|
|
`OriginNodeGuid`. Because inbounds can be pushed across hops, the panel attributes traffic and
|
|
online clients back to the originating panel using **stable GUIDs** rather than local IDs.
|
|
Relevant logic: `service/inbound_node.go` (`ReconcileNode`, `SetRemoteTraffic`, GUID merge,
|
|
`synthNodeGuid`, `panelGuid`) and `service/node.go` (`effectiveNodeGuid`, heartbeat, dirty
|
|
tracking). Node "dirty" flags drive an **anti-entropy reconciliation** so an offline node's
|
|
inbound edits converge once it reconnects.
|
|
|
|
**Where to look for node bugs:**
|
|
- Operation not reaching a node → `runtime/remote.go` + `runtime/manager.go`.
|
|
- Wrong traffic/online attribution across hops → `service/inbound_node.go` (GUID merge paths).
|
|
- Node shown offline / stale status → `job/node_heartbeat_job.go` + `service/node.go` (`Probe`, `UpdateHeartbeat`).
|
|
- Edits to an offline node not applying on reconnect → dirty/reconcile logic in `service/inbound_node.go` + `service/node.go` (`MarkNodeDirty`/`ClearNodeDirty`/`NodeSyncState`).
|
|
- TLS/mTLS handshake failures → `runtime/tls_client.go`, `service/node_mtls.go`, `service/node.go` (`FetchCertFingerprint`).
|
|
|
|
### 5.3 Traffic accounting
|
|
|
|
Per-client and per-inbound up/down counters originate from Xray's stats API and are persisted
|
|
to the DB. The Xray traffic job polls the core; node traffic is pulled from child nodes and
|
|
merged with GUID-based baselines to avoid double counting after resets.
|
|
|
|
**Key files:** `service/inbound_traffic.go`, `service/traffic_writer.go`,
|
|
`job/xray_traffic_job.go`, `job/node_traffic_sync_job.go`, `service/inbound_node.go`
|
|
(`SetRemoteTraffic` / `upsertNodeBaseline`), models `xray.ClientTraffic`,
|
|
`model.NodeClientTraffic`, `model.ClientGlobalTraffic` (cross-master totals).
|
|
Periodic resets: `job/periodic_traffic_reset_job.go` (keyed off `Inbound.TrafficReset`).
|
|
|
|
### 5.4 Background jobs (cron)
|
|
|
|
All registered in `web.go` → `startTask()`. Each is a struct with a `Run()` method in `internal/web/job/`:
|
|
|
|
| Schedule | Job | Purpose / condition |
|
|
|---|---|---|
|
|
| `@every 1s` | `check_xray_running_job` | Restart Xray if it died (2 consecutive down checks) |
|
|
| `@every 30s` | (inline func in `startTask`) | Debounced Xray restart — consumes the "need restart" flag (§5.1) |
|
|
| `@every 5s` | `xray_traffic_job` | Pull traffic stats from Xray (5s start delay) |
|
|
| `@every 5s` | `node_heartbeat_job` | Probe child nodes (online/offline) |
|
|
| `@every 5s` | `node_traffic_sync_job` | Pull + merge node traffic; push reconciliation |
|
|
| `@every 10s` | `check_client_ip_job` | Enforce per-client IP limits |
|
|
| `@every 10s` | `mtproto_job` | Reconcile `mtg` sidecars against enabled MTProto inbounds |
|
|
| `@every 5m` | `outbound_subscription_job` | Refresh outbound provider configs |
|
|
| `@hourly` | `warp_ip_job`, `periodic_traffic_reset_job("hourly")` | WARP IP rotation; traffic resets |
|
|
| `@daily` | `clear_logs_job`, `periodic_traffic_reset_job("daily")` | Log cleanup; resets |
|
|
| `@weekly` / `@monthly` | `periodic_traffic_reset_job(...)` | Weekly/monthly traffic resets |
|
|
| default `@every 1m` | `ldap_sync_job` | Only if LDAP enabled; schedule configurable |
|
|
| default `@daily` | `stats_notify_job` | Only if TG bot enabled; schedule configurable |
|
|
| `@every 2m` | `check_hash_storage` | Only if TG bot enabled; expires bot callback hashes |
|
|
| `@every 1m` | `check_cpu_usage` | Only if a CPU alarm is configured (TG or email); publishes `cpu.high` |
|
|
| `@every 1m` | `check_memory_usage` | Only if a memory alarm is configured; publishes `memory.high` |
|
|
| configurable | `free_os_memory` | Only if `sys.MemoryReleaseIntervalMinutes() > 0`; returns heap to OS |
|
|
|
|
To change *when* something runs, edit `startTask()`. To change *what* it does, edit the job file.
|
|
|
|
### 5.5 Type generation (Go → TypeScript) ⚠️ don't hand-edit generated files
|
|
|
|
The Go backend is the schema source of truth. `tools/openapigen` (a Go program, with a
|
|
`StructAllow` allowlist of exported types) emits
|
|
`frontend/src/generated/{schemas,types,zod,examples}.ts`. The frontend build runs this first:
|
|
|
|
- `npm run gen:zod` → `go run ./tools/openapigen` (regenerate from Go)
|
|
- `npm run gen:api` → builds the OpenAPI doc (`scripts/build-openapi.mjs`, driven by the
|
|
hand-maintained endpoint registry `src/pages/api-docs/endpoints.ts`)
|
|
- `npm run build` runs `gen:api` then `vite build`.
|
|
|
|
**Implication:** if you change a Go model/DTO that crosses the API boundary, regenerate the
|
|
frontend types (`cd frontend && npm run gen`) instead of editing `src/generated/` by hand.
|
|
|
|
### 5.6 Share-link / subscription generation
|
|
|
|
Two distinct code paths produce client configs:
|
|
- **Per-client links in the panel** (the "copy link" / QR in the UI): `service/client_link.go`
|
|
+ `util/link/outbound.go`.
|
|
- **Subscription endpoint** (what a client app polls): `internal/sub/service.go` (raw links),
|
|
`internal/sub/json_service.go` (JSON), `internal/sub/clash_service.go` (Clash YAML).
|
|
**`Host` rows** (`model.Host`, edited under /panel/api/hosts) override address/SNI/path/
|
|
security per inbound in subscription output — applied in `sub/host_sub.go`.
|
|
|
|
Both paths must agree per protocol. A malformed link for a specific protocol/transport combo
|
|
(e.g. XHTTP + Reality) is usually a field-lookup mismatch in **`internal/sub/service.go`** (and
|
|
its tests `service_test.go` / golden fixtures), or in `util/link/outbound.go`. The frontend
|
|
also has protocol schemas under `frontend/src/schemas/protocols/` and `frontend/src/lib/xray/`.
|
|
|
|
### 5.7 Event bus (in-process pub/sub)
|
|
|
|
`internal/eventbus/` is a minimal buffered-channel pub/sub. Producers call a non-blocking
|
|
`Publish(Event)`; all subscribers receive every event. Event types: `outbound.down|up`,
|
|
`xray.crash`, `node.down|up`, `cpu.high`, `memory.high`, `login.attempt`, with structured
|
|
payloads (OutboundHealthData, NodeHealthData, LoginEventData, SystemMetricData). Producers
|
|
include the CPU/memory jobs, node heartbeat, and login handling; consumers include the
|
|
Telegram bot and the email notifier (`service/email/`). Use it for cross-cutting
|
|
notifications instead of importing notification services into producers.
|
|
|
|
### 5.8 Tunnel health monitor
|
|
|
|
`internal/tunnelmonitor/` is an optional watchdog configured **only via env vars**
|
|
(`XUI_TUNNEL_HEALTH_*`, read in `internal/config/`), deliberately independent of panel
|
|
settings so it can be enabled from a systemd `EnvironmentFile` even when the panel is
|
|
unreachable. It periodically probes an HTTP URL (default: Cloudflare trace endpoint) through
|
|
the tunnel; after N successive failures (default 3) it fires a recovery callback wired to an
|
|
Xray restart.
|
|
|
|
---
|
|
|
|
## 6. Data model cheat-sheet
|
|
|
|
GORM models in `internal/database/model/` (main file `model.go` + siblings); all registered
|
|
for AutoMigrate in `internal/database/db.go`.
|
|
|
|
| Model | Table role | Notable fields |
|
|
|---|---|---|
|
|
| `User` | Admin login | bcrypt password, `LoginEpoch` (invalidates sessions) |
|
|
| `Inbound` | An Xray inbound | `Tag` (unique), `Port`, `Protocol`, `Settings`/`StreamSettings`/`Sniffing` (JSON), `Enable`, `TrafficReset`, `NodeID`, **`OriginNodeGuid`**, `ClientStats` (assoc) |
|
|
| `Client` | In-memory client view | UUID/email/flow/limits (parsed from inbound JSON; not persisted) |
|
|
| `ClientRecord` | Persisted client (`clients`) | `Email` (unique), `SubID`, `UUID`, `TotalGB`, `ExpiryTime`, `LimitIP`, `Group`, `Reset` |
|
|
| `ClientGroup` / `ClientInbound` | Grouping + client↔inbound join | many-to-many wiring, `FlowOverride` |
|
|
| `ClientExternalLink` | Extra links attached to a client | `Kind`, `Value`, `Remark`, `SortIndex` |
|
|
| `Host` | Subscription host overrides (per inbound) | `Address`, `Port`, `Sni`, `Path`, `Security`, `Fingerprint`, `SortOrder`, visibility/exclusion flags |
|
|
| `Node` | A managed child panel | `Guid`, `Address`, `Status`, `TlsVerifyMode`, `PinnedCertSha256`, `ConfigDirty`, version/heartbeat/metric fields |
|
|
| `NodeClientTraffic` | Per-node client traffic baseline | cross-node merge (anti-double-count) |
|
|
| `NodeClientIp` | Per-node client IP attribution | `NodeGuid`, `Email`, `Ips` |
|
|
| `ClientGlobalTraffic` | Cross-master usage totals | `MasterGuid`, `Email`, `Up`, `Down` |
|
|
| `xray.ClientTraffic` | Per-client counters (`client_traffics`) | `Email`, `Up`, `Down`, `Total`, `ExpiryTime`, `LastOnline` |
|
|
| `InboundClientIps` | IP set per client email | drives IP-limit enforcement |
|
|
| `OutboundTraffics` | Outbound counters | per outbound tag |
|
|
| `OutboundSubscription` | External provider subs | Warp/Nord style |
|
|
| `Setting` | Key/value panel settings | everything configurable |
|
|
| `ApiToken` | REST API tokens | SHA-256 hash (plaintext shown once) |
|
|
| `InboundFallback` | Fallback routing on a shared port | SNI/ALPN/path → dest |
|
|
| `HistoryOfSeeders` | Seeder bookkeeping | prevents re-running one-off migrations |
|
|
|
|
---
|
|
|
|
## 7. Symptom → File index (start here when debugging)
|
|
|
|
| Symptom / task | Primary file(s) | Then check |
|
|
|---|---|---|
|
|
| Add/modify an **API endpoint** | `controller/<resource>.go` (route registration at top of each file) | corresponding `service/*.go`, `frontend/src/pages/api-docs/endpoints.ts` |
|
|
| **Inbound** create/update/delete behavior | `service/inbound.go`, `service/inbound_clients.go` | `runtime/*`, `service/xray.go` |
|
|
| **Client** CRUD / limits / expiry | `service/client_crud.go`, `service/client_inbound_apply.go` | model `ClientRecord`, `service/inbound_traffic.go` |
|
|
| **Bulk** client operations slow/wrong | `service/client_bulk.go` | `service/client_paging.go` |
|
|
| Xray **won't apply** a config change | `service/xray.go` (`RestartXray`, `tryHotApply`) | `xray/hot_diff.go`, `xray/process.go` |
|
|
| Xray **restarts when it shouldn't** (kills connections) | `xray/hot_diff.go` (diff not classified as hot) | `service/xray.go` |
|
|
| **Traffic** counts wrong / reset behavior | `service/inbound_traffic.go`, `job/xray_traffic_job.go` | `service/traffic_writer.go`, `job/periodic_traffic_reset_job.go` |
|
|
| **Node** operation not propagating | `runtime/remote.go`, `runtime/manager.go` | `service/inbound_node.go` |
|
|
| **Multi-hop / cross-node attribution** (traffic or online clients on wrong panel) | `service/inbound_node.go` (GUID merge, `synthNodeGuid`, `effectiveNodeGuid`) | `service/node.go`, model `OriginNodeGuid`/`Node.Guid` |
|
|
| Node stuck **offline / stale** | `job/node_heartbeat_job.go`, `service/node.go` (`Probe`, `UpdateHeartbeat`) | `runtime/tls_client.go` (TLS verify) |
|
|
| Node **TLS / mTLS** auth failures | `runtime/tls_client.go`, `service/node_mtls.go`, `service/setting_mtls.go` | `service/node.go` (`FetchCertFingerprint`) |
|
|
| Offline node edits **not reconciling** on reconnect | `service/inbound_node.go` (`ReconcileNode`, dirty flags) | `service/node.go` (`MarkNodeDirty`/`NodeSyncState`) |
|
|
| **Share link / QR** malformed (per protocol) | `service/client_link.go`, `util/link/outbound.go` | `frontend/src/lib/xray/`, `frontend/src/schemas/protocols/` |
|
|
| **Subscription** output wrong (raw/JSON/Clash) | `internal/sub/service.go` | `sub/json_service.go`, `sub/clash_service.go`, sub golden tests |
|
|
| Subscription **host overrides** not applied | `service/host.go`, `sub/host_sub.go` | model `Host`, `frontend/src/pages/hosts/` |
|
|
| **External subscription** import/aggregation | `sub/external_subscription.go`, `sub/external_config.go` | `sub/clash_external.go` |
|
|
| **Settings** not saving / defaults | `service/setting.go`, `controller/setting.go` | model `Setting` |
|
|
| **Login / 2FA / sessions / CSRF** | `controller/index.go`, `service/panel/user.go`, `middleware/` | `session/` |
|
|
| **API tokens** | `service/panel/api_token.go`, `controller/setting.go` | model `ApiToken` |
|
|
| **Port conflict** on inbound add | `service/port_conflict.go` | `controller/inbound.go` |
|
|
| **Fallbacks** (shared 443, SNI routing) | `service/fallback.go`, `controller/inbound.go` | model `InboundFallback` |
|
|
| **Telegram bot** commands | `service/tgbot/` | `job/stats_notify_job.go` |
|
|
| **Email notifications** | `service/email/` | `internal/eventbus/` (consumers) |
|
|
| **CPU / memory alerts** not firing | `job/check_cpu_usage.go`, `job/check_memory_usage.go` | `internal/eventbus/`, notifier settings in `service/setting.go` |
|
|
| Xray auto-restart on **dead tunnel** | `internal/tunnelmonitor/` | `XUI_TUNNEL_HEALTH_*` in `internal/config/` |
|
|
| **WARP / Nord** outbound integration | `service/integration/warp.go` / `nord.go` | `service/outbound_subscription.go` |
|
|
| **MTProto** proxy issues | `internal/mtproto/manager.go`, `mtproto/process*.go` | `job/mtproto_job.go` |
|
|
| **DB migration** / new column | `internal/database/db.go` (AutoMigrate list), `migrate_data.go` | `model/model.go` |
|
|
| **Cron schedule** changes | `web.go` → `startTask()` | the specific `job/*.go` |
|
|
| **CORS / security headers / HTTPS** | `middleware/`, `web.go` (`initRouter`, TLS setup) | `config/` (env) |
|
|
| **Env vars / paths / DB type** | `internal/config/config.go` | `.env.example` |
|
|
| **Frontend route / screen** | `frontend/src/pages/<area>/`, `frontend/src/routes.tsx` | `frontend/src/api/queries/` |
|
|
| **Frontend ↔ backend type mismatch** | regenerate: `cd frontend && npm run gen` (`tools/openapigen`) | `frontend/src/generated/` |
|
|
| **System status / CPU / metrics** | `service/server.go`, `service/xray_metrics.go`, `service/metric_history.go` | `controller/server.go`, gopsutil |
|
|
|
|
---
|
|
|
|
## 8. Layering rules (where new code belongs)
|
|
|
|
1. **Controllers are thin.** Only: bind/validate input, call one service, shape the HTTP
|
|
response. No DB queries, no Xray calls, no business rules in `controller/`.
|
|
2. **Services own the logic and transactions.** All business rules, DB access, and decisions
|
|
about applying changes live in `service/`. If you're tempted to query GORM from a
|
|
controller, move it to a service.
|
|
3. **Never touch Xray's running state from a controller or job directly.** Go through
|
|
`XrayService` / the `runtime.Runtime` interface so local vs node dispatch stays correct.
|
|
4. **Any state-changing inbound/client op must dispatch through `runtime.Runtime`**, not
|
|
straight to `xray/api.go` — otherwise node deployments silently break.
|
|
5. **`internal/util/*` is leaf-only** (no imports of `service`/`controller`/`database`). Keep
|
|
helpers pure.
|
|
6. **Don't hand-edit generated files:** `frontend/src/generated/*` and `internal/web/dist/*`.
|
|
Regenerate instead.
|
|
7. **Models are the contract.** Changing a model field that crosses the API boundary means:
|
|
update `model.go` → handle migration in `db.go`/`migrate_data.go` → regenerate frontend types.
|
|
8. **Two servers, two concerns.** Admin features go in `internal/web`; anything an *end user*
|
|
fetches goes in `internal/sub`. Don't blur them.
|
|
9. **Cross-cutting notifications go through `internal/eventbus/`** — publish an event instead
|
|
of importing the Telegram/email services into producers.
|
|
|
|
---
|
|
|
|
## 9. Build / Test / Lint (verify your changes)
|
|
|
|
The canonical gate is the **Makefile** (mirrors CI): `make verify`. Also: `make gen`
|
|
(regenerate Zod/OpenAPI), `make lint` (Go + frontend), `make test` (Go `-shuffle=on` +
|
|
frontend), `make race`, `make build`. Run `make help` for everything. Raw commands:
|
|
|
|
**Backend (Go):**
|
|
```bash
|
|
go build ./... # compile everything
|
|
go test ./... # run all Go tests (many *_test.go alongside sources)
|
|
go test ./internal/web/service/... # focused: service-layer tests
|
|
go test ./internal/xray/... # hot-diff / process / api tests
|
|
go test ./internal/sub/... # subscription + golden link tests
|
|
go vet ./... # static checks
|
|
golangci-lint run # full lint (gofumpt + goimports formatting)
|
|
go run main.go # run the panel locally (serves embedded dist if built)
|
|
```
|
|
|
|
**Frontend (`cd frontend`, Node ≥ 22):**
|
|
```bash
|
|
npm install
|
|
npm run dev # Vite dev server on :5173; proxies API to Go backend on :2053 (run `go run main.go` too)
|
|
npm run typecheck # tsc --noEmit
|
|
npm run lint # eslint src
|
|
npm run test # vitest (incl. golden config-generation snapshots)
|
|
npm run gen # regenerate src/generated/* from Go (gen:zod + gen:api)
|
|
npm run build # gen:api + vite build → outputs to internal/web/dist (then rebuild Go binary to embed)
|
|
```
|
|
|
|
**Full local loop:** `cd frontend && npm run build` (refresh embedded `dist/`) → back to repo
|
|
root → `go build ./...` / `go run main.go`.
|
|
|
|
**Docker:** `docker compose up -d` (uses `Dockerfile` + `DockerEntrypoint.sh`).
|
|
|
|
**CI** (`.github/workflows/`): `ci.yml` (build/test/lint), `codeql.yml` (security scan),
|
|
`smoke.yml` (smoke tests), `mutation.yml` (mutation testing), `docker.yml` + `release.yml`
|
|
(multi-arch image + release builds), `cleanup_caches.yml`, `claude-bot.yml` (issue bot).
|
|
|
|
---
|
|
|
|
## 10. Gotchas & conventions
|
|
|
|
- **Module path is `.../v3`.** Internal imports use `github.com/mhsanaei/3x-ui/v3/internal/...`.
|
|
- **SQLite vs Postgres.** Default is SQLite at `{XUI_DB_FOLDER}/x-ui.db`. Postgres via
|
|
`XUI_DB_TYPE=postgres` + `XUI_DB_DSN`. Some SQL paths are dialect-aware (`database/dialect.go`);
|
|
test both when touching raw queries (there are `*_scale_postgres_test.go` suites).
|
|
- **`Inbound.Settings` / `StreamSettings` / `Sniffing` are raw JSON strings**, not structured
|
|
columns. Parsing/validation happens in services and the `xray` package, not in GORM.
|
|
- **Hot-reload is the default; full restart is the fallback.** Changes that look config-only
|
|
but cause a restart usually mean the diff in `xray/hot_diff.go` didn't recognize them as hot.
|
|
- **Node TLS:** remote calls honor `TlsVerifyMode` (`verify`/`skip`/`pin`/`mtls`). "Works on
|
|
skip, fails on verify/pin/mtls" → cert/fingerprint handling in `service/node.go`
|
|
(`FetchCertFingerprint`), `service/node_mtls.go`, and `runtime/tls_client.go`.
|
|
- **Restart is signal-driven.** `main.go` traps SIGHUP to restart panel+sub servers; the
|
|
in-process restart hook (`global.SetRestartHook`) funnels into the same path.
|
|
- **i18n:** backend catalogs in `internal/web/translation/` (13 locales, shared with the
|
|
frontend); frontend wiring in `frontend/src/i18n/`. Persian (`fa_IR`) is a first-class
|
|
locale (Jalali calendar via `persian-calendar-suite`).
|
|
- **Tests live next to code** (`foo.go` ↔ `foo_test.go`), plus golden snapshots in
|
|
`frontend/src/test/golden/fixtures/` for config generation — update fixtures intentionally,
|
|
not blindly, when output changes.
|