Alex-Devera/3x-ui
1
0
Fork 0
mirror of https://github.com/MHSanaei/3x-ui.git synced 2026-02-28 05:02:59 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: add panel guide documentation

Browse source
This commit is contained in:
Mohamadhosein Moazennia 2026-02-18 20:12:04 +03:30
parent 8b72cfd870
commit 9ea6f9d50b
16 changed files with 2347 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1233
PANEL_GUIDE_SOURCE_OF_TRUTH.md Normal file
View file

File diff suppressed because it is too large Load diff

81
docs/panel-guide/01-overview-and-architecture.md Normal file
View file

@ -0,0 +1,81 @@
# 01. Overview and Architecture
## What 3x-ui is
3x-ui is a control panel around Xray-core for:
- Inbound and client management
- Quota/expiry/statistics
- Advanced Xray config/routing editing
- Operational actions (restart, logs, backup/import/export)
- Optional subscription and Telegram integrations
## Core runtime parts
- Web panel server: `web/web.go`
- Subscription server: `sub/sub.go`
- Xray integration service: `web/service/xray.go`
- Binary entrypoint: `main.go`
## Data layer
Default storage is SQLite via GORM.
Models include:
- `User`
- `Inbound`
- `Setting`
- `OutboundTraffics`
- `InboundClientIps`
- `xray.ClientTraffic`
- `HistoryOfSeeders`
- Custom extension: `MasterClient`, `MasterClientInbound`
Files:
- `database/db.go`
- `database/model/model.go`
- `xray/client_traffic.go`
## Auth/session model
- Cookie session with secret from DB settings
- `/panel/*` requires login
- `/panel/api/*` also requires login
- Unauthorized API requests are intentionally hidden with 404 behavior
Files:
- `web/controller/base.go`
- `web/controller/api.go`
- `web/session/session.go`
## Background jobs and periodic logic
Cron-based tasks include:
- Xray process health checks
- Traffic collection from Xray
- Auto disable/renew logic
- Client IP checks and cleanup
- Optional LDAP and Telegram jobs
Files:
- `web/web.go`
- `web/job/*.go`
- `web/service/inbound.go`
## URL topology
UI:
- `/`
- `/panel/`
- `/panel/inbounds`
- `/panel/clients` (custom)
- `/panel/settings`
- `/panel/xray`
API:
- `/panel/api/inbounds/*`
- `/panel/api/server/*`
- `/panel/api/clients/*` (custom)
- `/panel/xray/*`
- `/panel/setting/*`
Subscription:
- Dynamic from settings (`subPath`, `subJsonPath`)

92
docs/panel-guide/02-pages-and-operations.md Normal file
View file

@ -0,0 +1,92 @@
# 02. Pages and Operations
## Overview page (`/panel/`)
Primary purpose:
- Server and Xray health view
- Quick operational actions
Typical actions:
- Restart/stop Xray
- View logs
- Check utilization and throughput
## Inbounds page (`/panel/inbounds`)
Primary purpose:
- Manage listeners and protocol endpoints
- Manage inbound-scoped clients
Core operations:
- Add/edit/delete inbound
- Enable/disable inbound
- Add/edit/delete client
- Bulk add clients
- Reset traffic (client/inbound/global)
- Export URLs/subscription data
- Clone inbound
Operational best practice:
1. Rename/label first.
2. Change one technical setting at a time.
3. Keep one known-good inbound untouched while testing.
## Clients page (`/panel/clients`) - custom extension
Primary purpose:
- Master client profile management
- Multi-inbound assignment orchestration
Core operations:
- Create master client (name, prefix, quota, expiry, ip limit, enabled, comment)
- Assign one or more inbounds
- Update profile and sync assigned inbounds
- Delete master client and remove assignments
## Panel Settings (`/panel/settings`)
Tabs:
- General
- Authentication
- Telegram Bot
- Subscription
Critical controls:
- Listen IP/domain/port
- Base path
- Session duration
- Admin credentials and 2FA
## Xray Configs (`/panel/xray`)
Tabs:
- Basics
- Routing Rules
- Outbounds
- Reverse
- Balancers
- DNS
- Advanced
Safety workflow:
1. Backup/export first.
2. Small changes only.
3. Save and restart Xray when needed.
4. Check logs immediately.
## Frequent operations checklist
- Add new inbound safely:
1. Create inbound with clear remark and tested config
2. Add one test client
3. Verify connectivity
4. Roll out to users
- Rotate admin credentials:
1. Change in Authentication tab
2. Re-login and confirm
- Recover from bad Xray config:
1. Restore known-good template
2. Restart Xray
3. Verify logs/status

