perf(memory): report real RSS and cut footprint via GOGC + periodic release

The Usage card showed runtime.MemStats.Sys, a never-shrinking high-water mark of reserved address space that also counts memory already returned to the OS, so it overstated real usage (e.g. ~300 MB on an idle 1-client server). Report process RSS instead so the number matches the OS and drops as memory is freed.

Replace the auto GOMEMLIMIT that targeted ~90 percent of total system RAM (a near no-op while the heap sits far below the limit, and a GC-thrash risk on small/shared VPS per go.dev/doc/gc-guide) with: a lower default GOGC (XUI_GOGC, default 75), a periodic debug.FreeOSMemory job (XUI_MEMORY_RELEASE_INTERVAL, default 10m, 0 disables), and a soft limit applied only from an explicit budget (GOMEMLIMIT, XUI_MEMORY_LIMIT, or a real cgroup cap at 90 percent).

docker-compose.yml

@@ -5,8 +5,8 @@ services:
       dockerfile: ./Dockerfile
     container_name: 3xui_app
     # hostname: yourhostname <- optional
-    # Optional hard memory cap. When set, the panel auto-derives its Go soft
+    # Optional hard memory cap. When set, the panel derives its Go soft limit
-    # limit (GOMEMLIMIT, ~90%) from this so it GCs before the OOM killer fires.
+    # (GOMEMLIMIT, ~90% of this cap) so it GCs before the OOM killer fires.
     # mem_limit: 512m
     # The bundled Fail2ban (XUI_ENABLE_FAIL2BAN below) enforces the IP limit
     # with iptables, which needs NET_ADMIN. Without these caps a ban is logged
@@ -21,8 +21,12 @@ services:
     environment:
       XRAY_VMESS_AEAD_FORCED: "false"
       XUI_ENABLE_FAIL2BAN: "true"
-      # Go memory soft limit. If neither is set, the panel auto-detects the
+      # Memory tuning. The panel keeps RAM low via GOGC + periodic release; it no
-      # cgroup/host limit and targets ~90%. Pin it explicitly with one of:
+      # longer sets a soft limit from total host RAM (no benefit, risks GC thrash).
+      # XUI_GOGC: "75"              # lower = less RAM, slightly more CPU; GOGC env overrides
+      # XUI_MEMORY_RELEASE_INTERVAL: "10"  # minutes between FreeOSMemory; 0 disables
+      # Go memory soft limit, only applied from an explicit budget below (or a
+      # real cgroup/mem_limit cap). Pin it with one of:
       # XUI_MEMORY_LIMIT: "400"      # in MiB
       # GOMEMLIMIT: "400MiB"         # Go syntax, takes precedence
       # XUI_PPROF: "true"           # expose pprof on 127.0.0.1:6060 for profiling

internal/util/sys/memlimit.go

@@ -1,27 +1,59 @@
 package sys
 
 import (
+	"fmt"
 	"os"
 	"runtime/debug"
 	"strconv"
 	"strings"
-
-	"github.com/shirou/gopsutil/v4/mem"
 )
 
-// memLimitHeadroomPercent is the share of detected memory used for the soft
+const (
-// limit, leaving room for non-heap (stacks, mmap, the xray child) before the OS
+	memLimitHeadroomPercent = 90
-// OOM-kills the process.
+	defaultGCPercent        = 75
-const memLimitHeadroomPercent = 90
+	defaultReleaseMinutes   = 10
+)
 
