Reduce list-page payloads with slim/paged endpoints (#4500)

* perf(inbounds): slim list payload + lazy hydrate for row actions

Adds GET /panel/api/inbounds/list/slim that returns the same list shape
but strips every per-client field besides email/enable/comment from
settings.clients[] and skips UUID/SubId enrichment on ClientStats.
The inbounds page only reads those three to compute its client counters
and badges, so the slim variant trims tens of bytes per client (uuid,
password, flow, security, totalGB, expiryTime, limitIp, tgId, ...).
On a panel with thousands of clients this is the dominant load-time
cost.

Detail flows (edit / info / qr / export / clone) call /get/:id through
a new hydrateInbound helper before opening — the slim list view never
needs the secrets it doesn't render.

* perf(clients): server-side pagination + slim row payload

Adds GET /panel/api/clients/list/paged that filters, sorts, and paginates
on the server, returns a slim row shape (drops uuid/password/auth/flow/
security/reverse/tgId per client), and includes a stable summary
(total, active, online[], depleted[], expiring[], deactive[]) computed
across the full DB row set so the dashboard cards don't change as the
user paginates or filters. Page size capped at 200.

useClients now exposes { clients (current page), total, filtered, query,
setQuery, summary, hydrate }. ClientsPage feeds its filter/sort/page
state into setQuery via a single effect, debounces search by 300ms, and
hydrates the full client record via /get/:email before opening edit/info/
qr modals. Local filter/sort logic and the all-clients summary memo are
gone.

On a 2000-client panel this turns the initial response from ~MB to ~25 row
slice (~10s of KB) and removes the all-client parse cost from every
refresh.

* perf(settings): use /inbounds/options for LDAP tag picker

The General settings tab only needs each inbound's tag/protocol/port to
fill a dropdown but was calling /panel/api/inbounds/list which ships the
full settings JSON with every embedded client. Switched it to /options
and added Tag to the projection. On a panel with thousands of clients
this drops the General-tab load payload from megabytes to a tiny
per-inbound row each.

* perf(clients): de-duplicate options + paged list fetches

Two issues caused each clients-page load to fire its requests twice:

1. setQuery in the hook took whatever object the consumer passed and
   stored it as-is. The consumer (ClientsPage) constructs a new object
   literal in an effect, so even when nothing actually changed the ref
   was new — the hook's useEffect saw a new query and re-fetched.
   Wrapped setQuery with a shallow value compare so identical params
   are a no-op.

2. The picker /inbounds/options fetch was bundled into refresh() with a
   length==0 guard, but the two back-to-back refreshes both saw an
   empty inbounds array (the first hadn't resolved yet) so both fired
   the request. Moved the options fetch into its own one-shot effect.

* perf(inbounds): share nodes list with form modal instead of refetching

InboundsPage and InboundFormModal both called useNodes() — each
instance maintains its own state and fires its own /panel/api/nodes/list
fetch on mount. Since the modal is always rendered (open or not), every
page load hit the endpoint twice.

Threaded nodes from the page through an availableNodes prop on the form
modal so they share one fetch.

* docs(api): register /clients/list/paged endpoint

TestAPIRoutesDocumented was failing because the new paginated clients
endpoint added in this branch wasn't listed in endpoints.js.

web/controller/client.go

@@ -20,6 +20,7 @@ type ClientController struct {
 	clientService  service.ClientService
 	inboundService service.InboundService
 	xrayService    service.XrayService
+	settingService service.SettingService
 }
 
 func NewClientController(g *gin.RouterGroup) *ClientController {
@@ -30,6 +31,7 @@ func NewClientController(g *gin.RouterGroup) *ClientController {
 
 func (a *ClientController) initRouter(g *gin.RouterGroup) {
 	g.GET("/list", a.list)
+	g.GET("/list/paged", a.listPaged)
 	g.GET("/get/:email", a.get)
 	g.GET("/traffic/:email", a.getTrafficByEmail)
 	g.GET("/subLinks/:subId", a.getSubLinks)
@@ -60,6 +62,20 @@ func (a *ClientController) list(c *gin.Context) {
 	jsonObj(c, rows, nil)
 }
 
+func (a *ClientController) listPaged(c *gin.Context) {
+	var params service.ClientPageParams
+	if err := c.ShouldBindQuery(&params); err != nil {
+		jsonMsg(c, I18nWeb(c, "pages.inbounds.toasts.obtain"), err)
+		return
+	}
+	resp, err := a.clientService.ListPaged(&a.inboundService, &a.settingService, params)
+	if err != nil {
+		jsonMsg(c, I18nWeb(c, "pages.inbounds.toasts.obtain"), err)
+		return
+	}
+	jsonObj(c, resp, nil)
+}
+
 func (a *ClientController) get(c *gin.Context) {
 	email := c.Param("email")
 	rec, err := a.clientService.GetRecordByEmail(nil, email)

web/controller/inbound.go

@@ -61,6 +61,7 @@ func (a *InboundController) broadcastInboundsUpdate(userId int) {
 func (a *InboundController) initRouter(g *gin.RouterGroup) {
 
 	g.GET("/list", a.getInbounds)
+	g.GET("/list/slim", a.getInboundsSlim)
 	g.GET("/options", a.getInboundOptions)
 	g.GET("/get/:id", a.getInbound)
 	g.GET("/:id/fallbacks", a.getFallbacks)
@@ -86,6 +87,18 @@ func (a *InboundController) getInbounds(c *gin.Context) {
 	jsonObj(c, inbounds, nil)
 }
 
+// getInboundsSlim is the list-page variant that strips full client
+// payloads from settings.clients[]. Detail-view flows still use /get/:id.
+func (a *InboundController) getInboundsSlim(c *gin.Context) {
+	user := session.GetLoginUser(c)
+	inbounds, err := a.inboundService.GetInboundsSlim(user.Id)
+	if err != nil {
+		jsonMsg(c, I18nWeb(c, "pages.inbounds.toasts.obtain"), err)
+		return
+	}
+	jsonObj(c, inbounds, nil)
+}
+
 // getInboundOptions returns a lightweight projection of the user's inbounds
 // (id, remark, protocol, port, tlsFlowCapable) for pickers in the clients UI.
 // Avoids shipping per-client settings and traffic stats just to fill a dropdown.

web/service/client.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"sort"
 	"strings"
 	"sync"
 	"time"
@@ -803,6 +804,351 @@ func (s *ClientService) ResetTrafficByEmail(inboundSvc *InboundService, email st
 	return needRestart, nil
 }
 
+// ClientSlim is the row-shape used by the clients page. It drops fields the
+// table never reads (UUID, password, auth, flow, security, reverse, tgId)
+// so the list payload stays compact even when the panel manages thousands
+// of clients. Modals that need the full record still call /get/:email.
+type ClientSlim struct {
+	Email      string              `json:"email"`
+	SubID      string              `json:"subId"`
+	Enable     bool                `json:"enable"`
+	TotalGB    int64               `json:"totalGB"`
+	ExpiryTime int64               `json:"expiryTime"`
+	LimitIP    int                 `json:"limitIp"`
+	Reset      int                 `json:"reset"`
+	Comment    string              `json:"comment,omitempty"`
+	InboundIds []int               `json:"inboundIds"`
+	Traffic    *xray.ClientTraffic `json:"traffic,omitempty"`
+	CreatedAt  int64               `json:"createdAt"`
+	UpdatedAt  int64               `json:"updatedAt"`
+}
+
+// ClientPageParams are the query params accepted by /panel/api/clients/list/paged.
+// All fields are optional — the empty value means "no filter" / defaults.
+type ClientPageParams struct {
+	Page     int    `form:"page"`
+	PageSize int    `form:"pageSize"`
+	Search   string `form:"search"`
+	Filter   string `form:"filter"`
+	Protocol string `form:"protocol"`
+	Sort     string `form:"sort"`
+	Order    string `form:"order"`
+}
+
+// ClientPageResponse is the shape returned by ListPaged. `Total` is the
+// row count in the DB; `Filtered` is the count after Search/Filter/Protocol
+// were applied, before pagination. The page contains at most PageSize items.
+// Summary is computed across the full DB row set so dashboard counters
+// on the clients page stay stable as the user paginates/filters.
+type ClientPageResponse struct {
+	Items    []ClientSlim   `json:"items"`
+	Total    int            `json:"total"`
+	Filtered int            `json:"filtered"`
+	Page     int            `json:"page"`
+	PageSize int            `json:"pageSize"`
+	Summary  ClientsSummary `json:"summary"`
+}
+
+// ClientsSummary collects per-bucket counts plus the matching email lists so
+// the clients page can render the dashboard stat cards and their hover
+// popovers without shipping the full client array.
+type ClientsSummary struct {
+	Total    int      `json:"total"`
+	Active   int      `json:"active"`
+	Online   []string `json:"online"`
+	Depleted []string `json:"depleted"`
+	Expiring []string `json:"expiring"`
+	Deactive []string `json:"deactive"`
+}
+
+const (
+	clientPageDefaultSize = 25
+	clientPageMaxSize     = 200
+)
+
+// ListPaged loads every client (with traffic + attachments) into memory,
+// applies the requested filter / search / protocol predicates, sorts, and
+// returns the requested page along with total and filtered counts. The DB
+// query itself is unchanged from List(); the win is that the response
+// only carries 25-ish slim rows over the wire instead of all 2000 full
+// records, which on real panels was the dominant cost.
+func (s *ClientService) ListPaged(inboundSvc *InboundService, settingSvc *SettingService, params ClientPageParams) (*ClientPageResponse, error) {
+	all, err := s.List()
+	if err != nil {
+		return nil, err
+	}
+	total := len(all)
+
+	pageSize := params.PageSize
+	if pageSize <= 0 {
+		pageSize = clientPageDefaultSize
+	}
+	if pageSize > clientPageMaxSize {
+		pageSize = clientPageMaxSize
+	}
+	page := params.Page
+	if page <= 0 {
+		page = 1
+	}
+
+	var protocolByInbound map[int]string
+	if params.Protocol != "" {
+		inbounds, err := inboundSvc.GetAllInbounds()
+		if err == nil {
+			protocolByInbound = make(map[int]string, len(inbounds))
+			for _, ib := range inbounds {
+				protocolByInbound[ib.Id] = string(ib.Protocol)
+			}
+		}
+	}
+
+	onlines := inboundSvc.GetOnlineClients()
+	onlineSet := make(map[string]struct{}, len(onlines))
+	for _, e := range onlines {
+		onlineSet[e] = struct{}{}
+	}
+
+	var expireDiffMs, trafficDiffBytes int64
+	if settingSvc != nil {
+		if v, err := settingSvc.GetExpireDiff(); err == nil {
+			expireDiffMs = int64(v) * 86400000
+		}
+		if v, err := settingSvc.GetTrafficDiff(); err == nil {
+			trafficDiffBytes = int64(v) * 1073741824
+		}
+	}
+
+	nowMs := time.Now().UnixMilli()
+	summary := buildClientsSummary(all, onlineSet, nowMs, expireDiffMs, trafficDiffBytes)
+
+	needle := strings.ToLower(strings.TrimSpace(params.Search))
+
+	filtered := make([]ClientWithAttachments, 0, len(all))
+	for _, c := range all {
+		if needle != "" && !clientMatchesSearch(c, needle) {
+			continue
+		}
+		if params.Protocol != "" && !clientMatchesProtocol(c, params.Protocol, protocolByInbound) {
+			continue
+		}
+		if params.Filter != "" && !clientMatchesBucket(c, params.Filter, onlineSet, nowMs, expireDiffMs, trafficDiffBytes) {
+			continue
+		}
+		filtered = append(filtered, c)
+	}
+
+	sortClients(filtered, params.Sort, params.Order)
+
+	filteredCount := len(filtered)
+	start := (page - 1) * pageSize
+	end := start + pageSize
+	if start > filteredCount {
+		start = filteredCount
+	}
+	if end > filteredCount {
+		end = filteredCount
+	}
+	pageRows := filtered[start:end]
+
+	items := make([]ClientSlim, 0, len(pageRows))
+	for _, c := range pageRows {
+		items = append(items, toClientSlim(c))
+	}
+
+	return &ClientPageResponse{
+		Items:    items,
+		Total:    total,
+		Filtered: filteredCount,
+		Page:     page,
+		PageSize: pageSize,
+		Summary:  summary,
+	}, nil
+}
+
+func buildClientsSummary(all []ClientWithAttachments, onlineSet map[string]struct{}, nowMs, expireDiffMs, trafficDiffBytes int64) ClientsSummary {
+	s := ClientsSummary{
+		Total:    len(all),
+		Online:   []string{},
+		Depleted: []string{},
+		Expiring: []string{},
+		Deactive: []string{},
+	}
+	for _, c := range all {
+		used := int64(0)
+		if c.Traffic != nil {
+			used = c.Traffic.Up + c.Traffic.Down
+		}
+		exhausted := c.TotalGB > 0 && used >= c.TotalGB
+		expired := c.ExpiryTime > 0 && c.ExpiryTime <= nowMs
+		if c.Enable {
+			if _, ok := onlineSet[c.Email]; ok {
+				s.Online = append(s.Online, c.Email)
+			}
+		}
+		if exhausted || expired {
+			s.Depleted = append(s.Depleted, c.Email)
+			continue
+		}
+		if !c.Enable {
+			s.Deactive = append(s.Deactive, c.Email)
+			continue
+		}
+		nearExpiry := c.ExpiryTime > 0 && c.ExpiryTime-nowMs < expireDiffMs
+		nearLimit := c.TotalGB > 0 && c.TotalGB-used < trafficDiffBytes
+		if nearExpiry || nearLimit {
+			s.Expiring = append(s.Expiring, c.Email)
+		} else {
+			s.Active++
+		}
+	}
+	return s
+}
+
+func toClientSlim(c ClientWithAttachments) ClientSlim {
+	return ClientSlim{
+		Email:      c.Email,
+		SubID:      c.SubID,
+		Enable:     c.Enable,
+		TotalGB:    c.TotalGB,
+		ExpiryTime: c.ExpiryTime,
+		LimitIP:    c.LimitIP,
+		Reset:      c.Reset,
+		Comment:    c.Comment,
+		InboundIds: c.InboundIds,
+		Traffic:    c.Traffic,
+		CreatedAt:  c.CreatedAt,
+		UpdatedAt:  c.UpdatedAt,
+	}
+}
+
+func clientMatchesSearch(c ClientWithAttachments, needle string) bool {
+	if needle == "" {
+		return true
+	}
+	if strings.Contains(strings.ToLower(c.Email), needle) {
+		return true
+	}
+	if strings.Contains(strings.ToLower(c.SubID), needle) {
+		return true
+	}
+	if strings.Contains(strings.ToLower(c.Comment), needle) {
+		return true
+	}
+	return false
+}
+
+func clientMatchesProtocol(c ClientWithAttachments, protocol string, byInbound map[int]string) bool {
+	if protocol == "" {
+		return true
+	}
+	for _, id := range c.InboundIds {
+		if byInbound[id] == protocol {
+			return true
+		}
+	}
+	return false
+}
+
+func clientMatchesBucket(c ClientWithAttachments, bucket string, onlineSet map[string]struct{}, nowMs, expireDiffMs, trafficDiffBytes int64) bool {
+	if bucket == "" {
+		return true
+	}
+	used := int64(0)
+	if c.Traffic != nil {
+		used = c.Traffic.Up + c.Traffic.Down
+	}
+	exhausted := c.TotalGB > 0 && used >= c.TotalGB
+	expired := c.ExpiryTime > 0 && c.ExpiryTime <= nowMs
+	switch bucket {
+	case "online":
+		if onlineSet == nil {
+			return false
+		}
+		_, ok := onlineSet[c.Email]
+		return ok && c.Enable
+	case "depleted":
+		return exhausted || expired
+	case "deactive":
+		return !c.Enable
+	case "active":
+		return c.Enable && !exhausted && !expired
+	case "expiring":
+		if !c.Enable || exhausted || expired {
+			return false
+		}
+		nearExpiry := c.ExpiryTime > 0 && c.ExpiryTime-nowMs < expireDiffMs
+		nearLimit := c.TotalGB > 0 && c.TotalGB-used < trafficDiffBytes
+		return nearExpiry || nearLimit
+	}
+	return true
+}
+
+func sortClients(rows []ClientWithAttachments, sortKey, order string) {
+	if sortKey == "" {
+		return
+	}
+	desc := order == "descend"
+	less := func(i, j int) bool {
+		a, b := rows[i], rows[j]
+		switch sortKey {
+		case "enable":
+			if a.Enable == b.Enable {
+				return false
+			}
+			return !a.Enable && b.Enable
+		case "email":
+			return strings.ToLower(a.Email) < strings.ToLower(b.Email)
+		case "inboundIds":
+			return len(a.InboundIds) < len(b.InboundIds)
+		case "traffic":
+			ua := int64(0)
+			if a.Traffic != nil {
+				ua = a.Traffic.Up + a.Traffic.Down
+			}
+			ub := int64(0)
+			if b.Traffic != nil {
+				ub = b.Traffic.Up + b.Traffic.Down
+			}
+			return ua < ub
+		case "remaining":
+			ra := int64(1<<62 - 1)
+			if a.TotalGB > 0 {
+				used := int64(0)
+				if a.Traffic != nil {
+					used = a.Traffic.Up + a.Traffic.Down
+				}
+				ra = a.TotalGB - used
+			}
+			rb := int64(1<<62 - 1)
+			if b.TotalGB > 0 {
+				used := int64(0)
+				if b.Traffic != nil {
+					used = b.Traffic.Up + b.Traffic.Down
+				}
+				rb = b.TotalGB - used
+			}
+			return ra < rb
+		case "expiryTime":
+			ea := int64(1<<62 - 1)
+			if a.ExpiryTime > 0 {
+				ea = a.ExpiryTime
+			}
+			eb := int64(1<<62 - 1)
+			if b.ExpiryTime > 0 {
+				eb = b.ExpiryTime
+			}
+			return ea < eb
+		}
+		return false
+	}
+	sort.SliceStable(rows, func(i, j int) bool {
+		if desc {
+			return less(j, i)
+		}
+		return less(i, j)
+	})
+}
+
 // BulkAdjustResult is returned by BulkAdjust to report how many clients were
 // successfully updated and which were skipped (typically because the field
 // being adjusted was unlimited for that client) or failed.

web/service/inbound.go

@@ -135,6 +135,71 @@ func (s *InboundService) GetInbounds(userId int) ([]*model.Inbound, error) {
 	return inbounds, nil
 }
 
+// GetInboundsSlim returns the same list of inbounds as GetInbounds but
+// strips every per-client field other than email / enable / comment from
+// settings.clients and skips UUID/SubId enrichment on ClientStats. The
+// inbounds page only needs those three to roll up client counts and
+// render badges, so this trims tens of bytes per client (UUID, password,
+// flow, security, totalGB, expiryTime, limitIp, tgId, ...) which adds
+// up fast on installs with thousands of clients.
+//
+// Full client data is still available through GET /panel/api/inbounds/get/:id
+// for the edit/info/qr/export/clone flows that need it.
+func (s *InboundService) GetInboundsSlim(userId int) ([]*model.Inbound, error) {
+	db := database.GetDB()
+	var inbounds []*model.Inbound
+	err := db.Model(model.Inbound{}).Preload("ClientStats").Where("user_id = ?", userId).Find(&inbounds).Error
+	if err != nil && err != gorm.ErrRecordNotFound {
+		return nil, err
+	}
+	s.annotateFallbackParents(db, inbounds)
+	for _, ib := range inbounds {
+		ib.Settings = slimSettingsClients(ib.Settings)
+	}
+	return inbounds, nil
+}
+
+// slimSettingsClients rewrites the inbound settings JSON so settings.clients[]
+// keeps only the fields the list view actually reads. Returns the input
+// unchanged when the JSON can't be parsed or has no clients array.
+func slimSettingsClients(settings string) string {
+	if settings == "" {
+		return settings
+	}
+	var raw map[string]any
+	if err := json.Unmarshal([]byte(settings), &raw); err != nil {
+		return settings
+	}
+	clients, ok := raw["clients"].([]any)
+	if !ok || len(clients) == 0 {
+		return settings
+	}
+	slim := make([]any, 0, len(clients))
+	for _, entry := range clients {
+		c, ok := entry.(map[string]any)
+		if !ok {
+			continue
+		}
+		row := make(map[string]any, 3)
+		if v, ok := c["email"]; ok {
+			row["email"] = v
+		}
+		if v, ok := c["enable"]; ok {
+			row["enable"] = v
+		}
+		if v, ok := c["comment"]; ok && v != "" {
+			row["comment"] = v
+		}
+		slim = append(slim, row)
+	}
+	raw["clients"] = slim
+	out, err := json.Marshal(raw)
+	if err != nil {
+		return settings
+	}
+	return string(out)
+}
+
 // annotateFallbackParents fills FallbackParent on each inbound that is
 // the child side of a fallback rule. One DB round-trip serves the full
 // list — the frontend needs this to rewrite the child's client-share
@@ -177,6 +242,7 @@ func (s *InboundService) annotateFallbackParents(db *gorm.DB, inbounds []*model.
 type InboundOption struct {
 	Id             int    `json:"id"`
 	Remark         string `json:"remark"`
+	Tag            string `json:"tag"`
 	Protocol       string `json:"protocol"`
 	Port           int    `json:"port"`
 	TlsFlowCapable bool   `json:"tlsFlowCapable"`
@@ -191,12 +257,13 @@ func (s *InboundService) GetInboundOptions(userId int) ([]InboundOption, error)
 	var rows []struct {
 		Id             int    `gorm:"column:id"`
 		Remark         string `gorm:"column:remark"`
+		Tag            string `gorm:"column:tag"`
 		Protocol       string `gorm:"column:protocol"`
 		Port           int    `gorm:"column:port"`
 		StreamSettings string `gorm:"column:stream_settings"`
 	}
 	err := db.Table("inbounds").
-		Select("id, remark, protocol, port, stream_settings").
+		Select("id, remark, tag, protocol, port, stream_settings").
 		Where("user_id = ?", userId).
 		Order("id ASC").
 		Scan(&rows).Error
@@ -208,6 +275,7 @@ func (s *InboundService) GetInboundOptions(userId int) ([]InboundOption, error)
 		out = append(out, InboundOption{
 			Id:             r.Id,
 			Remark:         r.Remark,
+			Tag:            r.Tag,
 			Protocol:       r.Protocol,
 			Port:           r.Port,
 			TlsFlowCapable: inboundCanEnableTlsFlow(r.Protocol, r.StreamSettings),