73
docs/panel-guide/03-api-and-cli-reference.md Normal file
View file

@ -0,0 +1,73 @@
# 03. API and CLI Reference
## API auth
- Session cookie required.
- API group is mounted under `/panel/api`.
- Unauthenticated API calls are hidden (404 behavior).
## Inbounds API (main set)
Examples:
- `GET /panel/api/inbounds/list`
- `GET /panel/api/inbounds/get/:id`
- `POST /panel/api/inbounds/add`
- `POST /panel/api/inbounds/update/:id`
- `POST /panel/api/inbounds/del/:id`
- `POST /panel/api/inbounds/addClient`
- `POST /panel/api/inbounds/updateClient/:clientId`
- `POST /panel/api/inbounds/:id/delClient/:clientId`
- `GET /panel/api/inbounds/getClientTraffics/:email`
Controller file:
- `web/controller/inbound.go`
## Server API
Examples:
- `GET /panel/api/server/status`
- `POST /panel/api/server/restartXrayService`
- `POST /panel/api/server/stopXrayService`
- `POST /panel/api/server/logs/:count`
Controller file:
- `web/controller/server.go`
## Custom Clients API (implemented)
- `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`
Files:
- `web/controller/client_center.go`
- `web/service/client_center.go`
## Panel and Xray settings APIs
- `/panel/setting/*`
- `/panel/xray/*`
Files:
- `web/controller/setting.go`
- `web/controller/xray_setting.go`
## CLI usage
Binary supports:
- `run`
- `setting`
- `migrate`
Examples:
```bash
go run . setting -port 2099 -username admin -password admin
go run . run
```
Admin shell scripts:
- `x-ui.sh`
- `install.sh`
- `update.sh`

57
docs/panel-guide/04-security-and-hardening.md Normal file
View file

@ -0,0 +1,57 @@
# 04. Security and Hardening
## Immediate high-priority items
1. Enable TLS for panel access.
2. Change default/guessable panel base path.
3. Change default subscription paths.
4. Use strong admin password + 2FA.
5. Restrict panel listen IP where possible.
## Operational hardening
- Keep backups of DB before major changes.
- Use staged config changes, not bulk edits.
- Keep one known-good inbound active.
- Review logs after each restart.
## Control-plane warning handling
If panel shows security warning banner:
- Treat as real risk, not cosmetic.
- Do not expose panel publicly without TLS.
## Inbound safety rules
For active user inbounds:
- Avoid sudden port/security/transport changes.
- Avoid key/shortId rotation without migration window.
- Avoid disable/delete on active inbounds without user communication.
Safe changes anytime:
- Remark/naming cleanup
- Client naming consistency
- Non-functional labeling and grouping
## Current naming standard recommendation
Use:
- `<protocol>-<transport>-<security>-<port>-<role>`
Examples:
- `vless-reality-tcp-443-main`
- `vless-reality-tcp-8443-alt`
- `vless-tcp-http-18080-test`
## Suggested maintenance cadence
Daily:
- Check Xray state, error logs, traffic anomalies
Weekly:
- Review depleted/disabled clients
- Validate backup and restore path
Monthly:
- Rotate sensitive paths/credentials if needed
- Review exposed interfaces and firewall rules

46
docs/panel-guide/05-client-management-model.md Normal file
View file

