3x-ui/docs/custom-subscription-templates.md

82 lines
3.9 KiB
Markdown
Raw Normal View History

feat: customizable subscription page templates (#5079) * feat: add support for subscription-based outbounds with auto-update - New OutboundSubscription model (full support on both SQLite and PostgreSQL) - Go subscription link parser (vmess/vless/trojan/ss/hysteria2/wireguard) matching frontend behavior - Stable tag assignment across refreshes (designed for balancer + routing use) - Runtime merge of subscription outbounds into Xray config (additive only) - Full CRUD + manual refresh + preview API - Background auto-update job (per-subscription interval) - Frontend management UI in Outbounds tab (Subscriptions drawer) + tag integration in balancers/routing rules - Proper dual-database support including CLI migration path Review & hardening notes: - Fixed merge logic bug that could drop manual outbounds - Added SSRF/private-IP protection on subscription URLs using SanitizePublicHTTPURL - Improved update interval UX (hours + minutes) - Auto-fetch on first subscription creation - Added detailed comments on tag stability strategy and balancer implications when servers are added/removed/rotated - Updated migrationModels() for CLI migrate-db support * fix: resolve frontend lint/type errors and Go build break Frontend (eslint + tsc clean): - Destructure subscriptionOutboundTags prop in RoutingTab and BalancersTab. It was declared in the interface and used in useMemo but never destructured, so it resolved as an unresolved global (react-hooks warning + tsc "Cannot find name"). The prop is passed by XrayPage, so the feature was silently inert. - OutboundsTab: remove unused useEffect import, add an OutboundSub type to replace any[] state and the any/any table render signature, type the subscriptionOutbounds cast, and replace unused catch (e) bindings with parameter-less catch. Also type HttpUtil.post as OutboundSub so r.obj?.id type-checks. Backend (go build clean): - outbound_subscription_job: websocket.MessageTypeXray is undefined; use the existing MessageTypeOutbounds since the job refreshes outbound subscriptions. * fix(xray): make outbound subscription creation work end-to-end - Correct API paths from /panel/xray/outbound-subs to /panel/api/xray/outbound-subs. The controller is mounted under /panel/api, so the old paths hit the SPA page route (GET-only) and 404'd on POST. - Send the create-subscription body as a plain object instead of URLSearchParams. The axios request interceptor serializes bodies with qs.stringify, which can't read URLSearchParams' internal storage and produced an empty body, so the backend rejected it with "subscription URL is required". - Use message.useMessage() + context holder instead of the static antd message API (resolves the "Static function can not consume context" warning), matching XrayPage's pattern. - Migrate the subscriptions Drawer to antd v6 props: width -> size, destroyOnClose -> destroyOnHidden, and Space direction -> orientation. * feat(xray): show traffic/test for subscription outbounds; harden + test the feature Display (the reported issue): - Replace the flat read-only pills with a proper read-only table (desktop) and cards (mobile) in a new SubscriptionOutbounds component, showing Address, Protocol, Traffic (matched by tag — already collected by Xray), and a Test button with Latency. No edit/delete/move (read-only). - Test subscription outbounds via the existing /testOutbound endpoint, with results keyed by tag (subscriptionTestStates + testSubscriptionOutbound in useXraySetting, wired through XrayPage). Generalize isTesting/testResult to a string|number key so the same helpers serve index- and tag-keyed states. i18n: - Replace all hardcoded English subscription strings with t() calls and add pages.xray.outboundSub.* keys to en-US.json (other locales fall back). Backend hardening + tests: - xray.go: drop the tautological `subSvc != nil` check. - outbound_subscription: re-validate every redirect hop against private/ internal addresses (CheckRedirect) and cap the redirect chain, closing an SSRF gap where only the initial host was checked. - Extract assignStableTags as a pure function and add unit tests for tag stability and SSRF rejection (the feature previously had no tests). Misc: - gofmt util/link/outbound.go (it was not gofmt-clean). * fix(xray): make outbound-subs feature pass CI (test compile, route docs, openapi) - outbound_test.go: remove unused `inner`/`lines` variables that broke the `util/link` test build (declared and not used). - Document the 7 outbound-subscription routes in endpoints.ts (list, create, update, delete, del alias, refresh, parse) so TestAPIRoutesDocumented passes. - Regenerate frontend/public/openapi.json (npm run gen) to include the new endpoints, satisfying the codegen freshness check. * feat(xray): per-subscription allow-private, gap-filled tags, UI tweaks, delete refresh Backend: - Add a per-subscription AllowPrivate flag (default off). Create/Update/refresh and the redirect check sanitize the URL with it, so localhost/LAN sources work only when explicitly opted in; the SSRF guard still blocks private targets by default. Controller reads the allowPrivate form field on create/update/parse. - Default outbound tag prefix now uses the smallest free "subN-" number instead of the auto-increment id, so deleting a subscription frees its number for reuse (a fresh start gives sub1) while staying stable per subscription. Extracted a pure defaultPrefixNumber() with unit tests. - deleteOutboundSub now signals SetToNeedRestart so xray drops the outbounds. Frontend: - "Allow private address" toggle in the add form (sends allowPrivate). - Delete now refreshes the xray view immediately (no manual page reload). - Subscriptions manager opens as a centered Modal instead of a right-side Drawer. - Move Outbounds to a top-level sidebar item under Nodes (out of Xray Configs). - Collapse WARP/NordVPN into a "more" dropdown. - Document the allowPrivate param in endpoints.ts. * i18n(xray): translate outbound-subscription UI into all locales - Translate the pages.xray.outboundSub.* strings (and allowPrivate label/hint) into all 12 non-English locales, matching each file's existing terminology. - Remove the unused outboundSub.add ("Add subscription") key from every locale. * feat: add custom subscription page template support Allow panel admins to use a custom HTML template for the subscription page instead of the default React-based SPA. Changes ------- Backend - web/service/setting.go: Add subThemeDir setting (default: empty) with a getter GetSubThemeDir(). - web/entity/entity.go: Add SubThemeDir field to AllSetting. - sub/subController.go: In serveSubPage, before falling back to the embedded SPA, check if subThemeDir is set and the directory exists. Look for sub.html first, then index.html. Parse with Go html/template and execute, injecting all standard page variables as template context. On any parse/execute error, log and fall through to the default page. Two backward-compat aliases added to the template data map: - result = links (for tx-ui v2 templates using {{ range .result }}) - jsonUrl = subJsonUrl Frontend - frontend/src/models/setting.ts: Add subThemeDir = '' to AllSetting. - frontend/src/pages/settings/SubscriptionGeneralTab.tsx: Add a Sub Theme Directory input in Subscription settings. Templates - sub_templates/README.md: Full authoring guide with all variables. - sub_templates/tx-ui/index.html: The tx-ui subscription page template migrated from v2 to v3 data shape. Credits ------- Bundled tx-ui template from AghayeCoder: https://github.com/AghayeCoder/tx-ui * chore: regenerate OpenAPI schemas and types for custom sub-template feature * feat(xray): subscription manager — edit, reorder/priority, status, preview, refresh-all Backend: - Per-subscription Priority + Prepend: subscriptions are ordered by Priority and placed before (Prepend) or after the manual template outbounds in the merge, so a subscription server can become the default. New Move(up/down) endpoint re-normalizes priorities; merge split into prepend/template/append. - List now returns a derived OutboundCount and orders by priority, and strips the heavy LastFetchedOutbounds/LinkIdentities blobs from the list payload. - Create/Update accept the prepend flag; new subs append at the end of priority. Frontend (Outbound Subscriptions modal): - Edit existing subscriptions (reuses the form + Update endpoint). - Inline enable/disable Switch, Status column (OK / error tooltip), Outbounds count column, per-row refresh spinner, "Refresh all" button. - Reorder (move up/down) controls + a "Before manual outbounds" toggle. - Preview button: fetch+parse a URL via /parse without saving. - Document the move route + prepend param in endpoints.ts; regenerate openapi.json. * i18n(xray): translate new subscription-manager strings into all locales Add the prepend/prependHint, preview/previewEmpty, refreshAll, statusOk and toastUpdated keys to all 12 non-English locales, matching each file's terminology. * refactor(sub): harden custom template rendering, drop bundled tx-ui template Builds on the custom subscription page template feature. Rendering hardening (sub/subController.go): - Render the custom template into a buffer and only write the response on success. Previously template.Execute wrote straight to the ResponseWriter, so a mid-render failure left a partially-written body and then fell through to the default page, corrupting the response (superfluous WriteHeader). - Cache parsed templates keyed by path, invalidated by file mtime, so each subscription page load no longer re-reads and re-parses the file from disk; admin edits are still picked up automatically. - Verify the configured path is a directory (IsDir) and log a Warning when it is set but unusable / an Error when a template fails to parse, instead of silently falling back. - Expose two new template variables: subTitle and subSupportUrl. Cleanup: - Remove the bundled tx-ui template and all tx-ui / AghayeCoder references (including the result/jsonUrl v2-compat aliases); use a generic my-theme example path in docs/UI/translation. - i18n the "Sub Theme Directory" setting (en-US subThemeDir/subThemeDirDesc) instead of hardcoded English. - Fix README: expire is seconds (not ms), lastOnline is ms; correct the settings tab name; note templates are admin-provided, not bundled/deployed. Tests: - Add sub/subController_test.go covering loadSubTemplate: render, sub.html precedence, fallback cases, malformed template, and mtime cache invalidation. Verified end-to-end in Docker: custom template renders with all variables, all fallback paths return the clean default page (no corruption), and the mtime cache reflects live edits. * i18n(settings): translate subThemeDir into all locales Add the subThemeDir / subThemeDirDesc keys (Sub Theme Directory setting) to all 12 non-English locales, matching each file's existing terminology. They previously fell back to en-US. --------- Co-authored-by: MHSanaei <ho3ein.sanaei@gmail.com> Co-authored-by: Rqzbeh <rqzbeh@users.noreply.github.com>
2026-06-08 13:04:47 -07:00
# 3x-ui Custom Subscription Templates
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
3x-ui can render your users' subscription pages from your own custom HTML templates.
feat: customizable subscription page templates (#5079) * feat: add support for subscription-based outbounds with auto-update - New OutboundSubscription model (full support on both SQLite and PostgreSQL) - Go subscription link parser (vmess/vless/trojan/ss/hysteria2/wireguard) matching frontend behavior - Stable tag assignment across refreshes (designed for balancer + routing use) - Runtime merge of subscription outbounds into Xray config (additive only) - Full CRUD + manual refresh + preview API - Background auto-update job (per-subscription interval) - Frontend management UI in Outbounds tab (Subscriptions drawer) + tag integration in balancers/routing rules - Proper dual-database support including CLI migration path Review & hardening notes: - Fixed merge logic bug that could drop manual outbounds - Added SSRF/private-IP protection on subscription URLs using SanitizePublicHTTPURL - Improved update interval UX (hours + minutes) - Auto-fetch on first subscription creation - Added detailed comments on tag stability strategy and balancer implications when servers are added/removed/rotated - Updated migrationModels() for CLI migrate-db support * fix: resolve frontend lint/type errors and Go build break Frontend (eslint + tsc clean): - Destructure subscriptionOutboundTags prop in RoutingTab and BalancersTab. It was declared in the interface and used in useMemo but never destructured, so it resolved as an unresolved global (react-hooks warning + tsc "Cannot find name"). The prop is passed by XrayPage, so the feature was silently inert. - OutboundsTab: remove unused useEffect import, add an OutboundSub type to replace any[] state and the any/any table render signature, type the subscriptionOutbounds cast, and replace unused catch (e) bindings with parameter-less catch. Also type HttpUtil.post as OutboundSub so r.obj?.id type-checks. Backend (go build clean): - outbound_subscription_job: websocket.MessageTypeXray is undefined; use the existing MessageTypeOutbounds since the job refreshes outbound subscriptions. * fix(xray): make outbound subscription creation work end-to-end - Correct API paths from /panel/xray/outbound-subs to /panel/api/xray/outbound-subs. The controller is mounted under /panel/api, so the old paths hit the SPA page route (GET-only) and 404'd on POST. - Send the create-subscription body as a plain object instead of URLSearchParams. The axios request interceptor serializes bodies with qs.stringify, which can't read URLSearchParams' internal storage and produced an empty body, so the backend rejected it with "subscription URL is required". - Use message.useMessage() + context holder instead of the static antd message API (resolves the "Static function can not consume context" warning), matching XrayPage's pattern. - Migrate the subscriptions Drawer to antd v6 props: width -> size, destroyOnClose -> destroyOnHidden, and Space direction -> orientation. * feat(xray): show traffic/test for subscription outbounds; harden + test the feature Display (the reported issue): - Replace the flat read-only pills with a proper read-only table (desktop) and cards (mobile) in a new SubscriptionOutbounds component, showing Address, Protocol, Traffic (matched by tag — already collected by Xray), and a Test button with Latency. No edit/delete/move (read-only). - Test subscription outbounds via the existing /testOutbound endpoint, with results keyed by tag (subscriptionTestStates + testSubscriptionOutbound in useXraySetting, wired through XrayPage). Generalize isTesting/testResult to a string|number key so the same helpers serve index- and tag-keyed states. i18n: - Replace all hardcoded English subscription strings with t() calls and add pages.xray.outboundSub.* keys to en-US.json (other locales fall back). Backend hardening + tests: - xray.go: drop the tautological `subSvc != nil` check. - outbound_subscription: re-validate every redirect hop against private/ internal addresses (CheckRedirect) and cap the redirect chain, closing an SSRF gap where only the initial host was checked. - Extract assignStableTags as a pure function and add unit tests for tag stability and SSRF rejection (the feature previously had no tests). Misc: - gofmt util/link/outbound.go (it was not gofmt-clean). * fix(xray): make outbound-subs feature pass CI (test compile, route docs, openapi) - outbound_test.go: remove unused `inner`/`lines` variables that broke the `util/link` test build (declared and not used). - Document the 7 outbound-subscription routes in endpoints.ts (list, create, update, delete, del alias, refresh, parse) so TestAPIRoutesDocumented passes. - Regenerate frontend/public/openapi.json (npm run gen) to include the new endpoints, satisfying the codegen freshness check. * feat(xray): per-subscription allow-private, gap-filled tags, UI tweaks, delete refresh Backend: - Add a per-subscription AllowPrivate flag (default off). Create/Update/refresh and the redirect check sanitize the URL with it, so localhost/LAN sources work only when explicitly opted in; the SSRF guard still blocks private targets by default. Controller reads the allowPrivate form field on create/update/parse. - Default outbound tag prefix now uses the smallest free "subN-" number instead of the auto-increment id, so deleting a subscription frees its number for reuse (a fresh start gives sub1) while staying stable per subscription. Extracted a pure defaultPrefixNumber() with unit tests. - deleteOutboundSub now signals SetToNeedRestart so xray drops the outbounds. Frontend: - "Allow private address" toggle in the add form (sends allowPrivate). - Delete now refreshes the xray view immediately (no manual page reload). - Subscriptions manager opens as a centered Modal instead of a right-side Drawer. - Move Outbounds to a top-level sidebar item under Nodes (out of Xray Configs). - Collapse WARP/NordVPN into a "more" dropdown. - Document the allowPrivate param in endpoints.ts. * i18n(xray): translate outbound-subscription UI into all locales - Translate the pages.xray.outboundSub.* strings (and allowPrivate label/hint) into all 12 non-English locales, matching each file's existing terminology. - Remove the unused outboundSub.add ("Add subscription") key from every locale. * feat: add custom subscription page template support Allow panel admins to use a custom HTML template for the subscription page instead of the default React-based SPA. Changes ------- Backend - web/service/setting.go: Add subThemeDir setting (default: empty) with a getter GetSubThemeDir(). - web/entity/entity.go: Add SubThemeDir field to AllSetting. - sub/subController.go: In serveSubPage, before falling back to the embedded SPA, check if subThemeDir is set and the directory exists. Look for sub.html first, then index.html. Parse with Go html/template and execute, injecting all standard page variables as template context. On any parse/execute error, log and fall through to the default page. Two backward-compat aliases added to the template data map: - result = links (for tx-ui v2 templates using {{ range .result }}) - jsonUrl = subJsonUrl Frontend - frontend/src/models/setting.ts: Add subThemeDir = '' to AllSetting. - frontend/src/pages/settings/SubscriptionGeneralTab.tsx: Add a Sub Theme Directory input in Subscription settings. Templates - sub_templates/README.md: Full authoring guide with all variables. - sub_templates/tx-ui/index.html: The tx-ui subscription page template migrated from v2 to v3 data shape. Credits ------- Bundled tx-ui template from AghayeCoder: https://github.com/AghayeCoder/tx-ui * chore: regenerate OpenAPI schemas and types for custom sub-template feature * feat(xray): subscription manager — edit, reorder/priority, status, preview, refresh-all Backend: - Per-subscription Priority + Prepend: subscriptions are ordered by Priority and placed before (Prepend) or after the manual template outbounds in the merge, so a subscription server can become the default. New Move(up/down) endpoint re-normalizes priorities; merge split into prepend/template/append. - List now returns a derived OutboundCount and orders by priority, and strips the heavy LastFetchedOutbounds/LinkIdentities blobs from the list payload. - Create/Update accept the prepend flag; new subs append at the end of priority. Frontend (Outbound Subscriptions modal): - Edit existing subscriptions (reuses the form + Update endpoint). - Inline enable/disable Switch, Status column (OK / error tooltip), Outbounds count column, per-row refresh spinner, "Refresh all" button. - Reorder (move up/down) controls + a "Before manual outbounds" toggle. - Preview button: fetch+parse a URL via /parse without saving. - Document the move route + prepend param in endpoints.ts; regenerate openapi.json. * i18n(xray): translate new subscription-manager strings into all locales Add the prepend/prependHint, preview/previewEmpty, refreshAll, statusOk and toastUpdated keys to all 12 non-English locales, matching each file's terminology. * refactor(sub): harden custom template rendering, drop bundled tx-ui template Builds on the custom subscription page template feature. Rendering hardening (sub/subController.go): - Render the custom template into a buffer and only write the response on success. Previously template.Execute wrote straight to the ResponseWriter, so a mid-render failure left a partially-written body and then fell through to the default page, corrupting the response (superfluous WriteHeader). - Cache parsed templates keyed by path, invalidated by file mtime, so each subscription page load no longer re-reads and re-parses the file from disk; admin edits are still picked up automatically. - Verify the configured path is a directory (IsDir) and log a Warning when it is set but unusable / an Error when a template fails to parse, instead of silently falling back. - Expose two new template variables: subTitle and subSupportUrl. Cleanup: - Remove the bundled tx-ui template and all tx-ui / AghayeCoder references (including the result/jsonUrl v2-compat aliases); use a generic my-theme example path in docs/UI/translation. - i18n the "Sub Theme Directory" setting (en-US subThemeDir/subThemeDirDesc) instead of hardcoded English. - Fix README: expire is seconds (not ms), lastOnline is ms; correct the settings tab name; note templates are admin-provided, not bundled/deployed. Tests: - Add sub/subController_test.go covering loadSubTemplate: render, sub.html precedence, fallback cases, malformed template, and mtime cache invalidation. Verified end-to-end in Docker: custom template renders with all variables, all fallback paths return the clean default page (no corruption), and the mtime cache reflects live edits. * i18n(settings): translate subThemeDir into all locales Add the subThemeDir / subThemeDirDesc keys (Sub Theme Directory setting) to all 12 non-English locales, matching each file's existing terminology. They previously fell back to en-US. --------- Co-authored-by: MHSanaei <ho3ein.sanaei@gmail.com> Co-authored-by: Rqzbeh <rqzbeh@users.noreply.github.com>
2026-06-08 13:04:47 -07:00
## How to use a Custom Template
1. Go to the 3x-ui panel settings.
2. Under **Settings → Subscription → Information**, locate the **Sub Theme Directory** field.
3. Provide the absolute path to the folder containing your template (e.g. `/etc/3x-ui/sub_templates/my-theme/`).
4. Save the settings.
> **Note:** 3x-ui does not ship any templates by default. Create your own template folder anywhere
> on the server, put an `index.html` (or `sub.html`) inside it, and point **Sub Theme Directory** at
> that absolute path. Leave the field empty to use the default built-in page.
## Creating a Template
A custom template must be an HTML file named `index.html` or `sub.html` located within the directory you specified in the settings.
The panel uses standard Go `html/template` to render the subscription page.
### Available Variables
When rendering the template, the following variables are injected into the template context (`{{ .variable }}`):
* `{{ .sId }}`: Subscription ID (UUID).
* `{{ .enabled }}`: Whether the subscription/client is enabled (boolean).
* `{{ .isOnline }}`: Whether the subscription's client has a live connection right now (boolean). Computed from the panel's online-client tracking (local Xray plus any remote nodes) at render time.
feat: customizable subscription page templates (#5079) * feat: add support for subscription-based outbounds with auto-update - New OutboundSubscription model (full support on both SQLite and PostgreSQL) - Go subscription link parser (vmess/vless/trojan/ss/hysteria2/wireguard) matching frontend behavior - Stable tag assignment across refreshes (designed for balancer + routing use) - Runtime merge of subscription outbounds into Xray config (additive only) - Full CRUD + manual refresh + preview API - Background auto-update job (per-subscription interval) - Frontend management UI in Outbounds tab (Subscriptions drawer) + tag integration in balancers/routing rules - Proper dual-database support including CLI migration path Review & hardening notes: - Fixed merge logic bug that could drop manual outbounds - Added SSRF/private-IP protection on subscription URLs using SanitizePublicHTTPURL - Improved update interval UX (hours + minutes) - Auto-fetch on first subscription creation - Added detailed comments on tag stability strategy and balancer implications when servers are added/removed/rotated - Updated migrationModels() for CLI migrate-db support * fix: resolve frontend lint/type errors and Go build break Frontend (eslint + tsc clean): - Destructure subscriptionOutboundTags prop in RoutingTab and BalancersTab. It was declared in the interface and used in useMemo but never destructured, so it resolved as an unresolved global (react-hooks warning + tsc "Cannot find name"). The prop is passed by XrayPage, so the feature was silently inert. - OutboundsTab: remove unused useEffect import, add an OutboundSub type to replace any[] state and the any/any table render signature, type the subscriptionOutbounds cast, and replace unused catch (e) bindings with parameter-less catch. Also type HttpUtil.post as OutboundSub so r.obj?.id type-checks. Backend (go build clean): - outbound_subscription_job: websocket.MessageTypeXray is undefined; use the existing MessageTypeOutbounds since the job refreshes outbound subscriptions. * fix(xray): make outbound subscription creation work end-to-end - Correct API paths from /panel/xray/outbound-subs to /panel/api/xray/outbound-subs. The controller is mounted under /panel/api, so the old paths hit the SPA page route (GET-only) and 404'd on POST. - Send the create-subscription body as a plain object instead of URLSearchParams. The axios request interceptor serializes bodies with qs.stringify, which can't read URLSearchParams' internal storage and produced an empty body, so the backend rejected it with "subscription URL is required". - Use message.useMessage() + context holder instead of the static antd message API (resolves the "Static function can not consume context" warning), matching XrayPage's pattern. - Migrate the subscriptions Drawer to antd v6 props: width -> size, destroyOnClose -> destroyOnHidden, and Space direction -> orientation. * feat(xray): show traffic/test for subscription outbounds; harden + test the feature Display (the reported issue): - Replace the flat read-only pills with a proper read-only table (desktop) and cards (mobile) in a new SubscriptionOutbounds component, showing Address, Protocol, Traffic (matched by tag — already collected by Xray), and a Test button with Latency. No edit/delete/move (read-only). - Test subscription outbounds via the existing /testOutbound endpoint, with results keyed by tag (subscriptionTestStates + testSubscriptionOutbound in useXraySetting, wired through XrayPage). Generalize isTesting/testResult to a string|number key so the same helpers serve index- and tag-keyed states. i18n: - Replace all hardcoded English subscription strings with t() calls and add pages.xray.outboundSub.* keys to en-US.json (other locales fall back). Backend hardening + tests: - xray.go: drop the tautological `subSvc != nil` check. - outbound_subscription: re-validate every redirect hop against private/ internal addresses (CheckRedirect) and cap the redirect chain, closing an SSRF gap where only the initial host was checked. - Extract assignStableTags as a pure function and add unit tests for tag stability and SSRF rejection (the feature previously had no tests). Misc: - gofmt util/link/outbound.go (it was not gofmt-clean). * fix(xray): make outbound-subs feature pass CI (test compile, route docs, openapi) - outbound_test.go: remove unused `inner`/`lines` variables that broke the `util/link` test build (declared and not used). - Document the 7 outbound-subscription routes in endpoints.ts (list, create, update, delete, del alias, refresh, parse) so TestAPIRoutesDocumented passes. - Regenerate frontend/public/openapi.json (npm run gen) to include the new endpoints, satisfying the codegen freshness check. * feat(xray): per-subscription allow-private, gap-filled tags, UI tweaks, delete refresh Backend: - Add a per-subscription AllowPrivate flag (default off). Create/Update/refresh and the redirect check sanitize the URL with it, so localhost/LAN sources work only when explicitly opted in; the SSRF guard still blocks private targets by default. Controller reads the allowPrivate form field on create/update/parse. - Default outbound tag prefix now uses the smallest free "subN-" number instead of the auto-increment id, so deleting a subscription frees its number for reuse (a fresh start gives sub1) while staying stable per subscription. Extracted a pure defaultPrefixNumber() with unit tests. - deleteOutboundSub now signals SetToNeedRestart so xray drops the outbounds. Frontend: - "Allow private address" toggle in the add form (sends allowPrivate). - Delete now refreshes the xray view immediately (no manual page reload). - Subscriptions manager opens as a centered Modal instead of a right-side Drawer. - Move Outbounds to a top-level sidebar item under Nodes (out of Xray Configs). - Collapse WARP/NordVPN into a "more" dropdown. - Document the allowPrivate param in endpoints.ts. * i18n(xray): translate outbound-subscription UI into all locales - Translate the pages.xray.outboundSub.* strings (and allowPrivate label/hint) into all 12 non-English locales, matching each file's existing terminology. - Remove the unused outboundSub.add ("Add subscription") key from every locale. * feat: add custom subscription page template support Allow panel admins to use a custom HTML template for the subscription page instead of the default React-based SPA. Changes ------- Backend - web/service/setting.go: Add subThemeDir setting (default: empty) with a getter GetSubThemeDir(). - web/entity/entity.go: Add SubThemeDir field to AllSetting. - sub/subController.go: In serveSubPage, before falling back to the embedded SPA, check if subThemeDir is set and the directory exists. Look for sub.html first, then index.html. Parse with Go html/template and execute, injecting all standard page variables as template context. On any parse/execute error, log and fall through to the default page. Two backward-compat aliases added to the template data map: - result = links (for tx-ui v2 templates using {{ range .result }}) - jsonUrl = subJsonUrl Frontend - frontend/src/models/setting.ts: Add subThemeDir = '' to AllSetting. - frontend/src/pages/settings/SubscriptionGeneralTab.tsx: Add a Sub Theme Directory input in Subscription settings. Templates - sub_templates/README.md: Full authoring guide with all variables. - sub_templates/tx-ui/index.html: The tx-ui subscription page template migrated from v2 to v3 data shape. Credits ------- Bundled tx-ui template from AghayeCoder: https://github.com/AghayeCoder/tx-ui * chore: regenerate OpenAPI schemas and types for custom sub-template feature * feat(xray): subscription manager — edit, reorder/priority, status, preview, refresh-all Backend: - Per-subscription Priority + Prepend: subscriptions are ordered by Priority and placed before (Prepend) or after the manual template outbounds in the merge, so a subscription server can become the default. New Move(up/down) endpoint re-normalizes priorities; merge split into prepend/template/append. - List now returns a derived OutboundCount and orders by priority, and strips the heavy LastFetchedOutbounds/LinkIdentities blobs from the list payload. - Create/Update accept the prepend flag; new subs append at the end of priority. Frontend (Outbound Subscriptions modal): - Edit existing subscriptions (reuses the form + Update endpoint). - Inline enable/disable Switch, Status column (OK / error tooltip), Outbounds count column, per-row refresh spinner, "Refresh all" button. - Reorder (move up/down) controls + a "Before manual outbounds" toggle. - Preview button: fetch+parse a URL via /parse without saving. - Document the move route + prepend param in endpoints.ts; regenerate openapi.json. * i18n(xray): translate new subscription-manager strings into all locales Add the prepend/prependHint, preview/previewEmpty, refreshAll, statusOk and toastUpdated keys to all 12 non-English locales, matching each file's terminology. * refactor(sub): harden custom template rendering, drop bundled tx-ui template Builds on the custom subscription page template feature. Rendering hardening (sub/subController.go): - Render the custom template into a buffer and only write the response on success. Previously template.Execute wrote straight to the ResponseWriter, so a mid-render failure left a partially-written body and then fell through to the default page, corrupting the response (superfluous WriteHeader). - Cache parsed templates keyed by path, invalidated by file mtime, so each subscription page load no longer re-reads and re-parses the file from disk; admin edits are still picked up automatically. - Verify the configured path is a directory (IsDir) and log a Warning when it is set but unusable / an Error when a template fails to parse, instead of silently falling back. - Expose two new template variables: subTitle and subSupportUrl. Cleanup: - Remove the bundled tx-ui template and all tx-ui / AghayeCoder references (including the result/jsonUrl v2-compat aliases); use a generic my-theme example path in docs/UI/translation. - i18n the "Sub Theme Directory" setting (en-US subThemeDir/subThemeDirDesc) instead of hardcoded English. - Fix README: expire is seconds (not ms), lastOnline is ms; correct the settings tab name; note templates are admin-provided, not bundled/deployed. Tests: - Add sub/subController_test.go covering loadSubTemplate: render, sub.html precedence, fallback cases, malformed template, and mtime cache invalidation. Verified end-to-end in Docker: custom template renders with all variables, all fallback paths return the clean default page (no corruption), and the mtime cache reflects live edits. * i18n(settings): translate subThemeDir into all locales Add the subThemeDir / subThemeDirDesc keys (Sub Theme Directory setting) to all 12 non-English locales, matching each file's existing terminology. They previously fell back to en-US. --------- Co-authored-by: MHSanaei <ho3ein.sanaei@gmail.com> Co-authored-by: Rqzbeh <rqzbeh@users.noreply.github.com>
2026-06-08 13:04:47 -07:00
* `{{ .download }}`: Formatted download traffic (e.g. "2.5 GB").
* `{{ .upload }}`: Formatted upload traffic.
* `{{ .total }}`: Formatted total traffic limit.
* `{{ .used }}`: Formatted used traffic (download + upload).
* `{{ .remained }}`: Formatted remaining traffic.
* `{{ .expire }}`: Expiration time as an int64 Unix timestamp in **seconds** (`0` means never). Multiply by 1000 for a JavaScript `Date`.
* `{{ .lastOnline }}`: Last online time as an int64 Unix timestamp in **milliseconds** (`0` means never seen).
* `{{ .downloadByte }}`: Download traffic in exact bytes (int64).
* `{{ .uploadByte }}`: Upload traffic in exact bytes (int64).
* `{{ .totalByte }}`: Total traffic limit in exact bytes (int64).
* `{{ .subUrl }}`: The URL of the subscription page.
* `{{ .subJsonUrl }}`: The URL for the JSON configuration of the subscription.
* `{{ .subClashUrl }}`: The URL for the Clash/Mihomo configuration.
* `{{ .subTitle }}`: The subscription title configured in the panel (Subscription → Information). Useful for page branding/headings. May be empty.
* `{{ .subSupportUrl }}`: The support URL configured in the panel. Useful for a "Contact support" link. May be empty.
* `{{ .links }}`: A list (slice) of string configurations (VMess, VLESS, etc. URLs). You can loop through them using `{{ range .links }} ... {{ end }}`.
* `{{ .emails }}`: A list (slice) of client emails, parallel to `links` — the email at index *i* owns the link at index *i*. May contain duplicates when one client has several links.
* `{{ .announce }}`: The announcement text configured in the panel (Settings → Subscription → Announce). May be empty.
feat: customizable subscription page templates (#5079) * feat: add support for subscription-based outbounds with auto-update - New OutboundSubscription model (full support on both SQLite and PostgreSQL) - Go subscription link parser (vmess/vless/trojan/ss/hysteria2/wireguard) matching frontend behavior - Stable tag assignment across refreshes (designed for balancer + routing use) - Runtime merge of subscription outbounds into Xray config (additive only) - Full CRUD + manual refresh + preview API - Background auto-update job (per-subscription interval) - Frontend management UI in Outbounds tab (Subscriptions drawer) + tag integration in balancers/routing rules - Proper dual-database support including CLI migration path Review & hardening notes: - Fixed merge logic bug that could drop manual outbounds - Added SSRF/private-IP protection on subscription URLs using SanitizePublicHTTPURL - Improved update interval UX (hours + minutes) - Auto-fetch on first subscription creation - Added detailed comments on tag stability strategy and balancer implications when servers are added/removed/rotated - Updated migrationModels() for CLI migrate-db support * fix: resolve frontend lint/type errors and Go build break Frontend (eslint + tsc clean): - Destructure subscriptionOutboundTags prop in RoutingTab and BalancersTab. It was declared in the interface and used in useMemo but never destructured, so it resolved as an unresolved global (react-hooks warning + tsc "Cannot find name"). The prop is passed by XrayPage, so the feature was silently inert. - OutboundsTab: remove unused useEffect import, add an OutboundSub type to replace any[] state and the any/any table render signature, type the subscriptionOutbounds cast, and replace unused catch (e) bindings with parameter-less catch. Also type HttpUtil.post as OutboundSub so r.obj?.id type-checks. Backend (go build clean): - outbound_subscription_job: websocket.MessageTypeXray is undefined; use the existing MessageTypeOutbounds since the job refreshes outbound subscriptions. * fix(xray): make outbound subscription creation work end-to-end - Correct API paths from /panel/xray/outbound-subs to /panel/api/xray/outbound-subs. The controller is mounted under /panel/api, so the old paths hit the SPA page route (GET-only) and 404'd on POST. - Send the create-subscription body as a plain object instead of URLSearchParams. The axios request interceptor serializes bodies with qs.stringify, which can't read URLSearchParams' internal storage and produced an empty body, so the backend rejected it with "subscription URL is required". - Use message.useMessage() + context holder instead of the static antd message API (resolves the "Static function can not consume context" warning), matching XrayPage's pattern. - Migrate the subscriptions Drawer to antd v6 props: width -> size, destroyOnClose -> destroyOnHidden, and Space direction -> orientation. * feat(xray): show traffic/test for subscription outbounds; harden + test the feature Display (the reported issue): - Replace the flat read-only pills with a proper read-only table (desktop) and cards (mobile) in a new SubscriptionOutbounds component, showing Address, Protocol, Traffic (matched by tag — already collected by Xray), and a Test button with Latency. No edit/delete/move (read-only). - Test subscription outbounds via the existing /testOutbound endpoint, with results keyed by tag (subscriptionTestStates + testSubscriptionOutbound in useXraySetting, wired through XrayPage). Generalize isTesting/testResult to a string|number key so the same helpers serve index- and tag-keyed states. i18n: - Replace all hardcoded English subscription strings with t() calls and add pages.xray.outboundSub.* keys to en-US.json (other locales fall back). Backend hardening + tests: - xray.go: drop the tautological `subSvc != nil` check. - outbound_subscription: re-validate every redirect hop against private/ internal addresses (CheckRedirect) and cap the redirect chain, closing an SSRF gap where only the initial host was checked. - Extract assignStableTags as a pure function and add unit tests for tag stability and SSRF rejection (the feature previously had no tests). Misc: - gofmt util/link/outbound.go (it was not gofmt-clean). * fix(xray): make outbound-subs feature pass CI (test compile, route docs, openapi) - outbound_test.go: remove unused `inner`/`lines` variables that broke the `util/link` test build (declared and not used). - Document the 7 outbound-subscription routes in endpoints.ts (list, create, update, delete, del alias, refresh, parse) so TestAPIRoutesDocumented passes. - Regenerate frontend/public/openapi.json (npm run gen) to include the new endpoints, satisfying the codegen freshness check. * feat(xray): per-subscription allow-private, gap-filled tags, UI tweaks, delete refresh Backend: - Add a per-subscription AllowPrivate flag (default off). Create/Update/refresh and the redirect check sanitize the URL with it, so localhost/LAN sources work only when explicitly opted in; the SSRF guard still blocks private targets by default. Controller reads the allowPrivate form field on create/update/parse. - Default outbound tag prefix now uses the smallest free "subN-" number instead of the auto-increment id, so deleting a subscription frees its number for reuse (a fresh start gives sub1) while staying stable per subscription. Extracted a pure defaultPrefixNumber() with unit tests. - deleteOutboundSub now signals SetToNeedRestart so xray drops the outbounds. Frontend: - "Allow private address" toggle in the add form (sends allowPrivate). - Delete now refreshes the xray view immediately (no manual page reload). - Subscriptions manager opens as a centered Modal instead of a right-side Drawer. - Move Outbounds to a top-level sidebar item under Nodes (out of Xray Configs). - Collapse WARP/NordVPN into a "more" dropdown. - Document the allowPrivate param in endpoints.ts. * i18n(xray): translate outbound-subscription UI into all locales - Translate the pages.xray.outboundSub.* strings (and allowPrivate label/hint) into all 12 non-English locales, matching each file's existing terminology. - Remove the unused outboundSub.add ("Add subscription") key from every locale. * feat: add custom subscription page template support Allow panel admins to use a custom HTML template for the subscription page instead of the default React-based SPA. Changes ------- Backend - web/service/setting.go: Add subThemeDir setting (default: empty) with a getter GetSubThemeDir(). - web/entity/entity.go: Add SubThemeDir field to AllSetting. - sub/subController.go: In serveSubPage, before falling back to the embedded SPA, check if subThemeDir is set and the directory exists. Look for sub.html first, then index.html. Parse with Go html/template and execute, injecting all standard page variables as template context. On any parse/execute error, log and fall through to the default page. Two backward-compat aliases added to the template data map: - result = links (for tx-ui v2 templates using {{ range .result }}) - jsonUrl = subJsonUrl Frontend - frontend/src/models/setting.ts: Add subThemeDir = '' to AllSetting. - frontend/src/pages/settings/SubscriptionGeneralTab.tsx: Add a Sub Theme Directory input in Subscription settings. Templates - sub_templates/README.md: Full authoring guide with all variables. - sub_templates/tx-ui/index.html: The tx-ui subscription page template migrated from v2 to v3 data shape. Credits ------- Bundled tx-ui template from AghayeCoder: https://github.com/AghayeCoder/tx-ui * chore: regenerate OpenAPI schemas and types for custom sub-template feature * feat(xray): subscription manager — edit, reorder/priority, status, preview, refresh-all Backend: - Per-subscription Priority + Prepend: subscriptions are ordered by Priority and placed before (Prepend) or after the manual template outbounds in the merge, so a subscription server can become the default. New Move(up/down) endpoint re-normalizes priorities; merge split into prepend/template/append. - List now returns a derived OutboundCount and orders by priority, and strips the heavy LastFetchedOutbounds/LinkIdentities blobs from the list payload. - Create/Update accept the prepend flag; new subs append at the end of priority. Frontend (Outbound Subscriptions modal): - Edit existing subscriptions (reuses the form + Update endpoint). - Inline enable/disable Switch, Status column (OK / error tooltip), Outbounds count column, per-row refresh spinner, "Refresh all" button. - Reorder (move up/down) controls + a "Before manual outbounds" toggle. - Preview button: fetch+parse a URL via /parse without saving. - Document the move route + prepend param in endpoints.ts; regenerate openapi.json. * i18n(xray): translate new subscription-manager strings into all locales Add the prepend/prependHint, preview/previewEmpty, refreshAll, statusOk and toastUpdated keys to all 12 non-English locales, matching each file's terminology. * refactor(sub): harden custom template rendering, drop bundled tx-ui template Builds on the custom subscription page template feature. Rendering hardening (sub/subController.go): - Render the custom template into a buffer and only write the response on success. Previously template.Execute wrote straight to the ResponseWriter, so a mid-render failure left a partially-written body and then fell through to the default page, corrupting the response (superfluous WriteHeader). - Cache parsed templates keyed by path, invalidated by file mtime, so each subscription page load no longer re-reads and re-parses the file from disk; admin edits are still picked up automatically. - Verify the configured path is a directory (IsDir) and log a Warning when it is set but unusable / an Error when a template fails to parse, instead of silently falling back. - Expose two new template variables: subTitle and subSupportUrl. Cleanup: - Remove the bundled tx-ui template and all tx-ui / AghayeCoder references (including the result/jsonUrl v2-compat aliases); use a generic my-theme example path in docs/UI/translation. - i18n the "Sub Theme Directory" setting (en-US subThemeDir/subThemeDirDesc) instead of hardcoded English. - Fix README: expire is seconds (not ms), lastOnline is ms; correct the settings tab name; note templates are admin-provided, not bundled/deployed. Tests: - Add sub/subController_test.go covering loadSubTemplate: render, sub.html precedence, fallback cases, malformed template, and mtime cache invalidation. Verified end-to-end in Docker: custom template renders with all variables, all fallback paths return the clean default page (no corruption), and the mtime cache reflects live edits. * i18n(settings): translate subThemeDir into all locales Add the subThemeDir / subThemeDirDesc keys (Sub Theme Directory setting) to all 12 non-English locales, matching each file's existing terminology. They previously fell back to en-US. --------- Co-authored-by: MHSanaei <ho3ein.sanaei@gmail.com> Co-authored-by: Rqzbeh <rqzbeh@users.noreply.github.com>
2026-06-08 13:04:47 -07:00
* `{{ .datepicker }}`: Current calendar format used by the panel (e.g. "gregorian" or "jalali").
## Live Status JSON (`?format=info`)
Every subscription URL also answers `GET <sub URL>?format=info` with the same view-model as JSON —
minus `links`, and with `emails` deduplicated — so a template can poll it and update usage or
online status live without reloading the page:
```json
{
"sId": "…",
"enabled": true,
"isOnline": true,
"used": "1.2 GB",
"remained": "8.8 GB",
"expire": 0,
"lastOnline": 1735680000000,
"…": "…"
}
```
Example polling snippet for a template:
```html
<span id="status"></span>
<script>
async function refreshStatus() {
const res = await fetch(window.location.pathname + '?format=info');
if (!res.ok) return;
const info = await res.json();
document.getElementById('status').textContent = info.isOnline ? 'Online' : 'Offline';
}
refreshStatus();
setInterval(refreshStatus, 10000);
</script>
```