install-agent: RELEASE_BASE -> V2.3.0 (sh + ps1)

country/country_auto in buildProbeNodeView now come from a local
MMDB lookup of the node's public address (held v4, held v6, seen
v4, seen v6) instead of the pin alone / a hardcoded empty string.
Layered data: local file in the data folder wins, embedded factory
snapshot is the fallback, no database means the pre-flag empty
shape. A weekly job conditionally downloads a fresher copy,
validates it, atomically replaces the local file and hot-swaps the
reader; no URL configured (geoipCountryDefaultURL / the
geoip_country_url setting) means the updater stays silent. No
address ever leaves the master.

cmd/xui-agent/main.go

@@ -0,0 +1,113 @@
+// Command xui-agent is the standalone Linux build of the 3x-ui node
+// agent (agent/panel split, phase 1). Until the split, nodes ran the
+// panel binary under the "agent" subcommand, shipping the whole web
+// panel and the embedded frontend to every node. This entry links only
+// the agent's own dependency closure (internal/agent plus config,
+// logger, selfupdate, xray-api types and two util leaves), so the node
+// artifact is a fraction of the panel binary while remaining a drop-in
+// replacement for it:
+//
+//   - invocation is unchanged: service units run
+//     "xui-agent agent [-config /etc/x-ui/agent.json]" (the bare
+//     "-config" form is also accepted for manual runs);
+//   - agent.json, the traffic baseline and the other state files keep
+//     their names, locations and formats;
+//   - the wire protocol with the master (register / heartbeat /
+//     config / traffic / probe-report / update intent) is byte-for-
+//     byte the internal/agent implementation the dual-mode binary ran.
+//
+// The agent lifecycle wiring below mirrors main.go's agent branch
+// exactly — the same internal/agent package does the work either way,
+// and cmd/xui-agent-windows is the Windows sibling of this entry.
+package main
+
+import (
+	"flag"
+	"fmt"
+	"log"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"syscall"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/agent"
+	"github.com/mhsanaei/3x-ui/v3/internal/config"
+	"github.com/mhsanaei/3x-ui/v3/internal/logger"
+
+	"github.com/op/go-logging"
+)
+
+func main() {
+	args := os.Args[1:]
+
+	// Version self-report: the agent's own display version (A-form),
+	// from the same build-time displayVersion injection the panel
+	// uses. Kept ahead of the subcommand so it works however the
+	// binary was invoked.
+	if len(args) > 0 {
+		switch args[0] {
+		case "-v", "--version", "version":
+			fmt.Println(config.GetAgentDisplayVersion())
+			return
+		}
+	}
+
+	// Service units (systemd / OpenRC / procd / nohup fallback in
+	// install-agent.sh) invoke the binary with the historical "agent"
+	// subcommand; consume it so those units keep working unchanged.
+	if len(args) > 0 && args[0] == "agent" {
+		args = args[1:]
+	} else if len(args) > 0 && args[0][0] != '-' {
+		fmt.Fprintf(os.Stderr, "xui-agent: unknown subcommand %q (this binary only runs the node agent)\n", args[0])
+		os.Exit(2)
+	}
+
+	runAgent(args)
+}
+
+// runAgent is main.go's agent branch, verbatim in behaviour: same
+// flags, same defaults, same shutdown wiring.
+func runAgent(args []string) {
+	agentCmd := flag.NewFlagSet("agent", flag.ExitOnError)
+	var configPath string
+	agentCmd.StringVar(&configPath, "config", "/etc/x-ui/agent.json", "Path to agent config file")
+	agentCmd.Parse(args)
+
+	// Agent mode always uses the panel's directory layout for the
+	// xray binary, geo files and config.json. Scoped to agent mode
+	// only so the panel's own relative "bin" default is untouched.
+	if os.Getenv("XUI_BIN_FOLDER") == "" {
+		_ = os.Setenv("XUI_BIN_FOLDER", agent.DefaultBinFolder)
+	}
+
+	cfg, err := agent.LoadConfig(configPath)
+	if err != nil {
+		log.Fatalf("Failed to load agent config from %s: %v", configPath, err)
+	}
+
+	// The acknowledged traffic baseline persists next to the agent
+	// config (its state home, e.g. /etc/x-ui), unless the config
+	// names a path.
+	if cfg.BaselinePath == "" {
+		cfg.BaselinePath = filepath.Join(filepath.Dir(configPath), "agent-traffic-baseline.json")
+	}
+
+	// Initialize logger
+	logger.InitLogger(logging.INFO)
+	log.Printf("Starting 3x-ui agent (node: %s)", cfg.NodeName)
+
+	ag := agent.New(cfg)
+
+	// Handle shutdown signals
+	sigCh := make(chan os.Signal, 1)
+	signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
+	go func() {
+		<-sigCh
+		log.Println("Shutting down agent...")
+		ag.Stop()
+	}()
+
+	if err := ag.Run(); err != nil {
+		log.Fatalf("Agent error: %v", err)
+	}
+}

frontend/src/pages/nodes/NodeFormModal.tsx