@ -0,0 +1,46 @@
# 05. Client Management Model (Native 3x-ui)
## Native model truth
3x-ui is inbound-first.
- Clients are stored inside each inbound.
- There is no native global user object that auto-attaches to multiple inbounds.
## Practical centralized behavior (without custom feature)
You can simulate central management by:
1. Reusing the same user identifier pattern (email/name).
2. Applying same policy per inbound client (quota/expiry/ip limit).
3. Automating updates with panel APIs.
## Why model works this way
Core internals are tied to inbound-scoped records:
- Client traffic links to inbound and email
- Client IP tracking is email-based
- Inbound settings embed client arrays
Key files:
- `web/service/inbound.go`
- `xray/client_traffic.go`
- `database/model/model.go`
## Per-client controls
For each inbound client you can set:
- `totalGB`
- `expiryTime`
- `limitIp`
- `enable`
- `comment`
- (protocol-specific identity fields)
## Automation endpoints commonly used
- `POST /panel/api/inbounds/addClient`
- `POST /panel/api/inbounds/updateClient/:clientId`
- `GET /panel/api/inbounds/getClientTraffics/:email`
## Operational recommendation
Use policy templates (for example 30d/100GB, 30d/300GB, unlimited) and apply them consistently.

68
docs/panel-guide/06-custom-client-center-feature.md Normal file
View file

@ -0,0 +1,68 @@
# 06. Custom Client-Center Feature
## Goal
Add a true operator-friendly client-first page while preserving 3x-ui compatibility and minimizing break risk.
## Implemented design
A new orchestration layer was added:
- Master client profile table
- Master client <-> inbound assignment mapping table
- Sync logic that creates/updates/removes native inbound clients automatically
## Added backend pieces
Models:
- `MasterClient`
- `MasterClientInbound`
Service:
- `web/service/client_center.go`
Controller/API:
- `web/controller/client_center.go`
- Mounted in `web/controller/api.go` under `/panel/api/clients/*`
## Added frontend pieces
- Route: `/panel/clients`
- Page: `web/html/clients.html`
- Sidebar item: `web/html/component/aSidebar.html`
## API surface
- `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`
## Behavior notes
- Supports multi-client protocols (vless/vmess/trojan/shadowsocks).
- Assignment email is generated uniquely per inbound.
- Master profile fields are synced to assigned inbound client entries.
- Detach can fail if an inbound would be left with zero clients (inherited safety rule).
## Stability fix included
`xray/api.go` now guards nil handler client and returns clear errors in:
- `AddInbound`
- `DelInbound`
- `AddUser`
- `RemoveUser`
This prevents nil-pointer panics during local/dev conditions.
## Files touched (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/clients.html`
- `web/html/component/aSidebar.html`
- `xray/api.go`

66
docs/panel-guide/07-dev-and-testing-workflow.md Normal file
View file

@ -0,0 +1,66 @@
# 07. Dev and Testing Workflow
## Local dev philosophy
Keep all local mutable state inside repo `tmp/`:
- `tmp/db`
- `tmp/logs`
- `tmp/bin`
- `tmp/cookies`
## Fast dev run (without air)
```bash
mkdir -p tmp/db tmp/logs
XUI_DB_FOLDER="$PWD/tmp/db" XUI_LOG_FOLDER="$PWD/tmp/logs" XUI_DEBUG=true \
go run . setting -port 2099 -username admin -password admin
XUI_DB_FOLDER="$PWD/tmp/db" XUI_LOG_FOLDER="$PWD/tmp/logs" XUI_DEBUG=true \
go run . run
```
Panel:
- URL: `http://127.0.0.1:2099`
- Login: `admin/admin` (fresh DB)
## Air live-reload
Config file:
- `.air.toml`
Run:
```bash
air -c .air.toml
```
Behavior:
- Builds to `tmp/bin/3x-ui-dev`
- Runs with tmp db/log env vars
- Bootstraps fresh DB credentials/port when DB absent
## Justfile commands
- `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`
## Validation checklist for custom clients feature
1. Login and open `/panel/clients`.
2. Create master client with one inbound assignment.
3. Confirm row appears in clients table.
4. Confirm assignment visible in list API.
5. Update policy fields and assignment set.
6. Confirm synced result in list API.
7. Delete master client and confirm list is empty.
## Notes from local test run
- Build and startup validated on local SQLite paths.
- API + UI flows for custom clients feature validated.
- Xray API nil-client panic path was fixed and replaced with explicit errors.

