feat(clients,groups): client groups + sub-links export + dedicated groups page

Persistent client groups
- New ClientGroup model + client_groups table that holds empty
  (placeholder) groups so a user can define a label before any client
  references it. ListGroups merges these with the distinct group_name
  values already stored on clients and reports {name, clientCount}.
- ClientRecord gains group_name column; the model.Client wire shape
  gains a matching `group` JSON field that survives the
  inbound.settings → SyncInbound round-trip.
- Rename/Delete on a group mutates client_groups (rename row / delete
  row) AND propagates to all matching clients in ClientRecord and in
  every owning inbound's settings JSON, all in one transaction.

Bulk operations
- AssignGroup(emails, group) updates clients.group_name + patches each
  affected inbound's settings JSON in one read-modify-write per inbound.
  Empty group clears the label. Auto-creates the client_groups row when
  the user assigns to a brand-new name.
- BulkResetTraffic(emails) loops the existing single-reset path so the
  caller can zero traffic across a whole selection or a whole group.
- EmailsByGroup(name) returns just the email list (used by the groups
  page to fan a single bulk action over every member).

Endpoints (all under /panel/api/clients)
- GET  /groups                         — summaries with counts
- GET  /groups/:name/emails            — emails in a group
- POST /groups/create                  — empty placeholder group
- POST /groups/rename                  — rename (table + clients + JSON)
- POST /groups/delete                  — drop label everywhere (clients survive)
- POST /bulkAssignGroup                — assign N selected clients
- POST /bulkResetTraffic               — reset traffic on a list

Clients page UX
- New Group column (Actions → Client → Group → Inbounds → …) with a
  click-to-filter chip.
- FilterDrawer gains a multi-select Group filter whose options come
  from the new ClientPageResponse.groups field (sourced from ListGroups
  so empty/placeholder groups are pickable too).
- Single-client and bulk-add forms gain a Group AutoComplete pre-loaded
  with all known group names.
- New toolbar buttons when selection > 0: "Group ({n})" opens
  BulkAssignGroupModal, "Sub links ({n})" opens SubLinksModal.

Sub-links export modal (new SubLinksModal.tsx)
- Table of selected clients with their subscription URL (and JSON URL
  when subJsonEnable is on), per-row copy, Copy all, and Download as
  sub-links-<timestamp>.txt. Warns when subscription is disabled or
  none of the selected clients have a subId.

Dedicated Groups page (new pages/groups/GroupsPage.tsx)
- /groups route + sidebar entry (TagsOutlined icon) + page title key.
- Card-based layout matching Clients/Inbounds/Nodes — summary card with
  Total/Grouped/Empty stats, main card with Add Group button + table.
- Per-row More dropdown (icon-first column on the left): Sub links,
  Adjust (days+traffic), Reset traffic, Rename, Delete clients in
  group, Delete group (keep clients). Empty groups disable the
  client-targeted actions.
- Reuses SubLinksModal and ClientBulkAdjustModal — emails for the
  group are fetched on demand from GET /groups/:name/emails.

Other polish
- /groups + groups-page selectors added to page-shell.css and
  page-cards.css so the new page inherits the same background, padding,
  card borders, hover shadow, and summary-card padding.
- .card-toolbar gains a small vertical padding so the larger toolbar
  buttons (now default size, matching Inbounds) don't crowd the top of
  the card-head on Clients and Groups pages.
