feat: node updates by restart, auto by default; Podman Quadlet install from the panel alongside compose [CI]

backend/agent/README.md

@@ -60,4 +60,4 @@ IPv6 线路需要 Agent 实际绑定 IPv6。新配置的默认 `listen.bind` 为
 - 测量引擎和协议由 `backend/shared/` 提供；节点身份、注册和连接由 `backend/fleet/` 提供。
 - 详细安全边界与拓扑见 [`../../docs/design/architecture.md`](../../docs/design/architecture.md)，协议说明见 [`../../docs/design/protocol.md`](../../docs/design/protocol.md)，部署见 [`../../docs/ops/deployment.md`](../../docs/ops/deployment.md)。
 
-Docker 与 rootless/rootful Podman 共用 `packaging/compose/agent/compose.yaml`，配置、身份和缓存放在命名 volume 中，无需宿主配置目录、keep-id 或手动 chown。首次导入和自动更新见部署文档。
+Podman 系用 Quadlet（`packaging/quadlet/moshiro-agent.container`，默认自动更新），Docker 用 `packaging/compose/agent/compose.yaml`（手动更新）；配置、身份和缓存放在命名 volume 中，无需宿主配置目录、keep-id 或手动 chown。首次导入和自动更新见部署文档。

backend/agent/src/MoShiro.Agent/AgentApp.cs

@@ -31,7 +31,7 @@ public sealed class AgentApp : IDisposable
     private readonly TaskCompletionSource _ready = new(TaskCreationOptions.RunContinuationsAsynchronously);
     private readonly AgentAdmission _admission;
     private readonly Outbox _outbox = new(64 << 20);
-    private readonly UpdateBridge _update;
+    private readonly RestartUpdater? _update;
     private readonly BackendUplink _uplink;
     private readonly UdpMux _udp;
     private readonly TcpAcceptor _tcp;
@@ -46,7 +46,7 @@ public sealed class AgentApp : IDisposable
     {
         _ownedRestart = restart is null ? new RestartController() : null;
         _restart = restart ?? _ownedRestart!;
-        _update = new UpdateBridge(dataDirectory, new ConfigStore(dataDirectory).Write, log);
+        _update = RestartUpdater.FromEnvironment("agent", _restart.RequestNow, time, log);
         _config = config;
         _identity = identity;
         _time = time;
@@ -235,7 +235,7 @@ public sealed class AgentApp : IDisposable
         {
             router.OnNotify(MoShiroMethods.UpdateOffer, MoShiroJsonContext.Default.UpdateOfferParams, (_, offer, _) =>
             {
-                _update.WriteOffer(offer);
+                _update?.Offer(offer);
                 return ValueTask.CompletedTask;
             });
         }
@@ -257,7 +257,7 @@ public sealed class AgentApp : IDisposable
         {
             router.OnNotify(MoShiroMethods.UpdateApply, MoShiroJsonContext.Default.UpdateOfferParams, (_, _, _) =>
             {
-                _update.RequestApply();
+                _update?.RequestApply();
                 return ValueTask.CompletedTask;
             });
         }
@@ -341,7 +341,7 @@ public sealed class AgentApp : IDisposable
             DroppedInvalid = _counters.DroppedInvalid,
             DroppedRateLimited = _counters.DroppedRateLimited,
             QueueBytes = _outbox.PendingBytes,
-            Update = _update.ReadStatus(),
+            Update = _update?.Status(),
         };
         _lastIn = packetsIn;
         _lastOut = packetsOut;

backend/fleet/src/Fleet.Hosting/Hosting.cs

@@ -181,7 +181,7 @@ public static class ServiceShell
             // 先取令牌、再取设置：中间被改动的话令牌会被取消，下一轮重新排
             CancellationToken changed = restart.ChangeToken;
             RestartSchedule? schedule = restart.Current;
-            using CancellationTokenSource wait = CancellationTokenSource.CreateLinkedTokenSource(cts.Token, changed);
+            using CancellationTokenSource wait = CancellationTokenSource.CreateLinkedTokenSource(cts.Token, changed, restart.NowToken);
             try
             {
                 if (schedule is null)
@@ -196,6 +196,13 @@ public static class ServiceShell
             }
             catch (OperationCanceledException)
             {
+                if (restart.NowReason is { } reason)
+                {
+                    log.Info("stopping", ("result", reason));
+                    await cts.CancelAsync();
+                    return;
+                }
+
                 continue; // 进程在退出，或者设置被改了：循环条件和下一轮会处理
             }
 

backend/fleet/src/Fleet.Hosting/RestartController.cs

@@ -8,7 +8,9 @@ public sealed class RestartController : IDisposable
     private readonly RestartSchedule? _local;
     private readonly object _gate = new();
     private RestartSchedule? _remote;
+    private readonly CancellationTokenSource _now = new();
     private CancellationTokenSource _changed = new();
+    private string? _nowReason;
 
     public RestartController(RestartSchedule? local = null)
     {
@@ -41,6 +43,32 @@ public sealed class RestartController : IDisposable
         }
     }
 
+    /// <summary>应用要求现在就有序退出（比如管理员请求更新）；退出的原因，没有就是 null。</summary>
+    public string? NowReason
+    {
+        get
+        {
+            lock (_gate)
+            {
+                return _nowReason;
+            }
+        }
+    }
+
+    /// <summary>应用要求现在就退出的令牌。</summary>
+    public CancellationToken NowToken => _now.Token;
+
+    /// <summary>要求进程现在就有序退出，由服务管理器拉起；不管有没有设置定时重启。</summary>
+    public void RequestNow(string reason)
+    {
+        lock (_gate)
+        {
+            _nowReason ??= reason;
+        }
+
+        _now.Cancel();
+    }
+
     /// <summary>面板下发的设置；为空表示面板关闭了定时重启。返回 false 表示文本不合法（节点忽略它）。</summary>
     public bool SetRemote(string? text)
     {
@@ -68,6 +96,7 @@ public sealed class RestartController : IDisposable
         lock (_gate)
         {
             _changed.Dispose();
+            _now.Dispose();
         }
     }
 }

backend/openapi/v1.json

@@ -5000,6 +5000,40 @@
         }
       }
     },