93
docs/panel-guide/08-protocols-and-config-analysis.md Normal file
View file

@ -0,0 +1,93 @@
# 08. Protocols and Config Analysis (Session Transfer)
## Scope
This file captures protocol and configuration understanding gathered during the session, including practical guidance for creating client-similar inbound behavior in 3x-ui.
## Xray protocol framing
Common protocols in this panel context:
- `vless`
- `vmess`
- `trojan`
- `shadowsocks`
Important distinction:
- Protocol defines identity/auth semantics.
- Transport/stream settings define wire behavior (tcp/ws/grpc/http-like headers/reality/tls/etc).
## Reality summary (operational)
Reality is used as a TLS-camouflage security layer in modern Xray setups (commonly with VLESS).
Typical panel representation:
- Protocol: `vless`
- Network: `tcp`
- Security marker: `Reality`
Operational notes:
- It is sensitive to keypair, shortIds, target/serverName settings.
- Changing Reality material on active inbounds can break all existing clients immediately.
- Use staged migration for key/shortId rotations.
## XHTTP / HTTP-like obfuscation context
In practical user terms (for this session), “similar config from client perspective” meant creating an inbound with:
- `vless` + `tcp`
- No TLS/Reality on that specific test inbound
- HTTP header camouflage (request path/host)
Implemented test-like inbound pattern in panel:
- Remark pattern after cleanup: `vless-tcp-http-18080-test`
- Port: `18080`
- HTTP obfuscation with `Host = speedtest.com`, `Path = /`
## Analysis of provided sample JSON configs
Two provided JSON samples were client-side local Xray configs, not panel server-side inbound objects.
High-level structure observed:
- Local inbounds:
- SOCKS and HTTP on loopback + LAN IP (`10808`, `10809`)
- Additional direct SOCKS inbound (`10820`) for bypass route
- Outbounds:
- Main `vless` outbound with `tcp` + HTTP header disguise
- `direct` (freedom)
- `block` (blackhole)
- Routing:
- Domain/IP direct lists
- Special rules for DNS endpoints and direct inbound tag
- DNS:
- DoH to Cloudflare and Google with domain-based resolver split
Interpretation:
- These configs are client aggregator profiles routing app traffic through a remote VLESS endpoint.
- To create “similar behavior” on your 3x-ui server, we focused on matching protocol/transport/obfuscation characteristics in inbound settings (not mirroring client local socks/http listener topology).
## Can similar inbounds be created in your instance?
Yes. Practical answer from this session:
- Similar client-facing server profile can be created in 3x-ui.
- Exact local client config object is not a server inbound; it must be translated to compatible inbound parameters.
## Safe conversion rules used
1. Preserve existing production inbounds (`443/8443 Reality`) to avoid breakage.
2. Add separate test inbound for obfuscated TCP behavior.
3. Use explicit remark naming to avoid accidental edits.
4. Verify saved settings from modal after creation.
## Naming standard adopted
- `vless-reality-tcp-443-main`
- `vless-reality-tcp-8443-alt`
- `vless-tcp-http-18080-test`
Format:
- `<protocol>-<security/transport>-<port>-<role>` (or close equivalent used here)
## Practical recommendations
- Keep Reality as production path when already stable for clients.
- Keep obfuscation test profiles isolated and clearly marked `-test`.
- Do not mix experimental configs into main inbound until tested and monitored.

141
docs/panel-guide/09-xray-protocol-reference.md Normal file
View file

