2026-06-27 06:42:11 -07:00
|
|
|
# CLAUDE.md
|
|
|
|
|
|
|
|
|
|
Operational guide for AI agents working in this repo. Long-form human docs:
|
|
|
|
|
`CONTRIBUTING.md` (setup, testing philosophy) and `frontend/README.md`.
|
|
|
|
|
Read those before large changes. This file is the short, must-follow version.
|
docs: move architecture map into docs/ and refresh it against the live tree
The architecture/code map previously lived in .claude/CLAUDE.md, which was
gitignored (local-only) and auto-loaded into every agent session alongside
the root CLAUDE.md. Track it in docs/architecture.md instead and reference
it from CLAUDE.md so it is read on demand.
While moving it, fact-check the whole map against the current tree:
- add the missing internal/eventbus and internal/tunnelmonitor packages,
the service/email subpackage, and util/wirecodec
- document node mTLS (tls_client.go, node_mtls.go, setting_mtls.go) and the
fourth TLS verify mode
- add the Host, ClientExternalLink, NodeClientIp and ClientGlobalTraffic
models plus their symptom-index rows
- correct the cron table (check_cpu_usage is 1m not 10s; add
check_memory_usage and free_os_memory), the middleware chain
(MaxBodyBytes, ConfigEnvelope, CSRF) and the controller route prefixes
- refresh the sub/ and service/ file listings, frontend pages (hosts/,
index/), CI workflow list, and replace stale exact line counts with
rounded sizes
2026-07-02 05:21:21 -07:00
|
|
|
For a deep navigation map (request lifecycle, cron-job table, symptom → file
|
|
|
|
|
index, layering rules), read `docs/architecture.md` on demand — do not guess
|
|
|
|
|
file locations when it can answer in one hop.
|
2026-06-27 06:42:11 -07:00
|
|
|
|
|
|
|
|
## Stack
|
|
|
|
|
- Backend: Go 1.26 (`module github.com/mhsanaei/3x-ui/v3`), Gin, GORM.
|
|
|
|
|
Runs Xray-core as a managed child process (`internal/xray/process.go`) and
|
|
|
|
|
imports `github.com/xtls/xray-core` for config types + gRPC stats/handler/router
|
2026-07-06 07:04:32 -07:00
|
|
|
API. MTProto inbounds run a second managed child — the `mtg-multi` binary
|
fix(mtproto): stop dropping connections on client/inbound edits; add live updates + ad-tag (#5838)
* fix(mtproto): split the mtg fingerprint into structural and secrets parts
A reordered clients array in the stored settings used to read as a config
change because the fingerprint concatenated secrets in array order, and one
opaque fingerprint could not tell a restart-worthy change (bind address,
fronting, throttle) from a secret-set change a reload-capable mtg can absorb
in place. Sort the secret pairs so order stops mattering, and split the value
so the upcoming hot-reload path can decide between keeping, reloading, and
restarting the process.
* fix(mtproto): stop restarting mtg on every inbound edit
Saving an mtproto inbound tore down and respawned its mtg sidecar even when
nothing material changed, dropping every live Telegram connection: the update
path pushed DelInbound+AddInbound, and Remove deletes the manager's map entry,
so Ensure's fingerprint no-op gate could never fire. Route mtproto updates
through a single Ensure call so an edit that leaves the generated TOML alone
keeps the process, and only real config changes restart it.
Capturing the pre-edit protocol also fixes a latent leak: changing an
inbound's protocol away from mtproto never stopped the sidecar, because the
snapshot handed to the runtime already carried the new protocol and the
removal took the xray branch, leaving an orphaned mtg holding the port.
An mtproto push failure no longer requests an xray restart - xray cannot fix
the sidecar, and the 10s reconcile job self-heals it.
The regression test fakes mtg by re-executing the test binary, counting
spawns through a pid file: an unchanged save and a remark-only edit must keep
the process, a re-keyed secret must restart it.
* fix(mtproto): exclude depleted clients from the reconcile job to match the sync push
The 10s reconcile job derived mtg secret sets from raw inbound settings while
the interactive push filtered clients through buildRuntimeInboundForAPI, which
drops client_traffics-disabled (depleted or expired) clients. The two paths
therefore disagreed on the fingerprint - each disagreement one needless mtg
restart dropping live connections - and worse, the job kept serving depleted
clients' secrets indefinitely, so running out of traffic never actually cut an
mtproto client's access.
DesiredMtprotoInstances now builds the job's desired state with the same
depletion overlay the push uses (one bulk client_traffics query), drops
inbounds whose every secret is filtered away so their sidecar stops, and
AddInbound pushes the filtered payload too so an imported inbound carrying
disabled stats does not seed a fingerprint the next reconcile disagrees with.
* feat(mtproto): hot-reload mtg secrets in place instead of restarting
A client add, removal, re-key, or enable-toggle changes only the [secrets]
section of the generated config, yet the panel could apply it only by killing
and respawning the mtg sidecar, dropping every Telegram connection on that
inbound. Split the ensure decision three ways: an identical config is a no-op,
a secrets-only change rewrites the TOML on the same api port and asks mtg to
hot-swap it via POST /reload, and a structural change (or a failed reload)
falls back to the full stop-and-start.
The reload endpoint is served by the mhsanaei/mtg-multi fork; against an older
binary the POST 404s and the manager restarts exactly as before, so panel and
binary upgrades stay order-independent.
* feat(mtproto): apply single-client edits to the sidecar immediately
Client CRUD on an mtproto inbound was a runtime no-op, so an add, delete,
re-key, or enable-toggle only reached mtg on the next 10s reconcile. With the
sidecar now able to hot-reload, push the change straight after the edit commits:
applyLocalMtproto rebuilds the inbound's filtered client set and re-applies it,
so a new client works within a moment (and, on a reload-capable binary, without
disturbing the others) and deleting the last client stops the process.
The three interactive single-client paths (add, update, delete) call it; bulk
operations still ride the reconcile job, which converges to the same state.
* chore(mtproto): pin mtg-multi to the mhsanaei fork v1.13.3
The reload endpoint the panel now uses lives in the mhsanaei/mtg-multi fork, so
point the source-build pin (DockerInit.sh + both release.yml matrices) at it and
bump to v1.13.3. The install still produces the same mtg-multi binary name, so
the mtg-<os>-<arch> rename and everything downstream are unchanged. Docs and the
package comment note the hot-reload path and its restart fallback.
* feat(mtproto): apply live secret updates via the management API and add ad-tag
Two capabilities the mhsanaei/mtg-multi v1.13.3 fork exposes are now surfaced by
the sidecar manager.
Live updates go through PUT /secrets on the fork's management API instead of
POST /reload: the panel already holds the whole desired set per inbound, so it
sends secrets and the advertising tag as one JSON call that mtg applies
atomically, keeping every unchanged connection and closing only removed or
re-keyed ones. The config file is still written first so a restart or crash
recovery reproduces the state, and any non-200 (an older binary, a refused
connection) still falls back to a full restart.
Per-inbound ad-tag adds an optional 32-hex Telegram advertising tag plus
public-ipv4/public-ipv6 overrides. The ad-tag rides the reloadable secrets
fingerprint, so changing it hot-applies without dropping connections; the public
IPs are proxy-construction parameters and sit in the structural fingerprint, so a
change there restarts the process. Empty public IPs are omitted so mtg
auto-detects the reachable address.
* feat(inbounds): expose the mtproto ad-tag and public IP in the inbound form
Adds an Ad-tag field (validated as 32 hex characters) plus optional Public IPv4
and Public IPv6 overrides to the MTProto inbound form, backed by the same-named
settings the sidecar writes into the mtg config. The public IPs are optional —
left blank, mtg auto-detects the reachable address the ad-tag middle proxy needs.
English strings are added to every locale; the non-English ones carry the
English text until translated and fall back to it meanwhile.
* ci(mtproto): install mtg-multi from prebuilt release binaries
The fork now publishes release archives for every platform we package, so
download and unpack the matching mtg-multi-<ver>-<os>-<arch> binary instead of
compiling it from source with go install. Faster builds and no toolchain step,
and the archive's platform labels line up with our matrix; the produced
mtg-<os>-<arch> filenames are unchanged.
* i18n(mtproto): localize the ad-tag and public IP strings
The six mtgAdTag*/mtgPublicIp* keys shipped with English text in every locale as
a placeholder. Translate them into the twelve non-English locales (Arabic,
Spanish, Persian, Indonesian, Japanese, Portuguese-BR, Russian, Turkish,
Ukrainian, Vietnamese, and Simplified/Traditional Chinese); en-US is unchanged.
* retired goreportcard.com
2026-07-06 16:13:24 -07:00
|
|
|
(`github.com/mhsanaei/mtg-multi`, a multi-secret fork built from source;
|
2026-07-06 07:04:32 -07:00
|
|
|
`internal/mtproto/`) — outside Xray, one process per inbound serving each
|
feat(mtproto): per-client ad-tags, management-API auth, and record secret sync
Catch the panel up to the mtg-multi README (v1.14.0):
- Each client can now carry its own 32-hex advertising tag overriding the
inbound-level one. The tag lives on the client (settings JSON is the
source of truth, clients.ad_tag is the UI projection), is rendered into
the fork's [secret-ad-tags] section for active secrets only (mtg rejects
a config whose override names an unknown secret), is pushed per entry
through PUT /secrets, and is part of the reload fingerprint so a tag
edit hot-applies without dropping connections.
- The loopback management API can replace the whole secret set, so every
mtg process now gets a random per-process api-token; the manager sends
it as a bearer token on PUT /secrets and GET /stats and reuses it across
config rewrites, because mtg reads the token only at startup.
- Malformed tags are rejected at every save path and additionally dropped
in InstanceFromInbound: one bad tag would otherwise fail the whole
generated config and take every client of the inbound down with it.
- SyncInbound never copied a re-keyed mtproto secret into the canonical
clients table, so the clients page and subscription links kept serving
the old secret, which mtg then rejects. It is now guarded-copied like
the other credentials.
2026-07-07 03:00:43 -07:00
|
|
|
client's FakeTLS secret via the fork's `[secrets]` section (plus per-client
|
|
|
|
|
ad-tags via `[secret-ad-tags]`). Client and ad-tag edits are hot-applied
|
|
|
|
|
through the fork's management API (`PUT /secrets`, bearer-token guarded) so
|
|
|
|
|
connections survive; the manager falls back to a process restart on older
|
|
|
|
|
binaries.
|
2026-06-27 06:42:11 -07:00
|
|
|
- Storage: SQLite by default (`/etc/x-ui/x-ui.db` on Linux; the executable dir on
|
|
|
|
|
Windows), PostgreSQL optional (`XUI_DB_TYPE` / `XUI_DB_DSN`). The CGo SQLite
|
|
|
|
|
driver (`mattn/go-sqlite3`) needs a C compiler — `CGO_ENABLED=0` builds fail.
|
|
|
|
|
- Frontend: React 19 + Ant Design 6 + Vite 8 + TypeScript in `frontend/`,
|
|
|
|
|
built into `internal/web/dist/` (gitignored) and embedded via `embed.FS`.
|
|
|
|
|
|
|
|
|
|
## Repo map
|
|
|
|
|
- `main.go` — entry point + `x-ui` CLI (run, migrate, migrate-db, setting, cert).
|
|
|
|
|
- `internal/config/` — env parsing (XUI_DEBUG, XUI_LOG_LEVEL, XUI_LOG_FOLDER,
|
|
|
|
|
XUI_BIN_FOLDER, XUI_SKIP_HSTS, XUI_PORT, XUI_DB_*).
|
|
|
|
|
- `internal/database/` + `internal/database/model/` — GORM schema (Inbound,
|
|
|
|
|
Client, Setting, User), inbound Protocol enum, AutoMigrate + hand-written
|
|
|
|
|
migrations in `db.go`.
|
|
|
|
|
- `internal/xray/` — Xray child-process lifecycle, config generation, gRPC API.
|
2026-07-06 07:04:32 -07:00
|
|
|
- `internal/mtproto/` — MTProto inbounds via the bundled `mtg-multi` binary.
|
2026-06-27 06:42:11 -07:00
|
|
|
- `internal/sub/` — subscription server (raw / JSON / Clash).
|
|
|
|
|
- `internal/eventbus/` — in-process pub/sub (outbound/node health, xray.crash,
|
|
|
|
|
cpu.high, memory.high, login.attempt).
|
|
|
|
|
- `internal/logger/`, `internal/util/` (link, crypto, sys, ldap, …),
|
|
|
|
|
`internal/tunnelmonitor/` — shared infrastructure.
|
|
|
|
|
- `internal/web/` — Gin server (embeds `dist/` + `translation/`).
|
|
|
|
|
- `controller/` — panel + REST API handlers; OpenAPI at /panel/api/openapi.json.
|
|
|
|
|
- `service/` — business logic (InboundService, SettingService, XrayService,
|
|
|
|
|
node sync); subpackages tgbot/, email/, outbound/, panel/, integration/.
|
|
|
|
|
- `job/` — cron jobs (traffic, fail2ban IP-limit, node heartbeat/sync, LDAP).
|
|
|
|
|
- `middleware/`, `entity/`, `global/`, `session/` (CSRF), `network/`,
|
|
|
|
|
`runtime/` (master/sub-node over mTLS), `websocket/`.
|
|
|
|
|
- `locale/` + `translation/` — i18n, 13 embedded locale JSON files.
|
|
|
|
|
- `frontend/` — React + TS source (see `frontend/CLAUDE.md`).
|
|
|
|
|
- `tools/openapigen/` — Go generator that emits frontend types + Zod/JSON schemas
|
|
|
|
|
into `frontend/src/generated/` from Go structs. The OpenAPI doc itself
|
|
|
|
|
(`frontend/public/openapi.json`) is assembled from those + `endpoints.ts` by
|
|
|
|
|
`frontend/scripts/build-openapi.mjs`.
|
|
|
|
|
|
|
|
|
|
## Hard rules (non-negotiable)
|
|
|
|
|
- NO `//` line comments in committed Go/TS. Names carry meaning; rename instead
|
|
|
|
|
of annotating. Exempt: `//go:build`, `//go:generate`, and other directives.
|
|
|
|
|
HTML `<!-- -->` is fine. (A linter cannot enforce this — you must.)
|
|
|
|
|
- New `g.POST`/`g.GET` in `internal/web/controller/` REQUIRES a matching entry
|
|
|
|
|
in `frontend/src/pages/api-docs/endpoints.ts`, then `make gen` (or
|
|
|
|
|
`cd frontend && npm run gen`). It is a hand-maintained registry — nothing checks
|
|
|
|
|
it against the Go routes, so an omitted route silently vanishes from the docs.
|
|
|
|
|
- Response examples come from Go struct `example:` tags via `tools/openapigen` —
|
|
|
|
|
never hand-write them. A new struct must be added to openapigen's `StructAllow`
|
|
|
|
|
allowlist (`tools/openapigen/main.go`) or it is silently omitted from
|
|
|
|
|
schemas/examples (and `build-openapi.mjs` then fails on the missing schema).
|
|
|
|
|
- A new English i18n key must be added to EVERY locale JSON in
|
|
|
|
|
`internal/web/translation/` (13 files). Missing keys fall back to en-US (or
|
|
|
|
|
render the raw key if absent there too); nothing fails the build, so they are
|
|
|
|
|
easy to miss.
|
|
|
|
|
- DB / model changes require a migration in `internal/database/db.go`.
|
|
|
|
|
- Conventional-commit prefixes (`feat`, `fix`, `refactor`, `chore`, `docs`,
|
|
|
|
|
`style`): `<area>: short imperative summary`, then a body explaining the why.
|
|
|
|
|
|
|
|
|
|
## Go conventions
|
|
|
|
|
- Stdlib `testing` only (no testify). Table-driven, `t.Run` subtests,
|
|
|
|
|
`t.Helper()` on helpers. Assert the exact value / typed error / emitted
|
|
|
|
|
string, never just `err != nil`. Prefer real deps over mocks: throwaway DB via
|
|
|
|
|
`database.InitDB(filepath.Join(t.TempDir(), "x-ui.db"))` +
|
|
|
|
|
`t.Cleanup(func() { _ = database.CloseDB() })`; `httptest` for HTTP.
|
|
|
|
|
`internal/sub`'s `initSubDB(t)` is the template.
|
|
|
|
|
- Code must pass `golangci-lint run` (gofumpt + goimports formatting): `make lint`.
|
|
|
|
|
|
|
|
|
|
## Frontend conventions (summary; full version in frontend/CLAUDE.md)
|
|
|
|
|
- Ant Design 6 only — no Tailwind/shadcn. Targeted tweaks, not rewrites.
|
|
|
|
|
- TS strict; `@typescript-eslint/no-explicit-any` is an error. Zod schemas in
|
|
|
|
|
`src/schemas/` are the source of truth; infer types with `z.infer`, never
|
|
|
|
|
hand-write. Do not edit `src/generated/`.
|
|
|
|
|
- Editing `frontend/src` does NOT change what users see until the Vite build is
|
|
|
|
|
regenerated into `internal/web/dist/`. In `XUI_DEBUG=true`, HTML is served from
|
|
|
|
|
the frozen embedded FS but JS/CSS off disk — after `npm run build` you MUST
|
|
|
|
|
restart `go run .` or you get a blank page with 404s.
|
|
|
|
|
- After touching share-link logic (`src/lib/xray/`), run `npm run test` (golden
|
|
|
|
|
fixtures); regenerate snapshots (`npx vitest run -u`) only for intentional
|
|
|
|
|
output changes, never to make a red test green.
|
|
|
|
|
|
|
|
|
|
## Build, test, verify
|
|
|
|
|
Run `make help` for all targets. The full local gate that mirrors CI:
|
|
|
|
|
|
|
|
|
|
make verify
|
|
|
|
|
|
|
|
|
|
Common targets: `make gen` (regenerate Zod/OpenAPI), `make lint` (Go + frontend),
|
|
|
|
|
`make test` (Go `-shuffle=on` + frontend), `make race`, `make build`. See `Makefile`.
|
|
|
|
|
|
|
|
|
|
## Definition of done (before opening a PR)
|
|
|
|
|
1. `make gen` and confirm `git diff` on `frontend/src/generated` +
|
|
|
|
|
`frontend/public/openapi.json` is clean.
|
|
|
|
|
2. `make verify` passes.
|
|
|
|
|
3. Diff is focused; refactors are separate from feature work.
|