+    "/install/quadlet/{file}": {
+      "get": {
+        "tags": [
+          "ops"
+        ],
+        "summary": "The static Podman Quadlet unit of agent or probe (agent.container, probe.container; same bytes for everyone)",
+        "operationId": "install_quadlet",
+        "parameters": [
+          {
+            "name": "file",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "404": {
+            "description": "Not Found",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDto"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/install.ps1": {
       "get": {
         "tags": [
@@ -6095,7 +6129,8 @@
           "token",
           "plaintext",
           "install_commands",
-          "compose"
+          "compose",
+          "quadlet"
         ],
         "type": "object",
         "properties": {
@@ -6110,6 +6145,9 @@
           },
           "compose": {
             "$ref": "#/components/schemas/ComposeInstallDto"
+          },
+          "quadlet": {
+            "$ref": "#/components/schemas/QuadletInstallDto"
           }
         }
       },
@@ -8520,6 +8558,29 @@
           }
         }
       },
+      "QuadletInstallDto": {
+        "required": [
+          "env",
+          "url",
+          "sha256",
+          "command"
+        ],
+        "type": "object",
+        "properties": {
+          "env": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          },
+          "sha256": {
+            "type": "string"
+          },
+          "command": {
+            "type": "string"
+          }
+        }
+      },
       "RawChunkMetaDto": {
         "required": [
           "chunk_id",

backend/probe/README.md

@@ -56,4 +56,4 @@ moshiro-probe --config /etc/moshiro/probe.json
 - 测量模块由 `backend/shared/MoShiro.Measurement/` 与 Agent 共用；Probe 负责发起连接、调度任务和记录本端数据。
 - 测量模型和协议细节见 [`../../docs/design/measurement.md`](../../docs/design/measurement.md) 与 [`../../docs/design/protocol.md`](../../docs/design/protocol.md)；整体架构见 [`../../docs/design/architecture.md`](../../docs/design/architecture.md)。
 
-Docker 与 rootless/rootful Podman 共用 `packaging/compose/probe/compose.yaml`，配置、身份和缓存放在命名 volume 中，无需宿主配置目录、keep-id 或手动 chown。首次导入和自动更新见部署文档。
+Podman 系用 Quadlet（`packaging/quadlet/moshiro-probe.container`，默认自动更新），Docker 用 `packaging/compose/probe/compose.yaml`（手动更新）；配置、身份和缓存放在命名 volume 中，无需宿主配置目录、keep-id 或手动 chown。首次导入和自动更新见部署文档。

backend/probe/src/MoShiro.Probe/ProbeApp.cs

@@ -36,7 +36,7 @@ public sealed class ProbeApp : IDisposable
         _env = new ConnectionEnv(identity.PeerIdentity, identity.NodeId.Value, file.Limits, directory, new MonoClock(time), time, log);
         directory.Changed += () => _changed.Release();
 
-        var update = new UpdateBridge(configDirectory, new ConfigStore(configDirectory).Write, log);
+        RestartUpdater? update = RestartUpdater.FromEnvironment("probe", reason => restart?.RequestNow(reason), time, log);
         var options = new FleetLinkOptions
         {
             Server = new Uri(file.Fleet.Server),
@@ -45,7 +45,7 @@ public sealed class ProbeApp : IDisposable
             NodeId = identity.NodeId,
             NodeVersion = Version,
             Capabilities = [MoShiroCapabilities.Base],
-            HeartbeatExtra = () => JsonSerializer.SerializeToElement(new ProbeHeartbeatExtra { Update = update.ReadStatus(), Ipv6 = Ipv6Diagnostics.Sample(null, Environment.GetEnvironmentVariable("MOSHIRO_NETWORK_SCOPE"), Environment.GetEnvironmentVariable("HOST_PROC")) }, MoShiroJsonContext.Default.ProbeHeartbeatExtra),
+            HeartbeatExtra = () => JsonSerializer.SerializeToElement(new ProbeHeartbeatExtra { Update = update?.Status(), Ipv6 = Ipv6Diagnostics.Sample(null, Environment.GetEnvironmentVariable("MOSHIRO_NETWORK_SCOPE"), Environment.GetEnvironmentVariable("HOST_PROC")) }, MoShiroJsonContext.Default.ProbeHeartbeatExtra),
             HelloMeta = () => JsonSerializer.SerializeToElement(new ProbeHelloMeta { Owners = [.. trust.Controllers], Platform = PlatformDetector.Detect(), Ipv6 = Ipv6Diagnostics.Sample(null, Environment.GetEnvironmentVariable("MOSHIRO_NETWORK_SCOPE"), Environment.GetEnvironmentVariable("HOST_PROC")) }, MoShiroJsonContext.Default.ProbeHelloMeta),
         };
         var list = new StateHandler<ProbeAgentList>(
@@ -59,12 +59,12 @@ public sealed class ProbeApp : IDisposable
         var router = new RpcRouter<LinkContext>(RpcSide.Node, MoShiroMethodTable.Table, NodeRoles.Probe)
             .OnNotify(MoShiroMethods.UpdateOffer, MoShiroJsonContext.Default.UpdateOfferParams, (_, offer, _) =>
             {
-                update.WriteOffer(offer);
+                update?.Offer(offer);
                 return ValueTask.CompletedTask;
             })
             .OnNotify(MoShiroMethods.UpdateApply, MoShiroJsonContext.Default.UpdateOfferParams, (_, _, _) =>
             {
-                update.RequestApply();
+                update?.RequestApply();
                 return ValueTask.CompletedTask;
             })
             .OnNotify(MoShiroMethods.Schedule, MoShiroJsonContext.Default.ScheduleParams, (_, schedule, _) =>

backend/shared/MoShiro.Measurement/Update/RestartUpdater.cs

@@ -0,0 +1,153 @@
+using System.Globalization;
+using System.Text.Json;
+using Fleet.Core;
+using MoShiro.Protocol;
+
+namespace MoShiro.Measurement;
+
+/// <summary>
+/// 节点的「更新」：面板建议、请求，节点<b>只负责有序退出</b>，换新版本由外面的服务管理器完成——
+/// 例如 Podman 的 Quadlet 单元写了 <c>Pull=always</c>，每次启动都先从镜像仓库拉最新的镜像，所以退出再被拉起就是更新。
+/// 节点自己不下载、不安装、不执行任何东西，所以不需要验证什么：最多让面板（管理员）请求一次重启，和定时重启是同一种能力。
+/// <list type="bullet">
+/// <item>只有设了环境变量 <c>MOSHIRO_UPDATE=restart</c> 才启用（Quadlet 模板里写好了）：别的部署方式退出之后不会重新拉取，开了也不会更新，所以没有启用就不报告更新状态。</item>
+/// <item>策略由环境变量 <c>MOSHIRO_UPDATE_POLICY</c> 决定：<c>auto</c>（默认）发现新版本就自己退出重启，<c>manual</c> 等管理端请求。自动更新有保护：
+/// 进程至少运行 <see cref="MinimumUptime"/> 才会自动退出，新镜像没拉到（标签没变、仓库还没更新）最多每个这么久重启一次，不会陷入重启循环。</item>
+/// <item>面板转来的发布清单（面板登记时已验过 CI 签名）只用来显示「有没有新版本」：组件对、比这个程序新（seq 晚于构建时间）、tag 和提交不同。</item>
+/// </list>
+/// </summary>
+public sealed class RestartUpdater
+{
+    public const string EnvironmentVariable = "MOSHIRO_UPDATE";
+    public const string PolicyVariable = "MOSHIRO_UPDATE_POLICY";
+
+    /// <summary>自动更新之前，进程至少要运行这么久。</summary>
+    public static readonly TimeSpan MinimumUptime = TimeSpan.FromMinutes(10);
+
+    private const int MaxManifestBytes = 4096;
+
+    private readonly string _component;
+    private readonly Action<string> _requestRestart;
+    private readonly TimeProvider _time;
+    private readonly INodeLog _log;
+    private readonly string _tag;
+    private readonly string _commit;
+    private readonly long _builtAt;
+    private readonly object _gate = new();
+    private readonly bool _auto;
+    private int _autoScheduled;
+    private readonly long _startedAt;
+    private UpdateStatus _status;
+
+    /// <param name="tag">这个程序的构建标签、提交和构建时间（秒）：默认取 <see cref="BuildInfo"/>，测试可以传入。</param>
+    public RestartUpdater(string component, Action<string> requestRestart, TimeProvider time, INodeLog log, string? tag = null, string? commit = null, long? builtAtEpoch = null, bool auto = false)
+    {
+        _auto = auto;
+        _startedAt = time.GetTimestamp();
+        _component = component;
+        _requestRestart = requestRestart;
+        _time = time;
+        _log = log;
+        _tag = tag ?? BuildInfo.Tag;
+        _commit = commit ?? BuildInfo.Commit;
+        _builtAt = builtAtEpoch ?? (DateTimeOffset.TryParse(BuildInfo.BuiltAt, CultureInfo.InvariantCulture, DateTimeStyles.AssumeUniversal, out DateTimeOffset built) ? built.ToUnixTimeSeconds() : 0);
+        _status = new UpdateStatus { State = "up_to_date", At = Now() };
+    }
+
+    /// <summary>环境变量 <c>MOSHIRO_UPDATE=restart</c> 才启用；否则返回 null，节点不报告更新状态。</summary>
+    public static RestartUpdater? FromEnvironment(string component, Action<string> requestRestart, TimeProvider time, INodeLog log) =>
+        string.Equals(Environment.GetEnvironmentVariable(EnvironmentVariable), "restart", StringComparison.Ordinal)
+            ? new RestartUpdater(component, requestRestart, time, log, auto: !string.Equals(Environment.GetEnvironmentVariable(PolicyVariable), "manual", StringComparison.OrdinalIgnoreCase))
+            : null;
+
+    /// <summary>面板转来的发布清单：只用来判断有没有新版本。</summary>
+    public void Offer(UpdateOfferParams offer)
+    {
+        if (offer.Manifest.Length is 0 or > MaxManifestBytes)
+        {
+            _log.Warn("ignoring an update offer of an unexpected size");
+            return;
+        }
+
+        try
+        {
+            using JsonDocument document = JsonDocument.Parse(offer.Manifest);
+            JsonElement root = document.RootElement;
+            if (root.ValueKind != JsonValueKind.Object || Text(root, "component") != _component || !root.TryGetProperty("seq", out JsonElement seqValue) || !seqValue.TryGetInt64(out long seq))
+            {
+                return;
+            }
+
+            string tag = Text(root, "tag");
+            string commit = Text(root, "commit");
+            bool same = (_tag.Length > 0 && tag == _tag) || (_commit.Length > 0 && commit.Length > 0 && commit == _commit);
+            bool available;
+            lock (_gate)
+            {
+                _status = same || seq <= _builtAt
+                    ? new UpdateStatus { State = "up_to_date", At = Now() }
+                    : new UpdateStatus
+                    {
+                        State = "available",
+                        Available = new UpdateAvailable { Tag = tag, Version = Text(root, "version"), Digest = Text(root, "digest"), Seq = seq },
+                        At = Now(),
+                    };
+                available = _status.State == "available";
+            }
+
+            if (available && _auto && Interlocked.Exchange(ref _autoScheduled, 1) == 0)
+            {
+                _ = ApplyAfterMinimumUptimeAsync();
+            }
+        }
+        catch (JsonException)
+        {
+            _log.Warn("ignoring an update offer that is not valid JSON");
+        }
+    }
+
+    /// <summary>自动更新：等进程运行够久再退出（刚启动就发现新版本，通常是重启之后标签还没变，立刻再退出会变成重启循环）。</summary>
+    private async Task ApplyAfterMinimumUptimeAsync()
+    {
+        TimeSpan wait = MinimumUptime - _time.GetElapsedTime(_startedAt);
+        if (wait > TimeSpan.Zero)
+        {
+            _log.Info("update available, restarting automatically later", ("in", wait.ToString("c", CultureInfo.InvariantCulture)));
+            await Task.Delay(wait, _time);
+        }
+
+        RequestApply();
+    }
+
+    /// <summary>面板请求更新：有新版本才退出（由外面的服务管理器拉起并拉取最新镜像）。</summary>
+    public bool RequestApply()
+    {
+        lock (_gate)
+        {
+            if (_status.State != "available")
+            {
+                return false;
+            }
+
+            _status = new UpdateStatus { State = "applying", Available = _status.Available, At = Now() };
+        }
+
+        _log.Info("update requested, restarting so the supervisor pulls the latest image");
+        _requestRestart("update");
+        return true;
+    }
+
+    /// <summary>随心跳上报的状态。</summary>
+    public UpdateStatus Status()
+    {
+        lock (_gate)
+        {
+            return new UpdateStatus { State = _status.State, Current = _status.Current, Available = _status.Available, Error = _status.Error, At = _status.At };
+        }
+    }
+
+    private long Now() => _time.GetUtcNow().ToUnixTimeSeconds();
+
+    private static string Text(JsonElement root, string name) =>
+        root.TryGetProperty(name, out JsonElement value) && value.ValueKind == JsonValueKind.String ? value.GetString() ?? "" : "";
+}

backend/shared/MoShiro.Measurement/Update/UpdateBridge.cs

@@ -1,100 +0,0 @@
-using System.Text;
-using System.Text.Json;
-using Fleet.Core;
-using MoShiro.Protocol;
-
-namespace MoShiro.Measurement;
-
-/// <summary>
-/// 节点进程和宿主机更新器之间的文件交换（容器里 <c>/etc/moshiro</c>，也就是数据目录）：
-/// 节点把面板发来的清单和签名写进 <c>update/</c>，把「更新」请求写成 <c>update/apply.request</c>；更新器验签并更新，状态由宿主更新器写在只读挂载的 <c>update-status/status.json</c>。
-/// 节点进程不执行任何命令，也不信任清单的内容（验签在宿主机上）。没有安装更新器时目录写不了或没人读，调用只是返回 false。
-/// </summary>
-public sealed class UpdateBridge
-{
-    private const int MaxManifestBytes = 4096;
-    private const int MaxSignatureBytes = 512;
-    private const int MaxStatusBytes = 4096;
-
-    private readonly string _updateDirectory;
-    private readonly string _statusFile;
-    private readonly Action<string, byte[]> _write;
-    private readonly INodeLog _log;
-
-    /// <param name="write">写数据目录里的文件（相对路径，原子替换）：由节点传入 <c>ConfigStore.Write</c>——常驻进程里只有它可以写文件。</param>
-    public UpdateBridge(string dataDirectory, Action<string, byte[]> write, INodeLog log)
-    {
-        _updateDirectory = Path.Combine(dataDirectory, "update");
-        _statusFile = Path.Combine(dataDirectory, "update-status", "status.json");
-        _write = write;
-        _log = log;
-    }
-
-    /// <summary>放下面板发来的清单和签名（和已有的一样就不动，免得每次重连都惊动更新器）。先写清单、后写签名：更新器监视的是签名文件。</summary>
-    public bool WriteOffer(UpdateOfferParams offer)
-    {
-        byte[] manifest = Encoding.UTF8.GetBytes(offer.Manifest);
-        byte[] signature = Encoding.UTF8.GetBytes(offer.Signature);
-        if (manifest.Length is 0 or > MaxManifestBytes || signature.Length is 0 or > MaxSignatureBytes)
-        {
-            _log.Warn("ignoring an update offer of an unexpected size");
-            return false;
-        }
-
-        try
-        {
-            string manifestPath = Path.Combine(_updateDirectory, "offer.manifest");
-            string signaturePath = Path.Combine(_updateDirectory, "offer.sig");
-            if (Same(manifestPath, manifest) && Same(signaturePath, signature))
-            {
-                return true;
-            }
-
-            _write("update/offer.manifest", manifest);
-            _write("update/offer.sig", signature);
-            _log.Info("update offer received");
-            return true;
-        }
-        catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
-        {
-            _log.Warn("could not store the update offer (is the updater installed?)", ("err", ex.Message));
-            return false;
-        }
-    }
-
-    /// <summary>请求更新：写一个空的 <c>apply.request</c>（更新器验签通过、清单更新才会真的动手）。</summary>
-    public bool RequestApply()
-    {
-        try
-        {
-            _write("update/apply.request", []);
-            _log.Info("update requested");
-            return true;
-        }
-        catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
-        {
-            _log.Warn("could not request the update (is the updater installed?)", ("err", ex.Message));
-            return false;
-        }
-    }
-
-    /// <summary>更新器的状态；没有安装更新器、文件不存在或内容不对时返回 null。</summary>
-    public UpdateStatus? ReadStatus()
-    {
-        try
-        {
-            if (!File.Exists(_statusFile) || new FileInfo(_statusFile).Length > MaxStatusBytes)
-            {
-                return null;
-            }
-
-            return JsonSerializer.Deserialize(File.ReadAllBytes(_statusFile), MoShiroJsonContext.Default.UpdateStatus);
-        }
-        catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or JsonException)
-        {
-            return null;
-        }
-    }
-
-    private static bool Same(string path, byte[] content) => File.Exists(path) && File.ReadAllBytes(path).AsSpan().SequenceEqual(content);
-}

backend/shared/tests/MoShiro.Measurement.Tests/MoShiro.Measurement.Tests.csproj

@@ -5,6 +5,7 @@
   </PropertyGroup>
   <ItemGroup>
     <PackageReference Include="xunit.v3" />
+    <PackageReference Include="Microsoft.Extensions.TimeProvider.Testing" />
     <ProjectReference Include="..\..\MoShiro.Measurement\MoShiro.Measurement.csproj" />
   </ItemGroup>
   <ItemGroup>

backend/shared/tests/MoShiro.Measurement.Tests/RestartUpdaterTests.cs

@@ -0,0 +1,113 @@
+using Fleet.Core;
+using Microsoft.Extensions.Time.Testing;
+using MoShiro.Protocol;
+
+namespace MoShiro.Measurement.Tests;
+
+public sealed class RestartUpdaterTests
+{
+    private readonly List<string> _restarts = [];
+
+    private RestartUpdater Create(string tag = "dev-aaa", string commit = "aaa", long builtAt = 1_000) =>
+        new("agent", _restarts.Add, TimeProvider.System, NullNodeLog.Instance, tag, commit, builtAt);
+
+    private static UpdateOfferParams Offer(string tag, long seq, string component = "agent", string commit = "bbb") =>
+        new() { Manifest = $"{{\"component\":\"{component}\",\"tag\":\"{tag}\",\"version\":\"0.4.0\",\"commit\":\"{commit}\",\"digest\":\"sha256:{new string('a', 64)}\",\"seq\":{seq}}}", Signature = "ignored" };
+
+    [Fact]
+    public void ANewerRelease_IsAvailable_AndOnlyARequestRestartsTheNode()
+    {
+        RestartUpdater updater = Create();
+        updater.Offer(Offer("dev-bbb", 2_000));
+        UpdateStatus status = updater.Status();
+        Assert.Equal("available", status.State);
+        Assert.Equal("dev-bbb", status.Available!.Tag);
+        Assert.Equal(2_000, status.Available.Seq);
+        Assert.Empty(_restarts);
+
+        Assert.True(updater.RequestApply());
+        Assert.Equal(["update"], _restarts);
+        Assert.Equal("applying", updater.Status().State);
+    }
+
+    [Fact]
+    public void TheReleaseThatIsAlreadyRunning_IsUpToDate_ByTagOrByCommit()
+    {
+        RestartUpdater updater = Create();
+        updater.Offer(Offer("dev-aaa", 2_000));
+        Assert.Equal("up_to_date", updater.Status().State);
+        updater.Offer(Offer("dev-other-tag", 2_000, commit: "aaa"));
+        Assert.Equal("up_to_date", updater.Status().State);
+        Assert.False(updater.RequestApply());
+        Assert.Empty(_restarts);
+    }
+
+    [Fact]
+    public void AnOfferOlderThanThisBuild_OrForAnotherComponent_IsNotAnUpdate()
+    {
+        RestartUpdater updater = Create(builtAt: 5_000);
+        updater.Offer(Offer("dev-bbb", 2_000));
+        Assert.Equal("up_to_date", updater.Status().State);
+        updater.Offer(Offer("dev-ccc", 9_000, component: "probe"));
+        Assert.Equal("up_to_date", updater.Status().State);
+        Assert.False(updater.RequestApply());
+    }
+
+    [Fact]
+    public void GarbageOffers_AreIgnored()
+    {
+        RestartUpdater updater = Create();
+        updater.Offer(new UpdateOfferParams { Manifest = "not json", Signature = "x" });
+        updater.Offer(new UpdateOfferParams { Manifest = new string('x', 5000), Signature = "x" });
+        updater.Offer(new UpdateOfferParams { Manifest = "{\"component\":\"agent\"}", Signature = "x" });
+        Assert.Equal("up_to_date", updater.Status().State);
+        Assert.False(updater.RequestApply());
+    }
+
+    [Fact]
+    public async Task TheAutoPolicy_RestartsByItself_ButNotBeforeTheMinimumUptime()
+    {
+        var time = new FakeTimeProvider(DateTimeOffset.FromUnixTimeSeconds(2_000_000_000));
+        var updater = new RestartUpdater("agent", _restarts.Add, time, NullNodeLog.Instance, "dev-aaa", "aaa", 1_000, auto: true);
+        updater.Offer(Offer("dev-bbb", 2_000));
+        updater.Offer(Offer("dev-bbb", 2_000)); // 重连时面板会再发一次：不能排两个
+        Assert.Empty(_restarts);
+        time.Advance(TimeSpan.FromMinutes(9));
+        await Task.Delay(50);
+        Assert.Empty(_restarts);
+        time.Advance(TimeSpan.FromMinutes(2));
+        await WaitAsync(() => _restarts.Count == 1);
+        Assert.Equal("applying", updater.Status().State);
+        await Task.Delay(50);
+        Assert.Single(_restarts);
+    }
+
+    [Fact]
+    public async Task TheManualPolicy_NeverRestartsByItself()
+    {
+        var time = new FakeTimeProvider(DateTimeOffset.FromUnixTimeSeconds(2_000_000_000));
+        var updater = new RestartUpdater("agent", _restarts.Add, time, NullNodeLog.Instance, "dev-aaa", "aaa", 1_000, auto: false);
+        updater.Offer(Offer("dev-bbb", 2_000));
+        time.Advance(TimeSpan.FromHours(1));
+        await Task.Delay(50);
+        Assert.Empty(_restarts);
+        Assert.Equal("available", updater.Status().State);
+    }
+
+    private static async Task WaitAsync(Func<bool> condition)
+    {
+        for (int i = 0; i < 100 && !condition(); i++)
+        {
+            await Task.Delay(20);
+        }
+
+        Assert.True(condition());
+    }
+
+    [Fact]
+    public void WithoutTheEnvironmentVariable_ThereIsNoUpdater()
+    {
+        Assert.Null(Environment.GetEnvironmentVariable(RestartUpdater.EnvironmentVariable));
+        Assert.Null(RestartUpdater.FromEnvironment("agent", _restarts.Add, TimeProvider.System, NullNodeLog.Instance));
+    }
+}

backend/src/MoShiro.Backend.Api/Admin/AgentEndpoints.cs

@@ -143,7 +143,7 @@ public static class AgentEndpoints
             return Problems.From(http, ownerError);
         }
 
-        var plan = new InstallPlan(genesis, controllers, InstallScripts.Sha256(InstallScripts.Sh), InstallScripts.Sha256(InstallScripts.Ps1), InstallScripts.ComposeSha256(request.Role ?? JoinTokenService.AgentRole));
+        var plan = new InstallPlan(genesis, controllers, InstallScripts.Sha256(InstallScripts.Sh), InstallScripts.Sha256(InstallScripts.Ps1), InstallScripts.ComposeSha256(request.Role ?? JoinTokenService.AgentRole), InstallScripts.QuadletSha256(request.Role ?? JoinTokenService.AgentRole));
         http.SetDetail($"{request.Role ?? JoinTokenService.AgentRole}: {request.Note}");
         Result<CreatedJoinToken> result = await tokens.CreateAsync(
             new Application.CreateJoinTokenRequest(request.Note, request.Labels, request.AutoApprove ?? true, request.MaxUses ?? 1, request.ExpiresInHours ?? 24, request.Role ?? JoinTokenService.AgentRole, http.GetPrincipal().Label), baseUrl, plan, http.RequestAborted);
@@ -154,7 +154,7 @@ public static class AgentEndpoints
 
         http.Response.Headers.CacheControl = "no-store";
         http.Response.Headers.Location = "/api/admin/join-tokens";
-        return TypedResults.Json(new CreatedJoinTokenDto(Mappers.ToDto(created.Info), created.Plaintext, new InstallCommandsDto(created.InstallCommands.Linux, created.InstallCommands.Macos, created.InstallCommands.Windows), new ComposeInstallDto(created.Compose.Env, created.Compose.Url, created.Compose.Sha256, created.Compose.Linux, created.Compose.Macos, created.Compose.Windows)), ApiJsonContext.Default.CreatedJoinTokenDto, statusCode: StatusCodes.Status201Created);
+        return TypedResults.Json(new CreatedJoinTokenDto(Mappers.ToDto(created.Info), created.Plaintext, new InstallCommandsDto(created.InstallCommands.Linux, created.InstallCommands.Macos, created.InstallCommands.Windows), new ComposeInstallDto(created.Compose.Env, created.Compose.Url, created.Compose.Sha256, created.Compose.Linux, created.Compose.Macos, created.Compose.Windows), new QuadletInstallDto(created.Quadlet.Env, created.Quadlet.Url, created.Quadlet.Sha256, created.Quadlet.Command)), ApiJsonContext.Default.CreatedJoinTokenDto, statusCode: StatusCodes.Status201Created);
     }
 
     private static async Task<IResult> RevokeTokenAsync(JoinTokenService tokens, string id, bool? purge, CancellationToken ct)

backend/src/MoShiro.Backend.Api/Contracts/AdminDtos.cs

@@ -91,6 +91,12 @@ public sealed record InstallCommandsDto(string Linux, string Macos, string Windo
 /// <param name="Windows">Windows（Docker Desktop，PowerShell）；Agent 同样是空的。</param>
 public sealed record ComposeInstallDto(string Env, string Url, string Sha256, string Linux, string Macos, string Windows);
 
+/// <param name="Env">要存成 <c>~/.config/moshiro/&lt;角色&gt;.env</c> 的内容（只有公开的值）。</param>
+/// <param name="Url">Quadlet 单元的下载地址。</param>
+/// <param name="Sha256">Quadlet 单元的 SHA-256：命令下载之后先核对它。</param>
+/// <param name="Command">Linux + Podman（rootless）：写 env、下载并核对单元、指定镜像仓库、启动，合在一起的一条命令。</param>
+public sealed record QuadletInstallDto(string Env, string Url, string Sha256, string Command);
+
 /// <summary>下一版里新增的 passkey。</summary>
 public sealed record ProposedCredentialDto(string Id, string Name, DateTimeOffset CreatedAt);
 
@@ -108,7 +114,7 @@ public sealed record TrustProposalDto(string Statement, int Version, string Chal
 /// <param name="InstallMatchesRelease">和 CI 签名的发布清单里记的哈希是否一致；没有清单或清单里没记时为空。不一致说明这个面板提供的脚本不是 CI 构建出来的那份。</param>
 public sealed record TrustStateDto(bool Initialized, string? Genesis, int Version, bool InSync, TrustProposalDto? Proposal, string InstallUrl = "", IReadOnlyList<string>? Operators = null, string InstallShSha256 = "", string InstallPs1Sha256 = "", bool? InstallMatchesRelease = null, string ServerKey = "", bool ServerKeyListed = false, IReadOnlyList<NodeOwnerDto>? OperatorDetails = null);
 
-public sealed record CreatedJoinTokenDto(JoinTokenDto Token, string Plaintext, InstallCommandsDto InstallCommands, ComposeInstallDto Compose);
+public sealed record CreatedJoinTokenDto(JoinTokenDto Token, string Plaintext, InstallCommandsDto InstallCommands, ComposeInstallDto Compose, QuadletInstallDto Quadlet);
 
 /// <summary>Agent 眼中连着的一个 Probe（Agent 上报）。</summary>
 public sealed record ConnectedProbeDto(string ProbeId, string? Version, string? Remote, DateTimeOffset ConnectedSince, string IpVersion = "ipv4");

backend/src/MoShiro.Backend.Api/Contracts/ApiJsonContext.cs

@@ -87,6 +87,7 @@ namespace MoShiro.Backend.Api;
 [JsonSerializable(typeof(SetupStatusDto))]
 [JsonSerializable(typeof(SetupRequest))]
 [JsonSerializable(typeof(ComposeInstallDto))]
+[JsonSerializable(typeof(QuadletInstallDto))]
 [JsonSerializable(typeof(ProposedCredentialDto))]
 [JsonSerializable(typeof(PasskeyDto))]
 [JsonSerializable(typeof(PageDto<PasskeyDto>))]

backend/src/MoShiro.Backend.Api/InstallScripts.cs

@@ -25,6 +25,12 @@ public static class InstallScripts
     /// <summary>某个角色（agent、probe）的 compose 文件的 SHA-256；其他角色返回空。</summary>
     public static string ComposeSha256(string? role) => role is "agent" or "probe" ? Sha256("compose-" + role + ".yaml") : string.Empty;
 
+    /// <summary>Quadlet 单元的资源名（<c>agent.container</c>、<c>probe.container</c>）；不是这两个就是 null。</summary>
+    public static string? QuadletResource(string file) => file is "agent.container" or "probe.container" ? "quadlet-" + file : null;
+
+    /// <summary>某个角色（agent、probe）的 Quadlet 单元的 SHA-256；其他角色返回空。</summary>
+    public static string QuadletSha256(string? role) => role is "agent" or "probe" ? Sha256("quadlet-" + role + ".container") : string.Empty;
+
     /// <summary>脚本内容的 SHA-256（小写十六进制，按 UTF-8 字节）。</summary>
     public static string Sha256(string resource) => Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(Read(resource))));
 

backend/src/MoShiro.Backend.Api/MoShiro.Backend.Api.csproj

@@ -13,6 +13,8 @@
     <EmbeddedResource Include="..\..\..\packaging\compose\agent\compose.yaml" LogicalName="compose-agent.yaml" />
     <EmbeddedResource Include="..\..\..\packaging\compose\probe\compose.yaml" LogicalName="compose-probe.yaml" />
     <EmbeddedResource Include="..\..\..\packaging\compose\backend\compose.yaml" LogicalName="compose-backend.yaml" />
+    <EmbeddedResource Include="..\..\..\packaging\quadlet\moshiro-agent.container" LogicalName="quadlet-agent.container" />
+    <EmbeddedResource Include="..\..\..\packaging\quadlet\moshiro-probe.container" LogicalName="quadlet-probe.container" />
   </ItemGroup>
   <!-- 前端构建产物（web 目录下 npm run build）内嵌进 Backend；没构建时不嵌入，Backend 只提供 API -->
   <ItemGroup Condition="Exists('..\..\..\web\display\dist\index.html')">

backend/src/MoShiro.Backend.Api/OpsEndpoints.cs

@@ -38,6 +38,10 @@ public static class OpsEndpoints
         app.MapGet("/install/compose/{file}", (HttpContext http, string file) => InstallScripts.ComposeResource(file) is { } resource ? Static(http, resource, "text/yaml") : Problems.Create(http, MoShiroErrors.NotFound, "unknown compose file"))
             .Api("install_compose", "The static compose file of agent, probe or backend (agent.yaml, probe.yaml, backend.yaml; same bytes for everyone)", Tag)
             .Produces(StatusCodes.Status200OK, contentType: "text/yaml").ProducesProblems(404);
+        // Podman Quadlet 单元（Linux 上推荐，节点的更新靠 Pull=always）：Agent、Probe 各一份，静态，命令里先核对 SHA-256。
+        app.MapGet("/install/quadlet/{file}", (HttpContext http, string file) => InstallScripts.QuadletResource(file) is { } resource ? Static(http, resource, "text/plain") : Problems.Create(http, MoShiroErrors.NotFound, "unknown quadlet file"))
+            .Api("install_quadlet", "The static Podman Quadlet unit of agent or probe (agent.container, probe.container; same bytes for everyone)", Tag)
+            .Produces(StatusCodes.Status200OK, contentType: "text/plain").ProducesProblems(404);
         app.MapGet("/install.ps1", (HttpContext http) => Static(http, InstallScripts.Ps1, "text/plain"))
             .Api("install_ps1", "The static one-line installer for Windows nodes (same bytes for everyone; its SHA-256 is published with each release)", Tag)
             .Produces(StatusCodes.Status200OK, contentType: "text/plain");

backend/src/MoShiro.Backend.Application/Admin/JoinTokenService.cs

@@ -15,7 +15,8 @@ public sealed record InstallCommands(string Linux, string Macos, string Windows)
 /// 和面板提供的静态安装脚本的 SHA-256（命令先核对哈希再执行）。没有建立信任根时 <c>Genesis</c> 为空，节点不固定信任根。
 /// </summary>
 /// <param name="ComposeSha256">面板提供的这个角色的 compose 文件的 SHA-256（命令下载之后先核对）。</param>
-public sealed record InstallPlan(string? Genesis, IReadOnlyList<string> Controllers, string ScriptShSha256, string ScriptPs1Sha256, string ComposeSha256 = "");
+/// <param name="QuadletSha256">面板提供的这个角色的 Podman Quadlet 单元的 SHA-256。</param>
+public sealed record InstallPlan(string? Genesis, IReadOnlyList<string> Controllers, string ScriptShSha256, string ScriptPs1Sha256, string ComposeSha256 = "", string QuadletSha256 = "");
 
 /// <summary>
 /// compose 安装：<c>Env</c> 是要存成 <c>.env</c> 的内容（只有公开的值），<c>Url</c> 和 <c>Sha256</c> 是 compose 文件的下载地址和哈希，
@@ -23,7 +24,13 @@ public sealed record InstallPlan(string? Genesis, IReadOnlyList<string> Controll
 /// </summary>
 public sealed record ComposeInstall(string Env, string Url, string Sha256, string Linux, string Macos, string Windows);
 
-public sealed record CreatedJoinToken(JoinTokenInfo Info, string Plaintext, InstallCommands InstallCommands, ComposeInstall Compose);
+/// <summary>
+/// Podman Quadlet 安装（Linux 上推荐）：<c>Env</c> 存成 <c>~/.config/moshiro/&lt;角色&gt;.env</c>，<c>Url</c> 和 <c>Sha256</c> 是 Quadlet 单元的下载地址和哈希，
+/// <c>Command</c> 把 env、单元、镜像仓库（drop-in）、核对哈希和启动合在一起。单元写了 <c>Pull=always</c>，节点退出再被拉起就是更新，默认自动更新。
+/// </summary>
+public sealed record QuadletInstall(string Env, string Url, string Sha256, string Command);
+
+public sealed record CreatedJoinToken(JoinTokenInfo Info, string Plaintext, InstallCommands InstallCommands, ComposeInstall Compose, QuadletInstall Quadlet);
 
 /// <summary>加入令牌：明文只在创建时返回一次，服务端只保存 SHA-256。</summary>
 public sealed class JoinTokenService
@@ -86,7 +93,7 @@ public sealed class JoinTokenService
             Ulid.NewPrefixed("jtk", _time), TokenHash.Sha256(plaintext), request.Note, request.Labels ?? [], request.AutoApprove, KindOf(request.Role),
             request.MaxUses, now + (request.ExpiresInHours * 3_600_000L), now, request.CreatedBy, ct);
 
-        return Result<CreatedJoinToken>.Ok(new CreatedJoinToken(info, plaintext, Commands(BaseUrl(requestBaseUrl), request.Role, plaintext, plan), Compose(BaseUrl(requestBaseUrl), request.Role, plaintext, plan)));
+        return Result<CreatedJoinToken>.Ok(new CreatedJoinToken(info, plaintext, Commands(BaseUrl(requestBaseUrl), request.Role, plaintext, plan), Compose(BaseUrl(requestBaseUrl), request.Role, plaintext, plan), Quadlet(BaseUrl(requestBaseUrl), request.Role, plaintext, plan)));
     }
 
     /// <summary>
@@ -150,6 +157,35 @@ public sealed class JoinTokenService
         return new ComposeInstall(Env(false), url, plan.ComposeSha256, linux, macos, windows);
     }
 