This commit is contained in:
MHSanaei
2026-05-27 17:30:55 +02:00
parent 7680e27d1d
commit 93eda06878
25 changed files with 2052 additions and 42 deletions
+127
View File
@@ -47,12 +47,20 @@ func (a *ClientController) initRouter(g *gin.RouterGroup) {
g.POST("/bulkAdjust", a.bulkAdjust)
g.POST("/bulkDel", a.bulkDelete)
g.POST("/bulkCreate", a.bulkCreate)
g.POST("/bulkAssignGroup", a.bulkAssignGroup)
g.POST("/resetTraffic/:email", a.resetTrafficByEmail)
g.POST("/updateTraffic/:email", a.updateTrafficByEmail)
g.POST("/ips/:email", a.getIps)
g.POST("/clearIps/:email", a.clearIps)
g.POST("/onlines", a.onlines)
g.POST("/lastOnline", a.lastOnline)
g.GET("/groups", a.listGroups)
g.GET("/groups/:name/emails", a.groupEmails)
g.POST("/groups/create", a.createGroup)
g.POST("/groups/rename", a.renameGroup)
g.POST("/groups/delete", a.deleteGroup)
g.POST("/bulkResetTraffic", a.bulkResetTraffic)
}
func (a *ClientController) list(c *gin.Context) {
@@ -210,6 +218,27 @@ type bulkDeleteRequest struct {
KeepTraffic bool `json:"keepTraffic"`
}
type bulkAssignGroupRequest struct {
Emails []string `json:"emails"`
Group string `json:"group"`
}
func (a *ClientController) bulkAssignGroup(c *gin.Context) {
var req bulkAssignGroupRequest
if err := c.ShouldBindJSON(&req); err != nil {
jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
return
}
affected, err := a.clientService.AssignGroup(req.Emails, req.Group)
if err != nil {
jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
return
}
jsonObj(c, gin.H{"affected": affected}, nil)
a.xrayService.SetToNeedRestart()
notifyClientsChanged()
}
func (a *ClientController) bulkDelete(c *gin.Context) {
var req bulkDeleteRequest
if err := c.ShouldBindJSON(&req); err != nil {
@@ -393,3 +422,101 @@ func (a *ClientController) detach(c *gin.Context) {
}
notifyClientsChanged()
}
func (a *ClientController) listGroups(c *gin.Context) {
rows, err := a.clientService.ListGroups()
if err != nil {
jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
return
}
jsonObj(c, rows, nil)
}
func (a *ClientController) groupEmails(c *gin.Context) {
name := c.Param("name")
emails, err := a.clientService.EmailsByGroup(name)
if err != nil {
jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
return
}
jsonObj(c, emails, nil)
}
type bulkResetRequest struct {
Emails []string `json:"emails"`
}
func (a *ClientController) bulkResetTraffic(c *gin.Context) {
var req bulkResetRequest
if err := c.ShouldBindJSON(&req); err != nil {
jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
return
}
affected, err := a.clientService.BulkResetTraffic(&a.inboundService, req.Emails)
if err != nil {
jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
return
}
jsonObj(c, gin.H{"affected": affected}, nil)
a.xrayService.SetToNeedRestart()
notifyClientsChanged()
}
type groupCreateBody struct {
Name string `json:"name"`
}
func (a *ClientController) createGroup(c *gin.Context) {
var body groupCreateBody
if err := c.ShouldBindJSON(&body); err != nil {
jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
return
}
if err := a.clientService.CreateGroup(body.Name); err != nil {
jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
return
}
jsonObj(c, gin.H{"name": body.Name}, nil)
notifyClientsChanged()
}
type groupRenameBody struct {
OldName string `json:"oldName"`
NewName string `json:"newName"`
}
func (a *ClientController) renameGroup(c *gin.Context) {
var body groupRenameBody
if err := c.ShouldBindJSON(&body); err != nil {
jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
return
}
affected, err := a.clientService.RenameGroup(body.OldName, body.NewName)
if err != nil {
jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
return
}
a.xrayService.SetToNeedRestart()
jsonObj(c, gin.H{"affected": affected}, nil)
notifyClientsChanged()
}
type groupDeleteBody struct {
Name string `json:"name"`
}
func (a *ClientController) deleteGroup(c *gin.Context) {
var body groupDeleteBody
if err := c.ShouldBindJSON(&body); err != nil {
jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
return
}
affected, err := a.clientService.DeleteGroup(body.Name)
if err != nil {
jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
return
}
a.xrayService.SetToNeedRestart()
jsonObj(c, gin.H{"affected": affected}, nil)
notifyClientsChanged()
}
+349
View File
@@ -237,6 +237,7 @@ func (s *ClientService) SyncInbound(tx *gorm.DB, inboundId int, clients []model.
row.ExpiryTime = incoming.ExpiryTime
row.Enable = incoming.Enable
row.TgID = incoming.TgID
row.Group = incoming.Group
row.Comment = incoming.Comment
row.Reset = incoming.Reset
if incoming.CreatedAt > 0 && (row.CreatedAt == 0 || incoming.CreatedAt < row.CreatedAt) {
@@ -863,6 +864,7 @@ type ClientSlim struct {
ExpiryTime int64 `json:"expiryTime"`
LimitIP int `json:"limitIp"`
Reset int `json:"reset"`
Group string `json:"group,omitempty"`
Comment string `json:"comment,omitempty"`
InboundIds []int `json:"inboundIds"`
Traffic *xray.ClientTraffic `json:"traffic,omitempty"`
@@ -894,6 +896,7 @@ type ClientPageParams struct {
AutoRenew string `form:"autoRenew"`
HasTgID string `form:"hasTgId"`
HasComment string `form:"hasComment"`
Group string `form:"group"`
}
// ClientPageResponse is the shape returned by ListPaged. `Total` is the
@@ -908,6 +911,7 @@ type ClientPageResponse struct {
Page int `json:"page"`
PageSize int `json:"pageSize"`
Summary ClientsSummary `json:"summary"`
Groups []string `json:"groups"`
}
// ClientsSummary collects per-bucket counts plus the matching email lists so
@@ -1017,6 +1021,9 @@ func (s *ClientService) ListPaged(inboundSvc *InboundService, settingSvc *Settin
if !clientMatchesHasComment(c, params.HasComment) {
continue
}
if !clientMatchesAnyGroup(c, params.Group) {
continue
}
filtered = append(filtered, c)
}
@@ -1038,6 +1045,15 @@ func (s *ClientService) ListPaged(inboundSvc *InboundService, settingSvc *Settin
items = append(items, toClientSlim(c))
}
groupRows, gErr := s.ListGroups()
if gErr != nil {
return nil, gErr
}
groups := make([]string, 0, len(groupRows))
for _, g := range groupRows {
groups = append(groups, g.Name)
}
return &ClientPageResponse{
Items: items,
Total: total,
@@ -1045,9 +1061,321 @@ func (s *ClientService) ListPaged(inboundSvc *InboundService, settingSvc *Settin
Page: page,
PageSize: pageSize,
Summary: summary,
Groups: groups,
}, nil
}
type GroupSummary struct {
Name string `json:"name"`
ClientCount int `json:"clientCount"`
}
func (s *ClientService) ListGroups() ([]GroupSummary, error) {
db := database.GetDB()
var derived []GroupSummary
if err := db.Model(&model.ClientRecord{}).
Select("group_name AS name, COUNT(*) AS client_count").
Where("group_name <> ''").
Group("group_name").
Scan(&derived).Error; err != nil {
return nil, err
}
var stored []model.ClientGroup
if err := db.Find(&stored).Error; err != nil {
return nil, err
}
merged := make(map[string]int, len(derived)+len(stored))
for _, g := range stored {
merged[g.Name] = 0
}
for _, g := range derived {
merged[g.Name] = g.ClientCount
}
out := make([]GroupSummary, 0, len(merged))
for name, count := range merged {
out = append(out, GroupSummary{Name: name, ClientCount: count})
}
sort.Slice(out, func(i, j int) bool {
return strings.ToLower(out[i].Name) < strings.ToLower(out[j].Name)
})
return out, nil
}
func (s *ClientService) EmailsByGroup(name string) ([]string, error) {
name = strings.TrimSpace(name)
if name == "" {
return []string{}, nil
}
db := database.GetDB()
var emails []string
if err := db.Model(&model.ClientRecord{}).
Where("group_name = ?", name).
Order("email ASC").
Pluck("email", &emails).Error; err != nil {
return nil, err
}
if emails == nil {
emails = []string{}
}
return emails, nil
}
func (s *ClientService) BulkResetTraffic(inboundSvc *InboundService, emails []string) (int, error) {
if len(emails) == 0 {
return 0, nil
}
count := 0
for _, email := range emails {
if _, err := s.ResetTrafficByEmail(inboundSvc, email); err != nil {
return count, err
}
count++
}
return count, nil
}
func (s *ClientService) CreateGroup(name string) error {
name = strings.TrimSpace(name)
if name == "" {
return common.NewError("group name is required")
}
db := database.GetDB()
var count int64
if err := db.Model(&model.ClientGroup{}).Where("name = ?", name).Count(&count).Error; err != nil {
return err
}
if count > 0 {
return common.NewError("group already exists")
}
return db.Create(&model.ClientGroup{Name: name}).Error
}
func (s *ClientService) RenameGroup(oldName, newName string) (int, error) {
oldName = strings.TrimSpace(oldName)
newName = strings.TrimSpace(newName)
if oldName == "" {
return 0, common.NewError("old group name is required")
}
if newName == "" {
return 0, common.NewError("new group name is required")
}
if oldName == newName {
return 0, nil
}
return s.replaceGroupValue(oldName, newName)
}
func (s *ClientService) DeleteGroup(name string) (int, error) {
name = strings.TrimSpace(name)
if name == "" {
return 0, common.NewError("group name is required")
}
return s.replaceGroupValue(name, "")
}
func (s *ClientService) AssignGroup(emails []string, group string) (int, error) {
group = strings.TrimSpace(group)
if len(emails) == 0 {
return 0, nil
}
db := database.GetDB()
if group != "" {
var exists int64
if err := db.Model(&model.ClientGroup{}).Where("name = ?", group).Count(&exists).Error; err != nil {
return 0, err
}
if exists == 0 {
var derived int64
if err := db.Model(&model.ClientRecord{}).Where("group_name = ?", group).Count(&derived).Error; err != nil {
return 0, err
}
if derived == 0 {
if err := db.Create(&model.ClientGroup{Name: group}).Error; err != nil {
return 0, err
}
}
}
}
var records []model.ClientRecord
if err := db.Where("email IN ?", emails).Find(&records).Error; err != nil {
return 0, err
}
if len(records) == 0 {
return 0, nil
}
affectedEmails := make([]string, 0, len(records))
for _, r := range records {
affectedEmails = append(affectedEmails, r.Email)
}
tx := db.Begin()
if err := tx.Model(&model.ClientRecord{}).
Where("email IN ?", affectedEmails).
UpdateColumn("group_name", group).Error; err != nil {
tx.Rollback()
return 0, err
}
var inboundIDs []int
if err := tx.Table("client_inbounds").
Joins("JOIN clients ON clients.id = client_inbounds.client_id").
Where("clients.email IN ?", affectedEmails).
Distinct("client_inbounds.inbound_id").
Pluck("inbound_id", &inboundIDs).Error; err != nil {
tx.Rollback()
return 0, err
}
emailSet := make(map[string]struct{}, len(affectedEmails))
for _, e := range affectedEmails {
emailSet[e] = struct{}{}
}
for _, ibID := range inboundIDs {
var ib model.Inbound
if err := tx.First(&ib, ibID).Error; err != nil {
tx.Rollback()
return 0, err
}
var settings map[string]any
if err := json.Unmarshal([]byte(ib.Settings), &settings); err != nil {
continue
}
clients, ok := settings["clients"].([]any)
if !ok {
continue
}
modified := false
for i := range clients {
cm, ok := clients[i].(map[string]any)
if !ok {
continue
}
email, _ := cm["email"].(string)
if _, hit := emailSet[email]; !hit {
continue
}
if group == "" {
delete(cm, "group")
} else {
cm["group"] = group
}
clients[i] = cm
modified = true
}
if modified {
settings["clients"] = clients
newSettings, err := json.Marshal(settings)
if err != nil {
continue
}
ib.Settings = string(newSettings)
if err := tx.Save(&ib).Error; err != nil {
tx.Rollback()
return 0, err
}
}
}
if err := tx.Commit().Error; err != nil {
return 0, err
}
return len(records), nil
}
func (s *ClientService) replaceGroupValue(oldName, newName string) (int, error) {
db := database.GetDB()
if newName == "" {
if err := db.Where("name = ?", oldName).Delete(&model.ClientGroup{}).Error; err != nil {
return 0, err
}
} else {
if err := db.Model(&model.ClientGroup{}).Where("name = ?", oldName).Update("name", newName).Error; err != nil {
return 0, err
}
}
var records []model.ClientRecord
if err := db.Where("group_name = ?", oldName).Find(&records).Error; err != nil {
return 0, err
}
if len(records) == 0 {
return 0, nil
}
affectedEmails := make([]string, 0, len(records))
for _, r := range records {
affectedEmails = append(affectedEmails, r.Email)
}
tx := db.Begin()
if err := tx.Model(&model.ClientRecord{}).
Where("group_name = ?", oldName).
UpdateColumn("group_name", newName).Error; err != nil {
tx.Rollback()
return 0, err
}
var inboundIDs []int
if err := tx.Table("client_inbounds").
Joins("JOIN clients ON clients.id = client_inbounds.client_id").
Where("clients.email IN ?", affectedEmails).
Distinct("client_inbounds.inbound_id").
Pluck("inbound_id", &inboundIDs).Error; err != nil {
tx.Rollback()
return 0, err
}
for _, ibID := range inboundIDs {
var ib model.Inbound
if err := tx.First(&ib, ibID).Error; err != nil {
tx.Rollback()
return 0, err
}
var settings map[string]any
if err := json.Unmarshal([]byte(ib.Settings), &settings); err != nil {
continue
}
clients, ok := settings["clients"].([]any)
if !ok {
continue
}
modified := false
for i := range clients {
cm, ok := clients[i].(map[string]any)
if !ok {
continue
}
if g, ok := cm["group"].(string); ok && g == oldName {
if newName == "" {
delete(cm, "group")
} else {
cm["group"] = newName
}
clients[i] = cm
modified = true
}
}
if modified {
settings["clients"] = clients
newSettings, err := json.Marshal(settings)
if err != nil {
continue
}
ib.Settings = string(newSettings)
if err := tx.Save(&ib).Error; err != nil {
tx.Rollback()
return 0, err
}
}
}
if err := tx.Commit().Error; err != nil {
return 0, err
}
return len(records), nil
}
func buildClientsSummary(all []ClientWithAttachments, onlineSet map[string]struct{}, nowMs, expireDiffMs, trafficDiffBytes int64) ClientsSummary {
s := ClientsSummary{
Total: len(all),
@@ -1096,6 +1424,7 @@ func toClientSlim(c ClientWithAttachments) ClientSlim {
ExpiryTime: c.ExpiryTime,
LimitIP: c.LimitIP,
Reset: c.Reset,
Group: c.Group,
Comment: c.Comment,
InboundIds: c.InboundIds,
Traffic: c.Traffic,
@@ -1261,6 +1590,26 @@ func clientMatchesHasComment(c ClientWithAttachments, mode string) bool {
return true
}
func clientMatchesAnyGroup(c ClientWithAttachments, csv string) bool {
groups := parseCSVStrings(csv)
if len(groups) == 0 {
return true
}
current := strings.TrimSpace(c.Group)
for _, g := range groups {
if g == "" {
if current == "" {
return true
}
continue
}
if strings.EqualFold(g, current) {
return true
}
}
return false
}
func clientMatchesBucket(c ClientWithAttachments, bucket string, onlineSet map[string]struct{}, nowMs, expireDiffMs, trafficDiffBytes int64) bool {
if bucket == "" {
return true
+48
View File
@@ -102,6 +102,7 @@
"dashboard": "Overview",
"inbounds": "Inbounds",
"clients": "Clients",
"groups": "Groups",
"nodes": "Nodes",
"settings": "Panel Settings",
"xray": "Xray Configs",
@@ -482,6 +483,9 @@
"subId": "Subscription ID",
"online": "Online",
"email": "Email",
"group": "Group",
"groupDesc": "Logical label used to bucket related clients (e.g. team, customer, region). Filterable from the toolbar.",
"groupPlaceholder": "e.g. customer-a",
"comment": "Comment",
"traffic": "Traffic",
"offline": "Offline",
@@ -509,6 +513,21 @@
"deleteConfirmContent": "This removes the client from every attached inbound and drops its traffic record. This cannot be undone.",
"deleteSelected": "Delete ({count})",
"adjustSelected": "Adjust ({count})",
"subLinksSelected": "Sub links ({count})",
"assignGroupSelected": "Group ({count})",
"assignGroupTitle": "Assign group to {count} client(s)",
"assignGroupTooltip": "Pick an existing group or type a new name. Leave blank to clear the group on the selected clients.",
"assignGroupPlaceholder": "Group name (leave blank to clear)",
"assignGroupAssignedToast": "Assigned {count} client(s) to {group}",
"assignGroupClearedToast": "Cleared group from {count} client(s)",
"subLinksTitle": "Sub links ({count})",
"subLinkColumn": "Subscription URL",
"subJsonLinkColumn": "Subscription JSON URL",
"subLinksCopyAll": "Copy all",
"subLinksCopiedAll": "Copied {count} link(s)",
"subLinksEmpty": "None of the selected clients have a subscription ID.",
"subLinksDisabled": "Subscription service is disabled.",
"subLinksDisabledHint": "Enable subscription in Panel Settings → Subscription to generate links.",
"bulkDeleteConfirmTitle": "Delete {count} clients?",
"bulkDeleteConfirmContent": "Each selected client is removed from every attached inbound and its traffic record is dropped. This cannot be undone.",
"bulkAdjustTitle": "Adjust {count} clients",
@@ -543,6 +562,35 @@
"delDepleted": "{count} depleted clients deleted"
}
},
"groups": {
"title": "Groups",
"name": "Name",
"clientCount": "Clients in group",
"totalGroups": "Total groups",
"totalGroupedClients": "Clients with a group",
"emptyGroups": "Empty groups",
"addGroup": "Add Group",
"createSuccess": "Group \"{name}\" created.",
"rename": "Rename",
"renameTitle": "Rename {name}",
"renameCollision": "A group named \"{name}\" already exists.",
"renameSuccess": "Renamed group on {count} client(s).",
"deleteConfirmTitle": "Delete group {name}?",
"deleteConfirmContent": "This removes the group and clears its label from {count} client(s). The clients themselves are not deleted.",
"deleteSuccess": "Cleared group from {count} client(s).",
"resetTraffic": "Reset traffic",
"resetConfirmTitle": "Reset traffic for group {name}?",
"resetConfirmContent": "This zeros up/down for all {count} client(s) in this group.",
"resetSuccess": "Reset traffic for {count} client(s).",
"adjustSuccess": "Adjusted {count} client(s) in {name}.",
"emptyForAction": "This group has no clients yet.",
"deleteGroupOnly": "Delete group (keep clients)",
"deleteClients": "Delete clients in group",
"deleteClientsConfirmTitle": "Delete all clients in {name}?",
"deleteClientsConfirmContent": "This permanently removes {count} client(s) along with their traffic records. The group label is cleared too. This cannot be undone.",
"deleteClientsSuccess": "Deleted {count} client(s).",
"deleteClientsMixed": "{ok} deleted, {failed} skipped"
},
"nodes": {
"title": "Nodes",
"addNode": "Add Node",