refactor(quota): migrate traffic quota from tunnel to user level (#311)

## Summary

- Replace tunnel-level traffic quota with user-level quota system
- Add `user_quota` table with daily/monthly limits and usage tracking
- Remove `tunnel_quota` table and related code
- Update user create/update API to accept quota configuration
- Migrate backup/restore to use user quota fields
- Update frontend to manage user quota instead of tunnel quota

## Test Plan

- [x] Backend unit tests pass
- [x] Contract tests updated for user quota
- [ ] Manual verification of quota enforcement

go-backend/internal/http/handler/flow_policy.go

@@ -44,6 +44,9 @@ func (h *Handler) processFlowItem(nodeID int64, item flowItem) {
 	if ok {
 		inFlow, outFlow := h.scaleFlowByTunnel(forwardID, item.D, item.U)
 		_ = h.repo.AddFlow(forwardID, userID, userTunnelID, inFlow, outFlow)
+		if quota, quotaErr := h.repo.AddUserQuotaUsage(userID, inFlow+outFlow, time.Now()); quotaErr == nil {
+			h.enforceUserQuotaIfNeeded(userID, quota)
+		}
 		h.processPeerShareFlowFromForward(forwardID, nodeID, serviceName, item)
 
 		if userTunnelID > 0 {
@@ -356,6 +359,9 @@ func (h *Handler) ensureUserTunnelForwardAllowed(userID int64, tunnelID int64, n
 	if flowLimit < current {
 		return errors.New("流量已超额，禁止开启转发")
 	}
+	if err := h.ensureUserForwardAllowedByQuota(userID, now); err != nil {
+		return err
+	}
 
 	userTunnelID, _, _, err := h.resolveUserTunnelAndLimiter(userID, tunnelID)
 	if err != nil {

go-backend/internal/http/handler/handler.go

@@ -101,6 +101,7 @@ func (h *Handler) Register(mux *http.ServeMux) {
 	mux.HandleFunc("/api/v1/user/update", h.userUpdate)
 	mux.HandleFunc("/api/v1/user/delete", h.userDelete)
 	mux.HandleFunc("/api/v1/user/reset", h.userResetFlow)
+	mux.HandleFunc("/api/v1/user/quota/reset", h.userQuotaReset)
 	mux.HandleFunc("/api/v1/user/groups", h.userGroups)
 	mux.HandleFunc("/api/v1/config/get", h.getConfigByName)
 	mux.HandleFunc("/api/v1/config/list", h.getConfigs)

go-backend/internal/http/handler/jobs.go

@@ -136,6 +136,7 @@ func (h *Handler) runResetAndExpiryJob(now time.Time) {
 	}
 
 	h.resetMonthlyFlow(now)
+	h.resetUserQuotaWindows(now)
 	h.disableExpiredUsers(now.UnixMilli())
 	h.disableExpiredUserTunnels(now.UnixMilli())
 }

go-backend/internal/http/handler/jobs_test.go

@@ -143,3 +143,40 @@ func TestRunResetAndExpiryJobResetsFlowAndDisablesExpiredRecords(t *testing.T) {
 		t.Fatalf("expected non-expiring forward to remain enabled, got status=%d", nonExpForwardStatus)
 	}
 }
+
+func TestRunResetAndExpiryJobResetsUserQuotaAndUnblocksUser(t *testing.T) {
+	dbPath := filepath.Join(t.TempDir(), "jobs-quota-reset.db")
+	r, err := repo.Open(dbPath)
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	t.Cleanup(func() { _ = r.Close() })
+
+	h := New(r, "secret")
+	now := time.Date(2026, 3, 12, 0, 0, 5, 0, time.UTC)
+	nowMs := now.UnixMilli()
+
+	if err := r.DB().Exec(`
+		INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(2, 'quota-reset-user', 'x', 1, 0, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, nowMs, nowMs).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+	if err := r.DB().Exec(`
+		INSERT INTO user_quota(user_id, daily_limit_gb, monthly_limit_gb, daily_used_bytes, monthly_used_bytes, day_key, month_key, disabled_by_quota, disabled_at, paused_forward_ids, created_time, updated_time)
+		VALUES(2, 10, 0, ?, ?, 20260311, 202603, 1, ?, '', ?, ?)
+	`, 11*int64(1024*1024*1024), 11*int64(1024*1024*1024), nowMs, nowMs, nowMs).Error; err != nil {
+		t.Fatalf("insert user quota: %v", err)
+	}
+
+	h.runResetAndExpiryJob(now)
+
+	dailyUsed := mustQueryInt(t, r, `SELECT daily_used_bytes FROM user_quota WHERE user_id = 2`)
+	if dailyUsed != 0 {
+		t.Fatalf("expected daily quota usage reset, got %d", dailyUsed)
+	}
+	quotaDisabled := mustQueryInt(t, r, `SELECT disabled_by_quota FROM user_quota WHERE user_id = 2`)
+	if quotaDisabled != 0 {
+		t.Fatalf("expected quota disabled flag cleared, got %d", quotaDisabled)
+	}
+}

go-backend/internal/http/handler/mutations.go

@@ -60,6 +60,12 @@ func (h *Handler) userCreate(w http.ResponseWriter, r *http.Request) {
 	num := asInt(req["num"], 10)
 	expTime := asInt64(req["expTime"], time.Now().Add(365*24*time.Hour).UnixMilli())
 	flowResetTime := asInt64(req["flowResetTime"], 1)
+	dailyQuotaGB := asInt64(req["dailyQuotaGB"], 0)
+	monthlyQuotaGB := asInt64(req["monthlyQuotaGB"], 0)
+	if dailyQuotaGB < 0 || monthlyQuotaGB < 0 {
+		response.WriteJSON(w, response.ErrDefault("配额不能小于0"))
+		return
+	}
 	roleID := 1
 	now := time.Now().UnixMilli()
 
@@ -68,6 +74,22 @@ func (h *Handler) userCreate(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
+	if dailyQuotaGB > 0 || monthlyQuotaGB > 0 {
+		tx := h.repo.BeginTx()
+		if tx == nil || tx.Error != nil {
+			response.WriteJSON(w, response.Err(-2, "database unavailable"))
+			return
+		}
+		defer func() { tx.Rollback() }()
+		if err := h.repo.SaveUserQuotaConfigTx(tx, userID, dailyQuotaGB, monthlyQuotaGB, now); err != nil {
+			response.WriteJSON(w, response.Err(-2, err.Error()))
+			return
+		}
+		if err := tx.Commit().Error; err != nil {
+			response.WriteJSON(w, response.Err(-2, err.Error()))
+			return
+		}
+	}
 
 	groupIDs := asInt64Slice(req["groupIds"])
 	if len(groupIDs) > 0 {
@@ -131,6 +153,8 @@ func (h *Handler) userUpdate(w http.ResponseWriter, r *http.Request) {
 	expTime := asInt64(req["expTime"], time.Now().Add(365*24*time.Hour).UnixMilli())
 	flowResetTime := asInt64(req["flowResetTime"], 1)
 	status := asInt(req["status"], 1)
+	_, hasDailyQuota := req["dailyQuotaGB"]
+	_, hasMonthlyQuota := req["monthlyQuotaGB"]
 	now := time.Now().UnixMilli()
 
 	pwd := asString(req["pwd"])
@@ -147,6 +171,34 @@ func (h *Handler) userUpdate(w http.ResponseWriter, r *http.Request) {
 	}
 
 	h.repo.PropagateUserFlowToTunnels(id, flow, num, expTime, flowResetTime)
+	if hasDailyQuota || hasMonthlyQuota {
+		dailyQuotaGB := asInt64(req["dailyQuotaGB"], 0)
+		monthlyQuotaGB := asInt64(req["monthlyQuotaGB"], 0)
+		if !(hasDailyQuota && hasMonthlyQuota) {
+			if currentQuota, err := h.repo.GetUserQuotaView(id, time.Now()); err == nil && currentQuota != nil {
+				if !hasDailyQuota {
+					dailyQuotaGB = currentQuota.DailyLimitGB
+				}
+				if !hasMonthlyQuota {
+					monthlyQuotaGB = currentQuota.MonthlyLimitGB
+				}
+			}
+		}
+		tx := h.repo.BeginTx()
+		if tx == nil || tx.Error != nil {
+			response.WriteJSON(w, response.Err(-2, "database unavailable"))
+			return
+		}
+		defer func() { tx.Rollback() }()
+		if err := h.repo.SaveUserQuotaConfigTx(tx, id, dailyQuotaGB, monthlyQuotaGB, now); err != nil {
+			response.WriteJSON(w, response.Err(-2, err.Error()))
+			return
+		}
+		if err := tx.Commit().Error; err != nil {
+			response.WriteJSON(w, response.Err(-2, err.Error()))
+			return
+		}
+	}
 
 	if groupIDsRaw, ok := req["groupIds"]; ok {
 		newGroupIDs := asInt64Slice(groupIDsRaw)
@@ -684,6 +736,7 @@ func (h *Handler) tunnelUpdate(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.ErrDefault("隧道ID不能为空"))
 		return
 	}
+	oldEntryNodeIDs, _ := h.tunnelEntryNodeIDs(id)
 
 	h.cleanupTunnelRuntime(id)
 	h.cleanupFederationRuntime(id)
@@ -755,6 +808,12 @@ func (h *Handler) tunnelUpdate(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	newEntryNodeIDs, _ := h.tunnelEntryNodeIDs(id)
+	if !sameInt64Set(oldEntryNodeIDs, newEntryNodeIDs) {
+		h.cleanupTunnelForwardRuntimesOnRemovedEntryNodes(id, oldEntryNodeIDs, newEntryNodeIDs)
+		h.syncTunnelForwardsEntryPorts(id, newEntryNodeIDs)
+	}
+
 	if typeVal == 2 {
 		createdChains, createdServices, applyErr := h.applyTunnelRuntime(runtimeState)
 		if applyErr != nil {
@@ -779,6 +838,195 @@ func (h *Handler) tunnelUpdate(w http.ResponseWriter, r *http.Request) {
 	response.WriteJSON(w, response.OKEmpty())
 }
 
+func sameInt64Set(a, b []int64) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	if len(a) == 0 {
+		return true
+	}
+	m := make(map[int64]int, len(a))
+	for _, v := range a {
+		m[v]++
+	}
+	for _, v := range b {
+		c, ok := m[v]
+		if !ok || c <= 0 {
+			return false
+		}
+		if c == 1 {
+			delete(m, v)
+			continue
+		}
+		m[v] = c - 1
+	}
+	return len(m) == 0
+}
+
+func pickForwardPortFromRecords(ports []forwardPortRecord) int {
+	min := 0
+	for _, fp := range ports {
+		if fp.Port <= 0 {
+			continue
+		}
+		if min == 0 || fp.Port < min {
+			min = fp.Port
+		}
+	}
+	return min
+}
+
+func forwardPortNodeIDs(ports []forwardPortRecord) []int64 {
+	ids := make([]int64, 0, len(ports))
+	for _, fp := range ports {
+		if fp.NodeID <= 0 {
+			continue
+		}
+		ids = append(ids, fp.NodeID)
+	}
+	return uniqueInt64s(ids)
+}
+
+func (h *Handler) deleteForwardServicesOnNodeBatch(forward *forwardRecord, nodeID int64) error {
+	if h == nil || forward == nil || nodeID <= 0 {
+		return errors.New("invalid forward service cleanup context")
+	}
+	bases, err := h.forwardServiceBaseCandidates(forward)
+	if err != nil {
+		return err
+	}
+	if len(bases) == 0 {
+		return nil
+	}
+
+	names := make([]string, 0, len(bases)*3)
+	seen := make(map[string]struct{}, len(bases)*3)
+	appendName := func(name string) {
+		if strings.TrimSpace(name) == "" {
+			return
+		}
+		if _, ok := seen[name]; ok {
+			return
+		}
+		seen[name] = struct{}{}
+		names = append(names, name)
+	}
+	for _, base := range bases {
+		appendName(base + "_tcp")
+		appendName(base + "_udp")
+		appendName(base)
+	}
+	if len(names) == 0 {
+		return nil
+	}
+
+	payload := map[string]interface{}{"services": names}
+	_, err = h.sendNodeCommand(nodeID, "DeleteService", payload, false, true)
+	return err
+}
+
+func uniqueInt64s(input []int64) []int64 {
+	if len(input) <= 1 {
+		return input
+	}
+	seen := make(map[int64]struct{}, len(input))
+	out := make([]int64, 0, len(input))
+	for _, v := range input {
+		if _, ok := seen[v]; ok {
+			continue
+		}
+		seen[v] = struct{}{}
+		out = append(out, v)
+	}
+	return out
+}
+
+func diffInt64s(base, subtract []int64) []int64 {
+	if len(base) == 0 {
+		return nil
+	}
+	seen := make(map[int64]struct{}, len(subtract))
+	for _, v := range subtract {
+		seen[v] = struct{}{}
+	}
+	out := make([]int64, 0, len(base))
+	for _, v := range base {
+		if _, ok := seen[v]; ok {
+			continue
+		}
+		out = append(out, v)
+	}
+	return uniqueInt64s(out)
+}
+
+func (h *Handler) cleanupTunnelForwardRuntimesOnRemovedEntryNodes(tunnelID int64, oldEntryNodeIDs, newEntryNodeIDs []int64) {
+	if h == nil || h.repo == nil || tunnelID <= 0 {
+		return
+	}
+
+	removedNodeIDs := diffInt64s(oldEntryNodeIDs, newEntryNodeIDs)
+	if len(removedNodeIDs) == 0 {
+		return
+	}
+
+	forwards, err := h.listForwardsByTunnel(tunnelID)
+	if err != nil || len(forwards) == 0 {
+		return
+	}
+
+	for i := range forwards {
+		f := &forwards[i]
+		if f == nil {
+			continue
+		}
+		for _, nodeID := range removedNodeIDs {
+			_ = h.deleteForwardServicesOnNode(f, nodeID)
+		}
+	}
+}
+
+func (h *Handler) syncTunnelForwardsEntryPorts(tunnelID int64, entryNodeIDs []int64) {
+	if h == nil || h.repo == nil || tunnelID <= 0 {
+		return
+	}
+	entryNodeIDs = uniqueInt64s(entryNodeIDs)
+	if len(entryNodeIDs) == 0 {
+		return
+	}
+
+	forwards, err := h.listForwardsByTunnel(tunnelID)
+	if err != nil || len(forwards) == 0 {
+		return
+	}
+
+	allowInIP := len(entryNodeIDs) == 1
+	for i := range forwards {
+		f := &forwards[i]
+		if f == nil {
+			continue
+		}
+		oldPorts, err := h.listForwardPorts(f.ID)
+		if err != nil {
+			continue
+		}
+		port := pickForwardPortFromRecords(oldPorts)
+		if port <= 0 {
+			continue
+		}
+
+		var entries []forwardPortReplaceEntry
+		if allowInIP {
+			entries = buildForwardPortEntriesWithPreservedInIP(entryNodeIDs, oldPorts, port)
+		} else {
+			entries = make([]forwardPortReplaceEntry, 0, len(entryNodeIDs))
+			for _, nid := range entryNodeIDs {
+				entries = append(entries, forwardPortReplaceEntry{NodeID: nid, Port: port, InIP: ""})
+			}
+		}
+		_ = h.repo.ReplaceForwardPorts(f.ID, entries)
+	}
+}
+
 func (h *Handler) tunnelDelete(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {
 		response.WriteJSON(w, response.ErrDefault("请求失败"))
@@ -1329,6 +1577,17 @@ func (h *Handler) forwardUpdate(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.ErrDefault("多入口隧道的转发不支持自定义监听IP"))
 		return
 	}
+	// When switching tunnels, entry nodes / service base may change. We must clean up old
+	// listeners on nodes that will be removed, otherwise the old ports keep listening.
+	tunnelChanged := tunnelID != forward.TunnelID
+	oldNodeIDs := forwardPortNodeIDs(oldPorts)
+	newNodeIDs := uniqueInt64s(fwdEntryNodes)
+	var removedNodeIDs []int64
+	var keptNodeIDs []int64
+	if tunnelChanged {
+		removedNodeIDs = diffInt64s(oldNodeIDs, newNodeIDs)
+		keptNodeIDs = diffInt64s(oldNodeIDs, removedNodeIDs)
+	}
 	for _, nodeID := range fwdEntryNodes {
 		node, nodeErr := h.getNodeRecord(nodeID)
 		if nodeErr != nil {
@@ -1370,12 +1629,41 @@ func (h *Handler) forwardUpdate(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
-	warnings, err := h.syncForwardServicesWithWarnings(updatedForward, "UpdateService", true)
+	warnings := make([]string, 0)
+	if tunnelChanged && len(keptNodeIDs) > 0 {
+		for _, nodeID := range keptNodeIDs {
+			if delErr := h.deleteForwardServicesOnNodeBatch(forward, nodeID); delErr != nil {
+				nodeLabel := fmt.Sprintf("%d", nodeID)
+				if n, nErr := h.getNodeRecord(nodeID); nErr == nil && n != nil && strings.TrimSpace(n.Name) != "" {
+					nodeLabel = strings.TrimSpace(n.Name)
+				}
+				warnings = append(warnings, fmt.Sprintf("节点 %s 清理旧转发监听失败: %v", nodeLabel, delErr))
+			}
+		}
+		time.Sleep(tunnelServiceBindRetryDelay)
+	}
+
+	syncWarnings, err := h.syncForwardServicesWithWarnings(updatedForward, "UpdateService", true)
 	if err != nil {
 		h.rollbackForwardMutation(forward, oldPorts)
 		response.WriteJSON(w, response.ErrDefault(err.Error()))
 		return
 	}
+	warnings = append(warnings, syncWarnings...)
+
+	// Best-effort cleanup for old entry nodes after a successful tunnel switch.
+	// Avoid cleaning nodes that are still used by the updated forward.
+	if tunnelChanged && len(removedNodeIDs) > 0 {
+		for _, nodeID := range removedNodeIDs {
+			if delErr := h.deleteForwardServicesOnNodeBatch(forward, nodeID); delErr != nil {
+				nodeLabel := fmt.Sprintf("%d", nodeID)
+				if n, nErr := h.getNodeRecord(nodeID); nErr == nil && n != nil && strings.TrimSpace(n.Name) != "" {
+					nodeLabel = strings.TrimSpace(n.Name)
+				}
+				warnings = append(warnings, fmt.Sprintf("节点 %s 清理旧隧道残留服务失败: %v", nodeLabel, delErr))
+			}
+		}
+	}
 	if len(warnings) > 0 {
 		response.WriteJSON(w, response.OK(map[string]interface{}{"warnings": warnings}))
 		return
@@ -1678,6 +1966,7 @@ func (h *Handler) forwardBatchChangeTunnel(w http.ResponseWriter, r *http.Reques
 			fail++
 			continue
 		}
+		oldNodeIDs := forwardPortNodeIDs(oldPorts)
 		port := h.repo.GetMinForwardPort(id)
 		if err := h.repo.UpdateForwardTunnel(id, req.TargetTunnelID, time.Now().UnixMilli()); err != nil {
 			fail++
@@ -1691,6 +1980,9 @@ func (h *Handler) forwardBatchChangeTunnel(w http.ResponseWriter, r *http.Reques
 			p = h.pickTunnelPort(req.TargetTunnelID)
 		}
 		bctEntryNodes, _ := h.tunnelEntryNodeIDs(req.TargetTunnelID)
+		newNodeIDs := uniqueInt64s(bctEntryNodes)
+		removedNodeIDs := diffInt64s(oldNodeIDs, newNodeIDs)
+		keptNodeIDs := diffInt64s(oldNodeIDs, removedNodeIDs)
 		portRangeOk := true
 		for _, nid := range bctEntryNodes {
 			nd, ndErr := h.getNodeRecord(nid)
@@ -1717,11 +2009,22 @@ func (h *Handler) forwardBatchChangeTunnel(w http.ResponseWriter, r *http.Reques
 			fail++
 			continue
 		}
+		if len(keptNodeIDs) > 0 {
+			for _, nodeID := range keptNodeIDs {
+				_ = h.deleteForwardServicesOnNodeBatch(forward, nodeID)
+			}
+			time.Sleep(tunnelServiceBindRetryDelay)
+		}
 		if err := h.syncForwardServices(updatedForward, "UpdateService", true); err != nil {
 			h.rollbackForwardMutation(forward, oldPorts)
 			fail++
 			continue
 		}
+		if len(removedNodeIDs) > 0 {
+			for _, nodeID := range removedNodeIDs {
+				_ = h.deleteForwardServicesOnNodeBatch(forward, nodeID)
+			}
+		}
 		success++
 	}
 	response.WriteJSON(w, response.OK(map[string]interface{}{"successCount": success, "failCount": fail}))

go-backend/internal/http/handler/user_quota.go

@@ -0,0 +1,139 @@
+package handler
+
+import (
+	"errors"
+	"net/http"
+	"time"
+
+	"go-backend/internal/http/response"
+	"go-backend/internal/store/model"
+	"go-backend/internal/store/repo"
+)
+
+func isUserQuotaExceeded(view *model.UserQuotaView) bool {
+	if view == nil {
+		return false
+	}
+	if view.DailyLimitGB > 0 && view.DailyUsedBytes >= view.DailyLimitGB*bytesPerGB {
+		return true
+	}
+	if view.MonthlyLimitGB > 0 && view.MonthlyUsedBytes >= view.MonthlyLimitGB*bytesPerGB {
+		return true
+	}
+	return false
+}
+
+func (h *Handler) userQuotaBlockReason(userID int64, now int64) (string, error) {
+	if h == nil || h.repo == nil || userID <= 0 {
+		return "", nil
+	}
+	quota, err := h.repo.GetUserQuotaView(userID, time.UnixMilli(now))
+	if err != nil || quota == nil {
+		return "", err
+	}
+	if quota.DisabledByQuota == 1 || isUserQuotaExceeded(quota) {
+		return "该用户流量配额已超额，禁止开启转发", nil
+	}
+	return "", nil
+}
+
+func (h *Handler) enforceUserQuotaIfNeeded(userID int64, quota *model.UserQuotaView) {
+	if h == nil || h.repo == nil || userID <= 0 || quota == nil {
+		return
+	}
+	if quota.DisabledByQuota == 1 || !isUserQuotaExceeded(quota) {
+		return
+	}
+
+	forwards, err := h.listActiveForwardsByUser(userID)
+	if err != nil {
+		return
+	}
+	pausedIDs := make([]int64, 0, len(forwards))
+	now := time.Now().UnixMilli()
+	for i := range forwards {
+		forward := &forwards[i]
+		if forward.Status != 1 {
+			continue
+		}
+		if err := h.controlForwardServices(forward, "PauseService", false); err != nil {
+			continue
+		}
+		if err := h.repo.UpdateForwardStatus(forward.ID, 0, now); err != nil {
+			continue
+		}
+		pausedIDs = append(pausedIDs, forward.ID)
+	}
+	_ = h.repo.MarkUserQuotaDisabled(userID, pausedIDs, now)
+}
+
+func (h *Handler) applyUserQuotaRelease(release *repo.UserQuotaRelease, now int64) {
+	if h == nil || h.repo == nil || release == nil || release.UserID <= 0 || !release.UnblockUser {
+		return
+	}
+	for _, forwardID := range release.ForwardIDs {
+		forward, err := h.getForwardRecord(forwardID)
+		if err != nil || forward == nil {
+			continue
+		}
+		if err := h.ensureUserTunnelForwardAllowed(forward.UserID, forward.TunnelID, now); err != nil {
+			continue
+		}
+		if err := h.controlForwardServices(forward, "ResumeService", false); err != nil {
+			continue
+		}
+		_ = h.repo.UpdateForwardStatus(forwardID, 1, now)
+	}
+}
+
+func (h *Handler) resetUserQuotaWindows(now time.Time) {
+	if h == nil || h.repo == nil {
+		return
+	}
+	releases, err := h.repo.RollUserQuotaWindows(now)
+	if err != nil {
+		return
+	}
+	nowMs := now.UnixMilli()
+	for i := range releases {
+		h.applyUserQuotaRelease(&releases[i], nowMs)
+	}
+}
+
+func (h *Handler) userQuotaReset(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+	var req struct {
+		UserID int64  `json:"userId"`
+		Scope  string `json:"scope"`
+	}
+	if err := decodeJSON(r.Body, &req); err != nil {
+		response.WriteJSON(w, response.ErrDefault("请求参数错误"))
+		return
+	}
+	if req.UserID <= 0 {
+		response.WriteJSON(w, response.ErrDefault("用户ID不能为空"))
+		return
+	}
+	release, err := h.repo.ResetUserQuotaUsage(req.UserID, req.Scope, time.Now())
+	if err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+	nowMs := time.Now().UnixMilli()
+	h.applyUserQuotaRelease(release, nowMs)
+	response.WriteJSON(w, response.OKEmpty())
+}
+
+func (h *Handler) ensureUserForwardAllowedByQuota(userID int64, now int64) error {
+	reason, err := h.userQuotaBlockReason(userID, now)
+	if err != nil {
+		return err
+	}
+	if reason != "" {
+		return errors.New(reason)
+	}
+	return nil
+}

go-backend/internal/store/model/model.go

@@ -129,6 +129,23 @@ type Tunnel struct {
 
 func (Tunnel) TableName() string { return "tunnel" }
 
+type UserQuota struct {
+	UserID           int64  `gorm:"column:user_id;primaryKey"`
+	DailyLimitGB     int64  `gorm:"column:daily_limit_gb;not null;default:0"`
+	MonthlyLimitGB   int64  `gorm:"column:monthly_limit_gb;not null;default:0"`
+	DailyUsedBytes   int64  `gorm:"column:daily_used_bytes;not null;default:0"`
+	MonthlyUsedBytes int64  `gorm:"column:monthly_used_bytes;not null;default:0"`
+	DayKey           int64  `gorm:"column:day_key;not null;default:0"`
+	MonthKey         int64  `gorm:"column:month_key;not null;default:0"`
+	DisabledByQuota  int    `gorm:"column:disabled_by_quota;not null;default:0"`
+	DisabledAt       int64  `gorm:"column:disabled_at;not null;default:0"`
+	PausedForwardIDs string `gorm:"column:paused_forward_ids;type:text;not null;default:''"`
+	CreatedTime      int64  `gorm:"column:created_time;not null"`
+	UpdatedTime      int64  `gorm:"column:updated_time;not null"`
+}
+
+func (UserQuota) TableName() string { return "user_quota" }
+
 type ChainTunnel struct {
 	ID        int64          `gorm:"primaryKey;autoIncrement"`
 	TunnelID  int64          `gorm:"column:tunnel_id;not null"`
@@ -321,19 +338,23 @@ type BackupData struct {
 }
 
 type UserBackup struct {
-	ID            int64  `json:"id"`
-	User          string `json:"user"`
-	Pwd           string `json:"pwd"`
-	RoleID        int    `json:"roleId"`
-	ExpTime       int64  `json:"expTime"`
-	Flow          int64  `json:"flow"`
-	InFlow        int64  `json:"inFlow"`
-	OutFlow       int64  `json:"outFlow"`
-	FlowResetTime int64  `json:"flowResetTime"`
-	Num           int    `json:"num"`
-	CreatedTime   int64  `json:"createdTime"`
-	UpdatedTime   int64  `json:"updatedTime,omitempty"`
-	Status        int    `json:"status"`
+	ID              int64  `json:"id"`
+	User            string `json:"user"`
+	Pwd             string `json:"pwd"`
+	RoleID          int    `json:"roleId"`
+	ExpTime         int64  `json:"expTime"`
+	Flow            int64  `json:"flow"`
+	InFlow          int64  `json:"inFlow"`
+	OutFlow         int64  `json:"outFlow"`
+	FlowResetTime   int64  `json:"flowResetTime"`
+	DailyQuotaGB    int64  `json:"dailyQuotaGB,omitempty"`
+	MonthlyQuotaGB  int64  `json:"monthlyQuotaGB,omitempty"`
+	DisabledByQuota int    `json:"disabledByQuota,omitempty"`
+	QuotaDisabledAt int64  `json:"quotaDisabledAt,omitempty"`
+	Num             int    `json:"num"`
+	CreatedTime     int64  `json:"createdTime"`
+	UpdatedTime     int64  `json:"updatedTime,omitempty"`
+	Status          int    `json:"status"`
 }
 
 type NodeBackup struct {
@@ -516,6 +537,19 @@ type TunnelRecord struct {
 	TrafficRatio float64
 }
 
+type UserQuotaView struct {
+	UserID           int64
+	DailyLimitGB     int64
+	MonthlyLimitGB   int64
+	DailyUsedBytes   int64
+	MonthlyUsedBytes int64
+	DayKey           int64
+	MonthKey         int64
+	DisabledByQuota  int
+	DisabledAt       int64
+	PausedForwardIDs string
+}
+
 // ForwardPortRecord is a forward port mapping used by control plane.
 type ForwardPortRecord struct {
 	NodeID int64

go-backend/internal/store/repo/repository.go

@@ -161,6 +161,7 @@ func (r *Repository) Close() error {
 func autoMigrateAll(db *gorm.DB) error {
 	models := []interface{}{
 		&model.User{},
+		&model.UserQuota{},
 		&model.Forward{},
 		&model.ForwardPort{},
 		&model.Node{},
@@ -663,16 +664,33 @@ func (r *Repository) ListUsers() ([]map[string]interface{}, error) {
 	if err := r.db.Where("role_id != ?", 0).Order("id DESC").Find(&users).Error; err != nil {
 		return nil, err
 	}
+	userIDs := make([]int64, 0, len(users))
+	for _, u := range users {
+		userIDs = append(userIDs, u.ID)
+	}
+	quotaMap, err := r.ListUserQuotaViewsByUserIDs(userIDs, time.Now())
+	if err != nil {
+		return nil, err
+	}
 	items := make([]map[string]interface{}, 0, len(users))
 	for _, u := range users {
-		items = append(items, map[string]interface{}{
+		item := map[string]interface{}{
 			"id": u.ID, "user": u.User, "name": u.User,
 			"roleId": u.RoleID, "status": u.Status,
 			"flow": u.Flow, "num": u.Num, "expTime": u.ExpTime,
 			"flowResetTime": u.FlowResetTime, "createdTime": u.CreatedTime,
 			"updatedTime": nullableInt64(u.UpdatedTime),
 			"inFlow":      u.InFlow, "outFlow": u.OutFlow,
-		})
+		}
+		if quota := quotaMap[u.ID]; quota != nil {
+			item["dailyQuotaGB"] = quota.DailyLimitGB
+			item["monthlyQuotaGB"] = quota.MonthlyLimitGB
+			item["dailyUsedBytes"] = quota.DailyUsedBytes
+			item["monthlyUsedBytes"] = quota.MonthlyUsedBytes
+			item["disabledByQuota"] = quota.DisabledByQuota
+			item["quotaDisabledAt"] = quota.DisabledAt
+		}
+		items = append(items, item)
 	}
 	return items, nil
 }
@@ -1794,6 +1812,14 @@ func (r *Repository) exportUsers() ([]model.UserBackup, error) {
 	if err := r.db.Order("id ASC").Find(&users).Error; err != nil {
 		return nil, err
 	}
+	userIDs := make([]int64, 0, len(users))
+	for _, u := range users {
+		userIDs = append(userIDs, u.ID)
+	}
+	quotaMap, err := r.ListUserQuotaViewsByUserIDs(userIDs, time.Now())
+	if err != nil {
+		return nil, err
+	}
 	out := make([]model.UserBackup, 0, len(users))
 	for _, u := range users {
 		b := model.UserBackup{
@@ -1802,6 +1828,12 @@ func (r *Repository) exportUsers() ([]model.UserBackup, error) {
 			FlowResetTime: u.FlowResetTime, Num: u.Num,
 			CreatedTime: u.CreatedTime, Status: u.Status,
 		}
+		if quota := quotaMap[u.ID]; quota != nil {
+			b.DailyQuotaGB = quota.DailyLimitGB
+			b.MonthlyQuotaGB = quota.MonthlyLimitGB
+			b.DisabledByQuota = quota.DisabledByQuota
+			b.QuotaDisabledAt = quota.DisabledAt
+		}
 		if u.UpdatedTime.Valid {
 			b.UpdatedTime = u.UpdatedTime.Int64
 		}
@@ -2166,6 +2198,39 @@ func importUsers(tx *gorm.DB, users []model.UserBackup, now int64) (int, error)
 		if err != nil {
 			return count, err
 		}
+		if u.DailyQuotaGB > 0 || u.MonthlyQuotaGB > 0 || u.DisabledByQuota != 0 || u.QuotaDisabledAt > 0 {
+			current := time.UnixMilli(now)
+			dayKey := int64(current.Year()*10000 + int(current.Month())*100 + current.Day())
+			monthKey := int64(current.Year()*100 + int(current.Month()))
+			quotaItem := model.UserQuota{
+				UserID:           u.ID,
+				DailyLimitGB:     u.DailyQuotaGB,
+				MonthlyLimitGB:   u.MonthlyQuotaGB,
+				DailyUsedBytes:   0,
+				MonthlyUsedBytes: 0,
+				DayKey:           dayKey,
+				MonthKey:         monthKey,
+				DisabledByQuota:  u.DisabledByQuota,
+				DisabledAt:       u.QuotaDisabledAt,
+				PausedForwardIDs: "",
+				CreatedTime:      now,
+				UpdatedTime:      now,
+			}
+			err = tx.Clauses(clause.OnConflict{
+				Columns: []clause.Column{{Name: "user_id"}},
+				DoUpdates: clause.AssignmentColumns([]string{
+					"daily_limit_gb", "monthly_limit_gb", "daily_used_bytes", "monthly_used_bytes",
+					"day_key", "month_key", "disabled_by_quota", "disabled_at", "paused_forward_ids", "updated_time",
+				}),
+			}).Create(&quotaItem).Error
+			if err != nil {
+				return count, err
+			}
+		} else {
+			if err := tx.Where("user_id = ?", u.ID).Delete(&model.UserQuota{}).Error; err != nil {
+				return count, err
+			}
+		}
 		count++
 	}
 	return count, nil

go-backend/internal/store/repo/repository_mutations.go

@@ -145,6 +145,9 @@ func (r *Repository) DeleteUserCascade(userID int64) error {
 		if err := tx.Where("user_id = ?", userID).Delete(&model.StatisticsFlow{}).Error; err != nil {
 			return err
 		}
+		if err := tx.Where("user_id = ?", userID).Delete(&model.UserQuota{}).Error; err != nil {
+			return err
+		}
 		return tx.Where("id = ?", userID).Delete(&model.User{}).Error
 	})
 }

go-backend/internal/store/repo/repository_user_quota.go

@@ -0,0 +1,378 @@
+package repo
+
+import (
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+
+	"go-backend/internal/store/model"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+const userQuotaBytesPerGB int64 = 1024 * 1024 * 1024
+
+type UserQuotaRelease struct {
+	UserID      int64
+	ForwardIDs  []int64
+	UnblockUser bool
+}
+
+func userQuotaWindowKeys(now time.Time) (int64, int64) {
+	return int64(now.Year()*10000 + int(now.Month())*100 + now.Day()), int64(now.Year()*100 + int(now.Month()))
+}
+
+func cloneUserQuotaView(q model.UserQuota) *model.UserQuotaView {
+	return &model.UserQuotaView{
+		UserID:           q.UserID,
+		DailyLimitGB:     q.DailyLimitGB,
+		MonthlyLimitGB:   q.MonthlyLimitGB,
+		DailyUsedBytes:   q.DailyUsedBytes,
+		MonthlyUsedBytes: q.MonthlyUsedBytes,
+		DayKey:           q.DayKey,
+		MonthKey:         q.MonthKey,
+		DisabledByQuota:  q.DisabledByQuota,
+		DisabledAt:       q.DisabledAt,
+		PausedForwardIDs: q.PausedForwardIDs,
+	}
+}
+
+func normalizeUserQuotaView(view *model.UserQuotaView, now time.Time) *model.UserQuotaView {
+	if view == nil {
+		return nil
+	}
+	dayKey, monthKey := userQuotaWindowKeys(now)
+	out := *view
+	if out.DayKey != dayKey {
+		out.DayKey = dayKey
+		out.DailyUsedBytes = 0
+	}
+	if out.MonthKey != monthKey {
+		out.MonthKey = monthKey
+		out.MonthlyUsedBytes = 0
+	}
+	return &out
+}
+
+func userQuotaExceeded(view *model.UserQuotaView) bool {
+	if view == nil {
+		return false
+	}
+	if view.DailyLimitGB > 0 && view.DailyUsedBytes >= view.DailyLimitGB*userQuotaBytesPerGB {
+		return true
+	}
+	if view.MonthlyLimitGB > 0 && view.MonthlyUsedBytes >= view.MonthlyLimitGB*userQuotaBytesPerGB {
+		return true
+	}
+	return false
+}
+
+func parsePausedForwardIDs(raw string) []int64 {
+	parts := strings.Split(strings.TrimSpace(raw), ",")
+	out := make([]int64, 0, len(parts))
+	seen := make(map[int64]struct{}, len(parts))
+	for _, part := range parts {
+		id, err := strconv.ParseInt(strings.TrimSpace(part), 10, 64)
+		if err != nil || id <= 0 {
+			continue
+		}
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		seen[id] = struct{}{}
+		out = append(out, id)
+	}
+	return out
+}
+
+func joinPausedForwardIDs(ids []int64) string {
+	if len(ids) == 0 {
+		return ""
+	}
+	parts := make([]string, 0, len(ids))
+	seen := make(map[int64]struct{}, len(ids))
+	for _, id := range ids {
+		if id <= 0 {
+			continue
+		}
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		seen[id] = struct{}{}
+		parts = append(parts, strconv.FormatInt(id, 10))
+	}
+	return strings.Join(parts, ",")
+}
+
+func (r *Repository) loadOrCreateUserQuotaTx(tx *gorm.DB, userID int64, now time.Time) (*model.UserQuota, error) {
+	if tx == nil {
+		return nil, errors.New("database unavailable")
+	}
+	dayKey, monthKey := userQuotaWindowKeys(now)
+	q := &model.UserQuota{}
+	err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).Where("user_id = ?", userID).First(q).Error
+	if err == nil {
+		return q, nil
+	}
+	if !errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, err
+	}
+	nowMs := now.UnixMilli()
+	q = &model.UserQuota{
+		UserID:           userID,
+		DayKey:           dayKey,
+		MonthKey:         monthKey,
+		CreatedTime:      nowMs,
+		UpdatedTime:      nowMs,
+		PausedForwardIDs: "",
+	}
+	if err := tx.Create(q).Error; err != nil {
+		return nil, err
+	}
+	return q, nil
+}
+
+func applyUserQuotaWindowRoll(q *model.UserQuota, now time.Time) bool {
+	if q == nil {
+		return false
+	}
+	changed := false
+	dayKey, monthKey := userQuotaWindowKeys(now)
+	if q.DayKey != dayKey {
+		q.DayKey = dayKey
+		q.DailyUsedBytes = 0
+		changed = true
+	}
+	if q.MonthKey != monthKey {
+		q.MonthKey = monthKey
+		q.MonthlyUsedBytes = 0
+		changed = true
+	}
+	return changed
+}
+
+func (r *Repository) SaveUserQuotaConfigTx(tx *gorm.DB, userID, dailyLimitGB, monthlyLimitGB int64, now int64) error {
+	if tx == nil {
+		return errors.New("database unavailable")
+	}
+	if userID <= 0 {
+		return errors.New("user id is required")
+	}
+	if dailyLimitGB < 0 || monthlyLimitGB < 0 {
+		return errors.New("quota limit cannot be negative")
+	}
+	current := time.UnixMilli(now)
+	q, err := r.loadOrCreateUserQuotaTx(tx, userID, current)
+	if err != nil {
+		return err
+	}
+	updates := map[string]interface{}{
+		"daily_limit_gb":   dailyLimitGB,
+		"monthly_limit_gb": monthlyLimitGB,
+		"updated_time":     now,
+	}
+	if q.DayKey == 0 || q.MonthKey == 0 {
+		dayKey, monthKey := userQuotaWindowKeys(current)
+		updates["day_key"] = dayKey
+		updates["month_key"] = monthKey
+	}
+	return tx.Model(&model.UserQuota{}).Where("user_id = ?", userID).Updates(updates).Error
+}
+
+func (r *Repository) ListUserQuotaViewsByUserIDs(userIDs []int64, now time.Time) (map[int64]*model.UserQuotaView, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	out := make(map[int64]*model.UserQuotaView)
+	if len(userIDs) == 0 {
+		return out, nil
+	}
+	var rows []model.UserQuota
+	if err := r.db.Where("user_id IN ?", userIDs).Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	for _, row := range rows {
+		out[row.UserID] = normalizeUserQuotaView(cloneUserQuotaView(row), now)
+	}
+	return out, nil
+}
+
+func (r *Repository) GetUserQuotaView(userID int64, now time.Time) (*model.UserQuotaView, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	if userID <= 0 {
+		return nil, nil
+	}
+	var row model.UserQuota
+	err := r.db.Where("user_id = ?", userID).First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return normalizeUserQuotaView(cloneUserQuotaView(row), now), nil
+}
+
+func (r *Repository) AddUserQuotaUsage(userID int64, usedBytes int64, now time.Time) (*model.UserQuotaView, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	if userID <= 0 {
+		return nil, nil
+	}
+	result := &model.UserQuotaView{}
+	err := r.db.Transaction(func(tx *gorm.DB) error {
+		q, err := r.loadOrCreateUserQuotaTx(tx, userID, now)
+		if err != nil {
+			return err
+		}
+		applyUserQuotaWindowRoll(q, now)
+		if usedBytes > 0 {
+			q.DailyUsedBytes += usedBytes
+			q.MonthlyUsedBytes += usedBytes
+		}
+		q.UpdatedTime = now.UnixMilli()
+		if err := tx.Model(&model.UserQuota{}).Where("user_id = ?", userID).Updates(map[string]interface{}{
+			"daily_used_bytes":   q.DailyUsedBytes,
+			"monthly_used_bytes": q.MonthlyUsedBytes,
+			"day_key":            q.DayKey,
+			"month_key":          q.MonthKey,
+			"updated_time":       q.UpdatedTime,
+		}).Error; err != nil {
+			return err
+		}
+		*result = *cloneUserQuotaView(*q)
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return normalizeUserQuotaView(result, now), nil
+}
+
+func (r *Repository) MarkUserQuotaDisabled(userID int64, pausedForwardIDs []int64, now int64) error {
+	if r == nil || r.db == nil {
+		return errors.New("repository not initialized")
+	}
+	if userID <= 0 {
+		return errors.New("user id is required")
+	}
+	return r.db.Model(&model.UserQuota{}).Where("user_id = ?", userID).Updates(map[string]interface{}{
+		"disabled_by_quota":  1,
+		"disabled_at":        now,
+		"paused_forward_ids": joinPausedForwardIDs(pausedForwardIDs),
+		"updated_time":       now,
+	}).Error
+}
+
+func (r *Repository) ResetUserQuotaUsage(userID int64, scope string, now time.Time) (*UserQuotaRelease, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	if userID <= 0 {
+		return nil, errors.New("user id is required")
+	}
+	scope = strings.TrimSpace(strings.ToLower(scope))
+	if scope == "" {
+		scope = "all"
+	}
+	if scope != "daily" && scope != "monthly" && scope != "all" {
+		return nil, fmt.Errorf("unsupported quota reset scope: %s", scope)
+	}
+	var release *UserQuotaRelease
+	err := r.db.Transaction(func(tx *gorm.DB) error {
+		q, err := r.loadOrCreateUserQuotaTx(tx, userID, now)
+		if err != nil {
+			return err
+		}
+		applyUserQuotaWindowRoll(q, now)
+		switch scope {
+		case "daily":
+			q.DailyUsedBytes = 0
+		case "monthly":
+			q.MonthlyUsedBytes = 0
+		case "all":
+			q.DailyUsedBytes = 0
+			q.MonthlyUsedBytes = 0
+		}
+		q.UpdatedTime = now.UnixMilli()
+		release = &UserQuotaRelease{UserID: userID}
+		if q.DisabledByQuota == 1 && !userQuotaExceeded(cloneUserQuotaView(*q)) {
+			release.UnblockUser = true
+			release.ForwardIDs = parsePausedForwardIDs(q.PausedForwardIDs)
+			q.DisabledByQuota = 0
+			q.DisabledAt = 0
+			q.PausedForwardIDs = ""
+		}
+		return tx.Model(&model.UserQuota{}).Where("user_id = ?", userID).Updates(map[string]interface{}{
+			"daily_used_bytes":   q.DailyUsedBytes,
+			"monthly_used_bytes": q.MonthlyUsedBytes,
+			"day_key":            q.DayKey,
+			"month_key":          q.MonthKey,
+			"disabled_by_quota":  q.DisabledByQuota,
+			"disabled_at":        q.DisabledAt,
+			"paused_forward_ids": q.PausedForwardIDs,
+			"updated_time":       q.UpdatedTime,
+		}).Error
+	})
+	if err != nil {
+		return nil, err
+	}
+	return release, nil
+}
+
+func (r *Repository) RollUserQuotaWindows(now time.Time) ([]UserQuotaRelease, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var releases []UserQuotaRelease
+	err := r.db.Transaction(func(tx *gorm.DB) error {
+		var rows []model.UserQuota
+		if err := tx.Find(&rows).Error; err != nil {
+			return err
+		}
+		nowMs := now.UnixMilli()
+		for _, row := range rows {
+			q := row
+			changed := applyUserQuotaWindowRoll(&q, now)
+			release := UserQuotaRelease{UserID: q.UserID}
+			if q.DisabledByQuota == 1 && !userQuotaExceeded(cloneUserQuotaView(q)) {
+				release.UnblockUser = true
+				release.ForwardIDs = parsePausedForwardIDs(q.PausedForwardIDs)
+				q.DisabledByQuota = 0
+				q.DisabledAt = 0
+				q.PausedForwardIDs = ""
+				changed = true
+			}
+			if !changed {
+				continue
+			}
+			q.UpdatedTime = nowMs
+			if err := tx.Model(&model.UserQuota{}).Where("user_id = ?", q.UserID).Updates(map[string]interface{}{
+				"daily_used_bytes":   q.DailyUsedBytes,
+				"monthly_used_bytes": q.MonthlyUsedBytes,
+				"day_key":            q.DayKey,
+				"month_key":          q.MonthKey,
+				"disabled_by_quota":  q.DisabledByQuota,
+				"disabled_at":        q.DisabledAt,
+				"paused_forward_ids": q.PausedForwardIDs,
+				"updated_time":       q.UpdatedTime,
+			}).Error; err != nil {
+				return err
+			}
+			if release.UnblockUser {
+				releases = append(releases, release)
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return releases, nil
+}

go-backend/tests/contract/limiter_sync_failure_contract_test.go

@@ -667,6 +667,421 @@ func TestTunnelUpdateRecoversFromAddressInUseContract(t *testing.T) {
 	}
 }
 
+func TestTunnelUpdateChangesEntryNodeButLeavesOldForwardRuntimeContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, r := setupContractRouter(t, secret)
+	server := httptest.NewServer(router)
+	defer server.Close()
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	now := time.Now().UnixMilli()
+	if err := r.DB().Exec(`
+		INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(2, 'issue281_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "issue281-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "issue281-tunnel")
+
+	insertNode := func(name, secretValue, ip, portRange string, inx int) int64 {
+		if err := r.DB().Exec(`
+			INSERT INTO node(name, secret, server_ip, server_ip_v4, server_ip_v6, port, interface_name, version, http, tls, socks, created_time, updated_time, status, tcp_listen_addr, udp_listen_addr, inx)
+			VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, name, secretValue, ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", inx).Error; err != nil {
+			t.Fatalf("insert node %s: %v", name, err)
+		}
+		return mustLastInsertID(t, r, name)
+	}
+
+	oldEntryNodeID := insertNode("issue281-old-entry", "issue281-old-entry-secret", "10.51.0.1", "51000-51010", 0)
+	newEntryNodeID := insertNode("issue281-new-entry", "issue281-new-entry-secret", "10.51.0.2", "52000-52010", 1)
+	exitNodeID := insertNode("issue281-exit", "issue281-exit-secret", "10.51.0.3", "53000-53010", 2)
+
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 51001, 'round', 1, 'tls')
+	`, tunnelID, oldEntryNodeID).Error; err != nil {
+		t.Fatalf("insert old entry chain_tunnel: %v", err)
+	}
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 3, ?, 53001, 'round', 1, 'tls')
+	`, tunnelID, exitNodeID).Error; err != nil {
+		t.Fatalf("insert exit chain_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
+		VALUES(281, 2, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)
+	`, tunnelID).Error; err != nil {
+		t.Fatalf("insert user_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO forward(user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(2, 'issue281_user', 'issue281-forward', ?, '8.8.8.8:53', 'fifo', 0, 0, ?, ?, 1, 0)
+	`, tunnelID, now, now).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+	forwardID := mustLastInsertID(t, r, "issue281-forward")
+
+	if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, oldEntryNodeID, 51001).Error; err != nil {
+		t.Fatalf("insert forward_port: %v", err)
+	}
+
+	forwardBase := fmt.Sprintf("%d_%d_%d", forwardID, 2, 281)
+
+	var commandMu sync.Mutex
+	oldEntryDeleteNames := make([]string, 0)
+	newEntryUpdateNames := make([]string, 0)
+
+	recordForwardServiceNames := func(data json.RawMessage, list *[]string) {
+		var serviceList []map[string]interface{}
+		if err := json.Unmarshal(data, &serviceList); err == nil {
+			for _, service := range serviceList {
+				name, _ := service["name"].(string)
+				if strings.HasPrefix(strings.TrimSpace(name), forwardBase) {
+					*list = append(*list, name)
+				}
+			}
+			return
+		}
+
+		var payload map[string]interface{}
+		if err := json.Unmarshal(data, &payload); err != nil {
+			return
+		}
+		if rawServices, ok := payload["services"].([]interface{}); ok {
+			for _, raw := range rawServices {
+				name, _ := raw.(string)
+				if strings.HasPrefix(strings.TrimSpace(name), forwardBase) {
+					*list = append(*list, name)
+				}
+			}
+			return
+		}
+	}
+
+	stopOldEntry := startMockNodeSessionWithCommandRecorder(t, server.URL, "issue281-old-entry-secret", func(cmdType string, data json.RawMessage) (bool, string) {
+		commandMu.Lock()
+		defer commandMu.Unlock()
+		if strings.EqualFold(strings.TrimSpace(cmdType), "DeleteService") {
+			recordForwardServiceNames(data, &oldEntryDeleteNames)
+		}
+		return false, ""
+	})
+	defer stopOldEntry()
+
+	stopNewEntry := startMockNodeSessionWithCommandRecorder(t, server.URL, "issue281-new-entry-secret", func(cmdType string, data json.RawMessage) (bool, string) {
+		commandMu.Lock()
+		defer commandMu.Unlock()
+		if strings.EqualFold(strings.TrimSpace(cmdType), "UpdateService") || strings.EqualFold(strings.TrimSpace(cmdType), "AddService") {
+			recordForwardServiceNames(data, &newEntryUpdateNames)
+		}
+		return false, ""
+	})
+	defer stopNewEntry()
+
+	stopExit := startMockNodeSessionWithCommandRecorder(t, server.URL, "issue281-exit-secret", func(cmdType string, data json.RawMessage) (bool, string) {
+		return false, ""
+	})
+	defer stopExit()
+
+	waitNodeStatus(t, r, oldEntryNodeID, 1)
+	waitNodeStatus(t, r, newEntryNodeID, 1)
+	waitNodeStatus(t, r, exitNodeID, 1)
+
+	payload := map[string]interface{}{
+		"id":           tunnelID,
+		"name":         "issue281-tunnel",
+		"type":         2,
+		"flow":         99999,
+		"trafficRatio": 1.0,
+		"status":       1,
+		"inNodeId": []map[string]interface{}{
+			{"nodeId": newEntryNodeID, "protocol": "tls", "strategy": "round"},
+		},
+		"chainNodes": []interface{}{},
+		"outNodeId": []map[string]interface{}{
+			{"nodeId": exitNodeID, "protocol": "tls", "strategy": "round", "port": 53001},
+		},
+	}
+	body, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("marshal payload: %v", err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(body))
+	req.Header.Set("Authorization", adminToken)
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+	assertCode(t, res, 0)
+
+	nodeAfter, portAfter := mustQueryInt64Int(t, r, `SELECT node_id, port FROM forward_port WHERE forward_id = ? LIMIT 1`, forwardID)
+	if nodeAfter != newEntryNodeID || portAfter != 51001 {
+		t.Fatalf("expected forward_port rebound to node=%d port=51001, got node=%d port=%d", newEntryNodeID, nodeAfter, portAfter)
+	}
+
+	commandMu.Lock()
+	defer commandMu.Unlock()
+	if len(newEntryUpdateNames) == 0 {
+		t.Fatalf("expected new entry node to receive forward runtime sync for %s", forwardBase)
+	}
+	if len(oldEntryDeleteNames) == 0 {
+		t.Fatalf("expected old entry node to receive forward DeleteService cleanup for %s, got none", forwardBase)
+	}
+}
+
+func TestTunnelUpdateEntryTransitionsCleanupForwardRuntimeContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, r := setupContractRouter(t, secret)
+	server := httptest.NewServer(router)
+	defer server.Close()
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	now := time.Now().UnixMilli()
+	if err := r.DB().Exec(`
+		INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(2, 'issue281_transition_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "issue281-transition-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "issue281-transition-tunnel")
+
+	insertNode := func(name, secretValue, ip, portRange string, inx int) int64 {
+		if err := r.DB().Exec(`
+			INSERT INTO node(name, secret, server_ip, server_ip_v4, server_ip_v6, port, interface_name, version, http, tls, socks, created_time, updated_time, status, tcp_listen_addr, udp_listen_addr, inx)
+			VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, name, secretValue, ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", inx).Error; err != nil {
+			t.Fatalf("insert node %s: %v", name, err)
+		}
+		return mustLastInsertID(t, r, name)
+	}
+
+	entryA := insertNode("issue281-transition-entry-a", "issue281-transition-entry-a-secret", "10.52.0.1", "54000-54010", 0)
+	entryB := insertNode("issue281-transition-entry-b", "issue281-transition-entry-b-secret", "10.52.0.2", "55000-55010", 1)
+	entryC := insertNode("issue281-transition-entry-c", "issue281-transition-entry-c-secret", "10.52.0.3", "56000-56010", 2)
+	exitNodeID := insertNode("issue281-transition-exit", "issue281-transition-exit-secret", "10.52.0.4", "57000-57010", 3)
+
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 54001, 'round', 1, 'tls')
+	`, tunnelID, entryA).Error; err != nil {
+		t.Fatalf("insert initial entry chain_tunnel: %v", err)
+	}
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 3, ?, 57001, 'round', 1, 'tls')
+	`, tunnelID, exitNodeID).Error; err != nil {
+		t.Fatalf("insert exit chain_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
+		VALUES(282, 2, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)
+	`, tunnelID).Error; err != nil {
+		t.Fatalf("insert user_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO forward(user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(2, 'issue281_transition_user', 'issue281-transition-forward', ?, '1.1.1.1:443', 'fifo', 0, 0, ?, ?, 1, 0)
+	`, tunnelID, now, now).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+	forwardID := mustLastInsertID(t, r, "issue281-transition-forward")
+
+	if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, entryA, 54001).Error; err != nil {
+		t.Fatalf("insert forward_port: %v", err)
+	}
+
+	forwardBase := fmt.Sprintf("%d_%d_%d", forwardID, 2, 282)
+	recorder := newForwardRuntimeCommandRecorder(forwardBase)
+
+	stopEntryA := startMockNodeSessionWithCommandRecorder(t, server.URL, "issue281-transition-entry-a-secret", recorder.handler("entry-a"))
+	defer stopEntryA()
+	stopEntryB := startMockNodeSessionWithCommandRecorder(t, server.URL, "issue281-transition-entry-b-secret", recorder.handler("entry-b"))
+	defer stopEntryB()
+	stopEntryC := startMockNodeSessionWithCommandRecorder(t, server.URL, "issue281-transition-entry-c-secret", recorder.handler("entry-c"))
+	defer stopEntryC()
+	stopExit := startMockNodeSessionWithCommandRecorder(t, server.URL, "issue281-transition-exit-secret", recorder.handler("exit"))
+	defer stopExit()
+
+	waitNodeStatus(t, r, entryA, 1)
+	waitNodeStatus(t, r, entryB, 1)
+	waitNodeStatus(t, r, entryC, 1)
+	waitNodeStatus(t, r, exitNodeID, 1)
+
+	updateTunnelEntries := func(entries []map[string]interface{}) {
+		payload := map[string]interface{}{
+			"id":           tunnelID,
+			"name":         "issue281-transition-tunnel",
+			"type":         2,
+			"flow":         99999,
+			"trafficRatio": 1.0,
+			"status":       1,
+			"inNodeId":     entries,
+			"chainNodes":   []interface{}{},
+			"outNodeId": []map[string]interface{}{
+				{"nodeId": exitNodeID, "protocol": "tls", "strategy": "round", "port": 57001},
+			},
+		}
+		body, err := json.Marshal(payload)
+		if err != nil {
+			t.Fatalf("marshal payload: %v", err)
+		}
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(body))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		assertCode(t, res, 0)
+	}
+
+	updateTunnelEntries([]map[string]interface{}{
+		{"nodeId": entryA, "protocol": "tls", "strategy": "round"},
+		{"nodeId": entryB, "protocol": "tls", "strategy": "round"},
+	})
+
+	afterMulti := mustQueryNodePorts(t, r, `SELECT node_id, port FROM forward_port WHERE forward_id = ? ORDER BY id ASC`, forwardID)
+	if len(afterMulti) != 2 || afterMulti[entryA] != 54001 || afterMulti[entryB] != 54001 {
+		t.Fatalf("expected forward_port on entryA+entryB with port 54001, got %v", afterMulti)
+	}
+	if recorder.syncCount("entry-b") == 0 {
+		t.Fatalf("expected entry-b to receive forward runtime sync for %s", forwardBase)
+	}
+	if recorder.deleteCount("entry-a") != 0 {
+		t.Fatalf("expected no cleanup on retained entry-a during single->multi transition, got %v", recorder.deleteNames("entry-a"))
+	}
+
+	updateTunnelEntries([]map[string]interface{}{
+		{"nodeId": entryC, "protocol": "tls", "strategy": "round"},
+	})
+
+	afterSingle := mustQueryNodePorts(t, r, `SELECT node_id, port FROM forward_port WHERE forward_id = ? ORDER BY id ASC`, forwardID)
+	if len(afterSingle) != 1 || afterSingle[entryC] != 54001 {
+		t.Fatalf("expected forward_port on entryC with port 54001, got %v", afterSingle)
+	}
+	if recorder.deleteCount("entry-a") == 0 {
+		t.Fatalf("expected cleanup on removed entry-a during multi->single transition, got %v", recorder.deleteNames("entry-a"))
+	}
+	if recorder.deleteCount("entry-b") == 0 {
+		t.Fatalf("expected cleanup on removed entry-b during multi->single transition, got %v", recorder.deleteNames("entry-b"))
+	}
+	if recorder.syncCount("entry-c") == 0 {
+		t.Fatalf("expected entry-c to receive forward runtime sync for %s", forwardBase)
+	}
+}
+
+type forwardRuntimeCommandRecorder struct {
+	prefix string
+
+	mu        sync.Mutex
+	deletes   map[string][]string
+	syncNames map[string][]string
+}
+
+func newForwardRuntimeCommandRecorder(prefix string) *forwardRuntimeCommandRecorder {
+	return &forwardRuntimeCommandRecorder{
+		prefix:    strings.TrimSpace(prefix),
+		deletes:   make(map[string][]string),
+		syncNames: make(map[string][]string),
+	}
+}
+
+func (r *forwardRuntimeCommandRecorder) handler(node string) func(string, json.RawMessage) (bool, string) {
+	return func(cmdType string, data json.RawMessage) (bool, string) {
+		names := collectForwardServiceNames(data, r.prefix)
+		if len(names) == 0 {
+			return false, ""
+		}
+
+		r.mu.Lock()
+		defer r.mu.Unlock()
+
+		if strings.EqualFold(strings.TrimSpace(cmdType), "DeleteService") {
+			r.deletes[node] = append(r.deletes[node], names...)
+		}
+		if strings.EqualFold(strings.TrimSpace(cmdType), "UpdateService") || strings.EqualFold(strings.TrimSpace(cmdType), "AddService") {
+			r.syncNames[node] = append(r.syncNames[node], names...)
+		}
+		return false, ""
+	}
+}
+
+func (r *forwardRuntimeCommandRecorder) deleteCount(node string) int {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return len(r.deletes[node])
+}
+
+func (r *forwardRuntimeCommandRecorder) syncCount(node string) int {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return len(r.syncNames[node])
+}
+
+func (r *forwardRuntimeCommandRecorder) deleteNames(node string) []string {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return append([]string(nil), r.deletes[node]...)
+}
+
+func collectForwardServiceNames(data json.RawMessage, prefix string) []string {
+	prefix = strings.TrimSpace(prefix)
+	if prefix == "" {
+		return nil
+	}
+
+	names := make([]string, 0)
+	var serviceList []map[string]interface{}
+	if err := json.Unmarshal(data, &serviceList); err == nil {
+		for _, service := range serviceList {
+			name, _ := service["name"].(string)
+			if strings.HasPrefix(strings.TrimSpace(name), prefix) {
+				names = append(names, name)
+			}
+		}
+		return names
+	}
+
+	var payload map[string]interface{}
+	if err := json.Unmarshal(data, &payload); err != nil {
+		return nil
+	}
+	if rawServices, ok := payload["services"].([]interface{}); ok {
+		for _, raw := range rawServices {
+			name, _ := raw.(string)
+			if strings.HasPrefix(strings.TrimSpace(name), prefix) {
+				names = append(names, name)
+			}
+		}
+	}
+	return names
+}
+
 func startMockNodeSessionWithCommandFailures(t *testing.T, baseURL string, nodeSecret string, failCommands map[string]string) func() {
 	t.Helper()
 

go-backend/tests/contract/user_quota_contract_test.go

@@ -0,0 +1,181 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"go-backend/internal/auth"
+	"go-backend/internal/http/response"
+)
+
+func TestForwardCreateBlockedWhenUserQuotaExceeded(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, repo := setupContractRouter(t, secret)
+	now := time.Now()
+	nowMs := now.UnixMilli()
+	dayKey := int64(now.Year()*10000 + int(now.Month())*100 + now.Day())
+	monthKey := int64(now.Year()*100 + int(now.Month()))
+
+	if err := repo.DB().Exec(`
+		INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(2, 'quota_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, nowMs, nowMs).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+	if err := repo.DB().Exec(`
+		INSERT INTO tunnel(id, name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(1, 'quota_tunnel', 1.0, 1, 'tls', 1, ?, ?, 1, NULL, 0)
+	`, nowMs, nowMs).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	if err := repo.DB().Exec(`
+		INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
+		VALUES(10, 2, 1, NULL, 99999, 99999, 0, 0, 1, 2727251700000, 1)
+	`).Error; err != nil {
+		t.Fatalf("insert user_tunnel: %v", err)
+	}
+	if err := repo.DB().Exec(`
+		INSERT INTO user_quota(user_id, daily_limit_gb, monthly_limit_gb, daily_used_bytes, monthly_used_bytes, day_key, month_key, disabled_by_quota, disabled_at, paused_forward_ids, created_time, updated_time)
+		VALUES(2, 10, 0, ?, ?, ?, ?, 1, ?, '', ?, ?)
+	`, 11*contractBytesPerGB, 11*contractBytesPerGB, dayKey, monthKey, nowMs, nowMs, nowMs).Error; err != nil {
+		t.Fatalf("insert user_quota: %v", err)
+	}
+
+	token, err := auth.GenerateToken(2, "quota_user", 1, secret)
+	if err != nil {
+		t.Fatalf("generate token: %v", err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/forward/create", bytes.NewBufferString(`{"tunnelId":1,"name":"quota-forward","remoteAddr":"1.1.1.1:53"}`))
+	req.Header.Set("Authorization", token)
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+
+	router.ServeHTTP(res, req)
+
+	var out response.R
+	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Code == 0 {
+		t.Fatalf("expected non-zero code when user quota exceeded")
+	}
+	if !strings.Contains(out.Msg, "配额") {
+		t.Fatalf("expected quota error, got %q", out.Msg)
+	}
+}
+
+func TestForwardResumeBlockedWhenUserQuotaExceeded(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, repo := setupContractRouter(t, secret)
+	now := time.Now()
+	nowMs := now.UnixMilli()
+	dayKey := int64(now.Year()*10000 + int(now.Month())*100 + now.Day())
+	monthKey := int64(now.Year()*100 + int(now.Month()))
+
+	if err := repo.DB().Exec(`
+		INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(2, 'quota_resume_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, nowMs, nowMs).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+	if err := repo.DB().Exec(`
+		INSERT INTO tunnel(id, name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(1, 'quota_resume_tunnel', 1.0, 1, 'tls', 1, ?, ?, 1, NULL, 0)
+	`, nowMs, nowMs).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	if err := repo.DB().Exec(`
+		INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
+		VALUES(10, 2, 1, NULL, 99999, 99999, 0, 0, 1, 2727251700000, 1)
+	`).Error; err != nil {
+		t.Fatalf("insert user_tunnel: %v", err)
+	}
+	if err := repo.DB().Exec(`
+		INSERT INTO forward(id, user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(1, 2, 'quota_resume_user', 'quota_resume_forward', 1, '1.1.1.1:53', 'fifo', 0, 0, ?, ?, 0, 0)
+	`, nowMs, nowMs).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+	if err := repo.DB().Exec(`
+		INSERT INTO user_quota(user_id, daily_limit_gb, monthly_limit_gb, daily_used_bytes, monthly_used_bytes, day_key, month_key, disabled_by_quota, disabled_at, paused_forward_ids, created_time, updated_time)
+		VALUES(2, 10, 0, ?, ?, ?, ?, 1, ?, '1', ?, ?)
+	`, 11*contractBytesPerGB, 11*contractBytesPerGB, dayKey, monthKey, nowMs, nowMs, nowMs).Error; err != nil {
+		t.Fatalf("insert user_quota: %v", err)
+	}
+
+	token, err := auth.GenerateToken(2, "quota_resume_user", 1, secret)
+	if err != nil {
+		t.Fatalf("generate token: %v", err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/forward/resume", bytes.NewBufferString(`{"id":1}`))
+	req.Header.Set("Authorization", token)
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+
+	router.ServeHTTP(res, req)
+
+	var out response.R
+	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Code == 0 {
+		t.Fatalf("expected non-zero code when user quota exceeded")
+	}
+	if !strings.Contains(out.Msg, "配额") {
+		t.Fatalf("expected quota error, got %q", out.Msg)
+	}
+	status := mustQueryInt(t, repo, `SELECT status FROM forward WHERE id = 1`)
+	if status != 0 {
+		t.Fatalf("expected forward to remain paused, got %d", status)
+	}
+}
+
+func TestUserQuotaResetClearsDisableFlag(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, repo := setupContractRouter(t, secret)
+	now := time.Now()
+	nowMs := now.UnixMilli()
+	dayKey := int64(now.Year()*10000 + int(now.Month())*100 + now.Day())
+	monthKey := int64(now.Year()*100 + int(now.Month()))
+
+	if err := repo.DB().Exec(`
+		INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(2, 'quota_reset_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, nowMs, nowMs).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+	if err := repo.DB().Exec(`
+		INSERT INTO user_quota(user_id, daily_limit_gb, monthly_limit_gb, daily_used_bytes, monthly_used_bytes, day_key, month_key, disabled_by_quota, disabled_at, paused_forward_ids, created_time, updated_time)
+		VALUES(2, 10, 0, ?, ?, ?, ?, 1, ?, '', ?, ?)
+	`, 11*contractBytesPerGB, 11*contractBytesPerGB, dayKey, monthKey, nowMs, nowMs, nowMs).Error; err != nil {
+		t.Fatalf("insert user_quota: %v", err)
+	}
+
+	token, err := auth.GenerateToken(1, "admin", 0, secret)
+	if err != nil {
+		t.Fatalf("generate token: %v", err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/user/quota/reset", bytes.NewBufferString(`{"userId":2,"scope":"all"}`))
+	req.Header.Set("Authorization", token)
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+
+	router.ServeHTTP(res, req)
+
+	var out response.R
+	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Code != 0 {
+		t.Fatalf("expected reset success, got code=%d msg=%q", out.Code, out.Msg)
+	}
+	quotaDisabled := mustQueryInt(t, repo, `SELECT disabled_by_quota FROM user_quota WHERE user_id = 2`)
+	if quotaDisabled != 0 {
+		t.Fatalf("expected quota disable flag cleared, got %d", quotaDisabled)
+	}
+}

plans/028-tunnel-entry-change-sync-forward-ports.md

@@ -0,0 +1,19 @@
+# 028 - Sync Forward Ports On Tunnel Entry Change
+
+## Goal
+When a tunnel's entry nodes change, automatically keep all forwards under that tunnel aligned by rebuilding `forward_port` rows to match the latest entry node set.
+
+## Scope
+- Backend only: update tunnel mutation flow to sync forward entry mappings.
+- Preserve existing forward port and bind IP behavior:
+  - Keep the existing forward port (choose the current min port in `forward_port`).
+  - Preserve `in_ip` only when the tunnel has a single entry node; clear `in_ip` for multi-entry tunnels.
+
+## Checklist
+- [x] Capture old entry node IDs before tunnel update commits.
+- [x] After commit, compare old/new entry node sets.
+- [x] If changed, rebuild `forward_port` for all forwards in the tunnel.
+- [x] Run `go test ./...` in `go-backend`.
+
+## Notes
+- Runtime redeploy/downlink is handled elsewhere; this change focuses on DB-level consistency of forward entry mappings.

plans/029-issue-281-contract-repro.md

@@ -0,0 +1,14 @@
+# 029 - Issue 281 Contract Repro
+
+## Goal
+Add a contract test that reproduces issue #281: after changing a tunnel's entry node, forward runtime cleanup does not remove the stale service from the old entry node.
+
+## Checklist
+- [x] Review existing contract test helpers for mock node command recording.
+- [x] Add a contract test that updates a tunnel entry node while a forward is bound to the tunnel.
+- [x] Assert the new entry node receives forward sync commands and the old entry node does not receive forward cleanup, reproducing the bug.
+- [x] Run the focused contract test and capture the failure.
+
+## Test Record
+- Command: `cd go-backend && go test ./tests/contract/... -run TestTunnelUpdateChangesEntryNodeButLeavesOldForwardRuntimeContract`
+- Result: failed as expected with `expected old entry node to receive forward DeleteService cleanup for 1_2_281, got none`.

plans/030-fix-issue-281-stale-forward-runtime-cleanup.md

@@ -0,0 +1,14 @@
+# 030 - Fix Issue 281 Stale Forward Runtime Cleanup
+
+## Goal
+When a tunnel's entry nodes change, remove forward runtime services from entry nodes that are no longer part of the tunnel before syncing the forward to its new entry nodes.
+
+## Checklist
+- [x] Review the tunnel update flow and identify where old/new entry node sets are available.
+- [x] Add backend cleanup for forward runtimes on removed entry nodes.
+- [x] Keep existing forward port rebuild and forward resync behavior intact.
+- [x] Run focused contract regression tests for the issue 281 repro.
+
+## Test Record
+- Command: `cd go-backend && go test ./tests/contract/... -run 'TestTunnelUpdateChangesEntryNodeButLeavesOldForwardRuntimeContract|TestTunnelUpdateRecoversFromAddressInUseContract'`
+- Result: passed.

plans/031-entry-transition-regression-coverage.md

@@ -0,0 +1,14 @@
+# 031 - Entry Transition Regression Coverage
+
+## Goal
+Expand issue #281 regression coverage to verify forward runtime cleanup and `forward_port` rebuilding across both single-entry to multi-entry and multi-entry to single-entry tunnel updates.
+
+## Checklist
+- [x] Review the current issue 281 contract repro and reuse its mock-node recording helpers.
+- [x] Add a broader contract test that exercises both entry transition directions.
+- [x] Assert removed entry nodes receive forward cleanup and retained/new entry nodes receive forward sync.
+- [x] Run focused contract tests and record the result.
+
+## Test Record
+- Command: `cd go-backend && go test ./tests/contract/... -run 'TestTunnelUpdateChangesEntryNodeButLeavesOldForwardRuntimeContract|TestTunnelUpdateEntryTransitionsCleanupForwardRuntimeContract|TestTunnelUpdateRecoversFromAddressInUseContract'`
+- Result: passed.

plans/032-issue-291-tunnel-traffic-quota.md

@@ -0,0 +1,15 @@
+# Issue 291 Tunnel Traffic Quota Plan
+
+- [x] Confirm quota semantics with issue owner: use existing billed traffic accounting (`traffic_ratio * tunnel.flow`), overage disables the tunnel and pauses active forwards, reset re-enables the tunnel and auto-resumes affected forwards.
+- [x] Extend backend schema in `go-backend/internal/store/model/model.go` with a dedicated tunnel quota persistence model that stores per-tunnel daily/monthly limits, current billed usage, rollover keys, and quota-disable metadata in a SQLite/PostgreSQL-safe shape.
+- [x] Add repository support in `go-backend/internal/store/repo/` for reading quota settings, atomically rolling day/month windows forward, incrementing billed tunnel usage from flow uploads, checking overage state, marking quota-triggered disable state, clearing usage on manual reset, and listing quota data alongside tunnels.
+- [x] Wire billed tunnel usage accumulation into `go-backend/internal/http/handler/flow_policy.go` so each node-reported flow item updates both existing user/user_tunnel counters and the tunnel quota counters using the current billed flow scaling path.
+- [x] Implement quota enforcement in backend handlers: when a tunnel crosses quota, set `tunnel.status = 0`, mark it as quota-disabled, pause all active forwards under that tunnel, and persist enough state to distinguish quota shutdown from manual disable.
+- [x] Block forward lifecycle operations against quota-disabled or already-over-quota tunnels in `go-backend/internal/http/handler/mutations.go` and related flow-policy checks so create/resume paths fail fast with explicit quota messages.
+- [x] Extend the maintenance/reset job in `go-backend/internal/http/handler/jobs.go` to perform daily and monthly quota rollover resets, clear quota-disable flags when limits reset, and auto-resume forwards that were paused by quota enforcement.
+- [x] Add manual quota reset API support under `go-backend/internal/http/handler/handler.go` and `go-backend/internal/http/handler/mutations.go` for daily/monthly/all reset scopes, with backend logic to clear counters, re-enable the tunnel, and auto-resume forwards.
+- [x] Extend tunnel API payloads in `go-backend/internal/store/repo/repository.go` and handler responses so `tunnel/list` and `tunnel/get` expose quota configuration, usage, reset window state, and quota-disable reason without conflicting with existing `flow` semantics.
+- [x] Update backup/import-export structs and repository export/import helpers in `go-backend/internal/store/model/model.go` and `go-backend/internal/store/repo/repository.go` so tunnel quota configuration is preserved across backup/restore; only persist configuration and disable metadata, not stale rolling usage, unless implementation proves current-period restoration is necessary.
+- [x] Update frontend tunnel types and API helpers in `vite-frontend/src/api/types.ts`, `vite-frontend/src/types/index.ts`, and `vite-frontend/src/api/index.ts` to accept and submit tunnel quota fields with safe defaults for older payloads.
+- [x] Add quota management UI to `vite-frontend/src/pages/tunnel.tsx` for daily/monthly quota inputs, billed usage display, over-quota status, reset actions, and clear tunnel-disabled messaging while preserving existing layout and form conventions.
+- [x] Verify behavior with backend contract coverage in `go-backend/tests/contract/` for over-quota disable, create/resume blocking, scheduled reset rollover, manual reset, and auto-resume after reset; run targeted backend tests plus a frontend build validation after implementation. (`go test ./internal/http/handler/... ./tests/contract/...` passed; frontend `npm run build` is currently blocked by missing local dependencies/types in this environment.)

plans/033-user-traffic-quota.md

@@ -0,0 +1,10 @@
+# User Traffic Quota (Fix PR #308 Semantics)
+
+- [x] Confirm new quota semantics: daily/monthly quota applies per user (aggregated across all tunnels), not per tunnel; overage pauses only that user's active forwards and blocks create/resume.
+- [x] Backend schema: replace `tunnel_quota` usage with new `user_quota` persistence model + view types.
+- [x] Repository: implement user quota read/write/increment/reset + daily/monthly window rollover.
+- [x] Handler: wire quota accumulation into flow uploads, enforce overage (pause forwards + mark quota-disabled), and add admin reset API.
+- [x] Jobs: run daily quota window rollover + release logic in existing 00:05 maintenance job.
+- [x] Backup/import: persist quota config + quota-disable metadata on user backup payloads (not rolling usage).
+- [x] Tests: update contract + handler job tests to validate quota blocking + reset window rollover.
+- [x] Frontend: move quota inputs/usage/reset UI from tunnel management to user management; update API/types accordingly.

vite-frontend/src/api/index.ts

@@ -18,6 +18,7 @@ import type {
   UserMutationPayload,
   NodeMutationPayload,
   TunnelMutationPayload,
+  UserQuotaResetPayload,
   UserTunnelAssignPayload,
   UserTunnelListQuery,
   UserTunnelRemovePayload,
@@ -193,6 +194,8 @@ export const updatePassword = (data: UpdatePasswordPayload) =>
 // 重置流量接口
 export const resetUserFlow = (data: { id: number; type: number }) =>
   Network.post("/user/reset", data);
+export const resetUserQuota = (data: UserQuotaResetPayload) =>
+  Network.post("/user/quota/reset", data);
 
 export const getUserGroups = (id: number) =>
   Network.post<number[]>("/user/groups", { id });

vite-frontend/src/api/types.ts

@@ -21,6 +21,12 @@ export interface UserApiItem {
   flowResetTime?: number;
   inFlow?: number;
   outFlow?: number;
+  dailyQuotaGB?: number;
+  monthlyQuotaGB?: number;
+  dailyUsedBytes?: number;
+  monthlyUsedBytes?: number;
+  disabledByQuota?: number;
+  quotaDisabledAt?: number;
   [key: string]: unknown;
 }
 
@@ -36,6 +42,13 @@ export interface TunnelApiItem {
   name: string;
   type: number;
   status: number;
+  flow?: number;
+  trafficRatio?: number;
+  inIp?: string;
+  ipPreference?: string;
+  inNodeId?: TunnelChainNodePayload[];
+  outNodeId?: TunnelChainNodePayload[];
+  chainNodes?: TunnelChainNodePayload[][];
   entryNodeId: number;
   exitNodeId: number;
   inx?: number;
@@ -210,6 +223,8 @@ export interface UserMutationPayload {
   num?: number;
   expTime?: number | string;
   flowResetTime?: number;
+  dailyQuotaGB?: number;
+  monthlyQuotaGB?: number;
   tunnelFlow?: number;
 }
 
@@ -257,6 +272,11 @@ export interface TunnelMutationPayload {
   chainNodes?: TunnelChainNodePayload[][];
 }
 
+export interface UserQuotaResetPayload {
+  userId: number;
+  scope?: "daily" | "monthly" | "all";
+}
+
 export interface UserTunnelAssignPayload {
   userId?: number;
   id?: number;

vite-frontend/src/pages/node.tsx

@@ -1779,7 +1779,7 @@ export default function NodePage() {
                                   )}
                                 </button>
                                 <div
-                                  className={`pointer-events-none invisible absolute z-30 w-72 max-w-[min(18rem,calc(100vw-4rem))] rounded-xl border border-divider/80 bg-background/98 p-3 opacity-0 shadow-xl backdrop-blur transition-all duration-150 group-hover/info:visible group-hover/info:pointer-events-auto group-hover/info:opacity-100 group-focus-within/info:visible group-focus-within/info:pointer-events-auto group-focus-within/info:opacity-100 ${
+                                  className={`pointer-events-none invisible absolute z-[60] w-72 max-w-[min(18rem,calc(100vw-4rem))] rounded-xl border border-divider/80 bg-background/98 p-3 opacity-0 shadow-xl backdrop-blur transition-all duration-150 group-hover/info:visible group-hover/info:pointer-events-auto group-hover/info:opacity-100 group-focus-within/info:visible group-focus-within/info:pointer-events-auto group-focus-within/info:opacity-100 ${
                                     infoPlacement === "bottom"
                                       ? "right-0 top-[calc(100%+0.75rem)] translate-y-1 group-hover/info:translate-y-0 group-focus-within/info:translate-y-0"
                                       : "right-[calc(100%+0.75rem)] top-1/2 -translate-y-1/2 translate-x-1 group-hover/info:translate-x-0 group-focus-within/info:translate-x-0"

vite-frontend/src/pages/tunnel.tsx

@@ -358,7 +358,7 @@ export default function TunnelPage() {
     });
     setErrors({});
     setModalOpen(true);
-  };
+  }; 
 
   // 删除隧道
   const handleDelete = (tunnel: Tunnel) => {
@@ -1357,6 +1357,7 @@ export default function TunnelPage() {
                                 </div>
                               )}
                             </div>
+
                           </div>
 
                           <div className="flex gap-1.5 mt-3">

vite-frontend/src/pages/user.tsx

@@ -55,6 +55,7 @@ import {
   updateUserTunnel,
   getSpeedLimitList,
   resetUserFlow,
+  resetUserQuota,
   getUserGroupList,
   getUserGroups,
 } from "@/api";
@@ -83,6 +84,16 @@ const formatFlow = (value: number, unit: string = "bytes"): string => {
   }
 };
 
+const formatQuotaLimit = (value?: number): string => {
+  const limit = Number(value ?? 0);
+
+  if (!Number.isFinite(limit) || limit <= 0) {
+    return "不限";
+  }
+
+  return `${limit} GB`;
+};
+
 const formatDate = (timestamp: number): string => {
   return new Date(timestamp).toLocaleString();
 };
@@ -138,6 +149,12 @@ const normalizeUserItem = (item: Partial<User>): User => {
     createdTime: item.createdTime,
     inFlow: Number(item.inFlow ?? 0),
     outFlow: Number(item.outFlow ?? 0),
+    dailyQuotaGB: Number(item.dailyQuotaGB ?? 0),
+    monthlyQuotaGB: Number(item.monthlyQuotaGB ?? 0),
+    dailyUsedBytes: Number(item.dailyUsedBytes ?? 0),
+    monthlyUsedBytes: Number(item.monthlyUsedBytes ?? 0),
+    disabledByQuota: Number(item.disabledByQuota ?? 0),
+    quotaDisabledAt: Number(item.quotaDisabledAt ?? 0),
   };
 };
 
@@ -188,11 +205,22 @@ export default function UserPage() {
     pwd: "",
     status: 1,
     flow: 100,
+    dailyQuotaGB: 0,
+    monthlyQuotaGB: 0,
     num: 10,
     expTime: null,
     flowResetTime: 0,
   });
   const [userFormLoading, setUserFormLoading] = useState(false);
+  const [quotaResetLoading, setQuotaResetLoading] = useState(false);
+
+  const editingUser = useMemo(
+    () =>
+      userForm.id
+        ? users.find((item) => item.id === userForm.id) || null
+        : null,
+    [userForm.id, users],
+  );
 
   // 隧道权限管理相关状态
   const {
@@ -442,6 +470,8 @@ export default function UserPage() {
       pwd: "",
       status: 1,
       flow: 100,
+      dailyQuotaGB: 0,
+      monthlyQuotaGB: 0,
       num: 10,
       expTime: null,
       flowResetTime: 0,
@@ -469,6 +499,8 @@ export default function UserPage() {
       pwd: "",
       status: user.status,
       flow: user.flow,
+      dailyQuotaGB: user.dailyQuotaGB ?? 0,
+      monthlyQuotaGB: user.monthlyQuotaGB ?? 0,
       num: user.num,
       expTime: user.expTime ? new Date(user.expTime) : null,
       flowResetTime: user.flowResetTime ?? 0,
@@ -748,6 +780,29 @@ export default function UserPage() {
     }
   };
 
+  const handleQuotaReset = async (scope: "daily" | "monthly" | "all") => {
+    const userId = userForm.id;
+    if (!userId) {
+      return;
+    }
+
+    setQuotaResetLoading(true);
+    try {
+      const response = await resetUserQuota({ userId, scope });
+
+      if (response.code === 0) {
+        toast.success("用户配额已重置");
+        await loadUsers(searchKeyword);
+      } else {
+        toast.error(response.msg || "重置用户配额失败");
+      }
+    } catch {
+      toast.error("重置用户配额失败");
+    } finally {
+      setQuotaResetLoading(false);
+    }
+  };
+
   // 隧道流量重置相关函数
   const handleResetTunnelFlow = (userTunnel: UserTunnel) => {
     setTunnelToReset(userTunnel);
@@ -946,6 +1001,16 @@ export default function UserPage() {
                         >
                           {userStatus.text}
                         </Chip>
+                        {user.disabledByQuota ? (
+                          <Chip
+                            className="text-xs"
+                            color="danger"
+                            size="sm"
+                            variant="flat"
+                          >
+                            配额超额
+                          </Chip>
+                        ) : null}
                       </div>
                     </div>
                   </CardHeader>
@@ -983,6 +1048,28 @@ export default function UserPage() {
 
                       {/* 其他信息 */}
                       <div className="space-y-1.5 pt-2 border-t border-divider">
+                        {(user.dailyQuotaGB ?? 0) > 0 ||
+                        (user.monthlyQuotaGB ?? 0) > 0 ||
+                        (user.disabledByQuota ?? 0) > 0 ? (
+                          <>
+                            <div className="flex justify-between text-sm">
+                              <span className="text-default-600">每日配额</span>
+                              <span className="font-medium text-xs">
+                                {formatFlow(Number(user.dailyUsedBytes ?? 0))} /
+                                {" "}
+                                {formatQuotaLimit(user.dailyQuotaGB)}
+                              </span>
+                            </div>
+                            <div className="flex justify-between text-sm">
+                              <span className="text-default-600">每月配额</span>
+                              <span className="font-medium text-xs">
+                                {formatFlow(Number(user.monthlyUsedBytes ?? 0))} /
+                                {" "}
+                                {formatQuotaLimit(user.monthlyQuotaGB)}
+                              </span>
+                            </div>
+                          </>
+                        ) : null}
                         <div className="flex justify-between text-sm">
                           <span className="text-default-600">规则数量</span>
                           <span className="font-medium text-xs">
@@ -1138,6 +1225,38 @@ export default function UserPage() {
                   setUserForm((prev) => ({ ...prev, flow: value }));
                 }}
               />
+              <Input
+                label="每日配额(GB)"
+                max="99999"
+                min="0"
+                placeholder="0 表示不限"
+                type="number"
+                value={userForm.dailyQuotaGB.toString()}
+                onChange={(e) => {
+                  const value = Math.min(
+                    Math.max(Number(e.target.value) || 0, 0),
+                    99999,
+                  );
+
+                  setUserForm((prev) => ({ ...prev, dailyQuotaGB: value }));
+                }}
+              />
+              <Input
+                label="每月配额(GB)"
+                max="99999"
+                min="0"
+                placeholder="0 表示不限"
+                type="number"
+                value={userForm.monthlyQuotaGB.toString()}
+                onChange={(e) => {
+                  const value = Math.min(
+                    Math.max(Number(e.target.value) || 0, 0),
+                    99999,
+                  );
+
+                  setUserForm((prev) => ({ ...prev, monthlyQuotaGB: value }));
+                }}
+              />
               <Input
                 isRequired
                 label="规则数量"
@@ -1210,6 +1329,81 @@ export default function UserPage() {
               />
             </div>
 
+            {isEdit &&
+              editingUser &&
+              ((editingUser.dailyQuotaGB ?? 0) > 0 ||
+                (editingUser.monthlyQuotaGB ?? 0) > 0 ||
+                (editingUser.disabledByQuota ?? 0) > 0) && (
+                <div className="space-y-3 rounded-xl border border-default-200 bg-default-50/60 p-4">
+                  <div className="flex items-center justify-between gap-3">
+                    <div>
+                      <h3 className="text-sm font-semibold text-foreground">
+                        当前配额状态
+                      </h3>
+                      <p className="text-xs text-default-500">
+                        配额超额后会自动暂停该用户的转发，重置后可恢复
+                      </p>
+                    </div>
+                    {editingUser.disabledByQuota ? (
+                      <Chip color="danger" size="sm" variant="flat">
+                        配额已触发禁用
+                      </Chip>
+                    ) : (
+                      <Chip color="success" size="sm" variant="flat">
+                        配额正常
+                      </Chip>
+                    )}
+                  </div>
+
+                  <div className="grid grid-cols-1 gap-3 md:grid-cols-2">
+                    <div className="rounded-lg bg-background p-3">
+                      <div className="text-xs text-default-500">每日用量</div>
+                      <div className="mt-1 text-sm font-semibold text-foreground">
+                        {formatFlow(Number(editingUser.dailyUsedBytes ?? 0))} /{" "}
+                        {formatQuotaLimit(editingUser.dailyQuotaGB)}
+                      </div>
+                    </div>
+                    <div className="rounded-lg bg-background p-3">
+                      <div className="text-xs text-default-500">每月用量</div>
+                      <div className="mt-1 text-sm font-semibold text-foreground">
+                        {formatFlow(Number(editingUser.monthlyUsedBytes ?? 0))} /{" "}
+                        {formatQuotaLimit(editingUser.monthlyQuotaGB)}
+                      </div>
+                    </div>
+                  </div>
+
+                  <div className="flex flex-wrap gap-2">
+                    <Button
+                      color="warning"
+                      isLoading={quotaResetLoading}
+                      size="sm"
+                      variant="flat"
+                      onPress={() => handleQuotaReset("daily")}
+                    >
+                      重置每日配额
+                    </Button>
+                    <Button
+                      color="warning"
+                      isLoading={quotaResetLoading}
+                      size="sm"
+                      variant="flat"
+                      onPress={() => handleQuotaReset("monthly")}
+                    >
+                      重置每月配额
+                    </Button>
+                    <Button
+                      color="primary"
+                      isLoading={quotaResetLoading}
+                      size="sm"
+                      variant="flat"
+                      onPress={() => handleQuotaReset("all")}
+                    >
+                      全部重置并恢复
+                    </Button>
+                  </div>
+                </div>
+              )}
+
             <RadioGroup
               label="状态"
               orientation="horizontal"

vite-frontend/src/types/index.ts

@@ -18,6 +18,12 @@ export interface User {
   createdTime?: number; // 创建时间戳
   inFlow?: number; // 下载流量(字节)
   outFlow?: number; // 上传流量(字节)
+  dailyQuotaGB?: number;
+  monthlyQuotaGB?: number;
+  dailyUsedBytes?: number;
+  monthlyUsedBytes?: number;
+  disabledByQuota?: number;
+  quotaDisabledAt?: number;
 }
 
 export interface UserGroup {
@@ -33,6 +39,8 @@ export interface UserForm {
   pwd?: string;
   status: number;
   flow: number;
+  dailyQuotaGB: number;
+  monthlyQuotaGB: number;
   num: number;
   expTime: Date | null;
   flowResetTime: number;