+    /// <summary>
+    /// Podman Quadlet 安装：env 文件、单元文件（静态，核对哈希）、一个把镜像仓库指向面板配置的 drop-in，然后启动用户服务。
+    /// 自动更新默认开（<c>MOSHIRO_UPDATE_POLICY</c> 缺省是 auto）：env 里留了一行注释，去掉 # 就改成在管理端手动点更新。
+    /// </summary>
+    public QuadletInstall Quadlet(string baseUrl, string role, string code, InstallPlan plan)
+    {
+        string url = $"{baseUrl}/install/quadlet/{role}.container";
+        var lines = new List<string> { $"MOSHIRO_SERVER={baseUrl}", $"MOSHIRO_JOIN={code}" };
+        if (plan.Genesis is null)
+        {
+            lines.Add("MOSHIRO_ALLOW_NO_OWNER=1");
+        }
+        else
+        {
+            lines.Add($"MOSHIRO_GENESIS={plan.Genesis}");
+            lines.Add($"MOSHIRO_CONTROLLERS={string.Join(',', plan.Controllers)}");
+        }
+
+        lines.Add("# 自动更新默认开：面板发现新版本后，节点运行满 10 分钟就自动重启，Podman 启动时拉最新镜像。想改成在管理端手动点「更新」，去掉下一行的 #");
+        lines.Add("# MOSHIRO_UPDATE_POLICY=manual");
+        string env = string.Join('\n', lines);
+        string unit = $"$HOME/.config/containers/systemd/moshiro-{role}.container";
+        string command = $"mkdir -p ~/.config/moshiro ~/.config/containers/systemd/moshiro-{role}.container.d && cat > ~/.config/moshiro/{role}.env <<'EOF'\n{env}\nEOF\n"
+            + $"chmod 600 ~/.config/moshiro/{role}.env && curl -fsSL '{url}' -o \"{unit}\" && echo \"{plan.QuadletSha256}  {unit}\" | sha256sum -c - "
+            + $"&& printf '[Container]\\nImage={ImageRepository(role)}:latest\\n' > ~/.config/containers/systemd/moshiro-{role}.container.d/10-image.conf "
+            + $"&& systemctl --user daemon-reload && systemctl --user start moshiro-{role}";
+        return new QuadletInstall(env, url, plan.QuadletSha256, command);
+    }
+
     /// <summary>这个角色的镜像仓库地址（不带 tag）：节点镜像仓库加上命名空间。</summary>
     private string ImageRepository(string role)
     {

backend/tests/MoShiro.Backend.Tests/InstallTests.cs

@@ -94,6 +94,53 @@ public sealed class InstallTests
         }
     }
 
