feat(clients): add inbound filter + mobile page-size control

Filter bar gets an Inbound select next to Protocol — the dropdown is
narrowed to inbounds matching the chosen protocol (or shows everything
when no protocol is picked), with remark search inside the dropdown.
Choosing a protocol clears any inbound selection that no longer fits.

Server side, ClientPageParams gains an Inbound int and ListPaged runs a
clientMatchesInbound check after the protocol filter. The selection
persists in clientsFilterState localStorage alongside the existing
search/filter/protocol entries.

Mobile clients view also grows the AntD Pagination control that was
previously only on the desktop table, so page size / page navigation
are reachable from phones.

.env.example

@@ -0,0 +1,4 @@
+XUI_DEBUG=true
+XUI_DB_FOLDER=x-ui
+XUI_LOG_FOLDER=x-ui
+XUI_BIN_FOLDER=x-ui

.github/FUNDING.yml

@@ -0,0 +1,14 @@
+# These are supported funding model platforms
+
+github: MHSanaei
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: mhsanaei
+custom: https://nowpayments.io/donation/hsanaei

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -0,0 +1,77 @@
+name: Bug report
+description: Create a report to help us improve
+title: "Bug report"
+labels: ["bug"]
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reporting a bug! Please fill out the following information.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: Describe the bug
+      description: A clear and concise description of what the bug is.
+      placeholder: My problem is...
+    validations:
+      required: true
+
+  - type: textarea
+    id: how-repeat-problem
+    attributes:
+      label: How to repeat the problem?
+      description: Sequence of actions that allow you to reproduce the bug
+      placeholder: |
+        1. Open `Inbounds` page
+        2. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-action
+    attributes:
+      label: Expected action
+      description: What's going to happen
+      placeholder: Must be...
+    validations:
+      required: false
+
+  - type: textarea
+    id: received-action
+    attributes:
+      label: Received action
+      description: What's really happening
+      placeholder: It's actually happening...
+    validations:
+      required: false
+
+  - type: input
+    id: xui-version
+    attributes:
+      label: 3x-ui Version
+      description: Which version of 3x-ui are you using?
+      placeholder: 2.X.X
+    validations:
+      required: true
+
+  - type: input
+    id: xray-version
+    attributes:
+      label: Xray-core Version
+      description: Which version of Xray-core are you using?
+      placeholder: 2.X.X
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      description: Please check all the checkboxes
+      options:
+        - label: This bug report is written entirely in English.
+          required: true
+        - label: This bug report is new and no one has reported it before me.
+          required: true

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -0,0 +1,39 @@
+name: Feature request
+description: Suggest an idea for this project
+title: "Feature request"
+labels: ["enhancement"]
+
+body:
+  - type: textarea
+    id: is-related-problem
+    attributes:
+      label: Is your feature request related to a problem?
+      description: A clear and concise description of what the problem is.
+      placeholder: I'm always frustrated when...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Describe the solution you'd like
+      description: A clear and concise description of what you want to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Describe alternatives you've considered
+      description: A clear and concise description of any alternative solutions or features you've considered.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      description: Please check all the checkboxes
+      options:
+        - label: This feature report is written entirely in English.
+          required: true

.github/ISSUE_TEMPLATE/question.yaml

@@ -0,0 +1,22 @@
+name: Question
+description: Describe this issue template's purpose here.
+title: "Question"
+labels: ["question"]
+
+body:
+  - type: textarea
+    id: question
+    attributes:
+      label: Question
+      placeholder: I have a question, ..., how can I solve it?
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      description: Please check all the checkboxes
+      options:
+        - label: This question is written entirely in English.
+          required: true

.github/copilot-instructions.md

@@ -0,0 +1,158 @@
+# 3X-UI Development Guide
+
+## Project Overview
+3X-UI is a web-based control panel for managing Xray-core servers. It's a Go application using Gin web framework with embedded static assets and SQLite database. The panel manages VPN/proxy inbounds, monitors traffic, and provides Telegram bot integration.
+
+## Architecture
+
+### Core Components
+- **main.go**: Entry point that initializes database, web server, and subscription server. Handles graceful shutdown via SIGHUP/SIGTERM signals
+- **web/**: Primary web server with Gin router, HTML templates, and static assets embedded via `//go:embed`
+- **xray/**: Xray-core process management and API communication for traffic monitoring
+- **database/**: GORM-based SQLite database with models in `database/model/`
+- **sub/**: Subscription server running alongside main web server (separate port)
+- **web/service/**: Business logic layer containing InboundService, SettingService, TgBot, etc.
+- **web/controller/**: HTTP handlers using Gin context (`*gin.Context`)
+- **web/job/**: Cron-based background jobs for traffic monitoring, CPU checks, LDAP sync
+
+### Key Architectural Patterns
+1. **Embedded Resources**: All web assets (HTML, CSS, JS, translations) are embedded at compile time using `embed.FS`:
+   - `web/assets` → `assetsFS`
+   - `web/html` → `htmlFS`
+   - `web/translation` → `i18nFS`
+
+2. **Dual Server Design**: Main web panel + subscription server run concurrently, managed by `web/global` package
+
+3. **Xray Integration**: Panel generates `config.json` for Xray binary, communicates via gRPC API for real-time traffic stats
+
+4. **Signal-Based Restart**: SIGHUP triggers graceful restart. **Critical**: Always call `service.StopBot()` before restart to prevent Telegram bot 409 conflicts
+
+5. **Database Seeders**: Uses `HistoryOfSeeders` model to track one-time migrations (e.g., password bcrypt migration)
+
+## Development Workflows
+
+### Building & Running
+```bash
+# Build (creates bin/3x-ui.exe)
+go run tasks.json → "go: build" task
+
+# Run with debug logging
+XUI_DEBUG=true go run ./main.go
+# Or use task: "go: run"
+
+# Test
+go test ./...
+```
+
+### Command-Line Operations
+The main.go accepts flags for admin tasks:
+- `-reset` - Reset all panel settings to defaults
+- `-show` - Display current settings (port, paths)
+- Use these by running the binary directly, not via web interface
+
+### Database Management
+- DB path: Configured via `config.GetDBPath()`, typically `/etc/x-ui/x-ui.db`
+- Models: Located in `database/model/model.go` - Auto-migrated on startup
+- Seeders: Use `HistoryOfSeeders` to prevent re-running migrations
+- Default credentials: admin/admin (hashed with bcrypt)
+
+### Telegram Bot Development
+- Bot instance in `web/service/tgbot.go` (3700+ lines)
+- Uses `telego` library with long polling
+- **Critical Pattern**: Must call `service.StopBot()` before any server restart to prevent 409 bot conflicts
+- Bot handlers use `telegohandler.BotHandler` for routing
+- i18n via embedded `i18nFS` passed to bot startup
+
+## Code Conventions
+
+### Service Layer Pattern
+Services inject dependencies (like xray.XrayAPI) and operate on GORM models:
+```go
+type InboundService struct {
+    xrayApi xray.XrayAPI
+}
+
+func (s *InboundService) GetInbounds(userId int) ([]*model.Inbound, error) {
+    // Business logic here
+}
+```
+
+### Controller Pattern
+Controllers use Gin context and inherit from BaseController:
+```go
+func (a *InboundController) getInbounds(c *gin.Context) {
+    // Use I18nWeb(c, "key") for translations
+    // Check auth via checkLogin middleware
+}
+```
+
+### Configuration Management
+- Environment vars: `XUI_DEBUG`, `XUI_LOG_LEVEL`, `XUI_MAIN_FOLDER`
+- Config embedded files: `config/version`, `config/name`
+- Use `config.GetLogLevel()`, `config.GetDBPath()` helpers
+
+### Internationalization
+- Translation files: `web/translation/<lang>.json` (one nested-namespace file per locale,
+  e.g. `en-US.json`). Vue SPA imports these via `import.meta.glob` from `frontend/src/i18n/`,
+  and the Go binary embeds the same files via `web/web.go`'s `//go:embed translation/*`.
+- Access from Go via `locale.I18n(locale.Web, "pages.login.loginAgain")` (see
+  `web/locale/locale.go`); access from Vue via `useI18n()` and `t('pages.login.loginAgain')`.
+- Use `locale.I18nType` enum (Web, Bot).
+
+## External Dependencies & Integration
+
+### Xray-core
+- Binary management: Download platform-specific binary (`xray-{os}-{arch}`) to bin folder
+- Config generation: Panel creates `config.json` dynamically from inbound/outbound settings
+- Process control: Start/stop via `xray/process.go`
+- gRPC API: Real-time stats via `xray/api.go` using `google.golang.org/grpc`
+
+### Critical External Paths
+- Xray binary: `{bin_folder}/xray-{os}-{arch}`
+- Xray config: `{bin_folder}/config.json`
+- GeoIP/GeoSite: `{bin_folder}/geoip.dat`, `geosite.dat`
+- Logs: `{log_folder}/3xipl.log`, `3xipl-banned.log`
+
+### Job Scheduling
+Uses `robfig/cron/v3` for periodic tasks:
+- Traffic monitoring: `xray_traffic_job.go`
+- CPU alerts: `check_cpu_usage.go`
+- IP tracking: `check_client_ip_job.go`
+- LDAP sync: `ldap_sync_job.go`
+
+Jobs registered in `web/web.go` during server initialization
+
+## Deployment & Scripts
+
+### Installation Script Pattern
+Both `install.sh` and `x-ui.sh` follow these patterns:
+- Multi-distro support via `$release` variable (ubuntu, debian, centos, arch, etc.)
+- Port detection with `is_port_in_use()` using ss/netstat/lsof
+- Systemd service management with distro-specific unit files (`.service.debian`, `.service.arch`, `.service.rhel`)
+
+### Docker Build
+Multi-stage Dockerfile:
+1. **Builder**: CGO-enabled build, runs `DockerInit.sh` to download Xray binary
+2. **Final**: Alpine-based with fail2ban pre-configured
+
+### Key File Locations (Production)
+- Binary: `/usr/local/x-ui/`
+- Database: `/etc/x-ui/x-ui.db`
+- Logs: `/var/log/x-ui/`
+- Service: `/etc/systemd/system/x-ui.service.*`
+
+## Testing & Debugging
+- Set `XUI_DEBUG=true` for detailed logging
+- Check Xray process: `x-ui.sh` script provides menu for status/logs
+- Database inspection: Direct SQLite access to x-ui.db
+- Traffic debugging: Check `3xipl.log` for IP limit tracking
+- Telegram bot: Logs show bot initialization and command handling
+
+## Common Gotchas
+1. **Bot Restart**: Always stop Telegram bot before server restart to avoid 409 conflict
+2. **Embedded Assets**: Changes to HTML/CSS require recompilation (not hot-reload)
+3. **Password Migration**: Seeder system tracks bcrypt migration - check `HistoryOfSeeders` table
+4. **Port Binding**: Subscription server uses different port from main panel
+5. **Xray Binary**: Must match OS/arch exactly - managed by installer scripts
+6. **Session Management**: Uses `gin-contrib/sessions` with cookie store
+7. **IP Limitation**: Implements "last IP wins" - when client exceeds LimitIP, oldest connections are automatically disconnected via Xray API to allow newest IPs

.github/dependabot.yml

@@ -1,10 +1,19 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
 version: 2
 updates:
-  - package-ecosystem: "gomod" # See documentation for possible values
+  - package-ecosystem: "github-actions" # See documentation for possible values
     directory: "/" # Location of package manifests
     schedule:
-      interval: "daily"
-  - package-ecosystem: "github-actions"
+      interval: "weekly"
+  - package-ecosystem: "gomod"
     directory: "/"
     schedule:
-      interval: "daily"
+      interval: "weekly"
+  - package-ecosystem: "npm"
+    directory: "/frontend"
+    schedule:
+      interval: "weekly"

.github/pull_request_template.yml

@@ -0,0 +1,20 @@
+## What is the pull request?
+
+<!-- Briefly describe the changes introduced by this pull request -->
+
+## Which part of the application is affected by the change?
+
+- [ ] Frontend
+- [ ] Backend
+
+## Type of Changes
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactoring
+- [ ] Other
+
+## Screenshots
+
+<!-- Add screenshots to illustrate the changes -->
+<!-- Remove this section if it is not applicable. -->

.github/workflows/ci.yml

@@ -0,0 +1,89 @@
+name: CI
+
+on:
+  pull_request:
+    paths:
+      - "**.go"
+      - "go.mod"
+      - "go.sum"
+      - "**.js"
+      - "**.mjs"
+      - "**.cjs"
+      - "**.ts"
+      - "**.html"
+      - "**.css"
+      - "frontend/package.json"
+      - "frontend/package-lock.json"
+      - ".nvmrc"
+  push:
+    branches:
+      - main
+    paths:
+      - "**.go"
+      - "go.mod"
+      - "go.sum"
+      - "**.js"
+      - "**.mjs"
+      - "**.cjs"
+      - "**.ts"
+      - "**.html"
+      - "**.css"
+      - "frontend/package.json"
+      - "frontend/package-lock.json"
+      - ".nvmrc"
+
+permissions:
+  contents: read
+
+jobs:
+  go-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+          cache: true
+      - name: Stub web/dist for go:embed
+        run: mkdir -p web/dist && touch web/dist/.gitkeep
+      - name: Test
+        run: |
+          go list ./... | grep -v '/frontend/node_modules/' > /tmp/go-packages.txt
+          go test $(cat /tmp/go-packages.txt)
+
+  govulncheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+          cache: true
+      - name: Stub web/dist for go:embed
+        run: mkdir -p web/dist && touch web/dist/.gitkeep
+      - name: Install govulncheck
+        run: go install golang.org/x/vuln/cmd/govulncheck@latest
+      - name: Run govulncheck
+        run: govulncheck ./...
+
+  frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - name: Install
+        run: npm ci
+        working-directory: frontend
+      - name: Lint
+        run: npm run lint
+        working-directory: frontend
+      - name: Build
+        run: npm run build
+        working-directory: frontend
+      - name: Audit
+        run: npm audit --audit-level=high
+        working-directory: frontend

.github/workflows/cleanup_caches.yml

@@ -0,0 +1,31 @@
+name: Cleanup Caches
+on:
+  schedule:
+    - cron: "0 3 * * *" # every day
+  workflow_dispatch:
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write
+    steps:
+      - name: Delete caches older than 1 day
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          CUTOFF_DATE=$(date -d "1 days ago" -Ins --utc | sed 's/+0000/Z/')
+          echo "Deleting caches older than: $CUTOFF_DATE"
+
+          CACHE_IDS=$(gh api --paginate repos/${{ github.repository }}/actions/caches \
+            --jq ".actions_caches[] | select(.last_accessed_at < \"$CUTOFF_DATE\") | .id" 2>/dev/null)
+
+          if [ -z "$CACHE_IDS" ]; then
+            echo "No old caches found to delete."
+          else
+            echo "$CACHE_IDS" | while read CACHE_ID; do
+              echo "Deleting cache: $CACHE_ID"
+              gh api -X DELETE repos/${{ github.repository }}/actions/caches/$CACHE_ID
+            done
+            echo "Old caches deleted successfully."
+          fi

.github/workflows/codeql.yml

@@ -0,0 +1,82 @@
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches:
+      - main
+    tags-ignore:
+      - "v*"
+    paths:
+      - "**.go"
+      - "go.mod"
+      - "go.sum"
+      - "**.js"
+      - "**.mjs"
+      - "**.cjs"
+      - "**.ts"
+      - "frontend/package-lock.json"
+  pull_request:
+    paths:
+      - "**.go"
+      - "go.mod"
+      - "go.sum"
+      - "**.js"
+      - "**.mjs"
+      - "**.cjs"
+      - "**.ts"
+      - "frontend/package-lock.json"
+  schedule:
+    - cron: "18 2 * * 2"
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    env:
+      CODEQL_ACTION_FILE_COVERAGE_ON_PRS: true
+    permissions:
+      security-events: write
+      packages: read
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: actions
+            build-mode: none
+          - language: go
+            build-mode: autobuild
+          - language: javascript-typescript
+            build-mode: none
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        if: matrix.language == 'go'
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Build frontend bundle
+        if: matrix.language == 'go'
+        run: |
+          npm ci
+          npm run build
+        working-directory: frontend
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{matrix.language}}"

.github/workflows/docker.yml

@@ -0,0 +1,60 @@
+name: Release 3X-UI for Docker
+
+permissions:
+  contents: read
+  packages: write
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: true
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: |
+            hsanaeii/3x-ui
+            ghcr.io/mhsanaei/3x-ui
+          tags: |
+            type=ref,event=branch
+            type=ref,event=tag
+            type=semver,pattern={{version}}
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKER_HUB_USERNAME }}
+          password: ${{ secrets.DOCKER_HUB_TOKEN }}
+
+      - name: Login to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64/v8,linux/arm/v7,linux/arm/v6,linux/386
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.github/workflows/release.yml

@@ -1,43 +1,289 @@
-name: Release 3X-ui
+name: Release 3X-UI
+
 on:
   workflow_dispatch:
+  push:
+    branches:
+      - "**"
+    tags:
+      - "v*.*.*"
+    paths:
+      - "**.js"
+      - "**.css"
+      - "**.html"
+      - "**.sh"
+      - "**.go"
+      - "go.mod"
+      - "go.sum"
+      - "x-ui.service.debian"
+      - "x-ui.service.arch"
+      - "x-ui.service.rhel"
+  pull_request:
+    paths:
+      - "**.js"
+      - "**.css"
+      - "**.html"
+      - "**.sh"
+      - "**.go"
+      - "go.mod"
+      - "go.sum"
+      - "x-ui.service.debian"
+      - "x-ui.service.arch"
+      - "x-ui.service.rhel"
+
 jobs:
- linuxamd64build:
-    name: build x-ui amd64 version
-    runs-on: ubuntu-20.04
+  build:
+    permissions:
+      contents: write
+    strategy:
+      matrix:
+        platform:
+          - amd64
+          - arm64
+          - armv7
+          - armv6
+          - 386
+          - armv5
+          - s390x
+    runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3.3.0
-      - name: Set up Go
-        uses: actions/setup-go@v3.5.0
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
         with:
-          go-version: '1.20.1'
-      - name: build linux amd64 version
+          go-version-file: go.mod
+          check-latest: true
+
+      # Frontend dist must be built BEFORE go build — Go's //go:embed
+      # all:dist directive in web/web.go requires web/dist/ to exist
+      # at compile time. web/dist/ is .gitignored, so on a fresh CI
+      # checkout it doesn't exist until vite emits it.
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Build frontend bundle
         run: |
-          CGO_ENABLED=1 GOOS=linux GOARCH=amd64 go build -o xui-release -v main.go
+          npm ci
+          npm run build
+        working-directory: frontend
+
+      - name: Build 3X-UI
+        run: |
+          export CGO_ENABLED=1
+          export GOOS=linux
+          export GOARCH=${{ matrix.platform }}
+          # Use Bootlin prebuilt cross-toolchains (musl 1.2.5 in stable series)
+          case "${{ matrix.platform }}" in
+            amd64) BOOTLIN_ARCH="x86-64" ;;
+            arm64) BOOTLIN_ARCH="aarch64" ;;
+            armv7) BOOTLIN_ARCH="armv7-eabihf"; export GOARCH=arm GOARM=7 ;;
+            armv6) BOOTLIN_ARCH="armv6-eabihf"; export GOARCH=arm GOARM=6 ;;
+            armv5) BOOTLIN_ARCH="armv5-eabi"; export GOARCH=arm GOARM=5 ;;
+            386) BOOTLIN_ARCH="x86-i686" ;;
+            s390x) BOOTLIN_ARCH="s390x-z13" ;;
+          esac
+          echo "Resolving Bootlin musl toolchain for arch=$BOOTLIN_ARCH (platform=${{ matrix.platform }})"
+          TARBALL_BASE="https://toolchains.bootlin.com/downloads/releases/toolchains/$BOOTLIN_ARCH/tarballs/"
+          TARBALL_URL=$(curl -fsSL "$TARBALL_BASE" | grep -oE "${BOOTLIN_ARCH}--musl--stable-[^\"]+\\.tar\\.xz" | sort -r | head -n1)
+          [ -z "$TARBALL_URL" ] && { echo "Failed to locate Bootlin musl toolchain for arch=$BOOTLIN_ARCH" >&2; exit 1; }
+          echo "Downloading: $TARBALL_URL"
+          cd /tmp
+          curl -fL -sS -o "$(basename "$TARBALL_URL")" "$TARBALL_BASE/$TARBALL_URL"
+          tar -xf "$(basename "$TARBALL_URL")"
+          TOOLCHAIN_DIR=$(find . -maxdepth 1 -type d -name "${BOOTLIN_ARCH}--musl--stable-*" | head -n1)
+          export PATH="$(realpath "$TOOLCHAIN_DIR")/bin:$PATH"
+          export CC=$(realpath "$(find "$TOOLCHAIN_DIR/bin" -name '*-gcc.br_real' -type f -executable | head -n1)")
+          [ -z "$CC" ] && { echo "No gcc.br_real found in $TOOLCHAIN_DIR/bin" >&2; exit 1; }
+          cd -
+          go build -ldflags "-w -s -linkmode external -extldflags '-static'" -o xui-release -v main.go
+          file xui-release
+          ldd xui-release || echo "Static binary confirmed"
+
           mkdir x-ui
-          cp xui-release x-ui/xui-release
-          cp x-ui.service x-ui/x-ui.service
-          cp x-ui.sh x-ui/x-ui.sh
-          cd x-ui
-          mv xui-release x-ui
-          mkdir bin
-          cd bin
-          wget https://github.com/mhsanaei/Xray-core/releases/latest/download/Xray-linux-64.zip
-          unzip Xray-linux-64.zip
-          rm -f Xray-linux-64.zip geoip.dat geosite.dat
-          wget https://github.com/Loyalsoldier/v2ray-rules-dat/releases/latest/download/geoip.dat
-          wget https://github.com/Loyalsoldier/v2ray-rules-dat/releases/latest/download/geosite.dat
-          mv xray xray-linux-amd64
-          cd ..
-          cd ..
-      - name: package
-        run: tar -zcvf x-ui-linux-amd64.tar.gz x-ui
-      - name: upload
-        uses: svenstaro/upload-release-action@2.5.0
+          cp xui-release x-ui/
+          cp x-ui.service.debian x-ui/
+          cp x-ui.service.arch x-ui/
+          cp x-ui.service.rhel x-ui/
+          cp x-ui.sh x-ui/
+          mv x-ui/xui-release x-ui/x-ui
+          mkdir x-ui/bin
+          cd x-ui/bin
+
+          # Download dependencies
+          Xray_URL="https://github.com/XTLS/Xray-core/releases/download/v26.5.9/"
+          if [ "${{ matrix.platform }}" == "amd64" ]; then
+            wget -q ${Xray_URL}Xray-linux-64.zip
+            unzip Xray-linux-64.zip
+            rm -f Xray-linux-64.zip
+          elif [ "${{ matrix.platform }}" == "arm64" ]; then
+            wget -q ${Xray_URL}Xray-linux-arm64-v8a.zip
+            unzip Xray-linux-arm64-v8a.zip
+            rm -f Xray-linux-arm64-v8a.zip
+          elif [ "${{ matrix.platform }}" == "armv7" ]; then
+            wget -q ${Xray_URL}Xray-linux-arm32-v7a.zip
+            unzip Xray-linux-arm32-v7a.zip
+            rm -f Xray-linux-arm32-v7a.zip
+          elif [ "${{ matrix.platform }}" == "armv6" ]; then
+            wget -q ${Xray_URL}Xray-linux-arm32-v6.zip
+            unzip Xray-linux-arm32-v6.zip
+            rm -f Xray-linux-arm32-v6.zip
+          elif [ "${{ matrix.platform }}" == "386" ]; then
+            wget -q ${Xray_URL}Xray-linux-32.zip
+            unzip Xray-linux-32.zip
+            rm -f Xray-linux-32.zip
+          elif [ "${{ matrix.platform }}" == "armv5" ]; then
+            wget -q ${Xray_URL}Xray-linux-arm32-v5.zip
+            unzip Xray-linux-arm32-v5.zip
+            rm -f Xray-linux-arm32-v5.zip
+          elif [ "${{ matrix.platform }}" == "s390x" ]; then
+            wget -q ${Xray_URL}Xray-linux-s390x.zip
+            unzip Xray-linux-s390x.zip
+            rm -f Xray-linux-s390x.zip
+          fi
+          rm -f geoip.dat geosite.dat
+          wget -q https://github.com/Loyalsoldier/v2ray-rules-dat/releases/latest/download/geoip.dat
+          wget -q https://github.com/Loyalsoldier/v2ray-rules-dat/releases/latest/download/geosite.dat
+          wget -q -O geoip_IR.dat https://github.com/chocolate4u/Iran-v2ray-rules/releases/latest/download/geoip.dat
+          wget -q -O geosite_IR.dat https://github.com/chocolate4u/Iran-v2ray-rules/releases/latest/download/geosite.dat
+          wget -q -O geoip_RU.dat https://github.com/runetfreedom/russia-v2ray-rules-dat/releases/latest/download/geoip.dat
+          wget -q -O geosite_RU.dat https://github.com/runetfreedom/russia-v2ray-rules-dat/releases/latest/download/geosite.dat
+          mv xray xray-linux-${{ matrix.platform }}
+          cd ../..
+
+      - name: Package
+        run: tar -zcvf x-ui-linux-${{ matrix.platform }}.tar.gz x-ui
+
+      - name: Upload files to Artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: x-ui-linux-${{ matrix.platform }}
+          path: ./x-ui-linux-${{ matrix.platform }}.tar.gz
+
+      - name: Upload files to GH release
+        uses: svenstaro/upload-release-action@v2
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
         with:
           repo_token: ${{ secrets.GITHUB_TOKEN }}
-          tag: ${{ github.ref }}
-          file: x-ui-linux-amd64.tar.gz
-          asset_name: x-ui-linux-amd64.tar.gz
-          prerelease: true
+          tag: ${{ github.ref_name }}
+          file: x-ui-linux-${{ matrix.platform }}.tar.gz
+          asset_name: x-ui-linux-${{ matrix.platform }}.tar.gz
           overwrite: true
+          prerelease: true
+
+  # =================================
+  #  Windows Build
+  # =================================
+  build-windows:
+    name: Build for Windows
+    permissions:
+      contents: write
+    strategy:
+      matrix:
+        platform:
+          - amd64
+    runs-on: windows-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+          check-latest: true
+
+      # Frontend dist must be built BEFORE go build — see comment on the
+      # Linux job above. This step is identical except npm runs on the
+      # Windows runner here.
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Build frontend bundle
+        shell: pwsh
+        run: |
+          npm ci
+          npm run build
+        working-directory: frontend
+
+      - name: Install MSYS2
+        uses: msys2/setup-msys2@v2
+        with:
+          msystem: MINGW64
+          update: true
+          install: >-
+            mingw-w64-x86_64-gcc
+            mingw-w64-x86_64-sqlite3
+            mingw-w64-x86_64-pkg-config
+
+      - name: Build 3X-UI for Windows (CGO)
+        shell: msys2 {0}
+        run: |
+          export PATH="/c/hostedtoolcache/windows/go/$(ls /c/hostedtoolcache/windows/go | sort -V | tail -n1)/x64/bin:$PATH"
+
+          export CGO_ENABLED=1
+          export GOOS=windows
+          export GOARCH=amd64
+          export CC=x86_64-w64-mingw32-gcc
+
+          which go
+          go version
+          gcc --version
+
+          go build -ldflags "-w -s" -o xui-release.exe -v main.go
+
+      - name: Copy and download resources
+        shell: pwsh
+        run: |
+          mkdir x-ui
+          Copy-Item xui-release.exe x-ui\x-ui.exe
+          mkdir x-ui\bin
+          cd x-ui\bin
+
+          # Download Xray for Windows
+          $Xray_URL = "https://github.com/XTLS/Xray-core/releases/download/v26.5.9/"
+          Invoke-WebRequest -Uri "${Xray_URL}Xray-windows-64.zip" -OutFile "Xray-windows-64.zip"
+          Expand-Archive -Path "Xray-windows-64.zip" -DestinationPath .
+          Remove-Item "Xray-windows-64.zip"
+          Remove-Item geoip.dat, geosite.dat -ErrorAction SilentlyContinue
+          Invoke-WebRequest -Uri "https://github.com/Loyalsoldier/v2ray-rules-dat/releases/latest/download/geoip.dat" -OutFile "geoip.dat"
+          Invoke-WebRequest -Uri "https://github.com/Loyalsoldier/v2ray-rules-dat/releases/latest/download/geosite.dat" -OutFile "geosite.dat"
+          Invoke-WebRequest -Uri "https://github.com/chocolate4u/Iran-v2ray-rules/releases/latest/download/geoip.dat" -OutFile "geoip_IR.dat"
+          Invoke-WebRequest -Uri "https://github.com/chocolate4u/Iran-v2ray-rules/releases/latest/download/geosite.dat" -OutFile "geosite_IR.dat"
+          Invoke-WebRequest -Uri "https://github.com/runetfreedom/russia-v2ray-rules-dat/releases/latest/download/geoip.dat" -OutFile "geoip_RU.dat"
+          Invoke-WebRequest -Uri "https://github.com/runetfreedom/russia-v2ray-rules-dat/releases/latest/download/geosite.dat" -OutFile "geosite_RU.dat"
+          Rename-Item xray.exe xray-windows-amd64.exe
+          cd ..
+          Copy-Item -Path ..\windows_files\* -Destination . -Recurse
+          cd ..
+
+      - name: Package to Zip
+        shell: pwsh
+        run: |
+          Compress-Archive -Path .\x-ui -DestinationPath "x-ui-windows-amd64.zip"
+
+      - name: Upload files to Artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: x-ui-windows-amd64
+          path: ./x-ui-windows-amd64.zip
+
+      - name: Upload files to GH release
+        uses: svenstaro/upload-release-action@v2
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+        with:
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ github.ref_name }}
+          file: x-ui-windows-amd64.zip
+          asset_name: x-ui-windows-amd64.zip
+          overwrite: true
+          prerelease: true

.gitignore

@@ -1,12 +1,46 @@
-.idea
-tmp
+# Ignore editor and IDE settings
+.idea/
+.vscode/
+.claude/
+.cache/
+.sync*
+
+# Ignore log files
+*.log
+
+# Ignore temporary files
+tmp/
+*.tar.gz
+
+# Ignore build and distribution directories
+backup/
 bin/
 dist/
-x-ui-*.tar.gz
-/x-ui
-/release.sh
-.sync*
-main
+!web/dist/
+web/dist/*
+!web/dist/.gitkeep
 release/
-access.log
-.cache
+node_modules/
+
+# Ignore compiled binaries
+main
+
+# Ignore script and executable files
+/release.sh
+/x-ui
+
+# Ignore OS specific files
+.DS_Store
+Thumbs.db
+
+# Ignore Go build files
+*.exe
+x-ui.db
+x-ui.db-shm
+x-ui.db-wal
+
+# Ignore Docker specific files
+docker-compose.override.yml
+
+# Ignore .env (Environment Variables) file
+.env

.nvmrc

@@ -0,0 +1 @@
+22

.vscode/launch.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "vscode://schemas/launch",
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Run 3x-ui (Debug)",
+      "type": "go",
+      "request": "launch",
+      "mode": "auto",
+      "program": "${workspaceFolder}",
+      "cwd": "${workspaceFolder}",
+      "env": {
+        "XUI_DEBUG": "true",
+        "XUI_DB_FOLDER": "x-ui",
+        "XUI_LOG_FOLDER": "x-ui",
+        "XUI_BIN_FOLDER": "x-ui"
+      },
+      "console": "integratedTerminal"
+    },
+  ]
+}

.vscode/tasks.json

@@ -0,0 +1,89 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "go: build",
+      "type": "shell",
+      "command": "go",
+      "args": [
+        "build",
+        "-o",
+        "bin/3x-ui.exe",
+        "./main.go"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "problemMatcher": [
+        "$go"
+      ],
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      }
+    },
+    {
+      "label": "go: run",
+      "type": "shell",
+      "command": "go",
+      "args": [
+        "run",
+        "./main.go"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}",
+        "env": {
+          "XUI_DEBUG": "true"
+        }
+      },
+      "problemMatcher": [
+        "$go"
+      ]
+    },
+    {
+      "label": "go: test",
+      "type": "shell",
+      "command": "go",
+      "args": [
+        "test",
+        "./..."
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "problemMatcher": [
+        "$go"
+      ],
+      "group": "test"
+    },
+    {
+      "label": "go: vet",
+      "type": "shell",
+      "command": "go",
+      "args": [
+        "vet",
+        "./..."
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "problemMatcher": [
+        "$go"
+      ]
+    },
+    {
+      "label": "go: fmt",
+      "type": "shell",
+      "command": "gofmt",
+      "args": [
+        "-l",
+        "-w",
+        "."
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "problemMatcher": []
+    }
+  ]
+}

CONTRIBUTING.md

@@ -0,0 +1,226 @@
+# Contributing
+
+Thanks for taking the time to contribute to 3x-ui. This guide gets a development panel running locally and explains the conventions the project follows so changes land cleanly.
+
+## Prerequisites
+
+- **Go 1.26+** (the version pinned in `go.mod`)
+- **Node.js 22+** and npm 10+ (for the React frontend)
+- **Git**
+- **A C compiler** — required by the CGo SQLite driver (`github.com/mattn/go-sqlite3`). Linux and macOS already ship one; for Windows see below.
+
+### Windows: MinGW-w64
+
+`go build` on Windows fails with `cgo: C compiler "gcc" not found` until a GCC toolchain is installed. Two options — pick whichever fits.
+
+**Option A — standalone zip (fastest, no package manager)**
+
+1. Download the latest build from <https://github.com/niXman/mingw-builds-binaries/releases>. For most setups, pick a release named:
+   ```
+   x86_64-<version>-release-posix-seh-ucrt-rt_<n>-rev<m>.7z
+   ```
+   (64-bit, POSIX threads, SEH exceptions, UCRT runtime — matches modern Windows defaults.)
+2. Extract it somewhere stable, e.g. `C:\mingw64\`.
+3. Add `C:\mingw64\bin` to the **Windows** `PATH` (System Properties → Environment Variables → Path → New).
+4. Open a fresh terminal and confirm:
+   ```powershell
+   gcc --version
+   ```
+
+**Option B — MSYS2 (when a Unix shell is also useful)**
+
+1. Install MSYS2 from <https://www.msys2.org/>.
+2. Open the **MSYS2 UCRT64** shell from the Start menu and update once:
+   ```bash
+   pacman -Syu
+   ```
+3. Install the UCRT64 toolchain:
+   ```bash
+   pacman -S --needed mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-pkg-config
+   ```
+4. Add `C:\msys64\ucrt64\bin` to the Windows `PATH`.
+5. Verify with `gcc --version` in a fresh terminal.
+
+After either path, `go build ./...` and `go run .` work normally.
+
+> **Why MinGW-w64 over MSVC:** `mattn/go-sqlite3` officially supports GCC, builds are faster on Windows, and the toolchain does not require a Visual Studio install. If Visual Studio Build Tools are already present that works too — just make sure `CC=cl` is **not** set in the environment.
+
+Cross-building the Linux SQLite target from Windows (or vice versa) requires a separate cross-compiler and is out of scope here; build natively on the target OS.
+
+## First-time setup
+
+```bash
+git clone https://github.com/MHSanaei/3x-ui.git
+cd 3x-ui
+
+cp .env.example .env
+
+mkdir x-ui
+
+go mod download
+
+cd frontend
+npm install
+npm run build
+cd ..
+```
+
+`.env.example` ships with defaults that keep the database, logs, and xray binary inside the local `x-ui/` folder so nothing escapes the project directory:
+
+```
+XUI_DEBUG=true
+XUI_DB_FOLDER=x-ui
+XUI_LOG_FOLDER=x-ui
+XUI_BIN_FOLDER=x-ui
+```
+
+Drop the xray binary (`xray-windows-amd64.exe` on Windows, `xray-linux-amd64` on Linux, etc.) plus the matching `geoip.dat` and `geosite.dat` files into `x-ui/`. The easiest source is a [released Xray-core build](https://github.com/XTLS/Xray-core/releases). On Windows, `wintun.dll` is also required for testing TUN inbounds.
+
+## Running
+
+```bash
+go run .
+```
+
+Open [http://localhost:2053](http://localhost:2053) and log in with `admin` / `admin`. Credentials must be changed on first login.
+
+### Inside VS Code
+
+The repo ships a launch profile in `.vscode/launch.json` (gitignored — copy from the snippet below if absent):
+
+```jsonc
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Run 3x-ui (Debug)",
+      "type": "go",
+      "request": "launch",
+      "mode": "auto",
+      "program": "${workspaceFolder}",
+      "cwd": "${workspaceFolder}",
+      "env": {
+        "XUI_DEBUG": "true",
+        "XUI_DB_FOLDER": "x-ui",
+        "XUI_LOG_FOLDER": "x-ui",
+        "XUI_BIN_FOLDER": "x-ui"
+      },
+      "console": "integratedTerminal"
+    }
+  ]
+}
+```
+
+## Working on the frontend
+
+The panel UI is a **React 19 + Ant Design 6 + TypeScript** app under `frontend/`, built with Vite 8. The sections below cover the architecture, the conventions, and the two dev workflows.
+
+### Architecture
+
+The frontend is a **multi-page application**, not a SPA. Every panel route (`/panel`, `/panel/inbounds`, `/panel/clients`, `/panel/xray`, `/panel/settings`, `/panel/nodes`, `/panel/api-docs`, `/panel/sub`, plus `login`) has its own HTML entry in `frontend/*.html` and its own bootstrap in `src/entries/<page>.tsx`. Vite emits each entry into `web/dist/`, and the Go binary embeds that directory at compile time via `embed.FS`. Each panel navigation is a real document load, but every per-page bundle is small enough to keep the experience responsive. There is no React Router and no global store; the surface area does not justify either.
+
+### State and data flow
+
+- **No global store.** State lives in the page that owns it. Cross-page data (settings, current user, theme) is re-fetched on each page load — the backend is local and responses are inexpensive.
+- **Hooks** in `src/hooks/` encapsulate reactive logic worth sharing inside a page (`useTheme`, `useStatus`, `useNodes`, `useWebSocket`, `useDatepicker`, …). Prefer extending an existing hook over introducing a new global.
+- **Domain models** in `src/models/` (`Inbound`, `DBInbound`, `Outbound`, `Status`, …) own the protocol-specific logic — link generation, settings JSON shape, TLS/Reality stream handling. React components stay declarative; they ask the model "what is my link?" and render the answer.
+- **HTTP** goes through `src/utils/index.js`'s `HttpUtil`, a thin Axios wrapper that handles CSRF, response toasts, and a `silent: true` opt-out for bulk operations that would otherwise spam toasts. The Axios setup itself lives in `src/api/axios-init.js`.
+
+### i18n
+
+Locale strings live in `web/translation/<locale>.json`, **not** under `frontend/`. The Go binary embeds the same JSON and serves it to both backend templates and `react-i18next` (initialized in `src/i18n/react.ts`). When a new English key is added it must also land in **every** non-English locale — missing keys do not break the build, they just render the raw key in the UI.
+
+### Two dev workflows
+
+| Goal | Command |
+|------|---------|
+| Iterate on UI changes with HMR | `cd frontend && npm run dev` (Vite on `:5173`, proxies `/panel/*` and `/api/*` to the Go panel on `:2053`). Start the Go panel first. |
+| Verify what end users actually see | `cd frontend && npm run build`, then `go run .`. The Go binary serves the built bundle — embedded in release mode, off disk in debug mode. |
+
+The Vite dev proxy rewrites the sidebar's production-style links (`/panel`, `/panel/inbounds`, `/panel/clients`, …) to the matching Vite-served HTML, so navigation behaves identically to production without round-tripping through Go. The allowlist lives in `MIGRATED_ROUTES` in `vite.config.js` — register every new page there.
+
+> **`XUI_DEBUG=true` gotcha** — in debug mode the panel serves HTML from the embedded FS (frozen at the last `go build` / `go run`) but JS/CSS off disk. Re-running `npm run build` without restarting Go leaves the embedded HTML pointing at the *old* hashed asset names, producing a blank page with 404s in the console. Always restart `go run .` after a frontend rebuild.
+
+### Adding a new page
+
+1. Create `frontend/<page>.html` (copy an existing entry and adjust the title and the imported `<script type="module" src="/src/entries/<page>.tsx">`).
+2. Create `src/entries/<page>.tsx` — mount the page with `createRoot(document.getElementById('app')!).render(...)`, wrapped in the shared `ConfigProvider` for AntD theming and i18n.
+3. Create the page component under `src/pages/<page>/<Page>.tsx` (kebab-case folder, PascalCase component).
+4. Register the entry in `rollupOptions.input` inside `vite.config.js`.
+5. If the page is reachable from the sidebar at `/panel/<route>`, add `<route>` to `MIGRATED_ROUTES` so dev-mode navigation works.
+6. Wire a Go controller route that calls `serveDistPage(c, "<page>.html")` to serve the embedded HTML in production.
+
+### Conventions
+
+- **TypeScript strict mode** — all new code in `.ts` / `.tsx`. Run `npm run typecheck` (`tsc --noEmit`) before pushing. The path alias `@/*` resolves to `src/*`.
+- **Ant Design 6** is the only UI kit — no Tailwind, no shadcn. A previous attempt to migrate was rolled back. Small, targeted UX tweaks beat sweeping rewrites; raise broader visual changes for discussion before implementing.
+- **Function components + hooks** everywhere. No class components.
+- **No `//` line comments** in committed JS/TS/Vue/Go. HTML `<!-- ... -->` is fine for template structure. Names should carry the meaning; rename rather than annotate. Comments are reserved for the *why*, and only when the reason is surprising.
+- **RTL is a first-class concern.** Persian and Arabic users matter — RTL is enabled through AntD's `ConfigProvider direction="rtl"`. When writing Persian text in toasts or labels, isolate code identifiers on their own lines so RTL reading flows.
+- **Do not break link generation.** Share-link generation has two paths: the **inbounds page** (`InboundsPage.tsx` → `checkFallback()`) and the **clients page** (`/panel/api/clients/subLinks/:subId` → backend `GetSubs`). Exercise both whenever URL generation, fallback projection, or TLS handling changes.
+- **Vite is pinned** to `8.0.13`. Do not bump to `8.0.14+` — the esbuild dep-optimizer in those builds breaks i18n loading in dev mode.
+
+### Project layout
+
+```
+frontend/
+├── *.html                 — Vite entry HTML, one per panel route
+├── tsconfig.json          — strict, jsx: "react-jsx", paths "@/*" → "src/*"
+├── eslint.config.js       — ESLint 10 flat config (@eslint/js + typescript-eslint + react-hooks)
+├── vite.config.js
+└── src/
+    ├── entries/           — per-page bootstrap (createRoot + render)
+    ├── pages/             — one folder per route (index, login, inbounds, clients, xray, nodes, settings, api-docs, sub)
+    ├── components/        — cross-page React components (AppSidebar, DateTimePicker, FinalMaskForm, JsonEditor, …)
+    ├── hooks/             — reusable hooks (useTheme, useStatus, useNodes, useWebSocket, useDatepicker, …)
+    ├── api/               — Axios setup + CSRF interceptor + WebSocket client
+    ├── i18n/              — react-i18next bootstrap (JSON lives in web/translation/)
+    ├── models/            — Inbound, DBInbound, Outbound, Status, reality-targets, …
+    ├── styles/            — shared CSS (page-cards, …)
+    └── utils/             — HttpUtil, ObjectUtil, LanguageManager, RandomUtil, SizeFormatter, …
+```
+
+For deeper notes on the frontend toolchain see [`frontend/README.md`](frontend/README.md).
+
+## Project layout
+
+| Path | Contents |
+|------|----------|
+| `main.go` | Process entry point, CLI subcommands, signal handling |
+| `web/` | Gin HTTP server, controllers, services, embedded frontend assets |
+| `frontend/` | React + Ant Design 6 + TypeScript source for the panel UI |
+| `database/` | GORM models, migrations, seeders (SQLite / PostgreSQL) |
+| `xray/` | Xray-core process lifecycle and gRPC API client |
+| `sub/` | Subscription endpoints (raw, JSON, Clash) |
+| `config/` | Environment-variable helpers, paths, defaults |
+| `x-ui/` | **Runtime data** — db, logs, xray binary, geo files (gitignored) |
+
+## Sending a pull request
+
+1. Branch off `main` (e.g. `feat/short-description`).
+2. Keep the diff focused — separate refactors from feature work.
+3. Run the relevant checks before pushing:
+   - `go build ./...`
+   - `go test ./...` (when Go code changed)
+   - `cd frontend && npm run typecheck && npm run lint && npm run build` (when the frontend changed)
+4. Commit messages follow the existing pattern in `git log` — `<area>: short imperative summary`, then a body explaining the *why*. Conventional-commit prefixes (`feat`, `fix`, `refactor`, `chore`, `style`, `docs`) are encouraged.
+5. Open the PR against `main` with a brief description of what changed and how to test it.
+
+## Useful environment variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `XUI_DEBUG` | `false` | Verbose logs + Gin debug mode + serve `/assets` from disk |
+| `XUI_LOG_LEVEL` | `info` | `debug` / `info` / `notice` / `warning` / `error` |
+| `XUI_DB_FOLDER` | platform default | Where `x-ui.db` lives |
+| `XUI_LOG_FOLDER` | platform default | Where `3xui.log` lives |
+| `XUI_BIN_FOLDER` | `bin` | Where the xray binary, geo files, and xray `config.json` live |
+| `XUI_DB_TYPE` | `sqlite` | Set to `postgres` to use PostgreSQL via `XUI_DB_DSN` |
+| `XUI_DB_DSN` | — | PostgreSQL DSN when `XUI_DB_TYPE=postgres` |
+
+## Issues and discussion
+
+- Bug reports and feature requests: [GitHub Issues](https://github.com/MHSanaei/3x-ui/issues)
+- General questions and ideas: [GitHub Discussions](https://github.com/MHSanaei/3x-ui/discussions)
+
+Before filing a bug, include the OS, Go version, panel version (`/panel/api/server/status` or the dashboard footer), and the relevant excerpt from `x-ui/3xui.log`.

DockerEntrypoint.sh

@@ -0,0 +1,61 @@
+#!/bin/sh
+
+# Start fail2ban with the 3x-ipl jail
+if [ "$XUI_ENABLE_FAIL2BAN" = "true" ]; then
+    LOG_FOLDER="${XUI_LOG_FOLDER:-/var/log/x-ui}"
+    mkdir -p "$LOG_FOLDER"
+    touch "$LOG_FOLDER/3xipl.log" "$LOG_FOLDER/3xipl-banned.log"
+
+    mkdir -p /etc/fail2ban/jail.d /etc/fail2ban/filter.d /etc/fail2ban/action.d
+
+    cat > /etc/fail2ban/jail.d/3x-ipl.conf << EOF
+[3x-ipl]
+enabled=true
+backend=auto
+filter=3x-ipl
+action=3x-ipl
+logpath=$LOG_FOLDER/3xipl.log
+maxretry=1
+findtime=32
+bantime=30m
+EOF
+
+    cat > /etc/fail2ban/filter.d/3x-ipl.conf << 'EOF'
+[Definition]
+datepattern = ^%%Y/%%m/%%d %%H:%%M:%%S
+failregex   = \[LIMIT_IP\]\s*Email\s*=\s*<F-USER>.+</F-USER>\s*\|\|\s*Disconnecting OLD IP\s*=\s*<ADDR>\s*\|\|\s*Timestamp\s*=\s*\d+
+ignoreregex =
+EOF
+
+    cat > /etc/fail2ban/action.d/3x-ipl.conf << EOF
+[INCLUDES]
+before = iptables-allports.conf
+
+[Definition]
+actionstart = <iptables> -N f2b-<name>
+              <iptables> -A f2b-<name> -j <returntype>
+              <iptables> -I <chain> -p <protocol> -j f2b-<name>
+
+actionstop = <iptables> -D <chain> -p <protocol> -j f2b-<name>
+             <actionflush>
+             <iptables> -X f2b-<name>
+
+actioncheck = <iptables> -n -L <chain> | grep -q 'f2b-<name>[ \t]'
+
+actionban = <iptables> -I f2b-<name> 1 -s <ip> -j <blocktype>
+            echo "\$(date +"%%Y/%%m/%%d %%H:%%M:%%S")   BAN   [Email] = <F-USER> [IP] = <ip> banned for <bantime> seconds." >> $LOG_FOLDER/3xipl-banned.log
+
+actionunban = <iptables> -D f2b-<name> -s <ip> -j <blocktype>
+              echo "\$(date +"%%Y/%%m/%%d %%H:%%M:%%S")   UNBAN   [Email] = <F-USER> [IP] = <ip> unbanned." >> $LOG_FOLDER/3xipl-banned.log
+
+[Init]
+name = default
+protocol = tcp
+chain = INPUT
+EOF
+
+    fail2ban-client -x start
+fi
+
+# Run x-ui
+exec /app/x-ui

DockerInit.sh

@@ -0,0 +1,40 @@
+#!/bin/sh
+case $1 in
+    amd64)
+        ARCH="64"
+        FNAME="amd64"
+        ;;
+    i386)
+        ARCH="32"
+        FNAME="i386"
+        ;;
+    armv8 | arm64 | aarch64)
+        ARCH="arm64-v8a"
+        FNAME="arm64"
+        ;;
+    armv7 | arm | arm32)
+        ARCH="arm32-v7a"
+        FNAME="arm32"
+        ;;
+    armv6)
+        ARCH="arm32-v6"
+        FNAME="armv6"
+        ;;
+    *)
+        ARCH="64"
+        FNAME="amd64"
+        ;;
+esac
+mkdir -p build/bin
+cd build/bin
+curl -sfLRO "https://github.com/XTLS/Xray-core/releases/download/v26.5.9/Xray-linux-${ARCH}.zip"
+unzip "Xray-linux-${ARCH}.zip"
+rm -f "Xray-linux-${ARCH}.zip" geoip.dat geosite.dat
+mv xray "xray-linux-${FNAME}"
+curl -sfLRO https://github.com/Loyalsoldier/v2ray-rules-dat/releases/latest/download/geoip.dat
+curl -sfLRO https://github.com/Loyalsoldier/v2ray-rules-dat/releases/latest/download/geosite.dat
+curl -sfLRo geoip_IR.dat https://github.com/chocolate4u/Iran-v2ray-rules/releases/latest/download/geoip.dat
+curl -sfLRo geosite_IR.dat https://github.com/chocolate4u/Iran-v2ray-rules/releases/latest/download/geosite.dat
+curl -sfLRo geoip_RU.dat https://github.com/runetfreedom/russia-v2ray-rules-dat/releases/latest/download/geoip.dat
+curl -sfLRo geosite_RU.dat https://github.com/runetfreedom/russia-v2ray-rules-dat/releases/latest/download/geosite.dat
+cd ../../

Dockerfile

@@ -0,0 +1,74 @@
+# ========================================================
+# Stage: Frontend (Vite)
+# ========================================================
+FROM --platform=$BUILDPLATFORM node:22-alpine AS frontend
+WORKDIR /src/frontend
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+COPY frontend/ ./
+COPY web/translation /src/web/translation
+RUN npm run build
+
+# ========================================================
+# Stage: Builder
+# ========================================================
+FROM golang:1.26-alpine AS builder
+WORKDIR /app
+ARG TARGETARCH
+
+RUN apk --no-cache --update add \
+  build-base \
+  gcc \
+  curl \
+  unzip
+
+COPY . .
+COPY --from=frontend /src/web/dist ./web/dist
+
+ENV CGO_ENABLED=1
+ENV CGO_CFLAGS="-D_LARGEFILE64_SOURCE"
+RUN go build -ldflags "-w -s" -o build/x-ui main.go
+RUN ./DockerInit.sh "$TARGETARCH"
+
+# ========================================================
+# Stage: Final Image of 3x-ui
+# ========================================================
+FROM alpine
+ENV TZ=Asia/Tehran
+WORKDIR /app
+
+RUN apk add --no-cache --update \
+  ca-certificates \
+  tzdata \
+  fail2ban \
+  bash \
+  curl \
+  openssl
+
+COPY --from=builder /app/build/ /app/
+COPY --from=builder /app/DockerEntrypoint.sh /app/
+COPY --from=builder /app/x-ui.sh /usr/bin/x-ui
+COPY --from=builder /app/web/translation /app/web/translation
+
+
+# Configure fail2ban
+RUN rm -f /etc/fail2ban/jail.d/alpine-ssh.conf \
+  && cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local \
+  && sed -i "s/^\[ssh\]$/&\nenabled = false/" /etc/fail2ban/jail.local \
+  && sed -i "s/^\[sshd\]$/&\nenabled = false/" /etc/fail2ban/jail.local \
+  && sed -i "s/#allowipv6 = auto/allowipv6 = auto/g" /etc/fail2ban/fail2ban.conf
+
+RUN chmod +x \
+  /app/DockerEntrypoint.sh \
+  /app/x-ui \
+  /usr/bin/x-ui
+
+ENV XUI_ENABLE_FAIL2BAN="true"
+# Database backend: set XUI_DB_TYPE=postgres and XUI_DB_DSN=postgres://... to use PostgreSQL.
+# Default (unset) is SQLite stored under /etc/x-ui.
+ENV XUI_DB_TYPE=""
+ENV XUI_DB_DSN=""
+EXPOSE 2053
+VOLUME [ "/etc/x-ui" ]
+CMD [ "./x-ui" ]
+ENTRYPOINT [ "/app/DockerEntrypoint.sh" ]

README.ar_EG.md

@@ -0,0 +1,62 @@
+[English](/README.md) | [فارسی](/README.fa_IR.md) | [العربية](/README.ar_EG.md) | [中文](/README.zh_CN.md) | [Español](/README.es_ES.md) | [Русский](/README.ru_RU.md)
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./media/3x-ui-dark.png">
+    <img alt="3x-ui" src="./media/3x-ui-light.png">
+  </picture>
+</p>
+
+[![Release](https://img.shields.io/github/v/release/mhsanaei/3x-ui.svg)](https://github.com/MHSanaei/3x-ui/releases)
+[![Build](https://img.shields.io/github/actions/workflow/status/mhsanaei/3x-ui/release.yml.svg)](https://github.com/MHSanaei/3x-ui/actions)
+[![GO Version](https://img.shields.io/github/go-mod/go-version/mhsanaei/3x-ui.svg)](#)
+[![Downloads](https://img.shields.io/github/downloads/mhsanaei/3x-ui/total.svg)](https://github.com/MHSanaei/3x-ui/releases/latest)
+[![License](https://img.shields.io/badge/license-GPL%20V3-blue.svg?longCache=true)](https://www.gnu.org/licenses/gpl-3.0.en.html)
+[![Go Reference](https://pkg.go.dev/badge/github.com/mhsanaei/3x-ui/v3.svg)](https://pkg.go.dev/github.com/mhsanaei/3x-ui/v3)
+[![Go Report Card](https://goreportcard.com/badge/github.com/mhsanaei/3x-ui/v3)](https://goreportcard.com/report/github.com/mhsanaei/3x-ui/v3)
+
+**3X-UI** — لوحة تحكم متقدمة مفتوحة المصدر تعتمد على الويب مصممة لإدارة خادم Xray-core. توفر واجهة سهلة الاستخدام لتكوين ومراقبة بروتوكولات VPN والوكيل المختلفة.
+
+> [!IMPORTANT]
+> هذا المشروع مخصص للاستخدام الشخصي والاتصال فقط، يرجى عدم استخدامه لأغراض غير قانونية، يرجى عدم استخدامه في بيئة الإنتاج.
+
+كمشروع محسن من مشروع X-UI الأصلي، يوفر 3X-UI استقرارًا محسنًا ودعمًا أوسع للبروتوكولات وميزات إضافية.
+
+## البدء السريع
+
+```
+bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
+```
+
+للحصول على الوثائق الكاملة، يرجى زيارة [ويكي المشروع](https://github.com/MHSanaei/3x-ui/wiki).
+
+## شكر خاص إلى
+
+- [alireza0](https://github.com/alireza0/)
+
+## الاعتراف
+
+- [Iran v2ray rules](https://github.com/chocolate4u/Iran-v2ray-rules) (الترخيص: **GPL-3.0**): _قواعد توجيه v2ray/xray و v2ray/xray-clients المحسنة مع النطاقات الإيرانية المدمجة وتركيز على الأمان وحظر الإعلانات._
+- [Russia v2ray rules](https://github.com/runetfreedom/russia-v2ray-rules-dat) (الترخيص: **GPL-3.0**): _يحتوي هذا المستودع على قواعد توجيه V2Ray محدثة تلقائيًا بناءً على بيانات النطاقات والعناوين المحظورة في روسيا._
+
+## أدوات المجتمع
+
+أدوات وتكاملات بناها المجتمع حول 3x-ui.
+
+- [terraform-provider-3x-ui](https://github.com/batonogov/terraform-provider-threexui) (الترخيص: **MIT**): _إدارة الاتصالات الواردة والعملاء وإعدادات اللوحة وتكوين Xray كرمز باستخدام Terraform / OpenTofu._
+
+## دعم المشروع
+
+**إذا كان هذا المشروع مفيدًا لك، فقد ترغب في إعطائه**:star2:
+
+<a href="https://www.buymeacoffee.com/MHSanaei" target="_blank">
+<img src="./media/default-yellow.png" alt="Buy Me A Coffee" style="height: 70px !important;width: 277px !important;" >
+</a>
+</br>
+<a href="https://nowpayments.io/donation/hsanaei" target="_blank" rel="noreferrer noopener">
+   <img src="./media/donation-button-black.svg" alt="Crypto donation button by NOWPayments">
+</a>
+
+## النجوم عبر الزمن
+
+[![Stargazers over time](https://starchart.cc/MHSanaei/3x-ui.svg?variant=adaptive)](https://starchart.cc/MHSanaei/3x-ui)

README.es_ES.md

@@ -0,0 +1,63 @@
+[English](/README.md) | [فارسی](/README.fa_IR.md) | [العربية](/README.ar_EG.md) | [中文](/README.zh_CN.md) | [Español](/README.es_ES.md) | [Русский](/README.ru_RU.md)
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./media/3x-ui-dark.png">
+    <img alt="3x-ui" src="./media/3x-ui-light.png">
+  </picture>
+</p>
+
+[![Release](https://img.shields.io/github/v/release/mhsanaei/3x-ui.svg)](https://github.com/MHSanaei/3x-ui/releases)
+[![Build](https://img.shields.io/github/actions/workflow/status/mhsanaei/3x-ui/release.yml.svg)](https://github.com/MHSanaei/3x-ui/actions)
+[![GO Version](https://img.shields.io/github/go-mod/go-version/mhsanaei/3x-ui.svg)](#)
+[![Downloads](https://img.shields.io/github/downloads/mhsanaei/3x-ui/total.svg)](https://github.com/MHSanaei/3x-ui/releases/latest)
+[![License](https://img.shields.io/badge/license-GPL%20V3-blue.svg?longCache=true)](https://www.gnu.org/licenses/gpl-3.0.en.html)
+[![Go Reference](https://pkg.go.dev/badge/github.com/mhsanaei/3x-ui/v3.svg)](https://pkg.go.dev/github.com/mhsanaei/3x-ui/v3)
+[![Go Report Card](https://goreportcard.com/badge/github.com/mhsanaei/3x-ui/v3)](https://goreportcard.com/report/github.com/mhsanaei/3x-ui/v3)
+
+**3X-UI** — panel de control avanzado basado en web de código abierto diseñado para gestionar el servidor Xray-core. Ofrece una interfaz fácil de usar para configurar y monitorear varios protocolos VPN y proxy.
+
+> [!IMPORTANT]
+> Este proyecto es solo para uso personal y comunicación, por favor no lo use para fines ilegales, por favor no lo use en un entorno de producción.
+
+Como una versión mejorada del proyecto X-UI original, 3X-UI proporciona mayor estabilidad, soporte más amplio de protocolos y características adicionales.
+
+## Inicio Rápido
+
+```
+bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
+```
+
+Para documentación completa, visita la [Wiki del proyecto](https://github.com/MHSanaei/3x-ui/wiki).
+
+## Un Agradecimiento Especial a
+
+- [alireza0](https://github.com/alireza0/)
+
+## Reconocimientos
+
+- [Iran v2ray rules](https://github.com/chocolate4u/Iran-v2ray-rules) (Licencia: **GPL-3.0**): _Reglas de enrutamiento mejoradas para v2ray/xray y v2ray/xray-clients con dominios iraníes incorporados y un enfoque en seguridad y bloqueo de anuncios._
+- [Russia v2ray rules](https://github.com/runetfreedom/russia-v2ray-rules-dat) (Licencia: **GPL-3.0**): _Este repositorio contiene reglas de enrutamiento V2Ray actualizadas automáticamente basadas en datos de dominios y direcciones bloqueadas en Rusia._
+
+## Herramientas de la Comunidad
+
+Herramientas e integraciones construidas por la comunidad alrededor de 3x-ui.
+
+- [terraform-provider-3x-ui](https://github.com/batonogov/terraform-provider-threexui) (Licencia: **MIT**): _Gestiona inbounds, clientes, configuración del panel y configuración de Xray como código con Terraform / OpenTofu._
+
+## Apoyar el Proyecto
+
+**Si este proyecto te es útil, puedes darle una**:star2:
+
+<a href="https://www.buymeacoffee.com/MHSanaei" target="_blank">
+<img src="./media/default-yellow.png" alt="Buy Me A Coffee" style="height: 70px !important;width: 277px !important;" >
+</a>
+
+</br>
+<a href="https://nowpayments.io/donation/hsanaei" target="_blank" rel="noreferrer noopener">
+   <img src="./media/donation-button-black.svg" alt="Crypto donation button by NOWPayments">
+</a>
+
+## Estrellas a lo Largo del Tiempo
+
+[![Stargazers over time](https://starchart.cc/MHSanaei/3x-ui.svg?variant=adaptive)](https://starchart.cc/MHSanaei/3x-ui)

README.fa_IR.md

@@ -0,0 +1,63 @@
+[English](/README.md) | [فارسی](/README.fa_IR.md) | [العربية](/README.ar_EG.md) | [中文](/README.zh_CN.md) | [Español](/README.es_ES.md) | [Русский](/README.ru_RU.md)
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./media/3x-ui-dark.png">
+    <img alt="3x-ui" src="./media/3x-ui-light.png">
+  </picture>
+</p>
+
+[![Release](https://img.shields.io/github/v/release/mhsanaei/3x-ui.svg)](https://github.com/MHSanaei/3x-ui/releases)
+[![Build](https://img.shields.io/github/actions/workflow/status/mhsanaei/3x-ui/release.yml.svg)](https://github.com/MHSanaei/3x-ui/actions)
+[![GO Version](https://img.shields.io/github/go-mod/go-version/mhsanaei/3x-ui.svg)](#)
+[![Downloads](https://img.shields.io/github/downloads/mhsanaei/3x-ui/total.svg)](https://github.com/MHSanaei/3x-ui/releases/latest)
+[![License](https://img.shields.io/badge/license-GPL%20V3-blue.svg?longCache=true)](https://www.gnu.org/licenses/gpl-3.0.en.html)
+[![Go Reference](https://pkg.go.dev/badge/github.com/mhsanaei/3x-ui/v3.svg)](https://pkg.go.dev/github.com/mhsanaei/3x-ui/v3)
+[![Go Report Card](https://goreportcard.com/badge/github.com/mhsanaei/3x-ui/v3)](https://goreportcard.com/report/github.com/mhsanaei/3x-ui/v3)
+
+**3X-UI** — یک پنل کنترل پیشرفته مبتنی بر وب با کد باز که برای مدیریت سرور Xray-core طراحی شده است. این پنل یک رابط کاربری آسان برای پیکربندی و نظارت بر پروتکل‌های مختلف VPN و پراکسی ارائه می‌دهد.
+
+> [!IMPORTANT]
+> این پروژه فقط برای استفاده شخصی و ارتباطات است، لطفاً از آن برای اهداف غیرقانونی استفاده نکنید، لطفاً از آن در محیط تولید استفاده نکنید.
+
+به عنوان یک نسخه بهبود یافته از پروژه اصلی X-UI، 3X-UI پایداری بهتر، پشتیبانی گسترده‌تر از پروتکل‌ها و ویژگی‌های اضافی را ارائه می‌دهد.
+
+## شروع سریع
+
+```
+bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
+```
+
+برای مستندات کامل، لطفاً به [ویکی پروژه](https://github.com/MHSanaei/3x-ui/wiki) مراجعه کنید.
+
+## تشکر ویژه از
+
+- [alireza0](https://github.com/alireza0/)
+
+## قدردانی
+
+- [Iran v2ray rules](https://github.com/chocolate4u/Iran-v2ray-rules) (مجوز: **GPL-3.0**): _قوانین مسیریابی بهبود یافته v2ray/xray و v2ray/xray-clients با دامنه‌های ایرانی داخلی و تمرکز بر امنیت و مسدود کردن تبلیغات._
+- [Russia v2ray rules](https://github.com/runetfreedom/russia-v2ray-rules-dat) (مجوز: **GPL-3.0**): _این مخزن شامل قوانین مسیریابی V2Ray به‌روزرسانی شده خودکار بر اساس داده‌های دامنه‌ها و آدرس‌های مسدود شده در روسیه است._
+
+## ابزارهای جامعه
+
+ابزارها و یکپارچه‌سازی‌هایی که توسط جامعه پیرامون 3x-ui ساخته شده‌اند.
+
+- [terraform-provider-3x-ui](https://github.com/batonogov/terraform-provider-threexui) (مجوز: **MIT**): _مدیریت اینباندها، کلاینت‌ها، تنظیمات پنل و پیکربندی Xray به‌صورت کد با Terraform / OpenTofu._
+
+## پشتیبانی از پروژه
+
+**اگر این پروژه برای شما مفید است، می‌توانید به آن یک**:star2: بدهید
+
+<a href="https://www.buymeacoffee.com/MHSanaei" target="_blank">
+<img src="./media/default-yellow.png" alt="Buy Me A Coffee" style="height: 70px !important;width: 277px !important;" >
+</a>
+
+</br>
+<a href="https://nowpayments.io/donation/hsanaei" target="_blank" rel="noreferrer noopener">
+   <img src="./media/donation-button-black.svg" alt="Crypto donation button by NOWPayments">
+</a>
+
+## ستاره‌ها در طول زمان
+
+[![Stargazers over time](https://starchart.cc/MHSanaei/3x-ui.svg?variant=adaptive)](https://starchart.cc/MHSanaei/3x-ui)

README.md

@@ -1,67 +1,95 @@
-# 3x-ui
-![](https://img.shields.io/github/v/release/mhsanaei/3x-ui.svg)
-![](https://img.shields.io/github/actions/workflow/status/mhsanaei/3x-ui/release.yml.svg)
-[![GO Version](https://img.shields.io/github/go-mod/go-version/mhsanaei/3x-ui.svg)](https://img.shields.io/github/go-mod/go-version/mhsanaei/3x-ui)
-[![Downloads](https://img.shields.io/github/downloads/mhsanaei/3x-ui/total.svg)](https://img.shields.io/github/downloads/mhsanaei/3x-ui/total)
+[English](/README.md) | [فارسی](/README.fa_IR.md) | [العربية](/README.ar_EG.md) | [中文](/README.zh_CN.md) | [Español](/README.es_ES.md) | [Русский](/README.ru_RU.md)
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./media/3x-ui-dark.png">
+    <img alt="3x-ui" src="./media/3x-ui-light.png">
+  </picture>
+</p>
+
+[![Release](https://img.shields.io/github/v/release/mhsanaei/3x-ui.svg)](https://github.com/MHSanaei/3x-ui/releases)
+[![Build](https://img.shields.io/github/actions/workflow/status/mhsanaei/3x-ui/release.yml.svg)](https://github.com/MHSanaei/3x-ui/actions)
+[![GO Version](https://img.shields.io/github/go-mod/go-version/mhsanaei/3x-ui.svg)](#)
+[![Downloads](https://img.shields.io/github/downloads/mhsanaei/3x-ui/total.svg)](https://github.com/MHSanaei/3x-ui/releases/latest)
 [![License](https://img.shields.io/badge/license-GPL%20V3-blue.svg?longCache=true)](https://www.gnu.org/licenses/gpl-3.0.en.html)
+[![Go Reference](https://pkg.go.dev/badge/github.com/mhsanaei/3x-ui/v3.svg)](https://pkg.go.dev/github.com/mhsanaei/3x-ui/v3)
+[![Go Report Card](https://goreportcard.com/badge/github.com/mhsanaei/3x-ui/v3)](https://goreportcard.com/report/github.com/mhsanaei/3x-ui/v3)
 
-> **Disclaimer: This project is only for personal learning and communication, please do not use it for illegal purposes, please do not use it in a production environment**
+**3X-UI** — advanced, open-source web-based control panel designed for managing Xray-core server. It offers a user-friendly interface for configuring and monitoring various VPN and proxy protocols.
 
-xray panel supporting multi-protocol, **Multi-lang (English,Farsi,Chinese)**
+> [!IMPORTANT]
+> This project is only for personal usage, please do not use it for illegal purposes, and please do not use it in a production environment.
 
-# Install & Upgrade
+As an enhanced fork of the original X-UI project, 3X-UI provides improved stability, broader protocol support, and additional features.
 
-```
+## Quick Start
+
+```bash
 bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
 ```
 
-# SSL
+For full documentation, please visit the [project Wiki](https://github.com/MHSanaei/3x-ui/wiki).
+
+## Database Options
+
+3X-UI supports two backends, chosen during the install:
+
+- **SQLite** (default) — a single file at `/etc/x-ui/x-ui.db`. Zero setup, ideal for small/medium deployments.
+- **PostgreSQL** — recommended for high client counts or multi-node setups. The installer can install PostgreSQL locally for you, or accept a DSN to an existing server.
+
+At runtime the backend is selected via env vars (the installer writes these to `/etc/default/x-ui` for you):
+
 ```
-apt-get install certbot -y
-certbot certonly --standalone --agree-tos --register-unsafely-without-email -d yourdomain.com
-certbot renew --dry-run
+XUI_DB_TYPE=postgres
+XUI_DB_DSN=postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable
 ```
 
-**If you think this project is helpful to you, you may wish to give a** :star2: 
+### Migrating an existing SQLite install to PostgreSQL
 
-# Default settings
+```bash
+x-ui migrate-db --dsn "postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable"
+# then set XUI_DB_TYPE and XUI_DB_DSN in /etc/default/x-ui and restart:
+systemctl restart x-ui
+```
 
-- Port: 2053
-- username and password will be generated randomly you can see them after you install it (x-ui "7")
-- database path: /etc/x-ui/x-ui.db
+The source SQLite file is left untouched; remove it manually once you have verified the new backend.
 
-before you set ssl on settings
-- http:// ip or domain:2053/xui
+### Docker
 
-After you set ssl on settings 
-- https://yourdomain:2053/xui
+The default `docker compose up -d` keeps using SQLite. To run with the bundled PostgreSQL service, uncomment the two `XUI_DB_*` env lines in `docker-compose.yml` and start with the profile:
 
-# Enable Traffic For Users:
+```bash
+docker compose --profile postgres up -d
+```
 
-**copy and paste to xray Configuration :** (you don't need to do this if you have a fresh install)
-- [for enable traffic](https://raw.githubusercontent.com/MHSanaei/3x-ui/main/media/for%20enable%20traffic.txt)
-- [for enable traffic+block all iran ip address](https://raw.githubusercontent.com/MHSanaei/3x-ui/main/media/for%20enable%20traffic%2Bblock%20all%20iran%20ip.txt)
+## A Special Thanks to
 
-# Suggestion System
-- Ubuntu 20.04+
-- Debian 10+
-- CentOS 8+
-
-# Pictures
-
-![1](https://raw.githubusercontent.com/MHSanaei/3x-ui/main/media/1.png)
-![2](https://raw.githubusercontent.com/MHSanaei/3x-ui/main/media/2.png)
-![3](https://raw.githubusercontent.com/MHSanaei/3x-ui/main/media/3.png)
-![4](https://raw.githubusercontent.com/MHSanaei/3x-ui/main/media/4.png)
-
-# A Special Thanks To
-- [vaxilu](https://github.com/vaxilu/)
-- [HexaSoftwareTech](https://github.com/HexaSoftwareTech/)
-- [diditra](https://github.com/diditra/)
-- [FranzKafkaYu](https://github.com/FranzKafkaYu)
 - [alireza0](https://github.com/alireza0/)
 
+## Acknowledgment
 
-## Stargazers over time
+- [Iran v2ray rules](https://github.com/chocolate4u/Iran-v2ray-rules) (License: **GPL-3.0**): _Enhanced v2ray/xray and v2ray/xray-clients routing rules with built-in Iranian domains and a focus on security and adblocking._
+- [Russia v2ray rules](https://github.com/runetfreedom/russia-v2ray-rules-dat) (License: **GPL-3.0**): _This repository contains automatically updated V2Ray routing rules based on data on blocked domains and addresses in Russia._
 
-[![Stargazers over time](https://starchart.cc/MHSanaei/3x-ui.svg)](https://starchart.cc/MHSanaei/3x-ui)
+## Community Tools
+
+Tools and integrations built by the community around 3x-ui.
+
+- [terraform-provider-3x-ui](https://github.com/batonogov/terraform-provider-threexui) (License: **MIT**): _Manage inbounds, clients, panel settings, and Xray configuration as code with Terraform / OpenTofu._
+
+## Support project
+
+**If this project is helpful to you, you may wish to give it a**:star2:
+
+<a href="https://www.buymeacoffee.com/MHSanaei" target="_blank">
+<img src="./media/default-yellow.png" alt="Buy Me A Coffee" style="height: 70px !important;width: 277px !important;" >
+</a>
+
+</br>
+<a href="https://nowpayments.io/donation/hsanaei" target="_blank" rel="noreferrer noopener">
+   <img src="./media/donation-button-black.svg" alt="Crypto donation button by NOWPayments">
+</a>
+
+## Stargazers over Time
+
+[![Stargazers over time](https://starchart.cc/MHSanaei/3x-ui.svg?variant=adaptive)](https://starchart.cc/MHSanaei/3x-ui)

README.ru_RU.md

@@ -0,0 +1,63 @@
+[English](/README.md) | [فارسی](/README.fa_IR.md) | [العربية](/README.ar_EG.md) | [中文](/README.zh_CN.md) | [Español](/README.es_ES.md) | [Русский](/README.ru_RU.md)
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./media/3x-ui-dark.png">
+    <img alt="3x-ui" src="./media/3x-ui-light.png">
+  </picture>
+</p>
+
+[![Release](https://img.shields.io/github/v/release/mhsanaei/3x-ui.svg)](https://github.com/MHSanaei/3x-ui/releases)
+[![Build](https://img.shields.io/github/actions/workflow/status/mhsanaei/3x-ui/release.yml.svg)](https://github.com/MHSanaei/3x-ui/actions)
+[![GO Version](https://img.shields.io/github/go-mod/go-version/mhsanaei/3x-ui.svg)](#)
+[![Downloads](https://img.shields.io/github/downloads/mhsanaei/3x-ui/total.svg)](https://github.com/MHSanaei/3x-ui/releases/latest)
+[![License](https://img.shields.io/badge/license-GPL%20V3-blue.svg?longCache=true)](https://www.gnu.org/licenses/gpl-3.0.en.html)
+[![Go Reference](https://pkg.go.dev/badge/github.com/mhsanaei/3x-ui/v3.svg)](https://pkg.go.dev/github.com/mhsanaei/3x-ui/v3)
+[![Go Report Card](https://goreportcard.com/badge/github.com/mhsanaei/3x-ui/v3)](https://goreportcard.com/report/github.com/mhsanaei/3x-ui/v3)
+
+**3X-UI** — продвинутая панель управления с открытым исходным кодом на основе веб-интерфейса, разработанная для управления сервером Xray-core. Предоставляет удобный интерфейс для настройки и мониторинга различных VPN и прокси-протоколов.
+
+> [!IMPORTANT]
+> Этот проект предназначен только для личного использования, пожалуйста, не используйте его в незаконных целях и в производственной среде.
+
+Как улучшенная версия оригинального проекта X-UI, 3X-UI обеспечивает повышенную стабильность, более широкую поддержку протоколов и дополнительные функции.
+
+## Быстрый старт
+
+```
+bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
+```
+
+Полную документацию смотрите в [вики проекта](https://github.com/MHSanaei/3x-ui/wiki).
+
+## Особая благодарность
+
+- [alireza0](https://github.com/alireza0/)
+
+## Благодарности
+
+- [Iran v2ray rules](https://github.com/chocolate4u/Iran-v2ray-rules) (Лицензия: **GPL-3.0**): _Улучшенные правила маршрутизации для v2ray/xray и v2ray/xray-clients со встроенными иранскими доменами и фокусом на безопасность и блокировку рекламы._
+- [Russia v2ray rules](https://github.com/runetfreedom/russia-v2ray-rules-dat) (Лицензия: **GPL-3.0**): _Этот репозиторий содержит автоматически обновляемые правила маршрутизации V2Ray на основе данных о заблокированных доменах и адресах в России._
+
+## Инструменты сообщества
+
+Инструменты и интеграции, созданные сообществом вокруг 3x-ui.
+
+- [terraform-provider-3x-ui](https://github.com/batonogov/terraform-provider-threexui) (Лицензия: **MIT**): _Управление входящими, клиентами, настройками панели и конфигурацией Xray через код с помощью Terraform / OpenTofu._
+
+## Поддержка проекта
+
+**Если этот проект полезен для вас, вы можете поставить ему**:star2:
+
+<a href="https://www.buymeacoffee.com/MHSanaei" target="_blank">
+<img src="./media/default-yellow.png" alt="Buy Me A Coffee" style="height: 70px !important;width: 277px !important;" >
+</a>
+
+</br>
+<a href="https://nowpayments.io/donation/hsanaei" target="_blank" rel="noreferrer noopener">
+   <img src="./media/donation-button-black.svg" alt="Crypto donation button by NOWPayments">
+</a>
+
+## Звезды с течением времени
+
+[![Stargazers over time](https://starchart.cc/MHSanaei/3x-ui.svg?variant=adaptive)](https://starchart.cc/MHSanaei/3x-ui)

README.zh_CN.md

@@ -0,0 +1,63 @@
+[English](/README.md) | [فارسی](/README.fa_IR.md) | [العربية](/README.ar_EG.md) | [中文](/README.zh_CN.md) | [Español](/README.es_ES.md) | [Русский](/README.ru_RU.md)
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./media/3x-ui-dark.png">
+    <img alt="3x-ui" src="./media/3x-ui-light.png">
+  </picture>
+</p>
+
+[![Release](https://img.shields.io/github/v/release/mhsanaei/3x-ui.svg)](https://github.com/MHSanaei/3x-ui/releases)
+[![Build](https://img.shields.io/github/actions/workflow/status/mhsanaei/3x-ui/release.yml.svg)](https://github.com/MHSanaei/3x-ui/actions)
+[![GO Version](https://img.shields.io/github/go-mod/go-version/mhsanaei/3x-ui.svg)](#)
+[![Downloads](https://img.shields.io/github/downloads/mhsanaei/3x-ui/total.svg)](https://github.com/MHSanaei/3x-ui/releases/latest)
+[![License](https://img.shields.io/badge/license-GPL%20V3-blue.svg?longCache=true)](https://www.gnu.org/licenses/gpl-3.0.en.html)
+[![Go Reference](https://pkg.go.dev/badge/github.com/mhsanaei/3x-ui/v3.svg)](https://pkg.go.dev/github.com/mhsanaei/3x-ui/v3)
+[![Go Report Card](https://goreportcard.com/badge/github.com/mhsanaei/3x-ui/v3)](https://goreportcard.com/report/github.com/mhsanaei/3x-ui/v3)
+
+**3X-UI** — 一个基于网页的高级开源控制面板，专为管理 Xray-core 服务器而设计。它提供了用户友好的界面，用于配置和监控各种 VPN 和代理协议。
+
+> [!IMPORTANT]
+> 本项目仅用于个人使用和通信，请勿将其用于非法目的，请勿在生产环境中使用。
+
+作为原始 X-UI 项目的增强版本，3X-UI 提供了更好的稳定性、更广泛的协议支持和额外的功能。
+
+## 快速开始
+
+```
+bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
+```
+
+完整文档请参阅 [项目Wiki](https://github.com/MHSanaei/3x-ui/wiki)。
+
+## 特别感谢
+
+- [alireza0](https://github.com/alireza0/)
+
+## 致谢
+
+- [Iran v2ray rules](https://github.com/chocolate4u/Iran-v2ray-rules) (许可证: **GPL-3.0**): _增强的 v2ray/xray 和 v2ray/xray-clients 路由规则，内置伊朗域名，专注于安全性和广告拦截。_
+- [Russia v2ray rules](https://github.com/runetfreedom/russia-v2ray-rules-dat) (许可证: **GPL-3.0**): _此仓库包含基于俄罗斯被阻止域名和地址数据自动更新的 V2Ray 路由规则。_
+
+## 社区工具
+
+社区围绕 3x-ui 构建的工具和集成。
+
+- [terraform-provider-3x-ui](https://github.com/batonogov/terraform-provider-threexui) (许可证: **MIT**): _使用 Terraform / OpenTofu 通过代码管理入站、客户端、面板设置和 Xray 配置。_
+
+## 支持项目
+
+**如果这个项目对您有帮助，您可以给它一个**:star2:
+
+<a href="https://www.buymeacoffee.com/MHSanaei" target="_blank">
+<img src="./media/default-yellow.png" alt="Buy Me A Coffee" style="height: 70px !important;width: 277px !important;" >
+</a>
+
+</br>
+<a href="https://nowpayments.io/donation/hsanaei" target="_blank" rel="noreferrer noopener">
+   <img src="./media/donation-button-black.svg" alt="Crypto donation button by NOWPayments">
+</a>
+
+## 随时间变化的星标数
+
+[![Stargazers over time](https://starchart.cc/MHSanaei/3x-ui.svg?variant=adaptive)](https://starchart.cc/MHSanaei/3x-ui)

config/config.go

@@ -1,9 +1,14 @@
+// Package config provides configuration management utilities for the 3x-ui panel,
+// including version information, logging levels, database paths, and environment variable handling.
 package config
 
 import (
 	_ "embed"
 	"fmt"
+	"io"
 	"os"
+	"path/filepath"
+	"runtime"
 	"strings"
 )
 
@@ -13,23 +18,29 @@ var version string
 //go:embed name
 var name string
 
+// LogLevel represents the logging level for the application.
 type LogLevel string
 
+// Logging level constants
 const (
-	Debug LogLevel = "debug"
-	Info  LogLevel = "info"
-	Warn  LogLevel = "warn"
-	Error LogLevel = "error"
+	Debug   LogLevel = "debug"
+	Info    LogLevel = "info"
+	Notice  LogLevel = "notice"
+	Warning LogLevel = "warning"
+	Error   LogLevel = "error"
 )
 
+// GetVersion returns the version string of the 3x-ui application.
 func GetVersion() string {
 	return strings.TrimSpace(version)
 }
 
+// GetName returns the name of the 3x-ui application.
 func GetName() string {
 	return strings.TrimSpace(name)
 }
 
+// GetLogLevel returns the current logging level based on environment variables or defaults to Info.
 func GetLogLevel() LogLevel {
 	if IsDebug() {
 		return Debug
@@ -41,10 +52,126 @@ func GetLogLevel() LogLevel {
 	return LogLevel(logLevel)
 }
 
+// IsDebug returns true if debug mode is enabled via the XUI_DEBUG environment variable.
 func IsDebug() bool {
 	return os.Getenv("XUI_DEBUG") == "true"
 }
 
+// IsSkipHSTS returns true if skipping HSTS mode is enabled via the XUI_SKIP_HSTS environment variable.
+func IsSkipHSTS() bool {
+	return os.Getenv("XUI_SKIP_HSTS") == "true"
+}
+
+// GetBinFolderPath returns the path to the binary folder, defaulting to "bin" if not set via XUI_BIN_FOLDER.
+func GetBinFolderPath() string {
+	binFolderPath := os.Getenv("XUI_BIN_FOLDER")
+	if binFolderPath == "" {
+		binFolderPath = "bin"
+	}
+	return binFolderPath
+}
+
+func getBaseDir() string {
+	exePath, err := os.Executable()
+	if err != nil {
+		return "."
+	}
+	exeDir := filepath.Dir(exePath)
+	exeDirLower := strings.ToLower(filepath.ToSlash(exeDir))
+	if strings.Contains(exeDirLower, "/appdata/local/temp/") || strings.Contains(exeDirLower, "/go-build") {
+		wd, err := os.Getwd()
+		if err != nil {
+			return "."
+		}
+		return wd
+	}
+	return exeDir
+}
+
+// GetDBFolderPath returns the path to the database folder based on environment variables or platform defaults.
+func GetDBFolderPath() string {
+	dbFolderPath := os.Getenv("XUI_DB_FOLDER")
+	if dbFolderPath != "" {
+		return dbFolderPath
+	}
+	if runtime.GOOS == "windows" {
+		return getBaseDir()
+	}
+	return "/etc/x-ui"
+}
+
+// GetDBPath returns the full path to the database file.
 func GetDBPath() string {
-	return fmt.Sprintf("/etc/%s/%s.db", GetName(), GetName())
+	return fmt.Sprintf("%s/%s.db", GetDBFolderPath(), GetName())
+}
+
+// GetDBKind returns the configured database backend: "sqlite" (default) or "postgres".
+func GetDBKind() string {
+	v := strings.ToLower(strings.TrimSpace(os.Getenv("XUI_DB_TYPE")))
+	switch v {
+	case "postgres", "postgresql", "pg":
+		return "postgres"
+	default:
+		return "sqlite"
+	}
+}
+
+// GetDBDSN returns the PostgreSQL DSN from XUI_DB_DSN. Empty for sqlite.
+func GetDBDSN() string {
+	return strings.TrimSpace(os.Getenv("XUI_DB_DSN"))
+}
+
+// GetLogFolder returns the path to the log folder based on environment variables or platform defaults.
+func GetLogFolder() string {
+	logFolderPath := os.Getenv("XUI_LOG_FOLDER")
+	if logFolderPath != "" {
+		return logFolderPath
+	}
+	if runtime.GOOS == "windows" {
+		return filepath.Join(".", "log")
+	}
+	return "/var/log/x-ui"
+}
+
+func copyFile(src, dst string) error {
+	in, err := os.Open(src)
+	if err != nil {
+		return err
+	}
+	defer in.Close()
+
+	out, err := os.Create(dst)
+	if err != nil {
+		return err
+	}
+	defer out.Close()
+
+	_, err = io.Copy(out, in)
+	if err != nil {
+		return err
+	}
+
+	return out.Sync()
+}
+
+func init() {
+	if runtime.GOOS != "windows" {
+		return
+	}
+	if os.Getenv("XUI_DB_FOLDER") != "" {
+		return
+	}
+	oldDBFolder := "/etc/x-ui"
+	oldDBPath := fmt.Sprintf("%s/%s.db", oldDBFolder, GetName())
+	newDBFolder := GetDBFolderPath()
+	newDBPath := fmt.Sprintf("%s/%s.db", newDBFolder, GetName())
+	_, err := os.Stat(newDBPath)
+	if err == nil {
+		return // new exists
+	}
+	_, err = os.Stat(oldDBPath)
+	if os.IsNotExist(err) {
+		return // old does not exist
+	}
+	_ = copyFile(oldDBPath, newDBPath) // ignore error
 }

config/version

@@ -1 +1 @@
-1.0.8
+3.1.0

database/db.go

@@ -1,13 +1,26 @@
+// Package database provides database initialization, migration, and management utilities
+// for the 3x-ui panel using GORM with SQLite or PostgreSQL.
 package database
 
 import (
-	"io/fs"
+	"bytes"
+	"encoding/json"
+	"errors"
+	"io"
+	"log"
 	"os"
 	"path"
-	"x-ui/config"
-	"x-ui/database/model"
-	"x-ui/xray"
+	"slices"
+	"strconv"
+	"strings"
+	"time"
 
+	"github.com/mhsanaei/3x-ui/v3/config"
+	"github.com/mhsanaei/3x-ui/v3/database/model"
+	"github.com/mhsanaei/3x-ui/v3/util/crypto"
+	"github.com/mhsanaei/3x-ui/v3/xray"
+
+	"gorm.io/driver/postgres"
 	"gorm.io/driver/sqlite"
 	"gorm.io/gorm"
 	"gorm.io/gorm/logger"
@@ -15,91 +28,460 @@ import (
 
 var db *gorm.DB
 
+const (
+	DialectSQLite   = "sqlite"
+	DialectPostgres = "postgres"
+)
+
+// IsPostgres reports whether the active connection is a PostgreSQL backend.
+func IsPostgres() bool {
+	if db == nil {
+		return config.GetDBKind() == "postgres"
+	}
+	return db.Dialector.Name() == "postgres"
+}
+
+// Dialect returns the active GORM dialect name, or "" if the DB is not open.
+func Dialect() string {
+	if db == nil {
+		return ""
+	}
+	return db.Dialector.Name()
+}
+
+const (
+	defaultUsername = "admin"
+	defaultPassword = "admin"
+)
+
+func initModels() error {
+	models := []any{
+		&model.User{},
+		&model.Inbound{},
+		&model.OutboundTraffics{},
+		&model.Setting{},
+		&model.InboundClientIps{},
+		&xray.ClientTraffic{},
+		&model.HistoryOfSeeders{},
+		&model.CustomGeoResource{},
+		&model.Node{},
+		&model.ApiToken{},
+		&model.ClientRecord{},
+		&model.ClientInbound{},
+		&model.InboundFallback{},
+	}
+	for _, mdl := range models {
+		if err := db.AutoMigrate(mdl); err != nil {
+			if isIgnorableDuplicateColumnErr(err, mdl) {
+				log.Printf("Ignoring duplicate column during auto migration for %T: %v", mdl, err)
+				continue
+			}
+			log.Printf("Error auto migrating model: %v", err)
+			return err
+		}
+	}
+	return nil
+}
+
+func isIgnorableDuplicateColumnErr(err error, mdl any) bool {
+	if err == nil {
+		return false
+	}
+	errMsg := strings.ToLower(err.Error())
+	// SQLite: "duplicate column name: foo"
+	// Postgres: `pq: column "foo" of relation "bar" already exists` / `sqlstate 42701`
+	const sqlitePrefix = "duplicate column name:"
+	if _, after, ok := strings.Cut(errMsg, sqlitePrefix); ok {
+		col := strings.TrimSpace(after)
+		col = strings.Trim(col, "`\"[]")
+		return col != "" && db != nil && db.Migrator().HasColumn(mdl, col)
+	}
+	if strings.Contains(errMsg, "already exists") && strings.Contains(errMsg, "column ") {
+		// Best effort: extract the column name between the first pair of double quotes.
+		if _, after, ok := strings.Cut(errMsg, "column \""); ok {
+			rest := after
+			if e := strings.Index(rest, "\""); e > 0 {
+				col := rest[:e]
+				return col != "" && db != nil && db.Migrator().HasColumn(mdl, col)
+			}
+		}
+	}
+	return false
+}
+
+// initUser creates a default admin user if the users table is empty.
 func initUser() error {
-	err := db.AutoMigrate(&model.User{})
+	empty, err := isTableEmpty("users")
 	if err != nil {
+		log.Printf("Error checking if users table is empty: %v", err)
 		return err
 	}
-	var count int64
-	err = db.Model(&model.User{}).Count(&count).Error
-	if err != nil {
-		return err
-	}
-	if count == 0 {
+	if empty {
+		hashedPassword, err := crypto.HashPasswordAsBcrypt(defaultPassword)
+
+		if err != nil {
+			log.Printf("Error hashing default password: %v", err)
+			return err
+		}
+
 		user := &model.User{
-			Username: "admin",
-			Password: "admin",
+			Username: defaultUsername,
+			Password: hashedPassword,
 		}
 		return db.Create(user).Error
 	}
 	return nil
 }
 
-func initInbound() error {
-	return db.AutoMigrate(&model.Inbound{})
-}
-
-func initSetting() error {
-	return db.AutoMigrate(&model.Setting{})
-}
-func initInboundClientIps() error {
-	return db.AutoMigrate(&model.InboundClientIps{})
-}
-func initClientTraffic() error {
-	return db.AutoMigrate(&xray.ClientTraffic{})
-}
-
-func InitDB(dbPath string) error {
-	dir := path.Dir(dbPath)
-	err := os.MkdirAll(dir, fs.ModeDir)
+// runSeeders migrates user passwords to bcrypt and records seeder execution to prevent re-running.
+func runSeeders(isUsersEmpty bool) error {
+	empty, err := isTableEmpty("history_of_seeders")
 	if err != nil {
+		log.Printf("Error checking if users table is empty: %v", err)
 		return err
 	}
 
-	var gormLogger logger.Interface
-
-	if config.IsDebug() {
-		gormLogger = logger.Default
-	} else {
-		gormLogger = logger.Discard
+	if empty && isUsersEmpty {
+		hashSeeder := &model.HistoryOfSeeders{
+			SeederName: "UserPasswordHash",
+		}
+		if err := db.Create(hashSeeder).Error; err != nil {
+			return err
+		}
+		return seedApiTokens()
 	}
 
-	c := &gorm.Config{
-		Logger: gormLogger,
-	}
-	db, err = gorm.Open(sqlite.Open(dbPath), c)
-	if err != nil {
+	var seedersHistory []string
+	if err := db.Model(&model.HistoryOfSeeders{}).Pluck("seeder_name", &seedersHistory).Error; err != nil {
+		log.Printf("Error fetching seeder history: %v", err)
 		return err
 	}
 
-	err = initUser()
-	if err != nil {
-		return err
+	if !slices.Contains(seedersHistory, "UserPasswordHash") && !isUsersEmpty {
+		var users []model.User
+		if err := db.Find(&users).Error; err != nil {
+			log.Printf("Error fetching users for password migration: %v", err)
+			return err
+		}
+
+		for _, user := range users {
+			hashedPassword, err := crypto.HashPasswordAsBcrypt(user.Password)
+			if err != nil {
+				log.Printf("Error hashing password for user '%s': %v", user.Username, err)
+				return err
+			}
+			if err := db.Model(&user).Update("password", hashedPassword).Error; err != nil {
+				log.Printf("Error updating password for user '%s': %v", user.Username, err)
+				return err
+			}
+		}
+
+		hashSeeder := &model.HistoryOfSeeders{
+			SeederName: "UserPasswordHash",
+		}
+		if err := db.Create(hashSeeder).Error; err != nil {
+			return err
+		}
 	}
-	err = initInbound()
-	if err != nil {
-		return err
+
+	if !slices.Contains(seedersHistory, "ApiTokensTable") {
+		if err := seedApiTokens(); err != nil {
+			return err
+		}
 	}
-	err = initSetting()
-	if err != nil {
-		return err
+
+	if !slices.Contains(seedersHistory, "ClientsTable") {
+		if err := seedClientsFromInboundJSON(); err != nil {
+			return err
+		}
 	}
-	err = initInboundClientIps()
-	if err != nil {
-		return err
-	}
-	err = initClientTraffic()
-	if err != nil {
-		return err
-	}
-	
 	return nil
 }
 
+// normalizeClientJSONFields coerces loosely-typed numeric fields in a raw
+// settings.clients entry so json.Unmarshal into model.Client doesn't fail
+// when older rows wrote tgId/limitIp/totalGB/etc. as strings. Empty strings
+// drop the key so the field falls back to its zero value.
+func normalizeClientJSONFields(obj map[string]any) {
+	normalizeInt := func(key string) {
+		raw, exists := obj[key]
+		if !exists {
+			return
+		}
+		s, ok := raw.(string)
+		if !ok {
+			return
+		}
+		trimmed := strings.ReplaceAll(strings.TrimSpace(s), " ", "")
+		if trimmed == "" {
+			delete(obj, key)
+			return
+		}
+		if n, err := strconv.ParseInt(trimmed, 10, 64); err == nil {
+			obj[key] = n
+		} else {
+			delete(obj, key)
+		}
+	}
+	for _, k := range []string{"tgId", "limitIp", "totalGB", "expiryTime", "reset", "created_at", "updated_at"} {
+		normalizeInt(k)
+	}
+}
+
+func seedClientsFromInboundJSON() error {
+	var inbounds []model.Inbound
+	if err := db.Find(&inbounds).Error; err != nil {
+		return err
+	}
+
+	return db.Transaction(func(tx *gorm.DB) error {
+		byEmail := map[string]*model.ClientRecord{}
+
+		for _, inbound := range inbounds {
+			if strings.TrimSpace(inbound.Settings) == "" {
+				continue
+			}
+			var settings map[string]any
+			if err := json.Unmarshal([]byte(inbound.Settings), &settings); err != nil {
+				log.Printf("ClientsTable seed: skip inbound %d (invalid settings json): %v", inbound.Id, err)
+				continue
+			}
+			rawList, ok := settings["clients"].([]any)
+			if !ok {
+				continue
+			}
+
+			for _, raw := range rawList {
+				obj, ok := raw.(map[string]any)
+				if !ok {
+					continue
+				}
+				normalizeClientJSONFields(obj)
+				blob, err := json.Marshal(obj)
+				if err != nil {
+					continue
+				}
+				var c model.Client
+				if err := json.Unmarshal(blob, &c); err != nil {
+					log.Printf("ClientsTable seed: skip client in inbound %d (unmarshal failed): %v; payload=%s",
+						inbound.Id, err, string(blob))
+					continue
+				}
+				email := strings.TrimSpace(c.Email)
+				if email == "" {
+					continue
+				}
+				incoming := c.ToRecord()
+
+				row, dup := byEmail[email]
+				if !dup {
+					if err := tx.Create(incoming).Error; err != nil {
+						return err
+					}
+					byEmail[email] = incoming
+					row = incoming
+				} else {
+					conflicts := model.MergeClientRecord(row, incoming)
+					for _, x := range conflicts {
+						log.Printf("client merge: email=%s conflict on %s old=%v new=%v kept=%v",
+							email, x.Field, x.Old, x.New, x.Kept)
+					}
+					if err := tx.Save(row).Error; err != nil {
+						return err
+					}
+				}
+
+				link := model.ClientInbound{
+					ClientId:     row.Id,
+					InboundId:    inbound.Id,
+					FlowOverride: c.Flow,
+				}
+				if err := tx.Where("client_id = ? AND inbound_id = ?", row.Id, inbound.Id).
+					FirstOrCreate(&link).Error; err != nil {
+					return err
+				}
+			}
+		}
+
+		return tx.Create(&model.HistoryOfSeeders{SeederName: "ClientsTable"}).Error
+	})
+}
+
+// seedApiTokens copies the legacy `apiToken` setting into the new
+// api_tokens table as a row named "default" so existing central panels
+// keep working after the upgrade. Idempotent — records itself in
+// history_of_seeders and only runs when api_tokens is empty.
+func seedApiTokens() error {
+	empty, err := isTableEmpty("api_tokens")
+	if err != nil {
+		return err
+	}
+	if empty {
+		var legacy model.Setting
+		err := db.Model(model.Setting{}).Where("key = ?", "apiToken").First(&legacy).Error
+		if err == nil && legacy.Value != "" {
+			row := &model.ApiToken{
+				Name:    "default",
+				Token:   legacy.Value,
+				Enabled: true,
+			}
+			if err := db.Create(row).Error; err != nil {
+				log.Printf("Error migrating legacy apiToken: %v", err)
+				return err
+			}
+		}
+	}
+	return db.Create(&model.HistoryOfSeeders{SeederName: "ApiTokensTable"}).Error
+}
+
+// isTableEmpty returns true if the named table contains zero rows.
+func isTableEmpty(tableName string) (bool, error) {
+	var count int64
+	err := db.Table(tableName).Count(&count).Error
+	return count == 0, err
+}
+
+// InitDB sets up the database connection, migrates models, and runs seeders.
+// When XUI_DB_TYPE=postgres, dbPath is ignored and XUI_DB_DSN is used instead.
+func InitDB(dbPath string) error {
+	var gormLogger logger.Interface
+	if config.IsDebug() {
+		gormLogger = logger.New(
+			log.New(os.Stdout, "\r\n", log.LstdFlags),
+			logger.Config{
+				SlowThreshold:             time.Second,
+				LogLevel:                  logger.Info,
+				IgnoreRecordNotFoundError: true,
+				Colorful:                  true,
+			},
+		)
+	} else {
+		gormLogger = logger.Discard
+	}
+	c := &gorm.Config{Logger: gormLogger}
+
+	var err error
+	switch config.GetDBKind() {
+	case "postgres":
+		dsn := config.GetDBDSN()
+		if dsn == "" {
+			return errors.New("XUI_DB_TYPE=postgres but XUI_DB_DSN is empty")
+		}
+		db, err = gorm.Open(postgres.Open(dsn), c)
+		if err != nil {
+			return err
+		}
+	default:
+		dir := path.Dir(dbPath)
+		if err = os.MkdirAll(dir, 0755); err != nil {
+			return err
+		}
+		dsn := dbPath + "?_journal_mode=WAL&_busy_timeout=10000&_synchronous=NORMAL&_txlock=immediate"
+		db, err = gorm.Open(sqlite.Open(dsn), c)
+		if err != nil {
+			return err
+		}
+		sqlDB, err := db.DB()
+		if err != nil {
+			return err
+		}
+		if _, err := sqlDB.Exec("PRAGMA journal_mode=WAL"); err != nil {
+			return err
+		}
+		if _, err := sqlDB.Exec("PRAGMA busy_timeout=10000"); err != nil {
+			return err
+		}
+		if _, err := sqlDB.Exec("PRAGMA synchronous=NORMAL"); err != nil {
+			return err
+		}
+	}
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		return err
+	}
+	sqlDB.SetMaxOpenConns(8)
+	sqlDB.SetMaxIdleConns(4)
+	sqlDB.SetConnMaxLifetime(time.Hour)
+
+	if err := initModels(); err != nil {
+		return err
+	}
+
+	isUsersEmpty, err := isTableEmpty("users")
+	if err != nil {
+		return err
+	}
+
+	if err := initUser(); err != nil {
+		return err
+	}
+	return runSeeders(isUsersEmpty)
+}
+
+// CloseDB closes the database connection if it exists.
+func CloseDB() error {
+	if db != nil {
+		sqlDB, err := db.DB()
+		if err != nil {
+			return err
+		}
+		return sqlDB.Close()
+	}
+	return nil
+}
+
+// GetDB returns the global GORM database instance.
 func GetDB() *gorm.DB {
 	return db
 }
 
 func IsNotFound(err error) bool {
-	return err == gorm.ErrRecordNotFound
+	return errors.Is(err, gorm.ErrRecordNotFound)
+}
+
+// IsSQLiteDB checks if the given file is a valid SQLite database by reading its signature.
+func IsSQLiteDB(file io.ReaderAt) (bool, error) {
+	signature := []byte("SQLite format 3\x00")
+	buf := make([]byte, len(signature))
+	_, err := file.ReadAt(buf, 0)
+	if err != nil {
+		return false, err
+	}
+	return bytes.Equal(buf, signature), nil
+}
+
+// Checkpoint performs a WAL checkpoint on the SQLite database to ensure data consistency.
+// No-op on PostgreSQL (WAL there is managed by the server).
+func Checkpoint() error {
+	if IsPostgres() {
+		return nil
+	}
+	return db.Exec("PRAGMA wal_checkpoint;").Error
+}
+
+// ValidateSQLiteDB opens the provided sqlite DB path with a throw-away connection
+// and runs a PRAGMA integrity_check to ensure the file is structurally sound.
+// It does not mutate global state or run migrations.
+func ValidateSQLiteDB(dbPath string) error {
+	if _, err := os.Stat(dbPath); err != nil { // file must exist
+		return err
+	}
+	gdb, err := gorm.Open(sqlite.Open(dbPath), &gorm.Config{Logger: logger.Discard})
+	if err != nil {
+		return err
+	}
+	sqlDB, err := gdb.DB()
+	if err != nil {
+		return err
+	}
+	defer sqlDB.Close()
+	var res string
+	if err := gdb.Raw("PRAGMA integrity_check;").Scan(&res).Error; err != nil {
+		return err
+	}
+	if res != "ok" {
+		return errors.New("sqlite integrity check failed: " + res)
+	}
+	return nil
 }

database/dialect.go

@@ -0,0 +1,26 @@
+package database
+
+import "fmt"
+
+// JSONClientsFromInbound returns the FROM clause that yields one row per element
+// of inbounds.settings -> clients, with a column named `client.value` whose text
+// fields can be read with JSONFieldText("client.value", "<key>").
+func JSONClientsFromInbound() string {
+	if IsPostgres() {
+		return "FROM inbounds, jsonb_array_elements(inbounds.settings::jsonb -> 'clients') AS client(value)"
+	}
+	return "FROM inbounds, JSON_EACH(JSON_EXTRACT(inbounds.settings, '$.clients')) AS client"
+}
+
+// JSONFieldText returns a SQL expression that extracts the textual value of <key>
+// from a JSON expression. On both backends the result is the raw (unquoted) string,
+// so callers do NOT need to trim surrounding quotes.
+func JSONFieldText(expr, key string) string {
+	if IsPostgres() {
+		return fmt.Sprintf("(%s ->> '%s')", expr, key)
+	}
+	// SQLite's JSON_EXTRACT on a text value returns the JSON-encoded form
+	// (with surrounding quotes). Wrap it in json_extract(json_quote(...)) trick
+	// is fragile; simpler: unwrap quotes with TRIM(BOTH '"').
+	return fmt.Sprintf("TRIM(JSON_EXTRACT(%s, '$.%s'), '\"')", expr, key)
+}

database/migrate_data.go

@@ -0,0 +1,143 @@
+package database
+
+import (
+	"errors"
+	"fmt"
+	"log"
+	"os"
+	"path"
+	"reflect"
+	"time"
+
+	"github.com/mhsanaei/3x-ui/v3/database/model"
+	"github.com/mhsanaei/3x-ui/v3/xray"
+
+	"gorm.io/driver/postgres"
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+// migrationModels is the FK-aware order in which tables are created and copied.
+// Parents come before their children so foreign-key constraints stay satisfied
+// even when checks are not explicitly disabled.
+func migrationModels() []any {
+	return []any{
+		&model.User{},
+		&model.Setting{},
+		&model.HistoryOfSeeders{},
+		&model.CustomGeoResource{},
+		&model.Node{},
+		&model.ApiToken{},
+		&model.Inbound{},
+		&xray.ClientTraffic{},
+		&model.OutboundTraffics{},
+		&model.InboundClientIps{},
+		&model.ClientRecord{},
+		&model.ClientInbound{},
+		&model.InboundFallback{},
+	}
+}
+
+// MigrateData copies every row from the configured SQLite file at srcPath into
+// a fresh PostgreSQL database described by dstDSN. The destination tables are
+// (re)created with AutoMigrate before the copy. Source data is left untouched.
+func MigrateData(srcPath, dstDSN string) error {
+	if _, err := os.Stat(srcPath); err != nil {
+		return fmt.Errorf("source sqlite not found at %s: %w", srcPath, err)
+	}
+	if dstDSN == "" {
+		return errors.New("destination DSN is required")
+	}
+
+	if err := os.MkdirAll(path.Dir(srcPath), 0755); err != nil {
+		return err
+	}
+
+	srcDSN := srcPath + "?_journal_mode=WAL&_busy_timeout=10000"
+	src, err := gorm.Open(sqlite.Open(srcDSN), &gorm.Config{Logger: logger.Discard})
+	if err != nil {
+		return fmt.Errorf("open sqlite source: %w", err)
+	}
+	srcSQL, err := src.DB()
+	if err != nil {
+		return err
+	}
+	defer srcSQL.Close()
+
+	dst, err := gorm.Open(postgres.Open(dstDSN), &gorm.Config{Logger: logger.Discard})
+	if err != nil {
+		return fmt.Errorf("open postgres destination: %w", err)
+	}
+	dstSQL, err := dst.DB()
+	if err != nil {
+		return err
+	}
+	defer dstSQL.Close()
+	dstSQL.SetConnMaxLifetime(time.Hour)
+
+	log.Println("Creating destination schema...")
+	for _, m := range migrationModels() {
+		if err := dst.AutoMigrate(m); err != nil {
+			return fmt.Errorf("AutoMigrate %T: %w", m, err)
+		}
+	}
+
+	totalRows := 0
+	for _, m := range migrationModels() {
+		n, err := copyTable(src, dst, m)
+		if err != nil {
+			return fmt.Errorf("copy %T: %w", m, err)
+		}
+		totalRows += n
+		log.Printf("  %-32s %d rows", reflect.TypeOf(m).Elem().Name(), n)
+	}
+
+	if err := resetPostgresSequences(dst); err != nil {
+		log.Printf("warning: failed to reset some postgres sequences: %v", err)
+	}
+
+	log.Printf("Migration complete: %d rows across %d tables.", totalRows, len(migrationModels()))
+	log.Println("Set XUI_DB_TYPE=postgres and XUI_DB_DSN=... in /etc/default/x-ui, then restart x-ui.")
+	return nil
+}
+
+// copyTable streams every row of `mdl` from src to dst in batches.
+func copyTable(src, dst *gorm.DB, mdl any) (int, error) {
+	sliceType := reflect.SliceOf(reflect.PointerTo(reflect.TypeOf(mdl).Elem()))
+	batchPtr := reflect.New(sliceType)
+	batchPtr.Elem().Set(reflect.MakeSlice(sliceType, 0, 0))
+
+	total := 0
+	err := src.Model(mdl).FindInBatches(batchPtr.Interface(), 500, func(tx *gorm.DB, _ int) error {
+		batch := batchPtr.Elem()
+		if batch.Len() == 0 {
+			return nil
+		}
+		if err := dst.CreateInBatches(batchPtr.Interface(), 200).Error; err != nil {
+			return err
+		}
+		total += batch.Len()
+		return nil
+	}).Error
+	return total, err
+}
+
+// resetPostgresSequences advances each table's id sequence past MAX(id),
+// otherwise the next INSERT-without-id would clash with copied rows.
+func resetPostgresSequences(dst *gorm.DB) error {
+	tables := []string{
+		"users", "inbounds", "outbound_traffics", "settings", "inbound_client_ips",
+		"client_traffics", "history_of_seeders", "custom_geo_resources", "nodes",
+		"api_tokens", "client_records", "client_inbounds", "inbound_fallback_children",
+	}
+	for _, t := range tables {
+		// setval is a no-op if the table or its id sequence doesn't exist; we ignore errors per-table.
+		_ = dst.Exec(fmt.Sprintf(
+			`SELECT setval(pg_get_serial_sequence('%s','id'), COALESCE((SELECT MAX(id) FROM "%s"), 1), true)
+			 WHERE pg_get_serial_sequence('%s','id') IS NOT NULL`,
+			t, t, t,
+		)).Error
+	}
+	return nil
+}

database/model/model.go

@@ -1,63 +1,232 @@
+// Package model defines the database models and data structures used by the 3x-ui panel.
 package model
 
 import (
+	"bytes"
+	"encoding/json"
 	"fmt"
-	"x-ui/util/json_util"
-	"x-ui/xray"
+	"strings"
+
+	"github.com/mhsanaei/3x-ui/v3/util/json_util"
+	"github.com/mhsanaei/3x-ui/v3/xray"
 )
 
+// Protocol represents the protocol type for Xray inbounds.
 type Protocol string
 
+// Protocol constants for different Xray inbound protocols
 const (
-	VMess       Protocol = "vmess"
+	VMESS       Protocol = "vmess"
 	VLESS       Protocol = "vless"
-	Dokodemo    Protocol = "Dokodemo-door"
-	Http        Protocol = "http"
+	Tunnel      Protocol = "tunnel"
+	HTTP        Protocol = "http"
 	Trojan      Protocol = "trojan"
 	Shadowsocks Protocol = "shadowsocks"
+	Mixed       Protocol = "mixed"
+	WireGuard   Protocol = "wireguard"
+	Hysteria    Protocol = "hysteria"
+	Hysteria2   Protocol = "hysteria2"
 )
 
-type User struct {
-	Id       int    `json:"id" gorm:"primaryKey;autoIncrement"`
-	Username string `json:"username"`
-	Password string `json:"password"`
+// IsHysteria returns true for both "hysteria" and "hysteria2".
+// Use instead of a bare ==model.Hysteria check: a v2 inbound stored
+// with the literal v2 string would otherwise fall through (#4081).
+func IsHysteria(p Protocol) bool {
+	return p == Hysteria || p == Hysteria2
 }
 
-type Inbound struct {
-	Id          int                  `json:"id" form:"id" gorm:"primaryKey;autoIncrement"`
-	UserId      int                  `json:"-"`
-	Up          int64                `json:"up" form:"up"`
-	Down        int64                `json:"down" form:"down"`
-	Total       int64                `json:"total" form:"total"`
-	Remark      string               `json:"remark" form:"remark"`
-	Enable      bool                 `json:"enable" form:"enable"`
-	ExpiryTime  int64                `json:"expiryTime" form:"expiryTime"`
-	ClientStats []xray.ClientTraffic `gorm:"foreignKey:InboundId;references:Id" json:"clientStats" form:"clientStats"`
+// User represents a user account in the 3x-ui panel.
+type User struct {
+	Id         int    `json:"id" gorm:"primaryKey;autoIncrement"`
+	Username   string `json:"username"`
+	Password   string `json:"password"`
+	LoginEpoch int64  `json:"-" gorm:"default:0"`
+}
 
-	// config part
+// Inbound represents an Xray inbound configuration with traffic statistics and settings.
+type Inbound struct {
+	Id                   int                  `json:"id" form:"id" gorm:"primaryKey;autoIncrement"`                                                    // Unique identifier
+	UserId               int                  `json:"-"`                                                                                               // Associated user ID
+	Up                   int64                `json:"up" form:"up"`                                                                                    // Upload traffic in bytes
+	Down                 int64                `json:"down" form:"down"`                                                                                // Download traffic in bytes
+	Total                int64                `json:"total" form:"total"`                                                                              // Total traffic limit in bytes
+	Remark               string               `json:"remark" form:"remark"`                                                                            // Human-readable remark
+	Enable               bool                 `json:"enable" form:"enable" gorm:"index:idx_enable_traffic_reset,priority:1"`                           // Whether the inbound is enabled
+	ExpiryTime           int64                `json:"expiryTime" form:"expiryTime"`                                                                    // Expiration timestamp
+	TrafficReset         string               `json:"trafficReset" form:"trafficReset" gorm:"default:never;index:idx_enable_traffic_reset,priority:2"` // Traffic reset schedule
+	LastTrafficResetTime int64                `json:"lastTrafficResetTime" form:"lastTrafficResetTime" gorm:"default:0"`                               // Last traffic reset timestamp
+	ClientStats          []xray.ClientTraffic `gorm:"foreignKey:InboundId;references:Id" json:"clientStats" form:"clientStats"`                        // Client traffic statistics
+
+	// Xray configuration fields
 	Listen         string   `json:"listen" form:"listen"`
-	Port           int      `json:"port" form:"port" gorm:"unique"`
+	Port           int      `json:"port" form:"port"`
 	Protocol       Protocol `json:"protocol" form:"protocol"`
 	Settings       string   `json:"settings" form:"settings"`
 	StreamSettings string   `json:"streamSettings" form:"streamSettings"`
 	Tag            string   `json:"tag" form:"tag" gorm:"unique"`
 	Sniffing       string   `json:"sniffing" form:"sniffing"`
-}
-type InboundClientIps struct {
-	Id       int    `json:"id" gorm:"primaryKey;autoIncrement"`
-	ClientEmail string `json:"clientEmail" form:"clientEmail" gorm:"unique"`
-	Ips string `json:"ips" form:"ips"`
+	NodeID         *int     `json:"nodeId,omitempty" form:"nodeId" gorm:"index"`
+
+	// FallbackParent is populated by the API layer when this inbound is
+	// attached as a fallback child of a VLESS/Trojan TCP-TLS master.
+	// The frontend uses it to rewrite client-share links so they advertise
+	// the master's externally reachable endpoint instead of the child's
+	// loopback listen. Not persisted.
+	FallbackParent *FallbackParentInfo `json:"fallbackParent,omitempty" gorm:"-"`
 }
 
+// FallbackParentInfo carries everything the frontend needs to rewrite a
+// child inbound's client link: where to connect (the master's address
+// and port) and which path matched on the master's fallbacks array.
+// The frontend already has the master inbound in its dbInbounds list,
+// so we only ship identifiers + the match path here.
+type FallbackParentInfo struct {
+	MasterId int    `json:"masterId"`
+	Path     string `json:"path,omitempty"`
+}
+
+// OutboundTraffics tracks traffic statistics for Xray outbound connections.
+type OutboundTraffics struct {
+	Id    int    `json:"id" form:"id" gorm:"primaryKey;autoIncrement"`
+	Tag   string `json:"tag" form:"tag" gorm:"unique"`
+	Up    int64  `json:"up" form:"up" gorm:"default:0"`
+	Down  int64  `json:"down" form:"down" gorm:"default:0"`
+	Total int64  `json:"total" form:"total" gorm:"default:0"`
+}
+
+// InboundClientIps stores IP addresses associated with inbound clients for access control.
+type InboundClientIps struct {
+	Id          int    `json:"id" gorm:"primaryKey;autoIncrement"`
+	ClientEmail string `json:"clientEmail" form:"clientEmail" gorm:"unique"`
+	Ips         string `json:"ips" form:"ips"`
+}
+
+// MarshalJSON emits the Ips column as a real JSON array instead of an escaped
+// JSON-text string. Empty or unparseable storage renders as null so API
+// consumers don't have to special-case the legacy double-encoded shape.
+func (ic InboundClientIps) MarshalJSON() ([]byte, error) {
+	type alias InboundClientIps
+	return json.Marshal(struct {
+		alias
+		Ips json.RawMessage `json:"ips"`
+	}{
+		alias: alias(ic),
+		Ips:   jsonStringFieldToRaw(ic.Ips),
+	})
+}
+
+// UnmarshalJSON accepts ips as either a JSON array (modern shape) or a
+// JSON-encoded string (legacy shape), normalising back to the JSON-text the
+// column stores.
+func (ic *InboundClientIps) UnmarshalJSON(data []byte) error {
+	type alias InboundClientIps
+	aux := struct {
+		*alias
+		Ips json.RawMessage `json:"ips"`
+	}{
+		alias: (*alias)(ic),
+	}
+	if err := json.Unmarshal(data, &aux); err != nil {
+		return err
+	}
+	ic.Ips = jsonStringFieldFromRaw(aux.Ips)
+	return nil
+}
+
+// HistoryOfSeeders tracks which database seeders have been executed to prevent re-running.
+type HistoryOfSeeders struct {
+	Id         int    `json:"id" gorm:"primaryKey;autoIncrement"`
+	SeederName string `json:"seederName"`
+}
+
+type ApiToken struct {
+	Id        int    `json:"id" gorm:"primaryKey;autoIncrement"`
+	Name      string `json:"name" gorm:"uniqueIndex;not null"`
+	Token     string `json:"token" gorm:"not null"`
+	Enabled   bool   `json:"enabled" gorm:"default:true"`
+	CreatedAt int64  `json:"createdAt" gorm:"autoCreateTime:milli"`
+}
+
+// MarshalJSON emits settings, streamSettings, and sniffing as nested JSON
+// objects rather than escaped strings, so API consumers don't need to JSON.parse
+// a string inside a string. Empty fields render as null; fields whose stored
+// text isn't valid JSON fall back to a JSON-encoded string so no data is lost.
+func (i Inbound) MarshalJSON() ([]byte, error) {
+	type alias Inbound
+	return json.Marshal(struct {
+		alias
+		Settings       json.RawMessage `json:"settings"`
+		StreamSettings json.RawMessage `json:"streamSettings"`
+		Sniffing       json.RawMessage `json:"sniffing"`
+	}{
+		alias:          alias(i),
+		Settings:       jsonStringFieldToRaw(i.Settings),
+		StreamSettings: jsonStringFieldToRaw(i.StreamSettings),
+		Sniffing:       jsonStringFieldToRaw(i.Sniffing),
+	})
+}
+
+// UnmarshalJSON accepts settings, streamSettings, and sniffing as either a raw
+// JSON object/array (the modern shape MarshalJSON emits) or a JSON-encoded
+// string (the legacy shape). Either form is normalised back to the JSON-text
+// string the DB column stores.
+func (i *Inbound) UnmarshalJSON(data []byte) error {
+	type alias Inbound
+	aux := struct {
+		*alias
+		Settings       json.RawMessage `json:"settings"`
+		StreamSettings json.RawMessage `json:"streamSettings"`
+		Sniffing       json.RawMessage `json:"sniffing"`
+	}{
+		alias: (*alias)(i),
+	}
+	if err := json.Unmarshal(data, &aux); err != nil {
+		return err
+	}
+	i.Settings = jsonStringFieldFromRaw(aux.Settings)
+	i.StreamSettings = jsonStringFieldFromRaw(aux.StreamSettings)
+	i.Sniffing = jsonStringFieldFromRaw(aux.Sniffing)
+	return nil
+}
+
+func jsonStringFieldToRaw(s string) json.RawMessage {
+	trimmed := strings.TrimSpace(s)
+	if trimmed == "" {
+		return json.RawMessage("null")
+	}
+	if json.Valid([]byte(trimmed)) {
+		return json.RawMessage(trimmed)
+	}
+	b, _ := json.Marshal(s)
+	return b
+}
+
+func jsonStringFieldFromRaw(r json.RawMessage) string {
+	trimmed := bytes.TrimSpace(r)
+	if len(trimmed) == 0 || bytes.Equal(trimmed, []byte("null")) {
+		return ""
+	}
+	if trimmed[0] == '"' {
+		var s string
+		if err := json.Unmarshal(trimmed, &s); err == nil {
+			return s
+		}
+	}
+	return string(trimmed)
+}
+
+// GenXrayInboundConfig generates an Xray inbound configuration from the Inbound model.
 func (i *Inbound) GenXrayInboundConfig() *xray.InboundConfig {
 	listen := i.Listen
-	if listen != "" {
-		listen = fmt.Sprintf("\"%v\"", listen)
+	if listen == "" {
+		listen = "0.0.0.0"
 	}
+	listen = fmt.Sprintf("\"%v\"", listen)
+	protocol := string(i.Protocol)
 	return &xray.InboundConfig{
 		Listen:         json_util.RawMessage(listen),
 		Port:           i.Port,
-		Protocol:       string(i.Protocol),
+		Protocol:       protocol,
 		Settings:       json_util.RawMessage(i.Settings),
 		StreamSettings: json_util.RawMessage(i.StreamSettings),
 		Tag:            i.Tag,
@@ -65,18 +234,347 @@ func (i *Inbound) GenXrayInboundConfig() *xray.InboundConfig {
 	}
 }
 
+// Setting stores key-value configuration settings for the 3x-ui panel.
 type Setting struct {
 	Id    int    `json:"id" form:"id" gorm:"primaryKey;autoIncrement"`
 	Key   string `json:"key" form:"key"`
 	Value string `json:"value" form:"value"`
 }
 
+// Node represents a remote 3x-ui panel registered with the central panel.
+// The central panel polls each node's existing /panel/api/server/status
+// endpoint over HTTP using the per-node ApiToken to populate the runtime
+// status fields below.
+type Node struct {
+	Id                  int    `json:"id" form:"id" gorm:"primaryKey;autoIncrement"`
+	Name                string `json:"name" form:"name" gorm:"uniqueIndex"`
+	Remark              string `json:"remark" form:"remark"`
+	Scheme              string `json:"scheme" form:"scheme"`
+	Address             string `json:"address" form:"address"`
+	Port                int    `json:"port" form:"port"`
+	BasePath            string `json:"basePath" form:"basePath"`
+	ApiToken            string `json:"apiToken" form:"apiToken"`
+	Enable              bool   `json:"enable" form:"enable" gorm:"default:true"`
+	AllowPrivateAddress bool   `json:"allowPrivateAddress" form:"allowPrivateAddress" gorm:"default:false"`
+
+	// Heartbeat-updated fields. UpdatedAt advances on every probe even when
+	// the row is otherwise unchanged so the UI's "last seen" tooltip is
+	// truthful without us having to read LastHeartbeat separately.
+	Status        string  `json:"status" gorm:"default:unknown"` // online|offline|unknown
+	LastHeartbeat int64   `json:"lastHeartbeat"`                 // unix seconds, 0 = never
+	LatencyMs     int     `json:"latencyMs"`
+	XrayVersion   string  `json:"xrayVersion"`
+	PanelVersion  string  `json:"panelVersion" gorm:"column:panel_version"`
+	CpuPct        float64 `json:"cpuPct"`
+	MemPct        float64 `json:"memPct"`
+	UptimeSecs    uint64  `json:"uptimeSecs"`
+	LastError     string  `json:"lastError"`
+
+	InboundCount  int `json:"inboundCount" gorm:"-"`
+	ClientCount   int `json:"clientCount" gorm:"-"`
+	OnlineCount   int `json:"onlineCount" gorm:"-"`
+	DepletedCount int `json:"depletedCount" gorm:"-"`
+
+	CreatedAt int64 `json:"createdAt" gorm:"autoCreateTime:milli"`
+	UpdatedAt int64 `json:"updatedAt" gorm:"autoUpdateTime:milli"`
+}
+
+type CustomGeoResource struct {
+	Id            int    `json:"id" gorm:"primaryKey;autoIncrement"`
+	Type          string `json:"type" gorm:"not null;uniqueIndex:idx_custom_geo_type_alias;column:geo_type"`
+	Alias         string `json:"alias" gorm:"not null;uniqueIndex:idx_custom_geo_type_alias"`
+	Url           string `json:"url" gorm:"not null"`
+	LocalPath     string `json:"localPath" gorm:"column:local_path"`
+	LastUpdatedAt int64  `json:"lastUpdatedAt" gorm:"default:0;column:last_updated_at"`
+	LastModified  string `json:"lastModified" gorm:"column:last_modified"`
+	CreatedAt     int64  `json:"createdAt" gorm:"autoCreateTime:milli;column:created_at"`
+	UpdatedAt     int64  `json:"updatedAt" gorm:"autoUpdateTime:milli;column:updated_at"`
+}
+
+type ClientReverse struct {
+	Tag string `json:"tag"`
+}
+
+// Client represents a client configuration for Xray inbounds with traffic limits and settings.
 type Client struct {
-	ID         string `json:"id"`
-	AlterIds   uint16 `json:"alterId"`
-	Email      string `json:"email"`
-	LimitIP    int    `json:"limitIp"`
+	ID         string         `json:"id,omitempty"`                 // Unique client identifier
+	Security   string         `json:"security"`                     // Security method (e.g., "auto", "aes-128-gcm")
+	Password   string         `json:"password,omitempty"`           // Client password
+	Flow       string         `json:"flow,omitempty"`               // Flow control (XTLS)
+	Reverse    *ClientReverse `json:"reverse,omitempty"`            // VLESS simple reverse proxy settings
+	Auth       string         `json:"auth,omitempty"`               // Auth password (Hysteria)
+	Email      string         `json:"email"`                        // Client email identifier
+	LimitIP    int            `json:"limitIp"`                      // IP limit for this client
+	TotalGB    int64          `json:"totalGB" form:"totalGB"`       // Total traffic limit in GB
+	ExpiryTime int64          `json:"expiryTime" form:"expiryTime"` // Expiration timestamp
+	Enable     bool           `json:"enable" form:"enable"`         // Whether the client is enabled
+	TgID       int64          `json:"tgId" form:"tgId"`             // Telegram user ID for notifications
+	SubID      string         `json:"subId" form:"subId"`           // Subscription identifier
+	Comment    string         `json:"comment" form:"comment"`       // Client comment
+	Reset      int            `json:"reset" form:"reset"`           // Reset period in days
+	CreatedAt  int64          `json:"created_at,omitempty"`         // Creation timestamp
+	UpdatedAt  int64          `json:"updated_at,omitempty"`         // Last update timestamp
+}
+
+type ClientRecord struct {
+	Id         int    `json:"id" gorm:"primaryKey;autoIncrement"`
+	Email      string `json:"email" gorm:"uniqueIndex;not null"`
+	SubID      string `json:"subId" gorm:"index;column:sub_id"`
+	UUID       string `json:"uuid" gorm:"column:uuid"`
+	Password   string `json:"password"`
+	Auth       string `json:"auth"`
+	Flow       string `json:"flow"`
 	Security   string `json:"security"`
-	TotalGB    int64  `json:"totalGB" form:"totalGB"`
-	ExpiryTime int64  `json:"expiryTime" form:"expiryTime"`
+	Reverse    string `json:"reverse" gorm:"column:reverse"`
+	LimitIP    int    `json:"limitIp" gorm:"column:limit_ip"`
+	TotalGB    int64  `json:"totalGB" gorm:"column:total_gb"`
+	ExpiryTime int64  `json:"expiryTime" gorm:"column:expiry_time"`
+	Enable     bool   `json:"enable" gorm:"default:true"`
+	TgID       int64  `json:"tgId" gorm:"column:tg_id"`
+	Comment    string `json:"comment"`
+	Reset      int    `json:"reset" gorm:"default:0"`
+	CreatedAt  int64  `json:"createdAt" gorm:"autoCreateTime:milli"`
+	UpdatedAt  int64  `json:"updatedAt" gorm:"autoUpdateTime:milli"`
+}
+
+func (ClientRecord) TableName() string { return "clients" }
+
+// MarshalJSON emits the reverse column as a nested JSON object rather than an
+// escaped JSON-text string, matching the same convention Inbound uses for its
+// JSON-text columns. Empty storage renders as null.
+func (r ClientRecord) MarshalJSON() ([]byte, error) {
+	type alias ClientRecord
+	return json.Marshal(struct {
+		alias
+		Reverse json.RawMessage `json:"reverse"`
+	}{
+		alias:   alias(r),
+		Reverse: jsonStringFieldToRaw(r.Reverse),
+	})
+}
+
+// UnmarshalJSON accepts reverse as either a JSON object (modern shape) or a
+// JSON-encoded string (legacy shape).
+func (r *ClientRecord) UnmarshalJSON(data []byte) error {
+	type alias ClientRecord
+	aux := struct {
+		*alias
+		Reverse json.RawMessage `json:"reverse"`
+	}{
+		alias: (*alias)(r),
+	}
+	if err := json.Unmarshal(data, &aux); err != nil {
+		return err
+	}
+	r.Reverse = jsonStringFieldFromRaw(aux.Reverse)
+	return nil
+}
+
+type ClientInbound struct {
+	ClientId     int    `json:"clientId" gorm:"primaryKey;column:client_id;index"`
+	InboundId    int    `json:"inboundId" gorm:"primaryKey;column:inbound_id;index"`
+	FlowOverride string `json:"flowOverride" gorm:"column:flow_override"`
+	CreatedAt    int64  `json:"createdAt" gorm:"autoCreateTime:milli"`
+}
+
+func (ClientInbound) TableName() string { return "client_inbounds" }
+
+// InboundFallback is one routing rule on a master inbound's
+// settings.fallbacks array. The master is always a VLESS or Trojan
+// inbound on TCP transport with TLS or Reality. The child is any other
+// inbound — its listen+port becomes the fallback dest, with optional
+// SNI/ALPN/path match criteria pulled from the same row.
+type InboundFallback struct {
+	Id        int    `json:"id" gorm:"primaryKey;autoIncrement"`
+	MasterId  int    `json:"masterId" gorm:"index;not null;column:master_id"`
+	ChildId   int    `json:"childId" gorm:"index;not null;column:child_id"`
+	Name      string `json:"name"`
+	Alpn      string `json:"alpn"`
+	Path      string `json:"path"`
+	Xver      int    `json:"xver"`
+	SortOrder int    `json:"sortOrder" gorm:"default:0;column:sort_order"`
+}
+
+func (InboundFallback) TableName() string { return "inbound_fallbacks" }
+
+func (c *Client) ToRecord() *ClientRecord {
+	rec := &ClientRecord{
+		Email:      c.Email,
+		SubID:      c.SubID,
+		UUID:       c.ID,
+		Password:   c.Password,
+		Auth:       c.Auth,
+		Flow:       c.Flow,
+		Security:   c.Security,
+		LimitIP:    c.LimitIP,
+		TotalGB:    c.TotalGB,
+		ExpiryTime: c.ExpiryTime,
+		Enable:     c.Enable,
+		TgID:       c.TgID,
+		Comment:    c.Comment,
+		Reset:      c.Reset,
+		CreatedAt:  c.CreatedAt,
+		UpdatedAt:  c.UpdatedAt,
+	}
+	if c.Reverse != nil {
+		if b, err := json.Marshal(c.Reverse); err == nil {
+			rec.Reverse = string(b)
+		}
+	}
+	return rec
+}
+
+func (r *ClientRecord) ToClient() *Client {
+	c := &Client{
+		ID:         r.UUID,
+		Email:      r.Email,
+		SubID:      r.SubID,
+		Password:   r.Password,
+		Auth:       r.Auth,
+		Flow:       r.Flow,
+		Security:   r.Security,
+		LimitIP:    r.LimitIP,
+		TotalGB:    r.TotalGB,
+		ExpiryTime: r.ExpiryTime,
+		Enable:     r.Enable,
+		TgID:       r.TgID,
+		Comment:    r.Comment,
+		Reset:      r.Reset,
+		CreatedAt:  r.CreatedAt,
+		UpdatedAt:  r.UpdatedAt,
+	}
+	if r.Reverse != "" {
+		var rev ClientReverse
+		if err := json.Unmarshal([]byte(r.Reverse), &rev); err == nil {
+			c.Reverse = &rev
+		}
+	}
+	return c
+}
+
+type ClientMergeConflict struct {
+	Field string
+	Old   any
+	New   any
+	Kept  any
+}
+
+func MergeClientRecord(existing *ClientRecord, incoming *ClientRecord) []ClientMergeConflict {
+	var conflicts []ClientMergeConflict
+	keep := func(field string, oldV, newV, kept any) {
+		conflicts = append(conflicts, ClientMergeConflict{Field: field, Old: oldV, New: newV, Kept: kept})
+	}
+	const redacted = "<redacted>"
+	keepSecret := func(field string) {
+		conflicts = append(conflicts, ClientMergeConflict{Field: field, Old: redacted, New: redacted, Kept: redacted})
+	}
+
+	incomingNewer := incoming.UpdatedAt > existing.UpdatedAt ||
+		(incoming.UpdatedAt == existing.UpdatedAt && incoming.CreatedAt > existing.CreatedAt)
+
+	if existing.UUID != incoming.UUID && incoming.UUID != "" {
+		if incomingNewer || existing.UUID == "" {
+			existing.UUID = incoming.UUID
+		}
+		keepSecret("uuid")
+	}
+	if existing.Password != incoming.Password && incoming.Password != "" {
+		if incomingNewer || existing.Password == "" {
+			existing.Password = incoming.Password
+			keepSecret("password")
+		}
+	}
+	if existing.Auth != incoming.Auth && incoming.Auth != "" {
+		if incomingNewer || existing.Auth == "" {
+			existing.Auth = incoming.Auth
+			keepSecret("auth")
+		}
+	}
+	if existing.Flow != incoming.Flow && incoming.Flow != "" {
+		if incomingNewer || existing.Flow == "" {
+			keep("flow", existing.Flow, incoming.Flow, incoming.Flow)
+			existing.Flow = incoming.Flow
+		}
+	}
+	if existing.Security != incoming.Security && incoming.Security != "" {
+		if incomingNewer || existing.Security == "" {
+			keep("security", existing.Security, incoming.Security, incoming.Security)
+			existing.Security = incoming.Security
+		}
+	}
+	if existing.SubID != incoming.SubID && incoming.SubID != "" {
+		if incomingNewer || existing.SubID == "" {
+			existing.SubID = incoming.SubID
+			keepSecret("subId")
+		}
+	}
+	if existing.TotalGB != incoming.TotalGB {
+		picked := existing.TotalGB
+		if existing.TotalGB == 0 || (incoming.TotalGB != 0 && incoming.TotalGB > existing.TotalGB) {
+			picked = incoming.TotalGB
+		}
+		if picked != existing.TotalGB {
+			keep("totalGB", existing.TotalGB, incoming.TotalGB, picked)
+			existing.TotalGB = picked
+		}
+	}
+	if existing.ExpiryTime != incoming.ExpiryTime {
+		picked := existing.ExpiryTime
+		if existing.ExpiryTime == 0 || (incoming.ExpiryTime != 0 && incoming.ExpiryTime > existing.ExpiryTime) {
+			picked = incoming.ExpiryTime
+		}
+		if picked != existing.ExpiryTime {
+			keep("expiryTime", existing.ExpiryTime, incoming.ExpiryTime, picked)
+			existing.ExpiryTime = picked
+		}
+	}
+	if existing.LimitIP != incoming.LimitIP && incoming.LimitIP != 0 {
+		picked := existing.LimitIP
+		if existing.LimitIP == 0 || incoming.LimitIP > existing.LimitIP {
+			picked = incoming.LimitIP
+		}
+		if picked != existing.LimitIP {
+			keep("limitIp", existing.LimitIP, incoming.LimitIP, picked)
+			existing.LimitIP = picked
+		}
+	}
+	if existing.TgID != incoming.TgID && incoming.TgID != 0 {
+		if incomingNewer || existing.TgID == 0 {
+			keep("tgId", existing.TgID, incoming.TgID, incoming.TgID)
+			existing.TgID = incoming.TgID
+		}
+	}
+	if existing.Reset != incoming.Reset && incoming.Reset != 0 {
+		if incomingNewer || existing.Reset == 0 {
+			keep("reset", existing.Reset, incoming.Reset, incoming.Reset)
+			existing.Reset = incoming.Reset
+		}
+	}
+	if existing.Reverse != incoming.Reverse && incoming.Reverse != "" {
+		if incomingNewer || existing.Reverse == "" {
+			keep("reverse", existing.Reverse, incoming.Reverse, incoming.Reverse)
+			existing.Reverse = incoming.Reverse
+		}
+	}
+	if existing.Comment != incoming.Comment && incoming.Comment != "" {
+		if incomingNewer || existing.Comment == "" {
+			keep("comment", existing.Comment, incoming.Comment, incoming.Comment)
+			existing.Comment = incoming.Comment
+		}
+	}
+	if existing.Enable != incoming.Enable {
+		if incoming.Enable {
+			if !existing.Enable {
+				keep("enable", existing.Enable, incoming.Enable, true)
+				existing.Enable = true
+			}
+		}
+	}
+	if incoming.CreatedAt != 0 && (existing.CreatedAt == 0 || incoming.CreatedAt < existing.CreatedAt) {
+		existing.CreatedAt = incoming.CreatedAt
+	}
+	if incoming.UpdatedAt > existing.UpdatedAt {
+		existing.UpdatedAt = incoming.UpdatedAt
+	}
+	return conflicts
 }

database/model/model_test.go

@@ -0,0 +1,209 @@
+package model
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestInboundMarshalJSONNestsObjectFields(t *testing.T) {
+	in := Inbound{
+		Id:             7,
+		Protocol:       VLESS,
+		Port:           443,
+		Settings:       `{"clients":[],"decryption":"none"}`,
+		StreamSettings: `{"network":"tcp"}`,
+		Sniffing:       `{"enabled":true}`,
+	}
+	out, err := json.Marshal(in)
+	if err != nil {
+		t.Fatalf("Marshal failed: %v", err)
+	}
+	var parsed map[string]any
+	if err := json.Unmarshal(out, &parsed); err != nil {
+		t.Fatalf("output is not valid JSON: %v", err)
+	}
+	for _, field := range []string{"settings", "streamSettings", "sniffing"} {
+		if _, ok := parsed[field].(map[string]any); !ok {
+			t.Errorf("expected %s to marshal as a JSON object, got %T", field, parsed[field])
+		}
+	}
+	if strings.Contains(string(out), `"settings":"`) {
+		t.Errorf("settings should not be emitted as a JSON string: %s", out)
+	}
+}
+
+func TestInboundMarshalJSONEmptyFieldsBecomeNull(t *testing.T) {
+	in := Inbound{Id: 1, Protocol: VLESS}
+	out, err := json.Marshal(in)
+	if err != nil {
+		t.Fatalf("Marshal failed: %v", err)
+	}
+	var parsed map[string]any
+	if err := json.Unmarshal(out, &parsed); err != nil {
+		t.Fatalf("output is not valid JSON: %v", err)
+	}
+	for _, field := range []string{"settings", "streamSettings", "sniffing"} {
+		if parsed[field] != nil {
+			t.Errorf("expected %s to be null, got %v", field, parsed[field])
+		}
+	}
+}
+
+func TestInboundUnmarshalJSONAcceptsBothShapes(t *testing.T) {
+	cases := []struct {
+		name string
+		body string
+	}{
+		{
+			name: "nested objects (modern)",
+			body: `{"id":1,"settings":{"clients":[],"decryption":"none"},"streamSettings":{"network":"tcp"},"sniffing":{"enabled":true}}`,
+		},
+		{
+			name: "JSON-encoded strings (legacy)",
+			body: `{"id":1,"settings":"{\"clients\":[],\"decryption\":\"none\"}","streamSettings":"{\"network\":\"tcp\"}","sniffing":"{\"enabled\":true}"}`,
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var in Inbound
+			if err := json.Unmarshal([]byte(tc.body), &in); err != nil {
+				t.Fatalf("Unmarshal failed: %v", err)
+			}
+			if !strings.Contains(in.Settings, `"decryption":"none"`) {
+				t.Errorf("Settings not normalised: %q", in.Settings)
+			}
+			if !strings.Contains(in.StreamSettings, `"network":"tcp"`) {
+				t.Errorf("StreamSettings not normalised: %q", in.StreamSettings)
+			}
+			if !strings.Contains(in.Sniffing, `"enabled":true`) {
+				t.Errorf("Sniffing not normalised: %q", in.Sniffing)
+			}
+		})
+	}
+}
+
+func TestInboundMarshalJSONInvalidTextFallsBackToString(t *testing.T) {
+	in := Inbound{Id: 1, Settings: "not json at all"}
+	out, err := json.Marshal(in)
+	if err != nil {
+		t.Fatalf("Marshal failed: %v", err)
+	}
+	if !strings.Contains(string(out), `"settings":"not json at all"`) {
+		t.Errorf("expected invalid settings text to be wrapped as a JSON string, got %s", out)
+	}
+}
+
+func TestClientRecordMarshalJSONNestsReverse(t *testing.T) {
+	rec := ClientRecord{Id: 1, Email: "alice@example.com", Reverse: `{"tag":"vless-in"}`}
+	out, err := json.Marshal(rec)
+	if err != nil {
+		t.Fatalf("Marshal failed: %v", err)
+	}
+	var parsed map[string]any
+	if err := json.Unmarshal(out, &parsed); err != nil {
+		t.Fatalf("output is not valid JSON: %v", err)
+	}
+	obj, ok := parsed["reverse"].(map[string]any)
+	if !ok {
+		t.Fatalf("expected reverse to marshal as a JSON object, got %T", parsed["reverse"])
+	}
+	if obj["tag"] != "vless-in" {
+		t.Errorf("expected tag to be preserved, got %v", obj["tag"])
+	}
+}
+
+func TestClientRecordMarshalJSONEmptyReverseIsNull(t *testing.T) {
+	rec := ClientRecord{Id: 1, Email: "alice@example.com"}
+	out, err := json.Marshal(rec)
+	if err != nil {
+		t.Fatalf("Marshal failed: %v", err)
+	}
+	var parsed map[string]any
+	if err := json.Unmarshal(out, &parsed); err != nil {
+		t.Fatalf("output is not valid JSON: %v", err)
+	}
+	if parsed["reverse"] != nil {
+		t.Errorf("expected reverse to be null, got %v", parsed["reverse"])
+	}
+}
+
+func TestClientRecordUnmarshalJSONAcceptsBothShapes(t *testing.T) {
+	cases := []struct {
+		name string
+		body string
+	}{
+		{name: "nested object", body: `{"id":1,"reverse":{"tag":"vless-in"}}`},
+		{name: "legacy string", body: `{"id":1,"reverse":"{\"tag\":\"vless-in\"}"}`},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var rec ClientRecord
+			if err := json.Unmarshal([]byte(tc.body), &rec); err != nil {
+				t.Fatalf("Unmarshal failed: %v", err)
+			}
+			if !strings.Contains(rec.Reverse, `"tag":"vless-in"`) {
+				t.Errorf("Reverse not normalised: %q", rec.Reverse)
+			}
+		})
+	}
+}
+
+func TestInboundClientIpsMarshalJSONNestsArray(t *testing.T) {
+	row := InboundClientIps{Id: 1, ClientEmail: "alice@example.com", Ips: `[{"ip":"1.2.3.4","timestamp":1700000000}]`}
+	out, err := json.Marshal(row)
+	if err != nil {
+		t.Fatalf("Marshal failed: %v", err)
+	}
+	var parsed map[string]any
+	if err := json.Unmarshal(out, &parsed); err != nil {
+		t.Fatalf("output is not valid JSON: %v", err)
+	}
+	arr, ok := parsed["ips"].([]any)
+	if !ok {
+		t.Fatalf("expected ips to marshal as a JSON array, got %T", parsed["ips"])
+	}
+	if len(arr) != 1 {
+		t.Errorf("expected 1 entry, got %d", len(arr))
+	}
+}
+
+func TestInboundClientIpsUnmarshalJSONAcceptsBothShapes(t *testing.T) {
+	cases := []struct {
+		name string
+		body string
+	}{
+		{name: "nested array", body: `{"id":1,"ips":[{"ip":"1.2.3.4","timestamp":1}]}`},
+		{name: "legacy string", body: `{"id":1,"ips":"[{\"ip\":\"1.2.3.4\",\"timestamp\":1}]"}`},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var row InboundClientIps
+			if err := json.Unmarshal([]byte(tc.body), &row); err != nil {
+				t.Fatalf("Unmarshal failed: %v", err)
+			}
+			if !strings.Contains(row.Ips, `"ip":"1.2.3.4"`) {
+				t.Errorf("Ips not normalised: %q", row.Ips)
+			}
+		})
+	}
+}
+
+func TestIsHysteria(t *testing.T) {
+	cases := []struct {
+		in   Protocol
+		want bool
+	}{
+		{Hysteria, true},
+		{Hysteria2, true},
+		{VLESS, false},
+		{Shadowsocks, false},
+		{Protocol(""), false},
+		{Protocol("hysteria3"), false},
+	}
+	for _, c := range cases {
+		if got := IsHysteria(c.in); got != c.want {
+			t.Errorf("IsHysteria(%q) = %v, want %v", c.in, got, c.want)
+		}
+	}
+}

docker-compose.yml

@@ -0,0 +1,34 @@
+services:
+  3xui:
+    build:
+      context: .
+      dockerfile: ./Dockerfile
+    container_name: 3xui_app
+    # hostname: yourhostname <- optional
+    volumes:
+      - $PWD/db/:/etc/x-ui/
+      - $PWD/cert/:/root/cert/
+    environment:
+      XRAY_VMESS_AEAD_FORCED: "false"
+      XUI_ENABLE_FAIL2BAN: "true"
+      # To use PostgreSQL instead of the default SQLite, run:
+      #   docker compose --profile postgres up -d
+      # and uncomment the two lines below.
+      # XUI_DB_TYPE: "postgres"
+      # XUI_DB_DSN: "postgres://xui:xui@postgres:5432/xui?sslmode=disable"
+    tty: true
+    ports:
+      - "2053:2053"
+    restart: unless-stopped
+
+  postgres:
+    image: postgres:16-alpine
+    container_name: 3xui_postgres
+    profiles: ["postgres"]
+    environment:
+      POSTGRES_USER: xui
+      POSTGRES_PASSWORD: xui
+      POSTGRES_DB: xui
+    volumes:
+      - $PWD/pgdata/:/var/lib/postgresql/data
+    restart: unless-stopped

frontend/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+.vite/
+*.log

frontend/README.md

@@ -0,0 +1,83 @@
+# 3x-ui frontend
+
+React 19 + Ant Design 6 + TypeScript + Vite 8. Multi-page app — one HTML
+entry per panel route — built into `../web/dist/` and embedded into the
+Go binary via `embed.FS`.
+
+## Dev
+
+```sh
+npm install
+npm run dev
+```
+
+Vite serves on `http://localhost:5173/`. API calls and `/panel/*` routes
+proxy to the Go panel at `http://localhost:2053/`, so start the Go panel
+first (`go run main.go`) and then Vite.
+
+The proxy auto-rewrites `/panel`, `/panel/settings`, `/panel/inbounds`,
+`/panel/xray` to the matching Vite-served HTML in dev mode (see
+`MIGRATED_ROUTES` in `vite.config.js`), so the sidebar's
+production-style links work without round-tripping through Go.
+
+## Production build
+
+```sh
+npm run build
+```
+
+Outputs to `../web/dist/` (HTML at the root, hashed JS/CSS under
+`assets/`). The Go binary embeds this directory at compile time and
+`web/controller/dist.go` serves the per-page HTML.
+
+## Type check and lint
+
+```sh
+npm run typecheck
+npm run lint
+```
+
+`tsc --noEmit` against `tsconfig.json` (strict mode, `jsx: "react-jsx"`,
+`@/*` → `src/*` alias). ESLint 10 with `eslint.config.js` (flat config)
+— `@eslint/js` recommended plus `typescript-eslint` and
+`eslint-plugin-react-hooks` rules.
+
+## Layout
+
+```
+frontend/
+├── *.html                 # Vite entry HTML, one per panel route
+├── tsconfig.json
+├── eslint.config.js
+├── vite.config.js
+└── src/
+    ├── entries/           # Per-page bootstrap (createRoot + render)
+    ├── pages/             # One folder per route, each with the page
+    │   ├── index/         # component + helpers + sub-components
+    │   ├── login/
+    │   ├── inbounds/
+    │   ├── clients/
+    │   ├── xray/
+    │   ├── nodes/
+    │   ├── settings/
+    │   ├── api-docs/
+    │   └── sub/
+    ├── components/        # Cross-page React components
+    ├── hooks/             # Reusable hooks (useTheme, useWebSocket, …)
+    ├── api/               # Axios setup, CSRF interceptor, WebSocket
+    ├── i18n/              # react-i18next init (locales live in web/translation/)
+    ├── models/            # Inbound, Outbound, Status, … domain classes
+    ├── styles/            # Shared CSS modules (page-cards, …)
+    └── utils/             # HttpUtil, ObjectUtil, LanguageManager, …
+```
+
+## Adding a new page
+
+1. Add `frontend/<page>.html` referencing `/src/entries/<page>.tsx`.
+2. Add `src/entries/<page>.tsx` that imports the page component and
+   mounts it with `createRoot(...).render(...)`.
+3. Add the page component under `src/pages/<page>/`.
+4. Register the entry in `rollupOptions.input` in `vite.config.js`.
+5. If the page is reachable from the sidebar at `/panel/<route>`, add
+   it to `MIGRATED_ROUTES` so the dev proxy serves the Vite HTML.
+6. Wire the Go controller to `serveDistPage(c, "<page>.html")`.

frontend/api-docs.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>API Docs</title>
+  </head>
+  <body>
+    <div id="message"></div>
+    <div id="app"></div>
+    <script type="module" src="/src/entries/api-docs.tsx"></script>
+  </body>
+</html>

frontend/clients.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Clients</title>
+  </head>
+  <body>
+    <div id="message"></div>
+    <div id="app"></div>
+    <script type="module" src="/src/entries/clients.tsx"></script>
+  </body>
+</html>

frontend/eslint.config.js

@@ -0,0 +1,71 @@
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import reactHooks from 'eslint-plugin-react-hooks';
+import globals from 'globals';
+
+export default [
+  { ignores: ['node_modules/**', '../web/dist/**'] },
+  js.configs.recommended,
+  {
+    files: ['**/*.js'],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+    },
+    rules: {
+      'no-unused-vars': ['warn', {
+        argsIgnorePattern: '^_',
+        varsIgnorePattern: '^_',
+        caughtErrorsIgnorePattern: '^_',
+      }],
+      'no-empty': ['error', { allowEmptyCatch: true }],
+      'no-case-declarations': 'off',
+    },
+  },
+  ...tseslint.configs.recommended.map((config) => ({
+    ...config,
+    files: ['**/*.{ts,tsx}'],
+  })),
+  {
+    files: ['**/*.{ts,tsx}'],
+    plugins: {
+      'react-hooks': reactHooks,
+    },
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+      globals: {
+        ...globals.browser,
+      },
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      '@typescript-eslint/no-unused-vars': ['warn', {
+        argsIgnorePattern: '^_',
+        varsIgnorePattern: '^_',
+        caughtErrorsIgnorePattern: '^_',
+      }],
+      'no-empty': ['error', { allowEmptyCatch: true }],
+
+      // react-hooks v7 introduces several new rules driven by the React
+      // Compiler. The migration uses several legitimate patterns those
+      // rules flag (initial-fetch in useEffect, dirty-check derived
+      // state, `Date.now()` inside derive helpers, inline arrow event
+      // handlers, in-place mutation of imported Outbound class
+      // instances in the OutboundFormModal). We're not running the
+      // compiler, so the memoization-preservation warnings have no
+      // effect on runtime — turning them off until the codebase
+      // stabilises.
+      'react-hooks/set-state-in-effect': 'off',
+      'react-hooks/purity': 'off',
+      'react-hooks/react-compiler': 'off',
+      'react-hooks/preserve-manual-memoization': 'off',
+      'react-hooks/immutability': 'off',
+      'react-hooks/refs': 'off',
+    },
+  },
+];

frontend/inbounds.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Inbounds</title>
+  </head>
+  <body>
+    <div id="message"></div>
+    <div id="app"></div>
+    <script type="module" src="/src/entries/inbounds.tsx"></script>
+  </body>
+</html>

frontend/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Overview</title>
+  </head>
+  <body>
+    <div id="message"></div>
+    <div id="app"></div>
+    <script type="module" src="/src/entries/index.tsx"></script>
+  </body>
+</html>

frontend/login.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="robots" content="noindex,nofollow" />
+    <title>Sign in</title>
+  </head>
+  <body>
+    <div id="message"></div>
+    <div id="app"></div>
+    <script type="module" src="/src/entries/login.tsx"></script>
+  </body>
+</html>

frontend/nodes.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Nodes</title>
+  </head>
+  <body>
+    <div id="message"></div>
+    <div id="app"></div>
+    <script type="module" src="/src/entries/nodes.tsx"></script>
+  </body>
+</html>

frontend/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "3x-ui-frontend",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "description": "3x-ui panel frontend (React 19 + Ant Design 6 + Vite 8).",
+  "engines": {
+    "node": ">=22.0.0",
+    "npm": ">=10.0.0"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ant-design/icons": "^6.2.3",
+    "@codemirror/lang-json": "^6.0.2",
+    "@codemirror/theme-one-dark": "^6.1.3",
+    "antd": "^6.4.3",
+    "axios": "^1.16.1",
+    "codemirror": "^6.0.2",
+    "dayjs": "^1.11.20",
+    "i18next": "^26.2.0",
+    "otpauth": "^9.5.1",
+    "persian-calendar-suite": "^1.5.5",
+    "qs": "^6.15.2",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "react-i18next": "^17.0.8"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.2",
+    "eslint": "^10.4.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.6.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.4",
+    "vite": "8.0.13"
+  }
+}

frontend/settings.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Settings</title>
+  </head>
+  <body>
+    <div id="message"></div>
+    <div id="app"></div>
+    <script type="module" src="/src/entries/settings.tsx"></script>
+  </body>
+</html>

frontend/src/api/axios-init.js

@@ -0,0 +1,128 @@
+import axios from 'axios';
+import qs from 'qs';
+
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'TRACE']);
+const CSRF_TOKEN_PATH = '/csrf-token';
+
+let csrfToken = null;
+let csrfFetchPromise = null;
+let sessionExpired = false;
+
+function readMetaToken() {
+  return document.querySelector('meta[name="csrf-token"]')?.getAttribute('content') || null;
+}
+
+async function fetchCsrfToken() {
+  try {
+    const basePath = window.X_UI_BASE_PATH;
+    const url = (typeof basePath === 'string' && basePath !== '' && basePath !== '/'
+      ? basePath.replace(/\/$/, '') + CSRF_TOKEN_PATH
+      : CSRF_TOKEN_PATH);
+    const res = await fetch(url, {
+      method: 'GET',
+      credentials: 'same-origin',
+      headers: { 'X-Requested-With': 'XMLHttpRequest' },
+    });
+    if (!res.ok) return null;
+    const json = await res.json();
+    return json?.success && typeof json.obj === 'string' ? json.obj : null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+async function ensureCsrfToken() {
+  if (csrfToken) return csrfToken;
+  const meta = readMetaToken();
+  if (meta) {
+    csrfToken = meta;
+    return csrfToken;
+  }
+  if (!csrfFetchPromise) csrfFetchPromise = fetchCsrfToken();
+  const fetched = await csrfFetchPromise;
+  csrfFetchPromise = null;
+  if (fetched) csrfToken = fetched;
+  return csrfToken;
+}
+
+// Apply the panel's axios defaults + interceptors. Call once at app
+// startup before any HTTP call goes out.
+export function setupAxios() {
+  axios.defaults.headers.post['Content-Type'] = 'application/x-www-form-urlencoded; charset=UTF-8';
+  axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';
+
+  // Read base path from window object or fallback to meta tag (for Cloudflare Rocket Loader compatibility)
+  let basePath = window.X_UI_BASE_PATH;
+  if (!basePath) {
+    const metaTag = document.querySelector('meta[name="base-path"]');
+    basePath = metaTag ? metaTag.getAttribute('content') : null;
+  }
+  if (typeof basePath === 'string' && basePath !== '' && basePath !== '/') {
+    axios.defaults.baseURL = basePath;
+  }
+
+  // Seed the cache from the meta tag if a server-rendered page injected
+  // one — saves a round trip on legacy templates that still embed it.
+  csrfToken = readMetaToken();
+
+  axios.interceptors.request.use(
+    async (config) => {
+      config.headers = config.headers || {};
+      const method = (config.method || 'get').toUpperCase();
+      if (!SAFE_METHODS.has(method)) {
+        const token = await ensureCsrfToken();
+        if (token) config.headers['X-CSRF-Token'] = token;
+      }
+      if (config.data instanceof FormData) {
+        config.headers['Content-Type'] = 'multipart/form-data';
+      } else {
+        const declaredType = String(config.headers['Content-Type'] || config.headers['content-type'] || '');
+        if (declaredType.toLowerCase().startsWith('application/json')) {
+          if (config.data !== undefined && typeof config.data !== 'string') {
+            config.data = JSON.stringify(config.data);
+          }
+        } else {
+          config.data = qs.stringify(config.data, { arrayFormat: 'repeat' });
+        }
+      }
+      return config;
+    },
+    (error) => Promise.reject(error),
+  );
+
+  axios.interceptors.response.use(
+    (response) => response,
+    async (error) => {
+      const status = error.response?.status;
+      if (status === 401) {
+        if (!sessionExpired) {
+          sessionExpired = true;
+          const basePath = window.X_UI_BASE_PATH || '/';
+          window.location.replace(basePath);
+        }
+        return new Promise(() => { });
+      }
+      // 403 with a stale/missing CSRF token: drop the cache, re-fetch, retry once.
+      const cfg = error.config;
+      if (status === 403 && cfg && !cfg.__csrfRetried) {
+        csrfToken = null;
+        cfg.__csrfRetried = true;
+        const token = await ensureCsrfToken();
+        if (token) {
+          cfg.headers = cfg.headers || {};
+          cfg.headers['X-CSRF-Token'] = token;
+          const declaredType = String(cfg.headers['Content-Type'] || cfg.headers['content-type'] || '');
+          if (typeof cfg.data === 'string') {
+            if (declaredType.toLowerCase().startsWith('application/json')) {
+              try { cfg.data = JSON.parse(cfg.data); } catch (_e) { /* keep as-is */ }
+            } else {
+              cfg.data = qs.parse(cfg.data);
+            }
+          }
+          return axios(cfg);
+        }
+      }
+      return Promise.reject(error);
+    },
+  );
+}

frontend/src/api/websocket.js

@@ -0,0 +1,231 @@
+/**
+ * WebSocket client for real-time panel updates.
+ *
+ * Public API (kept stable for index.html / inbounds.html / xray.html):
+ *   - connect()                     — open the connection (idempotent)
+ *   - disconnect()                  — close and stop reconnecting
+ *   - on(event, callback)           — subscribe to event
+ *   - off(event, callback)          — unsubscribe
+ *   - send(data)                    — send JSON to the server
+ *   - isConnected                   — boolean, current state
+ *   - reconnectAttempts             — number, attempts since last success
+ *   - maxReconnectAttempts          — number, give-up threshold
+ *
+ * Built-in events:
+ *   'connected', 'disconnected', 'error', 'message',
+ *   plus any server-emitted message type (status, traffic, client_stats, ...).
+ */
+export class WebSocketClient {
+  static #MAX_PAYLOAD_BYTES = 10 * 1024 * 1024; // 10 MB, mirrors hub maxMessageSize.
+  static #BASE_RECONNECT_MS = 1000;
+  static #MAX_RECONNECT_MS = 30_000;
+  // After exhausting maxReconnectAttempts we switch to a polite slow-retry
+  // cadence rather than giving up forever — a panel that recovers an hour
+  // later should reconnect without a manual page reload.
+  static #SLOW_RETRY_MS = 60_000;
+
+  constructor(basePath = '') {
+    this.basePath = basePath;
+    this.maxReconnectAttempts = 10;
+    this.reconnectAttempts = 0;
+    this.isConnected = false;
+
+    this.ws = null;
+    this.shouldReconnect = true;
+    this.reconnectTimer = null;
+    this.listeners = new Map(); // event → Set<callback>
+  }
+
+  // Open the connection. Safe to call repeatedly — no-op if already
+  // open/connecting. Re-enables reconnects if previously disabled. Cancels
+  // any pending reconnect timer so an external connect() can't race a
+  // delayed retry into spawning a second socket.
+  connect() {
+    if (this.ws && (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING)) {
+      return;
+    }
+    this.shouldReconnect = true;
+    this.#cancelReconnect();
+    this.#openSocket();
+  }
+
+  // Close the connection and stop any pending reconnect attempt. Resets the
+  // attempt counter so a future connect() starts fresh from the small backoff.
+  disconnect() {
+    this.shouldReconnect = false;
+    this.#cancelReconnect();
+    this.reconnectAttempts = 0;
+    if (this.ws) {
+      try { this.ws.close(1000, 'client disconnect'); } catch { /* ignore */ }
+      this.ws = null;
+    }
+    this.isConnected = false;
+  }
+
+  // Subscribe to an event. Re-subscribing the same callback is a no-op.
+  on(event, callback) {
+    if (typeof callback !== 'function') return;
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(callback);
+  }
+
+  // Unsubscribe from an event.
+  off(event, callback) {
+    const set = this.listeners.get(event);
+    if (!set) return;
+    set.delete(callback);
+    if (set.size === 0) this.listeners.delete(event);
+  }
+
+  // Send JSON to the server. Drops silently if not connected — callers
+  // should rely on connect()/server pushes rather than client-initiated sends.
+  send(data) {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(data));
+    }
+  }
+
+  // ───── internals ─────
+
+  #openSocket() {
+    const url = this.#buildUrl();
+    let socket;
+    try {
+      socket = new WebSocket(url);
+    } catch (err) {
+      console.error('WebSocket: failed to construct connection', err);
+      this.#emit('error', err);
+      this.#scheduleReconnect();
+      return;
+    }
+    this.ws = socket;
+
+    // Every handler must check `this.ws !== socket` first. A previous socket
+    // can still fire events (especially `close`) after we've moved on to a
+    // new one — e.g. connect() called while the old socket is in CLOSING
+    // state. Without the guard, a stale close would null out the freshly
+    // opened socket and silently break send().
+    socket.addEventListener('open', () => {
+      if (this.ws !== socket) return;
+      this.isConnected = true;
+      this.reconnectAttempts = 0;
+      this.#emit('connected');
+    });
+
+    socket.addEventListener('message', (event) => {
+      if (this.ws !== socket) return;
+      this.#onMessage(event);
+    });
+
+    socket.addEventListener('error', (event) => {
+      if (this.ws !== socket) return;
+      // Browsers fire 'error' before 'close' on failure. We surface it for
+      // consumers (so polling fallbacks can engage) but don't log every blip
+      // — bad networks would flood the console otherwise.
+      this.#emit('error', event);
+    });
+
+    socket.addEventListener('close', () => {
+      if (this.ws !== socket) return;
+      this.isConnected = false;
+      this.ws = null;
+      this.#emit('disconnected');
+      if (this.shouldReconnect) this.#scheduleReconnect();
+    });
+  }
+
+  #buildUrl() {
+    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    // basePath comes from window.X_UI_BASE_PATH which is only injected
+    // by the Go binary in production. In dev (Vite serves directly) the
+    // global is missing and basePath would be '' — without the fallback to
+    // '/' we'd build `ws://host:portws` (no separator) and the WebSocket
+    // constructor throws a SyntaxError.
+    let basePath = this.basePath || '/';
+    if (!basePath.startsWith('/')) basePath = '/' + basePath;
+    if (!basePath.endsWith('/')) basePath += '/';
+    return `${protocol}//${window.location.host}${basePath}ws`;
+  }
+
+  #onMessage(event) {
+    const data = event.data;
+    // Reject oversized payloads up front. We compare actual UTF-8 byte
+    // length (via Blob.size) against the limit — string.length counts
+    // UTF-16 code units, which can undercount real bytes by up to 4× for
+    // payloads with non-ASCII characters and bypass the cap.
+    if (typeof data === 'string') {
+      const byteLen = new Blob([data]).size;
+      if (byteLen > WebSocketClient.#MAX_PAYLOAD_BYTES) {
+        console.error(`WebSocket: payload too large (${byteLen} bytes), closing`);
+        try { this.ws?.close(1009, 'message too big'); } catch { /* ignore */ }
+        return;
+      }
+    }
+    let message;
+    try {
+      message = JSON.parse(data);
+    } catch (err) {
+      console.error('WebSocket: invalid JSON message', err);
+      return;
+    }
+    if (!message || typeof message !== 'object' || typeof message.type !== 'string') {
+      console.error('WebSocket: malformed message envelope');
+      return;
+    }
+    this.#emit(message.type, message.payload, message.time);
+    this.#emit('message', message);
+  }
+
+  #emit(event, ...args) {
+    const set = this.listeners.get(event);
+    if (!set) return;
+    for (const callback of set) {
+      try {
+        callback(...args);
+      } catch (err) {
+        console.error(`WebSocket: handler for "${event}" threw`, err);
+      }
+    }
+  }
+
+  #scheduleReconnect() {
+    if (!this.shouldReconnect) return;
+    this.#cancelReconnect();
+
+    let base;
+    if (this.reconnectAttempts < this.maxReconnectAttempts) {
+      this.reconnectAttempts += 1;
+      // Exponential backoff inside the active window.
+      const exp = WebSocketClient.#BASE_RECONNECT_MS * 2 ** (this.reconnectAttempts - 1);
+      base = Math.min(WebSocketClient.#MAX_RECONNECT_MS, exp);
+    } else {
+      // Active window exhausted — keep trying once a minute. The page-level
+      // polling fallback runs in parallel; this just brings WS back when the
+      // network recovers.
+      base = WebSocketClient.#SLOW_RETRY_MS;
+    }
+    // ±25% jitter so reloads after a panel restart don't reconnect in lockstep.
+    const delay = base * (0.75 + Math.random() * 0.5);
+
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      // clearTimeout doesn't cancel a callback that has already fired but
+      // whose macrotask hasn't run yet — re-check shouldReconnect here so
+      // disconnect() called in that window can't be overridden.
+      if (!this.shouldReconnect) return;
+      this.#openSocket();
+    }, delay);
+  }
+
+  #cancelReconnect() {
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+}
+

frontend/src/components/AppSidebar.css

@@ -0,0 +1,287 @@
+.ant-sidebar > .ant-layout-sider {
+  position: sticky;
+  top: 0;
+  height: 100vh;
+  align-self: flex-start;
+}
+
+.sider-brand,
+.drawer-brand {
+  font-weight: 600;
+  font-size: 18px;
+  letter-spacing: 0.5px;
+  color: rgba(0, 0, 0, 0.88);
+}
+
+.sider-brand {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 14px 14px;
+  border-bottom: 1px solid rgba(128, 128, 128, 0.15);
+  user-select: none;
+}
+
+.sider-brand-collapsed {
+  justify-content: center;
+  font-size: 16px;
+  padding: 14px 4px;
+  letter-spacing: 0;
+}
+
+.brand-block {
+  display: inline-flex;
+  flex-direction: column;
+  align-items: center;
+  min-width: 0;
+  line-height: 1.1;
+}
+
+.brand-text {
+  display: block;
+}
+
+.brand-version {
+  display: block;
+  width: 100%;
+  text-align: center;
+  font-size: 10px;
+  font-weight: 500;
+  letter-spacing: 0;
+  opacity: 0.6;
+  margin-top: 2px;
+}
+
+.sider-brand-collapsed .brand-block {
+  align-items: center;
+  flex: 0 0 auto;
+}
+
+.brand-actions {
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  flex-shrink: 0;
+}
+
+.sidebar-donate {
+  background: transparent;
+  border: none;
+  width: 30px;
+  height: 30px;
+  border-radius: 50%;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: rgba(0, 0, 0, 0.75);
+  text-decoration: none;
+  flex-shrink: 0;
+  transition: background-color 0.2s, transform 0.15s, color 0.2s;
+}
+
+.sidebar-donate:hover,
+.sidebar-donate:focus-visible {
+  background-color: rgba(236, 72, 153, 0.12);
+  color: #ec4899;
+  transform: scale(1.08);
+  outline: none;
+}
+
+.sidebar-donate .anticon {
+  font-size: 16px;
+}
+
+.sidebar-theme-cycle {
+  background: transparent;
+  border: none;
+  width: 30px;
+  height: 30px;
+  border-radius: 50%;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  color: rgba(0, 0, 0, 0.75);
+  padding: 0;
+  flex-shrink: 0;
+  transition: background-color 0.2s, transform 0.15s, color 0.2s;
+}
+
+.sidebar-theme-cycle:hover,
+.sidebar-theme-cycle:focus-visible {
+  background-color: rgba(64, 150, 255, 0.1);
+  color: #4096ff;
+  transform: scale(1.08);
+  outline: none;
+}
+
+.sidebar-theme-cycle svg {
+  width: 16px;
+  height: 16px;
+}
+
+.drawer-header-actions {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.drawer-handle {
+  position: fixed;
+  top: 12px;
+  left: 12px;
+  z-index: 1100;
+  background: rgba(0, 0, 0, 0.55);
+  color: #fff;
+  border: none;
+  width: 40px;
+  height: 40px;
+  border-radius: 50%;
+  cursor: pointer;
+  display: none;
+  align-items: center;
+  justify-content: center;
+  font-size: 18px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.25);
+}
+
+.drawer-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 14px 16px;
+  border-bottom: 1px solid rgba(128, 128, 128, 0.15);
+}
+
+.drawer-close {
+  background: transparent;
+  border: none;
+  width: 32px;
+  height: 32px;
+  border-radius: 50%;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  font-size: 16px;
+  color: rgba(0, 0, 0, 0.65);
+}
+
+.drawer-close:hover,
+.drawer-close:focus-visible {
+  background: rgba(128, 128, 128, 0.18);
+}
+
+.drawer-menu .ant-menu-item {
+  height: 48px;
+  line-height: 48px;
+  margin: 0;
+  border-radius: 0;
+}
+
+.drawer-menu .ant-menu-item .anticon {
+  font-size: 16px;
+}
+
+.drawer-utility {
+  margin-top: auto;
+  border-top: 1px solid rgba(128, 128, 128, 0.15);
+}
+
+.ant-sidebar > .ant-layout-sider .ant-layout-sider-children {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+}
+
+.sider-nav {
+  flex: 1 1 auto;
+  overflow-y: auto;
+  overflow-x: hidden;
+  min-height: 0;
+}
+
+.sider-utility {
+  flex: 0 0 auto;
+  border-top: 1px solid rgba(128, 128, 128, 0.15);
+}
+
+@media (max-width: 768px) {
+  .drawer-handle {
+    display: inline-flex;
+  }
+
+  .ant-sidebar > .ant-layout-sider .ant-layout-sider-children,
+  .ant-sidebar > .ant-layout-sider .ant-layout-sider-trigger {
+    display: none;
+  }
+
+  .ant-sidebar > .ant-layout-sider {
+    flex: 0 0 0 !important;
+    max-width: 0 !important;
+    min-width: 0 !important;
+    width: 0 !important;
+  }
+}
+
+body.dark .drawer-brand,
+body.dark .sider-brand {
+  color: rgba(255, 255, 255, 0.92);
+}
+
+html[data-theme='ultra-dark'] .drawer-brand,
+html[data-theme='ultra-dark'] .sider-brand {
+  color: #ffffff;
+}
+
+body.dark .drawer-close {
+  color: rgba(255, 255, 255, 0.75);
+}
+
+html[data-theme='ultra-dark'] .drawer-close {
+  color: rgba(255, 255, 255, 0.85);
+}
+
+body.dark .sidebar-theme-cycle {
+  color: rgba(255, 255, 255, 0.85);
+}
+
+html[data-theme='ultra-dark'] .sidebar-theme-cycle {
+  color: rgba(255, 255, 255, 0.92);
+}
+
+body.dark .sidebar-donate {
+  color: rgba(255, 255, 255, 0.85);
+}
+
+html[data-theme='ultra-dark'] .sidebar-donate {
+  color: rgba(255, 255, 255, 0.92);
+}
+
+body.dark .ant-drawer .ant-drawer-content,
+body.dark .ant-drawer .ant-drawer-body {
+  background: #252526 !important;
+}
+
+html[data-theme='ultra-dark'] .ant-drawer .ant-drawer-content,
+html[data-theme='ultra-dark'] .ant-drawer .ant-drawer-body {
+  background: #0a0a0a !important;
+}
+
+.sider-nav .ant-menu-item-selected,
+.sider-utility .ant-menu-item-selected,
+.drawer-menu .ant-menu-item-selected {
+  background-color: rgba(64, 150, 255, 0.2) !important;
+  color: #4096ff !important;
+}
+
+.sider-nav .ant-menu-item-active:not(.ant-menu-item-selected),
+.sider-utility .ant-menu-item-active:not(.ant-menu-item-selected),
+.drawer-menu .ant-menu-item-active:not(.ant-menu-item-selected),
+.sider-nav .ant-menu-item:not(.ant-menu-item-selected):not(.ant-menu-item-disabled):hover,
+.sider-utility .ant-menu-item:not(.ant-menu-item-selected):not(.ant-menu-item-disabled):hover,
+.drawer-menu .ant-menu-item:not(.ant-menu-item-selected):not(.ant-menu-item-disabled):hover {
+  background-color: rgba(64, 150, 255, 0.1) !important;
+  color: #4096ff !important;
+}

frontend/src/components/AppSidebar.tsx

@@ -0,0 +1,290 @@
+import { useCallback, useMemo, useState } from 'react';
+import type { ComponentType } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Drawer, Layout, Menu } from 'antd';
+import type { MenuProps } from 'antd';
+import {
+  ApiOutlined,
+  ClusterOutlined,
+  CloseOutlined,
+  DashboardOutlined,
+  HeartOutlined,
+  LogoutOutlined,
+  MenuOutlined,
+  SettingOutlined,
+  TeamOutlined,
+  ToolOutlined,
+  UserOutlined,
+} from '@ant-design/icons';
+
+import { HttpUtil } from '@/utils';
+import { pauseAnimationsUntilLeave, useTheme } from '@/hooks/useTheme';
+import './AppSidebar.css';
+
+const SIDEBAR_COLLAPSED_KEY = 'isSidebarCollapsed';
+const DONATE_URL = 'https://donate.sanaei.dev/';
+
+interface AppSidebarProps {
+  basePath?: string;
+  requestUri?: string;
+}
+
+type IconName = 'dashboard' | 'user' | 'team' | 'setting' | 'tool' | 'cluster' | 'logout' | 'apidocs';
+
+const iconByName: Record<IconName, ComponentType> = {
+  dashboard: DashboardOutlined,
+  user: UserOutlined,
+  team: TeamOutlined,
+  setting: SettingOutlined,
+  tool: ToolOutlined,
+  cluster: ClusterOutlined,
+  logout: LogoutOutlined,
+  apidocs: ApiOutlined,
+};
+
+function readCollapsed(): boolean {
+  try {
+    return JSON.parse(localStorage.getItem(SIDEBAR_COLLAPSED_KEY) || 'false');
+  } catch {
+    return false;
+  }
+}
+
+function DonateButton({ ariaLabel }: { ariaLabel: string }) {
+  return (
+    <a
+      href={DONATE_URL}
+      target="_blank"
+      rel="noopener noreferrer"
+      className="sidebar-donate"
+      aria-label={ariaLabel}
+      title={ariaLabel}
+    >
+      <HeartOutlined />
+    </a>
+  );
+}
+
+function ThemeCycleButton({ id, isDark, isUltra, onCycle, ariaLabel }: {
+  id: string;
+  isDark: boolean;
+  isUltra: boolean;
+  onCycle: () => void;
+  ariaLabel: string;
+}) {
+  return (
+    <button
+      id={id}
+      type="button"
+      className="sidebar-theme-cycle"
+      aria-label={ariaLabel}
+      title={ariaLabel}
+      onClick={onCycle}
+    >
+      {!isDark ? (
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+          <circle cx="12" cy="12" r="4" />
+          <path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M6.34 17.66l-1.41 1.41M19.07 4.93l-1.41 1.41" />
+        </svg>
+      ) : !isUltra ? (
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+          <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
+        </svg>
+      ) : (
+        <svg viewBox="0 0 24 24" fill="currentColor" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+          <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
+          <path fill="none" d="M19 3l0.7 1.4 1.4 0.7-1.4 0.7L19 7.2l-0.7-1.4-1.4-0.7 1.4-0.7z" />
+        </svg>
+      )}
+    </button>
+  );
+}
+
+export default function AppSidebar({ basePath = '', requestUri = '' }: AppSidebarProps) {
+  const { t } = useTranslation();
+  const { isDark, isUltra, toggleTheme, toggleUltra } = useTheme();
+
+  const [collapsed, setCollapsed] = useState<boolean>(() => readCollapsed());
+  const [drawerOpen, setDrawerOpen] = useState(false);
+
+  const prefix = basePath.startsWith('/') ? basePath : `/${basePath || ''}`;
+  const currentTheme: 'light' | 'dark' = isDark ? 'dark' : 'light';
+  const panelVersion = window.X_UI_CUR_VER || '';
+
+  const tabs = useMemo<{ key: string; icon: IconName; title: string }[]>(() => [
+    { key: `${prefix}panel/`, icon: 'dashboard', title: t('menu.dashboard') },
+    { key: `${prefix}panel/inbounds`, icon: 'user', title: t('menu.inbounds') },
+    { key: `${prefix}panel/clients`, icon: 'team', title: t('menu.clients') },
+    { key: `${prefix}panel/nodes`, icon: 'cluster', title: t('menu.nodes') },
+    { key: `${prefix}panel/settings`, icon: 'setting', title: t('menu.settings') },
+    { key: `${prefix}panel/xray`, icon: 'tool', title: t('menu.xray') },
+    { key: `${prefix}panel/api-docs`, icon: 'apidocs', title: t('menu.apiDocs') },
+    { key: 'logout', icon: 'logout', title: t('logout') },
+  ], [prefix, t]);
+
+  const navItems = useMemo(() => tabs.filter((tab) => tab.icon !== 'logout'), [tabs]);
+  const utilItems = useMemo(() => tabs.filter((tab) => tab.icon === 'logout'), [tabs]);
+
+  const toMenuItems = useCallback((items: typeof tabs): MenuProps['items'] =>
+    items.map((tab) => {
+      const Icon = iconByName[tab.icon];
+      return {
+        key: tab.key,
+        icon: <Icon />,
+        label: tab.title,
+      };
+    }),
+  []);
+
+  const openLink = useCallback(async (key: string) => {
+    if (key === 'logout') {
+      await HttpUtil.post('/logout');
+      window.location.href = basePath || '/';
+      return;
+    }
+    if (key.startsWith('http')) {
+      window.open(key);
+    } else {
+      window.location.href = key;
+    }
+  }, [basePath]);
+
+  const onMenuClick = useCallback<NonNullable<MenuProps['onClick']>>(({ key }) => {
+    openLink(String(key));
+  }, [openLink]);
+
+  const onSiderCollapse = useCallback((isCollapsed: boolean, type: 'clickTrigger' | 'responsive') => {
+    if (type === 'clickTrigger') {
+      localStorage.setItem(SIDEBAR_COLLAPSED_KEY, String(isCollapsed));
+      setCollapsed(isCollapsed);
+    }
+  }, []);
+
+  const cycleTheme = useCallback((id: string) => {
+    pauseAnimationsUntilLeave(id);
+    if (!isDark) {
+      toggleTheme();
+      if (isUltra) toggleUltra();
+    } else if (!isUltra) {
+      toggleUltra();
+    } else {
+      toggleUltra();
+      toggleTheme();
+    }
+  }, [isDark, isUltra, toggleTheme, toggleUltra]);
+
+  return (
+    <div className="ant-sidebar">
+      <Layout.Sider
+        theme={currentTheme}
+        collapsible
+        collapsed={collapsed}
+        breakpoint="md"
+        onCollapse={onSiderCollapse}
+      >
+        <div className={`sider-brand${collapsed ? ' sider-brand-collapsed' : ''}`}>
+          <div className="brand-block">
+            <span className="brand-text">{collapsed ? '3X' : '3X-UI'}</span>
+            {!collapsed && panelVersion && (
+              <span className="brand-version">v{panelVersion}</span>
+            )}
+          </div>
+          {!collapsed && (
+            <div className="brand-actions">
+              <DonateButton ariaLabel={t('menu.donate') || 'Donate'} />
+              <ThemeCycleButton
+                id="theme-cycle"
+                isDark={isDark}
+                isUltra={isUltra}
+                onCycle={() => cycleTheme('theme-cycle')}
+                ariaLabel={t('menu.theme')}
+              />
+            </div>
+          )}
+        </div>
+        <Menu
+          theme={currentTheme}
+          mode="inline"
+          selectedKeys={[requestUri]}
+          className="sider-nav"
+          items={toMenuItems(navItems)}
+          onClick={onMenuClick}
+        />
+        <Menu
+          theme={currentTheme}
+          mode="inline"
+          selectedKeys={[requestUri]}
+          className="sider-utility"
+          items={toMenuItems(utilItems)}
+          onClick={onMenuClick}
+        />
+      </Layout.Sider>
+
+      <Drawer
+        placement="left"
+        closable={false}
+        open={drawerOpen}
+        rootClassName={currentTheme}
+        size="min(82vw, 320px)"
+        styles={{
+          wrapper: { padding: 0 },
+          body: { padding: 0, display: 'flex', flexDirection: 'column', height: '100%' },
+          header: { display: 'none' },
+        }}
+        onClose={() => setDrawerOpen(false)}
+      >
+        <div className="drawer-header">
+          <div className="brand-block">
+            <span className="drawer-brand">3X-UI</span>
+            {panelVersion && <span className="brand-version">v{panelVersion}</span>}
+          </div>
+          <div className="drawer-header-actions">
+            <DonateButton ariaLabel={t('menu.donate') || 'Donate'} />
+            <ThemeCycleButton
+              id="theme-cycle-drawer"
+              isDark={isDark}
+              isUltra={isUltra}
+              onCycle={() => cycleTheme('theme-cycle-drawer')}
+              ariaLabel={t('menu.theme')}
+            />
+            <button
+              className="drawer-close"
+              type="button"
+              aria-label={t('close')}
+              onClick={() => setDrawerOpen(false)}
+            >
+              <CloseOutlined />
+            </button>
+          </div>
+        </div>
+        <Menu
+          theme={currentTheme}
+          mode="inline"
+          selectedKeys={[requestUri]}
+          className="drawer-menu drawer-nav"
+          items={toMenuItems(navItems)}
+          onClick={(info) => { onMenuClick(info); setDrawerOpen(false); }}
+        />
+        <Menu
+          theme={currentTheme}
+          mode="inline"
+          selectedKeys={[requestUri]}
+          className="drawer-menu drawer-utility"
+          items={toMenuItems(utilItems)}
+          onClick={(info) => { onMenuClick(info); setDrawerOpen(false); }}
+        />
+      </Drawer>
+
+      {!drawerOpen && (
+        <button
+          className="drawer-handle"
+          type="button"
+          aria-label={t('menu.dashboard')}
+          onClick={() => setDrawerOpen(true)}
+        >
+          <MenuOutlined />
+        </button>
+      )}
+    </div>
+  );
+}

frontend/src/components/CustomStatistic.css

@@ -0,0 +1,52 @@
+.ant-statistic-content {
+  font-size: 17px !important;
+  line-height: 1.4 !important;
+  font-weight: 600;
+}
+
+.ant-statistic-content-value,
+.ant-statistic-content-prefix,
+.ant-statistic-content-suffix {
+  font-size: 17px !important;
+}
+
+.ant-statistic-content-prefix {
+  margin-inline-end: 8px !important;
+  opacity: 0.7;
+}
+
+.ant-statistic-content-prefix .anticon {
+  font-size: 17px !important;
+}
+
+.ant-statistic-content-suffix {
+  font-size: 12px !important;
+  opacity: 0.55;
+  margin-inline-start: 4px;
+  font-weight: 500;
+}
+
+.ant-statistic-title {
+  font-size: 11px !important;
+  margin-bottom: 6px !important;
+  letter-spacing: 0.6px;
+  text-transform: uppercase;
+  color: rgba(0, 0, 0, 0.55);
+  font-weight: 500;
+}
+
+body.dark .ant-statistic-content {
+  color: rgba(255, 255, 255, 0.92);
+}
+
+body.dark .ant-statistic-title {
+  color: rgba(255, 255, 255, 0.72);
+}
+
+html[data-theme='ultra-dark'] .ant-statistic-content {
+  color: rgba(255, 255, 255, 0.95);
+}
+
+html[data-theme='ultra-dark'] .ant-statistic-title {
+  color: rgba(255, 255, 255, 0.70);
+}

frontend/src/components/CustomStatistic.tsx

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+import { Statistic } from 'antd';
+import './CustomStatistic.css';
+
+interface CustomStatisticProps {
+  title?: string;
+  value?: string | number;
+  prefix?: ReactNode;
+  suffix?: ReactNode;
+}
+
+export default function CustomStatistic({ title = '', value = '', prefix, suffix }: CustomStatisticProps) {
+  return <Statistic title={title} value={value} prefix={prefix} suffix={suffix} />;
+}

frontend/src/components/DateTimePicker.css

@@ -0,0 +1,35 @@
+.jdp-wrap {
+  width: 100%;
+}
+
+.jdp-wrap > * {
+  width: 100%;
+}
+
+.jdp-wrap input {
+  direction: ltr;
+  text-align: left;
+  unicode-bidi: plaintext;
+}
+
+.jdp-dark .jdp-wrap input,
+.jdp-dark input {
+  color: rgba(255, 255, 255, 0.88) !important;
+  background-color: #23252b !important;
+}
+
+.jdp-ultra .jdp-wrap input,
+.jdp-ultra input {
+  color: rgba(255, 255, 255, 0.88) !important;
+  background-color: #101013 !important;
+}
+
+.jdp-dark input::placeholder,
+.jdp-ultra input::placeholder {
+  color: rgba(255, 255, 255, 0.30) !important;
+}
+
+.jdp-disabled {
+  pointer-events: none;
+  opacity: 0.6;
+}

frontend/src/components/DateTimePicker.tsx

@@ -0,0 +1,98 @@
+import { useMemo } from 'react';
+import { DatePicker } from 'antd';
+import dayjs from 'dayjs';
+import type { Dayjs } from 'dayjs';
+import { PersianDateTimePicker } from 'persian-calendar-suite';
+
+import { useDatepicker } from '@/hooks/useDatepicker';
+import { useTheme } from '@/hooks/useTheme';
+import './DateTimePicker.css';
+
+interface DateTimePickerProps {
+  value: Dayjs | null;
+  onChange: (next: Dayjs | null) => void;
+  showTime?: boolean;
+  format?: string;
+  placeholder?: string;
+  disabled?: boolean;
+}
+
+const LIGHT_THEME = {
+  primaryColor: '#1677ff',
+  backgroundColor: '#ffffff',
+  borderColor: '#d9d9d9',
+  hoverColor: 'rgba(22, 119, 255, 0.10)',
+  selectedTextColor: '#ffffff',
+  textColor: 'rgba(0, 0, 0, 0.88)',
+};
+
+const DARK_THEME = {
+  primaryColor: '#1677ff',
+  backgroundColor: '#23252b',
+  borderColor: 'rgba(255, 255, 255, 0.12)',
+  hoverColor: 'rgba(22, 119, 255, 0.18)',
+  selectedTextColor: '#ffffff',
+  textColor: 'rgba(255, 255, 255, 0.88)',
+};
+
+const ULTRA_DARK_THEME = {
+  primaryColor: '#1677ff',
+  backgroundColor: '#101013',
+  borderColor: 'rgba(255, 255, 255, 0.08)',
+  hoverColor: 'rgba(22, 119, 255, 0.16)',
+  selectedTextColor: '#ffffff',
+  textColor: 'rgba(255, 255, 255, 0.88)',
+};
+
+export default function DateTimePicker({
+  value,
+  onChange,
+  showTime = true,
+  format = 'YYYY-MM-DD HH:mm:ss',
+  placeholder = '',
+  disabled = false,
+}: DateTimePickerProps) {
+  const { datepicker } = useDatepicker();
+  const { isDark, isUltra } = useTheme();
+
+  const persianTheme = useMemo(() => {
+    if (isUltra) return ULTRA_DARK_THEME;
+    if (isDark) return DARK_THEME;
+    return LIGHT_THEME;
+  }, [isDark, isUltra]);
+
+  if (datepicker === 'jalalian') {
+    return (
+      <div className={`jdp-wrap${isDark ? ' jdp-dark' : ''}${isUltra ? ' jdp-ultra' : ''}${disabled ? ' jdp-disabled' : ''}`}>
+        <PersianDateTimePicker
+          value={value ? value.valueOf() : null}
+          onChange={(next: number | string | null) => {
+            if (next == null || next === '') {
+              onChange(null);
+              return;
+            }
+            const ms = typeof next === 'number' ? next : Number(next);
+            if (Number.isFinite(ms)) onChange(dayjs(ms));
+          }}
+          showTime={showTime}
+          outputFormat="timestamp"
+          persianNumbers
+          rtlCalendar
+          theme={persianTheme}
+        />
+      </div>
+    );
+  }
+
+  return (
+    <DatePicker
+      value={value}
+      onChange={(next) => onChange(next || null)}
+      showTime={showTime ? { format: 'HH:mm:ss' } : false}
+      format={format}
+      placeholder={placeholder}
+      disabled={disabled}
+      style={{ width: '100%' }}
+    />
+  );
+}

frontend/src/components/FinalMaskForm.tsx

@@ -0,0 +1,738 @@
+import { useMemo } from 'react';
+import { Button, Divider, Form, Input, InputNumber, Select, Switch } from 'antd';
+import { DeleteOutlined, PlusOutlined, ReloadOutlined } from '@ant-design/icons';
+
+import { RandomUtil } from '@/utils';
+import { Protocols } from '@/models/outbound.js';
+
+interface StreamShape {
+  network?: string;
+  kcp?: { mtu?: number };
+  finalmask: {
+    tcp?: MaskRow[];
+    udp?: MaskRow[];
+    enableQuicParams?: boolean;
+    quicParams?: QuicParams;
+  };
+  addTcpMask: (type?: string) => void;
+  delTcpMask: (index: number) => void;
+  addUdpMask: (type?: string) => void;
+  delUdpMask: (index: number) => void;
+}
+
+interface MaskRow {
+  type: string;
+  settings: Record<string, unknown>;
+  _getDefaultSettings: (type: string, settings: Record<string, unknown>) => Record<string, unknown>;
+}
+
+interface ItemRow {
+  type: string;
+  packet: string | unknown[];
+  delay?: number | string;
+  rand?: number | string;
+  randRange?: string;
+}
+
+interface QuicParams {
+  congestion: string;
+  debug?: boolean;
+  brutalUp?: number | string;
+  brutalDown?: number | string;
+  hasUdpHop?: boolean;
+  udpHop?: { ports: string; interval: string | number };
+  maxIdleTimeout?: number;
+  keepAlivePeriod?: number;
+  disablePathMTUDiscovery?: boolean;
+  maxIncomingStreams?: number;
+  initStreamReceiveWindow?: number;
+  maxStreamReceiveWindow?: number;
+  initConnectionReceiveWindow?: number;
+  maxConnectionReceiveWindow?: number;
+}
+
+interface FinalMaskFormProps {
+  stream: StreamShape;
+  protocol: string;
+  onChange: () => void;
+}
+
+function changeMaskType(mask: MaskRow, type: string) {
+  mask.type = type;
+  mask.settings = mask._getDefaultSettings(type, {});
+}
+
+function changeItemType(item: ItemRow, type: string) {
+  item.type = type;
+  if (type === 'base64') item.packet = RandomUtil.randomBase64();
+  else if (type === 'array') {
+    item.rand = 0;
+    item.packet = [];
+  } else item.packet = '';
+}
+
+function newClientServerItem(): ItemRow {
+  return { delay: 0, rand: 0, randRange: '0-255', type: 'array', packet: [] };
+}
+
+function newUdpClientServerItem(): ItemRow {
+  return { rand: 0, randRange: '0-255', type: 'array', packet: [] };
+}
+
+function newNoiseItem(): ItemRow {
+  return { rand: '1-8192', randRange: '0-255', type: 'array', packet: [], delay: '10-20' };
+}
+
+export default function FinalMaskForm({ stream, protocol, onChange }: FinalMaskFormProps) {
+  const isHysteria = protocol === Protocols.Hysteria || protocol === 'hysteria';
+  const network = stream?.network || '';
+
+  const showTcp = useMemo(
+    () => ['raw', 'tcp', 'httpupgrade', 'ws', 'grpc', 'xhttp'].includes(network),
+    [network],
+  );
+  const showUdp = isHysteria || network === 'kcp';
+  const showQuic = isHysteria || network === 'xhttp';
+
+  function notify() {
+    onChange();
+  }
+
+  function changeUdpMaskType(mask: MaskRow, type: string) {
+    changeMaskType(mask, type);
+    if (network === 'kcp' && stream.kcp) {
+      stream.kcp.mtu = type === 'xdns' ? 900 : 1350;
+    }
+    notify();
+  }
+
+  function addUdpMaskWithDefault() {
+    const def = isHysteria ? 'salamander' : 'mkcp-aes128gcm';
+    stream.addUdpMask(def);
+    notify();
+  }
+
+  const tcpMasks = stream.finalmask.tcp || [];
+  const udpMasks = stream.finalmask.udp || [];
+
+  if (!showTcp && !showUdp && !showQuic) return null;
+
+  return (
+    <Form colon={false} labelCol={{ md: { span: 8 } }} wrapperCol={{ md: { span: 14 } }}>
+      {showTcp && (
+        <>
+          <Form.Item label="TCP Masks">
+            <Button
+              type="primary"
+              size="small"
+              icon={<PlusOutlined />}
+              onClick={() => {
+                stream.addTcpMask('fragment');
+                notify();
+              }}
+            />
+          </Form.Item>
+
+          {tcpMasks.map((mask, mIdx) => (
+            <div key={`tcp-${mIdx}`}>
+              <Divider style={{ margin: 0 }}>
+                TCP Mask {mIdx + 1}
+                <DeleteOutlined
+                  style={{ color: 'rgb(255, 77, 79)', cursor: 'pointer', marginLeft: 8 }}
+                  onClick={() => {
+                    stream.delTcpMask(mIdx);
+                    notify();
+                  }}
+                />
+              </Divider>
+
+              <Form.Item label="Type">
+                <Select
+                  value={mask.type}
+                  onChange={(v) => {
+                    changeMaskType(mask, v);
+                    notify();
+                  }}
+                  options={[
+                    { value: 'fragment', label: 'Fragment' },
+                    { value: 'header-custom', label: 'Header Custom' },
+                    { value: 'sudoku', label: 'Sudoku' },
+                  ]}
+                />
+              </Form.Item>
+
+              {mask.type === 'fragment' && (
+                <>
+                  <Form.Item label="Packets">
+                    <Select
+                      value={mask.settings.packets as string}
+                      onChange={(v) => {
+                        (mask.settings as Record<string, unknown>).packets = v;
+                        notify();
+                      }}
+                      options={[
+                        { value: 'tlshello', label: 'tlshello' },
+                        { value: '1-3', label: '1-3' },
+                        { value: '1-5', label: '1-5' },
+                      ]}
+                    />
+                  </Form.Item>
+                  {(['length', 'delay', 'maxSplit'] as const).map((field) => (
+                    <Form.Item key={field} label={field === 'maxSplit' ? 'Max Split' : field.charAt(0).toUpperCase() + field.slice(1)}>
+                      <Input
+                        value={(mask.settings[field] as string) || ''}
+                        onChange={(e) => {
+                          (mask.settings as Record<string, unknown>)[field] = e.target.value;
+                          notify();
+                        }}
+                      />
+                    </Form.Item>
+                  ))}
+                </>
+              )}
+
+              {mask.type === 'sudoku' && (
+                <>
+                  {(['password', 'ascii', 'customTable', 'customTables'] as const).map((field) => (
+                    <Form.Item key={field} label={field === 'customTable' ? 'Custom Table' : field === 'customTables' ? 'Custom Tables' : field.charAt(0).toUpperCase() + field.slice(1)}>
+                      <Input
+                        value={(mask.settings[field] as string) || ''}
+                        onChange={(e) => {
+                          (mask.settings as Record<string, unknown>)[field] = e.target.value;
+                          notify();
+                        }}
+                      />
+                    </Form.Item>
+                  ))}
+                  {(['paddingMin', 'paddingMax'] as const).map((field) => (
+                    <Form.Item key={field} label={field === 'paddingMin' ? 'Padding Min' : 'Padding Max'}>
+                      <InputNumber
+                        value={(mask.settings[field] as number) || 0}
+                        min={0}
+                        onChange={(v) => {
+                          (mask.settings as Record<string, unknown>)[field] = Number(v) || 0;
+                          notify();
+                        }}
+                      />
+                    </Form.Item>
+                  ))}
+                </>
+              )}
+
+              {mask.type === 'header-custom' && (
+                <HeaderCustomGroups mask={mask} kind="tcp" onChange={notify} />
+              )}
+            </div>
+          ))}
+        </>
+      )}
+
+      {showUdp && (
+        <>
+          <Form.Item label="UDP Masks">
+            <Button type="primary" size="small" icon={<PlusOutlined />} onClick={addUdpMaskWithDefault} />
+          </Form.Item>
+
+          {udpMasks.map((mask, mIdx) => (
+            <div key={`udp-${mIdx}`}>
+              <Divider style={{ margin: 0 }}>
+                UDP Mask {mIdx + 1}
+                <DeleteOutlined
+                  style={{ color: 'rgb(255, 77, 79)', cursor: 'pointer', marginLeft: 8 }}
+                  onClick={() => {
+                    stream.delUdpMask(mIdx);
+                    notify();
+                  }}
+                />
+              </Divider>
+
+              <Form.Item label="Type">
+                <Select
+                  value={mask.type}
+                  onChange={(v) => changeUdpMaskType(mask, v)}
+                  options={
+                    isHysteria
+                      ? [{ value: 'salamander', label: 'Salamander (Hysteria2)' }]
+                      : [
+                          { value: 'mkcp-aes128gcm', label: 'mKCP AES-128-GCM' },
+                          { value: 'header-dns', label: 'Header DNS' },
+                          { value: 'header-dtls', label: 'Header DTLS 1.2' },
+                          { value: 'header-srtp', label: 'Header SRTP' },
+                          { value: 'header-utp', label: 'Header uTP' },
+                          { value: 'header-wechat', label: 'Header WeChat Video' },
+                          { value: 'header-wireguard', label: 'Header WireGuard' },
+                          { value: 'mkcp-original', label: 'mKCP Original' },
+                          { value: 'xdns', label: 'xDNS' },
+                          { value: 'xicmp', label: 'xICMP' },
+                          { value: 'header-custom', label: 'Header Custom' },
+                          { value: 'noise', label: 'Noise' },
+                        ]
+                  }
+                />
+              </Form.Item>
+
+              {['mkcp-aes128gcm', 'salamander'].includes(mask.type) && (
+                <Form.Item label="Password">
+                  <Input
+                    value={(mask.settings.password as string) || ''}
+                    placeholder="Obfuscation password"
+                    onChange={(e) => {
+                      (mask.settings as Record<string, unknown>).password = e.target.value;
+                      notify();
+                    }}
+                  />
+                </Form.Item>
+              )}
+
+              {mask.type === 'header-dns' && (
+                <Form.Item label="Domain">
+                  <Input
+                    value={(mask.settings.domain as string) || ''}
+                    placeholder="e.g., www.example.com"
+                    onChange={(e) => {
+                      (mask.settings as Record<string, unknown>).domain = e.target.value;
+                      notify();
+                    }}
+                  />
+                </Form.Item>
+              )}
+
+              {mask.type === 'xdns' && (
+                <Form.Item label="Domains">
+                  <Select
+                    mode="tags"
+                    value={(mask.settings.domains as string[]) || []}
+                    style={{ width: '100%' }}
+                    tokenSeparators={[',']}
+                    placeholder="e.g., www.example.com"
+                    onChange={(v) => {
+                      (mask.settings as Record<string, unknown>).domains = v;
+                      notify();
+                    }}
+                  />
+                </Form.Item>
+              )}
+
+              {mask.type === 'noise' && (
+                <NoiseItems mask={mask} onChange={notify} />
+              )}
+
+              {mask.type === 'header-custom' && (
+                <UdpHeaderCustom mask={mask} onChange={notify} />
+              )}
+
+              {mask.type === 'xicmp' && (
+                <>
+                  <Form.Item label="IP">
+                    <Input
+                      value={(mask.settings.ip as string) || ''}
+                      placeholder="0.0.0.0"
+                      onChange={(e) => {
+                        (mask.settings as Record<string, unknown>).ip = e.target.value;
+                        notify();
+                      }}
+                    />
+                  </Form.Item>
+                  <Form.Item label="ID">
+                    <InputNumber
+                      value={(mask.settings.id as number) || 0}
+                      min={0}
+                      onChange={(v) => {
+                        (mask.settings as Record<string, unknown>).id = Number(v) || 0;
+                        notify();
+                      }}
+                    />
+                  </Form.Item>
+                </>
+              )}
+            </div>
+          ))}
+        </>
+      )}
+
+      {showQuic && (
+        <>
+          <Form.Item label="QUIC Params">
+            <Switch
+              checked={!!stream.finalmask.enableQuicParams}
+              onChange={(v) => {
+                stream.finalmask.enableQuicParams = v;
+                notify();
+              }}
+            />
+          </Form.Item>
+          {stream.finalmask.enableQuicParams && stream.finalmask.quicParams && (
+            <QuicParamsForm params={stream.finalmask.quicParams} onChange={notify} />
+          )}
+        </>
+      )}
+    </Form>
+  );
+}
+
+function HeaderCustomGroups({
+  mask,
+  kind: _kind,
+  onChange,
+}: {
+  mask: MaskRow;
+  kind: 'tcp';
+  onChange: () => void;
+}) {
+  const settings = mask.settings as { clients?: ItemRow[][]; servers?: ItemRow[][] };
+  if (!settings.clients) settings.clients = [];
+  if (!settings.servers) settings.servers = [];
+
+  return (
+    <>
+      {(['clients', 'servers'] as const).map((groupKey) => (
+        <div key={groupKey}>
+          <Form.Item label={groupKey === 'clients' ? 'Clients' : 'Servers'}>
+            <Button
+              type="primary"
+              size="small"
+              icon={<PlusOutlined />}
+              onClick={() => {
+                (settings[groupKey] as ItemRow[][]).push([newClientServerItem()]);
+                onChange();
+              }}
+            />
+          </Form.Item>
+          {(settings[groupKey] as ItemRow[][]).map((group, gi) => (
+            <div key={`${groupKey}-${gi}`}>
+              <Divider style={{ margin: 0 }}>
+                {groupKey === 'clients' ? 'Clients' : 'Servers'} Group {gi + 1}
+                <DeleteOutlined
+                  style={{ color: 'rgb(255, 77, 79)', cursor: 'pointer', marginLeft: 8 }}
+                  onClick={() => {
+                    (settings[groupKey] as ItemRow[][]).splice(gi, 1);
+                    onChange();
+                  }}
+                />
+              </Divider>
+              {group.map((item, _ii) => (
+                <ItemEditor key={_ii} item={item} onChange={onChange} delayAsNumber />
+              ))}
+            </div>
+          ))}
+        </div>
+      ))}
+    </>
+  );
+}
+
+function UdpHeaderCustom({ mask, onChange }: { mask: MaskRow; onChange: () => void }) {
+  const settings = mask.settings as { client?: ItemRow[]; server?: ItemRow[] };
+  if (!settings.client) settings.client = [];
+  if (!settings.server) settings.server = [];
+  return (
+    <>
+      {(['client', 'server'] as const).map((groupKey) => (
+        <div key={groupKey}>
+          <Form.Item label={groupKey === 'client' ? 'Client' : 'Server'}>
+            <Button
+              type="primary"
+              size="small"
+              icon={<PlusOutlined />}
+              onClick={() => {
+                (settings[groupKey] as ItemRow[]).push(newUdpClientServerItem());
+                onChange();
+              }}
+            />
+          </Form.Item>
+          {(settings[groupKey] as ItemRow[]).map((item, ci) => (
+            <div key={ci}>
+              <Divider style={{ margin: 0 }}>
+                {groupKey === 'client' ? 'Client' : 'Server'} {ci + 1}
+                <DeleteOutlined
+                  style={{ color: 'rgb(255, 77, 79)', cursor: 'pointer', marginLeft: 8 }}
+                  onClick={() => {
+                    (settings[groupKey] as ItemRow[]).splice(ci, 1);
+                    onChange();
+                  }}
+                />
+              </Divider>
+              <ItemEditor item={item} onChange={onChange} />
+            </div>
+          ))}
+        </div>
+      ))}
+    </>
+  );
+}
+
+function NoiseItems({ mask, onChange }: { mask: MaskRow; onChange: () => void }) {
+  const settings = mask.settings as { reset?: number; noise?: ItemRow[] };
+  if (!settings.noise) settings.noise = [];
+
+  return (
+    <>
+      <Form.Item label="Reset">
+        <InputNumber
+          value={settings.reset || 0}
+          min={0}
+          onChange={(v) => {
+            settings.reset = Number(v) || 0;
+            onChange();
+          }}
+        />
+      </Form.Item>
+      <Form.Item label="Noise">
+        <Button
+          type="primary"
+          size="small"
+          icon={<PlusOutlined />}
+          onClick={() => {
+            (settings.noise as ItemRow[]).push(newNoiseItem());
+            onChange();
+          }}
+        />
+      </Form.Item>
+      {(settings.noise as ItemRow[]).map((n, ni) => (
+        <div key={ni}>
+          <Divider style={{ margin: 0 }}>
+            Noise {ni + 1}
+            <DeleteOutlined
+              style={{ color: 'rgb(255, 77, 79)', cursor: 'pointer', marginLeft: 8 }}
+              onClick={() => {
+                (settings.noise as ItemRow[]).splice(ni, 1);
+                onChange();
+              }}
+            />
+          </Divider>
+          <ItemEditor item={n} onChange={onChange} delayAsString />
+        </div>
+      ))}
+    </>
+  );
+}
+
+function ItemEditor({
+  item,
+  onChange,
+  delayAsNumber,
+  delayAsString,
+}: {
+  item: ItemRow;
+  onChange: () => void;
+  delayAsNumber?: boolean;
+  delayAsString?: boolean;
+}) {
+  return (
+    <>
+      <Form.Item label="Type">
+        <Select
+          value={item.type}
+          onChange={(v) => {
+            changeItemType(item, v);
+            onChange();
+          }}
+          options={[
+            { value: 'array', label: 'Array' },
+            { value: 'str', label: 'String' },
+            { value: 'hex', label: 'Hex' },
+            { value: 'base64', label: 'Base64' },
+          ]}
+        />
+      </Form.Item>
+      {delayAsNumber && (
+        <Form.Item label="Delay (ms)">
+          <InputNumber
+            value={typeof item.delay === 'number' ? item.delay : 0}
+            min={0}
+            onChange={(v) => {
+              item.delay = Number(v) || 0;
+              onChange();
+            }}
+          />
+        </Form.Item>
+      )}
+      {item.type === 'array' ? (
+        <>
+          <Form.Item label="Rand">
+            {delayAsString ? (
+              <Input
+                value={String(item.rand ?? '')}
+                onChange={(e) => {
+                  item.rand = e.target.value;
+                  onChange();
+                }}
+                placeholder="0 or 1-8192"
+              />
+            ) : (
+              <InputNumber
+                value={typeof item.rand === 'number' ? item.rand : 0}
+                min={0}
+                onChange={(v) => {
+                  item.rand = Number(v) || 0;
+                  onChange();
+                }}
+              />
+            )}
+          </Form.Item>
+          <Form.Item label="Rand Range">
+            <Input
+              value={item.randRange || ''}
+              placeholder="0-255"
+              onChange={(e) => {
+                item.randRange = e.target.value;
+                onChange();
+              }}
+            />
+          </Form.Item>
+        </>
+      ) : (
+        <Form.Item label="Packet">
+          {item.type === 'base64' ? (
+            <Input.Group compact>
+              <Input
+                value={String(item.packet ?? '')}
+                placeholder="binary data"
+                style={{ width: 'calc(100% - 32px)' }}
+                onChange={(e) => {
+                  item.packet = e.target.value;
+                  onChange();
+                }}
+              />
+              <Button
+                icon={<ReloadOutlined />}
+                onClick={() => {
+                  item.packet = RandomUtil.randomBase64();
+                  onChange();
+                }}
+              />
+            </Input.Group>
+          ) : (
+            <Input
+              value={String(item.packet ?? '')}
+              placeholder="binary data"
+              onChange={(e) => {
+                item.packet = e.target.value;
+                onChange();
+              }}
+            />
+          )}
+        </Form.Item>
+      )}
+      {delayAsString && (
+        <Form.Item label="Delay">
+          <Input
+            value={typeof item.delay === 'string' ? item.delay : ''}
+            placeholder="10-20"
+            onChange={(e) => {
+              item.delay = e.target.value;
+              onChange();
+            }}
+          />
+        </Form.Item>
+      )}
+    </>
+  );
+}
+
+function QuicParamsForm({ params, onChange }: { params: QuicParams; onChange: () => void }) {
+  function update<K extends keyof QuicParams>(key: K, value: QuicParams[K]) {
+    params[key] = value;
+    onChange();
+  }
+  return (
+    <>
+      <Form.Item label="Congestion">
+        <Select
+          value={params.congestion}
+          onChange={(v) => update('congestion', v)}
+          options={[
+            { value: 'reno', label: 'Reno' },
+            { value: 'bbr', label: 'BBR' },
+            { value: 'brutal', label: 'Brutal' },
+            { value: 'force-brutal', label: 'Force Brutal' },
+          ]}
+        />
+      </Form.Item>
+      <Form.Item label="Debug">
+        <Switch checked={!!params.debug} onChange={(v) => update('debug', v)} />
+      </Form.Item>
+      {['brutal', 'force-brutal'].includes(params.congestion) && (
+        <>
+          <Form.Item label="Brutal Up">
+            <Input
+              value={String(params.brutalUp ?? '')}
+              placeholder="65537"
+              onChange={(e) => update('brutalUp', e.target.value)}
+            />
+          </Form.Item>
+          <Form.Item label="Brutal Down">
+            <Input
+              value={String(params.brutalDown ?? '')}
+              placeholder="65537"
+              onChange={(e) => update('brutalDown', e.target.value)}
+            />
+          </Form.Item>
+        </>
+      )}
+      <Form.Item label="UDP Hop">
+        <Switch checked={!!params.hasUdpHop} onChange={(v) => update('hasUdpHop', v)} />
+      </Form.Item>
+      {params.hasUdpHop && params.udpHop && (
+        <>
+          <Form.Item label="Hop Ports">
+            <Input
+              value={params.udpHop.ports || ''}
+              placeholder="e.g. 20000-50000"
+              onChange={(e) => {
+                params.udpHop!.ports = e.target.value;
+                onChange();
+              }}
+            />
+          </Form.Item>
+          <Form.Item label="Hop Interval (s)">
+            <InputNumber
+              value={Number(params.udpHop.interval) || 5}
+              min={5}
+              onChange={(v) => {
+                params.udpHop!.interval = Number(v) || 5;
+                onChange();
+              }}
+            />
+          </Form.Item>
+        </>
+      )}
+      {(
+        [
+          ['maxIdleTimeout', 'Max Idle Timeout (s)', 4, 120],
+          ['keepAlivePeriod', 'Keep Alive Period (s)', 2, 60],
+        ] as const
+      ).map(([key, label, min, max]) => (
+        <Form.Item key={key} label={label}>
+          <InputNumber
+            value={params[key] as number}
+            min={min}
+            max={max}
+            onChange={(v) => update(key, Number(v) || min)}
+          />
+        </Form.Item>
+      ))}
+      <Form.Item label="Disable Path MTU Dis">
+        <Switch checked={!!params.disablePathMTUDiscovery} onChange={(v) => update('disablePathMTUDiscovery', v)} />
+      </Form.Item>
+      {(
+        [
+          ['maxIncomingStreams', 'Max Incoming Streams', 8, '1024 = default'],
+          ['initStreamReceiveWindow', 'Init Stream Window', 16384, '8388608 = default'],
+          ['maxStreamReceiveWindow', 'Max Stream Window', 16384, '8388608 = default'],
+          ['initConnectionReceiveWindow', 'Init Conn Window', 16384, '20971520 = default'],
+          ['maxConnectionReceiveWindow', 'Max Conn Window', 16384, '20971520 = default'],
+        ] as const
+      ).map(([key, label, min, placeholder]) => (
+        <Form.Item key={key} label={label}>
+          <InputNumber
+            value={params[key] as number}
+            min={min}
+            placeholder={placeholder}
+            onChange={(v) => update(key, Number(v) || 0)}
+          />
+        </Form.Item>
+      ))}
+    </>
+  );
+}

frontend/src/components/InfinityIcon.tsx

@@ -0,0 +1,19 @@
+interface InfinityIconProps {
+  width?: number | string;
+  height?: number | string;
+}
+
+export default function InfinityIcon({ width = 14, height = 10 }: InfinityIconProps) {
+  return (
+    <svg
+      width={width}
+      height={height}
+      viewBox="0 0 640 512"
+      fill="currentColor"
+      aria-hidden="true"
+      style={{ verticalAlign: '-1px', display: 'inline-block' }}
+    >
+      <path d="M484.4 96C407 96 349.2 164.1 320 208.5C290.8 164.1 233 96 155.6 96C69.75 96 0 167.8 0 256s69.75 160 155.6 160C233.1 416 290.8 347.9 320 303.5C349.2 347.9 407 416 484.4 416C570.3 416 640 344.2 640 256S570.3 96 484.4 96zM155.6 368C96.25 368 48 317.8 48 256s48.25-112 107.6-112c67.75 0 120.5 82.25 137.1 112C276 285.8 223.4 368 155.6 368zM484.4 368c-67.75 0-120.5-82.25-137.1-112C364 226.2 416.6 144 484.4 144C543.8 144 592 194.2 592 256S543.8 368 484.4 368z" />
+    </svg>
+  );
+}

frontend/src/components/InputAddon.css

@@ -0,0 +1,40 @@
+.input-addon {
+  display: inline-flex;
+  align-items: center;
+  padding: 0 11px;
+  height: 32px;
+  font-size: 14px;
+  line-height: 30px;
+  background-color: rgba(0, 0, 0, 0.02);
+  border: 1px solid #d9d9d9;
+  border-radius: 6px;
+  position: relative;
+  z-index: 1;
+  color: rgba(0, 0, 0, 0.88);
+  white-space: nowrap;
+}
+
+body.dark .input-addon,
+html[data-theme='ultra-dark'] .input-addon {
+  background-color: rgba(255, 255, 255, 0.04);
+  border-color: #424242;
+  color: rgba(255, 255, 255, 0.85);
+}
+
+.ant-space-compact > .input-addon:not(:first-child) {
+  margin-inline-start: -1px;
+}
+
+.ant-space-compact > .input-addon:first-child {
+  border-start-end-radius: 0;
+  border-end-end-radius: 0;
+}
+
+.ant-space-compact > .input-addon:last-child {
+  border-start-start-radius: 0;
+  border-end-start-radius: 0;
+}
+
+.ant-space-compact > .input-addon:not(:first-child):not(:last-child) {
+  border-radius: 0;
+}

frontend/src/components/InputAddon.tsx

@@ -0,0 +1,21 @@
+import type { CSSProperties, ReactNode } from 'react';
+import './InputAddon.css';
+
+interface InputAddonProps {
+  children: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+  onClick?: () => void;
+}
+
+export default function InputAddon({ children, className = '', style, onClick }: InputAddonProps) {
+  return (
+    <span
+      className={`input-addon ${className}`.trim()}
+      style={style}
+      onClick={onClick}
+    >
+      {children}
+    </span>
+  );
+}

frontend/src/components/JsonEditor.css

@@ -0,0 +1,26 @@
+.json-editor-host {
+  border: 1px solid var(--ant-color-border, #d9d9d9);
+  border-radius: 6px;
+  overflow: hidden;
+  background: var(--ant-color-bg-container, #fff);
+}
+
+.json-editor-host .cm-editor,
+.json-editor-host .cm-editor.cm-focused {
+  outline: none;
+}
+
+.json-editor-host:focus-within {
+  border-color: var(--ant-color-primary, #1677ff);
+  box-shadow: 0 0 0 2px rgba(22, 119, 255, 0.1);
+}
+
+body.dark .json-editor-host {
+  border-color: #3a3a3c;
+  background: #1e1e1e;
+}
+
+html[data-theme="ultra-dark"] .json-editor-host {
+  border-color: #1f1f1f;
+  background: #0a0a0a;
+}

frontend/src/components/JsonEditor.tsx

@@ -0,0 +1,179 @@
+import { forwardRef, useEffect, useImperativeHandle, useRef } from 'react';
+import { EditorView, basicSetup } from 'codemirror';
+import { EditorState, Compartment } from '@codemirror/state';
+import { json, jsonParseLinter } from '@codemirror/lang-json';
+import { lintGutter, linter } from '@codemirror/lint';
+import { oneDarkHighlightStyle } from '@codemirror/theme-one-dark';
+import { syntaxHighlighting } from '@codemirror/language';
+import { keymap } from '@codemirror/view';
+import { indentWithTab } from '@codemirror/commands';
+
+import { useTheme } from '@/hooks/useTheme';
+import './JsonEditor.css';
+
+export interface JsonEditorProps {
+  value: string;
+  onChange?: (next: string) => void;
+  minHeight?: string;
+  maxHeight?: string;
+  readOnly?: boolean;
+}
+
+export interface JsonEditorHandle {
+  focus: () => void;
+}
+
+interface DarkPalette {
+  bg: string;
+  panelBg: string;
+  activeBg: string;
+  border: string;
+  selection: string;
+}
+
+function buildDarkTheme({ bg, panelBg, activeBg, border, selection }: DarkPalette) {
+  return EditorView.theme(
+    {
+      '&': { color: '#dcdcdc', backgroundColor: bg },
+      '.cm-content': { caretColor: '#dcdcdc' },
+      '.cm-cursor, .cm-dropCursor': { borderLeftColor: '#dcdcdc' },
+      '.cm-gutters': {
+        backgroundColor: bg,
+        borderRight: `1px solid ${border}`,
+        color: '#6a6a6a',
+      },
+      '.cm-activeLine': { backgroundColor: activeBg },
+      '.cm-activeLineGutter': { backgroundColor: activeBg, color: '#dcdcdc' },
+      '&.cm-focused .cm-selectionBackground, .cm-selectionBackground, .cm-content ::selection':
+        { backgroundColor: selection },
+      '.cm-panels': { backgroundColor: panelBg, color: '#dcdcdc' },
+      '.cm-panels.cm-panels-top': { borderBottom: `1px solid ${border}` },
+      '.cm-panels.cm-panels-bottom': { borderTop: `1px solid ${border}` },
+      '.cm-tooltip': {
+        backgroundColor: panelBg,
+        border: `1px solid ${border}`,
+        color: '#dcdcdc',
+      },
+    },
+    { dark: true },
+  );
+}
+
+const darkTheme = buildDarkTheme({
+  bg: '#1e1e1e',
+  panelBg: '#2d2d30',
+  activeBg: '#252526',
+  border: '#3a3a3c',
+  selection: '#3a3a3c',
+});
+
+const ultraDarkTheme = buildDarkTheme({
+  bg: '#0a0a0a',
+  panelBg: '#141414',
+  activeBg: '#141414',
+  border: '#1f1f1f',
+  selection: '#2a2a2a',
+});
+
+function themeExtension(isDark: boolean, isUltra: boolean) {
+  if (!isDark) return [];
+  const chrome = isUltra ? ultraDarkTheme : darkTheme;
+  return [chrome, syntaxHighlighting(oneDarkHighlightStyle)];
+}
+
+const JsonEditor = forwardRef<JsonEditorHandle, JsonEditorProps>(function JsonEditor(
+  { value, onChange, minHeight = '320px', maxHeight = '600px', readOnly = false },
+  ref,
+) {
+  const hostRef = useRef<HTMLDivElement | null>(null);
+  const viewRef = useRef<EditorView | null>(null);
+  const themeCompartmentRef = useRef<Compartment>(new Compartment());
+  const readonlyCompartmentRef = useRef<Compartment>(new Compartment());
+  const onChangeRef = useRef(onChange);
+  const valueRef = useRef(value);
+  const { isDark, isUltra } = useTheme();
+
+  useEffect(() => {
+    onChangeRef.current = onChange;
+  }, [onChange]);
+
+  useImperativeHandle(ref, () => ({
+    focus: () => viewRef.current?.focus(),
+  }));
+
+  useEffect(() => {
+    if (!hostRef.current) return;
+
+    const updateListener = EditorView.updateListener.of((u) => {
+      if (!u.docChanged) return;
+      const next = u.state.doc.toString();
+      if (next === valueRef.current) return;
+      valueRef.current = next;
+      onChangeRef.current?.(next);
+    });
+
+    const view = new EditorView({
+      parent: hostRef.current,
+      state: EditorState.create({
+        doc: value,
+        extensions: [
+          basicSetup,
+          keymap.of([indentWithTab]),
+          json(),
+          linter(jsonParseLinter()),
+          lintGutter(),
+          EditorView.lineWrapping,
+          updateListener,
+          themeCompartmentRef.current.of(themeExtension(isDark, isUltra)),
+          readonlyCompartmentRef.current.of(EditorState.readOnly.of(readOnly)),
+          EditorView.theme({
+            '&': { height: '100%' },
+            '.cm-scroller': {
+              fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace',
+              fontSize: '12px',
+              minHeight,
+              maxHeight,
+            },
+          }),
+        ],
+      }),
+    });
+
+    viewRef.current = view;
+
+    return () => {
+      view.destroy();
+      viewRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    const view = viewRef.current;
+    if (!view) return;
+    const current = view.state.doc.toString();
+    if (value === current) return;
+    valueRef.current = value;
+    view.dispatch({ changes: { from: 0, to: current.length, insert: value } });
+  }, [value]);
+
+  useEffect(() => {
+    const view = viewRef.current;
+    if (!view) return;
+    view.dispatch({
+      effects: themeCompartmentRef.current.reconfigure(themeExtension(isDark, isUltra)),
+    });
+  }, [isDark, isUltra]);
+
+  useEffect(() => {
+    const view = viewRef.current;
+    if (!view) return;
+    view.dispatch({
+      effects: readonlyCompartmentRef.current.reconfigure(EditorState.readOnly.of(readOnly)),
+    });
+  }, [readOnly]);
+
+  return <div ref={hostRef} className="json-editor-host" />;
+});
+
+export default JsonEditor;

frontend/src/components/LazyMount.tsx

@@ -0,0 +1,20 @@
+import { Suspense, useEffect, useState, type ReactNode } from 'react';
+
+interface LazyMountProps {
+  when: boolean;
+  fallback?: ReactNode;
+  children: ReactNode;
+}
+
+// Mounts children only after `when` first becomes true and keeps them mounted
+// thereafter, so React.lazy modals get loaded on demand but their close
+// animations still play out. Pair with `lazy(() => import(...))` modal imports
+// on heavy list pages to keep the initial bundle small.
+export default function LazyMount({ when, fallback = null, children }: LazyMountProps) {
+  const [mounted, setMounted] = useState(when);
+  useEffect(() => {
+    if (when && !mounted) setMounted(true);
+  }, [when, mounted]);
+  if (!mounted) return null;
+  return <Suspense fallback={fallback}>{children}</Suspense>;
+}

frontend/src/components/PromptModal.tsx

@@ -0,0 +1,82 @@
+import { useEffect, useRef, useState } from 'react';
+import { Input, Modal } from 'antd';
+import type { InputRef } from 'antd';
+
+interface PromptModalProps {
+  open: boolean;
+  onClose: () => void;
+  title: string;
+  okText?: string;
+  type?: 'input' | 'textarea';
+  initialValue?: string;
+  loading?: boolean;
+  onConfirm: (value: string) => void;
+}
+
+export default function PromptModal({
+  open,
+  onClose,
+  title,
+  okText = 'OK',
+  type = 'input',
+  initialValue = '',
+  loading = false,
+  onConfirm,
+}: PromptModalProps) {
+  const [value, setValue] = useState('');
+  const textareaRef = useRef<HTMLTextAreaElement | null>(null);
+  const inputRef = useRef<InputRef | null>(null);
+
+  useEffect(() => {
+    if (open) {
+      setValue(initialValue);
+      setTimeout(() => {
+        if (type === 'textarea') textareaRef.current?.focus();
+        else inputRef.current?.focus();
+      }, 50);
+    }
+  }, [open, initialValue, type]);
+
+  function onKeydown(e: React.KeyboardEvent<HTMLTextAreaElement | HTMLInputElement>) {
+    if (type !== 'textarea' && e.key === 'Enter') {
+      e.preventDefault();
+      onConfirm(value);
+      return;
+    }
+    if (type === 'textarea' && e.ctrlKey && e.key.toLowerCase() === 's') {
+      e.preventDefault();
+      onConfirm(value);
+    }
+  }
+
+  return (
+    <Modal
+      open={open}
+      title={title}
+      okText={okText}
+      cancelText="Cancel"
+      mask={{ closable: false }}
+      confirmLoading={loading}
+      onOk={() => onConfirm(value)}
+      onCancel={onClose}
+      destroyOnHidden
+    >
+      {type === 'textarea' ? (
+        <Input.TextArea
+          ref={(el) => { textareaRef.current = (el as unknown as { resizableTextArea?: { textArea: HTMLTextAreaElement } })?.resizableTextArea?.textArea ?? null; }}
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+          autoSize={{ minRows: 10, maxRows: 20 }}
+          onKeyDown={onKeydown}
+        />
+      ) : (
+        <Input
+          ref={inputRef}
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+          onKeyDown={onKeydown}
+        />
+      )}
+    </Modal>
+  );
+}

frontend/src/components/SettingListItem.css

@@ -0,0 +1,43 @@
+.setting-list-item {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  border-bottom: 1px solid rgba(5, 5, 5, 0.06);
+}
+
+.setting-list-item:last-child {
+  border-bottom: 0;
+}
+
+body.dark .setting-list-item,
+html[data-theme='ultra-dark'] .setting-list-item {
+  border-bottom-color: rgba(255, 255, 255, 0.08);
+}
+
+.setting-list-meta {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.setting-list-title {
+  font-size: 14px;
+  color: rgba(0, 0, 0, 0.88);
+  font-weight: 500;
+}
+
+.setting-list-description {
+  font-size: 14px;
+  color: rgba(0, 0, 0, 0.45);
+  line-height: 1.5715;
+}
+
+body.dark .setting-list-title,
+html[data-theme='ultra-dark'] .setting-list-title {
+  color: rgba(255, 255, 255, 0.85);
+}
+
+body.dark .setting-list-description,
+html[data-theme='ultra-dark'] .setting-list-description {
+  color: rgba(255, 255, 255, 0.45);
+}

frontend/src/components/SettingListItem.tsx

@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react';
+import { Col, Row } from 'antd';
+import './SettingListItem.css';
+
+interface SettingListItemProps {
+  paddings?: 'small' | 'default';
+  title?: ReactNode;
+  description?: ReactNode;
+  children?: ReactNode;
+  control?: ReactNode;
+}
+
+export default function SettingListItem({
+  paddings = 'default',
+  title,
+  description,
+  children,
+  control,
+}: SettingListItemProps) {
+  const padding = paddings === 'small' ? '10px 20px' : '20px';
+  return (
+    <div className="setting-list-item" style={{ padding }}>
+      <Row gutter={[8, 16]} style={{ width: '100%' }}>
+        <Col xs={24} lg={12}>
+          <div className="setting-list-meta">
+            {title && <div className="setting-list-title">{title}</div>}
+            {description && <div className="setting-list-description">{description}</div>}
+          </div>
+        </Col>
+        <Col xs={24} lg={12}>
+          {control ?? children}
+        </Col>
+      </Row>
+    </div>
+  );
+}

frontend/src/components/Sparkline.css

@@ -0,0 +1,44 @@
+.sparkline-svg {
+  display: block;
+  width: 100%;
+}
+
+.sparkline-svg .cpu-grid-y-text,
+.sparkline-svg .cpu-grid-x-text {
+  fill: rgba(0, 0, 0, 0.55);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  letter-spacing: 0.2px;
+}
+
+.sparkline-svg .cpu-grid-text {
+  fill: rgba(0, 0, 0, 0.88);
+}
+
+.sparkline-svg .cpu-grid-line {
+  stroke: rgba(0, 0, 0, 0.08);
+}
+
+.sparkline-svg .cpu-tooltip-text {
+  pointer-events: none;
+}
+
+.sparkline-svg .cpu-tooltip-pill {
+  filter: drop-shadow(0 2px 6px rgba(0, 0, 0, 0.18));
+}
+
+body.dark .sparkline-svg .cpu-grid-y-text,
+body.dark .sparkline-svg .cpu-grid-x-text {
+  fill: rgba(255, 255, 255, 0.7);
+}
+
+body.dark .sparkline-svg .cpu-grid-text {
+  fill: rgba(255, 255, 255, 0.95);
+}
+
+body.dark .sparkline-svg .cpu-grid-line {
+  stroke: rgba(255, 255, 255, 0.10);
+}
+
+body.dark .sparkline-svg .cpu-tooltip-pill {
+  filter: drop-shadow(0 2px 8px rgba(0, 0, 0, 0.6));
+}

frontend/src/components/Sparkline.tsx

@@ -0,0 +1,368 @@
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
+import type { MouseEvent } from 'react';
+import './Sparkline.css';
+
+interface SparklineProps {
+  data: number[];
+  labels?: (string | number)[];
+  vbWidth?: number;
+  height?: number;
+  stroke?: string;
+  strokeWidth?: number;
+  maxPoints?: number;
+  showGrid?: boolean;
+  gridColor?: string;
+  fillOpacity?: number;
+  showMarker?: boolean;
+  markerRadius?: number;
+  showAxes?: boolean;
+  yTickStep?: number;
+  tickCountX?: number;
+  paddingLeft?: number;
+  paddingRight?: number;
+  paddingTop?: number;
+  paddingBottom?: number;
+  showTooltip?: boolean;
+  valueMin?: number;
+  valueMax?: number | null;
+  yFormatter?: (v: number) => string;
+  tooltipFormatter?: ((v: number) => string) | null;
+}
+
+export default function Sparkline({
+  data,
+  labels = [],
+  vbWidth = 320,
+  height = 80,
+  stroke = '#008771',
+  strokeWidth = 2,
+  maxPoints = 120,
+  showGrid = true,
+  gridColor = 'rgba(0,0,0,0.08)',
+  fillOpacity = 0.22,
+  showMarker = true,
+  markerRadius = 3,
+  showAxes = false,
+  yTickStep = 25,
+  tickCountX = 4,
+  paddingLeft = 56,
+  paddingRight = 6,
+  paddingTop = 6,
+  paddingBottom = 20,
+  showTooltip = false,
+  valueMin = 0,
+  valueMax = 100,
+  yFormatter = (v: number) => `${Math.round(v)}%`,
+  tooltipFormatter = null,
+}: SparklineProps) {
+  const svgRef = useRef<SVGSVGElement | null>(null);
+  const [measuredWidth, setMeasuredWidth] = useState(0);
+  const [hoverIdx, setHoverIdx] = useState(-1);
+
+  const reactId = useId();
+  const safeId = reactId.replace(/[^a-zA-Z0-9]/g, '');
+  const gradId = `spkGrad-${safeId}`;
+  const shadowId = `spkShadow-${safeId}`;
+  const glowId = `spkGlow-${safeId}`;
+
+  useEffect(() => {
+    const el = svgRef.current;
+    if (!el) return;
+    const measure = () => {
+      const w = el.getBoundingClientRect?.().width || 0;
+      if (w > 0) setMeasuredWidth(Math.round(w));
+    };
+    measure();
+    if (typeof ResizeObserver !== 'undefined') {
+      const ro = new ResizeObserver(measure);
+      ro.observe(el);
+      return () => ro.disconnect();
+    }
+    window.addEventListener('resize', measure);
+    return () => window.removeEventListener('resize', measure);
+  }, []);
+
+  const effectiveVbWidth = measuredWidth > 0 ? measuredWidth : vbWidth;
+  const drawWidth = Math.max(1, effectiveVbWidth - paddingLeft - paddingRight);
+  const drawHeight = Math.max(1, height - paddingTop - paddingBottom);
+  const nPoints = Math.min(data.length, maxPoints);
+
+  const dataSlice = useMemo(
+    () => (nPoints === 0 ? [] : data.slice(data.length - nPoints)),
+    [data, nPoints],
+  );
+
+  const labelsSlice = useMemo(() => {
+    if (!labels?.length || nPoints === 0) return [] as (string | number)[];
+    const start = Math.max(0, labels.length - nPoints);
+    return labels.slice(start);
+  }, [labels, nPoints]);
+
+  const yDomain = useMemo(() => {
+    const min = valueMin;
+    if (valueMax != null) return { min, max: valueMax };
+    let max = min;
+    for (const v of dataSlice) {
+      const n = Number(v);
+      if (Number.isFinite(n) && n > max) max = n;
+    }
+    if (max <= min) max = min + 1;
+    return { min, max: max * 1.1 };
+  }, [dataSlice, valueMin, valueMax]);
+
+  const project = useCallback(
+    (v: number) => {
+      const { min, max } = yDomain;
+      const span = max - min;
+      if (span <= 0) return paddingTop + drawHeight;
+      const clipped = Math.max(min, Math.min(max, Number(v) || 0));
+      const ratio = (clipped - min) / span;
+      return Math.round(paddingTop + (drawHeight - ratio * drawHeight));
+    },
+    [yDomain, paddingTop, drawHeight],
+  );
+
+  const pointsArr = useMemo<[number, number][]>(() => {
+    if (nPoints === 0) return [];
+    const w = drawWidth;
+    const dx = nPoints > 1 ? w / (nPoints - 1) : 0;
+    return dataSlice.map((v, i) => {
+      const x = Math.round(paddingLeft + i * dx);
+      return [x, project(v)];
+    });
+  }, [dataSlice, nPoints, drawWidth, paddingLeft, project]);
+
+  const pointsStr = useMemo(() => pointsArr.map((p) => `${p[0]},${p[1]}`).join(' '), [pointsArr]);
+
+  const areaPath = useMemo(() => {
+    if (pointsArr.length === 0) return '';
+    const first = pointsArr[0];
+    const last = pointsArr[pointsArr.length - 1];
+    const baseY = paddingTop + drawHeight;
+    const line = pointsStr.replace(/ /g, ' L ');
+    return `M ${first[0]},${baseY} L ${line} L ${last[0]},${baseY} Z`;
+  }, [pointsArr, pointsStr, paddingTop, drawHeight]);
+
+  const gridLines = useMemo(() => {
+    if (!showGrid) return [];
+    const h = drawHeight;
+    const w = drawWidth;
+    return [0, 0.25, 0.5, 0.75, 1].map((r) => {
+      const y = Math.round(paddingTop + h * r);
+      return { x1: paddingLeft, y1: y, x2: paddingLeft + w, y2: y };
+    });
+  }, [showGrid, drawHeight, drawWidth, paddingTop, paddingLeft]);
+
+  const lastPoint = pointsArr.length === 0 ? null : pointsArr[pointsArr.length - 1];
+
+  const yTicks = useMemo(() => {
+    if (!showAxes) return [];
+    const { min, max } = yDomain;
+    const out: { y: number; label: string }[] = [];
+    if (valueMax === 100 && valueMin === 0 && yTickStep > 0) {
+      for (let p = min; p <= max; p += yTickStep) {
+        out.push({ y: project(p), label: yFormatter(p) });
+      }
+      return out;
+    }
+    const ticks = 5;
+    for (let i = 0; i < ticks; i++) {
+      const v = min + ((max - min) * i) / (ticks - 1);
+      out.push({ y: project(v), label: yFormatter(v) });
+    }
+    return out;
+  }, [showAxes, yDomain, valueMax, valueMin, yTickStep, project, yFormatter]);
+
+  const xTicks = useMemo(() => {
+    if (!showAxes) return [];
+    if (nPoints === 0) return [];
+    const m = Math.max(2, tickCountX);
+    const w = drawWidth;
+    const dx = nPoints > 1 ? w / (nPoints - 1) : 0;
+    const out: { x: number; label: string }[] = [];
+    for (let i = 0; i < m; i++) {
+      const idx = Math.round((i * (nPoints - 1)) / (m - 1));
+      const label = labelsSlice[idx] != null ? String(labelsSlice[idx]) : String(idx);
+      const x = Math.round(paddingLeft + idx * dx);
+      out.push({ x, label });
+    }
+    return out;
+  }, [showAxes, labelsSlice, nPoints, tickCountX, drawWidth, paddingLeft]);
+
+  const onMouseMove = useCallback(
+    (evt: MouseEvent<SVGSVGElement>) => {
+      if (!showTooltip || pointsArr.length === 0) return;
+      const rect = evt.currentTarget.getBoundingClientRect();
+      const px = evt.clientX - rect.left;
+      const x = (px / rect.width) * effectiveVbWidth;
+      const dx = nPoints > 1 ? drawWidth / (nPoints - 1) : 0;
+      const idx = Math.max(0, Math.min(nPoints - 1, Math.round((x - paddingLeft) / (dx || 1))));
+      setHoverIdx(idx);
+    },
+    [showTooltip, pointsArr.length, effectiveVbWidth, nPoints, drawWidth, paddingLeft],
+  );
+
+  const onMouseLeave = useCallback(() => setHoverIdx(-1), []);
+
+  const hoverText = useMemo(() => {
+    const idx = hoverIdx;
+    if (idx < 0 || idx >= dataSlice.length) return '';
+    const raw = Number(dataSlice[idx] || 0);
+    const fmt = tooltipFormatter || yFormatter;
+    const val = fmt(Number.isFinite(raw) ? raw : 0);
+    const lab = labelsSlice[idx] != null ? labelsSlice[idx] : '';
+    return `${val}${lab ? ' • ' + lab : ''}`;
+  }, [hoverIdx, dataSlice, labelsSlice, tooltipFormatter, yFormatter]);
+
+  const tooltipPillWidth = Math.max(48, hoverText.length * 6.2 + 14);
+  const hoverPoint = hoverIdx >= 0 ? pointsArr[hoverIdx] : null;
+  const tooltipX = hoverPoint
+    ? Math.max(
+        paddingLeft + 2,
+        Math.min(effectiveVbWidth - paddingRight - tooltipPillWidth - 2, hoverPoint[0] - tooltipPillWidth / 2),
+      )
+    : 0;
+
+  return (
+    <svg
+      ref={svgRef}
+      width="100%"
+      height={height}
+      viewBox={`0 0 ${effectiveVbWidth} ${height}`}
+      preserveAspectRatio="none"
+      className="sparkline-svg"
+      onMouseMove={onMouseMove}
+      onMouseLeave={onMouseLeave}
+    >
+      <defs>
+        <linearGradient id={gradId} x1="0" y1="0" x2="0" y2="1">
+          <stop offset="0%" stopColor={stroke} stopOpacity={Math.min(1, fillOpacity * 1.8)} />
+          <stop offset="50%" stopColor={stroke} stopOpacity={fillOpacity * 0.7} />
+          <stop offset="100%" stopColor={stroke} stopOpacity={0} />
+        </linearGradient>
+        <filter id={shadowId} x="-10%" y="-50%" width="120%" height="200%">
+          <feGaussianBlur in="SourceAlpha" stdDeviation="2.4" />
+          <feOffset dx="0" dy="2" result="offsetBlur" />
+          <feComponentTransfer>
+            <feFuncA type="linear" slope="0.45" />
+          </feComponentTransfer>
+          <feMerge>
+            <feMergeNode />
+            <feMergeNode in="SourceGraphic" />
+          </feMerge>
+        </filter>
+        <radialGradient id={glowId}>
+          <stop offset="0%" stopColor={stroke} stopOpacity="0.55" />
+          <stop offset="100%" stopColor={stroke} stopOpacity="0" />
+        </radialGradient>
+      </defs>
+
+      {showGrid && (
+        <g>
+          {gridLines.map((g, i) => (
+            <line
+              key={i}
+              x1={g.x1}
+              y1={g.y1}
+              x2={g.x2}
+              y2={g.y2}
+              stroke={gridColor}
+              strokeWidth={1}
+              strokeDasharray="3 5"
+              className="cpu-grid-line"
+            />
+          ))}
+        </g>
+      )}
+
+      {showAxes && (
+        <g>
+          {yTicks.map((tk, i) => (
+            <text
+              key={`y${i}`}
+              className="cpu-grid-y-text"
+              x={Math.max(0, paddingLeft - 6)}
+              y={tk.y + 4}
+              textAnchor="end"
+              fontSize={10.5}
+            >
+              {tk.label}
+            </text>
+          ))}
+          {xTicks.map((tk, i) => (
+            <text
+              key={`x${i}`}
+              className="cpu-grid-x-text"
+              x={tk.x}
+              y={paddingTop + drawHeight + 14}
+              textAnchor="middle"
+              fontSize={10.5}
+            >
+              {tk.label}
+            </text>
+          ))}
+        </g>
+      )}
+
+      {areaPath && <path d={areaPath} fill={`url(#${gradId})`} stroke="none" />}
+      <polyline
+        points={pointsStr}
+        fill="none"
+        stroke={stroke}
+        strokeWidth={strokeWidth}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        filter={`url(#${shadowId})`}
+      />
+      {showMarker && lastPoint && (
+        <>
+          <circle cx={lastPoint[0]} cy={lastPoint[1]} r={markerRadius * 3} fill={`url(#${glowId})`}>
+            <animate attributeName="r" values={`${markerRadius * 2.4};${markerRadius * 3.4};${markerRadius * 2.4}`} dur="2.6s" repeatCount="indefinite" />
+          </circle>
+          <circle cx={lastPoint[0]} cy={lastPoint[1]} r={markerRadius + 1.5} fill={stroke} fillOpacity={0.25} />
+          <circle cx={lastPoint[0]} cy={lastPoint[1]} r={markerRadius} fill={stroke} stroke="#fff" strokeWidth={1.5} />
+        </>
+      )}
+
+      {showTooltip && hoverIdx >= 0 && pointsArr[hoverIdx] && (
+        <g>
+          <line
+            className="cpu-grid-h-line"
+            x1={pointsArr[hoverIdx][0]}
+            x2={pointsArr[hoverIdx][0]}
+            y1={paddingTop}
+            y2={paddingTop + drawHeight}
+            stroke={stroke}
+            strokeOpacity={0.45}
+            strokeWidth={1}
+            strokeDasharray="3 4"
+          />
+          <circle cx={pointsArr[hoverIdx][0]} cy={pointsArr[hoverIdx][1]} r={5} fill={stroke} fillOpacity={0.25} />
+          <circle cx={pointsArr[hoverIdx][0]} cy={pointsArr[hoverIdx][1]} r={3.5} fill={stroke} stroke="#fff" strokeWidth={1.5} />
+          <rect
+            x={tooltipX}
+            y={paddingTop + 2}
+            width={tooltipPillWidth}
+            height={18}
+            rx={9}
+            ry={9}
+            className="cpu-tooltip-pill"
+            fill={stroke}
+            fillOpacity={0.92}
+          />
+          <text
+            className="cpu-tooltip-text"
+            x={tooltipX + tooltipPillWidth / 2}
+            y={paddingTop + 14}
+            textAnchor="middle"
+            fontSize={11}
+            fontWeight={600}
+            fill="#fff"
+          >
+            {hoverText}
+          </text>
+        </g>
+      )}
+    </svg>
+  );
+}

frontend/src/components/TextModal.tsx

@@ -0,0 +1,59 @@
+import { Button, Input, Modal, message } from 'antd';
+import { CopyOutlined, DownloadOutlined } from '@ant-design/icons';
+
+import { ClipboardManager, FileManager } from '@/utils';
+
+interface TextModalProps {
+  open: boolean;
+  onClose: () => void;
+  title: string;
+  content: string;
+  fileName?: string;
+}
+
+export default function TextModal({ open, onClose, title, content, fileName = '' }: TextModalProps) {
+  const [messageApi, messageContextHolder] = message.useMessage();
+  async function copy() {
+    const ok = await ClipboardManager.copyText(content || '');
+    if (ok) {
+      messageApi.success('Copied');
+      onClose();
+    }
+  }
+
+  function download() {
+    if (!fileName) return;
+    FileManager.downloadTextFile(content, fileName);
+  }
+
+  return (
+    <>
+      {messageContextHolder}
+      <Modal
+        open={open}
+        title={title}
+        onCancel={onClose}
+        destroyOnHidden
+      footer={(
+        <>
+          {fileName && (
+            <Button icon={<DownloadOutlined />} onClick={download}>{fileName}</Button>
+          )}
+          <Button type="primary" icon={<CopyOutlined />} onClick={copy}>Copy</Button>
+        </>
+      )}
+    >
+      <Input.TextArea
+        value={content}
+        readOnly
+        autoSize={{ minRows: 10, maxRows: 20 }}
+        style={{
+          fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace',
+          fontSize: 12,
+          overflowY: 'auto',
+        }}
+      />
+      </Modal>
+    </>
+  );
+}

frontend/src/entries/api-docs.tsx

@@ -0,0 +1,28 @@
+import { createRoot } from 'react-dom/client';
+import { message } from 'antd';
+import 'antd/dist/reset.css';
+
+import { setupAxios } from '@/api/axios-init.js';
+import { applyDocumentTitle } from '@/utils';
+import { readyI18n } from '@/i18n/react';
+import { ThemeProvider } from '@/hooks/useTheme';
+import ApiDocsPage from '@/pages/api-docs/ApiDocsPage';
+
+setupAxios();
+applyDocumentTitle();
+
+const messageContainer = document.getElementById('message');
+if (messageContainer) {
+  message.config({ getContainer: () => messageContainer });
+}
+
+readyI18n().then(() => {
+  const root = document.getElementById('app');
+  if (root) {
+    createRoot(root).render(
+      <ThemeProvider>
+        <ApiDocsPage />
+      </ThemeProvider>,
+    );
+  }
+});

frontend/src/entries/clients.tsx

@@ -0,0 +1,28 @@
+import { createRoot } from 'react-dom/client';
+import { message } from 'antd';
+import 'antd/dist/reset.css';
+
+import { setupAxios } from '@/api/axios-init.js';
+import { applyDocumentTitle } from '@/utils';
+import { readyI18n } from '@/i18n/react';
+import { ThemeProvider } from '@/hooks/useTheme';
+import ClientsPage from '@/pages/clients/ClientsPage';
+
+setupAxios();
+applyDocumentTitle();
+
+const messageContainer = document.getElementById('message');
+if (messageContainer) {
+  message.config({ getContainer: () => messageContainer });
+}
+
+readyI18n().then(() => {
+  const root = document.getElementById('app');
+  if (root) {
+    createRoot(root).render(
+      <ThemeProvider>
+        <ClientsPage />
+      </ThemeProvider>,
+    );
+  }
+});

frontend/src/entries/inbounds.tsx

@@ -0,0 +1,28 @@
+import { createRoot } from 'react-dom/client';
+import { message } from 'antd';
+import 'antd/dist/reset.css';
+
+import { setupAxios } from '@/api/axios-init.js';
+import { applyDocumentTitle } from '@/utils';
+import { readyI18n } from '@/i18n/react';
+import { ThemeProvider } from '@/hooks/useTheme';
+import InboundsPage from '@/pages/inbounds/InboundsPage';
+
+setupAxios();
+applyDocumentTitle();
+
+const messageContainer = document.getElementById('message');
+if (messageContainer) {
+  message.config({ getContainer: () => messageContainer });
+}
+
+readyI18n().then(() => {
+  const root = document.getElementById('app');
+  if (root) {
+    createRoot(root).render(
+      <ThemeProvider>
+        <InboundsPage />
+      </ThemeProvider>,
+    );
+  }
+});

frontend/src/entries/index.tsx

@@ -0,0 +1,28 @@
+import { createRoot } from 'react-dom/client';
+import { message } from 'antd';
+import 'antd/dist/reset.css';
+
+import { setupAxios } from '@/api/axios-init.js';
+import { applyDocumentTitle } from '@/utils';
+import { readyI18n } from '@/i18n/react';
+import { ThemeProvider } from '@/hooks/useTheme';
+import IndexPage from '@/pages/index/IndexPage';
+
+setupAxios();
+applyDocumentTitle();
+
+const messageContainer = document.getElementById('message');
+if (messageContainer) {
+  message.config({ getContainer: () => messageContainer });
+}
+
+readyI18n().then(() => {
+  const root = document.getElementById('app');
+  if (root) {
+    createRoot(root).render(
+      <ThemeProvider>
+        <IndexPage />
+      </ThemeProvider>,
+    );
+  }
+});

frontend/src/entries/login.tsx

@@ -0,0 +1,28 @@
+import { createRoot } from 'react-dom/client';
+import { message } from 'antd';
+import 'antd/dist/reset.css';
+
+import { setupAxios } from '@/api/axios-init.js';
+import { applyDocumentTitle } from '@/utils';
+import { readyI18n } from '@/i18n/react';
+import { ThemeProvider } from '@/hooks/useTheme';
+import LoginPage from '@/pages/login/LoginPage';
+
+setupAxios();
+applyDocumentTitle();
+
+const messageContainer = document.getElementById('message');
+if (messageContainer) {
+  message.config({ getContainer: () => messageContainer });
+}
+
+readyI18n().then(() => {
+  const root = document.getElementById('app');
+  if (root) {
+    createRoot(root).render(
+      <ThemeProvider>
+        <LoginPage />
+      </ThemeProvider>,
+    );
+  }
+});

frontend/src/entries/nodes.tsx

@@ -0,0 +1,28 @@
+import { createRoot } from 'react-dom/client';
+import { message } from 'antd';
+import 'antd/dist/reset.css';
+
+import { setupAxios } from '@/api/axios-init.js';
+import { applyDocumentTitle } from '@/utils';
+import { readyI18n } from '@/i18n/react';
+import { ThemeProvider } from '@/hooks/useTheme';
+import NodesPage from '@/pages/nodes/NodesPage';
+
+setupAxios();
+applyDocumentTitle();
+
+const messageContainer = document.getElementById('message');
+if (messageContainer) {
+  message.config({ getContainer: () => messageContainer });
+}
+
+readyI18n().then(() => {
+  const root = document.getElementById('app');
+  if (root) {
+    createRoot(root).render(
+      <ThemeProvider>
+        <NodesPage />
+      </ThemeProvider>,
+    );
+  }
+});

frontend/src/entries/settings.tsx

@@ -0,0 +1,28 @@
+import { createRoot } from 'react-dom/client';
+import { message } from 'antd';
+import 'antd/dist/reset.css';
+
+import { setupAxios } from '@/api/axios-init.js';
+import { applyDocumentTitle } from '@/utils';
+import { readyI18n } from '@/i18n/react';
+import { ThemeProvider } from '@/hooks/useTheme';
+import SettingsPage from '@/pages/settings/SettingsPage';
+
+setupAxios();
+applyDocumentTitle();
+
+const messageContainer = document.getElementById('message');
+if (messageContainer) {
+  message.config({ getContainer: () => messageContainer });
+}
+
+readyI18n().then(() => {
+  const root = document.getElementById('app');
+  if (root) {
+    createRoot(root).render(
+      <ThemeProvider>
+        <SettingsPage />
+      </ThemeProvider>,
+    );
+  }
+});

frontend/src/entries/subpage.tsx

@@ -0,0 +1,23 @@
+import { createRoot } from 'react-dom/client';
+import { message } from 'antd';
+import 'antd/dist/reset.css';
+
+import { readyI18n } from '@/i18n/react';
+import { ThemeProvider } from '@/hooks/useTheme';
+import SubPage from '@/pages/sub/SubPage';
+
+const messageContainer = document.getElementById('message');
+if (messageContainer) {
+  message.config({ getContainer: () => messageContainer });
+}
+
+readyI18n().then(() => {
+  const root = document.getElementById('app');
+  if (root) {
+    createRoot(root).render(
+      <ThemeProvider>
+        <SubPage />
+      </ThemeProvider>,
+    );
+  }
+});

frontend/src/entries/xray.tsx

@@ -0,0 +1,28 @@
+import { createRoot } from 'react-dom/client';
+import { message } from 'antd';
+import 'antd/dist/reset.css';
+
+import { setupAxios } from '@/api/axios-init.js';
+import { applyDocumentTitle } from '@/utils';
+import { readyI18n } from '@/i18n/react';
+import { ThemeProvider } from '@/hooks/useTheme';
+import XrayPage from '@/pages/xray/XrayPage';
+
+setupAxios();
+applyDocumentTitle();
+
+const messageContainer = document.getElementById('message');
+if (messageContainer) {
+  message.config({ getContainer: () => messageContainer });
+}
+
+readyI18n().then(() => {
+  const root = document.getElementById('app');
+  if (root) {
+    createRoot(root).render(
+      <ThemeProvider>
+        <XrayPage />
+      </ThemeProvider>,
+    );
+  }
+});

frontend/src/env.d.ts

@@ -0,0 +1,65 @@
+/// <reference types="vite/client" />
+
+interface SubPageData {
+  sId?: string;
+  enabled?: boolean;
+  download?: string;
+  upload?: string;
+  total?: string;
+  used?: string;
+  remained?: string;
+  totalByte?: string | number;
+  expire?: string | number;
+  lastOnline?: string | number;
+  subUrl?: string;
+  subJsonUrl?: string;
+  subClashUrl?: string;
+  subTitle?: string;
+  links?: string[];
+  datepicker?: 'gregorian' | 'jalalian';
+  downloadByte?: string | number;
+  uploadByte?: string | number;
+  usedByte?: string | number;
+}
+
+interface Window {
+  X_UI_BASE_PATH?: string;
+  X_UI_CUR_VER?: string;
+  __SUB_PAGE_DATA__?: SubPageData;
+}
+
+declare module 'persian-calendar-suite' {
+  import type { ComponentType, ReactNode } from 'react';
+
+  type DateInput = string | number | null;
+  type OutputFormat = 'iso' | 'shamsi' | 'gregorian' | 'hijri' | 'timestamp';
+
+  interface PersianDateTimePickerProps {
+    value?: DateInput;
+    onChange?: (value: number | string | null) => void;
+    defaultValue?: string | number | 'now' | null;
+    showTime?: boolean;
+    minuteStep?: number;
+    outputFormat?: OutputFormat;
+    showFooter?: boolean;
+    theme?: Record<string, unknown>;
+    disabledHours?: number[];
+    minDate?: string | Date | null;
+    maxDate?: string | Date | null;
+    enabledDates?: string[] | null;
+    disabledDates?: string[] | null;
+    disabledWeekDays?: number[];
+    persianNumbers?: boolean;
+    rtlCalendar?: boolean;
+    placeholder?: string;
+    disabled?: boolean;
+    className?: string;
+    children?: ReactNode;
+  }
+
+  export const PersianDateTimePicker: ComponentType<PersianDateTimePickerProps>;
+  export const PersianCalendar: ComponentType<Record<string, unknown>>;
+  export const PersianDateRangePicker: ComponentType<Record<string, unknown>>;
+  export const PersianTimePicker: ComponentType<Record<string, unknown>>;
+  export const PersianTimeline: ComponentType<Record<string, unknown>>;
+}

frontend/src/hooks/useAllSetting.ts

@@ -0,0 +1,69 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { HttpUtil } from '@/utils';
+import { AllSetting } from '@/models/setting';
+
+interface ApiMsg<T = unknown> {
+  success?: boolean;
+  obj?: T;
+}
+
+export function useAllSetting() {
+  const [allSetting, setAllSetting] = useState<AllSetting>(() => new AllSetting());
+  const [oldAllSetting, setOldAllSetting] = useState<AllSetting>(() => new AllSetting());
+  const [fetched, setFetched] = useState(false);
+  const [spinning, setSpinning] = useState(false);
+  const fetchedRef = useRef(false);
+
+  const applyServerState = useCallback((obj: unknown) => {
+    setAllSetting(new AllSetting(obj));
+    setOldAllSetting(new AllSetting(obj));
+  }, []);
+
+  const fetchAll = useCallback(async () => {
+    const msg = await HttpUtil.post('/panel/setting/all') as ApiMsg;
+    if (msg?.success) {
+      applyServerState(msg.obj);
+      fetchedRef.current = true;
+      setFetched(true);
+    }
+  }, [applyServerState]);
+
+  const saveAll = useCallback(async () => {
+    setSpinning(true);
+    try {
+      const msg = await HttpUtil.post('/panel/setting/update', allSetting) as ApiMsg;
+      if (msg?.success) await fetchAll();
+    } finally {
+      setSpinning(false);
+    }
+  }, [allSetting, fetchAll]);
+
+  const updateSetting = useCallback((patch: Partial<AllSetting>) => {
+    setAllSetting((prev) => {
+      const next = new AllSetting(prev);
+      Object.assign(next, patch);
+      return next;
+    });
+  }, []);
+
+  const saveDisabled = useMemo(
+    () => allSetting.equals(oldAllSetting),
+    [allSetting, oldAllSetting],
+  );
+
+  useEffect(() => {
+     
+    fetchAll();
+  }, [fetchAll]);
+
+  return {
+    allSetting,
+    updateSetting,
+    fetched,
+    spinning,
+    setSpinning,
+    saveDisabled,
+    fetchAll,
+    saveAll,
+  };
+}

frontend/src/hooks/useClients.ts

@@ -0,0 +1,391 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { HttpUtil } from '@/utils';
+
+const JSON_HEADERS = { headers: { 'Content-Type': 'application/json' } } as const;
+
+export interface ClientTraffic {
+  up?: number;
+  down?: number;
+  total?: number;
+  expiryTime?: number;
+  enable?: boolean;
+  lastOnline?: number;
+}
+
+export interface ClientRecord {
+  email: string;
+  subId?: string;
+  uuid?: string;
+  password?: string;
+  auth?: string;
+  flow?: string;
+  totalGB?: number;
+  expiryTime?: number;
+  limitIp?: number;
+  tgId?: number | string;
+  comment?: string;
+  enable?: boolean;
+  inboundIds?: number[];
+  traffic?: ClientTraffic;
+  reverse?: { tag?: string };
+  createdAt?: number;
+  updatedAt?: number;
+  [key: string]: unknown;
+}
+
+export interface InboundOption {
+  id: number;
+  remark?: string;
+  protocol?: string;
+  port?: number;
+  tlsFlowCapable?: boolean;
+}
+
+interface ApiMsg<T = unknown> {
+  success?: boolean;
+  msg?: string;
+  obj?: T;
+}
+
+interface SubSettings {
+  enable: boolean;
+  subURI: string;
+  subJsonURI: string;
+  subJsonEnable: boolean;
+}
+
+export interface ClientQueryParams {
+  page: number;
+  pageSize: number;
+  search?: string;
+  filter?: string;
+  protocol?: string;
+  inbound?: number;
+  sort?: string;
+  order?: 'ascend' | 'descend';
+}
+
+export interface ClientsSummary {
+  total: number;
+  active: number;
+  online: string[];
+  depleted: string[];
+  expiring: string[];
+  deactive: string[];
+}
+
+interface ClientPageResponse {
+  items: ClientRecord[];
+  total: number;
+  filtered: number;
+  page: number;
+  pageSize: number;
+  summary?: ClientsSummary;
+}
+
+const DEFAULT_QUERY: ClientQueryParams = { page: 1, pageSize: 25 };
+
+export function useClients() {
+  const [clients, setClients] = useState<ClientRecord[]>([]);
+  const [total, setTotal] = useState(0);
+  const [filtered, setFiltered] = useState(0);
+  const [summary, setSummary] = useState<ClientsSummary>({
+    total: 0, active: 0, online: [], depleted: [], expiring: [], deactive: [],
+  });
+  const [inbounds, setInbounds] = useState<InboundOption[]>([]);
+  const [onlines, setOnlines] = useState<string[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [fetched, setFetched] = useState(false);
+  const [query, setQueryState] = useState<ClientQueryParams>(DEFAULT_QUERY);
+  // Shallow-compare against the previous query so callers can pass a fresh
+  // object on every render (the common React pattern) without triggering a
+  // re-fetch when nothing actually changed.
+  const setQuery = useCallback((next: ClientQueryParams) => {
+    setQueryState((prev) => {
+      if (
+        prev.page === next.page
+        && prev.pageSize === next.pageSize
+        && (prev.search ?? '') === (next.search ?? '')
+        && (prev.filter ?? '') === (next.filter ?? '')
+        && (prev.protocol ?? '') === (next.protocol ?? '')
+        && (prev.inbound ?? 0) === (next.inbound ?? 0)
+        && (prev.sort ?? '') === (next.sort ?? '')
+        && (prev.order ?? '') === (next.order ?? '')
+      ) return prev;
+      return next;
+    });
+  }, []);
+  const [subSettings, setSubSettings] = useState<SubSettings>({
+    enable: false, subURI: '', subJsonURI: '', subJsonEnable: false,
+  });
+  const [ipLimitEnable, setIpLimitEnable] = useState(false);
+  const [tgBotEnable, setTgBotEnable] = useState(false);
+  const [expireDiff, setExpireDiff] = useState(0);
+  const [trafficDiff, setTrafficDiff] = useState(0);
+  const [pageSize, setPageSize] = useState(0);
+
+  const clientsRef = useRef<ClientRecord[]>([]);
+  const queryRef = useRef<ClientQueryParams>(query);
+  const invalidateTimerRef = useRef<number | null>(null);
+
+  useEffect(() => { clientsRef.current = clients; }, [clients]);
+  useEffect(() => { queryRef.current = query; }, [query]);
+
+  const buildQS = (p: ClientQueryParams) => {
+    const sp = new URLSearchParams();
+    sp.set('page', String(p.page || 1));
+    sp.set('pageSize', String(p.pageSize || DEFAULT_QUERY.pageSize));
+    if (p.search) sp.set('search', p.search);
+    if (p.filter) sp.set('filter', p.filter);
+    if (p.protocol) sp.set('protocol', p.protocol);
+    if (p.inbound && p.inbound > 0) sp.set('inbound', String(p.inbound));
+    if (p.sort) sp.set('sort', p.sort);
+    if (p.order) sp.set('order', p.order);
+    return sp.toString();
+  };
+
+  const refresh = useCallback(async (override?: ClientQueryParams) => {
+    setLoading(true);
+    try {
+      const params = override ?? queryRef.current;
+      const qs = buildQS(params);
+      const msg = await HttpUtil.get(`/panel/api/clients/list/paged?${qs}`) as ApiMsg<ClientPageResponse>;
+      if (msg?.success && msg.obj) {
+        setClients(Array.isArray(msg.obj.items) ? msg.obj.items : []);
+        setTotal(msg.obj.total ?? 0);
+        setFiltered(msg.obj.filtered ?? 0);
+        if (msg.obj.summary) setSummary(msg.obj.summary);
+      }
+      setFetched(true);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  // Inbound options are picker-shaped and don't depend on the clients query —
+  // fetch them once on mount instead of every refresh.
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      const msg = await HttpUtil.get('/panel/api/inbounds/options') as ApiMsg<InboundOption[]>;
+      if (cancelled) return;
+      if (msg?.success) setInbounds(Array.isArray(msg.obj) ? msg.obj : []);
+    })();
+    return () => { cancelled = true; };
+  }, []);
+
+  const fetchSubSettings = useCallback(async () => {
+    const msg = await HttpUtil.post('/panel/setting/defaultSettings') as ApiMsg<Record<string, unknown>>;
+    if (!msg?.success) return;
+    const s = msg.obj || {};
+    setSubSettings({
+      enable: !!s.subEnable,
+      subURI: (s.subURI as string) || '',
+      subJsonURI: (s.subJsonURI as string) || '',
+      subJsonEnable: !!s.subJsonEnable,
+    });
+    setIpLimitEnable(!!s.ipLimitEnable);
+    setTgBotEnable(!!s.tgBotEnable);
+    setExpireDiff(((s.expireDiff as number) ?? 0) * 86400000);
+    setTrafficDiff(((s.trafficDiff as number) ?? 0) * 1073741824);
+    setPageSize((s.pageSize as number) ?? 0);
+  }, []);
+
+  // hydrate fetches the full client record (uuid, password, flow, ...) for a
+  // single email. The paged list endpoint omits these to keep the row payload
+  // tiny; edit / info / qr / link modals call this to get a complete record
+  // before opening.
+  const hydrate = useCallback(async (email: string): Promise<{ client: ClientRecord; inboundIds: number[] } | null> => {
+    if (!email) return null;
+    const msg = await HttpUtil.get(`/panel/api/clients/get/${encodeURIComponent(email)}`) as ApiMsg<{ client: ClientRecord; inboundIds: number[] }>;
+    if (!msg?.success || !msg.obj) return null;
+    return msg.obj;
+  }, []);
+
+  const create = useCallback(async (payload: unknown) => {
+    const msg = await HttpUtil.post('/panel/api/clients/add', payload, JSON_HEADERS) as ApiMsg;
+    if (msg?.success) await refresh();
+    return msg;
+  }, [refresh]);
+
+  const update = useCallback(async (email: string, client: unknown) => {
+    if (!email) return null;
+    const encoded = encodeURIComponent(email);
+    const msg = await HttpUtil.post(`/panel/api/clients/update/${encoded}`, client, JSON_HEADERS) as ApiMsg;
+    if (msg?.success) await refresh();
+    return msg;
+  }, [refresh]);
+
+  const remove = useCallback(async (email: string, keepTraffic = false) => {
+    if (!email) return null;
+    const encoded = encodeURIComponent(email);
+    const url = keepTraffic
+      ? `/panel/api/clients/del/${encoded}?keepTraffic=1`
+      : `/panel/api/clients/del/${encoded}`;
+    const msg = await HttpUtil.post(url) as ApiMsg;
+    if (msg?.success) await refresh();
+    return msg;
+  }, [refresh]);
+
+  const removeMany = useCallback(async (emails: string[], keepTraffic = false) => {
+    if (!Array.isArray(emails) || emails.length === 0) return [];
+    const suffix = keepTraffic ? '?keepTraffic=1' : '';
+    const results = await Promise.all(emails.map((email) => {
+      const url = `/panel/api/clients/del/${encodeURIComponent(email)}${suffix}`;
+      return HttpUtil.post(url, undefined, { silent: true }) as Promise<ApiMsg>;
+    }));
+    await refresh();
+    return results;
+  }, [refresh]);
+
+  const bulkAdjust = useCallback(async (emails: string[], addDays: number, addBytes: number) => {
+    if (!Array.isArray(emails) || emails.length === 0) return null;
+    const msg = await HttpUtil.post(
+      '/panel/api/clients/bulkAdjust',
+      { emails, addDays, addBytes },
+      JSON_HEADERS,
+    ) as ApiMsg<{ adjusted: number; skipped?: { email: string; reason: string }[] }>;
+    if (msg?.success) await refresh();
+    return msg;
+  }, [refresh]);
+
+  const attach = useCallback(async (email: string, inboundIds: number[]) => {
+    if (!email) return null;
+    const encoded = encodeURIComponent(email);
+    const msg = await HttpUtil.post(`/panel/api/clients/${encoded}/attach`, { inboundIds }, JSON_HEADERS) as ApiMsg;
+    if (msg?.success) await refresh();
+    return msg;
+  }, [refresh]);
+
+  const detach = useCallback(async (email: string, inboundIds: number[]) => {
+    if (!email) return null;
+    const encoded = encodeURIComponent(email);
+    const msg = await HttpUtil.post(`/panel/api/clients/${encoded}/detach`, { inboundIds }, JSON_HEADERS) as ApiMsg;
+    if (msg?.success) await refresh();
+    return msg;
+  }, [refresh]);
+
+  const resetTraffic = useCallback(async (client: ClientRecord) => {
+    if (!client?.email) return null;
+    const url = `/panel/api/clients/resetTraffic/${encodeURIComponent(client.email)}`;
+    const msg = await HttpUtil.post(url) as ApiMsg;
+    if (msg?.success) await refresh();
+    return msg;
+  }, [refresh]);
+
+  const resetAllTraffics = useCallback(async () => {
+    const msg = await HttpUtil.post('/panel/api/clients/resetAllTraffics') as ApiMsg;
+    if (msg?.success) await refresh();
+    return msg;
+  }, [refresh]);
+
+  const delDepleted = useCallback(async () => {
+    const msg = await HttpUtil.post('/panel/api/clients/delDepleted') as ApiMsg<{ deleted?: number }>;
+    if (msg?.success) await refresh();
+    return msg;
+  }, [refresh]);
+
+  const setEnable = useCallback(async (client: ClientRecord, enable: boolean) => {
+    if (!client?.email) return null;
+    const payload = {
+      email: client.email,
+      subId: client.subId,
+      id: client.uuid,
+      password: client.password,
+      auth: client.auth,
+      totalGB: client.totalGB || 0,
+      expiryTime: client.expiryTime || 0,
+      limitIp: client.limitIp || 0,
+      comment: client.comment || '',
+      enable: !!enable,
+    };
+    return update(client.email, payload);
+  }, [update]);
+
+  const applyTrafficEvent = useCallback((payload: unknown) => {
+    if (!payload || typeof payload !== 'object') return;
+    const p = payload as { onlineClients?: string[] };
+    if (Array.isArray(p.onlineClients)) {
+      setOnlines(p.onlineClients);
+    }
+  }, []);
+
+  const applyClientStatsEvent = useCallback((payload: unknown) => {
+    if (!payload || typeof payload !== 'object') return;
+    const p = payload as { clients?: ClientTraffic[] & { email?: string }[] };
+    if (!Array.isArray(p.clients) || p.clients.length === 0) return;
+    const byEmail = new Map<string, ClientTraffic>();
+    for (const row of p.clients as (ClientTraffic & { email?: string })[]) {
+      if (row && row.email) byEmail.set(row.email, row);
+    }
+    const cur = clientsRef.current || [];
+    let touched = false;
+    const next = cur.slice();
+    for (let i = 0; i < next.length; i++) {
+      const row = next[i];
+      const upd = byEmail.get(row?.email);
+      if (!upd) continue;
+      const merged: ClientTraffic = { ...(row.traffic || {}) };
+      if (typeof upd.up === 'number') merged.up = upd.up;
+      if (typeof upd.down === 'number') merged.down = upd.down;
+      if (typeof upd.total === 'number') merged.total = upd.total;
+      if (typeof upd.expiryTime === 'number') merged.expiryTime = upd.expiryTime;
+      if (typeof upd.enable === 'boolean') merged.enable = upd.enable;
+      if (typeof upd.lastOnline === 'number') merged.lastOnline = upd.lastOnline;
+      next[i] = { ...row, traffic: merged };
+      touched = true;
+    }
+    if (touched) setClients(next);
+  }, []);
+
+  const applyInvalidate = useCallback((payload: unknown) => {
+    if (!payload || typeof payload !== 'object') return;
+    const p = payload as { type?: string };
+    if (p.type !== 'inbounds' && p.type !== 'clients') return;
+    if (invalidateTimerRef.current != null) clearTimeout(invalidateTimerRef.current);
+    invalidateTimerRef.current = window.setTimeout(() => {
+      invalidateTimerRef.current = null;
+      refresh();
+    }, 200);
+  }, [refresh]);
+
+  useEffect(() => {
+    Promise.all([refresh(query), fetchSubSettings()]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [query, fetchSubSettings]);
+
+  return {
+    clients,
+    total,
+    filtered,
+    summary,
+    hydrate,
+    query,
+    setQuery,
+    inbounds,
+    onlines,
+    loading,
+    fetched,
+    subSettings,
+    ipLimitEnable,
+    tgBotEnable,
+    expireDiff,
+    trafficDiff,
+    pageSize,
+    refresh,
+    create,
+    update,
+    remove,
+    removeMany,
+    bulkAdjust,
+    attach,
+    detach,
+    resetTraffic,
+    resetAllTraffics,
+    delDepleted,
+    setEnable,
+    applyTrafficEvent,
+    applyClientStatsEvent,
+    applyInvalidate,
+  };
+}

frontend/src/hooks/useDatepicker.ts

@@ -0,0 +1,57 @@
+import { useEffect, useState } from 'react';
+import { HttpUtil } from '@/utils';
+
+type Calendar = 'gregorian' | 'jalalian';
+
+let cachedValue: Calendar = 'gregorian';
+let fetched = false;
+let pending: Promise<void> | null = null;
+const listeners = new Set<(value: Calendar) => void>();
+
+function notify(value: Calendar) {
+  listeners.forEach((fn) => fn(value));
+}
+
+async function loadOnce(): Promise<void> {
+  if (fetched) return;
+  if (pending) {
+    await pending;
+    return;
+  }
+  pending = (async () => {
+    try {
+      const msg = await HttpUtil.post('/panel/setting/defaultSettings') as {
+        success?: boolean;
+        obj?: { datepicker?: Calendar };
+      };
+      if (msg?.success) {
+        cachedValue = msg.obj?.datepicker || 'gregorian';
+        notify(cachedValue);
+      }
+    } finally {
+      fetched = true;
+      pending = null;
+    }
+  })();
+  await pending;
+}
+
+export function setDatepicker(value: Calendar) {
+  fetched = true;
+  cachedValue = value || 'gregorian';
+  notify(cachedValue);
+}
+
+export function useDatepicker() {
+  const [datepicker, setLocal] = useState<Calendar>(cachedValue);
+
+  useEffect(() => {
+    listeners.add(setLocal);
+    loadOnce();
+    return () => {
+      listeners.delete(setLocal);
+    };
+  }, []);
+
+  return { datepicker };
+}

frontend/src/hooks/useMediaQuery.ts

@@ -0,0 +1,15 @@
+import { useEffect, useState } from 'react';
+
+const MOBILE_BREAKPOINT_PX = 768;
+
+export function useMediaQuery(breakpoint: number = MOBILE_BREAKPOINT_PX) {
+  const [isMobile, setIsMobile] = useState<boolean>(() => window.innerWidth <= breakpoint);
+
+  useEffect(() => {
+    const onResize = () => setIsMobile(window.innerWidth <= breakpoint);
+    window.addEventListener('resize', onResize);
+    return () => window.removeEventListener('resize', onResize);
+  }, [breakpoint]);
+
+  return { isMobile };
+}

frontend/src/hooks/useNodes.ts

@@ -0,0 +1,177 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { HttpUtil } from '@/utils';
+
+export interface NodeRecord {
+  id: number;
+  name?: string;
+  remark?: string;
+  scheme?: string;
+  address?: string;
+  port?: number;
+  basePath?: string;
+  apiToken?: string;
+  enable?: boolean;
+  status?: 'online' | 'offline' | string;
+  latencyMs?: number;
+  cpuPct?: number;
+  memPct?: number;
+  xrayVersion?: string;
+  panelVersion?: string;
+  uptimeSecs?: number;
+  inboundCount?: number;
+  clientCount?: number;
+  onlineCount?: number;
+  depletedCount?: number;
+  lastHeartbeat?: number;
+  lastError?: string;
+  allowPrivateAddress?: boolean;
+  [key: string]: unknown;
+}
+
+interface ApiMsg<T = unknown> {
+  success?: boolean;
+  msg?: string;
+  obj?: T;
+}
+
+interface NodeTotals {
+  total: number;
+  online: number;
+  offline: number;
+  avgLatency: number;
+  inbounds: number;
+  clients: number;
+  onlineClients: number;
+  depleted: number;
+}
+
+export function useNodes() {
+  const [nodes, setNodes] = useState<NodeRecord[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [fetched, setFetched] = useState(false);
+  const fetchedRef = useRef(false);
+
+  const refresh = useCallback(async () => {
+    setLoading(true);
+    try {
+      const msg = await HttpUtil.get('/panel/api/nodes/list') as ApiMsg<NodeRecord[]>;
+      if (msg?.success) {
+        setNodes(Array.isArray(msg.obj) ? msg.obj : []);
+      }
+      fetchedRef.current = true;
+      setFetched(true);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  const applyNodesEvent = useCallback((payload: unknown) => {
+    if (Array.isArray(payload)) {
+      setNodes(payload as NodeRecord[]);
+      if (!fetchedRef.current) {
+        fetchedRef.current = true;
+        setFetched(true);
+      }
+    }
+  }, []);
+
+  const create = useCallback(async (payload: Partial<NodeRecord>) => {
+    const msg = await HttpUtil.post('/panel/api/nodes/add', payload) as ApiMsg;
+    if (msg?.success) await refresh();
+    return msg;
+  }, [refresh]);
+
+  const update = useCallback(async (id: number, payload: Partial<NodeRecord>) => {
+    const msg = await HttpUtil.post(`/panel/api/nodes/update/${id}`, payload) as ApiMsg;
+    if (msg?.success) await refresh();
+    return msg;
+  }, [refresh]);
+
+  const remove = useCallback(async (id: number) => {
+    const msg = await HttpUtil.post(`/panel/api/nodes/del/${id}`) as ApiMsg;
+    if (msg?.success) await refresh();
+    return msg;
+  }, [refresh]);
+
+  const setEnable = useCallback(async (id: number, enable: boolean) => {
+    const msg = await HttpUtil.post(`/panel/api/nodes/setEnable/${id}`, { enable }) as ApiMsg;
+    if (msg?.success) await refresh();
+    return msg;
+  }, [refresh]);
+
+  const testConnection = useCallback(async (payload: Partial<NodeRecord>) => {
+    return await HttpUtil.post('/panel/api/nodes/test', payload) as ApiMsg<{
+      status: string;
+      latencyMs?: number;
+      xrayVersion?: string;
+      error?: string;
+    }>;
+  }, []);
+
+  const probe = useCallback(async (id: number) => {
+    const msg = await HttpUtil.post(`/panel/api/nodes/probe/${id}`) as ApiMsg<{
+      status: string;
+      latencyMs?: number;
+      error?: string;
+    }>;
+    if (msg?.success) await refresh();
+    return msg;
+  }, [refresh]);
+
+  const totals = useMemo<NodeTotals>(() => {
+    let online = 0;
+    let offline = 0;
+    let latencySum = 0;
+    let latencyCount = 0;
+    let inbounds = 0;
+    let clients = 0;
+    let onlineClients = 0;
+    let depleted = 0;
+    for (const n of nodes) {
+      inbounds += n.inboundCount || 0;
+      clients += n.clientCount || 0;
+      onlineClients += n.onlineCount || 0;
+      depleted += n.depletedCount || 0;
+      if (!n.enable) continue;
+      if (n.status === 'online') {
+        online += 1;
+        if (n.latencyMs && n.latencyMs > 0) {
+          latencySum += n.latencyMs;
+          latencyCount += 1;
+        }
+      } else if (n.status === 'offline') {
+        offline += 1;
+      }
+    }
+    return {
+      total: nodes.length,
+      online,
+      offline,
+      avgLatency: latencyCount > 0 ? Math.round(latencySum / latencyCount) : 0,
+      inbounds,
+      clients,
+      onlineClients,
+      depleted,
+    };
+  }, [nodes]);
+
+  useEffect(() => {
+     
+    refresh();
+  }, [refresh]);
+
+  return {
+    nodes,
+    loading,
+    fetched,
+    totals,
+    refresh,
+    applyNodesEvent,
+    create,
+    update,
+    remove,
+    setEnable,
+    testConnection,
+    probe,
+  };
+}

frontend/src/hooks/useStatus.ts

@@ -0,0 +1,35 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { HttpUtil } from '@/utils';
+import { Status } from '@/models/status';
+
+const POLL_INTERVAL_MS = 2000;
+
+export function useStatus() {
+  const [status, setStatus] = useState<Status>(() => new Status());
+  const [fetched, setFetched] = useState(false);
+  const fetchedRef = useRef(false);
+
+  const refresh = useCallback(async () => {
+    try {
+      const msg = await HttpUtil.get('/panel/api/server/status');
+      if (msg?.success) {
+        setStatus(new Status(msg.obj));
+        if (!fetchedRef.current) {
+          fetchedRef.current = true;
+          setFetched(true);
+        }
+      }
+    } catch (e) {
+      console.error('Failed to get status:', e);
+    }
+  }, []);
+
+  useEffect(() => {
+    refresh();
+    const timer = window.setInterval(refresh, POLL_INTERVAL_MS);
+    return () => window.clearInterval(timer);
+  }, [refresh]);
+
+  return { status, fetched, refresh };
+}

frontend/src/hooks/useTheme.tsx

@@ -0,0 +1,136 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';
+import type { ReactNode } from 'react';
+import { theme as antdTheme } from 'antd';
+import type { ThemeConfig } from 'antd';
+
+const STORAGE_DARK = 'dark-mode';
+const STORAGE_ULTRA = 'isUltraDarkThemeEnabled';
+
+function readBool(key: string, fallback: boolean): boolean {
+  const raw = localStorage.getItem(key);
+  if (raw === null) return fallback;
+  return raw === 'true';
+}
+
+function applyDom(isDark: boolean, isUltra: boolean) {
+  document.body.setAttribute('class', isDark ? 'dark' : 'light');
+  if (isUltra) {
+    document.documentElement.setAttribute('data-theme', 'ultra-dark');
+  } else {
+    document.documentElement.removeAttribute('data-theme');
+  }
+  const msg = document.getElementById('message');
+  if (msg) msg.className = isDark ? 'dark' : 'light';
+}
+
+// module load so the document is in the right theme before React mounts.
+const initialDark = readBool(STORAGE_DARK, true);
+const initialUltra = readBool(STORAGE_ULTRA, false);
+applyDom(initialDark, initialUltra);
+
+const DARK_TOKENS = {
+  colorBgBase: '#1a1b1f',
+  colorBgLayout: '#1a1b1f',
+  colorBgContainer: '#23252b',
+  colorBgElevated: '#2d2f37',
+};
+const ULTRA_DARK_TOKENS = {
+  colorBgBase: '#000',
+  colorBgLayout: '#000',
+  colorBgContainer: '#101013',
+  colorBgElevated: '#1a1a1e',
+};
+const DARK_LAYOUT_TOKENS = {
+  bodyBg: '#1a1b1f',
+  headerBg: '#15161a',
+  headerColor: '#ffffff',
+  footerBg: '#1a1b1f',
+  siderBg: '#15161a',
+  triggerBg: '#23252b',
+  triggerColor: '#ffffff',
+};
+const ULTRA_DARK_LAYOUT_TOKENS = {
+  bodyBg: '#000',
+  headerBg: '#050507',
+  headerColor: '#ffffff',
+  footerBg: '#000',
+  siderBg: '#050507',
+  triggerBg: '#1a1a1e',
+  triggerColor: '#ffffff',
+};
+const DARK_MENU_TOKENS = {
+  darkItemBg: '#15161a',
+  darkSubMenuItemBg: '#1a1b1f',
+  darkPopupBg: '#23252b',
+};
+const ULTRA_DARK_MENU_TOKENS = {
+  darkItemBg: '#050507',
+  darkSubMenuItemBg: '#000',
+  darkPopupBg: '#101013',
+};
+
+export function buildAntdThemeConfig(isDark: boolean, isUltra: boolean): ThemeConfig {
+  if (!isDark) {
+    return { algorithm: antdTheme.defaultAlgorithm };
+  }
+  return {
+    algorithm: antdTheme.darkAlgorithm,
+    token: isUltra ? ULTRA_DARK_TOKENS : DARK_TOKENS,
+    components: {
+      Layout: isUltra ? ULTRA_DARK_LAYOUT_TOKENS : DARK_LAYOUT_TOKENS,
+      Menu: isUltra ? ULTRA_DARK_MENU_TOKENS : DARK_MENU_TOKENS,
+    },
+  };
+}
+
+export function pauseAnimationsUntilLeave(elementId: string): void {
+  document.documentElement.setAttribute('data-theme-animations', 'off');
+  const el = document.getElementById(elementId);
+  if (!el) return;
+  const restore = () => {
+    document.documentElement.removeAttribute('data-theme-animations');
+    el.removeEventListener('mouseleave', restore);
+    el.removeEventListener('touchend', restore);
+  };
+  el.addEventListener('mouseleave', restore);
+  el.addEventListener('touchend', restore);
+}
+
+interface ThemeContextValue {
+  isDark: boolean;
+  isUltra: boolean;
+  toggleTheme: () => void;
+  toggleUltra: () => void;
+  antdThemeConfig: ThemeConfig;
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [isDark, setIsDark] = useState<boolean>(initialDark);
+  const [isUltra, setIsUltra] = useState<boolean>(initialUltra);
+
+  useEffect(() => {
+    applyDom(isDark, isUltra);
+    localStorage.setItem(STORAGE_DARK, String(isDark));
+    localStorage.setItem(STORAGE_ULTRA, String(isUltra));
+  }, [isDark, isUltra]);
+
+  const toggleTheme = useCallback(() => setIsDark((v) => !v), []);
+  const toggleUltra = useCallback(() => setIsUltra((v) => !v), []);
+
+  const antdThemeConfig = useMemo(() => buildAntdThemeConfig(isDark, isUltra), [isDark, isUltra]);
+
+  const value = useMemo<ThemeContextValue>(
+    () => ({ isDark, isUltra, toggleTheme, toggleUltra, antdThemeConfig }),
+    [isDark, isUltra, toggleTheme, toggleUltra, antdThemeConfig],
+  );
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme(): ThemeContextValue {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) throw new Error('useTheme must be used inside <ThemeProvider>');
+  return ctx;
+}

frontend/src/hooks/useWebSocket.ts

@@ -0,0 +1,32 @@
+import { useEffect } from 'react';
+import { WebSocketClient } from '@/api/websocket.js';
+
+type Handler = (payload: unknown) => void;
+
+interface SharedClient {
+  connect(): void;
+  on(event: string, fn: Handler): void;
+  off(event: string, fn: Handler): void;
+}
+
+let sharedClient: SharedClient | null = null;
+
+function getSharedClient(): SharedClient {
+  if (sharedClient) return sharedClient;
+  const basePath = (typeof window !== 'undefined' && window.X_UI_BASE_PATH) || '';
+  sharedClient = new WebSocketClient(basePath) as SharedClient;
+  return sharedClient;
+}
+
+export function useWebSocket(handlers: Record<string, Handler>) {
+  useEffect(() => {
+    const client = getSharedClient();
+    const entries = Object.entries(handlers);
+    for (const [event, fn] of entries) client.on(event, fn);
+    client.connect();
+    return () => {
+      for (const [event, fn] of entries) client.off(event, fn);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+}

frontend/src/hooks/useXraySetting.ts

@@ -0,0 +1,370 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { HttpUtil, PromiseUtil } from '@/utils';
+
+const DIRTY_POLL_MS = 1000;
+
+export interface OutboundTrafficRow {
+  tag: string;
+  up: number;
+  down: number;
+}
+
+export interface OutboundTestResult {
+  success: boolean;
+  delay?: number;
+  error?: string;
+  mode?: string;
+  ttfbMs?: number;
+  tlsMs?: number;
+  connectMs?: number;
+  dnsMs?: number;
+  statusCode?: number;
+  endpoints?: { address: string; delay?: number; success: boolean; error?: string }[];
+}
+
+export interface OutboundTestState {
+  testing?: boolean;
+  result?: OutboundTestResult | null;
+  mode?: string;
+}
+
+export interface XraySettingsValue {
+  inbounds?: unknown[];
+  outbounds?: { tag?: string; protocol?: string; settings?: unknown; streamSettings?: unknown }[];
+  routing?: {
+    rules?: { type?: string; outboundTag?: string; balancerTag?: string; [key: string]: unknown }[];
+    balancers?: unknown[];
+    domainStrategy?: string;
+  };
+  dns?: { tag?: string; servers?: unknown[] };
+  log?: Record<string, unknown>;
+  policy?: { system?: Record<string, boolean> };
+  observatory?: unknown;
+  burstObservatory?: unknown;
+  fakedns?: unknown;
+  [key: string]: unknown;
+}
+
+export type SetTemplate = (
+  next: XraySettingsValue | null | ((prev: XraySettingsValue | null) => XraySettingsValue | null),
+) => void;
+
+export interface UseXraySettingResult {
+  fetched: boolean;
+  spinning: boolean;
+  saveDisabled: boolean;
+  fetchError: string;
+  xraySetting: string;
+  setXraySetting: (next: string) => void;
+  templateSettings: XraySettingsValue | null;
+  setTemplateSettings: SetTemplate;
+  outboundTestUrl: string;
+  setOutboundTestUrl: (v: string) => void;
+  inboundTags: string[];
+  clientReverseTags: string[];
+  restartResult: string;
+  outboundsTraffic: OutboundTrafficRow[];
+  outboundTestStates: Record<number, OutboundTestState>;
+  testingAll: boolean;
+  fetchAll: () => Promise<void>;
+  fetchOutboundsTraffic: () => Promise<void>;
+  resetOutboundsTraffic: (tag: string) => Promise<void>;
+  applyOutboundsEvent: (payload: unknown) => void;
+  testOutbound: (
+    index: number,
+    outbound: unknown,
+    mode?: string,
+  ) => Promise<OutboundTestResult | null>;
+  testAllOutbounds: (mode?: string) => Promise<void>;
+  saveAll: () => Promise<void>;
+  resetToDefault: () => Promise<void>;
+  restartXray: () => Promise<void>;
+}
+
+export function useXraySetting(): UseXraySettingResult {
+  const [fetched, setFetched] = useState(false);
+  const [spinning, setSpinning] = useState(false);
+  const [saveDisabled, setSaveDisabled] = useState(true);
+  const [fetchError, setFetchError] = useState('');
+  const [xraySetting, setXraySettingState] = useState('');
+  const [templateSettings, setTemplateSettingsState] = useState<XraySettingsValue | null>(null);
+  const [outboundTestUrl, setOutboundTestUrlState] = useState('https://www.google.com/generate_204');
+  const [inboundTags, setInboundTags] = useState<string[]>([]);
+  const [clientReverseTags, setClientReverseTags] = useState<string[]>([]);
+  const [restartResult, setRestartResult] = useState('');
+  const [outboundsTraffic, setOutboundsTraffic] = useState<OutboundTrafficRow[]>([]);
+  const [outboundTestStates, setOutboundTestStates] = useState<Record<number, OutboundTestState>>({});
+  const [testingAll, setTestingAll] = useState(false);
+
+  const oldXraySettingRef = useRef('');
+  const oldOutboundTestUrlRef = useRef('');
+  const syncingRef = useRef(false);
+  const xraySettingRef = useRef('');
+  const outboundTestUrlRef = useRef(outboundTestUrl);
+  const templateSettingsRef = useRef<XraySettingsValue | null>(null);
+
+  xraySettingRef.current = xraySetting;
+  outboundTestUrlRef.current = outboundTestUrl;
+  templateSettingsRef.current = templateSettings;
+
+  const setXraySetting = useCallback((next: string) => {
+    setXraySettingState(next);
+    if (syncingRef.current) return;
+    try {
+      const parsed = JSON.parse(next);
+      syncingRef.current = true;
+      setTemplateSettingsState(parsed);
+      syncingRef.current = false;
+    } catch {
+      /* ignore — wait for user to finish */
+    }
+  }, []);
+
+  const setTemplateSettings: SetTemplate = useCallback((nextOrFn) => {
+    setTemplateSettingsState((prev) => {
+      const next = typeof nextOrFn === 'function' ? nextOrFn(prev) : nextOrFn;
+      if (next == null) return next;
+      if (!syncingRef.current) {
+        try {
+          syncingRef.current = true;
+          setXraySettingState(JSON.stringify(next, null, 2));
+        } finally {
+          syncingRef.current = false;
+        }
+      }
+      return next;
+    });
+  }, []);
+
+  const setOutboundTestUrl = useCallback((v: string) => {
+    setOutboundTestUrlState(v);
+  }, []);
+
+  const fetchAll = useCallback(async () => {
+    setFetchError('');
+    const msg = await HttpUtil.post('/panel/xray/');
+    if (!msg?.success) {
+      setFetchError(msg?.msg || 'Failed to load xray config');
+      setFetched(true);
+      return;
+    }
+    let obj;
+    try {
+      obj = JSON.parse(msg.obj);
+    } catch (e) {
+      const err = e as Error;
+      setFetchError(`Malformed xray config response: ${err?.message || String(err)}`);
+      setFetched(true);
+      return;
+    }
+    const pretty = JSON.stringify(obj.xraySetting, null, 2);
+    syncingRef.current = true;
+    setXraySettingState(pretty);
+    setTemplateSettingsState(obj.xraySetting);
+    oldXraySettingRef.current = pretty;
+    syncingRef.current = false;
+    setInboundTags(obj.inboundTags || []);
+    setClientReverseTags(obj.clientReverseTags || []);
+    const nextUrl = obj.outboundTestUrl || 'https://www.google.com/generate_204';
+    setOutboundTestUrlState(nextUrl);
+    oldOutboundTestUrlRef.current = nextUrl;
+    setFetched(true);
+    setSaveDisabled(true);
+  }, []);
+
+  const saveAll = useCallback(async () => {
+    setSpinning(true);
+    try {
+      const msg = await HttpUtil.post('/panel/xray/update', {
+        xraySetting: xraySettingRef.current,
+        outboundTestUrl: outboundTestUrlRef.current || 'https://www.google.com/generate_204',
+      });
+      if (msg?.success) await fetchAll();
+    } finally {
+      setSpinning(false);
+    }
+  }, [fetchAll]);
+
+  const fetchOutboundsTraffic = useCallback(async () => {
+    const msg = await HttpUtil.get('/panel/xray/getOutboundsTraffic');
+    if (msg?.success) setOutboundsTraffic(msg.obj || []);
+  }, []);
+
+  const resetOutboundsTraffic = useCallback(async (tag: string) => {
+    const msg = await HttpUtil.post('/panel/xray/resetOutboundsTraffic', { tag });
+    if (msg?.success) await fetchOutboundsTraffic();
+  }, [fetchOutboundsTraffic]);
+
+  const applyOutboundsEvent = useCallback((payload: unknown) => {
+    if (Array.isArray(payload)) setOutboundsTraffic(payload as OutboundTrafficRow[]);
+  }, []);
+
+  const testOutbound = useCallback(
+    async (index: number, outbound: unknown, mode = 'tcp'): Promise<OutboundTestResult | null> => {
+      if (!outbound) return null;
+      setOutboundTestStates((prev) => ({
+        ...prev,
+        [index]: { testing: true, result: null, mode },
+      }));
+      try {
+        const msg = await HttpUtil.post('/panel/xray/testOutbound', {
+          outbound: JSON.stringify(outbound),
+          allOutbounds: JSON.stringify(templateSettingsRef.current?.outbounds || []),
+          mode,
+        });
+        if (msg?.success) {
+          setOutboundTestStates((prev) => ({
+            ...prev,
+            [index]: { testing: false, result: msg.obj },
+          }));
+          return msg.obj;
+        }
+        setOutboundTestStates((prev) => ({
+          ...prev,
+          [index]: {
+            testing: false,
+            result: { success: false, error: msg?.msg || 'Unknown error', mode },
+          },
+        }));
+      } catch (e) {
+        setOutboundTestStates((prev) => ({
+          ...prev,
+          [index]: {
+            testing: false,
+            result: { success: false, error: String(e), mode },
+          },
+        }));
+      }
+      return null;
+    },
+    [],
+  );
+
+  const testAllOutbounds = useCallback(async (mode = 'tcp') => {
+    const list = templateSettingsRef.current?.outbounds || [];
+    if (list.length === 0 || testingAll) return;
+    setTestingAll(true);
+    try {
+      const concurrency = mode === 'tcp' ? 8 : 1;
+      const queue = list
+        .map((ob, i) => ({ index: i, outbound: ob }))
+        .filter(({ outbound }) => {
+          const tag = outbound?.tag;
+          const proto = outbound?.protocol;
+          if (proto === 'blackhole' || proto === 'loopback' || tag === 'blocked') return false;
+          if (mode === 'tcp' && (proto === 'freedom' || proto === 'dns')) return false;
+          return true;
+        });
+      async function worker() {
+        while (queue.length > 0) {
+          const item = queue.shift();
+          if (!item) break;
+          await testOutbound(item.index, item.outbound, mode);
+        }
+      }
+      const workers = Array.from(
+        { length: Math.min(concurrency, queue.length) },
+        () => worker(),
+      );
+      await Promise.all(workers);
+    } finally {
+      setTestingAll(false);
+    }
+  }, [testingAll, testOutbound]);
+
+  const resetToDefault = useCallback(async () => {
+    setSpinning(true);
+    try {
+      const msg = await HttpUtil.get('/panel/setting/getDefaultJsonConfig');
+      if (msg?.success) {
+        const cloned = JSON.parse(JSON.stringify(msg.obj));
+        setTemplateSettings(cloned);
+      }
+    } finally {
+      setSpinning(false);
+    }
+  }, [setTemplateSettings]);
+
+  const restartXray = useCallback(async () => {
+    setSpinning(true);
+    try {
+      const msg = await HttpUtil.post('/panel/api/server/restartXrayService');
+      if (msg?.success) {
+        await PromiseUtil.sleep(500);
+        const r = await HttpUtil.get('/panel/xray/getXrayResult');
+        if (r?.success) setRestartResult(r.obj || '');
+      }
+    } finally {
+      setSpinning(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    fetchAll();
+    fetchOutboundsTraffic();
+    const timer = window.setInterval(() => {
+      const dirtyXray = oldXraySettingRef.current !== xraySettingRef.current;
+      const dirtyUrl = oldOutboundTestUrlRef.current !== outboundTestUrlRef.current;
+      setSaveDisabled(!(dirtyXray || dirtyUrl));
+    }, DIRTY_POLL_MS);
+    return () => window.clearInterval(timer);
+  }, [fetchAll, fetchOutboundsTraffic]);
+
+  return useMemo(
+    () => ({
+      fetched,
+      spinning,
+      saveDisabled,
+      fetchError,
+      xraySetting,
+      setXraySetting,
+      templateSettings,
+      setTemplateSettings,
+      outboundTestUrl,
+      setOutboundTestUrl,
+      inboundTags,
+      clientReverseTags,
+      restartResult,
+      outboundsTraffic,
+      outboundTestStates,
+      testingAll,
+      fetchAll,
+      fetchOutboundsTraffic,
+      resetOutboundsTraffic,
+      applyOutboundsEvent,
+      testOutbound,
+      testAllOutbounds,
+      saveAll,
+      resetToDefault,
+      restartXray,
+    }),
+    [
+      fetched,
+      spinning,
+      saveDisabled,
+      fetchError,
+      xraySetting,
+      setXraySetting,
+      templateSettings,
+      setTemplateSettings,
+      outboundTestUrl,
+      setOutboundTestUrl,
+      inboundTags,
+      clientReverseTags,
+      restartResult,
+      outboundsTraffic,
+      outboundTestStates,
+      testingAll,
+      fetchAll,
+      fetchOutboundsTraffic,
+      resetOutboundsTraffic,
+      applyOutboundsEvent,
+      testOutbound,
+      testAllOutbounds,
+      saveAll,
+      resetToDefault,
+      restartXray,
+    ],
+  );
+}

frontend/src/i18n/react.ts

@@ -0,0 +1,43 @@
+import i18next from 'i18next';
+import { initReactI18next } from 'react-i18next';
+
+import { LanguageManager } from '@/utils';
+import enUS from '../../../web/translation/en-US.json';
+
+const FALLBACK = 'en-US';
+
+const lazyModules = import.meta.glob([
+  '../../../web/translation/*.json',
+  '!../../../web/translation/en-US.json',
+]);
+
+function moduleKeyFor(code: string): string {
+  return `../../../web/translation/${code}.json`;
+}
+
+let active: string = LanguageManager.getLanguage();
+if (active !== FALLBACK && !Object.prototype.hasOwnProperty.call(lazyModules, moduleKeyFor(active))) {
+  active = FALLBACK;
+}
+
+export async function readyI18n() {
+  await i18next.use(initReactI18next).init({
+    lng: active,
+    fallbackLng: FALLBACK,
+    resources: { [FALLBACK]: { translation: enUS } },
+    interpolation: { escapeValue: false, prefix: '{', suffix: '}' },
+    returnNull: false,
+  });
+  if (active !== FALLBACK) {
+    const loader = lazyModules[moduleKeyFor(active)] as (() => Promise<{ default: Record<string, unknown> }>) | undefined;
+    if (loader) {
+      const mod = await loader();
+      const messages = (mod.default ?? mod) as Record<string, unknown>;
+      i18next.addResourceBundle(active, 'translation', messages, true, true);
+      await i18next.changeLanguage(active);
+    }
+  }
+  return i18next;
+}
+
+export { i18next as i18n };

frontend/src/models/dbinbound.js

@@ -0,0 +1,191 @@
+import dayjs from 'dayjs';
+import { ObjectUtil, NumberFormatter, SizeFormatter } from '@/utils';
+import { Inbound, Protocols } from './inbound.js';
+
+export function coerceInboundJsonField(value) {
+    if (value == null) return {};
+    if (typeof value === 'object') return value;
+    if (typeof value !== 'string') return {};
+    const trimmed = value.trim();
+    if (trimmed === '') return {};
+    try {
+        return JSON.parse(trimmed);
+    } catch (_e) {
+        return {};
+    }
+}
+
+export class DBInbound {
+
+    constructor(data) {
+        this.id = 0;
+        this.userId = 0;
+        this.up = 0;
+        this.down = 0;
+        this.total = 0;
+        this.remark = "";
+        this.enable = true;
+        this.expiryTime = 0;
+        this.trafficReset = "never";
+        this.lastTrafficResetTime = 0;
+
+        this.listen = "";
+        this.port = 0;
+        this.protocol = "";
+        this.settings = "";
+        this.streamSettings = "";
+        this.tag = "";
+        this.sniffing = "";
+        this.clientStats = ""
+        // Optional FK to web/runtime registered Node. null/undefined =
+        // local panel; otherwise the inbound lives on the named node.
+        this.nodeId = null;
+        // Populated by the API when this inbound is a fallback child of
+        // a VLESS/Trojan TCP-TLS master. Shape: { masterId, path }.
+        this.fallbackParent = null;
+        if (data == null) {
+            return;
+        }
+        ObjectUtil.cloneProps(this, data);
+    }
+
+    get totalGB() {
+        return NumberFormatter.toFixed(this.total / SizeFormatter.ONE_GB, 2);
+    }
+
+    set totalGB(gb) {
+        this.total = NumberFormatter.toFixed(gb * SizeFormatter.ONE_GB, 0);
+    }
+
+    get isVMess() {
+        return this.protocol === Protocols.VMESS;
+    }
+
+    get isVLess() {
+        return this.protocol === Protocols.VLESS;
+    }
+
+    get isTrojan() {
+        return this.protocol === Protocols.TROJAN;
+    }
+
+    get isSS() {
+        return this.protocol === Protocols.SHADOWSOCKS;
+    }
+
+    get isMixed() {
+        return this.protocol === Protocols.MIXED;
+    }
+
+    get isHTTP() {
+        return this.protocol === Protocols.HTTP;
+    }
+
+    get isWireguard() {
+        return this.protocol === Protocols.WIREGUARD;
+    }
+
+    get isHysteria() {
+        return this.protocol === Protocols.HYSTERIA;
+    }
+
+    get address() {
+        let address = location.hostname;
+        if (!ObjectUtil.isEmpty(this.listen) && this.listen !== "0.0.0.0") {
+            address = this.listen;
+        }
+        return address;
+    }
+
+    get _expiryTime() {
+        if (this.expiryTime === 0) {
+            return null;
+        }
+        return dayjs(this.expiryTime);
+    }
+
+    set _expiryTime(t) {
+        if (t == null) {
+            this.expiryTime = 0;
+        } else {
+            this.expiryTime = t.valueOf();
+        }
+    }
+
+    get isExpiry() {
+        return this.expiryTime < new Date().getTime();
+    }
+
+    invalidateCache() {
+        this._cachedInbound = null;
+        this._clientStatsMap = null;
+    }
+
+    toInbound() {
+        if (this._cachedInbound) {
+            return this._cachedInbound;
+        }
+
+        const settings = coerceInboundJsonField(this.settings);
+        const streamSettings = coerceInboundJsonField(this.streamSettings);
+        const sniffing = coerceInboundJsonField(this.sniffing);
+
+        const config = {
+            port: this.port,
+            listen: this.listen,
+            protocol: this.protocol,
+            settings: settings,
+            streamSettings: streamSettings,
+            tag: this.tag,
+            sniffing: sniffing,
+            clientStats: this.clientStats,
+        };
+
+        this._cachedInbound = Inbound.fromJson(config);
+        return this._cachedInbound;
+    }
+
+    getClientStats(email) {
+        if (!this._clientStatsMap) {
+            this._clientStatsMap = new Map();
+            if (this.clientStats && Array.isArray(this.clientStats)) {
+                for (const stats of this.clientStats) {
+                    this._clientStatsMap.set(stats.email, stats);
+                }
+            }
+        }
+        return this._clientStatsMap.get(email);
+    }
+
+    isMultiUser() {
+        switch (this.protocol) {
+            case Protocols.VMESS:
+            case Protocols.VLESS:
+            case Protocols.TROJAN:
+            case Protocols.HYSTERIA:
+                return true;
+            case Protocols.SHADOWSOCKS:
+                return this.toInbound().isSSMultiUser;
+            default:
+                return false;
+        }
+    }
+
+    hasLink() {
+        switch (this.protocol) {
+            case Protocols.VMESS:
+            case Protocols.VLESS:
+            case Protocols.TROJAN:
+            case Protocols.SHADOWSOCKS:
+            case Protocols.HYSTERIA:
+                return true;
+            default:
+                return false;
+        }
+    }
+
+    genInboundLinks(remarkModel, hostOverride = '') {
+        const inbound = this.toInbound();
+        return inbound.genInboundLinks(this.remark, remarkModel, hostOverride);
+    }
+}

frontend/src/models/reality-targets.js

@@ -0,0 +1,24 @@
+// List of popular services for VLESS Reality Target/SNI randomization
+export const REALITY_TARGETS = [
+    { target: 'www.amazon.com:443', sni: 'www.amazon.com' },
+    { target: 'aws.amazon.com:443', sni: 'aws.amazon.com' },
+    { target: 'www.oracle.com:443', sni: 'www.oracle.com' },
+    { target: 'www.nvidia.com:443', sni: 'www.nvidia.com' },
+    { target: 'www.amd.com:443', sni: 'www.amd.com' },
+    { target: 'www.intel.com:443', sni: 'www.intel.com' },
+    { target: 'www.sony.com:443', sni: 'www.sony.com' }
+];
+
+/**
+ * Returns a random Reality target configuration from the predefined list
+ * @returns {Object} Object with target and sni properties
+ */
+export function getRandomRealityTarget() {
+    const randomIndex = Math.floor(Math.random() * REALITY_TARGETS.length);
+    const selected = REALITY_TARGETS[randomIndex];
+    // Return a copy to avoid reference issues
+    return {
+        target: selected.target,
+        sni: selected.sni
+    };
+}

frontend/src/models/setting.ts

@@ -0,0 +1,100 @@
+import { ObjectUtil } from '@/utils';
+
+export class AllSetting {
+  webListen = '';
+  webDomain = '';
+  webPort = 2053;
+  webCertFile = '';
+  webKeyFile = '';
+  webBasePath = '/';
+  sessionMaxAge = 360;
+  trustedProxyCIDRs = '127.0.0.1/32,::1/128';
+  pageSize = 25;
+  expireDiff = 0;
+  trafficDiff = 0;
+  remarkModel = '-ieo';
+  datepicker: 'gregorian' | 'jalalian' = 'gregorian';
+  tgBotEnable = false;
+  tgBotToken = '';
+  tgBotProxy = '';
+  tgBotAPIServer = '';
+  tgBotChatId = '';
+  tgRunTime = '@daily';
+  tgBotBackup = false;
+  tgBotLoginNotify = true;
+  tgCpu = 80;
+  tgLang = 'en-US';
+  twoFactorEnable = false;
+  twoFactorToken = '';
+  xrayTemplateConfig = '';
+  subEnable = true;
+  subJsonEnable = false;
+  subTitle = '';
+  subSupportUrl = '';
+  subProfileUrl = '';
+  subAnnounce = '';
+  subEnableRouting = true;
+  subRoutingRules = '';
+  subListen = '';
+  subPort = 2096;
+  subPath = '/sub/';
+  subJsonPath = '/json/';
+  subClashEnable = true;
+  subClashPath = '/clash/';
+  subDomain = '';
+  externalTrafficInformEnable = false;
+  externalTrafficInformURI = '';
+  restartXrayOnClientDisable = true;
+  subCertFile = '';
+  subKeyFile = '';
+  subUpdates = 12;
+  subEncrypt = true;
+  subShowInfo = true;
+  subEmailInRemark = true;
+  subURI = '';
+  subJsonURI = '';
+  subClashURI = '';
+  subJsonFragment = '';
+  subJsonNoises = '';
+  subJsonMux = '';
+  subJsonRules = '';
+
+  timeLocation = 'Local';
+
+  ldapEnable = false;
+  ldapHost = '';
+  ldapPort = 389;
+  ldapUseTLS = false;
+  ldapBindDN = '';
+  ldapPassword = '';
+  ldapBaseDN = '';
+  ldapUserFilter = '(objectClass=person)';
+  ldapUserAttr = 'mail';
+  ldapVlessField = 'vless_enabled';
+  ldapSyncCron = '@every 1m';
+  ldapFlagField = '';
+  ldapTruthyValues = 'true,1,yes,on';
+  ldapInvertFlag = false;
+  ldapInboundTags = '';
+  ldapAutoCreate = false;
+  ldapAutoDelete = false;
+  ldapDefaultTotalGB = 0;
+  ldapDefaultExpiryDays = 0;
+  ldapDefaultLimitIP = 0;
+  hasTgBotToken = false;
+  hasTwoFactorToken = false;
+  hasLdapPassword = false;
+  hasApiToken = false;
+  hasWarpSecret = false;
+  hasNordSecret = false;
+
+  constructor(data?: unknown) {
+    if (data != null) {
+      ObjectUtil.cloneProps(this, data);
+    }
+  }
+
+  equals(other: AllSetting): boolean {
+    return ObjectUtil.equals(this, other);
+  }
+}

frontend/src/models/status.ts

@@ -0,0 +1,120 @@
+import { NumberFormatter } from '@/utils';
+
+export class CurTotal {
+  current: number;
+  total: number;
+
+  constructor(current: number, total: number) {
+    this.current = current;
+    this.total = total;
+  }
+
+  get percent(): number {
+    if (this.total === 0) return 0;
+    return NumberFormatter.toFixed((this.current / this.total) * 100, 2);
+  }
+
+  get color(): string {
+    const p = this.percent;
+    if (p < 80) return '#1677ff';
+    if (p < 90) return '#faad14';
+    return '#ff4d4f';
+  }
+}
+
+const XRAY_STATE_COLORS: Record<string, string> = {
+  running: 'green',
+  stop: 'orange',
+  error: 'red',
+};
+
+export interface NetIO {
+  up: number;
+  down: number;
+}
+
+export interface NetTraffic {
+  sent: number;
+  recv: number;
+}
+
+export interface PublicIP {
+  ipv4: string | number;
+  ipv6: string | number;
+}
+
+export interface AppStats {
+  threads: number;
+  mem: number;
+  uptime: number;
+}
+
+export interface XrayInfo {
+  state: 'running' | 'stop' | 'error' | string;
+  errorMsg: string;
+  version: string;
+  color: string;
+}
+
+interface StatusInput {
+  cpu?: number;
+  cpuCores?: number;
+  logicalPro?: number;
+  cpuSpeedMhz?: number;
+  disk?: { current?: number; total?: number };
+  loads?: number[];
+  mem?: { current?: number; total?: number };
+  netIO?: NetIO;
+  netTraffic?: NetTraffic;
+  publicIP?: PublicIP;
+  swap?: { current?: number; total?: number };
+  tcpCount?: number;
+  udpCount?: number;
+  uptime?: number;
+  appUptime?: number;
+  appStats?: AppStats;
+  xray?: Partial<XrayInfo>;
+}
+
+export class Status {
+  cpu: CurTotal = new CurTotal(0, 0);
+  cpuCores = 0;
+  logicalPro = 0;
+  cpuSpeedMhz = 0;
+  disk: CurTotal = new CurTotal(0, 0);
+  loads: number[] = [0, 0, 0];
+  mem: CurTotal = new CurTotal(0, 0);
+  netIO: NetIO = { up: 0, down: 0 };
+  netTraffic: NetTraffic = { sent: 0, recv: 0 };
+  publicIP: PublicIP = { ipv4: 0, ipv6: 0 };
+  swap: CurTotal = new CurTotal(0, 0);
+  tcpCount = 0;
+  udpCount = 0;
+  uptime = 0;
+  appUptime = 0;
+  appStats: AppStats = { threads: 0, mem: 0, uptime: 0 };
+  xray: XrayInfo = { state: 'stop', errorMsg: '', version: '', color: '' };
+
+  constructor(data?: StatusInput | null) {
+    if (data == null) return;
+
+    this.cpu = new CurTotal(data.cpu ?? 0, 100);
+    this.cpuCores = data.cpuCores ?? 0;
+    this.logicalPro = data.logicalPro ?? 0;
+    this.cpuSpeedMhz = data.cpuSpeedMhz ?? 0;
+    this.disk = new CurTotal(data.disk?.current ?? 0, data.disk?.total ?? 0);
+    this.loads = (data.loads || [0, 0, 0]).map((v) => NumberFormatter.toFixed(v, 2));
+    this.mem = new CurTotal(data.mem?.current ?? 0, data.mem?.total ?? 0);
+    this.netIO = data.netIO ?? this.netIO;
+    this.netTraffic = data.netTraffic ?? this.netTraffic;
+    this.publicIP = data.publicIP ?? this.publicIP;
+    this.swap = new CurTotal(data.swap?.current ?? 0, data.swap?.total ?? 0);
+    this.tcpCount = data.tcpCount ?? 0;
+    this.udpCount = data.udpCount ?? 0;
+    this.uptime = data.uptime ?? 0;
+    this.appUptime = data.appUptime ?? 0;
+    this.appStats = data.appStats ?? this.appStats;
+    this.xray = { ...this.xray, ...(data.xray || {}) };
+    this.xray.color = XRAY_STATE_COLORS[this.xray.state] ?? 'gray';
+  }
+}

frontend/src/pages/api-docs/ApiDocsPage.css

@@ -0,0 +1,292 @@
+.api-docs-page {
+  --bg-page: #e6e8ec;
+  --bg-card: #ffffff;
+  min-height: 100vh;
+  background: var(--bg-page);
+}
+
+.api-docs-page.is-dark {
+  --bg-page: #1a1b1f;
+  --bg-card: #23252b;
+}
+
+.api-docs-page.is-dark.is-ultra {
+  --bg-page: #000;
+  --bg-card: #101013;
+}
+
+.api-docs-page .content-shell {
+  background: var(--bg-page);
+}
+
+.api-docs-page .content-area {
+  padding: 24px;
+  max-width: 100%;
+}
+
+@media (max-width: 768px) {
+  .api-docs-page .content-area {
+    padding: 16px 12px 12px;
+    padding-top: 64px;
+  }
+}
+
+.docs-wrapper {
+  max-width: 1100px;
+  margin: 0 auto;
+}
+
+.docs-header {
+  margin-bottom: 20px;
+  padding: 24px;
+  background: var(--bg-card);
+  border: 1px solid rgba(128, 128, 128, 0.12);
+  border-radius: 10px;
+}
+
+.docs-title {
+  font-size: 28px;
+  font-weight: 800;
+  margin: 0 0 8px;
+  color: rgba(0, 0, 0, 0.88);
+  letter-spacing: -0.3px;
+}
+
+.docs-lead {
+  margin: 0;
+  color: rgba(0, 0, 0, 0.65);
+  line-height: 1.65;
+  font-size: 14px;
+}
+
+.docs-lead code,
+.token-hint code {
+  background: rgba(128, 128, 128, 0.12);
+  padding: 1px 6px;
+  border-radius: 4px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 12.5px;
+}
+
+.token-card,
+.curl-card {
+  margin-bottom: 16px;
+}
+
+.token-card-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  flex-wrap: wrap;
+  margin-bottom: 10px;
+  min-height: 32px;
+}
+
+.token-card-title {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  font-weight: 600;
+  font-size: 14px;
+}
+
+.token-hint {
+  margin: 10px 0 0;
+  color: rgba(0, 0, 0, 0.55);
+  font-size: 12.5px;
+  line-height: 1.55;
+}
+
+.toolbar {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+  margin-bottom: 16px;
+}
+
+.search-bar {
+  flex: 1;
+  min-width: 200px;
+  max-width: 480px;
+}
+
+.match-count {
+  font-size: 12px;
+  color: rgba(0, 0, 0, 0.5);
+  white-space: nowrap;
+}
+
+.toc-nav {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  gap: 8px 12px;
+  padding: 12px 16px;
+  background: var(--bg-card);
+  border: 1px solid rgba(128, 128, 128, 0.12);
+  border-radius: 8px;
+  margin-bottom: 16px;
+}
+
+.toc-label {
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.6px;
+  color: rgba(0, 0, 0, 0.5);
+  padding-top: 3px;
+  flex-shrink: 0;
+}
+
+.toc-links {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+
+.toc-link {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  padding: 4px 10px;
+  border-radius: 20px;
+  font-size: 12.5px;
+  color: rgba(0, 0, 0, 0.65);
+  background: rgba(128, 128, 128, 0.06);
+  border: 1px solid transparent;
+  text-decoration: none;
+  cursor: pointer;
+  transition: all 0.2s;
+  white-space: nowrap;
+}
+
+.toc-link:hover {
+  background: rgba(22, 119, 255, 0.08);
+  color: #1677ff;
+  border-color: rgba(22, 119, 255, 0.2);
+}
+
+.toc-link.active {
+  background: rgba(22, 119, 255, 0.12);
+  color: #1677ff;
+  border-color: rgba(22, 119, 255, 0.3);
+  font-weight: 600;
+}
+
+.toc-icon {
+  font-size: 13px;
+  opacity: 0.8;
+}
+
+.toc-text {
+  font-size: 12.5px;
+}
+
+.toc-badge {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 18px;
+  height: 18px;
+  padding: 0 5px;
+  border-radius: 9px;
+  font-size: 10.5px;
+  font-weight: 700;
+  background: rgba(22, 119, 255, 0.12);
+  color: #1677ff;
+  line-height: 1;
+}
+
+.toc-link.active .toc-badge {
+  background: #1677ff;
+  color: #fff;
+}
+
+body.dark .docs-title {
+  color: rgba(255, 255, 255, 0.92);
+}
+
+html[data-theme='ultra-dark'] .docs-title {
+  color: rgba(255, 255, 255, 0.95);
+}
+
+body.dark .docs-header {
+  background: #252526;
+  border-color: rgba(255, 255, 255, 0.08);
+}
+
+html[data-theme='ultra-dark'] .docs-header {
+  background: #0a0a0a;
+  border-color: rgba(255, 255, 255, 0.06);
+}
+
+body.dark .docs-lead,
+body.dark .token-hint {
+  color: rgba(255, 255, 255, 0.7);
+}
+
+html[data-theme='ultra-dark'] .docs-lead,
+html[data-theme='ultra-dark'] .token-hint {
+  color: rgba(255, 255, 255, 0.75);
+}
+
+body.dark .docs-lead code,
+body.dark .token-hint code {
+  background: rgba(255, 255, 255, 0.1);
+}
+
+html[data-theme='ultra-dark'] .docs-lead code,
+html[data-theme='ultra-dark'] .token-hint code {
+  background: rgba(255, 255, 255, 0.12);
+}
+
+body.dark .toc-nav {
+  background: #252526;
+  border-color: rgba(255, 255, 255, 0.08);
+}
+
+html[data-theme='ultra-dark'] .toc-nav {
+  background: #0a0a0a;
+  border-color: rgba(255, 255, 255, 0.06);
+}
+
+body.dark .toc-label {
+  color: rgba(255, 255, 255, 0.55);
+}
+
+html[data-theme='ultra-dark'] .toc-label {
+  color: rgba(255, 255, 255, 0.6);
+}
+
+body.dark .toc-link {
+  color: rgba(255, 255, 255, 0.65);
+  background: rgba(255, 255, 255, 0.06);
+}
+
+html[data-theme='ultra-dark'] .toc-link {
+  background: rgba(255, 255, 255, 0.04);
+}
+
+body.dark .toc-link:hover {
+  background: rgba(88, 166, 255, 0.12);
+  color: #58a6ff;
+  border-color: rgba(88, 166, 255, 0.25);
+}
+
+body.dark .toc-link.active {
+  background: rgba(88, 166, 255, 0.15);
+  color: #58a6ff;
+  border-color: rgba(88, 166, 255, 0.35);
+}
+
+body.dark .toc-badge {
+  background: rgba(88, 166, 255, 0.15);
+  color: #58a6ff;
+}
+
+body.dark .toc-link.active .toc-badge {
+  background: #58a6ff;
+  color: #0d1117;
+}

frontend/src/pages/api-docs/ApiDocsPage.tsx

@@ -0,0 +1,247 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import type { ComponentType, MouseEvent } from 'react';
+import { Button, Card, ConfigProvider, Input, Layout, Space } from 'antd';
+import {
+  ApiOutlined,
+  CloudServerOutlined,
+  ClusterOutlined,
+  CompressOutlined,
+  ExpandOutlined,
+  GlobalOutlined,
+  KeyOutlined,
+  LinkOutlined,
+  NodeIndexOutlined,
+  SafetyCertificateOutlined,
+  SaveOutlined,
+  SearchOutlined,
+  SettingOutlined,
+  WifiOutlined,
+} from '@ant-design/icons';
+
+import { useTheme } from '@/hooks/useTheme';
+import AppSidebar from '@/components/AppSidebar';
+import { sections as allSections } from './endpoints.js';
+import EndpointSection from './EndpointSection';
+import type { Section } from './EndpointSection';
+import CodeBlock from './CodeBlock';
+import '@/styles/page-cards.css';
+import './ApiDocsPage.css';
+
+const sectionIcons: Record<string, ComponentType<{ className?: string }>> = {
+  authentication: SafetyCertificateOutlined,
+  inbounds: NodeIndexOutlined,
+  server: CloudServerOutlined,
+  nodes: ClusterOutlined,
+  'custom-geo': GlobalOutlined,
+  backup: SaveOutlined,
+  settings: SettingOutlined,
+  'api-tokens': KeyOutlined,
+  'xray-settings': WifiOutlined,
+  subscription: LinkOutlined,
+  websocket: ApiOutlined,
+};
+
+const curlExample = `curl -X GET \\
+  -H "Authorization: Bearer YOUR_API_TOKEN" \\
+  -H "Accept: application/json" \\
+  https://your-panel.example.com/panel/api/inbounds/list`;
+
+const basePath = window.X_UI_BASE_PATH || '';
+const requestUri = window.location.pathname;
+const settingsHref = `${basePath}panel/settings#security`;
+
+const endpointCount = (allSections as Section[]).reduce(
+  (sum, s) => sum + s.endpoints.length,
+  0,
+);
+
+export default function ApiDocsPage() {
+  const { isDark, isUltra, antdThemeConfig } = useTheme();
+
+  const [searchQuery, setSearchQuery] = useState('');
+  const [collapsedSections, setCollapsedSections] = useState<Set<string>>(() => new Set());
+  const [activeSection, setActiveSection] = useState('');
+
+  const sections = useMemo<Section[]>(() => {
+    const q = searchQuery.toLowerCase().trim();
+    if (!q) return allSections as Section[];
+    return (allSections as Section[])
+      .map((s) => ({
+        ...s,
+        endpoints: s.endpoints.filter((e) =>
+          e.path.toLowerCase().includes(q)
+          || e.summary?.toLowerCase().includes(q)
+          || e.method.toLowerCase().includes(q),
+        ),
+      }))
+      .filter((s) => s.endpoints.length > 0);
+  }, [searchQuery]);
+
+  const visibleEndpoints = useMemo(
+    () => sections.reduce((sum, s) => sum + s.endpoints.length, 0),
+    [sections],
+  );
+
+  const toggleSection = useCallback((id: string) => {
+    setCollapsedSections((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) next.delete(id); else next.add(id);
+      return next;
+    });
+  }, []);
+
+  const expandAll = useCallback(() => setCollapsedSections(new Set()), []);
+  const collapseAll = useCallback(
+    () => setCollapsedSections(new Set((allSections as Section[]).map((s) => s.id))),
+    [],
+  );
+
+  const scrollToSection = useCallback((id: string) => (e: MouseEvent) => {
+    e.preventDefault();
+    const el = document.getElementById(id);
+    if (!el) return;
+    el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    if (window.location.hash !== `#${id}`) {
+      history.replaceState(null, '', `#${id}`);
+    }
+  }, []);
+
+  useEffect(() => {
+    const onHashChange = () => {
+      const id = window.location.hash.slice(1);
+      if (!id) return;
+      const el = document.getElementById(id);
+      if (el) el.scrollIntoView({ behavior: 'auto', block: 'start' });
+    };
+    requestAnimationFrame(onHashChange);
+    window.addEventListener('hashchange', onHashChange);
+    return () => window.removeEventListener('hashchange', onHashChange);
+  }, []);
+
+  useEffect(() => {
+    const onScroll = () => {
+      const toc = document.querySelector('.toc-nav');
+      const tocHeight = toc instanceof HTMLElement ? toc.offsetHeight : 56;
+      let current = '';
+      for (const s of sections) {
+        const el = document.getElementById(s.id);
+        if (!el) continue;
+        const rect = el.getBoundingClientRect();
+        if (rect.top <= tocHeight + 20) {
+          current = s.id;
+        }
+      }
+      setActiveSection(current);
+    };
+    window.addEventListener('scroll', onScroll, { passive: true });
+    requestAnimationFrame(onScroll);
+    return () => window.removeEventListener('scroll', onScroll);
+  }, [sections]);
+
+  const pageClass = useMemo(() => {
+    const classes = ['api-docs-page'];
+    if (isDark) classes.push('is-dark');
+    if (isUltra) classes.push('is-ultra');
+    return classes.join(' ');
+  }, [isDark, isUltra]);
+
+  return (
+    <ConfigProvider theme={antdThemeConfig}>
+      <Layout className={pageClass}>
+        <AppSidebar basePath={basePath} requestUri={requestUri} />
+
+        <Layout className="content-shell">
+          <Layout.Content className="content-area">
+            <div className="docs-wrapper">
+              <header className="docs-header">
+                <h1 className="docs-title">API Documentation</h1>
+                <p className="docs-lead">
+                  The 3x-ui panel exposes a REST API under <code>/panel/api/</code>. Authenticate with the panel session
+                  cookie, or with the <code>Authorization: Bearer &lt;token&gt;</code> header below. Every endpoint
+                  returns a uniform <code>{'{ success, msg, obj }'}</code> envelope unless otherwise noted.
+                </p>
+              </header>
+
+              <Card className="token-card" size="small">
+                <div className="token-card-head">
+                  <div className="token-card-title">
+                    <KeyOutlined />
+                    <span>API Tokens</span>
+                  </div>
+                  <Button type="primary" size="small" href={settingsHref}>
+                    Manage tokens
+                  </Button>
+                </div>
+                <p className="token-hint">
+                  Create, enable, or revoke named Bearer tokens in{' '}
+                  <a href={settingsHref}>Settings → Security</a>. Send each request as{' '}
+                  <code>Authorization: Bearer &lt;token&gt;</code>. Token-authenticated callers skip CSRF and don&apos;t
+                  need a session cookie. Deleting a token revokes it immediately — running bots will need a new one.
+                </p>
+              </Card>
+
+              <Card className="curl-card" size="small" title="Quick example">
+                <CodeBlock code={curlExample} lang="text" />
+              </Card>
+
+              <div className="toolbar">
+                <Input
+                  className="search-bar"
+                  prefix={<SearchOutlined />}
+                  placeholder="Search endpoints by path, method, or description…"
+                  allowClear
+                  value={searchQuery}
+                  onChange={(e) => setSearchQuery(e.target.value)}
+                />
+                {searchQuery && (
+                  <span className="match-count">
+                    {visibleEndpoints} / {endpointCount} endpoints
+                  </span>
+                )}
+                <Space size="small">
+                  <Button size="small" icon={<ExpandOutlined />} onClick={expandAll}>
+                    Expand all
+                  </Button>
+                  <Button size="small" icon={<CompressOutlined />} onClick={collapseAll}>
+                    Collapse all
+                  </Button>
+                </Space>
+              </div>
+
+              <nav className="toc-nav">
+                <span className="toc-label">On this page:</span>
+                <div className="toc-links">
+                  {sections.map((s) => {
+                    const Icon = sectionIcons[s.id];
+                    return (
+                      <a
+                        key={s.id}
+                        className={`toc-link${activeSection === s.id ? ' active' : ''}`}
+                        href={`#${s.id}`}
+                        onClick={scrollToSection(s.id)}
+                      >
+                        {Icon && <Icon />}
+                        <span className="toc-text">{s.title}</span>
+                        <span className="toc-badge">{s.endpoints.length}</span>
+                      </a>
+                    );
+                  })}
+                </div>
+              </nav>
+
+              {sections.map((s) => (
+                <EndpointSection
+                  key={s.id}
+                  section={s}
+                  icon={sectionIcons[s.id]}
+                  collapsed={collapsedSections.has(s.id)}
+                  onToggle={() => toggleSection(s.id)}
+                />
+              ))}
+            </div>
+          </Layout.Content>
+        </Layout>
+      </Layout>
+    </ConfigProvider>
+  );
+}

frontend/src/pages/api-docs/CodeBlock.css

@@ -0,0 +1,107 @@
+.code-block-wrapper {
+  position: relative;
+  border-radius: 6px;
+  overflow: hidden;
+  border: 1px solid rgba(128, 128, 128, 0.15);
+}
+
+.code-toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 4px 8px;
+  background: rgba(128, 128, 128, 0.06);
+  border-bottom: 1px solid rgba(128, 128, 128, 0.1);
+}
+
+.lang-badge {
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: 0.5px;
+  color: rgba(0, 0, 0, 0.4);
+  text-transform: uppercase;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+
+.copy-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 26px;
+  height: 26px;
+  border: 1px solid rgba(128, 128, 128, 0.15);
+  border-radius: 4px;
+  background: rgba(255, 255, 255, 0.7);
+  color: rgba(0, 0, 0, 0.45);
+  cursor: pointer;
+  font-size: 12px;
+  transition: all 0.15s;
+}
+
+.copy-btn:hover {
+  background: #fff;
+  color: #1677ff;
+  border-color: #1677ff;
+}
+
+.copy-btn.copied {
+  background: #52c41a;
+  color: #fff;
+  border-color: #52c41a;
+}
+
+.code-block {
+  background: rgba(128, 128, 128, 0.04);
+  padding: 10px 12px;
+  margin: 0;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 12.5px;
+  line-height: 1.6;
+  white-space: pre-wrap;
+  word-break: break-word;
+  overflow-x: auto;
+  border: none;
+  border-radius: 0;
+}
+
+.json-key { color: #0550ae; }
+.json-string { color: #116329; }
+.json-number { color: #9a6700; }
+.json-boolean { color: #cf222e; }
+.json-null { color: #8250df; }
+
+body.dark .code-block-wrapper {
+  border-color: rgba(255, 255, 255, 0.1);
+}
+
+body.dark .code-toolbar {
+  background: rgba(255, 255, 255, 0.03);
+  border-color: rgba(255, 255, 255, 0.06);
+}
+
+body.dark .lang-badge {
+  color: rgba(255, 255, 255, 0.4);
+}
+
+body.dark .code-block {
+  background: rgba(255, 255, 255, 0.03);
+  color: rgba(255, 255, 255, 0.88);
+}
+
+body.dark .json-key { color: #79c0ff; }
+body.dark .json-string { color: #7ee787; }
+body.dark .json-number { color: #d29922; }
+body.dark .json-boolean { color: #ff7b72; }
+body.dark .json-null { color: #d2a8ff; }
+
+body.dark .copy-btn {
+  background: rgba(255, 255, 255, 0.06);
+  color: rgba(255, 255, 255, 0.45);
+  border-color: rgba(255, 255, 255, 0.12);
+}
+
+body.dark .copy-btn:hover {
+  background: rgba(255, 255, 255, 0.1);
+  color: #58a6ff;
+  border-color: #58a6ff;
+}

frontend/src/pages/api-docs/CodeBlock.tsx

@@ -0,0 +1,69 @@
+import { useMemo, useState } from 'react';
+import { message } from 'antd';
+import { CheckOutlined, CopyOutlined } from '@ant-design/icons';
+import { ClipboardManager } from '@/utils';
+import './CodeBlock.css';
+
+interface CodeBlockProps {
+  code?: string;
+  lang?: string;
+}
+
+function escapeHtml(str: string): string {
+  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function highlightJson(str: string): string {
+  const escaped = escapeHtml(str);
+  return escaped.replace(
+    /("(?:[^"\\]|\\.)*")\s*(:)|("(?:[^"\\]|\\.)*")|(-?\d+\.?\d*(?:[eE][+-]?\d+)?)\b|(true|false)|(null)|([{}[\]])/g,
+    (_m, key, colon, string, number, bool, nil) => {
+      if (colon) return `<span class="json-key">${key}</span>${colon}`;
+      if (string) return `<span class="json-string">${string}</span>`;
+      if (number) return `<span class="json-number">${number}</span>`;
+      if (bool) return `<span class="json-boolean">${bool}</span>`;
+      if (nil) return `<span class="json-null">${nil}</span>`;
+      return _m;
+    },
+  );
+}
+
+export default function CodeBlock({ code = '', lang = 'json' }: CodeBlockProps) {
+  const [copied, setCopied] = useState(false);
+  const [messageApi, messageContextHolder] = message.useMessage();
+
+  const highlighted = useMemo(
+    () => (lang === 'json' ? highlightJson(code) : escapeHtml(code)),
+    [code, lang],
+  );
+
+  async function copyCode() {
+    const ok = await ClipboardManager.copyText(code);
+    if (ok) {
+      setCopied(true);
+      messageApi.success('Copied');
+      window.setTimeout(() => setCopied(false), 2000);
+    } else {
+      messageApi.error('Copy failed');
+    }
+  }
+
+  return (
+    <div className="code-block-wrapper">
+      {messageContextHolder}
+      <div className="code-toolbar">
+        <span className="lang-badge">{lang.toUpperCase()}</span>
+        <button
+          className={`copy-btn${copied ? ' copied' : ''}`}
+          onClick={copyCode}
+          title={copied ? 'Copied' : 'Copy'}
+        >
+          {copied ? <CheckOutlined /> : <CopyOutlined />}
+        </button>
+      </div>
+      <pre className={`code-block lang-${lang}`}>
+        <code dangerouslySetInnerHTML={{ __html: highlighted }} />
+      </pre>
+    </div>
+  );
+}

frontend/src/pages/api-docs/EndpointRow.css

@@ -0,0 +1,93 @@
+.endpoint-row {
+  padding: 14px 8px;
+  margin: 0 -8px;
+  transition: background 0.15s;
+  border-radius: 6px;
+}
+
+.endpoint-row:hover {
+  background: rgba(128, 128, 128, 0.03);
+}
+
+.endpoint-row + .endpoint-row {
+  border-top: 1px solid rgba(128, 128, 128, 0.1);
+}
+
+.endpoint-header {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+
+.method-tag {
+  font-weight: 700;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 11px;
+  letter-spacing: 0.5px;
+  min-width: 56px;
+  text-align: center;
+  text-transform: uppercase;
+  border-radius: 4px;
+  padding: 2px 8px;
+  line-height: 1.6;
+}
+
+.endpoint-path {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 13.5px;
+  word-break: break-all;
+  color: rgba(0, 0, 0, 0.8);
+  background: rgba(128, 128, 128, 0.06);
+  padding: 2px 8px;
+  border-radius: 4px;
+}
+
+.endpoint-summary {
+  margin: 8px 0 0;
+  color: rgba(0, 0, 0, 0.6);
+  line-height: 1.6;
+  font-size: 13.5px;
+}
+
+.endpoint-block {
+  margin-top: 14px;
+}
+
+.block-label {
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.6px;
+  color: rgba(0, 0, 0, 0.45);
+  margin-bottom: 6px;
+}
+
+.error-label {
+  color: #cf222e;
+}
+
+body.dark .endpoint-row:hover {
+  background: rgba(255, 255, 255, 0.02);
+}
+
+body.dark .endpoint-row + .endpoint-row {
+  border-top-color: rgba(255, 255, 255, 0.08);
+}
+
+body.dark .endpoint-path {
+  color: rgba(255, 255, 255, 0.82);
+  background: rgba(255, 255, 255, 0.05);
+}
+
+body.dark .endpoint-summary {
+  color: rgba(255, 255, 255, 0.65);
+}
+
+body.dark .block-label {
+  color: rgba(255, 255, 255, 0.45);
+}
+
+body.dark .error-label {
+  color: #ff7b72;
+}

frontend/src/pages/api-docs/EndpointRow.tsx

@@ -0,0 +1,84 @@
+import { Table, Tag } from 'antd';
+import type { ColumnsType } from 'antd/es/table';
+import { methodColors, safeInlineHtml } from './endpoints.js';
+import CodeBlock from './CodeBlock';
+import './EndpointRow.css';
+
+interface Param {
+  name: string;
+  in?: string;
+  type?: string;
+  desc?: string;
+}
+
+export interface Endpoint {
+  method: string;
+  path: string;
+  summary?: string;
+  params?: Param[];
+  body?: string;
+  response?: string;
+  errorResponse?: string;
+}
+
+const paramColumns: ColumnsType<Param> = [
+  { title: 'Name', dataIndex: 'name', key: 'name', width: 180 },
+  { title: 'In', dataIndex: 'in', key: 'in', width: 100 },
+  { title: 'Type', dataIndex: 'type', key: 'type', width: 120 },
+  { title: 'Description', dataIndex: 'desc', key: 'desc' },
+];
+
+export default function EndpointRow({ endpoint }: { endpoint: Endpoint }) {
+  const tagColor = (methodColors as Record<string, string>)[endpoint.method] || 'default';
+  const hasParams = Array.isArray(endpoint.params) && endpoint.params.length > 0;
+
+  return (
+    <div className="endpoint-row">
+      <div className="endpoint-header">
+        <Tag color={tagColor} className="method-tag">{endpoint.method}</Tag>
+        <code className="endpoint-path">{endpoint.path}</code>
+      </div>
+
+      {endpoint.summary && (
+        <p
+          className="endpoint-summary"
+          dangerouslySetInnerHTML={{ __html: safeInlineHtml(endpoint.summary) }}
+        />
+      )}
+
+      {hasParams && (
+        <div className="endpoint-block">
+          <div className="block-label">Parameters</div>
+          <Table
+            columns={paramColumns}
+            dataSource={endpoint.params}
+            pagination={false}
+            size="small"
+            rowKey="name"
+          />
+        </div>
+      )}
+
+      {endpoint.body && (
+        <div className="endpoint-block">
+          <div className="block-label">Request body</div>
+          <CodeBlock code={endpoint.body} lang="json" />
+        </div>
+      )}
+
+      {endpoint.response && (
+        <div className="endpoint-block">
+          <div className="block-label">Response</div>
+          <CodeBlock code={endpoint.response} lang="json" />
+        </div>
+      )}
+
+      {endpoint.errorResponse && (
+        <div className="endpoint-block">
+          <div className="block-label error-label">Error response</div>
+          <CodeBlock code={endpoint.errorResponse} lang="json" />
+        </div>
+      )}
+    </div>
+  );
+}