feat: one-line install for agents and probes from one shared script (curl | bash, zsh, PowerShell) [CI]

backend/openapi/v1.json

@@ -4139,16 +4139,28 @@
         }
       }
     },
-    "/install.sh": {
+    "/install": {
       "get": {
         "tags": [
           "ops"
         ],
-        "summary": "Installer for Linux nodes",
+        "summary": "One-line installer for Linux and macOS nodes (agent or probe, decided by the code)",
         "operationId": "install_sh",
+        "parameters": [
+          {
+            "name": "code",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
         "responses": {
-          "501": {
-            "description": "Not Implemented",
+          "200": {
+            "description": "OK"
+          },
+          "404": {
+            "description": "Not Found",
             "content": {
               "application/problem+json": {
                 "schema": {
@@ -4165,11 +4177,23 @@
         "tags": [
           "ops"
         ],
-        "summary": "Installer for Windows nodes",
+        "summary": "One-line installer for Windows nodes (agent or probe, decided by the code)",
         "operationId": "install_ps1",
+        "parameters": [
+          {
+            "name": "code",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
         "responses": {
-          "501": {
-            "description": "Not Implemented",
+          "200": {
+            "description": "OK"
+          },
+          "404": {
+            "description": "Not Found",
             "content": {
               "application/problem+json": {
                 "schema": {

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

@@ -0,0 +1,23 @@
+using System.Reflection;
+using MoShiro.Backend.Application;
+
+namespace MoShiro.Backend.Api;
+
+/// <summary>
+/// 一行安装脚本：<c>packaging/install/</c> 下的 <c>install.sh</c> 和 <c>install.ps1</c> 作为嵌入资源打进 Backend，
+/// 这里把角色、网关、代码和镜像填进去。Agent 和 Probe 共用同一份，不分开维护。
+/// </summary>
+public static class InstallScripts
+{
+    public static string Render(string resource, InstallTarget target)
+    {
+        using Stream stream = typeof(InstallScripts).Assembly.GetManifestResourceStream(resource)
+            ?? throw new InvalidOperationException($"the embedded resource {resource} is missing");
+        using var reader = new StreamReader(stream);
+        return reader.ReadToEnd()
+            .Replace("@@ROLE@@", target.Role, StringComparison.Ordinal)
+            .Replace("@@SERVER@@", target.Server, StringComparison.Ordinal)
+            .Replace("@@CODE@@", target.Code, StringComparison.Ordinal)
+            .Replace("@@IMAGE@@", target.Image, StringComparison.Ordinal);
+    }
+}

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

@@ -7,5 +7,7 @@
   <ItemGroup>
     <PackageReference Include="Microsoft.AspNetCore.OpenApi" />
     <ProjectReference Include="..\MoShiro.Backend.Application\MoShiro.Backend.Application.csproj" />
+    <EmbeddedResource Include="..\..\..\packaging\install\install.sh" LogicalName="install.sh" />
+    <EmbeddedResource Include="..\..\..\packaging\install\install.ps1" LogicalName="install.ps1" />
   </ItemGroup>
 </Project>

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

@@ -6,7 +6,7 @@ using MoShiro.Protocol;
 
 namespace MoShiro.Backend.Api;
 
-/// <summary>运维端点：<c>/healthz</c>、<c>/metrics</c>（admin 令牌）、安装脚本。</summary>
+/// <summary>运维端点：<c>/healthz</c>、<c>/metrics</c>（admin 令牌）、一行安装脚本（<c>/install</c>、<c>/install.ps1</c>）。</summary>
 public static class OpsEndpoints
 {
     private const string Tag = "ops";
@@ -19,10 +19,30 @@ public static class OpsEndpoints
         app.MapGet("/metrics", MetricsAsync)
             .Api("metrics_get", "Prometheus metrics (admin token)", Tag)
             .Produces(StatusCodes.Status200OK, contentType: "text/plain").ProducesProblems(401, 403);
-        app.MapGet("/install.sh", (HttpContext http) => NotShipped(http))
-            .Api("install_sh", "Installer for Linux nodes", Tag).ProducesProblems(501);
-        app.MapGet("/install.ps1", (HttpContext http) => NotShipped(http))
-            .Api("install_ps1", "Installer for Windows nodes", Tag).ProducesProblems(501);
+        // 一行安装：curl -fsSL 'https://panel/install?code=…' | bash（macOS 用 zsh），irm 'https://panel/install.ps1?code=…' | iex（Windows）。
+        // Agent 和 Probe 是同一份脚本，角色、网关和镜像由一次性代码决定；代码不能用就是 404。
+        app.MapGet("/install", (HttpContext http, JoinTokenService tokens, BackendOptions options, string? code) => InstallAsync(http, tokens, options, code, "install.sh", "text/x-shellscript"))
+            .Api("install_sh", "One-line installer for Linux and macOS nodes (agent or probe, decided by the code)", Tag)
+            .Produces(StatusCodes.Status200OK, contentType: "text/x-shellscript").ProducesProblems(404);
+        app.MapGet("/install.sh", (HttpContext http, JoinTokenService tokens, BackendOptions options, string? code) => InstallAsync(http, tokens, options, code, "install.sh", "text/x-shellscript"))
+            .ExcludeFromDescription();
+        app.MapGet("/install.ps1", (HttpContext http, JoinTokenService tokens, BackendOptions options, string? code) => InstallAsync(http, tokens, options, code, "install.ps1", "text/plain"))
+            .Api("install_ps1", "One-line installer for Windows nodes (agent or probe, decided by the code)", Tag)
+            .Produces(StatusCodes.Status200OK, contentType: "text/plain").ProducesProblems(404);
+    }
+
+    private static async Task<IResult> InstallAsync(HttpContext http, JoinTokenService tokens, BackendOptions options, string? code, string resource, string contentType)
+    {
+        string baseUrl = options.PublicUrl ?? $"{http.Request.Scheme}://{http.Request.Host}";
+        InstallTarget? target = string.IsNullOrEmpty(code) ? null : await tokens.ResolveInstallAsync(code, baseUrl, http.RequestAborted);
+        if (target is null)
+        {
+            return Problems.Create(http, MoShiroErrors.NotFound, "the install code is invalid, expired or already used");
+        }
+
+        string script = InstallScripts.Render(resource, target);
+        http.Response.Headers.CacheControl = "no-store";
+        return TypedResults.Text(script, contentType + "; charset=utf-8");
     }
 
     private static async Task<IResult> HealthAsync(HttpContext http, OpsService ops)
@@ -46,8 +66,4 @@ public static class OpsEndpoints
 
         return TypedResults.Text(await ops.RenderPrometheusAsync(http.RequestAborted), "text/plain; version=0.0.4");
     }
-
-    /// <summary>安装脚本需要下载节点程序的发布物，那属于打包与部署（M6），目前还没有。</summary>
-    private static IResult NotShipped(HttpContext http) =>
-        Problems.Create(http, StatusCodes.Status501NotImplemented, ErrorCodeHttpMap.NotImplemented.Value, "the node installer ships with packaging (M6)");
 }

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

@@ -5,11 +5,14 @@ namespace MoShiro.Backend.Application;
 /// <param name="Role"><c>agent</c>（默认）或 <c>probe</c>：用这个令牌注册出来的是哪种节点。</param>
 public sealed record CreateJoinTokenRequest(string? Note, IReadOnlyList<string>? Labels, bool AutoApprove, int MaxUses, int ExpiresInHours, string Role = JoinTokenService.AgentRole);
 
-/// <summary>各个系统上的安装命令（Linux 和 macOS 都用 install.sh，Windows 用 install.ps1）。</summary>
+/// <summary>各个系统上的一行安装命令：Linux 用 bash、macOS 用 zsh、Windows 用 PowerShell。命令里只有一次性代码，节点名字默认取主机名；Agent 和 Probe 是同一份脚本，角色由代码决定。</summary>
 public sealed record InstallCommands(string Linux, string Macos, string Windows);
 
 public sealed record CreatedJoinToken(JoinTokenInfo Info, string Plaintext, InstallCommands InstallCommands);
 
+/// <summary>安装脚本里要填的四个值。</summary>
+public sealed record InstallTarget(string Role, string Server, string Code, string Image);
+
 /// <summary>加入令牌：明文只在创建时返回一次，服务端只保存 SHA-256。</summary>
 public sealed class JoinTokenService
 {
@@ -71,18 +74,44 @@ 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, ct);
 
-        string baseUrl = (_options.PublicUrl ?? requestBaseUrl ?? "https://panel.example.com").TrimEnd('/');
-        // Probe 和 Agent 一样用加入令牌注册；容器节点用部署脚本，Linux 二进制用 install.sh
-        string shell = request.Role == ProbeRole
-            ? $"sudo sh deploy-node.sh probe --server {baseUrl} --join {plaintext} --name <node-name>"
-            : $"curl -fsSL {baseUrl}/install.sh | sh -s -- --join {plaintext} --name <node-name>";
-        // PowerShell 6+（pwsh）：在 cmd 或 PowerShell 里都能直接粘贴
-        string powershell = request.Role == ProbeRole
-            ? $"fleet-enroll --server {baseUrl} --join {plaintext} --name <node-name> --identity-dir <dir>"
-            : $"pwsh -NoProfile -ExecutionPolicy Bypass -Command \"& ([scriptblock]::Create((irm {baseUrl}/install.ps1))) -Join {plaintext} -Name <node-name>\"";
-        return Result<CreatedJoinToken>.Ok(new CreatedJoinToken(info, plaintext, new InstallCommands(shell, shell, powershell)));
+        string baseUrl = BaseUrl(requestBaseUrl);
+        string query = $"{baseUrl}/install?code={plaintext}";
+        return Result<CreatedJoinToken>.Ok(new CreatedJoinToken(info, plaintext, new InstallCommands(
+            $"curl -fsSL '{query}' | bash",
+            $"curl -fsSL '{query}' | zsh",
+            $"irm '{baseUrl}/install.ps1?code={plaintext}' | iex")));
     }
 
+    private string BaseUrl(string? requestBaseUrl) => (_options.PublicUrl ?? requestBaseUrl ?? "https://panel.example.com").TrimEnd('/');
+
+    /// <summary>
+    /// 安装脚本要填的值：由代码找到令牌（不消耗），角色、网关、镜像都在这里决定，Agent 和 Probe 共用同一份脚本。
+    /// 代码不存在、已吊销、已过期或用完了返回 null。网关和镜像要是含有会破坏脚本引号的字符也返回 null。
+    /// </summary>
+    public async ValueTask<InstallTarget?> ResolveInstallAsync(string code, string? requestBaseUrl, CancellationToken ct)
+    {
+        if (code.Length is 0 or > 200)
+        {
+            return null;
+        }
+
+        JoinTokenInfo? token = await _store.FindAsync(TokenHash.Sha256(code), ct);
+        if (token is null || token.RevokedAtMs is not null || token.ExpiresAtMs <= _time.GetUtcNow().ToUnixTimeMilliseconds() || token.Uses >= token.MaxUses)
+        {
+            return null;
+        }
+
+        string role = RoleOf(token.Kind);
+        string registry = (_options.NodeImageRegistry ?? "").Trim('/');
+        string ns = _options.ImageNamespace.Trim('/');
+        string image = $"{(registry.Length > 0 ? registry + "/" : "")}{(ns.Length > 0 ? ns : "moshiro")}/moshiro-{role}:latest";
+        string server = BaseUrl(requestBaseUrl);
+        return IsSafe(server) && IsSafe(image) && IsSafe(code) ? new InstallTarget(role, server, code, image) : null;
+    }
+
+    /// <summary>值会被放进脚本的单引号里：只允许 URL 和镜像名里正常出现的字符。</summary>
+    private static bool IsSafe(string value) => value.All(c => char.IsAsciiLetterOrDigit(c) || c is '.' or '-' or '_' or ':' or '/' or '[' or ']' or '~' or '%');
+
     public ValueTask<IReadOnlyList<JoinTokenInfo>> ListAsync(CancellationToken ct) => _store.ListAsync(ct);
 
     public ValueTask<bool> RevokeAsync(string id, CancellationToken ct) => _store.RevokeAsync(id, _time.GetUtcNow().ToUnixTimeMilliseconds(), ct);

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

@@ -12,6 +12,9 @@ public sealed class BackendOptions
     /// <summary>容器使用的 OCI repository namespace；Compose 默认 moshiro，开发镜像使用 moshiro-dev。</summary>
     public string ImageNamespace { get; set; } = "";
 
+    /// <summary>节点镜像所在的仓库地址（管理端「添加 Agent / Probe」生成的容器命令用它拼镜像名）。</summary>
+    public string NodeImageRegistry { get; set; } = "registry.oeo.one";
+
     /// <summary>容器内更新请求目录；留空使用数据目录下的 update/。</summary>
     public string? BackendUpdateDirectory { get; set; }
 

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

@@ -58,6 +58,9 @@ public interface IJoinTokenStore
 
     ValueTask<IReadOnlyList<JoinTokenInfo>> ListAsync(CancellationToken ct);
 
+    /// <summary>按令牌的 SHA-256 查找（安装脚本用它确认令牌能不能用，不消耗）。</summary>
+    ValueTask<JoinTokenInfo?> FindAsync(byte[] tokenSha256, CancellationToken ct);
+
     ValueTask<bool> RevokeAsync(string id, long nowMs, CancellationToken ct);
 
     ValueTask<bool> DeleteAsync(string id, CancellationToken ct);

backend/src/MoShiro.Backend.Storage.Sqlite/SqliteConfigStores.cs

@@ -32,6 +32,14 @@ public sealed class SqliteJoinTokenStore : IJoinTokenStore
                 r => new JoinTokenInfo(r.GetString(0), r.NullableString(1), StorageJson.Strings(r.GetString(2)), r.GetInt64(3) != 0, r.GetInt32(4), r.GetInt32(5), r.GetInt64(6), r.NullableLong(7), r.GetInt64(8), r.GetString(9))),
             ct);
 
+    public ValueTask<JoinTokenInfo?> FindAsync(byte[] tokenSha256, CancellationToken ct) =>
+        _db.ReadAsync(
+            c => c.QueryOne(
+                "SELECT id, note, labels, auto_approve, max_uses, uses, expires_at, revoked_at, created_at, kind FROM join_tokens WHERE token_sha256 = @h",
+                r => new JoinTokenInfo(r.GetString(0), r.NullableString(1), StorageJson.Strings(r.GetString(2)), r.GetInt64(3) != 0, r.GetInt32(4), r.GetInt32(5), r.GetInt64(6), r.NullableLong(7), r.GetInt64(8), r.GetString(9)),
+                ("@h", tokenSha256)),
+            ct);
+
     public ValueTask<bool> RevokeAsync(string id, long nowMs, CancellationToken ct) =>
         _db.WriteAsync(c => c.Exec("UPDATE join_tokens SET revoked_at = @now WHERE id = @id AND revoked_at IS NULL", ("@id", id), ("@now", nowMs)) == 1, ct);
 

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

@@ -222,11 +222,12 @@ public sealed class ApiBasicsTests
     }
 
     [Fact]
-    public async Task InstallScripts_AreNotShippedYet()
+    public async Task InstallScripts_RequireAValidCode()
     {
+        // 一行安装脚本凭一次性代码获取；没有代码或代码不能用是 404（完整行为见 InstallTests）
         using HttpResponseMessage response = await _backend.Anonymous.GetAsync("/install.sh");
-        Assert.Equal(HttpStatusCode.NotImplemented, response.StatusCode);
-        Assert.Equal("not_implemented", JsonNode.Parse(await response.Content.ReadAsStringAsync())!["code"]!.GetValue<string>());
+        Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
+        Assert.Equal("not_found", JsonNode.Parse(await response.Content.ReadAsStringAsync())!["code"]!.GetValue<string>());
     }
 }
 

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

@@ -0,0 +1,83 @@
+using System.Net;
+using System.Text.Json.Nodes;
+
+namespace MoShiro.Backend.Tests;
+
+/// <summary>一行安装：Agent 和 Probe 共用同一份脚本，角色、网关、镜像由一次性代码决定，节点名字默认取主机名。</summary>
+[Collection("probe-e2e")]
+public sealed class InstallTests
+{
+    private readonly BackendFixture _backend;
+
+    public InstallTests(BackendFixture backend)
+    {
+        _backend = backend;
+    }
+
+    private async Task<JsonNode> CreateAsync(string role)
+    {
+        using HttpResponseMessage response = await _backend.Admin.PostAsync("/api/admin/join-tokens", BackendFixture.Json(new JsonObject { ["role"] = role }));
+        return JsonNode.Parse(await response.Content.ReadAsStringAsync())!;
+    }
+
+    [Theory]
+    [InlineData("agent")]
+    [InlineData("probe")]
+    public async Task Commands_AreOneLiners_WithoutAPlaceholder_AndTheScriptIsFilledInForTheRole(string role)
+    {
+        JsonNode created = await CreateAsync(role);
+        string code = created["plaintext"]!.GetValue<string>();
+        JsonNode commands = created["install_commands"]!;
+        string linux = commands["linux"]!.GetValue<string>();
+        string macos = commands["macos"]!.GetValue<string>();
+        string windows = commands["windows"]!.GetValue<string>();
+        Assert.StartsWith("curl -fsSL '", linux, StringComparison.Ordinal);
+        Assert.EndsWith("/install?code=" + code + "' | bash", linux, StringComparison.Ordinal);
+        Assert.EndsWith("/install?code=" + code + "' | zsh", macos, StringComparison.Ordinal);
+        Assert.StartsWith("irm '", windows, StringComparison.Ordinal);
+        Assert.EndsWith("/install.ps1?code=" + code + "' | iex", windows, StringComparison.Ordinal);
+        Assert.DoesNotContain("<", linux + macos + windows, StringComparison.Ordinal); // 没有要用户自己替换的占位符
+
+        // 脚本不需要登录（拿代码就是授权），不带缓存
+        using HttpResponseMessage sh = await _backend.Anonymous.GetAsync("/install?code=" + code);
+        string script = await sh.Content.ReadAsStringAsync();
+        Assert.Equal(HttpStatusCode.OK, sh.StatusCode);
+        Assert.Equal("no-store", sh.Headers.CacheControl?.ToString());
+        Assert.Contains($"ROLE='{role}'", script, StringComparison.Ordinal);
+        Assert.Contains($"CODE='{code}'", script, StringComparison.Ordinal);
+        Assert.Contains($"/moshiro-{role}:latest'", script, StringComparison.Ordinal);
+        Assert.Contains("SERVER='http", script, StringComparison.Ordinal);
+        Assert.DoesNotContain("@@", script, StringComparison.Ordinal);
+
+        using HttpResponseMessage ps = await _backend.Anonymous.GetAsync("/install.ps1?code=" + code);
+        string powershell = await ps.Content.ReadAsStringAsync();
+        Assert.Equal(HttpStatusCode.OK, ps.StatusCode);
+        Assert.Contains($"$role = '{role}'", powershell, StringComparison.Ordinal);
+        Assert.DoesNotContain("@@", powershell, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task Script_IsNotServedForUnknownRevokedOrUsedUpCodes()
+    {
+        foreach (string path in new[] { "/install", "/install?code=", "/install?code=jt_nope", "/install.ps1?code=jt_nope", "/install.sh?code=jt_nope" })
+        {
+            using HttpResponseMessage response = await _backend.Anonymous.GetAsync(path);
+            Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
+        }
+
+        JsonNode revoked = await CreateAsync("agent");
+        using HttpResponseMessage delete = await _backend.Admin.DeleteAsync("/api/admin/join-tokens/" + revoked["token"]!["id"]!.GetValue<string>());
+        Assert.True(delete.IsSuccessStatusCode);
+        using HttpResponseMessage gone = await _backend.Anonymous.GetAsync("/install?code=" + revoked["plaintext"]!.GetValue<string>());
+        Assert.Equal(HttpStatusCode.NotFound, gone.StatusCode);
+
+        // 用完了（一次性令牌已经注册过一个节点）
+        JsonNode used = await CreateAsync("probe");
+        string code = used["plaintext"]!.GetValue<string>();
+        using HttpResponseMessage before = await _backend.Anonymous.GetAsync("/install?code=" + code);
+        Assert.Equal(HttpStatusCode.OK, before.StatusCode);
+        await using (await MoShiro.TestSupport.AgentSimulator.EnrollAsync(_backend.Anonymous, code, _backend.UniqueName("used"))) { }
+        using HttpResponseMessage after = await _backend.Anonymous.GetAsync("/install?code=" + code);
+        Assert.Equal(HttpStatusCode.NotFound, after.StatusCode);
+    }
+}

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.sh", "/install.ps1"];
+            string[] roots = ["/healthz", "/metrics", "/install", "/install.ps1"];
             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))
             {