+    [Theory]
+    [InlineData("agent")]
+    [InlineData("probe")]
+    public async Task QuadletInstall_ChecksTheUnitHash_PointsTheImageAtTheConfiguredRepository_AndLeavesAutoUpdateOn(string role)
+    {
+        JsonNode created = await CreateAsync(role);
+        JsonNode quadlet = created["quadlet"]!;
+        string env = quadlet["env"]!.GetValue<string>();
+        string command = quadlet["command"]!.GetValue<string>();
+        string url = quadlet["url"]!.GetValue<string>();
+
+        Assert.EndsWith($"/install/quadlet/{role}.container", url, StringComparison.Ordinal);
+        Assert.Contains($"MOSHIRO_JOIN={created["plaintext"]!.GetValue<string>()}", env, StringComparison.Ordinal);
+        Assert.Contains("# MOSHIRO_UPDATE_POLICY=manual", env, StringComparison.Ordinal); // 默认自动更新，env 里只留一行注释说明怎么改成手动
+        Assert.DoesNotContain("\nMOSHIRO_UPDATE_POLICY=", env, StringComparison.Ordinal);
+        Assert.Contains($"~/.config/moshiro/{role}.env", command, StringComparison.Ordinal);
+        Assert.Contains("chmod 600", command, StringComparison.Ordinal);
+        Assert.Contains($"echo \"{quadlet["sha256"]!.GetValue<string>()}  $HOME/.config/containers/systemd/moshiro-{role}.container\" | sha256sum -c -", command, StringComparison.Ordinal);
+        Assert.Contains($"Image=", command, StringComparison.Ordinal);
+        Assert.Contains($"/moshiro-{role}:latest", command, StringComparison.Ordinal);
+        Assert.EndsWith($"systemctl --user daemon-reload && systemctl --user start moshiro-{role}", command, StringComparison.Ordinal);
+
+        // 面板提供的就是命令里核对的那份：Pull=always（退出再被拉起就是更新），并告诉节点外面会重新拉取
+        using HttpResponseMessage served = await _backend.Anonymous.GetAsync($"/install/quadlet/{role}.container");
+        Assert.Equal(HttpStatusCode.OK, served.StatusCode);
+        byte[] body = await served.Content.ReadAsByteArrayAsync();
+        Assert.Equal(quadlet["sha256"]!.GetValue<string>(), Convert.ToHexStringLower(System.Security.Cryptography.SHA256.HashData(body)));
+        string unit = System.Text.Encoding.UTF8.GetString(body);
+        Assert.Contains("\nPull=always", unit, StringComparison.Ordinal);
+        Assert.Contains("Environment=MOSHIRO_UPDATE=restart", unit, StringComparison.Ordinal);
+        Assert.Contains("ReadOnly=true", unit, StringComparison.Ordinal);
+        Assert.Contains("DropCapability=ALL", unit, StringComparison.Ordinal);
+        Assert.Contains("NoNewPrivileges=true", unit, StringComparison.Ordinal);
+        Assert.DoesNotContain("jt_", unit, StringComparison.Ordinal);
+    }
+
+    [Theory]
+    [InlineData("evil.container")]
+    [InlineData("backend.container")]
+    [InlineData("agent")]
+    public async Task OnlyTheTwoQuadletUnits_AreServed(string file)
+    {
+        using HttpResponseMessage response = await _backend.Anonymous.GetAsync("/install/quadlet/" + file);
+
+        Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
+    }
+
     [Theory]
     [InlineData("agent.yaml")]
     [InlineData("probe.yaml")]

backend/tests/MoShiro.Backend.Tests/OpenApiConformanceTests.cs

@@ -53,7 +53,7 @@ public sealed partial class OpenApiConformanceTests
         foreach ((string path, _) in doc["paths"]!.AsObject())
         {
             string[] prefixes = ["/api/public/", "/api/admin/", "/api/agent/v1/"];
-            string[] roots = ["/healthz", "/metrics", "/install", "/install.ps1", "/install/manifest", "/install/manifest.sig", "/install/compose/{file}", "/api/release/offer"];
+            string[] roots = ["/healthz", "/metrics", "/install", "/install.ps1", "/install/manifest", "/install/manifest.sig", "/install/compose/{file}", "/install/quadlet/{file}", "/api/release/offer"];
             Assert.True(prefixes.Any(p => path.StartsWith(p, StringComparison.Ordinal)) || roots.Contains(path), $"{path} is outside the documented layers");
             foreach (string segment in path.Split('/', StringSplitOptions.RemoveEmptyEntries))
             {