fix: address open bug reports (#4539, #4538, #4535, #4531, #4515) (#4545)
* fix: hash-storage panic on SIGHUP and seeder dup-key on cold restart (#4539)
Two bugs that combine into an unrecoverable crash loop after a user
enables the Telegram bot in settings on a fresh install.
1. CheckHashStorageJob.Run panics with a nil pointer dereference. The
cron job is scheduled whenever settings say the bot is enabled, but
the package-level hash storage is only initialized inside
Tgbot.Start, which StartPanelOnly intentionally skips
(startTgBot=false). Toggling the bot on via the panel triggers
SIGHUP, the storage stays nil, and the cron fires 2 minutes later
and panics, exiting 2.
2. seedClientsFromInboundJSON is not idempotent. The fresh-install
early-return path recorded only UserPasswordHash + ApiTokensTable,
never ClientsTable. After the admin adds clients via the panel
(which writes to the clients table through SyncInbound), the next
start runs the seeder for the first time, finds matching emails
already in the table, and fails with SQLSTATE 23505 on
idx_clients_email, turning the panic above into an unrecoverable
crash loop on PostgreSQL.
Fixes:
- web/job/check_hash_storage.go: nil-check the storage before calling
RemoveExpiredHashes.
- database/db.go: in the fresh-install early-return path, also record
ClientsTable so the seeder never re-runs against panel-added data.
- database/db.go: hydrate seedClientsFromInboundJSON's byEmail cache
from existing rows so it merges instead of inserting when a row with
the same email already lives in the clients table.
Regression tests cover both paths.
Closes #4539
* fix(clients): preserve protocol-specific credentials across multi-inbound syncs (#4538)
fillProtocolDefaults only populates the credential relevant to the
inbound's protocol (c.ID for VLESS, c.Auth for Hysteria, c.Password
for Trojan/Shadowsocks). Each inbound's settings.clients JSON
therefore carries the same client with only one of those fields set.
SyncInbound's update path was unconditionally copying every credential
column from incoming to the existing clients row, so the second sync
(e.g. Hysteria after VLESS) would write UUID="" over a valid VLESS
UUID and Auth="" the other way around. The next GetXrayConfig then
emitted VLESS client entries with no "id" field, and xray-core
crashed on startup with "common/uuid: invalid UUID:".
Guard UUID/Password/Auth/Flow/Security/Reverse against empty
overwrites so each protocol's sync only writes the credentials it
actually owns. Other fields (LimitIP, TotalGB, Comment, etc.) keep
the existing copy-everything behavior so admins can still clear them
through the panel.
Regression test in client_sync_multiprotocol_test.go.
Closes #4538
* fix(expiry): show delayed-start countdown in subscribe and client info (#4535)
A client with "start after first use" expiry stores the duration as a
negative number of milliseconds (e.g. -86400000 = 1 day after first
connect). The clients page row already renders this correctly as
"Delayed start: 1d", but two other surfaces treated negative values as
zero and rendered them as unlimited:
- Subscription header: the index==0 / index>0 branches in subService,
subClashService and subJsonService only carried ExpiryTime forward
when > 0, so traffic.ExpiryTime stayed at zero and the header sent
expire=0. Every imported client appeared to have no expiry, and the
built-in subscribe page rendered the "unlimited" tag.
- ClientInfoModal: both the expiryLabel helper and the rendering check
treated <= 0 as the "no expiry" branch, so the modal showed an
infinity tag instead of "Delayed start: Nd".
Add subscriptionExpiryFromClient to map negative durations onto a
"now + |value|" timestamp so subscription clients see an actual expiry
they can count down from. Update ClientInfoModal's helper and render
to match the clients-page convention.
Regression test in subService_test.go covers the helper.
Refs #4535
* feat(clash): emit xhttp and httpupgrade transports in subscription (#4531)
applyTransport's switch only covered tcp/ws/grpc; xhttp and
httpupgrade inbounds fell through to the default branch and returned
false. buildProxy then returned a nil map and the inbound was dropped
from the Clash subscription. When the subscription only contained
xhttp/httpupgrade inbounds, the proxies list ended up empty and the
client saw a 404 (or an "Error!" body on older builds), then refused
to parse.
Add a case for each, mapping the inbound's stream settings onto the
Mihomo-format opts blocks:
xhttp -> xhttp-opts: { path, host, mode }
httpupgrade -> http-upgrade-opts: { path, headers: { Host } }
Host falls back to the headers map when the dedicated `host` field is
empty, matching the existing ws behavior.
Closes #4531
* fix(online): refresh online-clients list even when no WS frontend is connected (#4515)
XrayTrafficJob and NodeTrafficSyncJob both gated the entire
post-traffic-write block behind websocket.HasClients() to skip
expensive broadcasts when no browser is open. The block included the
RefreshOnlineClientsFromMap call that keeps the in-memory
p.onlineClients list current.
Several non-WS consumers read that same list:
- Telegram bot (tgbot.go calls p.GetOnlineClients in 3 places)
- REST GET /panel/api/onlines (returned to API callers)
- Internal alerts that check whether a client is online
When no browser was watching the dashboard, the list went stale and
stayed empty, so the bot reported "nobody online" and the onlines API
returned [] even when xray had active sessions.
Move RefreshOnlineClientsFromMap above the HasClients guard so the
in-memory list is always fresh. Only the actual BroadcastTraffic /
BroadcastClientStats / BroadcastOutbounds calls (and the
GetAllClientTraffics / GetInboundsTrafficSummary work that feeds them)
remain gated by HasClients.
Closes #4515
* fix: address copilot review on #4545
Two issues raised by the Copilot review:
1) subscriptionExpiryFromClient called time.Now() per invocation.
Two clients with the same delayed-start duration normalized to
timestamps a few milliseconds apart, so the aggregator's
"if normalized != traffic.ExpiryTime" check tripped and the
subscription header expire= dropped back to 0 — the exact bug
the helper was meant to fix, just one client later.
Take nowMs as a parameter; each of GetSubs / GetClash / GetConfig
captures one timestamp per request and reuses it.
2) Guarding Flow against empty incoming values in SyncInbound
prevented a user from ever clearing a VLESS flow via the panel.
FlowOverride on client_inbounds is the per-inbound mechanism that
already preserves flow correctly across protocols, so the guard
on the shared clients.flow column is the wrong place.
Drop the Flow guard, keep the rest (UUID/Password/Auth/Security/
Reverse — none of which have a per-inbound override column).
Adds a regression test that asserts clearing flow on the owning
inbound makes ListForInbound return flow="".
The existing cross-protocol test is rewritten to assert on the
user-visible behavior (ListForInbound flow) instead of the shared
clients.flow column.
2026-05-24 15:08:06 -07:00
|
|
|
package database
|
|
|
|
|
|
|
|
|
|
import (
|
|
|
|
|
"encoding/json"
|
|
|
|
|
"path/filepath"
|
2026-05-28 09:20:34 -07:00
|
|
|
"regexp"
|
fix: address open bug reports (#4539, #4538, #4535, #4531, #4515) (#4545)
* fix: hash-storage panic on SIGHUP and seeder dup-key on cold restart (#4539)
Two bugs that combine into an unrecoverable crash loop after a user
enables the Telegram bot in settings on a fresh install.
1. CheckHashStorageJob.Run panics with a nil pointer dereference. The
cron job is scheduled whenever settings say the bot is enabled, but
the package-level hash storage is only initialized inside
Tgbot.Start, which StartPanelOnly intentionally skips
(startTgBot=false). Toggling the bot on via the panel triggers
SIGHUP, the storage stays nil, and the cron fires 2 minutes later
and panics, exiting 2.
2. seedClientsFromInboundJSON is not idempotent. The fresh-install
early-return path recorded only UserPasswordHash + ApiTokensTable,
never ClientsTable. After the admin adds clients via the panel
(which writes to the clients table through SyncInbound), the next
start runs the seeder for the first time, finds matching emails
already in the table, and fails with SQLSTATE 23505 on
idx_clients_email, turning the panic above into an unrecoverable
crash loop on PostgreSQL.
Fixes:
- web/job/check_hash_storage.go: nil-check the storage before calling
RemoveExpiredHashes.
- database/db.go: in the fresh-install early-return path, also record
ClientsTable so the seeder never re-runs against panel-added data.
- database/db.go: hydrate seedClientsFromInboundJSON's byEmail cache
from existing rows so it merges instead of inserting when a row with
the same email already lives in the clients table.
Regression tests cover both paths.
Closes #4539
* fix(clients): preserve protocol-specific credentials across multi-inbound syncs (#4538)
fillProtocolDefaults only populates the credential relevant to the
inbound's protocol (c.ID for VLESS, c.Auth for Hysteria, c.Password
for Trojan/Shadowsocks). Each inbound's settings.clients JSON
therefore carries the same client with only one of those fields set.
SyncInbound's update path was unconditionally copying every credential
column from incoming to the existing clients row, so the second sync
(e.g. Hysteria after VLESS) would write UUID="" over a valid VLESS
UUID and Auth="" the other way around. The next GetXrayConfig then
emitted VLESS client entries with no "id" field, and xray-core
crashed on startup with "common/uuid: invalid UUID:".
Guard UUID/Password/Auth/Flow/Security/Reverse against empty
overwrites so each protocol's sync only writes the credentials it
actually owns. Other fields (LimitIP, TotalGB, Comment, etc.) keep
the existing copy-everything behavior so admins can still clear them
through the panel.
Regression test in client_sync_multiprotocol_test.go.
Closes #4538
* fix(expiry): show delayed-start countdown in subscribe and client info (#4535)
A client with "start after first use" expiry stores the duration as a
negative number of milliseconds (e.g. -86400000 = 1 day after first
connect). The clients page row already renders this correctly as
"Delayed start: 1d", but two other surfaces treated negative values as
zero and rendered them as unlimited:
- Subscription header: the index==0 / index>0 branches in subService,
subClashService and subJsonService only carried ExpiryTime forward
when > 0, so traffic.ExpiryTime stayed at zero and the header sent
expire=0. Every imported client appeared to have no expiry, and the
built-in subscribe page rendered the "unlimited" tag.
- ClientInfoModal: both the expiryLabel helper and the rendering check
treated <= 0 as the "no expiry" branch, so the modal showed an
infinity tag instead of "Delayed start: Nd".
Add subscriptionExpiryFromClient to map negative durations onto a
"now + |value|" timestamp so subscription clients see an actual expiry
they can count down from. Update ClientInfoModal's helper and render
to match the clients-page convention.
Regression test in subService_test.go covers the helper.
Refs #4535
* feat(clash): emit xhttp and httpupgrade transports in subscription (#4531)
applyTransport's switch only covered tcp/ws/grpc; xhttp and
httpupgrade inbounds fell through to the default branch and returned
false. buildProxy then returned a nil map and the inbound was dropped
from the Clash subscription. When the subscription only contained
xhttp/httpupgrade inbounds, the proxies list ended up empty and the
client saw a 404 (or an "Error!" body on older builds), then refused
to parse.
Add a case for each, mapping the inbound's stream settings onto the
Mihomo-format opts blocks:
xhttp -> xhttp-opts: { path, host, mode }
httpupgrade -> http-upgrade-opts: { path, headers: { Host } }
Host falls back to the headers map when the dedicated `host` field is
empty, matching the existing ws behavior.
Closes #4531
* fix(online): refresh online-clients list even when no WS frontend is connected (#4515)
XrayTrafficJob and NodeTrafficSyncJob both gated the entire
post-traffic-write block behind websocket.HasClients() to skip
expensive broadcasts when no browser is open. The block included the
RefreshOnlineClientsFromMap call that keeps the in-memory
p.onlineClients list current.
Several non-WS consumers read that same list:
- Telegram bot (tgbot.go calls p.GetOnlineClients in 3 places)
- REST GET /panel/api/onlines (returned to API callers)
- Internal alerts that check whether a client is online
When no browser was watching the dashboard, the list went stale and
stayed empty, so the bot reported "nobody online" and the onlines API
returned [] even when xray had active sessions.
Move RefreshOnlineClientsFromMap above the HasClients guard so the
in-memory list is always fresh. Only the actual BroadcastTraffic /
BroadcastClientStats / BroadcastOutbounds calls (and the
GetAllClientTraffics / GetInboundsTrafficSummary work that feeds them)
remain gated by HasClients.
Closes #4515
* fix: address copilot review on #4545
Two issues raised by the Copilot review:
1) subscriptionExpiryFromClient called time.Now() per invocation.
Two clients with the same delayed-start duration normalized to
timestamps a few milliseconds apart, so the aggregator's
"if normalized != traffic.ExpiryTime" check tripped and the
subscription header expire= dropped back to 0 — the exact bug
the helper was meant to fix, just one client later.
Take nowMs as a parameter; each of GetSubs / GetClash / GetConfig
captures one timestamp per request and reuses it.
2) Guarding Flow against empty incoming values in SyncInbound
prevented a user from ever clearing a VLESS flow via the panel.
FlowOverride on client_inbounds is the per-inbound mechanism that
already preserves flow correctly across protocols, so the guard
on the shared clients.flow column is the wrong place.
Drop the Flow guard, keep the rest (UUID/Password/Auth/Security/
Reverse — none of which have a per-inbound override column).
Adds a regression test that asserts clearing flow on the owning
inbound makes ListForInbound return flow="".
The existing cross-protocol test is rewritten to assert on the
user-visible behavior (ListForInbound flow) instead of the shared
clients.flow column.
2026-05-24 15:08:06 -07:00
|
|
|
"testing"
|
|
|
|
|
|
refactor: focused service files, leaf subpackages, and an internal/ layout (#5167)
* refactor(service): split client.go into focused files
client.go had grown to 4455 lines mixing ~10 responsibilities. Split it
verbatim into cohesive same-package files (no behavior change):
client.go foundation: ClientService, ClientWithAttachments,
ClientCreatePayload, ErrClientNotInInbound, sqlInChunk
client_locks.go inbound mutation locks, delete tombstones, compactOrphans
client_lookup.go read-only lookups (GetByID, List, EffectiveFlow, ...)
client_link.go inbound association sync (SyncInbound, DetachInbound, ...)
client_crud.go single-client CRUD + validation + protocol defaults
client_inbound_apply.go low-level inbound-settings mutators + by-email setters
client_bulk.go bulk attach/detach/adjust/delete/create + DelDepleted
client_traffic.go traffic-reset paths
client_groups.go client group management
client_paging.go paged listing, filtering, sorting, summary
Every declaration moved unchanged (verified: identical func/type/const/var
signature set before vs after). Imports redistributed per file via goimports.
go build ./..., go vet, and go test ./web/service/... all pass.
* refactor(service): split inbound.go into focused files
inbound.go was 4100 lines. Split it verbatim into cohesive same-package
files (no behavior change):
inbound.go core inbound CRUD + InboundService (keeps pkg doc)
inbound_protocol.go protocol / stream capability helpers
inbound_node.go node/runtime/remote coordination + online tracking
inbound_traffic.go traffic accounting, reset, client stats
inbound_client_ips.go per-client IP tracking
inbound_clients.go client lookups within inbounds + copy-clients
inbound_disable.go auto-disable invalid inbounds/clients
inbound_migration.go DB migrations
inbound_sublink.go subscription link providers
inbound_util.go generic slice/string helpers
Identical func/type/const/var signature set before vs after; package doc
comment preserved on inbound.go. Imports redistributed via goimports.
Build, vet, and go test ./web/service/... all pass.
* refactor(service): split tgbot.go into focused files
tgbot.go was 3738 lines dominated by a 1246-line answerCallback. Split it
verbatim into cohesive same-package files (no behavior change):
tgbot.go lifecycle, bot setup, caches, small utils
tgbot_router.go incoming update / command / callback dispatch
tgbot_send.go outbound messaging primitives
tgbot_client.go client views, actions, subscription links
tgbot_inbound.go inbound listing / pickers
tgbot_report.go server usage, exhausted, online, backups, notifications
Identical func/type/const/var signature set before vs after. Imports
redistributed via goimports. Build, vet, and go test ./web/service/... pass.
* refactor(client): dedupe single-field by-email setters
ResetClientIpLimitByEmail, ResetClientExpiryTimeByEmail, and
ResetClientTrafficLimitByEmail shared an identical ~50-line body that
resolves the inbound by email, confirms the client exists, rewrites a
single-client settings payload, and delegates to UpdateInboundClient.
Extract that into applyClientFieldByEmail(inboundSvc, email, mutate) and
reduce each setter to a 3-line wrapper. Behavior is unchanged: same checks
and error strings, same single-client payload contract, same totalGB guard.
SetClientTelegramUserID (resolves by traffic id, different error text) and
ToggleClientEnableByEmail/SetClientEnableByEmail (different return shape and
a pre-read of the old state) intentionally keep their own bodies.
* refactor(service): extract panel/ subpackage
Move the panel-administration leaf services out of the flat service
package into web/service/panel/ (package panel):
user.go UserService (auth / 2FA / LDAP)
panel.go PanelService (restart / self-update) + version helpers
panel_other.go non-unix RestartPanel
panel_unix.go unix RestartPanel
api_token.go ApiTokenService
websocket.go WebSocketService
panel_test.go version/shellQuote unit tests
These are leaves: they depend on core (SettingService, Release) but no
core file references them, so the extraction creates no import cycle.
Core references are now qualified (service.SettingService, service.Release);
callers in main.go, web/web.go, and web/controller/* updated to panel.*.
Build, vet, and go test ./web/... pass.
* refactor(service): extract integration/ subpackage
Move the external-provider integration leaves into web/service/integration/
(package integration):
warp.go WarpService (Cloudflare WARP)
nord.go NordService (NordVPN)
custom_geo.go CustomGeoService (custom geo asset management)
*_test.go custom_geo / panel-proxy tests
These depend on core (SettingService, ServerService, XraySettingService) but
no core file references them. xray_setting.go stays in core because it calls
the unexported SettingService.saveSetting. The shared isBlockedIP SSRF helper
(used by core url_safety.go and by custom_geo) now has a small copy in each
package rather than being exported. Core references qualified; callers in
web/web.go, web/job/*, and web/controller/* updated to integration.*.
Build, vet, and go test ./web/... pass.
* refactor(service): extract tgbot/ subpackage
Move the Telegram bot (6 files + test) into web/service/tgbot/ (package
tgbot). It is a leaf: it embeds five core services (Inbound/Client/Setting/
Server/Xray) and the core never references it, so no import cycle.
To support the package boundary without changing behavior:
- core exposes XrayProcess() *xray.Process so tgbot keeps calling the
exact same running-process methods it used via the package-level `p`;
- three core methods tgbot calls are exported: ClientService.checkIs-
EnabledByEmail -> CheckIsEnabledByEmail, InboundService.getAllEmails ->
GetAllEmails (callers updated in-package);
- tgbot's embedded-field types and the few core type refs (Status,
ClientCreatePayload, SanitizePublicHTTPURL) are now service-qualified.
Callers in main.go, web/web.go, web/job/*, and web/controller/* updated to
tgbot.*. Build, vet, and go test ./web/... pass.
* refactor(service): extract outbound/ subpackage
OutboundService (outbound.go) imports only neutral packages (config,
database, model, xray) and its production code is referenced by no core or
sibling service file — only by web/controller/xray_setting.go and
web/job/xray_traffic_job.go. Move it to web/service/outbound/ (package
outbound); no core qualification needed inside. Callers updated to outbound.*.
The one coupling was a tiny pure test helper, outboundsContainTag, used by
both outbound.go and the core outbound_subscription_test.go; it now has a
small copy in that test file rather than being shared across the boundary.
Build, vet, and go test ./web/... pass.
* refactor(util): move wireguard into its own subpackage
util/wireguard.go was the lone file of the root `util` package (24 lines,
one exported func GenerateWireguardKeypair), while every other util concern
lives in a focused subpackage (util/common, util/crypto, util/netsafe, ...).
Move it to util/wireguard/ (package wireguard) for consistency; its only
importer, web/service/integration/warp.go, is updated. The root `util`
package no longer exists.
* refactor(sub): drop redundant sub prefix from filenames
Inside package sub the subXxx.go prefix just repeats the package name
(like client_*.go did inside service). Rename for consistency; content and
type names are unchanged:
subController.go -> controller.go
subService.go -> service.go
subClashService.go -> clash_service.go
subJsonService.go -> json_service.go
(+ matching _test.go files)
* refactor(controller): rename xui.go -> spa.go
XUIController serves the panel's single-page-app shell; spa.go names that
role plainly (the other controller files are domain-named). File rename only
— the type stays XUIController. api_docs_test.go keys route base paths by
filename, so its "xui.go" case is updated to "spa.go".
* refactor: move backend packages under internal/
Adopt the idiomatic Go application layout: the backend packages now live
under internal/ (a boundary the toolchain enforces), signalling private
implementation instead of a library-style flat root. No runtime behavior
changes — only import paths and a few build/config paths move.
Moved: config, database, logger, mtproto, sub, util, web, xray -> internal/.
main.go stays at the repo root and tools/openapigen stays under tools/ (both
still import internal/* because the internal rule keys off the module root).
The module path github.com/mhsanaei/3x-ui/v3 is unchanged; 149 .go files had
their import prefix rewritten to .../internal/<pkg>.
Couplings the Go compiler can't see, updated to the new layout:
- frontend i18n imports of web/translation (react.ts, setup.components.ts)
- vite outDir + eslint/tsconfig ignore globs -> internal/web/dist
- Dockerfile COPY paths for web/dist and web/translation
- locale.go os.DirFS("web") disk fallback -> "internal/web"
- .gitignore and ci.yml go:embed stub for internal/web/dist
- api_docs_test.go repo-root relative walk (one level deeper)
- tools/openapigen filesystem package paths; ApiTokenView repointed to the
web/service/panel subpackage and codegen regenerated (clears a stale
type the ci.yml codegen check was failing on)
Verified: go build/vet/test (all packages), and frontend typecheck, lint,
vitest (478 tests), and production build into internal/web/dist.
* fix(config): keep test runs from writing logs into the source tree
GetLogFolder() returns a CWD-relative "./log" on Windows. Under `go test`
the working directory is each package's own folder, so InitLogger (called by
tests in web/job, web/service, xray, web/websocket) created stray log/
directories scattered through the source tree (e.g. internal/web/job/log/).
Redirect to a shared temp folder when testing.Testing() reports a test run.
Production behavior is unchanged: Windows still uses ./log next to the binary
and Linux /var/log/x-ui. The log files were always gitignored (*.log) and
never committed; this just stops the noise at the source.
* docs: move subscription-template guide out of root into docs/
sub_templates/ was a top-level folder holding only a README and no actual
templates (3x-ui ships none by design), referenced nowhere and unlinked from
any doc — it read like an empty placeholder cluttering the repo root.
Move the guide to docs/custom-subscription-templates.md (a proper docs home),
reword its intro to read as documentation rather than a folder note, link it
from the Features list in README.md, and drop the empty sub_templates/ folder.
* fix: update stale web/ path references after the internal/ move
The internal/ migration rewrote Go import paths but left some references to
the old top-level layout in docs, comments, and a few runtime disk paths.
Functional (dev-mode only): the disk-serving fallbacks that read the Vite
build from disk when running from source still pointed at web/dist/, which
moved to internal/web/dist/ — so `os.DirFS`/`os.Stat`/`os.ReadFile` in
internal/web/web.go and internal/sub/{sub,controller}.go are corrected.
Production was unaffected (it serves the embedded FS; verified by the Docker
build), but `go run` with a live frontend build silently fell back to embed.
Docs/comments: frontend/README.md, CONTRIBUTING.md, the claude-issue-bot and
release workflows, the openapigen -root help text, and assorted Go comments
now reference internal/web, internal/database, internal/sub, internal/xray,
etc. Package-name mentions (the "web" package), root paths (main.go,
frontend/, install scripts, /etc/x-ui), routes (/panel/api/xray), and the
historical "web/assets no longer exists" note were intentionally left as-is.
* refactor(web): remove the legacy /xui -> /panel redirect middleware
RedirectMiddleware existed only for backward compatibility with the old
`/xui` URL scheme (301-redirecting /xui and /xui/API to /panel and
/panel/api). That cutover was long ago, so drop the middleware, its
registration in initRouter, and the now-inaccurate "URL redirection"
mention in the middleware package doc. Old /xui URLs now 404 like any other
unknown path. HTTPS auto-redirect and auth redirects are unrelated and stay.
* build: fix .dockerignore for internal/ layout and exclude runtime dir
- web/dist -> internal/web/dist: the embedded frontend moved under internal/,
so the stale exclude no longer matched and the locally-built dist could be
sent to the build context (the frontend stage rebuilds it fresh anyway).
- exclude x-ui/: the local runtime directory (SQLite db, geo .dat files, xray
binaries, certs — ~150MB) was being shipped into the build context for no
reason. Verified the pattern excludes only the directory and still keeps
x-ui.sh, which the Dockerfile copies to /usr/bin/x-ui.
2026-06-10 06:19:22 -07:00
|
|
|
"github.com/mhsanaei/3x-ui/v3/internal/database/model"
|
fix: address open bug reports (#4539, #4538, #4535, #4531, #4515) (#4545)
* fix: hash-storage panic on SIGHUP and seeder dup-key on cold restart (#4539)
Two bugs that combine into an unrecoverable crash loop after a user
enables the Telegram bot in settings on a fresh install.
1. CheckHashStorageJob.Run panics with a nil pointer dereference. The
cron job is scheduled whenever settings say the bot is enabled, but
the package-level hash storage is only initialized inside
Tgbot.Start, which StartPanelOnly intentionally skips
(startTgBot=false). Toggling the bot on via the panel triggers
SIGHUP, the storage stays nil, and the cron fires 2 minutes later
and panics, exiting 2.
2. seedClientsFromInboundJSON is not idempotent. The fresh-install
early-return path recorded only UserPasswordHash + ApiTokensTable,
never ClientsTable. After the admin adds clients via the panel
(which writes to the clients table through SyncInbound), the next
start runs the seeder for the first time, finds matching emails
already in the table, and fails with SQLSTATE 23505 on
idx_clients_email, turning the panic above into an unrecoverable
crash loop on PostgreSQL.
Fixes:
- web/job/check_hash_storage.go: nil-check the storage before calling
RemoveExpiredHashes.
- database/db.go: in the fresh-install early-return path, also record
ClientsTable so the seeder never re-runs against panel-added data.
- database/db.go: hydrate seedClientsFromInboundJSON's byEmail cache
from existing rows so it merges instead of inserting when a row with
the same email already lives in the clients table.
Regression tests cover both paths.
Closes #4539
* fix(clients): preserve protocol-specific credentials across multi-inbound syncs (#4538)
fillProtocolDefaults only populates the credential relevant to the
inbound's protocol (c.ID for VLESS, c.Auth for Hysteria, c.Password
for Trojan/Shadowsocks). Each inbound's settings.clients JSON
therefore carries the same client with only one of those fields set.
SyncInbound's update path was unconditionally copying every credential
column from incoming to the existing clients row, so the second sync
(e.g. Hysteria after VLESS) would write UUID="" over a valid VLESS
UUID and Auth="" the other way around. The next GetXrayConfig then
emitted VLESS client entries with no "id" field, and xray-core
crashed on startup with "common/uuid: invalid UUID:".
Guard UUID/Password/Auth/Flow/Security/Reverse against empty
overwrites so each protocol's sync only writes the credentials it
actually owns. Other fields (LimitIP, TotalGB, Comment, etc.) keep
the existing copy-everything behavior so admins can still clear them
through the panel.
Regression test in client_sync_multiprotocol_test.go.
Closes #4538
* fix(expiry): show delayed-start countdown in subscribe and client info (#4535)
A client with "start after first use" expiry stores the duration as a
negative number of milliseconds (e.g. -86400000 = 1 day after first
connect). The clients page row already renders this correctly as
"Delayed start: 1d", but two other surfaces treated negative values as
zero and rendered them as unlimited:
- Subscription header: the index==0 / index>0 branches in subService,
subClashService and subJsonService only carried ExpiryTime forward
when > 0, so traffic.ExpiryTime stayed at zero and the header sent
expire=0. Every imported client appeared to have no expiry, and the
built-in subscribe page rendered the "unlimited" tag.
- ClientInfoModal: both the expiryLabel helper and the rendering check
treated <= 0 as the "no expiry" branch, so the modal showed an
infinity tag instead of "Delayed start: Nd".
Add subscriptionExpiryFromClient to map negative durations onto a
"now + |value|" timestamp so subscription clients see an actual expiry
they can count down from. Update ClientInfoModal's helper and render
to match the clients-page convention.
Regression test in subService_test.go covers the helper.
Refs #4535
* feat(clash): emit xhttp and httpupgrade transports in subscription (#4531)
applyTransport's switch only covered tcp/ws/grpc; xhttp and
httpupgrade inbounds fell through to the default branch and returned
false. buildProxy then returned a nil map and the inbound was dropped
from the Clash subscription. When the subscription only contained
xhttp/httpupgrade inbounds, the proxies list ended up empty and the
client saw a 404 (or an "Error!" body on older builds), then refused
to parse.
Add a case for each, mapping the inbound's stream settings onto the
Mihomo-format opts blocks:
xhttp -> xhttp-opts: { path, host, mode }
httpupgrade -> http-upgrade-opts: { path, headers: { Host } }
Host falls back to the headers map when the dedicated `host` field is
empty, matching the existing ws behavior.
Closes #4531
* fix(online): refresh online-clients list even when no WS frontend is connected (#4515)
XrayTrafficJob and NodeTrafficSyncJob both gated the entire
post-traffic-write block behind websocket.HasClients() to skip
expensive broadcasts when no browser is open. The block included the
RefreshOnlineClientsFromMap call that keeps the in-memory
p.onlineClients list current.
Several non-WS consumers read that same list:
- Telegram bot (tgbot.go calls p.GetOnlineClients in 3 places)
- REST GET /panel/api/onlines (returned to API callers)
- Internal alerts that check whether a client is online
When no browser was watching the dashboard, the list went stale and
stayed empty, so the bot reported "nobody online" and the onlines API
returned [] even when xray had active sessions.
Move RefreshOnlineClientsFromMap above the HasClients guard so the
in-memory list is always fresh. Only the actual BroadcastTraffic /
BroadcastClientStats / BroadcastOutbounds calls (and the
GetAllClientTraffics / GetInboundsTrafficSummary work that feeds them)
remain gated by HasClients.
Closes #4515
* fix: address copilot review on #4545
Two issues raised by the Copilot review:
1) subscriptionExpiryFromClient called time.Now() per invocation.
Two clients with the same delayed-start duration normalized to
timestamps a few milliseconds apart, so the aggregator's
"if normalized != traffic.ExpiryTime" check tripped and the
subscription header expire= dropped back to 0 — the exact bug
the helper was meant to fix, just one client later.
Take nowMs as a parameter; each of GetSubs / GetClash / GetConfig
captures one timestamp per request and reuses it.
2) Guarding Flow against empty incoming values in SyncInbound
prevented a user from ever clearing a VLESS flow via the panel.
FlowOverride on client_inbounds is the per-inbound mechanism that
already preserves flow correctly across protocols, so the guard
on the shared clients.flow column is the wrong place.
Drop the Flow guard, keep the rest (UUID/Password/Auth/Security/
Reverse — none of which have a per-inbound override column).
Adds a regression test that asserts clearing flow on the owning
inbound makes ListForInbound return flow="".
The existing cross-protocol test is rewritten to assert on the
user-visible behavior (ListForInbound flow) instead of the shared
clients.flow column.
2026-05-24 15:08:06 -07:00
|
|
|
)
|
|
|
|
|
|
|
|
|
|
func TestSeedClientsFromInboundJSON_IsIdempotentAgainstExistingClients(t *testing.T) {
|
|
|
|
|
dbDir := t.TempDir()
|
|
|
|
|
t.Setenv("XUI_DB_FOLDER", dbDir)
|
2026-05-31 06:25:05 -07:00
|
|
|
if err := InitDB(filepath.Join(dbDir, "x-ui.db")); err != nil {
|
fix: address open bug reports (#4539, #4538, #4535, #4531, #4515) (#4545)
* fix: hash-storage panic on SIGHUP and seeder dup-key on cold restart (#4539)
Two bugs that combine into an unrecoverable crash loop after a user
enables the Telegram bot in settings on a fresh install.
1. CheckHashStorageJob.Run panics with a nil pointer dereference. The
cron job is scheduled whenever settings say the bot is enabled, but
the package-level hash storage is only initialized inside
Tgbot.Start, which StartPanelOnly intentionally skips
(startTgBot=false). Toggling the bot on via the panel triggers
SIGHUP, the storage stays nil, and the cron fires 2 minutes later
and panics, exiting 2.
2. seedClientsFromInboundJSON is not idempotent. The fresh-install
early-return path recorded only UserPasswordHash + ApiTokensTable,
never ClientsTable. After the admin adds clients via the panel
(which writes to the clients table through SyncInbound), the next
start runs the seeder for the first time, finds matching emails
already in the table, and fails with SQLSTATE 23505 on
idx_clients_email, turning the panic above into an unrecoverable
crash loop on PostgreSQL.
Fixes:
- web/job/check_hash_storage.go: nil-check the storage before calling
RemoveExpiredHashes.
- database/db.go: in the fresh-install early-return path, also record
ClientsTable so the seeder never re-runs against panel-added data.
- database/db.go: hydrate seedClientsFromInboundJSON's byEmail cache
from existing rows so it merges instead of inserting when a row with
the same email already lives in the clients table.
Regression tests cover both paths.
Closes #4539
* fix(clients): preserve protocol-specific credentials across multi-inbound syncs (#4538)
fillProtocolDefaults only populates the credential relevant to the
inbound's protocol (c.ID for VLESS, c.Auth for Hysteria, c.Password
for Trojan/Shadowsocks). Each inbound's settings.clients JSON
therefore carries the same client with only one of those fields set.
SyncInbound's update path was unconditionally copying every credential
column from incoming to the existing clients row, so the second sync
(e.g. Hysteria after VLESS) would write UUID="" over a valid VLESS
UUID and Auth="" the other way around. The next GetXrayConfig then
emitted VLESS client entries with no "id" field, and xray-core
crashed on startup with "common/uuid: invalid UUID:".
Guard UUID/Password/Auth/Flow/Security/Reverse against empty
overwrites so each protocol's sync only writes the credentials it
actually owns. Other fields (LimitIP, TotalGB, Comment, etc.) keep
the existing copy-everything behavior so admins can still clear them
through the panel.
Regression test in client_sync_multiprotocol_test.go.
Closes #4538
* fix(expiry): show delayed-start countdown in subscribe and client info (#4535)
A client with "start after first use" expiry stores the duration as a
negative number of milliseconds (e.g. -86400000 = 1 day after first
connect). The clients page row already renders this correctly as
"Delayed start: 1d", but two other surfaces treated negative values as
zero and rendered them as unlimited:
- Subscription header: the index==0 / index>0 branches in subService,
subClashService and subJsonService only carried ExpiryTime forward
when > 0, so traffic.ExpiryTime stayed at zero and the header sent
expire=0. Every imported client appeared to have no expiry, and the
built-in subscribe page rendered the "unlimited" tag.
- ClientInfoModal: both the expiryLabel helper and the rendering check
treated <= 0 as the "no expiry" branch, so the modal showed an
infinity tag instead of "Delayed start: Nd".
Add subscriptionExpiryFromClient to map negative durations onto a
"now + |value|" timestamp so subscription clients see an actual expiry
they can count down from. Update ClientInfoModal's helper and render
to match the clients-page convention.
Regression test in subService_test.go covers the helper.
Refs #4535
* feat(clash): emit xhttp and httpupgrade transports in subscription (#4531)
applyTransport's switch only covered tcp/ws/grpc; xhttp and
httpupgrade inbounds fell through to the default branch and returned
false. buildProxy then returned a nil map and the inbound was dropped
from the Clash subscription. When the subscription only contained
xhttp/httpupgrade inbounds, the proxies list ended up empty and the
client saw a 404 (or an "Error!" body on older builds), then refused
to parse.
Add a case for each, mapping the inbound's stream settings onto the
Mihomo-format opts blocks:
xhttp -> xhttp-opts: { path, host, mode }
httpupgrade -> http-upgrade-opts: { path, headers: { Host } }
Host falls back to the headers map when the dedicated `host` field is
empty, matching the existing ws behavior.
Closes #4531
* fix(online): refresh online-clients list even when no WS frontend is connected (#4515)
XrayTrafficJob and NodeTrafficSyncJob both gated the entire
post-traffic-write block behind websocket.HasClients() to skip
expensive broadcasts when no browser is open. The block included the
RefreshOnlineClientsFromMap call that keeps the in-memory
p.onlineClients list current.
Several non-WS consumers read that same list:
- Telegram bot (tgbot.go calls p.GetOnlineClients in 3 places)
- REST GET /panel/api/onlines (returned to API callers)
- Internal alerts that check whether a client is online
When no browser was watching the dashboard, the list went stale and
stayed empty, so the bot reported "nobody online" and the onlines API
returned [] even when xray had active sessions.
Move RefreshOnlineClientsFromMap above the HasClients guard so the
in-memory list is always fresh. Only the actual BroadcastTraffic /
BroadcastClientStats / BroadcastOutbounds calls (and the
GetAllClientTraffics / GetInboundsTrafficSummary work that feeds them)
remain gated by HasClients.
Closes #4515
* fix: address copilot review on #4545
Two issues raised by the Copilot review:
1) subscriptionExpiryFromClient called time.Now() per invocation.
Two clients with the same delayed-start duration normalized to
timestamps a few milliseconds apart, so the aggregator's
"if normalized != traffic.ExpiryTime" check tripped and the
subscription header expire= dropped back to 0 — the exact bug
the helper was meant to fix, just one client later.
Take nowMs as a parameter; each of GetSubs / GetClash / GetConfig
captures one timestamp per request and reuses it.
2) Guarding Flow against empty incoming values in SyncInbound
prevented a user from ever clearing a VLESS flow via the panel.
FlowOverride on client_inbounds is the per-inbound mechanism that
already preserves flow correctly across protocols, so the guard
on the shared clients.flow column is the wrong place.
Drop the Flow guard, keep the rest (UUID/Password/Auth/Security/
Reverse — none of which have a per-inbound override column).
Adds a regression test that asserts clearing flow on the owning
inbound makes ListForInbound return flow="".
The existing cross-protocol test is rewritten to assert on the
user-visible behavior (ListForInbound flow) instead of the shared
clients.flow column.
2026-05-24 15:08:06 -07:00
|
|
|
t.Fatalf("InitDB failed: %v", err)
|
|
|
|
|
}
|
|
|
|
|
t.Cleanup(func() { _ = CloseDB() })
|
|
|
|
|
|
|
|
|
|
settings, err := json.Marshal(map[string]any{
|
|
|
|
|
"clients": []any{
|
|
|
|
|
map[string]any{
|
|
|
|
|
"id": "ce8d33df-3a64-4f10-8f9b-91c3a8e0c001",
|
|
|
|
|
"email": "alice@example.com",
|
|
|
|
|
"enable": true,
|
|
|
|
|
"flow": "",
|
|
|
|
|
"subId": "alice-sub",
|
|
|
|
|
"comment": "from-inbound-json",
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
})
|
|
|
|
|
if err != nil {
|
|
|
|
|
t.Fatalf("marshal settings: %v", err)
|
|
|
|
|
}
|
|
|
|
|
inbound := model.Inbound{
|
|
|
|
|
UserId: 1,
|
|
|
|
|
Port: 12345,
|
|
|
|
|
Protocol: model.VLESS,
|
|
|
|
|
Settings: string(settings),
|
|
|
|
|
Tag: "test-inbound",
|
|
|
|
|
}
|
|
|
|
|
if err := db.Create(&inbound).Error; err != nil {
|
|
|
|
|
t.Fatalf("seed inbound: %v", err)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
preExisting := &model.ClientRecord{
|
|
|
|
|
Email: "alice@example.com",
|
|
|
|
|
UUID: "ce8d33df-3a64-4f10-8f9b-91c3a8e0c001",
|
|
|
|
|
SubID: "alice-sub",
|
|
|
|
|
Enable: true,
|
|
|
|
|
Comment: "added-via-api",
|
|
|
|
|
}
|
|
|
|
|
if err := db.Create(preExisting).Error; err != nil {
|
|
|
|
|
t.Fatalf("seed client row: %v", err)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
if err := db.Where("seeder_name = ?", "ClientsTable").Delete(&model.HistoryOfSeeders{}).Error; err != nil {
|
|
|
|
|
t.Fatalf("clear ClientsTable history: %v", err)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
if err := seedClientsFromInboundJSON(); err != nil {
|
|
|
|
|
t.Fatalf("seedClientsFromInboundJSON should be idempotent against existing rows, got: %v", err)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
var count int64
|
|
|
|
|
if err := db.Model(&model.ClientRecord{}).Where("email = ?", "alice@example.com").Count(&count).Error; err != nil {
|
|
|
|
|
t.Fatalf("count clients: %v", err)
|
|
|
|
|
}
|
|
|
|
|
if count != 1 {
|
|
|
|
|
t.Fatalf("alice@example.com should resolve to exactly one row, got %d", count)
|
|
|
|
|
}
|
|
|
|
|
}
|
2026-05-28 09:20:34 -07:00
|
|
|
|
|
|
|
|
func TestNormalizeInboundClientSubId_FillsMissingAndPreservesExisting(t *testing.T) {
|
|
|
|
|
dbDir := t.TempDir()
|
|
|
|
|
t.Setenv("XUI_DB_FOLDER", dbDir)
|
2026-05-31 06:25:05 -07:00
|
|
|
if err := InitDB(filepath.Join(dbDir, "x-ui.db")); err != nil {
|
2026-05-28 09:20:34 -07:00
|
|
|
t.Fatalf("InitDB failed: %v", err)
|
|
|
|
|
}
|
|
|
|
|
t.Cleanup(func() { _ = CloseDB() })
|
|
|
|
|
|
|
|
|
|
settings, err := json.Marshal(map[string]any{
|
|
|
|
|
"clients": []any{
|
|
|
|
|
map[string]any{
|
|
|
|
|
"id": "00000000-0000-0000-0000-000000000001",
|
|
|
|
|
"email": "missing-sub@example.com",
|
|
|
|
|
"subId": "",
|
|
|
|
|
},
|
|
|
|
|
map[string]any{
|
|
|
|
|
"id": "00000000-0000-0000-0000-000000000002",
|
|
|
|
|
"email": "no-sub-key@example.com",
|
|
|
|
|
},
|
|
|
|
|
map[string]any{
|
|
|
|
|
"id": "00000000-0000-0000-0000-000000000003",
|
|
|
|
|
"email": "has-sub@example.com",
|
|
|
|
|
"subId": "keep-me-1234",
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
})
|
|
|
|
|
if err != nil {
|
|
|
|
|
t.Fatalf("marshal settings: %v", err)
|
|
|
|
|
}
|
|
|
|
|
inbound := model.Inbound{
|
|
|
|
|
UserId: 1,
|
|
|
|
|
Port: 23456,
|
|
|
|
|
Protocol: model.VLESS,
|
|
|
|
|
Settings: string(settings),
|
|
|
|
|
Tag: "subid-fix-inbound",
|
|
|
|
|
}
|
|
|
|
|
if err := db.Create(&inbound).Error; err != nil {
|
|
|
|
|
t.Fatalf("seed inbound: %v", err)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
if err := db.Where("seeder_name = ?", "InboundClientSubIdFix").Delete(&model.HistoryOfSeeders{}).Error; err != nil {
|
|
|
|
|
t.Fatalf("clear seeder history: %v", err)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
if err := normalizeInboundClientSubId(); err != nil {
|
|
|
|
|
t.Fatalf("normalizeInboundClientSubId: %v", err)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
var reloaded model.Inbound
|
|
|
|
|
if err := db.First(&reloaded, inbound.Id).Error; err != nil {
|
|
|
|
|
t.Fatalf("reload inbound: %v", err)
|
|
|
|
|
}
|
|
|
|
|
var parsed map[string]any
|
|
|
|
|
if err := json.Unmarshal([]byte(reloaded.Settings), &parsed); err != nil {
|
|
|
|
|
t.Fatalf("unmarshal settings: %v", err)
|
|
|
|
|
}
|
|
|
|
|
clients, ok := parsed["clients"].([]any)
|
|
|
|
|
if !ok || len(clients) != 3 {
|
|
|
|
|
t.Fatalf("expected 3 clients, got %v", parsed["clients"])
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
subIdPattern := regexp.MustCompile(`^[0-9a-z]{16}$`)
|
2026-06-01 15:37:20 -07:00
|
|
|
for i := range 2 {
|
2026-05-28 09:20:34 -07:00
|
|
|
obj := clients[i].(map[string]any)
|
|
|
|
|
sub, _ := obj["subId"].(string)
|
|
|
|
|
if !subIdPattern.MatchString(sub) {
|
|
|
|
|
t.Fatalf("client %d: expected 16-char [0-9a-z] subId, got %q", i, sub)
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
preserved := clients[2].(map[string]any)["subId"].(string)
|
|
|
|
|
if preserved != "keep-me-1234" {
|
|
|
|
|
t.Fatalf("expected existing subId preserved, got %q", preserved)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
var historyCount int64
|
|
|
|
|
if err := db.Model(&model.HistoryOfSeeders{}).Where("seeder_name = ?", "InboundClientSubIdFix").Count(&historyCount).Error; err != nil {
|
|
|
|
|
t.Fatalf("count seeder history: %v", err)
|
|
|
|
|
}
|
|
|
|
|
if historyCount != 1 {
|
|
|
|
|
t.Fatalf("expected one InboundClientSubIdFix history row, got %d", historyCount)
|
|
|
|
|
}
|
|
|
|
|
}
|