@ -0,0 +1,141 @@
# 09. Xray Protocol Reference for 3x-ui
## Scope
This document captures protocol-level understanding relevant to 3x-ui operations and implementation decisions.
Important:
- It is an operator-focused reference, not full wire-spec replacement for each protocol.
- Always validate against current upstream Xray docs before major production migrations.
## Protocols supported in current model/constants
From `database/model/model.go` protocol constants:
- `vmess`
- `vless`
- `trojan`
- `shadowsocks`
- `http`
- `mixed`
- `tunnel`
- `wireguard`
## Concept model
In Xray/3x-ui, configuration is split into:
1. Protocol/auth layer (vless/vmess/trojan/ss/etc)
2. Transport/stream layer (`tcp`, `ws`, `grpc`, etc)
3. Security layer (`none`, `tls`, `reality`)
4. Routing/DNS policy layer
Most operator mistakes happen when these layers are mixed conceptually.
## VLESS
Characteristics:
- Modern lightweight protocol (common choice with Reality).
- Client identity via UUID (`id`) and optional `flow` in specific TLS/XTLS contexts.
Typical production pairings:
- `vless + tcp + reality`
- `vless + ws + tls`
- `vless + grpc + tls`
Operational notes:
- Treat UUID/flow/security migration as coordinated change.
- Reality key material/shortIds are break-sensitive.
## VMESS
Characteristics:
- Legacy/common protocol with UUID identity and security parameters.
Operational notes:
- Can still work well, but many modern deployments prefer VLESS.
- Migration VMESS->VLESS should be staged as full client profile replacement.
## Trojan
Characteristics:
- Password-based identity model.
- Often used with TLS-like camouflage patterns.
3x-ui key behavior:
- Client key for updates/deletes is password for trojan path in service logic.
## Shadowsocks
Characteristics:
- Cipher/password model.
- Includes classic and 2022-style cipher handling paths in Xray integration.
3x-ui key behavior:
- Email plays tracking role in panel logic even for SS clients.
- For SS, client-key handling differs from UUID-based protocols.
## WireGuard / Tunnel / HTTP / Mixed
These exist in model support and can appear in inbound definitions depending on build/version/UI exposure.
Operational recommendation:
- Use these only when your use-case explicitly requires them.
- Keep your mainstream user path on one well-tested protocol family.
## Reality
Reality is a security/camouflage mode (commonly with VLESS TCP).
Key operator concerns:
- Public key/private key, shortIds, destination/serverName consistency.
- Any mismatch causes hard connect failures.
- Keep a fallback inbound during rotations.
## XHTTP / HTTP-style obfuscation context
In this session context, “xhttp-like/client-similar behavior” referred to HTTP header camouflage over TCP-style transport.
Implemented test pattern:
- `vless-tcp-http-18080-test`
- Request header host and path set for camouflage testing.
Guidance:
- Keep obfuscation experiments in clearly marked test inbounds.
- Do not blend experimental obfuscation into main production inbound without staged rollout.
## Routing and DNS interplay (critical)
Protocol success can still fail at policy layer due to:
- DNS resolver split policies
- Domain/IP route overrides
- Direct/proxy exceptions
Always validate:
1. Inbound reaches server
2. Auth/security valid
3. DNS route correct
4. Outbound path available
## Practical compatibility checklist before creating a new inbound type
1. Confirm protocol support in current panel build.
2. Confirm client app supports same protocol+transport+security combo.
3. Create isolated test inbound first.
4. Add one test client and verify handshake/traffic.
5. Roll out with explicit naming and fallback path.
## Naming convention reminder
Use descriptive remarks to prevent operator error:
- `<protocol>-<transport>-<security>-<port>-<role>`
Examples used in session:
- `vless-reality-tcp-443-main`
- `vless-reality-tcp-8443-alt`
- `vless-tcp-http-18080-test`
## Where to cross-check in codebase
- Protocol constants: `database/model/model.go`
- Inbound/client update logic: `web/service/inbound.go`
- Xray add/remove user and inbound operations: `xray/api.go`
- Xray config assembly: `web/service/xray.go`

