feat(backend): report node platform, geo and build info

Agents and probes report OS, arch and build (version, tag, commit, time).
The backend looks up country and ISP of public addresses only, stores them
in node_meta (schema v5) and exposes display info via /api/public/nodes,
/api/public/about and /api/admin/build-info behind site.show_build.

backend/src/Monitor.Backend.Application/Admin/SettingsService.cs

@@ -12,6 +12,7 @@ public sealed record SettingView(string Key, string Type, string Value, string D
 public sealed class SettingsService
 {
     public const string SitePublic = "site.public";
+    public const string SiteShowBuild = "site.show_build";
     public const string RawDays = "retention.raw_days";
     public const string TestRawDays = "retention.test_raw_days";
     public const string Metric10sHours = "retention.metric_10s_hours";
@@ -40,6 +41,7 @@ public sealed class SettingsService
     private static IReadOnlyList<SettingSpec> Known(BackendOptions o) =>
     [
         new(SitePublic, "bool", "false", 0, 1, "Whether anonymous visitors can read the public API."),
+        new(SiteShowBuild, "bool", "false", 0, 1, "Whether the public pages show the versions, tags and build times of the backend, agents and probes."),
         new(RawDays, "int", o.RawRetentionDays.ToString(CultureInfo.InvariantCulture), 1, 365, "Days to keep raw chunks of continuous tasks."),
         new(TestRawDays, "int", o.TestRawRetentionDays.ToString(CultureInfo.InvariantCulture), 1, 365, "Days to keep raw chunks of on-demand tests."),
         new(Metric10sHours, "int", o.Metric10sRetentionHours.ToString(CultureInfo.InvariantCulture), 1, 720, "Hours to keep the 10 s metric layer."),
@@ -114,6 +116,9 @@ public sealed class SettingsService
         return _sitePublic;
     }
 
+    /// <summary>访客能不能看到版本、tag 和构建时间（站点公开之后的另一道开关，默认关）。</summary>
+    public async ValueTask<bool> IsShowBuildAsync(CancellationToken ct) => await _store.GetAsync(SiteShowBuild, ct) == "true";
+
     public async ValueTask<int> GetIntAsync(string key, CancellationToken ct)
     {
         SettingSpec spec = Specs.First(s => s.Key == key);

backend/src/Monitor.Backend.Application/Agents/AgentEventService.cs

@@ -9,12 +9,14 @@ public sealed class AgentEventService
     private readonly AgentRuntime _runtime;
     private readonly IEventStore _events;
     private readonly TimeProvider _time;
+    private readonly NodeInfoService _nodes;
 
-    public AgentEventService(AgentRuntime runtime, IEventStore events, TimeProvider time)
+    public AgentEventService(AgentRuntime runtime, IEventStore events, TimeProvider time, NodeInfoService nodes)
     {
         _runtime = runtime;
         _events = events;
         _time = time;
+        _nodes = nodes;
     }
 
     public async ValueTask OnEventAsync(NodeId agent, AgentEventParams e, CancellationToken ct)
@@ -32,7 +34,8 @@ public sealed class AgentEventService
         switch (e.Kind)
         {
             case AgentEventKinds.ProbeConnected when !string.IsNullOrEmpty(e.Detail):
-                state.AddProbe(e.Probe is { } p ? new ConnectedProbeInfo(e.Detail, p.Version, p.Remote, p.SinceUtcMs > 0 ? p.SinceUtcMs : at) : new ConnectedProbeInfo(e.Detail, null, null, at));
+                state.AddProbe(e.Probe is { } p ? new ConnectedProbeInfo(e.Detail, p.Version, p.Remote, p.SinceUtcMs > 0 ? p.SinceUtcMs : at, p.Platform) : new ConnectedProbeInfo(e.Detail, null, null, at));
+                _nodes.ObserveProbeInBackground(e.Detail, e.Probe?.Remote, e.Probe?.Platform);
                 break;
             case AgentEventKinds.ProbeDisconnected when !string.IsNullOrEmpty(e.Detail):
                 state.RemoveProbe(e.Detail);

backend/src/Monitor.Backend.Application/Agents/AgentRuntime.cs

@@ -5,7 +5,7 @@ using Monitor.Protocol;
 namespace Monitor.Backend.Application;
 
 /// <summary>Agent 眼中的一个已连接 Probe（Agent 在事件和心跳里上报）。</summary>
-public sealed record ConnectedProbeInfo(string Id, string? Version, string? Remote, long SinceMs);
+public sealed record ConnectedProbeInfo(string Id, string? Version, string? Remote, long SinceMs, PlatformInfo? Platform = null);
 
 /// <summary>Agent 的运行时状态（只在内存中）：连着哪些 Probe、最近的进程内计数、端点变化次数。</summary>
 public sealed class AgentRuntimeState

backend/src/Monitor.Backend.Application/Agents/AgentService.cs

@@ -20,8 +20,11 @@ public sealed partial class AgentService
     private readonly TaskPlanner _planner;
     private readonly ISettingsStore _settings;
 
-    public AgentService(IAgentStore agents, AgentRuntime runtime, IAgentGateway gateway, TaskPlanner planner, ISettingsStore settings)
+    private readonly NodeInfoService _nodes;
+
+    public AgentService(IAgentStore agents, AgentRuntime runtime, IAgentGateway gateway, TaskPlanner planner, ISettingsStore settings, NodeInfoService nodes)
     {
+        _nodes = nodes;
         _agents = agents;
         _runtime = runtime;
         _gateway = gateway;
@@ -114,6 +117,7 @@ public sealed partial class AgentService
     {
         await _gateway.DisconnectAsync(id, "deleted", ct);
         await _agents.DeleteAsync(id, ct);
+        await _nodes.ForgetAsync(id.Value, ct);
         _runtime.Remove(id);
         await AfterAgentSetChangedAsync(ct);
     }

backend/src/Monitor.Backend.Application/Agents/MonitorFleetHooks.cs

@@ -51,9 +51,11 @@ public sealed class MonitorNodeEventSink : INodeEventSink
     private readonly IEventStore _events;
     private readonly LiveHub _live;
     private readonly AgentService _service;
+    private readonly NodeInfoService _nodes;
 
-    public MonitorNodeEventSink(IAgentStore agents, AgentRuntime runtime, IEventStore events, LiveHub live, AgentService service)
+    public MonitorNodeEventSink(IAgentStore agents, AgentRuntime runtime, IEventStore events, LiveHub live, AgentService service, NodeInfoService nodes)
     {
+        _nodes = nodes;
         _agents = agents;
         _runtime = runtime;
         _events = events;
@@ -87,7 +89,11 @@ public sealed class MonitorNodeEventSink : INodeEventSink
                     state.LastHeartbeatAtMs = nodeEvent.AtMs;
                     if (beat is not null)
                     {
-                        state.ReplaceProbes(beat.Probes.Select(p => new ConnectedProbeInfo(p.Id.Value, p.Version, p.Remote, p.SinceUtcMs)));
+                        state.ReplaceProbes(beat.Probes.Select(p => new ConnectedProbeInfo(p.Id.Value, p.Version, p.Remote, p.SinceUtcMs, p.Platform)));
+                        foreach (ConnectedProbe p in beat.Probes)
+                        {
+                            _nodes.ObserveProbeInBackground(p.Id.Value, p.Remote, p.Platform);
+                        }
                     }
                 }
                 catch (JsonException)
@@ -142,6 +148,7 @@ public sealed class MonitorNodeEventSink : INodeEventSink
 
         // 端口或证书指纹变了，Probe 需要新的列表
         AgentRecord? after = await _agents.GetAsync(id, ct);
+        _nodes.ObserveAgentInBackground(id.Value, after?.PublicHost, meta.Platform);
         if (before is not null && after is not null
             && (!before.TlsSpki.AsSpan().SequenceEqual(after.TlsSpki) || before.ProbeTcpPort != after.ProbeTcpPort || !before.ProbeUdpPorts.SequenceEqual(after.ProbeUdpPorts))
             && after.Status == NodeStatus.Active)

backend/src/Monitor.Backend.Application/Agents/ProbeService.cs

@@ -35,9 +35,11 @@ public sealed partial class ProbeService
     private readonly AgentRuntime _runtime;
     private readonly IAgentGateway _gateway;
     private readonly TimeProvider _time;
+    private readonly NodeInfoService _nodes;
 
-    public ProbeService(IProbeStore probes, IAgentStore agents, AgentService agentService, AgentRuntime runtime, IAgentGateway gateway, TimeProvider time)
+    public ProbeService(IProbeStore probes, IAgentStore agents, AgentService agentService, AgentRuntime runtime, IAgentGateway gateway, TimeProvider time, NodeInfoService nodes)
     {
+        _nodes = nodes;
         _probes = probes;
         _agents = agents;
         _agentService = agentService;
@@ -138,6 +140,7 @@ public sealed partial class ProbeService
         bool deleted = await _probes.DeleteAsync(id, ct);
         if (deleted)
         {
+            await _nodes.ForgetAsync(id, ct);
             _gateway.NotifyAllTaskSetsChanged();
         }
 

backend/src/Monitor.Backend.Application/ApplicationServiceCollectionExtensions.cs

@@ -27,6 +27,7 @@ public static class ApplicationServiceCollectionExtensions
         services.AddSingleton<AgentService>();
         services.AddSingleton<AgentEventService>();
         services.AddSingleton<HostStatusService>();
+        services.AddSingleton<NodeInfoService>();
         services.AddSingleton<ProbeService>();
         services.AddSingleton<LineService>();
         services.AddSingleton<TestService>();

backend/src/Monitor.Backend.Application/BackendOptions.cs

@@ -61,6 +61,12 @@ public sealed class BackendOptions
     /// </summary>
     public double PhaseDurationScale { get; set; } = 1.0;
 
+    /// <summary>
+    /// IP 归属查询服务的地址（`GET {地址}/lookup?ip=…`）：Backend 用 Probe、Agent 的来源地址查一次国家和运营商，
+    /// 只留下国家代码和运营商名，IP 不对外。留空 = 不查。服务的使用条款（公益、不能商用、保留署名）由部署的人自己遵守。
+    /// </summary>
+    public string? GeoLookupUrl { get; set; } = "https://ip.007995.xyz";
+
     /// <summary>初始管理员（只在没有任何用户时创建）。</summary>
     public string? InitialAdminUser { get; set; }
 

backend/src/Monitor.Backend.Application/Nodes/IspClassifier.cs

@@ -0,0 +1,86 @@
+namespace Monitor.Backend.Application;
+
+/// <summary>
+/// 把「ASN 和组织名」归成几个常见的国内运营商：mobile / telecom / unicom / broadnet；别的是 other（显示组织名）。
+/// 只用来挑展示用的图标和中文名。
+/// </summary>
+public static class IspClassifier
+{
+    public const string Mobile = "mobile";
+    public const string Telecom = "telecom";
+    public const string Unicom = "unicom";
+    public const string Broadnet = "broadnet";
+    public const string Other = "other";
+
+    private static readonly HashSet<int> s_mobile = [9808, 24400, 24445, 56040, 56041, 56042, 56044, 56046, 56047, 56048, 132525, 138407];
+    private static readonly HashSet<int> s_telecom = [4134, 4809, 4811, 4812, 4813, 9394, 17638, 23724, 38283, 58466, 58519, 136188, 137693];
+    private static readonly HashSet<int> s_unicom = [4808, 4837, 9929, 10099, 17621, 17622, 17623, 17816, 136958, 138421];
+    private static readonly HashSet<int> s_broadnet = [63838, 140061];
+
+    public static (string Key, string Name) Classify(int? asn, string? organization)
+    {
+        if (asn is { } a)
+        {
+            if (s_mobile.Contains(a))
+            {
+                return (Mobile, "中国移动");
+            }
+
+            if (s_telecom.Contains(a))
+            {
+                return (Telecom, "中国电信");
+            }
+
+            if (s_unicom.Contains(a))
+            {
+                return (Unicom, "中国联通");
+            }
+
+            if (s_broadnet.Contains(a))
+            {
+                return (Broadnet, "中国广电");
+            }
+        }
+
+        string org = organization ?? string.Empty;
+        if (Has(org, "china mobile") || Has(org, "cmnet") || Has(org, "中国移动"))
+        {
+            return (Mobile, "中国移动");
+        }
+
+        if (Has(org, "china telecom") || Has(org, "chinanet") || Has(org, "中国电信"))
+        {
+            return (Telecom, "中国电信");
+        }
+
+        if (Has(org, "china unicom") || Has(org, "cncgroup") || Has(org, "中国联通"))
+        {
+            return (Unicom, "中国联通");
+        }
+
+        if (Has(org, "china broadnet") || Has(org, "中国广电"))
+        {
+            return (Broadnet, "中国广电");
+        }
+
+        return (Other, Shorten(org));
+    }
+
+    private static bool Has(string text, string needle) => text.Contains(needle, StringComparison.OrdinalIgnoreCase);
+
+    /// <summary>组织名常常很长（「Hangzhou Alibaba Advertising Co.,Ltd.」）：去掉公司后缀，最多留 28 个字符。</summary>
+    internal static string Shorten(string organization)
+    {
+        string name = organization.Trim();
+        foreach (string suffix in new[] { ", Inc.", " Inc.", ", LLC", " LLC", " Co.,Ltd.", " Co., Ltd.", " Co.,Ltd", " Co., Ltd", " Ltd.", " Ltd", " Corporation", " Corp.", " Limited", " GmbH", " B.V.", " S.A." })
+        {
+            if (name.EndsWith(suffix, StringComparison.OrdinalIgnoreCase))
+            {
+                name = name[..^suffix.Length].TrimEnd(',', ' ');
+                break;
+            }
+        }
+
+        return name.Length > 28 ? name[..28].TrimEnd() : name;
+    }
+}

backend/src/Monitor.Backend.Application/Nodes/NodeInfo.cs

@@ -0,0 +1,34 @@
+namespace Monitor.Backend.Application;
+
+/// <summary>
+/// 一个节点（Agent 或 Probe）用来展示的信息：系统和架构、国家、运营商，以及它自己上报的构建信息（版本、tag、提交、构建时间）。
+/// <b>不含任何 IP 地址、城市、ASN 或经纬度</b>——这些只在查询的那一刻用到，不留下，也不对外。
+/// </summary>
+public sealed record NodeInfo(
+    string NodeId,
+    string Kind,
+    string? Os,
+    string? OsName,
+    string? Arch,
+    string? Country,
+    string? IspKey,
+    string? IspName,
+    string? Version = null,
+    string? Tag = null,
+    string? Commit = null,
+    string? BuiltAt = null);
+
+/// <summary>
+/// 存起来的完整记录（只给 Backend 内部用）：多了一个「查询用的主机」，用来判断地址变了没有、要不要重新查。
+/// 这个字段不会出现在任何对外的接口里。
+/// </summary>
+public sealed record NodeMeta(NodeInfo Info, string? GeoHost, long GeoAtMs, long UpdatedAtMs);
+
+public static class NodeKinds
+{
+    public const string Agent = "agent";
+    public const string Probe = "probe";
+}
+
+/// <summary>IP 归属查询的结果（只取需要的几项）。</summary>
+public sealed record GeoInfo(string? Country, int? Asn, string? Organization, bool IsPrivate);

backend/src/Monitor.Backend.Application/Nodes/NodeInfoService.cs

@@ -0,0 +1,220 @@
+using System.Collections.Concurrent;
+using System.Net;
+using System.Net.Sockets;
+using Monitor.Protocol;
+
+namespace Monitor.Backend.Application;
+
+/// <summary>
+/// 节点的展示信息：系统和架构（节点自报），国家和运营商（Backend 用节点的来源地址查一次）。
+/// <list type="bullet">
+/// <item>Probe、Agent 不访问任何外部服务（客户的防火墙常常要审计），查询只由 Backend 发起。</item>
+/// <item>只查公网地址：回环、内网、CGNAT、链路本地的地址一律不发出去。</item>
+/// <item>查询结果只留国家代码和运营商；IP 不对外，也不和展示信息一起返回。</item>
+/// </list>
+/// </summary>
+public sealed class NodeInfoService
+{
+    /// <summary>同一个地址已经查过的结果保留多久，过期后在节点下次出现时重新查（运营商偶尔会变）。</summary>
+    private static readonly TimeSpan s_geoTtl = TimeSpan.FromDays(7);
+
+    /// <summary>查询失败之后多久再试。</summary>
+    private static readonly TimeSpan s_retryAfter = TimeSpan.FromMinutes(10);
+
+    private readonly INodeMetaStore _store;
+    private readonly IGeoLookup _geo;
+    private readonly TimeProvider _time;
+    private readonly ConcurrentDictionary<string, NodeMeta> _cache = new();
+    private readonly ConcurrentDictionary<string, byte> _inflight = new();
+    private Task? _load;
+
+    public NodeInfoService(INodeMetaStore store, IGeoLookup geo, TimeProvider time)
+    {
+        _store = store;
+        _geo = geo;
+        _time = time;
+    }
+
+    /// <summary>所有节点的展示信息（Agent 和 Probe）。</summary>
+    public async ValueTask<IReadOnlyList<NodeInfo>> ListAsync(CancellationToken ct)
+    {
+        await EnsureLoadedAsync(ct);
+        return [.. _cache.Values.Select(m => m.Info)];
+    }
+
+    /// <summary>节点自报的系统、架构和构建信息；没有变化就不写库。</summary>
+    public async ValueTask SetPlatformAsync(string nodeId, string kind, PlatformInfo? platform, CancellationToken ct)
+    {
+        if (platform is null)
+        {
+            return;
+        }
+
+        await EnsureLoadedAsync(ct);
+        NodeMeta current = _cache.TryGetValue(nodeId, out NodeMeta? found) ? found : Empty(nodeId, kind);
+        string? os = Clean(platform.Os, 16);
+        string? name = Clean(platform.Name, 40);
+        string? arch = Clean(platform.Arch, 16);
+        string? version = Clean(platform.Version, 32);
+        string? tag = Clean(platform.Tag, 64);
+        string? commit = Clean(platform.Commit, 40);
+        string? builtAt = Clean(platform.BuiltAt, 32);
+        NodeInfo i = current.Info;
+        if (i.Os == os && i.OsName == name && i.Arch == arch && i.Version == version && i.Tag == tag && i.Commit == commit && i.BuiltAt == builtAt)
+        {
+            return;
+        }
+
+        await SaveAsync(current with { Info = i with { Os = os, OsName = name, Arch = arch, Version = version, Tag = tag, Commit = commit, BuiltAt = builtAt }, UpdatedAtMs = Now() }, ct);
+    }
+
+    /// <summary>
+    /// 节点从某个地址连上来了：查一次它的国家和运营商。已经查过同一个地址（并且没过期）就什么也不做；
+    /// 私有地址不查；查询失败或服务关着，不影响别的，隔一阵再试。
+    /// </summary>
+    public async ValueTask ObserveAddressAsync(string nodeId, string kind, string? host, CancellationToken ct)
+    {
+        host = host?.Trim();
+        if (string.IsNullOrEmpty(host) || !IsPublic(host) || !_inflight.TryAdd(nodeId, 0))
+        {
+            return;
+        }
+
+        try
+        {
+            await EnsureLoadedAsync(ct);
+            NodeMeta current = _cache.TryGetValue(nodeId, out NodeMeta? found) ? found : Empty(nodeId, kind);
+            long now = Now();
+            bool same = string.Equals(current.GeoHost, host, StringComparison.OrdinalIgnoreCase);
+            bool fresh = current.Info.Country is not null && now - current.GeoAtMs < s_geoTtl.TotalMilliseconds;
+            bool recentlyFailed = current.Info.Country is null && now - current.GeoAtMs < s_retryAfter.TotalMilliseconds;
+            if (same && (fresh || recentlyFailed))
+            {
+                return;
+            }
+
+            GeoInfo? geo = await _geo.LookupAsync(host, ct);
+            if (geo is null || geo.IsPrivate || string.IsNullOrEmpty(geo.Country))
+            {
+                // 记下这次没查到（地址和时间），免得每次心跳都去查
+                await SaveAsync(current with { GeoHost = host, GeoAtMs = now, UpdatedAtMs = now }, ct);
+                return;
+            }
+
+            (string key, string name) = IspClassifier.Classify(geo.Asn, geo.Organization);
+            string country = geo.Country.ToUpperInvariant();
+            await SaveAsync(current with { Info = current.Info with { Country = country, IspKey = key, IspName = Clean(name, 40) }, GeoHost = host, GeoAtMs = now, UpdatedAtMs = now }, ct);
+        }
+        finally
+        {
+            _inflight.TryRemove(nodeId, out _);
+        }
+    }
+
+    /// <summary>Probe 连上来或心跳报告它还连着：记下它的系统信息，并在后台查它的国家和运营商。出错只吞掉，不影响调用方。</summary>
+    public void ObserveProbeInBackground(string probeId, string? remote, PlatformInfo? platform) =>
+        _ = Task.Run(async () =>
+        {
+            try
+            {
+                using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(15));
+                await SetPlatformAsync(probeId, NodeKinds.Probe, platform, cts.Token);
+                await ObserveAddressAsync(probeId, NodeKinds.Probe, remote, cts.Token);
+            }
+            catch (Exception ex) when (ex is OperationCanceledException or InvalidOperationException or IOException)
+            {
+                // 展示信息拿不到也没关系，下次再试
+            }
+        });
+
+    /// <summary>Agent 打招呼（hello）：记下它的系统信息，并用它的公开地址在后台查国家和运营商。</summary>
+    public void ObserveAgentInBackground(string agentId, string? publicHost, PlatformInfo? platform) =>
+        _ = Task.Run(async () =>
+        {
+            try
+            {
+                using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(15));
+                await SetPlatformAsync(agentId, NodeKinds.Agent, platform, cts.Token);
+                await ObserveAddressAsync(agentId, NodeKinds.Agent, publicHost, cts.Token);
+            }
+            catch (Exception ex) when (ex is OperationCanceledException or InvalidOperationException or IOException)
+            {
+                // 同上
+            }
+        });
+
+    public async ValueTask ForgetAsync(string nodeId, CancellationToken ct)
+    {
+        _cache.TryRemove(nodeId, out _);
+        await _store.DeleteAsync(nodeId, ct);
+    }
+
+    /// <summary>公网地址才值得查：回环、内网、CGNAT、链路本地、未指定的地址一律不发出去。域名放行（由查询服务自己解析）。</summary>
+    public static bool IsPublic(string host)
+    {
+        if (!IPAddress.TryParse(host, out IPAddress? ip))
+        {
+            return host.Contains('.', StringComparison.Ordinal) && !host.EndsWith(".local", StringComparison.OrdinalIgnoreCase) && !host.EndsWith(".internal", StringComparison.OrdinalIgnoreCase);
+        }
+
+        if (IPAddress.IsLoopback(ip) || ip.Equals(IPAddress.Any) || ip.Equals(IPAddress.IPv6Any) || ip.Equals(IPAddress.None))
+        {
+            return false;
+        }
+
+        if (ip.IsIPv4MappedToIPv6)
+        {
+            ip = ip.MapToIPv4();
+        }
+
+        if (ip.AddressFamily == AddressFamily.InterNetwork)
+        {
+            byte[] b = ip.GetAddressBytes();
+            return !(b[0] == 10
+                || (b[0] == 172 && b[1] is >= 16 and <= 31)
+                || (b[0] == 192 && b[1] == 168)
+                || (b[0] == 169 && b[1] == 254)
+                || (b[0] == 100 && b[1] is >= 64 and <= 127)
+                || b[0] == 0
+                || b[0] >= 224);
+        }
+
+        byte[] v6 = ip.GetAddressBytes();
+        bool linkLocal = v6[0] == 0xfe && (v6[1] & 0xc0) == 0x80;
+        bool uniqueLocal = (v6[0] & 0xfe) == 0xfc;
+        bool multicast = v6[0] == 0xff;
+        return !(linkLocal || uniqueLocal || multicast);
+    }
+
+    /// <summary>第一次用到时从库里读一次（只读一次，之后都在内存里）。</summary>
+    private async ValueTask EnsureLoadedAsync(CancellationToken ct)
+    {
+        Task load = Volatile.Read(ref _load) ?? Interlocked.CompareExchange(ref _load, LoadAsync(), null) ?? _load!;
+        await load.WaitAsync(ct);
+    }
+
+    private async Task LoadAsync()
+    {
+        foreach (NodeMeta meta in await _store.ListAsync(CancellationToken.None))
+        {
+            _cache.TryAdd(meta.Info.NodeId, meta);
+        }
+    }
+
+    private async ValueTask SaveAsync(NodeMeta meta, CancellationToken ct)
+    {
+        _cache[meta.Info.NodeId] = meta;
+        await _store.SaveAsync(meta, ct);
+    }
+
+    private long Now() => _time.GetUtcNow().ToUnixTimeMilliseconds();
+
+    private static NodeMeta Empty(string nodeId, string kind) => new(new NodeInfo(nodeId, kind, null, null, null, null, null, null), null, 0, 0);
+
+    /// <summary>节点自报的字符串只用于展示：去掉首尾空白，截断，没有内容就当没有。</summary>
+    private static string? Clean(string? text, int max)
+    {
+        string trimmed = text?.Trim() ?? string.Empty;
+        return trimmed.Length == 0 ? null : trimmed.Length > max ? trimmed[..max] : trimmed;
+    }
+}

backend/src/Monitor.Backend.Application/Ports/StorePorts.cs

@@ -33,6 +33,22 @@ public interface IAgentStore
     ValueTask SetAppliedTaskStateAsync(NodeId id, long appliedVersion, string? rejectedJson, CancellationToken ct);
 }
 
+/// <summary>节点的展示信息（系统、架构、国家、运营商）。</summary>
+public interface INodeMetaStore
+{
+    ValueTask<IReadOnlyList<NodeMeta>> ListAsync(CancellationToken ct);
+
+    ValueTask SaveAsync(NodeMeta meta, CancellationToken ct);
+
+    ValueTask DeleteAsync(string nodeId, CancellationToken ct);
+}
+
+/// <summary>查一个 IP（或域名）的归属：国家、ASN、组织。实现负责超时和失败（失败返回 null，不抛）。</summary>
+public interface IGeoLookup
+{
+    ValueTask<GeoInfo?> LookupAsync(string host, CancellationToken ct);
+}
+
 public interface IJoinTokenStore
 {
     ValueTask<JoinTokenInfo> CreateAsync(string id, byte[] tokenSha256, string? note, IReadOnlyList<string> labels, bool autoApprove, int maxUses, long expiresAtMs, long nowMs, CancellationToken ct);