3x-ui/PANEL_GUIDE_SOURCE_OF_TRUTH.md

3x-ui Panel Deep Guide (Source of Truth)

Scope and trust model

This document is built from:

• Official project wiki pages cloned from https://github.com/MHSanaei/3x-ui.wiki.git.
• Source code in this repository (MHSanaei/3x-ui, current local main).
• Live panel inspection against your running instance via Playwright.

This is intended to be a practical source of truth for operating the panel.

Important constraints:

• The panel evolves quickly; always re-check against current code/wiki before risky production changes.
• Some behavior differs by version, settings, and enabled modules (Telegram, LDAP, Fail2Ban, subscription JSON).

---

1. What 3x-ui is

3x-ui is a web control panel around Xray-core. It manages:

• Inbounds and client accounts.
• Traffic/expiry limits and stats.
• Xray config template editing and advanced routing/outbound controls.
• Operational actions (restart Xray, logs, geofile updates, DB export/import).
• Optional subscription service (links and JSON endpoint).
• Optional Telegram bot features.

---

2. Runtime architecture

2.1 Core processes

The binary starts two servers:

• Web panel server (UI + panel API).
• Subscription server (separate listener/path logic).

Code references:

• main.go boot and signal handling.
• web/web.go panel server setup.
• sub/sub.go subscription server setup.

2.2 Data layer

Persistent data is SQLite (GORM). Default models auto-migrated at startup:

• User
• Inbound
• OutboundTraffics
• Setting
• InboundClientIps
• xray.ClientTraffic
• HistoryOfSeeders

Code references:

• database/db.go
• database/model/model.go
• xray/client_traffic.go

2.3 Session/auth model

• Session cookie store is configured with secret from settings.
• Cookie is HttpOnly, SameSite=Lax, max age based on sessionMaxAge.
• Panel routes under /panel require login session.
• API routes under /panel/api also require session; unauthorized API returns 404 (not 401) to hide endpoint existence.

Code references:

• web/web.go (session setup)
• web/session/session.go
• web/controller/xui.go and web/controller/api.go

2.4 Scheduler/background jobs

Panel cron jobs include:

• Xray running check: every 1s.
• Conditional Xray restart pass: every 30s.
• Traffic pull from Xray API: every 10s (after initial delay).
• Client IP checks: every 10s.
• Log cleanup: daily.
• Periodic traffic reset: daily/weekly/monthly.
• LDAP sync: configurable cron, when enabled.
• Telegram stats notify: configurable cron, when enabled.
• Hash storage cleanup: every 2m (Telegram callbacks).
• CPU threshold monitor: every 10s (Telegram feature).

Code references:

• web/web.go
• web/job/*.go

---

3. URL topology and route map

With default base path /, main user-facing URLs are:

• Login: /
• Panel pages: /panel/, /panel/inbounds, /panel/settings, /panel/xray
• Panel APIs: /panel/api/...

If webBasePath changes, the entire panel path is prefixed.

3.1 UI routes

Code references:

• web/controller/index.go

• web/controller/xui.go

• GET / login page (or redirects to panel/ when already logged in).

• POST /login

• GET /logout

• POST /getTwoFactorEnable

• GET /panel/

• GET /panel/inbounds

• GET /panel/settings

• GET /panel/xray

3.2 API routes (panel)

Code references:

• web/controller/api.go
• web/controller/inbound.go
• web/controller/server.go
• web/controller/setting.go
• web/controller/xray_setting.go

Main groups:

• /panel/api/inbounds/*
• /panel/api/server/*
• /panel/setting/*
• /panel/xray/*
• /panel/api/backuptotgbot

(See sections 8 and 9 for functional behavior per group.)

3.3 Subscription service routes

Code references:

• sub/sub.go
• sub/subController.go

Routes are dynamic based on settings:

• Link path: {subPath}:subid
• JSON path (if enabled): {subJsonPath}:subid

Defaults are typically /sub/ and /json/ style paths.

---

4. Live instance findings (from your panel)

Observed in your current running panel:

• Version shown: v2.8.10.
• Xray shown running.
• Inbounds page has 2 active VLESS+Reality inbounds on ports 443 and 8443.
• Security warnings active:
  • Panel connection not secure (TLS missing).
  • Panel path appears default/weak.
  • Subscription path appears default/weak.

This confirms panel behavior matches code/wiki defaults and hardening alerts.

---

5. Page-by-page guide

5.1 Overview page

Purpose:

• Operational dashboard for server + Xray + quick management actions.

Typical widgets/actions:

• CPU/RAM/Swap/Storage stats.
• Xray state with Stop / Restart actions.
• Current Xray version and switch/update actions.
• Logs, config, backup shortcuts.
• Uptime and traffic/speed totals.
• IP info, connection stats.

Backed by:

• server.status and related API endpoints.
• WebSocket status broadcasts.

Code references:

• web/controller/server.go
• web/service/server.go
• web/websocket/*

5.2 Inbounds page

Purpose:

• Manage listeners and user clients.

Core capabilities:

• Add/edit/delete inbounds.
• Enable/disable inbound.
• Add/edit/delete clients.
• Bulk client add.
• Reset traffic (single client, per inbound, global).
• Remove depleted clients.
• Import inbound.
• Export URLs/subscription URLs/inbound template.
• Search/filter and online/last-online checks.

Live menu entries seen in your panel include:

• Edit
• Add Client
• Add Bulk
• Reset Clients Traffic
• Export All URLs
• Export All URLs - Subscription
• Delete Depleted Clients
• Export Inbound
• Reset Traffic
• Clone
• Delete

Implementation notes:

• Changes are persisted to DB, and for enabled inbounds/clients are mirrored via Xray API when possible.
• For certain changes, needRestart path is set and picked up by scheduler.
• Traffic accounting is updated from periodic Xray traffic pulls.

Code references:

• web/controller/inbound.go
• web/service/inbound.go
• web/service/xray.go

5.3 Panel Settings page

Top tabs (observed + source):

• General
• Authentication
• Telegram Bot
• Subscription

General

What it controls:

• Listen IP/domain/port for panel.
• Panel URI path (webBasePath).
• Session duration.
• Pagination size.
• Language.
• Additional collapsible areas: notifications, certificates, external traffic, date/time, LDAP.

Why critical:

• Port/path/domain/listen are core attack-surface controls.

Authentication

What it controls:

• Admin credential change (current/new username/password).
• Two-factor authentication section.

Behavior:

• Update verifies old credentials first.
• Passwords are hashed (bcrypt).

Telegram Bot

What it controls:

• Enable/disable bot.
• Bot token.
• Admin chat IDs.
• Notification cadence/language.
• Additional bot notification/proxy/server settings.

Capabilities documented and implemented:

• Periodic reports.
• Login notify.
• CPU/load notify.
• Backup delivery.
• Client lookup/report flows.

Subscription

What it controls:

• Subscription service enable.
• JSON subscription endpoint enable.
• Listen IP/domain/port.
• URI paths for link/json endpoints.
• Encryption/show-info/update interval/title/support/announce.
• Routing headers integration settings.

Behavior notes:

• Subscription server can run with separate certs/keys.
• Headers like Subscription-Userinfo, profile metadata, and routing hints can be returned.

Code references:

• web/controller/setting.go
• web/service/setting.go
• sub/sub.go
• sub/subController.go

5.4 Xray Configs page

Top tabs (observed):

• Basics
• Routing Rules
• Outbounds
• Reverse
• Balancers
• DNS
• Advanced

Basics

Controls global xray behavior such as:

• General runtime strategies.
• Statistics/log/general options.
• Outbound test URL used for test-outbound checks.

Routing Rules

Defines how traffic is routed (domain/ip/network/rule matching, outbound tags). Used for use-cases like WARP/TOR steering.

Outbounds

Manages outbound objects and stats. Features include:

• Add/edit/delete outbound.
• WARP creation/registration hooks.
• Outbound traffic reset.
• Outbound connectivity test (using server-controlled test URL).

Reverse/Balancers/DNS

Advanced xray building blocks exposed in UI for complex routing topologies.

Advanced

Raw template-centric advanced xray config editing. Final generated config derives from template + panel-managed entities.

Safety note:

• Invalid advanced edits can break xray start; keep recovery path (default/reset) ready.

Code references:

• web/controller/xray_setting.go
• web/service/xray_setting.go
• web/service/outbound.go
• web/service/warp.go
• web/service/xray.go

---

6. Subscription service deep behavior

The subscription server:

• Is independent from panel UI server.
• Reads dedicated subscription settings.
• Supports optional domain enforcement.
• Supports link and JSON endpoints.
• Supports base64 response mode for subscription links.
• Can render HTML subscription page when requested by browser/flags.
• Emits metadata headers (Subscription-Userinfo, update interval, profile headers, routing headers).

Code references:

• sub/sub.go
• sub/subController.go
• sub/subService.go
• sub/subJsonService.go

---

7. Settings catalog (important keys)

Default key space includes panel, xray, telegram, subscription, ldap, and feature toggles. Key examples:

• Panel: webListen, webDomain, webPort, webCertFile, webKeyFile, webBasePath, sessionMaxAge.
• Security/auth: secret, twoFactorEnable, twoFactorToken.
• Xray: xrayTemplateConfig, xrayOutboundTestUrl.
• Telegram: tgBotEnable, tgBotToken, tgBotChatId, tgRunTime, tgCpu, etc.
• Subscription: subEnable, subJsonEnable, subPort, subPath, subJsonPath, subEncrypt, subUpdates, etc.
• LDAP: multiple ldap* keys.

Code references:

• web/service/setting.go default map and getters/setters.

---

8. API behavior guide

8.1 Auth

• Login endpoint creates session cookie.
• API requires valid session.
• Unauthenticated API calls return 404 by design.

Code references:

• web/controller/index.go
• web/controller/api.go

8.2 Inbounds API

Base path: /panel/api/inbounds

Functions:

• Read inbounds/client traffics.
• CRUD inbound.
• CRUD inbound clients.
• Reset traffic operations.
• Import inbound.
• Online/last-online queries.
• IP tracking/cleanup.

Code reference:

• web/controller/inbound.go

8.3 Server API

Base path: /panel/api/server

Functions:

• Status and CPU history.
• Xray version listing/install.
• Geofile updates.
• Logs and xray logs retrieval.
• Config and DB export.
• DB import.
• Utility key generators (UUID, X25519, ML-DSA-65, ML-KEM-768, VLESS keys, ECH cert).

Code reference:

• web/controller/server.go

8.4 Xray settings API

Base path: /panel/xray

Functions:

• Read/update xray template + outbound test URL.
• Get xray result text.
• Get/reset outbound traffic.
• Warp actions (data, del, config, reg, license).
• Test outbound endpoint.

Code reference:

• web/controller/xray_setting.go

8.5 Panel settings API

Base path: /panel/setting

Functions:

• Get all settings.
• Get default settings.
• Update settings.
• Update user credentials.
• Restart panel.
• Get default xray JSON config.

Code reference:

• web/controller/setting.go

---

9. CLI and admin script operations

9.1 Binary subcommands (x-ui binary)

From main.go:

• run
• migrate
• setting (reset/show/port/user/password/basepath/listenIP/cert flags/telegram flags)
• cert

Useful flag examples:

• x-ui setting -show true
• x-ui setting -port 2053
• x-ui setting -webBasePath /random-path/
• x-ui setting -username <u> -password <p>
• x-ui setting -resetTwoFactor true
• x-ui cert -webCert <fullchain.pem> -webCertKey <privkey.pem>

9.2 Menu/admin shell script (x-ui.sh)

Top-level menu includes:

• Install/update/uninstall/legacy.
• Reset credentials/base path/settings.
• Port change and current settings display.
• Start/stop/restart/status/log management.
• Autostart toggles.
• SSL management (ACME, Cloudflare, set cert paths).
• IP limit/Fail2Ban management.
• Firewall management.
• SSH port-forwarding helper.
• BBR, geofile update, speedtest.

Script subcommands include:

• x-ui start|stop|restart|status|settings|enable|disable|log|banlog|update|legacy|install|uninstall|update-all-geofiles

Code reference:

• x-ui.sh

---

10. Security and hardening guide (critical)

Minimum hardening baseline:

1. Change default admin credentials immediately.
2. Enable two-factor authentication.
3. Change panel URI path from default (/) to a long random path ending with /.
4. Use TLS certs for panel and subscription endpoints.
5. Prefer binding panel to localhost/private interface and use SSH tunnel for admin access.
6. Restrict firewall rules tightly (panel port not globally open if possible).
7. Enable Fail2Ban/IP limit where relevant.
8. Keep geofiles and xray/panel versions updated.
9. Treat Telegram token as secret; rotate if exposed.
10. Export backups regularly and test restore flow.

Operational warning:

• Many panel settings changes require Save + Restart Panel/Xray to apply.

---

11. Common operational workflows

11.1 Add a new inbound safely

1. Go to Inbounds -> Add Inbound.
2. Choose protocol/transport/security (e.g., VLESS + TCP + Reality).
3. Set port/tag/stream settings and enable inbound.
4. Add clients with limits (traffic, expiry, IP limit, reset policy).
5. Save and verify on Overview (xray running, no config errors).
6. Export URLs/subscription for distribution.

11.2 Rotate admin credentials

1. Panel Settings -> Authentication.
2. Fill current and new credentials.
3. Confirm and verify new login.
4. Enable/verify 2FA.

11.3 Enable subscription links

1. Panel Settings -> Subscription.
2. Enable Subscription Service and set secure path/domain/port.
3. Optionally enable JSON endpoint and set separate path.
4. Configure TLS cert paths for subscription listener.
5. Save and restart panel/services as required.
6. Validate /{subPath}{subid} and JSON endpoint.

11.4 Configure WARP routing

1. Xray Configs -> Outbounds -> WARP create/register flow.
2. Add/verify outbound tag.
3. Routing Rules add domain/ip/network rules to send selected traffic to WARP outbound.
4. Save and restart xray.

11.5 Restore from DB backup

1. Export DB first before risky operations.
2. Use server API/UI import DB action.
3. Ensure xray restart path completes.
4. Validate inbounds/clients/settings and login after import.

---

12. Known caveats and behavior notes

• API unauthorized returns 404 (intentional) and may confuse API clients expecting 401.
• Some warning/help text in wiki is version-sensitive; code behavior wins when mismatch appears.
• Access log and fail2ban/IP-limit behavior depend on proper Xray log setup.
• High bandwidth users may continue briefly after limits due to periodic enforcement cadence.
• If DB is slow/locked, traffic/accounting behavior can appear delayed.

---

13. High-value file map (for future deep checks)

• Boot/CLI:
  • main.go
  • x-ui.sh
• Web server and middleware wiring:
  • web/web.go
  • web/middleware/*
• Controllers (routes):
  • web/controller/index.go
  • web/controller/xui.go
  • web/controller/api.go
  • web/controller/inbound.go
  • web/controller/server.go
  • web/controller/setting.go
  • web/controller/xray_setting.go
• Services (business logic):
  • web/service/inbound.go
  • web/service/server.go
  • web/service/setting.go
  • web/service/xray.go
  • web/service/xray_setting.go
  • web/service/outbound.go
  • web/service/tgbot.go
  • web/service/warp.go
• Subscription:
  • sub/sub.go
  • sub/subController.go
  • sub/subService.go
  • sub/subJsonService.go
• DB/models:
  • database/db.go
  • database/model/model.go
  • xray/client_traffic.go
• Jobs:
  • web/job/*.go
• Wiki snapshot used:
  • ../3x-ui.wiki/*.md

---

14. Suggested maintenance routine

Daily:

• Check Overview status and xray health.
• Check logs for abnormal auth attempts/errors.

Weekly:

• Verify backup export/import viability.
• Review depleted/expired clients and cleanup.
• Review fail2ban and firewall rules.

Monthly:

• Rotate sensitive secrets where feasible.
• Review panel path/port exposure and TLS validity.
• Re-audit settings after version updates.

---

15. User-perspective panel operating guide

This section is intentionally UI-first: what you see, what to click, and what happens.

Version context:

• Labels below are based on your observed panel (v2.8.10, English language).
• If your language/theme differs, icon+position are usually stable even when text changes.

15.1 Login screen (/)

Visible items:

• Username input.
• Password input.
• Optional Code input (appears when 2FA is enabled).
• Log In button.
• Top-right settings button (theme + language).

How to use:

1. Enter username and password.
2. If 2FA enabled, enter the one-time code.
3. Click Log In.
4. On success, panel opens Overview.

Failure behavior:

• Wrong credentials show toast error.
• Login attempts are logged and may notify Telegram (if enabled).

15.2 Sidebar navigation

Main left menu items:

• Overview
• Inbounds
• Panel Settings
• Xray Configs
• Log Out

Top utility item:

• Theme switch.

How to use:

1. Use menu to move between modules.
2. Log Out clears your session and returns to login.

15.3 Overview page (/panel/)

What this page is for:

• Quick health check and service control.

Typical cards/buttons:

• CPU/RAM/Swap/Storage cards.
• Xray status card (Running/Stopped) with Stop and Restart.
• Xray version control button.
• Management shortcuts: Logs, Config, Backup.
• System usage, speed, total traffic, connection counts, uptime.

How to operate safely:

1. Check top warning banners first (security/config warnings).
2. Confirm Xray is Running.
3. Use Restart after major config edits.
4. Use Logs when users report failures.
5. Use Backup before risky changes.

15.4 Inbounds page (/panel/inbounds)

This is the main daily operations page.

Top summary cards:

• Total Sent/Received.
• Total Usage.
• All-time Total Usage.
• Total Inbounds.
• Clients count.

Toolbar buttons:

• Add Inbound: create a new listener.
• General Actions: mass operations across inbounds/clients.
• Sync icon: refresh table/state.
• Download icon/menu: export-related actions (depends on build/UI state).
• Filter toggle + Search box.

Inbound row controls:

• Expand button: opens nested client details for that inbound.
• Row ... menu: per-inbound actions.
• Enable switch: on/off without deleting row.

Observed row ... actions and intent:

• Edit: modify inbound protocol/stream/security params.
• Add Client: add one client under this inbound.
• Add Bulk: create many clients in one operation.
• Reset Clients Traffic: reset client traffic counters in this inbound.
• Export All URLs: copy/generate all client connection URLs.
• Export All URLs - Subscription: copy/generate subscription-style URLs.
• Delete Depleted Clients: remove clients that expired/exhausted traffic.
• Export Inbound: export inbound config object.
• Reset Traffic: reset inbound-level traffic usage.
• Clone: duplicate inbound config as a new inbound.
• Delete: remove the inbound.

Recommended working pattern:

1. Create inbound with Add Inbound.
2. Immediately add at least one client.
3. Verify inbound switch is enabled.
4. Test with exported URL on a client app.
5. Monitor traffic growth and online status.

15.5 Panel Settings page (/panel/settings)

This page controls panel behavior and administration.

Global buttons at top:

• Save: writes pending changes to DB.
• Restart Panel: applies panel-side changes.

Critical rule:

• Save does not always fully apply runtime behavior until restart.

Top tabs:

• General
• Authentication
• Telegram Bot
• Subscription

General tab

Primary fields and what they do:

• Listen IP: bind panel server to specific interface.
• Listen Domain: optional host/domain validation.
• Listen Port: panel TCP port.
• URI Path: panel base path (webBasePath) must start/end with /.
• Session Duration: login persistence in minutes.
• Pagination Size: rows per page in inbounds table.
• Language: panel UI language.

Common change flow:

1. Update field.
2. Click Save.
3. Click Restart Panel.
4. Reopen panel at updated URL/path if changed.

Authentication tab

Sections:

• Admin credentials:
  • Current username/password.
  • New username/password.
  • Confirm button.
• Two-factor authentication:
  • Enable/disable/setup 2FA token flow.

Change flow:

1. Fill current and new credentials.
2. Click Confirm.
3. Re-login with new credentials to verify.
4. Enable 2FA and test one full logout/login cycle.

Telegram Bot tab

General section includes:

• Enable Telegram Bot switch.
• Telegram Token.
• Admin Chat ID (comma-separated possible).
• Bot language.

Additional sections:

• Notifications behavior/timing.
• Proxy and API server options.

Use case flow:

1. Enable switch.
2. Paste token from BotFather.
3. Add your chat ID(s).
4. Save and restart panel.
5. Trigger a test action (e.g., login notification/backup) and verify receipt.

Subscription tab

Core controls:

• Subscription Service switch.
• JSON Subscription switch.
• Listen IP, Listen Domain, Listen Port.
• URI Path (link endpoint path, e.g. /sub/).

Common secure setup:

1. Enable subscription.
2. Set non-default path(s).
3. Configure domain/certificates.
4. Save + restart.
5. Validate link endpoint and (if enabled) JSON endpoint.

15.6 Xray Configs page (/panel/xray)

Global buttons at top:

• Save: persist template/config changes.
• Restart Xray: apply xray runtime changes.

Critical rule:

• Most xray config edits need both Save and Restart Xray to be active.

Top tabs:

• Basics
• Routing Rules
• Outbounds
• Reverse
• Balancers
• DNS
• Advanced

Basics

What to change here:

• General runtime strategy fields.
• Log/statistics behavior.
• Outbound Test URL used by outbound tests.

When to use:

• Initial deployment cleanup.
• Debugging route and DNS behavior.

Routing Rules

What it controls:

• Match conditions and outbound target per rule.

How to use:

1. Add rule.
2. Set match condition (domain/ip/network/etc.).
3. Select outbound tag destination.
4. Save + restart Xray.
5. Validate by testing target domains/services.

Outbounds

Common controls:

• Add outbound.
• WARP creation/registration.
• Test outbound connectivity.
• Outbound traffic table and reset actions.

How to use:

1. Add outbound with valid protocol details.
2. Use test action to verify connectivity/latency.
3. Attach routing rule to actually send traffic there.

Reverse

Purpose:

• Reverse proxy structures in Xray config.

Use only when needed:

• More advanced topologies; easy to misconfigure.

Balancers

Purpose:

• Group outbounds and balance traffic by strategy.

Practical note:

• Set clear tags and test routes before production use.

DNS

Purpose:

• Built-in DNS behavior for Xray. Practical note:
• DNS changes can impact all traffic patterns; test carefully.

Advanced

Purpose:

• Raw template editing for full-control scenarios.

Safe editing workflow:

1. Export/backup current config first.
2. Make small incremental changes.
3. Save.
4. Restart Xray.
5. Check logs immediately for parse/runtime errors.

15.7 Security alert banner behavior

When shown, it is actionable. Common warnings:

• No TLS for panel.
• Default panel port/path.
• Default subscription path.

Treat these as high-priority hardening tasks, not cosmetic notices.

15.8 Save/Restart behavior quick table

• Inbounds/client edits:
  • Usually immediate DB change.
  • Runtime update via API/restart logic; verify with status/logs.
• Panel settings edits:
  • Save required.
  • Often requires Restart Panel.
• Xray config edits:
  • Save required.
  • Usually requires Restart Xray.

15.9 “What to click when” quick recipes

Add a user to existing inbound:

1. Inbounds -> row ... -> Add Client.
2. Fill client limits/expiry.
3. Save.
4. Export URL and test.

Disable compromised client fast:

1. Inbounds -> expand row.
2. Locate client.
3. Disable/delete client.
4. Confirm in online/last-online views.

Rotate panel URL path:

1. Panel Settings -> General -> URI Path.
2. Enter random path ending /.
3. Save -> Restart Panel.
4. Reconnect using new URL.

Recover from bad xray edit:

1. Xray Configs -> use defaults/reset path.
2. Save.
3. Restart Xray.
4. Check logs and overview status.

15.10 User mistakes to avoid

• Editing many settings at once without intermediate tests.
• Forgetting restart after Save.
• Leaving default path/port.
• Enabling Telegram bot but exposing token carelessly.
• Using Advanced tab without backup.

---

16. Revision metadata

• Document generated: 2026-02-18 (local time).
• Based on repo: workspace/open-source/3x-ui (local main).
• Based on wiki commit: 6408b1c in local clone workspace/open-source/3x-ui.wiki.

---

17. Live instance addendum (practical operations and standards)

This section captures validated behavior from hands-on operations in a live 3x-ui panel session.

17.1 Client management reality: “single place” vs “inbound-scoped”

Important model:

• In 3x-ui, clients are created under inbounds.
• There is no native global user object automatically attached to all inbounds.
• Expiry/traffic/IP-limit are set per client entry inside each inbound.

Practical way to manage “as one user”:

1. Reuse one stable identifier (email) across all inbounds for that user.
2. Optionally reuse same UUID where protocol/client behavior allows (commonly VLESS workflows).
3. Update quota/expiry on each inbound client entry.
4. Use client traffic/search views/API by email to track usage consistently.

17.2 API endpoints to automate cross-inbound client ops

Useful API patterns for centralized tooling:

• POST /panel/api/inbounds/addClient
• POST /panel/api/inbounds/updateClient/:clientId
• GET /panel/api/inbounds/getClientTraffics/:email

Recommended automation pattern:

• Keep one “master user policy” (days, GB, ip-limit).
• Apply the policy to a list of inbound IDs via API.
• Use email as the logical cross-inbound key.

17.3 Inbound naming standard (recommended)

Use deterministic names:

• <protocol>-<transport>-<security>-<port>-<role>

Examples:

• vless-reality-tcp-443-main
• vless-reality-tcp-8443-alt
• vless-tcp-http-18080-test

Why this works:

• Immediate readability in crowded tables.
• Faster incident response (role and port visible).
• Lower chance of editing the wrong inbound.

17.4 Safe cleanup order for production panels

Apply changes in this order:

1. Rename remarks first (zero functional risk).
2. Verify rows after each save (port/protocol/security unchanged).
3. Only then change functional settings (security/transport/sni/etc.) in isolated steps.
4. Keep one known-good main inbound untouched while testing alternatives.

17.5 Current validated inbound organization pattern

Observed clean structure pattern:

• Main production inbound on 443 with Reality.
• Secondary fallback Reality inbound on alternate TLS-like port (e.g. 8443).
• Separate explicitly-labeled test inbound for experiments.

Operational guidance:

• Keep test inbound clearly labeled (-test) and isolated from production users.
• Remove or disable test inbound when no longer needed.
• Avoid mixing experimental header/obfuscation settings into production remarks.

17.6 Security and control-plane warning handling

If panel shows connection-security warning (no TLS on panel access):

• Treat as a control-plane hardening task.
• Do not enter sensitive credentials over untrusted links.
• Prefer TLS-terminated panel access path as soon as possible.

17.7 Non-breaking tuning rules for existing inbounds

For active user inbounds:

• Do not change port/security/transport unexpectedly.
• Do not rotate keys/shortIds without a migration window.
• Do not disable inbounds with active clients before notification.

For cleanup that is safe anytime:

• Rename remarks.
• Standardize client email/label patterns.
• Review per-client quota/expiry/IP-limit consistency.

---

18. Custom feature: centralized client management (implemented)

This repository now includes a client-first management layer that stays compatible with 3x-ui inbound-scoped architecture.

18.1 What was added

• New panel page: /panel/clients
• New sidebar menu item: Clients Center
• New authenticated API group:
  • GET /panel/api/clients/list
  • GET /panel/api/clients/inbounds
  • POST /panel/api/clients/add
  • POST /panel/api/clients/update/:id
  • POST /panel/api/clients/del/:id
• New database models:
  • master_clients (central profile: name/quota/expiry/ip-limit/enable/comment)
  • master_client_inbounds (mapping master client -> assigned inbounds + underlying assignment email/client key)

18.2 Architectural approach

Why this design:

• Native 3x-ui clients are inbound-scoped.
• Core traffic/ip logic is email-centric and inbound-linked.
• A deep core rewrite is high-risk.

Implemented solution:

• Keep native inbound clients as the execution layer.
• Add master client profiles as orchestration layer.
• On assignment, create/update/remove corresponding inbound clients automatically.

18.3 User workflow now

1. Open Clients Center.
2. Create a master client with:
   • Display name
   • Email prefix
   • Traffic quota (GB)
   • Expiry date/time
   • IP limit
   • Enabled flag
   • Comment
3. Select one or more inbounds.
4. Save.

Result:

• Assigned inbound client records are created and kept in sync from this master profile.
• Updating a master client syncs limits/expiry/enabled/comment to all assigned inbounds.
• Removing assignments detaches from those inbounds.

18.4 Important behavior details

• Assignment emails are generated uniquely per inbound to stay compatible with existing uniqueness checks.
• The feature supports multi-client protocols (VLESS/VMESS/Trojan/Shadowsocks).
• If removing a client would leave an inbound with zero clients, detach can fail by design (safety guard inherited from inbound logic).

18.5 Stability improvement included

A panic-safe guard was added in Xray API client methods (AddInbound, DelInbound, AddUser, RemoveUser) to return a clean error when handler service is not initialized, instead of nil-pointer panic.

18.6 Local validation performed

Environment:

• Local run with SQLite (XUI_DB_FOLDER custom path), custom log folder, panel on local port.

Validated:

• Login works.
• GET /panel/api/clients/list works.
• GET /panel/api/clients/inbounds works.
• POST /panel/api/clients/add works.
• POST /panel/api/clients/update/:id works (including inbound assignment sync).
• POST /panel/api/clients/del/:id works.
• Browser UI route /panel/clients renders.
• UI create flow works (form -> save -> row visible in table).

18.7 Files touched for this feature

• database/model/model.go
• database/db.go
• web/service/client_center.go
• web/controller/client_center.go
• web/controller/api.go
• web/controller/xui.go
• web/html/component/aSidebar.html
• web/html/clients.html
• xray/api.go

18.8 Future hardening suggestions

• Add explicit role/permission checks for client-center APIs in multi-admin scenarios.
• Add audit logs for master-client create/update/delete operations.
• Add automated integration tests for add/update/remove assignment scenarios.

---

19. Dev workflow additions (implemented)

This section captures engineering workflow additions made during implementation.

19.1 Air live-reload setup

Added:

• .air.toml

Behavior:

• Builds dev binary to tmp/bin/3x-ui-dev.
• Runs panel with:
  • XUI_DB_FOLDER=$PWD/tmp/db
  • XUI_LOG_FOLDER=$PWD/tmp/logs
  • XUI_DEBUG=true
• Auto-creates tmp/db, tmp/logs, tmp/bin.
• Initializes fresh local DB automatically (admin/admin on port 2099) if DB does not exist.

Run:

1. air -c .air.toml
2. Open http://127.0.0.1:2099
3. Login admin/admin (fresh dev DB case)

19.2 Justfile command setup

Added:

• justfile

Common commands:

• just help
• just ensure-tmp
• just init-dev
• just run
• just air
• just build
• just check
• just api-login
• just api-clients-inbounds
• just api-clients-list
• just clean-tmp

All commands are scoped to local tmp/ so production paths are untouched.

19.3 Local test execution summary

Validated locally after implementation:

• Build success with go build ./....
• App starts with local sqlite paths under tmp/.
• New route /panel/clients renders.
• New APIs respond correctly with authenticated session.
• Client-center create/update/delete flows work end-to-end.
• Assignment sync between master clients and inbounds works.

19.4 Stability fix included during testing

In local test conditions where Xray handler client may be unavailable, API operations previously could panic. Fix applied in xray/api.go:

• Guard AddInbound, DelInbound, AddUser, RemoveUser against nil handler service client.
• Return explicit error instead of panic.

---

20. Guide split map (new focused docs)

This monolithic document is now complemented by focused files under:

• docs/panel-guide/

Index:

• docs/panel-guide/README.md
• docs/panel-guide/01-overview-and-architecture.md
• docs/panel-guide/02-pages-and-operations.md
• docs/panel-guide/03-api-and-cli-reference.md
• docs/panel-guide/04-security-and-hardening.md
• docs/panel-guide/05-client-management-model.md
• docs/panel-guide/06-custom-client-center-feature.md
• docs/panel-guide/07-dev-and-testing-workflow.md
• docs/panel-guide/08-protocols-and-config-analysis.md
• docs/panel-guide/09-xray-protocol-reference.md
• docs/panel-guide/10-glossary-and-concepts.md
• docs/panel-guide/11-troubleshooting-runbook.md
• docs/panel-guide/12-change-management-and-rollout.md
• docs/panel-guide/13-feature-file-map-and-decision-log.md
• docs/panel-guide/99-session-context-transfer-2026-02-18.md

Use those files for day-to-day operations and implementation reference.