61
docs/panel-guide/10-glossary-and-concepts.md Normal file
View file

@ -0,0 +1,61 @@
# 10. Glossary and Concepts
## Core terms
- Inbound:
Server-side listener definition (protocol, port, stream/security settings, and clients).
- Outbound:
Egress route object used by routing policy.
- Client (native 3x-ui):
Per-inbound user entry embedded under inbound settings.
- Master Client (custom feature):
Central profile that syncs policy to assigned inbound clients.
- Assignment:
Link between one master client and one inbound (custom table-backed mapping).
- Stream/Transport:
Wire transport settings (tcp/ws/grpc/etc) independent from protocol identity.
- Security layer:
`none`, `tls`, or `reality` depending on stream configuration.
- Sniffing:
Metadata/domain extraction behavior for routing logic.
- Traffic reset:
Reset policy cycle for usage counters.
- `needRestart`:
Service flag indicating runtime API update failed or restart is required for consistency.
## Data model concepts
- `inbounds.settings` stores client arrays as JSON.
- `xray.ClientTraffic` stores usage/state counters per tracked client email.
- `InboundClientIps` stores email-to-IP observations.
- Custom extension adds:
- `MasterClient`
- `MasterClientInbound`
## Control plane vs data plane
- Control plane:
Panel UI/API, DB, settings, orchestration jobs.
- Data plane:
Xray runtime handling proxy traffic.
Operationally:
- A panel save may succeed in DB while runtime application may require restart.
- Always verify both DB state and runtime state for critical changes.
## Practical mental model
1. Configure inbound protocol/transport/security.
2. Attach clients (native or via master sync).
3. Validate routing/DNS/outbound path.
4. Confirm runtime apply and traffic counters.

84
docs/panel-guide/11-troubleshooting-runbook.md Normal file
View file

@ -0,0 +1,84 @@
# 11. Troubleshooting Runbook
## Fast triage order
1. Confirm panel reachability and login.
2. Check Xray running state on Overview.
3. Check recent panel logs and Xray logs.
4. Verify inbound enable state and port binding.
5. Verify client enabled/quota/expiry/IP limits.
6. Verify routing and DNS policy impact.
## Common issues
### Panel loads but auth/session fails
Checks:
- Session settings and secret availability.
- Cookie persistence and base path correctness.
Files:
- `web/web.go`
- `web/service/setting.go`
### Inbound saved but traffic not flowing
Checks:
- Runtime apply result (`needRestart` scenarios).
- Xray state and error logs.
- Transport/security mismatch with client app.
Files:
- `web/service/inbound.go`
- `web/service/xray.go`
### Clients unexpectedly disabled/depleted
Checks:
- Auto disable/renew logic from periodic jobs.
- `totalGB`, `expiryTime`, reset behavior.
Files:
- `web/service/inbound.go`
- `web/job/xray_traffic_job.go`
### Assignment sync errors in custom clients feature
Checks:
- Inbound protocol supports multi-client.
- Assignment detach is not removing last remaining client from inbound.
- Underlying inbound client key (id/password/email) still valid.
Files:
- `web/service/client_center.go`
- `web/service/inbound.go`
### Panic or 500 during Xray API interaction
Current guard:
- `xray/api.go` now returns explicit error when handler client is nil.
Action:
- Confirm Xray API availability and startup timing.
## Local dev troubleshooting
If app cannot write default paths:
- Use repo-local env:
- `XUI_DB_FOLDER=$PWD/tmp/db`
- `XUI_LOG_FOLDER=$PWD/tmp/logs`
If dependency proxy blocks build:
- `GOPROXY=direct go build ./...`
If login fails in fresh local DB:
- Run init:
- `go run . setting -port 2099 -username admin -password admin`
## Evidence collection checklist
Collect before major debugging:
1. Active inbounds list JSON.
2. Client traffic record snapshot.
3. Current panel settings export.
4. Recent xray log excerpts around failure time.

53
docs/panel-guide/12-change-management-and-rollout.md Normal file
View file