-// ApplyMemoryLimit sets a Go soft memory limit (the runtime's GOMEMLIMIT) when
+// ApplyMemoryTuning configures the Go runtime for a lower, steadier footprint and
-// one is not already configured, so a long-running panel in a memory-capped
+// returns one log line per decision. It does NOT derive a soft limit from total
-// container or VPS triggers GC as it approaches the cap instead of growing RSS
+// system RAM: on a shared or uncontrolled host that gives no benefit (GOGC, not
-// until the OS OOM-kills it. Precedence: an explicit GOMEMLIMIT env is left to
+// the limit, paces GC while the heap is far below it) and risks GC thrashing, so
-// the runtime; otherwise XUI_MEMORY_LIMIT (in MiB) wins; otherwise the limit is
+// memory is kept low via GOGC plus the periodic release job instead.
-// derived from the cgroup memory limit, falling back to total system RAM.
+func ApplyMemoryTuning() []string {
-// Returns the limit applied in bytes (0 when none) and a short source label.
+	lines := []string{applyGCPercent()}
-func ApplyMemoryLimit() (int64, string) {
+	if limit, source := applyMemoryLimit(); limit > 0 {
+		lines = append(lines, fmt.Sprintf("Go memory soft limit set to %d MiB (%s)", limit>>20, source))
+	} else {
+		lines = append(lines, "Go memory soft limit not enforced: "+source)
+	}
+	return lines
+}
+
+// applyGCPercent lowers GOGC so the heap high-water mark, and thus RSS, stays
+// smaller. An explicit GOGC env (including GOGC=off) is left to the runtime.
+func applyGCPercent() string {
+	if _, ok := os.LookupEnv("GOGC"); ok {
+		return "GC percent: GOGC env (handled by the Go runtime)"
+	}
+
+	pct := defaultGCPercent
+	if v := strings.TrimSpace(os.Getenv("XUI_GOGC")); v != "" {
+		if n, err := strconv.Atoi(v); err == nil {
+			pct = n
+		}
+	}
+
+	if pct <= 0 {
+		return "GC percent left at Go default"
+	}
+	debug.SetGCPercent(pct)
+	return fmt.Sprintf("GC percent set to %d", pct)
+}
+
+// applyMemoryLimit sets the soft limit only from an explicit budget: GOMEMLIMIT
+// env (left to the runtime), XUI_MEMORY_LIMIT in MiB, or a real cgroup limit at
+// 90% to leave headroom for non-heap and the xray child. No budget -> Go default.
+func applyMemoryLimit() (int64, string) {
 	if strings.TrimSpace(os.Getenv("GOMEMLIMIT")) != "" {
 		return 0, "GOMEMLIMIT env (handled by the Go runtime)"
 	}
@@ -34,28 +66,32 @@ func ApplyMemoryLimit() (int64, string) {
 		}
 	}
 
-	total, source := detectAvailableMemory()
+	if v, ok := cgroupMemoryLimit(); ok {
-	if total <= 0 {
+		limit := v / 100 * memLimitHeadroomPercent
-		return 0, "undetectable; left at Go default"
+		debug.SetMemoryLimit(limit)
+		return limit, "cgroup limit"
 	}
-	limit := total / 100 * memLimitHeadroomPercent
+
-	debug.SetMemoryLimit(limit)
+	return 0, "no explicit budget; soft limit left at Go default"
-	return limit, source
 }
 
-func detectAvailableMemory() (int64, string) {
+// MemoryReleaseIntervalMinutes reports how often freed heap memory is returned to
-	if v, ok := cgroupMemoryLimit(); ok {
+// the OS via debug.FreeOSMemory. XUI_MEMORY_RELEASE_INTERVAL overrides the
-		return v, "cgroup limit"
+// default; an explicit 0 disables the periodic release.
+func MemoryReleaseIntervalMinutes() int {
+	v := strings.TrimSpace(os.Getenv("XUI_MEMORY_RELEASE_INTERVAL"))
+	if v == "" {
+		return defaultReleaseMinutes
 	}
-	if vm, err := mem.VirtualMemory(); err == nil && vm.Total > 0 {
+	if n, err := strconv.Atoi(v); err == nil && n >= 0 {
-		return int64(vm.Total), "system RAM"
+		return n
 	}
-	return 0, ""
+	return defaultReleaseMinutes
 }
 
 // cgroupMemoryLimit reads the container memory limit from cgroup v2 then v1.
 // A "max" value or the v1 unlimited sentinel (~8 EiB) means no limit at this
-// level, so it reports not-found and the caller falls back to system RAM. The
+// level, so it reports not-found and the caller falls back to the Go default. The
 // files are absent off Linux, which also yields not-found.
 func cgroupMemoryLimit() (int64, bool) {
 	const unlimited = int64(1) << 62

internal/util/sys/procmem.go

@@ -0,0 +1,34 @@
+package sys
+
+import (
+	"os"
+	"sync"
+
+	"github.com/shirou/gopsutil/v4/process"
+)
+
+var (
+	selfProc     *process.Process
+	selfProcOnce sync.Once
+)
+
+// SelfRSS returns the resident set size of the current process in bytes — the
+// real physical memory the OS attributes to the panel. Unlike
+// runtime.MemStats.Sys (a never-shrinking high-water mark of reserved address
+// space that also counts memory already returned to the OS), RSS reflects current
+// usage and drops as memory is released. Returns 0 when unavailable.
+func SelfRSS() uint64 {
+	selfProcOnce.Do(func() {
+		if p, err := process.NewProcess(int32(os.Getpid())); err == nil {
+			selfProc = p
+		}
+	})
+
+	if selfProc == nil {
+		return 0
+	}
+	if mi, err := selfProc.MemoryInfo(); err == nil && mi != nil {
+		return mi.RSS
+	}
+	return 0
+}

internal/web/job/free_os_memory.go

@@ -0,0 +1,19 @@
+package job
+
+import "runtime/debug"
+
+// MemoryReleaseJob returns freed heap spans to the OS so steady-state RSS tracks
+// the live heap between the bursty traffic-collection jobs, instead of lingering
+// at the high-water mark until the scavenger lazily reclaims it.
+type MemoryReleaseJob struct{}
+
+// NewMemoryReleaseJob creates a new memory-release job instance.
+func NewMemoryReleaseJob() *MemoryReleaseJob {
+	return new(MemoryReleaseJob)
+}
+
+// Run forces a GC and returns as much free memory to the OS as possible. It is
+// scheduled on a minutes cadence because FreeOSMemory triggers a full GC.
+func (j *MemoryReleaseJob) Run() {
+	debug.FreeOSMemory()
+}

internal/web/service/server.go

@@ -610,9 +610,13 @@ func (s *ServerService) GetStatus(lastStatus *Status) *Status {
 	}
 
 	// Application stats
-	var rtm runtime.MemStats
+	if rss := sys.SelfRSS(); rss > 0 {
-	runtime.ReadMemStats(&rtm)
+		status.AppStats.Mem = rss
-	status.AppStats.Mem = rtm.Sys
+	} else {
+		var rtm runtime.MemStats
+		runtime.ReadMemStats(&rtm)
+		status.AppStats.Mem = rtm.Sys
+	}
 	status.AppStats.Threads = uint32(runtime.NumGoroutine())
 	if p != nil && p.IsRunning() {
 		status.AppStats.Uptime = p.GetUptime()

internal/web/web.go

@@ -21,6 +21,7 @@ import (
 	"github.com/mhsanaei/3x-ui/v3/internal/logger"
 	"github.com/mhsanaei/3x-ui/v3/internal/mtproto"
 	"github.com/mhsanaei/3x-ui/v3/internal/util/common"
+	"github.com/mhsanaei/3x-ui/v3/internal/util/sys"
 	"github.com/mhsanaei/3x-ui/v3/internal/web/controller"
 	"github.com/mhsanaei/3x-ui/v3/internal/web/job"
 	"github.com/mhsanaei/3x-ui/v3/internal/web/locale"
@@ -394,6 +395,10 @@ func (s *Server) startTask(restartXray bool) {
 	if s.memoryAlarmWanted() {
 		s.cron.AddJob(cadenceMemoryAlarm, job.NewCheckMemJob())
 	}
+
+	if mins := sys.MemoryReleaseIntervalMinutes(); mins > 0 {
+		s.cron.AddJob(fmt.Sprintf("@every %dm", mins), job.NewMemoryReleaseJob())
+	}
 }
 
 // cpuAlarmWanted reports whether any notifier is configured to receive cpu.high

main.go

@@ -53,10 +53,8 @@ func runWebServer() {
 
 	godotenv.Load()
 
-	if limit, source := sys.ApplyMemoryLimit(); limit > 0 {
+	for _, line := range sys.ApplyMemoryTuning() {
-		logger.Infof("Go memory soft limit set to %d MiB (%s)", limit>>20, source)
+		logger.Info(line)
-	} else {
-		logger.Info("Go memory soft limit not enforced: ", source)
 	}
 
 	if os.Getenv("XUI_PPROF") == "true" {