@@ -84,9 +84,6 @@ export default function NodeFormModal({
   const [testResult, setTestResult] = useState<ProbeResult | null>(null);
   const [agentToken, setAgentToken] = useState<string | null>(null);
   const [agentNodeName, setAgentNodeName] = useState('');
-  // Whether the just-created agent node was flagged probe-only, so the
-  // install command below can carry the matching --probe-only flag.
-  const [agentProbeOnly, setAgentProbeOnly] = useState(false);
   const [agentMasterUrl, setAgentMasterUrl] = useState('');
   // Edit mode (item 19): the stored install material for an existing agent
   // node, fetched from the master; null until loaded / for non-agent nodes.
@@ -104,7 +101,6 @@ export default function NodeFormModal({
   const inboundSyncMode = useWatch({ control: methods.control, name: 'inboundSyncMode' }) ?? 'all';
   const nodeType = useWatch({ control: methods.control, name: 'nodeType' }) ?? 'traditional';
   const isAgent = nodeType === 'agent';
-  const probeOnly = useWatch({ control: methods.control, name: 'probeOnly' }) ?? false;
   const { data: outboundGroups } = useOutboundTagGroups({ excludeBlackhole: true });
 
   // Outbounds and balancers share one picker (like the panel-outbound selector);
@@ -186,10 +182,13 @@ export default function NodeFormModal({
     const cmd = shownInstall.hasToken
       ? `${base} --token ${shownInstall.token} --name ${shownInstall.name}`
       : `${base} --name ${shownInstall.name}`;
-    // The toggle is the source of truth for the re-displayed command:
-    // flipping it rewrites the command the operator would re-run.
-    return probeOnly ? `${cmd} --probe-only` : cmd;
-  }, [shownInstall, editMasterUrl, probeOnly]);
+    // The command never carries --probe-only: an agent.json preset would
+    // pin probe-only on the machine (dual-source OR gate) and the panel
+    // toggle alone could no longer turn it off. Probe-only is governed
+    // solely by the master-side flag; the script flag stays for manual
+    // installs that deliberately want the preset.
+    return cmd;
+  }, [shownInstall, editMasterUrl]);
 
   const title = useMemo(
     () => (mode === 'edit' ? t('pages.nodes.editNode') : t('pages.nodes.addNode')),
@@ -307,7 +306,6 @@ export default function NodeFormModal({
         if (agentMode && mode === 'add' && obj?.agentToken) {
           setAgentToken(obj.agentToken);
           setAgentNodeName(result.data.name.trim());
-          setAgentProbeOnly(result.data.probeOnly ?? false);
           // Default the master URL to the address this panel is being
           // viewed through — origin AND base path. Dropping the base
           // path made the agent's registration 404. User can edit it.
@@ -330,7 +328,7 @@ export default function NodeFormModal({
   // one would produce a command that can never register, so withhold it
   // (and say why) instead of letting the user copy a dead command.
   const installCmd = agentMasterUrl
-    ? `bash <(curl -fL https://git.881218.xyz/rogue/3x-ui-agent/raw/branch/main/install-agent.sh) --master ${agentMasterUrl} --token ${agentToken ?? ''} --name ${agentNodeName}${agentProbeOnly ? ' --probe-only' : ''}`
+    ? `bash <(curl -fL https://git.881218.xyz/rogue/3x-ui-agent/raw/branch/main/install-agent.sh) --master ${agentMasterUrl} --token ${agentToken ?? ''} --name ${agentNodeName}`
     : '';
 
   return (

go.mod

@@ -68,6 +68,7 @@ require (
 	github.com/mattn/go-isatty v0.0.24 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/oschwald/maxminddb-golang v1.13.1 // indirect
 	github.com/pelletier/go-toml/v2 v2.4.3 // indirect
 	github.com/power-devops/perfstat v0.0.0-20260805114148-88456608a4f6 // indirect
 	github.com/quic-go/qpack v0.6.0 // indirect

go.sum

@@ -108,6 +108,8 @@ github.com/nicksnyder/go-i18n/v2 v2.6.1 h1:JDEJraFsQE17Dut9HFDHzCoAWGEQJom5s0TRd
 github.com/nicksnyder/go-i18n/v2 v2.6.1/go.mod h1:Vee0/9RD3Quc/NmwEjzzD7VTZ+Ir7QbXocrkhOzmUKA=
 github.com/op/go-logging v0.0.0-20160315200505-970db520ece7 h1:lDH9UUVJtmYCjyT0CI4q8xvlXPxeZ0gYCVvWbmPlp88=
 github.com/op/go-logging v0.0.0-20160315200505-970db520ece7/go.mod h1:HzydrMdWErDVzsI23lYNej1Htcns9BCg93Dk0bBINWk=
+github.com/oschwald/maxminddb-golang v1.13.1 h1:G3wwjdN9JmIK2o/ermkHM+98oX5fS+k5MbwsmL4MRQE=
+github.com/oschwald/maxminddb-golang v1.13.1/go.mod h1:K4pgV9N/GcK694KSTmVSDTODk4IsCNThNdTmnaBZ/F8=
 github.com/pelletier/go-toml/v2 v2.4.3 h1:GTRvJQutkOSftxIFD5xw9aepkYNuPWmVJpffdDPYVpY=
 github.com/pelletier/go-toml/v2 v2.4.3/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=

install-agent.ps1

@@ -29,7 +29,7 @@ $ErrorActionPreference = "Stop"
 
 # Release download base, same shape as install-agent.sh's
 # RELEASE_BASE (the version segment is bumped by the release flow).
-$ReleaseBase = "https://git.881218.xyz/rogue/3x-ui-agent/releases/download/V2.2.1"
+$ReleaseBase = "https://git.881218.xyz/rogue/3x-ui-agent/releases/download/V2.3.0"
 if (-not $AgentUrl) {
     $AgentUrl = "$ReleaseBase/x-ui-agent-windows-amd64.exe"
 }

install-agent.sh

@@ -81,8 +81,13 @@ esac
 # sing-box 核心在 NexusGate 仓的专用发行里（见下方 SINGBOX_BASE）。
 # 注意：本脚本是 V2 版——只装 sing-box 运行时；主控未升 V2 前不要用它
 # 重装节点（节点升级走面板一键更新，不需要本脚本）。
-RELEASE_BASE="https://git.881218.xyz/rogue/3x-ui-agent/releases/download/V2.2.1"
-XUI_URL="${XUI_URL:-${RELEASE_BASE}/x-ui-linux-${BIN_ARCH}}"
+#
+# agent/主控拆分（期一）：下载的是 agent 专用产物 x-ui-agent-linux-<arch>
+# （独立入口 cmd/xui-agent，不再是主控双模式二进制）。该资产自拆分版
+# 发行起才有——RELEASE_BASE 的升版由发版步完成，指向拆分版即可用；
+# 若需装拆分前的旧版节点，显式 XUI_URL 指回 x-ui-linux-<arch> 即可。
+RELEASE_BASE="https://git.881218.xyz/rogue/3x-ui-agent/releases/download/V2.3.0"
+XUI_URL="${XUI_URL:-${RELEASE_BASE}/x-ui-agent-linux-${BIN_ARCH}}"
 
 ROOT="${XUI_ROOT:-}"
 XUI_HOME="${ROOT}/usr/local/x-ui"

internal/agent/update.go

@@ -151,7 +151,12 @@ func (a *Agent) runUpdate(intent updateIntent) {
 		fail(fmt.Errorf("locate own binary: %w", err))
 		return
 	}
-	asset, err := selfupdate.AssetName(runtime.GOARCH)
+	// Agent/panel split (phase 1): the agent downloads the standalone
+	// agent asset, not the panel binary. An agent build predating the
+	// split still asks for the panel asset (AssetName) — the two are
+	// interchangeable at the same path, so each generation converges
+	// on the form its own build requests.
+	asset, err := selfupdate.AgentAssetName(runtime.GOARCH)
 	if err != nil {
 		fail(err)
 		return

internal/agent/update_test.go

@@ -22,7 +22,9 @@ import (
 
 func fakeReleaseServer(t *testing.T, payload []byte, goodSum bool, hits *atomic.Int32) *httptest.Server {
 	t.Helper()
-	asset, err := selfupdate.AssetName(runtime.GOARCH)
+	// The agent requests the standalone agent asset (agent/panel
+	// split); the fake release only serves that name.
+	asset, err := selfupdate.AgentAssetName(runtime.GOARCH)
 	if err != nil {
 		t.Fatal(err)
 	}

internal/selfupdate/selfupdate.go

@@ -20,8 +20,10 @@ import (
 )
 
 // DefaultBaseURL is the release download base of the fork's own Gitea.
-// A release tag directory hangs directly below it:
-// <base><tag>/x-ui-linux-<arch> plus a "<asset>.sha256" sidecar.
+// A release tag directory hangs directly below it, holding the panel
+// assets (<base><tag>/x-ui-linux-<arch>) and — since the agent/panel
+// split — the standalone agent assets (x-ui-agent-linux-<arch>),
+// each with a "<asset>.sha256" sidecar.
 const DefaultBaseURL = "https://git.881218.xyz/rogue/3x-ui-agent/releases/download/"
 
 // LatestReleaseAPI is the Gitea API endpoint for the newest release of the
@@ -41,7 +43,9 @@ func BaseURL() string {
 	return DefaultBaseURL
 }
 
-// AssetName maps a GOARCH to the release asset name published for it.
+// AssetName maps a GOARCH to the release asset name published for it:
+// the panel (dual-mode) binary. The panel's own native self-update
+// downloads this asset; pre-split agents consumed it too.
 func AssetName(goarch string) (string, error) {
 	switch goarch {
 	case "amd64":
@@ -53,6 +57,24 @@ func AssetName(goarch string) (string, error) {
 	}
 }
 
+// AgentAssetName maps a GOARCH to the standalone agent asset published
+// since the agent/panel split (phase 1). A split agent's one-click
+// update downloads this asset — never the panel binary — so a node
+// keeps its slim form across updates. Releases predating the split do
+// not carry these assets; an intent pointing at such a tag fails the
+// download and the agent keeps running its old binary (the designed
+// failure mode of runUpdate).
+func AgentAssetName(goarch string) (string, error) {
+	switch goarch {
+	case "amd64":
+		return "x-ui-agent-linux-amd64", nil
+	case "arm64":
+		return "x-ui-agent-linux-arm64", nil
+	default:
+		return "", fmt.Errorf("no agent release asset for architecture %q", goarch)
+	}
+}
+
 // LatestReleaseURLEnv overrides the release-lookup endpoint as a whole
 // (mirrors, tests), analogous to BaseURLEnv.
 const LatestReleaseURLEnv = "XUI_RELEASE_LATEST_URL"

internal/selfupdate/selfupdate_test.go

@@ -47,6 +47,18 @@ func TestAssetName(t *testing.T) {
 	}
 }
 
+func TestAgentAssetName(t *testing.T) {
+	if name, err := AgentAssetName("amd64"); err != nil || name != "x-ui-agent-linux-amd64" {
+		t.Fatalf("amd64: %q, %v", name, err)
+	}
+	if name, err := AgentAssetName("arm64"); err != nil || name != "x-ui-agent-linux-arm64" {
+		t.Fatalf("arm64: %q, %v", name, err)
+	}
+	if _, err := AgentAssetName("riscv64"); err == nil {
+		t.Fatal("unknown arch must error")
+	}
+}
+
 func TestSwapExecutableKeepsBackup(t *testing.T) {
 	dir := t.TempDir()
 	exe := filepath.Join(dir, "xui-agent")

internal/web/controller/probe_public_test.go

@@ -601,3 +601,61 @@ func TestProbeWebSocket(t *testing.T) {
 func itoa(v int64) string {
 	return strconv.FormatInt(v, 10)
 }
+
+// Q7: the resolved country reaches both frames. The seed's held
+// address is a documentation range (unlisted in any country DB), so
+// repoint it at a real public address whose country the embedded
+// DB-IP snapshot knows — 8.8.8.8 is US there.
+func TestProbePublicCountryFlag(t *testing.T) {
+	rig := newProbeTestRig(t)
+	pubID, _ := rig.seedAgent(t, "FlagNode", true)
+
+	db := database.GetDB()
+	var agent model.AgentNode
+	if err := db.First(&agent, pubID).Error; err != nil {
+		t.Fatalf("load seeded agent: %v", err)
+	}
+	agent.IPv4 = "8.8.8.8"
+	if err := db.Save(&agent).Error; err != nil {
+		t.Fatalf("repoint agent address: %v", err)
+	}
+
+	rig.setSetting(t, "public_page", "on")
+	service.InvalidateProbeSnapshot()
+
+	find := func(rec *httptest.ResponseRecorder) map[string]any {
+		t.Helper()
+		var frame struct {
+			Nodes []map[string]any `json:"nodes"`
+			Admin bool             `json:"admin"`
+		}
+		if err := json.Unmarshal(rec.Body.Bytes(), &frame); err != nil {
+			t.Fatalf("frame decode: %v", err)
+		}
+		for _, n := range frame.Nodes {
+			if n["id"] == float64(pubID) {
+				return n
+			}
+		}
+		t.Fatalf("seeded node missing from frame: %s", rec.Body.String())
+		return nil
+	}
+
+	rec := rig.do(http.MethodGet, "/api/nodes", nil, false)
+	if rec.Code != 200 {
+		t.Fatalf("nodes anon: %d", rec.Code)
+	}
+	if got := find(rec)["country"]; got != "US" {
+		t.Fatalf("anonymous country = %v, want US", got)
+	}
+
+	rec = rig.do(http.MethodGet, "/api/nodes", nil, true)
+	if rec.Code != 200 {
+		t.Fatalf("nodes admin: %d", rec.Code)
+	}
+	admin := find(rec)
+	if admin["country"] != "US" || admin["country_auto"] != "US" || admin["country_pin"] != "" {
+		t.Fatalf("admin country triple = (%v, %v, %v), want (US, US, empty)",
+			admin["country"], admin["country_auto"], admin["country_pin"])
+	}
+}

internal/web/job/geoip_country_job.go

@@ -0,0 +1,23 @@
+package job
+
+import (
+	"github.com/mhsanaei/3x-ui/v3/internal/web/service"
+)
+
+// GeoIPCountryJob is the weekly refresh of the local country
+// database behind the public pages' node flags (Q7: a local MMDB on
+// the master, never an external per-node lookup). The service does
+// the conditional download, validation and hot swap; with no update
+// URL configured the pass is a no-op, so scheduling it is harmless
+// on installs that never opted in.
+type GeoIPCountryJob struct{}
+
+// NewGeoIPCountryJob creates a geoip country job instance.
+func NewGeoIPCountryJob() *GeoIPCountryJob {
+	return new(GeoIPCountryJob)
+}
+
+// Run executes one update pass.
+func (j *GeoIPCountryJob) Run() {
+	service.UpdateGeoIPCountry()
+}

internal/web/service/geoip_country.go

@@ -0,0 +1,376 @@
+package service
+
+import (
+	_ "embed"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/oschwald/maxminddb-golang"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/config"
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+	"github.com/mhsanaei/3x-ui/v3/internal/logger"
+)
+
+// Node country flags (item 7 Q7, resolved 2026-10-24): the public
+// views carry an ISO country code per node, which the themes render
+// as a flag. The upstream hub resolves it by calling ipinfo.io per
+// node; this build never sends a node address to a third party — the
+// lookup is a local MMDB read on the master, from the node's own
+// reported addresses. The agent is untouched: it already reports its
+// interface addresses in its facts, and the master already observes
+// the connection's source addresses (SeenIPv4/SeenIPv6).
+//
+// The data is the DB-IP Lite country database (CC BY 4.0 by DB-IP,
+// https://db-ip.com; attribution and snapshot provenance live in
+// geoipdata/NOTICE), in the MMDB conversion published by the
+// sapics/ip-location-db project. Three layers, in winning order:
+//
+//  1. a local file in the data folder (geoip-country.mmdb beside the
+//     panel database) — written by the weekly updater below, or by
+//     the operator by hand;
+//  2. the factory snapshot embedded in the binary (geoipdata/), so a
+//     fresh install shows flags with no network at all;
+//  3. no database: lookups answer "", the views render exactly the
+//     pre-flag shape.
+//
+// Reads are mmap-backed (maxminddb.Open) or run against the embedded
+// bytes in place; either way a lookup is a pure in-memory tree walk
+// on the snapshot path, and answers are cached per address for the
+// life of the loaded database.
+
+//go:embed geoipdata/country.mmdb
+var geoipCountryEmbedded []byte
+
+// geoipCountryFileName is the local copy's name inside the data
+// folder (config.GetDBFolderPath, where x-ui.db and probe.db live).
+const geoipCountryFileName = "geoip-country.mmdb"
+
+// geoipCountryDefaultURL is the weekly updater's fallback source,
+// used when the operator has not set the geoip_country_url setting.
+//
+// RELEASE-TIME (main session): point this at the self-hosted Gitea
+// mirror asset for geoip-country.mmdb. Empty disables auto-update;
+// the embedded snapshot and any hand-placed local file still apply.
+// Set at V2.3.0 release time to the standing `geoip-country` release
+// asset on the self-hosted Gitea (asset swapped in place, URL stable).
+const geoipCountryDefaultURL = "https://git.881218.xyz/rogue/3x-ui-agent/releases/download/geoip-country/geoip-country.mmdb"
+
+// Settings keys (main settings KV, alongside the other probe_* keys).
+const (
+	geoipCountryURLSetting  = "geoip_country_url"
+	geoipCountryETagSetting = "geoip_country_etag"
+)
+
+// geoipCountryMaxBytes caps one update download; the country
+// database is ~8 MB today, the cap only stops a runaway response.
+const geoipCountryMaxBytes = 64 << 20
+
+// geoipCountryProbeIP / geoipCountryProbeIPv6 are the well-known
+// addresses a candidate database must answer to be trusted (Google
+// DNS v4, AliDNS v6 — both resolve in the DB-IP data).
+const (
+	geoipCountryProbeIP   = "8.8.8.8"
+	geoipCountryProbeIPv6 = "2400:3200::1"
+)
+
+// GeoIPCountryLocalPath is where the local country database lives.
+func GeoIPCountryLocalPath() string {
+	return filepath.Join(config.GetDBFolderPath(), geoipCountryFileName)
+}
+
+// geoipCountryUpdateURL resolves the updater's source: the operator
+// setting wins, else the compiled-in default (possibly empty).
+func geoipCountryUpdateURL() string {
+	if v, ok := probeSetting(geoipCountryURLSetting); ok {
+		if v = strings.TrimSpace(v); v != "" {
+			return v
+		}
+	}
+	return geoipCountryDefaultURL
+}
+
+// ---- the loaded database ----
+
+// countryRecord is the DB-IP Lite record shape: a flat country_code.
+type countryRecord struct {
+	CountryCode string `maxminddb:"country_code"`
+}
+
+// geoipDB is one loaded database plus its per-address answer cache
+// ("" answers are cached too — an unlisted address stays unlisted
+// until the database is swapped).
+type geoipDB struct {
+	reader *maxminddb.Reader
+	origin string // "local" | "embedded"
+
+	mu    sync.Mutex
+	cache map[string]string
+}
+
+func (db *geoipDB) lookup(ipStr string) string {
+	db.mu.Lock()
+	if cc, ok := db.cache[ipStr]; ok {
+		db.mu.Unlock()
+		return cc
+	}
+	db.mu.Unlock()
+
+	cc := ""
+	var rec countryRecord
+	if err := db.reader.Lookup(net.ParseIP(ipStr), &rec); err == nil {
+		cc = rec.CountryCode
+	}
+
+	db.mu.Lock()
+	db.cache[ipStr] = cc
+	db.mu.Unlock()
+	return cc
+}
+
+var (
+	geoipMu   sync.RWMutex
+	geoipCur  *geoipDB
+	geoipOnce sync.Once
+)
+
+// currentGeoIP returns the live database, loading it on first use.
+func currentGeoIP() *geoipDB {
+	geoipOnce.Do(func() {
+		if db := loadGeoIP(); db != nil {
+			swapGeoIP(db)
+		}
+	})
+	geoipMu.RLock()
+	defer geoipMu.RUnlock()
+	return geoipCur
+}
+
+// swapGeoIP makes db the live database. The replaced reader is
+// deliberately NOT closed: it is mmap-backed (or backed by the
+// binary's own image), a lookup racing the swap could still be
+// walking it, and an mmap cannot be safely unmapped under a reader.
+// The mapping is one file per week at most and is reclaimed when the
+// process exits.
+func swapGeoIP(db *geoipDB) {
+	geoipMu.Lock()
+	geoipCur = db
+	geoipMu.Unlock()
+}
+
+// loadGeoIP applies the layer order: a valid local file wins, else
+// the embedded snapshot. A local file that will not open or will not
+// answer falls through to the snapshot with one warning — a corrupt
+// download must never take the flags (or the panel) down.
+func loadGeoIP() *geoipDB {
+	if path := GeoIPCountryLocalPath(); path != "" {
+		if r, err := openGeoIPFile(path); err == nil {
+			return &geoipDB{reader: r, origin: "local", cache: map[string]string{}}
+		} else {
+			logger.Warningf("geoip: local country database %s unusable (%v); using the embedded snapshot", path, err)
+		}
+	}
+	if r, err := maxminddb.FromBytes(geoipCountryEmbedded); err == nil {
+		if err := probeGeoIPReader(r); err == nil {
+			return &geoipDB{reader: r, origin: "embedded", cache: map[string]string{}}
+		} else {
+			logger.Warningf("geoip: embedded country snapshot fails validation: %v", err)
+		}
+	} else {
+		logger.Warningf("geoip: embedded country snapshot will not open: %v", err)
+	}
+	return &geoipDB{origin: "none", cache: map[string]string{}}
+}
+
+// openGeoIPFile opens a database file and checks it answers.
+func openGeoIPFile(path string) (*maxminddb.Reader, error) {
+	r, err := maxminddb.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	if err := probeGeoIPReader(r); err != nil {
+		_ = r.Close()
+		return nil, err
+	}
+	return r, nil
+}
+
+// probeGeoIPReader is the functional validation: the well-known
+// probe address must resolve to a country code, and a v6 probe must
+// at least answer without an error. (maxminddb's Verify is NOT used:
+// it also audits metadata niceties — the DB-IP/sapics files carry an
+// empty description map and fail it despite being fully readable,
+// verified against the factory snapshot on 2026-10-24. A candidate
+// that opens and answers both probes is a working country DB; a
+// truncated or foreign file fails to open or errors a lookup.)
+func probeGeoIPReader(r *maxminddb.Reader) error {
+	var rec countryRecord
+	if err := r.Lookup(net.ParseIP(geoipCountryProbeIP), &rec); err != nil {
+		return err
+	}
+	if rec.CountryCode == "" {
+		return fmt.Errorf("probe address %s resolves to no country", geoipCountryProbeIP)
+	}
+	return r.Lookup(net.ParseIP(geoipCountryProbeIPv6), &rec)
+}
+
+// verifyGeoIPFile validates a fresh download in place before it may
+// replace the live database.
+func verifyGeoIPFile(path string) error {
+	r, err := maxminddb.Open(path)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = r.Close() }()
+	return probeGeoIPReader(r)
+}
+
+// ---- lookups used by the public views ----
+
+// countryCodeForIP resolves one public IP literal to its ISO country
+// code, "" for anything non-public, unknown, or unanswerable. The
+// public gate runs first so private/held addresses never reach the
+// database (they have no country, exactly as on the hub).
+func countryCodeForIP(ipStr string) string {
+	ipStr = strings.TrimSpace(ipStr)
+	if !IsPublicIPLiteral(ipStr) {
+		return ""
+	}
+	db := currentGeoIP()
+	if db == nil || db.reader == nil {
+		return ""
+	}
+	return db.lookup(ipStr)
+}
+
+// probeCountryAuto is a node's auto-detected country: the first
+// public address in the hub's order — the held interface v4, then
+// held v6, then the master-observed exit v4, then exit v6 — resolved
+// locally. "" when the node shows no public address or the database
+// has no answer for it.
+func probeCountryAuto(a *model.AgentNode) string {
+	for _, s := range []string{a.IPv4, a.IPv6, a.SeenIPv4, a.SeenIPv6} {
+		if IsPublicIPLiteral(s) {
+			return countryCodeForIP(s)
+		}
+	}
+	return ""
+}
+
+// probeCountry resolves the pair the views publish (hub api.rs): the
+// effective country is the operator's pin when one is set, else the
+// auto-detected code; country_auto always carries the detected code.
+func probeCountry(pin string, a *model.AgentNode) (country, auto string) {
+	auto = probeCountryAuto(a)
+	if pin != "" {
+		return pin, auto
+	}
+	return auto, auto
+}
+
+// ---- weekly auto-update ----
+
+type geoipFetchResult int
+
+const (
+	geoipFetchUnchanged geoipFetchResult = iota
+	geoipFetchUpdated
+)
+
+// downloadGeoIPCountry performs one conditional download of url into
+// destPath. The candidate lands in a temp file in the destination
+// directory, is fully validated there, and only then renames over
+// destPath (atomic on the same filesystem); any failure leaves
+// destPath and the live database untouched.
+func downloadGeoIPCountry(client *http.Client, url, destPath, etag string, ifModifiedSince time.Time) (geoipFetchResult, string, error) {
+	req, err := http.NewRequest(http.MethodGet, url, nil)
+	if err != nil {
+		return geoipFetchUnchanged, etag, err
+	}
+	if etag != "" {
+		req.Header.Set("If-None-Match", etag)
+	}
+	if !ifModifiedSince.IsZero() {
+		req.Header.Set("If-Modified-Since", ifModifiedSince.UTC().Format(http.TimeFormat))
+	}
+	resp, err := client.Do(req)
+	if err != nil {
+		return geoipFetchUnchanged, etag, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode == http.StatusNotModified {
+		return geoipFetchUnchanged, etag, nil
+	}
+	if resp.StatusCode != http.StatusOK {
+		return geoipFetchUnchanged, etag, fmt.Errorf("update server answered %s", resp.Status)
+	}
+
+	dir := filepath.Dir(destPath)
+	tmp, err := os.CreateTemp(dir, ".geoip-country-*.tmp")
+	if err != nil {
+		return geoipFetchUnchanged, etag, err
+	}
+	tmpName := tmp.Name()
+	defer func() { _ = os.Remove(tmpName) }()
+	n, err := io.Copy(tmp, io.LimitReader(resp.Body, geoipCountryMaxBytes))
+	if err := tmp.Close(); err != nil {
+		return geoipFetchUnchanged, etag, err
+	}
+	if err != nil {
+		return geoipFetchUnchanged, etag, err
+	}
+	if n == 0 {
+		return geoipFetchUnchanged, etag, fmt.Errorf("update download was empty")
+	}
+	if err := verifyGeoIPFile(tmpName); err != nil {
+		return geoipFetchUnchanged, etag, fmt.Errorf("downloaded database rejected: %w", err)
+	}
+	if err := os.Rename(tmpName, destPath); err != nil {
+		return geoipFetchUnchanged, etag, err
+	}
+	return geoipFetchUpdated, resp.Header.Get("ETag"), nil
+}
+
+// UpdateGeoIPCountry runs one update pass: a conditional download
+// from the configured URL, a validated atomic replace of the local
+// copy, and a hot swap of the live reader. No configured URL or any
+// failure keeps the current database; a failure logs a single
+// warning (the hub discipline: a broken mirror must not spam).
+func UpdateGeoIPCountry() {
+	url := geoipCountryUpdateURL()
+	if url == "" {
+		return
+	}
+	dest := GeoIPCountryLocalPath()
+	var lastMod time.Time
+	if fi, err := os.Stat(dest); err == nil {
+		lastMod = fi.ModTime()
+	}
+	etag, _ := probeSetting(geoipCountryETagSetting)
+	client := &http.Client{Timeout: 2 * time.Minute}
+	res, newETag, err := downloadGeoIPCountry(client, url, dest, etag, lastMod)
+	if err != nil {
+		logger.Warningf("geoip: country database update from %s failed: %v (keeping the current database)", url, err)
+		return
+	}
+	if res != geoipFetchUpdated {
+		return
+	}
+	if newETag != "" && newETag != etag {
+		_ = setProbeSetting(geoipCountryETagSetting, newETag)
+	}
+	r, err := openGeoIPFile(dest)
+	if err != nil {
+		logger.Warningf("geoip: updated country database %s will not reopen: %v", dest, err)
+		return
+	}
+	swapGeoIP(&geoipDB{reader: r, origin: "local", cache: map[string]string{}})
+	logger.Infof("geoip: country database updated from %s", url)
+}

internal/web/service/geoip_country_test.go

@@ -0,0 +1,259 @@
+package service
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/oschwald/maxminddb-golang"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+	"github.com/mhsanaei/3x-ui/v3/internal/web/service/probe"
+)
+
+// Q7 node country flags: local MMDB resolution on the master. The
+// known-address expectations below are calibrated against the
+// embedded factory snapshot (DB-IP Lite country database, retrieved
+// 2026-10-24; provenance in geoipdata/NOTICE): these are long-lived
+// anycast/ISP addresses whose country attribution is stable across
+// editions — 8.8.8.8 (Google DNS) US, 223.5.5.5 (AliDNS) CN,
+// 1.1.1.1 (Cloudflare/APNIC) AU, 2400:3200::1 (AliDNS v6) CN.
+
+// useEmbeddedGeoIP swaps the embedded snapshot in as the live
+// database for one test, restoring whatever was live before.
+func useEmbeddedGeoIP(t *testing.T) {
+	t.Helper()
+	prev := currentGeoIP() // fire the lazy load so the Once is spent
+	r, err := maxminddb.FromBytes(geoipCountryEmbedded)
+	if err != nil {
+		t.Fatalf("embedded snapshot will not open: %v", err)
+	}
+	swapGeoIP(&geoipDB{reader: r, origin: "embedded", cache: map[string]string{}})
+	t.Cleanup(func() { swapGeoIP(prev) })
+}
+
+func TestCountryCodeForIPKnownAddresses(t *testing.T) {
+	useEmbeddedGeoIP(t)
+	for ip, want := range map[string]string{
+		"8.8.8.8":      "US",
+		"223.5.5.5":    "CN",
+		"1.1.1.1":      "AU",
+		"2400:3200::1": "CN",
+		" 8.8.8.8 ":    "US", // surrounding space is trimmed
+	} {
+		if got := countryCodeForIP(ip); got != want {
+			t.Errorf("countryCodeForIP(%q) = %q, want %q", ip, got, want)
+		}
+	}
+	// Non-public and unlisted addresses have no country.
+	for _, ip := range []string{
+		"192.168.0.1", // RFC1918
+		"10.0.0.5",    // RFC1918
+		"127.0.0.1",   // loopback
+		"100.64.0.1",  // CGNAT shared range
+		"203.0.113.9", // public documentation range: unlisted in the DB
+		"",            // empty
+		"example.com", // not a literal
+		"999.1.1.1",   // not an address
+	} {
+		if got := countryCodeForIP(ip); got != "" {
+			t.Errorf("countryCodeForIP(%q) = %q, want empty", ip, got)
+		}
+	}
+}
+
+func TestProbeCountryAutoSourceOrder(t *testing.T) {
+	useEmbeddedGeoIP(t)
+	// Held v4 leads over held v6 (hub order).
+	a := &model.AgentNode{IPv4: "8.8.8.8", IPv6: "2400:3200::1", SeenIPv4: "223.5.5.5"}
+	if got := probeCountryAuto(a); got != "US" {
+		t.Errorf("held v4 first: got %q, want US", got)
+	}
+	// A private held v4 is skipped; the held public v6 beats the
+	// observed exit v4.
+	a = &model.AgentNode{IPv4: "10.0.0.5", IPv6: "2400:3200::1", SeenIPv4: "8.8.8.8"}
+	if got := probeCountryAuto(a); got != "CN" {
+		t.Errorf("held v6 over exit v4: got %q, want CN", got)
+	}
+	// Exit addresses are the fallback when the node holds none.
+	a = &model.AgentNode{SeenIPv4: "223.5.5.5"}
+	if got := probeCountryAuto(a); got != "CN" {
+		t.Errorf("exit v4 fallback: got %q, want CN", got)
+	}
+	a = &model.AgentNode{SeenIPv6: "2400:3200::1"}
+	if got := probeCountryAuto(a); got != "CN" {
+		t.Errorf("exit v6 fallback: got %q, want CN", got)
+	}
+	// No public address anywhere: no country.
+	a = &model.AgentNode{IPv4: "192.168.1.2", SeenIPv4: "10.1.1.1"}
+	if got := probeCountryAuto(a); got != "" {
+		t.Errorf("private only: got %q, want empty", got)
+	}
+}
+
+func TestProbeCountryPinWins(t *testing.T) {
+	useEmbeddedGeoIP(t)
+	a := &model.AgentNode{IPv4: "223.5.5.5"}
+	country, auto := probeCountry("JP", a)
+	if country != "JP" || auto != "CN" {
+		t.Errorf("pin set: got (%q, %q), want (JP, CN)", country, auto)
+	}
+	country, auto = probeCountry("", a)
+	if country != "CN" || auto != "CN" {
+		t.Errorf("no pin: got (%q, %q), want (CN, CN)", country, auto)
+	}
+	country, auto = probeCountry("JP", &model.AgentNode{})
+	if country != "JP" || auto != "" {
+		t.Errorf("pin without address: got (%q, %q), want (JP, empty)", country, auto)
+	}
+}
+
+func TestBuildProbeNodeViewCountry(t *testing.T) {
+	useEmbeddedGeoIP(t)
+	src := probeNodeSource{
+		name:  "flagged",
+		agent: model.AgentNode{IPv4: "8.8.8.8"},
+		meta:  probe.Meta{Public: true},
+	}
+	anon := buildProbeNodeView(src, false)
+	if anon["country"] != "US" {
+		t.Errorf("anonymous country = %v, want US", anon["country"])
+	}
+	admin := buildProbeNodeView(src, true)
+	if admin["country"] != "US" || admin["country_auto"] != "US" || admin["country_pin"] != "" {
+		t.Errorf("admin pair = (%v, %v, pin %v), want (US, US, empty)",
+			admin["country"], admin["country_auto"], admin["country_pin"])
+	}
+	src.meta.CountryPin = "DE"
+	if got := buildProbeNodeView(src, false)["country"]; got != "DE" {
+		t.Errorf("pinned country = %v, want DE", got)
+	}
+	if got := buildProbeNodeView(src, true)["country_auto"]; got != "US" {
+		t.Errorf("country_auto under a pin = %v, want US", got)
+	}
+	// A node with no public address keeps the pre-flag empty country.
+	src = probeNodeSource{name: "dark", agent: model.AgentNode{IPv4: "192.168.0.9"}, meta: probe.Meta{Public: true}}
+	if got := buildProbeNodeView(src, false)["country"]; got != "" {
+		t.Errorf("private node country = %v, want empty", got)
+	}
+}
+
+func TestOpenGeoIPFileValidation(t *testing.T) {
+	dir := t.TempDir()
+	bad := filepath.Join(dir, "bad.mmdb")
+	if err := os.WriteFile(bad, []byte("this is not an mmdb"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := openGeoIPFile(bad); err == nil {
+		t.Fatal("garbage file opened as a country database")
+	}
+	good := filepath.Join(dir, "good.mmdb")
+	if err := os.WriteFile(good, geoipCountryEmbedded, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	r, err := openGeoIPFile(good)
+	if err != nil {
+		t.Fatalf("embedded bytes as a file rejected: %v", err)
+	}
+	defer func() { _ = r.Close() }()
+	db := &geoipDB{reader: r, cache: map[string]string{}}
+	if got := db.lookup("223.5.5.5"); got != "CN" {
+		t.Errorf("file-backed lookup = %q, want CN", got)
+	}
+}
+
+// ---- the weekly updater's download/validate/replace core ----
+
+func TestDownloadGeoIPCountryUpdates(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("ETag", `"db-v1"`)
+		_, _ = w.Write(geoipCountryEmbedded)
+	}))
+	defer srv.Close()
+
+	dest := filepath.Join(t.TempDir(), "geoip-country.mmdb")
+	res, etag, err := downloadGeoIPCountry(srv.Client(), srv.URL, dest, "", time.Time{})
+	if err != nil {
+		t.Fatalf("download: %v", err)
+	}
+	if res != geoipFetchUpdated || etag != `"db-v1"` {
+		t.Fatalf("got (res %v, etag %q), want (updated, \"db-v1\")", res, etag)
+	}
+	fi, err := os.Stat(dest)
+	if err != nil || fi.Size() != int64(len(geoipCountryEmbedded)) {
+		t.Fatalf("dest stat = %v (err %v), want %d bytes", fi, err, len(geoipCountryEmbedded))
+	}
+	// The replaced file is a working database.
+	r, err := openGeoIPFile(dest)
+	if err != nil {
+		t.Fatalf("replaced file will not open: %v", err)
+	}
+	_ = r.Close()
+}
+
+func TestDownloadGeoIPCountryNotModified(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("If-None-Match") == `"db-v1"` || r.Header.Get("If-Modified-Since") != "" {
+			w.WriteHeader(http.StatusNotModified)
+			return
+		}
+		_, _ = w.Write(geoipCountryEmbedded)
+	}))
+	defer srv.Close()
+
+	dir := t.TempDir()
+	dest := filepath.Join(dir, "geoip-country.mmdb")
+	if err := os.WriteFile(dest, []byte("ORIGINAL"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// ETag path.
+	res, _, err := downloadGeoIPCountry(srv.Client(), srv.URL, dest, `"db-v1"`, time.Time{})
+	if err != nil || res != geoipFetchUnchanged {
+		t.Fatalf("etag path: got (res %v, err %v), want unchanged", res, err)
+	}
+	// If-Modified-Since path.
+	res, _, err = downloadGeoIPCountry(srv.Client(), srv.URL, dest, "", time.Now())
+	if err != nil || res != geoipFetchUnchanged {
+		t.Fatalf("modified-since path: got (res %v, err %v), want unchanged", res, err)
+	}
+	body, _ := os.ReadFile(dest)
+	if string(body) != "ORIGINAL" {
+		t.Fatalf("dest rewritten on a 304: %q", body)
+	}
+}
+
+func TestDownloadGeoIPCountryRejectsBad(t *testing.T) {
+	dir := t.TempDir()
+	dest := filepath.Join(dir, "geoip-country.mmdb")
+	if err := os.WriteFile(dest, []byte("ORIGINAL"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	assertKept := func(name string) {
+		t.Helper()
+		body, _ := os.ReadFile(dest)
+		if string(body) != "ORIGINAL" {
+			t.Fatalf("%s: dest replaced despite the failure: %q", name, body)
+		}
+	}
+
+	garbage := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte("definitely not an mmdb, just bytes"))
+	}))
+	defer garbage.Close()
+	if _, _, err := downloadGeoIPCountry(garbage.Client(), garbage.URL, dest, "", time.Time{}); err == nil {
+		t.Fatal("garbage download accepted")
+	}
+	assertKept("garbage")
+
+	broken := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer broken.Close()
+	if _, _, err := downloadGeoIPCountry(broken.Client(), broken.URL, dest, "", time.Time{}); err == nil {
+		t.Fatal("500 download accepted")
+	}
+	assertKept("500")
+}

internal/web/service/geoipdata/NOTICE

@@ -0,0 +1,26 @@
+Country database attribution
+============================
+
+The embedded country.mmdb is the DB-IP Lite country database
+(dbip-country, IPv4+IPv6 combined), converted to MMDB format by the
+sapics/ip-location-db project:
+
+  https://github.com/sapics/ip-location-db
+
+The underlying data is made available by DB-IP (https://db-ip.com)
+under the Creative Commons Attribution 4.0 International License
+(CC BY 4.0):
+
+  https://creativecommons.org/licenses/by/4.0/
+
+Attribution: IP geolocation data by DB-IP, https://db-ip.com
+
+Snapshot provenance (factory copy embedded in the binary):
+  source file : dbip-country.mmdb (sapics/ip-location-db "latest" release)
+  retrieved   : 2026-10-24
+  size        : 8300093 bytes
+  sha256      : fcecf33b565fcda088bbcb7a959b5b35c8e5195ed64fcd67daa3cd9384f6272b
+
+Locally updated copies (downloaded by the master's weekly updater
+into the data folder as geoip-country.mmdb) supersede this snapshot
+at runtime; they are the same database from the same source.

internal/web/service/probe_public.go

@@ -288,6 +288,11 @@ func buildProbeNodeView(src probeNodeSource, full bool) map[string]any {
 	a := src.agent
 	m := src.meta
 	t := src.traffic
+	// The flag pair (hub api.rs): the effective country is the pin
+	// when the operator set one, else the locally resolved code for
+	// the node's public address (geoip_country.go, Q7 — no external
+	// lookup ever leaves the master).
+	country, countryAuto := probeCountry(m.CountryPin, &a)
 
 	var lastSeenAgo any
 	if src.lastSeen > 0 {
@@ -312,7 +317,7 @@ func buildProbeNodeView(src probeNodeSource, full bool) map[string]any {
 	view := map[string]any{
 		"id":                a.Id,
 		"name":              probeDisplayName(src.name, m.PublicRemark),
-		"country":           m.CountryPin,
+		"country":           country,
 		"group":             m.GroupName,
 		"public_remark":     m.PublicRemark,
 		"sort":              m.Sort,
@@ -383,7 +388,7 @@ func buildProbeNodeView(src probeNodeSource, full bool) map[string]any {
 	view["ipv6_auto"] = probeAutoAddress(exits, held4, held6, m.IPv4Pin, "", true)
 	view["interval"] = interval
 	view["country_pin"] = m.CountryPin
-	view["country_auto"] = ""
+	view["country_auto"] = countryAuto
 	view["remark"] = src.remark
 	view["notify"] = m.Notify
 	return view

internal/web/web.go

@@ -320,9 +320,10 @@ const (
 	cadenceXrayLogPrune  = "@every 10m"
 	// cpu.Percent samples over a full minute (blocking), so a finer cadence just
 	// stacks overlapping samplers; subscribers rate-limit alerts to 1/min anyway.
-	cadenceCheckHash   = "@every 2m"
-	cadenceCPUAlarm    = "@every 1m"
-	cadenceMemoryAlarm = "@every 1m"
+	cadenceCheckHash    = "@every 2m"
+	cadenceCPUAlarm     = "@every 1m"
+	cadenceMemoryAlarm  = "@every 1m"
+	cadenceGeoIPCountry = "@weekly"
 )
 
 // startTask schedules background jobs (Xray checks, traffic jobs, cron
@@ -378,6 +379,18 @@ func (s *Server) startTask(restartXray bool, loc *time.Location) {
 		job.NewProbeNotifyHousekeepingJob().Run()
 	}()
 
+	// Node country flags (Q7): refresh the local country database
+	// weekly. The pass is a conditional download — a no-op while no
+	// update URL is configured, cheap (304) while the mirror copy is
+	// current — and the same one-minute startup kick as the probe
+	// jobs above lets a long-parked install catch up without waiting
+	// out the week.
+	_, _ = s.cron.AddJob(cadenceGeoIPCountry, job.NewGeoIPCountryJob())
+	go func() {
+		time.Sleep(time.Minute)
+		job.NewGeoIPCountryJob().Run()
+	}()
+
 	// check client ips from log file every day
 	_, _ = s.cron.AddJob("@daily", job.NewClearLogsJob())
 	_, _ = s.cron.AddJob(cadenceXrayLogPrune, job.NewPruneXrayLogsJob())