@ -0,0 +1,53 @@
# 12. Change Management and Rollout
## Goal
Provide low-risk patterns for introducing protocol/config/UI/backend changes in a running panel.
## Safe rollout pattern
1. Backup DB.
2. Add new config in parallel (do not replace old path immediately).
3. Validate with one test client.
4. Migrate a small user slice.
5. Monitor logs/latency/failure rate.
6. Complete migration and decommission old path.
## For inbound/protocol changes
Do first:
- Naming cleanup and explicit role labels.
- New test inbound with clear `-test` suffix.
Do later:
- Security/transport rotations on production inbound.
## For client policy changes
- Apply policy in additive way.
- Prefer staged updates by user segment.
- Confirm no accidental disable due to quota/expiry mismatch.
## For custom feature changes
- Keep additive APIs; avoid breaking old endpoints.
- Feature-flag or route-gate where possible.
- Maintain backward compatibility with inbound-native operations.
## Regression checklist
After any significant change verify:
1. Login and panel navigation.
2. Inbounds list and edit flow.
3. Add/update/delete client flow.
4. Export URL/subscription flow.
5. Xray restart and log health.
6. Custom clients page CRUD + sync.
## Rollback checklist
1. Stop rollout.
2. Revert to known-good binary/config.
3. Restore DB backup if data mutation is root cause.
4. Re-validate panel and xray state.
5. Reintroduce change in smaller scope.

61
docs/panel-guide/13-feature-file-map-and-decision-log.md Normal file
View file

@ -0,0 +1,61 @@
# 13. Feature File Map and Decision Log
## Why this exists
To preserve implementation intent and reduce rediscovery cost when modifying the custom client-center extension.
## Decision log (session)
1. Decision:
Build client-center as orchestration layer instead of replacing inbound-native model.
Reason:
Lower break risk with existing email/inbound-centric traffic and client logic.
2. Decision:
Keep existing inbounds/client APIs intact and add new API namespace.
Reason:
Backward compatibility for existing UI and operational scripts.
3. Decision:
Add panic guards in Xray API integration points.
Reason:
Improve resilience in dev/runtime states where handler client may be unavailable.
## File map (custom extension)
Data models:
- `database/model/model.go`
- `MasterClient`
- `MasterClientInbound`
Migration registration:
- `database/db.go`
Backend service:
- `web/service/client_center.go`
Controller/API:
- `web/controller/client_center.go`
- `web/controller/api.go` (mounts `/panel/api/clients`)
UI route and page:
- `web/controller/xui.go` (`/panel/clients`)
- `web/html/clients.html`
- `web/html/component/aSidebar.html`
Stability fix:
- `xray/api.go`
Dev tooling:
- `.air.toml`
- `justfile`
## Future extension points
1. Add granular permissions for clients API.
2. Add audit logs table for master-client actions.
3. Add integration tests for sync edge-cases.
4. Add i18n keys for custom page labels/messages.

98
docs/panel-guide/99-session-context-transfer-2026-02-18.md Normal file
View file

@ -0,0 +1,98 @@
# 99. Session Context Transfer (2026-02-18)
## Purpose
This is a handoff snapshot of all major context and decisions from the collaboration session, so future work can continue without re-discovery.
## Repository and research context
- Repo analyzed: `MHSanaei/3x-ui`
- Wiki reference used: `MHSanaei/3x-ui/wiki`
- Existing long guide maintained and expanded: `PANEL_GUIDE_SOURCE_OF_TRUTH.md`
- Focused guide set added under: `docs/panel-guide/`
## Live panel operational context captured
Panel URL pattern used in session:
- `http://127.0.0.1:2053/panel/`
Observed production-style inbounds in your panel during cleanup:
- `reality-443` (renamed)
- `reality-8443` (renamed)
Additional test inbound created by request:
- VLESS TCP with HTTP obfuscation style (`Host speedtest.com`, path `/`) on `18080`
Final cleaned naming applied in live panel:
- `vless-reality-tcp-443-main`
- `vless-reality-tcp-8443-alt`
- `vless-tcp-http-18080-test`
## Core product-model conclusion
Native 3x-ui is inbound-first:
- Clients are managed per inbound.
- There is no built-in global client object with many-to-many inbound assignment UX.
This drove implementation choice:
- Build a client-center orchestration layer, not a deep replacement of native inbound client model.
## Custom feature delivered
Implemented centralized client-management extension:
- New page: `/panel/clients`
- New API group: `/panel/api/clients/*`
- New DB models for master profile + inbound assignments
- Sync engine to create/update/remove underlying inbound clients
Files created/updated for feature:
- `web/service/client_center.go`
- `web/controller/client_center.go`
- `web/html/clients.html`
- `database/model/model.go`
- `database/db.go`
- `web/controller/api.go`
- `web/controller/xui.go`
- `web/html/component/aSidebar.html`
## Additional engineering improvements
1. Air setup:
- Added `.air.toml` for live-reload development.
- Keeps DB/log/bin in `tmp/`.
2. Justfile setup:
- Added `justfile` with common run/build/air/api helper commands.
3. Runtime stability guard:
- Added nil-handler checks in `xray/api.go` (`AddInbound`, `DelInbound`, `AddUser`, `RemoveUser`) to avoid panic and return explicit errors.
## Local validation that was performed
Local dev run used repo-local paths:
- DB: `tmp/db`
- Logs: `tmp/logs`
- Port: `2099`
Validated flows:
- Build success (`go build ./...`)
- Panel startup in debug/dev mode
- Login and authenticated API access
- Custom clients API CRUD and assignment sync
- `/panel/clients` UI render and create flow via browser automation
## Known caveats from session
- A large set of `.playwright-cli` artifacts exists in working tree; this was intentionally not cleaned to avoid touching unrelated state.
- If Xray handler service is unavailable in dev conditions, inbound operations may return explicit errors (now handled) rather than panic.
## Recommended next actions
1. Add automated integration tests for client-center sync scenarios.
2. Add role/audit controls for client-center APIs in multi-admin environments.
3. Decide whether to keep monolithic guide as archive-only and rely on split docs for active maintenance.
4. If desired, add i18n labels for new `Clients` UI text to align with full localization style.
## Sensitive data handling note
Credentials used during interactive operations were user-provided in chat and are intentionally not persisted in this file.

40
docs/panel-guide/README.md Normal file
View file

@ -0,0 +1,40 @@
# 3x-ui Guide Index
This folder is the focused replacement for the monolithic `PANEL_GUIDE_SOURCE_OF_TRUTH.md`.
## Files
1. `01-overview-and-architecture.md`
2. `02-pages-and-operations.md`
3. `03-api-and-cli-reference.md`
4. `04-security-and-hardening.md`
5. `05-client-management-model.md`
6. `06-custom-client-center-feature.md`
7. `07-dev-and-testing-workflow.md`
8. `08-protocols-and-config-analysis.md`
9. `09-xray-protocol-reference.md`
10. `10-glossary-and-concepts.md`
11. `11-troubleshooting-runbook.md`
12. `12-change-management-and-rollout.md`
13. `13-feature-file-map-and-decision-log.md`
14. `99-session-context-transfer-2026-02-18.md`
## Recommended read order
1. Read `01` for system model.
2. Read `02` for operator actions.
3. Read `04` before internet exposure.
4. Read `05` and `06` for client strategy.
5. Read `07` for local dev/test workflow.
6. Read `08` for protocol conversion and sample-config interpretation.
7. Read `09` for protocol reference and compatibility guidance.
8. Read `10` for shared terminology and mental models.
9. Read `11` for incident/debug operation.
10. Read `12` before any risky rollout/migration.
11. Read `13` before modifying custom feature code.
12. Read `99` for full session handoff context.
## Scope note
- These files reflect current repository state and live validation work done on 2026-02-18.
- For historical context and raw long-form notes, keep `PANEL_GUIDE_SOURCE_OF_TRUTH.md` as archive.