@namewta/speculo 1.0.7 → 1.0.8

package/template/workflows/ops/common/schemas/status.schema.json

@@ -194,6 +194,16 @@
       ],
       "additionalProperties": false
     },
+    "public_ingress": {
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "$ref": "#/$defs/public_ingress"
+        }
+      ]
+    },
     "updated_at": {
       "type": [
         "string",
@@ -290,6 +300,64 @@
           },
           "required": [],
           "additionalProperties": false
+        },
+        "host_services": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+                "maxLength": 80
+              },
+              "kind": {
+                "enum": [
+                  "wireguard",
+                  "nginx",
+                  "systemd",
+                  "probe",
+                  "other"
+                ]
+              },
+              "unit": {
+                "type": "string",
+                "minLength": 1
+              },
+              "listen_port": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              },
+              "listen": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "tunnel_address": {
+                "type": "string",
+                "minLength": 1
+              },
+              "config_path": {
+                "type": "string",
+                "minLength": 1
+              },
+              "public_url": {
+                "type": "string",
+                "minLength": 1
+              },
+              "notes": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id",
+              "kind"
+            ],
+            "additionalProperties": false
+          }
         }
       },
       "required": [
@@ -766,6 +834,80 @@
         "network"
       ],
       "additionalProperties": false
+    },
+    "public_ingress": {
+      "type": "object",
+      "properties": {
+        "schema_version": {
+          "const": 1
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "not_the_same_as": {
+          "type": "string"
+        },
+        "mappings": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "public": {
+                "type": "string",
+                "minLength": 1
+              },
+              "layer4": {
+                "type": "string"
+              },
+              "via": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "backend": {
+                "type": "string",
+                "minLength": 1
+              },
+              "backend_deployment": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "public",
+              "backend"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "open_http_checklist": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "forbidden_ports": {
+          "type": "array",
+          "items": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 65535
+          }
+        }
+      },
+      "required": [
+        "schema_version",
+        "title",
+        "path",
+        "mappings"
+      ],
+      "additionalProperties": false
     }
   }
 }

package/template/workflows/ops/common/service-profiles/elasticsearch.md

@@ -0,0 +1,13 @@
+# elasticsearch 服务档案
+
+提供者是独立 elasticsearch 项目（或用户选定的 kebab ID），`service_type` 用实际产品名，不伪装成内置分配 adapter。image 固定摘要。数据在 `data/elasticsearch/data`，日志在 `logs/elasticsearch`；容器内 data/logs 路径按所用镜像 VOLUME 显式 bind，禁止匿名卷。
+
+官方 Elasticsearch 8 会在启动时写 `elasticsearch.keystore`（临时文件 `elasticsearch.keystore.tmp`）。把 config/data/logs bind 到项目目录后：
+
+- 容器用户必须能写 data 与实际 keystore 目录；不要把 keystore 放进只读 config bind。
+- 仅当镜像仍必须写容器根文件系统时，才允许 `read_only: false`，并提供不少于 12 字符的 `writable_root_justification`。默认仍是只读根。
+- `config/` 与 `*.conf`/`*.yml` 默认文件模式 0644，供非 root 镜像用户读取；config/env bind 必须 `read_only: true`。
+
+生产健康检查不能只用 docker-proxy 上的 TCP。Compose 服务应声明 `healthcheck`；`compose --wait` 之后执行器要求 `State.Status=running`、非 OOMKilled/Restarting，若存在 Health 则必须 `healthy`。
+
+没有内置集群分配/账号 adapter。跨项目访问通过 existing + 实际授权探测，或专用 host/project 脚本；不能把「能 compose up」写成已具备逻辑资源恢复能力。备份使用该版本可验证的 snapshot/仓库工具；单 APP 回滚不得恢复整个集群。

package/template/workflows/ops/common/service-profiles/redis.md

@@ -2,6 +2,10 @@
 
 提供者独立 redis-main 项目，service_type=redis，service.compose_service 指向实际服务。数据在 data/redis/instance；ACL 文件配置为 data/redis/acl/users.acl（service.acl_persistence 必须完全匹配），容器 ACL 写入路径必须映射到这个项目数据目录，不能将 ACL SAVE 写到只读 config。
 
+`config/redis.conf` 以及 `*.acl` 默认文件模式 0644。Redis 镜像若以非 root 用户运行，0600 root 配置会导致 `can't open config file` 后重启循环。config bind 必须只读；可写数据只在 data/logs/run。不要为了读配置而把整个容器根改成可写。
+
 每个 APP 使用不同 ACL username、prefix 和凭据；禁用/限制危险管理命令，内置分配使用受限命令类别。必须核验真实客户端兼容性、ACL SAVE 和新账号认证。prefix/数字 DB 不等于独立内存/CPU/备份恢复边界；要求强隔离时部署专用实例。
 
+生产健康检查使用 redis-cli PING 或镜像 healthcheck，不能把 docker-proxy 的 TCP listen 当成进程可用。无 healthcheck 时 `compose --wait` 只表示容器已创建。
+
 持久化 AOF/RDB 属于业务数据不是可随意清理的日志。公共实例恢复影响所有消费者，需要整体维护批准。

package/template/workflows/ops/common/templates/CONTROLLER-RECORD.md

@@ -1,13 +1,27 @@
 # 部署机完整明文记录
 
-此文件是内容合同，不含真实密码；实际生成器依据成功回执填入真实值，不把占位符当交付。
+此文件是内容合同；控制端总册在策略启用时于表格单元格内保存真实账号密码，服务端 README 默认仍不写密码。
 
-## 主机与项目部署矩阵
+## 服务一览表
+
+主机、服务（含主机级入口）、访问地址、账号、密码、版本、最近部署时间、持久化目录。特殊字符逐字保留。路径使用 Markdown，不用 HTML `<code>`。
+
+## 公网访问内网
+
+当前映射行、四层条件、新开公网 HTTP 清单、禁止项。与 Clash/TUN 出口不是同一条连接。
+
+## 说明
+
+特别约束、启停、备份恢复。不把每个项目 README 全文拼进 FLEET / 主机 DEPLOYMENTS。
 
 ## 真实用户名、密码、访问密钥与用途
 
+表格单元格 + 项目 OPERATIONS；未知旧密码不能编造。密钥认证记录实际认证方式。
+
 ## 服务端配置和 README 镜像位置
 
+hosts/<host_id>/deployments/<id>/server-files 与 server/README。主机级入口：hosts/<id>/knowledge/host-services.json。
+
 ## 运行记录、局部失败/unknown、双边回执
 
 ## 业务数据备份实际位置，不声称仅记录配置就备份数据

package/template/workflows/ops/common/templates/HOST-README.md

@@ -4,8 +4,18 @@
 
 ## host_id、实际身份、host_root、更新 UTC 时间
 
-## 同级 APP 与公共服务表、最后验证版本、目录
+## 服务一览表
+
+主机、服务（含 APP / 共享服务 / WireGuard / Nginx / 探测单元）、访问地址、账号（服务端不写密码）、版本、最近验证时间、持久化或配置路径。未写入 host_services 或部署账本的入口下次交付不会出现。
+
+## 公网访问内网（若已登记 public_ingress）
+
+映射表、四层条件、新开公网 HTTP 服务步骤、禁止暴露的端口。入口与出口不是同一条连接。
+
+## 说明
+
+各主机级服务的 ListenPort / 隧道地址 / 配置路径 / 规范，以及 APP 备份恢复摘要。完整启停命令在项目 README，不把项目全文拼进主机总册。
 
 ## 通用规范、知识与部署总册索引
 
-## 系统问题、依赖影响、备份与恢复说明
+`docs/standards/DEPLOYMENT-STANDARD.md`；`knowledge/host-services.json`；`knowledge/public-ingress.json`；`DEPLOYMENTS.md`。

package/template/workflows/ops/common/tests/test_ops.mjs

@@ -13,6 +13,7 @@ import * as agent from "../tools/opslib/agent.mjs";
 import * as transport from "../tools/opslib/transport.mjs";
 import * as docs from "../tools/opslib/docs.mjs";
 import * as services from "../tools/opslib/services.mjs";
+import * as controlFiles from "../tools/opslib/control_files.mjs";
 import { initialize, analyze, cliHooks } from "../tools/opslib/cli.mjs";
 import { taskFiles } from "../tools/opslib/native_windows.mjs";
 
@@ -440,9 +441,16 @@ test("planner contracts", async (t) => {
     const [info] = fx.plan();
     assert.throws(() => execution.approval(fx.state, info.run_id, "0".repeat(64), "test", "explicit statement"), OpsError);
   });
-  await each("state drift blocks approval", (fx) => {
+  await each("unrelated host registration does not block approval", (fx) => {
     const [info] = fx.plan();
-    model.register(fx.state, {});
+    model.register(fx.state, { hosts: [{ ...fx.host, host_id: "node-b", display_name: "Node B", root: join(fx.tmp, "server-b") }] });
+    fx.approve(info);
+  });
+  await each("touched host catalog drift blocks approval", (fx) => {
+    const [info] = fx.plan();
+    const s = model.load(fx.state);
+    s.hosts["node-a"] = { ...s.hosts["node-a"], display_name: "Renamed" };
+    model.save(fx.state, s);
     assert.throws(() => fx.approve(info), OpsError);
   });
   await each("approval is immutable", (fx) => {
@@ -489,6 +497,81 @@ test("planner contracts", async (t) => {
   await each("compose rejects writable root", (fx) => {
     assert.throws(() => planner.composeModel({ compose: { services: { app: { image: "example@sha256:" + "a".repeat(64), read_only: false } } } }, fx.host, join(fx.target, "app-a"), "ops-app-a", {}, {}), OpsError);
   });
+  await each("compose allows justified writable root", (fx) => {
+    const [value] = planner.composeModel({
+      compose: {
+        services: {
+          app: {
+            image: "example@sha256:" + "a".repeat(64),
+            read_only: false,
+            writable_root_justification: "elasticsearch keystore tmp must be created at process start",
+          },
+        },
+      },
+    }, fx.host, join(fx.target, "app-a"), "ops-app-a", {}, {});
+    assert.equal(value.services.app.read_only, false);
+    assert.equal("writable_root_justification" in value.services.app, false);
+  });
+  await each("config files default to 0644", (fx) => {
+    const s = fx.spec();
+    s.deployments[0].files.push({ path: "config/redis.conf", content: "port 6379\n" });
+    const [, plan] = fx.plan(s);
+    const conf = plan.operations.find((o) => o.kind === "write" && String(o.path).replaceAll("\\", "/").endsWith("config/redis.conf"));
+    const env = plan.operations.find((o) => o.kind === "write" && String(o.path).replaceAll("\\", "/").includes("/env/"));
+    assert.equal(conf.mode, 0o644);
+    assert.equal(env.mode, 0o600);
+  });
+  await each("host write-file cannot overlay generated docs", (fx) => {
+    assert.throws(() => fx.plan({
+      schema_version: 1, worker: "H", operation: "prepare", reason: "test overlay",
+      rollback_note: "Retain generated host documentation.",
+      host_actions: [{ host_id: "node-a", kind: "write-file", reason: "Overwrite generated README", path: "README.md", content: "fake success" }],
+    }), OpsError);
+  });
+  await each("declared nginx control file is planned", (fx) => {
+    const [, plan] = fx.plan({
+      schema_version: 1, worker: "H", operation: "prepare", reason: "Persist reviewed nginx site",
+      rollback_note: "Restore previous nginx conf from backup copy.",
+      host_actions: [{
+        host_id: "node-a", kind: "write-control", reason: "Public ingress site for reviewed backend",
+        path: "/etc/nginx/conf.d/app.conf", content: "server { listen 57492; }\n",
+        rollback: "Restore /etc/nginx/conf.d/app.conf from the run backup.",
+        verification: [{ type: "command", argv: [process.execPath, "-e", "process.exit(0)"] }],
+      }],
+    });
+    assert.ok(plan.external_files["node-a"].includes("/etc/nginx/conf.d/app.conf"));
+    assert.equal(plan.operations.find((o) => o.path === "/etc/nginx/conf.d/app.conf").mode, 0o644);
+  });
+  await each("undeclared control path rejected", (fx) => {
+    assert.throws(() => fx.plan({
+      schema_version: 1, worker: "H", operation: "prepare", reason: "should fail",
+      rollback_note: "Do not write arbitrary system files.",
+      host_actions: [{ host_id: "node-a", kind: "write-control", reason: "not a control file", path: "/etc/passwd", content: "x\n" }],
+    }), OpsError);
+  });
+  await each("core systemd unit control rejected", (fx) => {
+    assert.throws(() => fx.plan({
+      schema_version: 1, worker: "H", operation: "prepare", reason: "should fail",
+      rollback_note: "Do not replace sshd unit files.",
+      host_actions: [{
+        host_id: "node-a", kind: "write-control", reason: "core unit forbidden",
+        path: "/etc/systemd/system/sshd.service", content: "[Unit]\n",
+        rollback: "Restore sshd.service from package.",
+        verification: [{ type: "command", argv: [process.execPath, "-e", "process.exit(0)"] }],
+      }],
+    }), OpsError);
+  });
+  await each("declared control file needs verification", (fx) => {
+    assert.throws(() => fx.plan({
+      schema_version: 1, worker: "H", operation: "prepare", reason: "should fail",
+      rollback_note: "Restore previous nginx conf from backup copy.",
+      host_actions: [{
+        host_id: "node-a", kind: "write-control", reason: "Public ingress site",
+        path: "/etc/nginx/nginx.conf", content: "http {}\n",
+        rollback: "Restore nginx.conf from backup.",
+      }],
+    }), OpsError);
+  });
   await each("compose safe persistence model", (fx) => {
     const [value] = planner.composeModel({ compose: { services: { app: { image: "example@sha256:" + "a".repeat(64), volumes: [{ type: "bind", source: "data/app/storage", target: "/data" }] } } } }, fx.host, join(fx.target, "app-a"), "ops-app-a", { "app.env": {} }, {});
     assert.equal(value.services.app.read_only, true);
@@ -737,6 +820,8 @@ test("ssh contract", () => {
     assert.ok(captured.argv.includes("BatchMode=yes"));
     assert.ok(!joined.includes(PASSWORD));
     assert.ok(captured.argv.includes("UserKnownHostsFile=" + kh));
+    assert.ok(Buffer.isBuffer(captured.input));
+    assert.equal(captured.encoding, "buffer");
   } finally { transport.transportHooks.spawnSync = prev; rmSync(d, { recursive: true, force: true }); }
 });
 
@@ -750,3 +835,148 @@ test("knownhosts digest drift", () => {
   assert.notEqual(before, transport.hostTransportDigest(h));
   rmSync(d, { recursive: true, force: true });
 });
+
+test("command keeps raw docker json when secrets appear", () => {
+  const fx = agentFixture();
+  try {
+    const secret = "1234";
+    const json = JSON.stringify({ State: { Status: "running" }, Env: ["MYSQL_ROOT_PASSWORD=" + secret] });
+    const prev = agent.agentHooks.spawnSync;
+    agent.agentHooks.spawnSync = () => ({ status: 0, stdout: Buffer.from(json), stderr: Buffer.alloc(0) });
+    try {
+      const r = agent.command(["docker", "inspect", "x"], { cwd: fx.root, secrets: [secret] });
+      assert.equal(JSON.parse(r.stdout).Env[0], "MYSQL_ROOT_PASSWORD=" + secret);
+      assert.ok(!r.log_stdout.includes(secret));
+      assert.equal(agent.parseDockerJson(r.stdout, "inspect").State.Status, "running");
+    } finally { agent.agentHooks.spawnSync = prev; }
+  } finally { fx.cleanup(); }
+});
+
+test("command stdin is buffer with encoding buffer", () => {
+  const fx = agentFixture();
+  try {
+    const captured = {};
+    const prev = agent.agentHooks.spawnSync;
+    agent.agentHooks.spawnSync = (_cmd, _args, kw) => {
+      Object.assign(captured, kw);
+      return { status: 0, stdout: Buffer.from("ok"), stderr: Buffer.alloc(0) };
+    };
+    try {
+      agent.command(["echo"], { cwd: fx.root, stdin: "hello" });
+      assert.ok(Buffer.isBuffer(captured.input));
+      assert.equal(captured.input.toString("utf8"), "hello");
+      assert.equal(captured.encoding, "buffer");
+    } finally { agent.agentHooks.spawnSync = prev; }
+  } finally { fx.cleanup(); }
+});
+
+test("inspect container gate requires running healthy", () => {
+  agent.inspectContainerGate({ Name: "/ok", State: { Status: "running" } });
+  agent.inspectContainerGate({ Name: "/okh", State: { Status: "running", Health: { Status: "healthy" } } });
+  assert.throws(() => agent.inspectContainerGate({ Name: "/exited", State: { Status: "exited" } }), agent.Failure);
+  assert.throws(() => agent.inspectContainerGate({ Name: "/oom", State: { Status: "running", OOMKilled: true } }), agent.Failure);
+  assert.throws(() => agent.inspectContainerGate({ Name: "/restart", State: { Status: "running", Restarting: true } }), agent.Failure);
+  assert.throws(() => agent.inspectContainerGate({ Name: "/starting", State: { Status: "running", Health: { Status: "starting" } } }), agent.Failure);
+});
+
+test("control file helpers", () => {
+  assert.equal(controlFiles.isBuiltinControlPath("/etc/docker/daemon.json"), true);
+  assert.equal(controlFiles.isDeclaredControlPath("/etc/nginx/conf.d/app.conf"), true);
+  assert.equal(controlFiles.isDeclaredControlPath("/etc/wireguard/wg0.conf"), true);
+  assert.equal(controlFiles.defaultFileMode("config/redis.conf"), 0o644);
+  assert.equal(controlFiles.defaultFileMode("env/app.env"), 0o600);
+  assert.throws(() => controlFiles.assertSafeControlPath("/etc/shadow"), OpsError);
+  assert.throws(() => controlFiles.assertSafeControlPath("/etc/systemd/system/sshd.service", { reason: "reviewed unit", rollback: "restore package unit" }), OpsError);
+});
+
+test("disjoint host plans apply sequentially", () => runFx((fx) => {
+  model.register(fx.state, { hosts: [{ ...fx.host, host_id: "node-b", display_name: "Node B", root: join(fx.tmp, "server-b") }] });
+  const specA = {
+    schema_version: 1, worker: "H", operation: "maintain", hosts: ["node-a"], reason: "Host A cache fixture",
+    rollback_note: "Keep isolated cache until a separate purge is approved.",
+    host_actions: [{ host_id: "node-a", kind: "write-file", reason: "Create only fixture cache A", path: "_host/cache/a/cache.txt", content: "A" }],
+  };
+  const specB = {
+    schema_version: 1, worker: "H", operation: "maintain", hosts: ["node-b"], reason: "Host B cache fixture",
+    rollback_note: "Keep isolated cache until a separate purge is approved.",
+    host_actions: [{ host_id: "node-b", kind: "write-file", reason: "Create only fixture cache B", path: "_host/cache/b/cache.txt", content: "B" }],
+  };
+  const [infoA] = fx.plan(specA);
+  const [infoB] = fx.plan(specB);
+  fx.approve(infoA);
+  fx.approve(infoB);
+  const rB = execution.apply(fx.state, infoB.run_id);
+  assert.equal(rB.status, "completed", JSON.stringify(rB));
+  const rA = execution.apply(fx.state, infoA.run_id);
+  assert.equal(rA.status, "completed", JSON.stringify(rA));
+  assert.equal(readFileSync(join(fx.target, "_host", "cache", "a", "cache.txt"), "utf8"), "A");
+  assert.equal(readFileSync(join(fx.tmp, "server-b", "_host", "cache", "b", "cache.txt"), "utf8"), "B");
+}));
+
+test("host and fleet handbooks are markdown service tables", () => runFx((fx) => {
+  const s = fx.graph();
+  s.hosts["node-a"].host_services = [{
+    id: "wg0", kind: "wireguard", unit: "wg-quick@wg0", listen_port: 51820,
+    tunnel_address: "10.77.0.2/24", config_path: "/etc/wireguard/wg0.conf",
+    notes: "入口隧道，不是 Clash 出口",
+  }, {
+    id: "nginx-public", kind: "nginx", unit: "nginx.service", listen_port: 57492,
+    public_url: "http://203.0.113.10:57492/", config_path: "/etc/nginx/conf.d/app.conf",
+  }];
+  s.public_ingress = {
+    schema_version: 1, title: "公网访问内网", path: "knowledge/public-ingress.json",
+    not_the_same_as: "Clash TUN 是出口",
+    mappings: [{ public: "http://203.0.113.10:57492/", layer4: "57492/tcp", via: ["nginx-public", "wg0"], backend: "10.77.0.2:8080" }],
+    open_http_checklist: ["在入口主机增加 Nginx listen", "更新 WG AllowedIPs"],
+    forbidden_ports: [22, 3306],
+  };
+  const fleet = docs.fleetDocument(s, ["node-a"], "run-test", now(), { ledger: model.ledgerLoad(fx.state), includeCredentials: true });
+  const server = docs.hostReadme(s, "node-a", "run-test", now(), { full: true });
+  for (const text of [fleet, server, docs.code("/srv/ops")]) {
+    assert.ok(!text.includes("<code>"));
+    assert.ok(!text.includes("<br>"));
+  }
+  assert.ok(fleet.includes("服务一览"));
+  assert.ok(fleet.includes("说明"));
+  assert.ok(fleet.includes("公网访问内网"));
+  assert.ok(fleet.includes("10.77.0.2:8080"));
+  assert.ok(fleet.includes("wg-quick@wg0"));
+  assert.ok(fleet.includes("新开公网 HTTP"));
+  assert.ok(fleet.includes(PASSWORD));
+  assert.ok(!server.includes(PASSWORD));
+  assert.ok(server.includes("服务一览"));
+  assert.ok(docs.hostServicesDocument(s.hosts["node-a"]).includes("wg0"));
+}));
+
+test("host services and public ingress are delivered", () => runFx((fx) => {
+  const host = { ...fx.host, host_services: [{
+    id: "wg0", kind: "wireguard", unit: "wg-quick@wg0", listen_port: 51820,
+    tunnel_address: "10.77.0.2/24", config_path: "/etc/wireguard/wg0.conf",
+  }] };
+  const spec = {
+    schema_version: 1, worker: "H", operation: "maintain", hosts: ["node-a"],
+    reason: "Record host ingress ledger",
+    rollback_note: "Keep previous host-services ledger until a new plan replaces it.",
+    resource_updates: { hosts: [host] },
+    public_ingress: {
+      schema_version: 1, title: "公网访问内网", path: "knowledge/public-ingress.json",
+      mappings: [{ public: "http://203.0.113.10:57492/", layer4: "57492/tcp", via: ["wg0"], backend: "10.77.0.2:8080" }],
+      open_http_checklist: ["更新 Nginx 与 WG", "刷新 public-ingress.json"],
+      forbidden_ports: [22],
+    },
+    host_actions: [{ host_id: "node-a", kind: "write-file", reason: "Create only fixture cache", path: "_host/cache/demo/cache.txt", content: "cache" }],
+  };
+  const [, , r] = fx.runSpec(spec);
+  assert.equal(r.status, "completed", JSON.stringify(r));
+  const catalog = model.load(fx.state);
+  assert.equal(catalog.hosts["node-a"].host_services[0].id, "wg0");
+  assert.equal(catalog.public_ingress.mappings[0].backend, "10.77.0.2:8080");
+  const remoteServices = readJson(join(fx.target, "knowledge", "host-services.json"));
+  assert.equal(remoteServices.services[0].unit, "wg-quick@wg0");
+  const remoteIngress = readJson(join(fx.target, "knowledge", "public-ingress.json"));
+  assert.ok(remoteIngress.mappings[0].public.includes("57492"));
+  const fleet = readFileSync(join(fx.state, "FLEET-DEPLOYMENTS.md"), "utf8");
+  assert.ok(fleet.includes("服务一览"));
+  assert.ok(fleet.includes("公网访问内网"));
+  assert.ok(!fleet.includes("<code>"));
+}));

package/template/workflows/ops/common/tools/opslib/agent.mjs

@@ -288,9 +288,6 @@ function under(path, root, allowRoot = false) {
 
 function checkedPath(path, req, allowRoot = false) {
   if ((req.external_files ?? []).includes(path)) {
-    if (path !== "/etc/docker/daemon.json" && !/^\/etc\/systemd\/system\/ops-[a-z0-9-]+\.service$/.test(path)) {
-      throw new Failure("unrecognized external control file");
-    }
     noLinks(path);
     return resolve(path);
   }
@@ -304,7 +301,14 @@ export function stripSecrets(text, values) {
   return text.replace(/(password|passwd|token|secret|access_key)(\s*[=:]\s*)[^\s,;]+/gi, "$1$2[REDACTED]");
 }
 
-function command(argv, { cwd, env = null, stdin = null, timeout = 300, secrets = null, success_codes = null } = {}) {
+export const agentHooks = { spawnSync };
+
+function stdinBuffer(stdin) {
+  if (stdin == null) return undefined;
+  return Buffer.isBuffer(stdin) ? stdin : Buffer.from(String(stdin), "utf8");
+}
+
+export function command(argv, { cwd, env = null, stdin = null, timeout = 300, secrets = null, success_codes = null } = {}) {
   if (!Array.isArray(argv) || !argv.length || !argv.every((x) => typeof x === "string" && !x.includes("\0"))) {
     throw new Failure("argv must be a nonempty string array");
   }
@@ -313,10 +317,11 @@ function command(argv, { cwd, env = null, stdin = null, timeout = 300, secrets =
   mkdir(runTmp, 0o700);
   const outPath = join(runTmp, "out.bin"), errPath = join(runTmp, "err.bin");
   try {
-    const p = spawnSync(argv[0], argv.slice(1), {
+    // Node 24: encoding "buffer" with a string input throws ERR_UNKNOWN_ENCODING.
+    const p = agentHooks.spawnSync(argv[0], argv.slice(1), {
       cwd,
       env: { ...process.env, ...(env || {}), TMPDIR: runTmp, TMP: runTmp, TEMP: runTmp },
-      input: stdin != null ? stdin : undefined,
+      input: stdinBuffer(stdin),
       timeout: timeout * 1000,
       maxBuffer: 32 * 1024 * 1024,
       encoding: "buffer",
@@ -326,14 +331,18 @@ function command(argv, { cwd, env = null, stdin = null, timeout = 300, secrets =
     if (p.error) throw new Failure(String(p.error.message || p.error));
     const rawOut = (p.stdout || Buffer.alloc(0)).subarray(0, 2 * 1024 * 1024);
     const rawErr = (p.stderr || Buffer.alloc(0)).subarray(0, 2 * 1024 * 1024);
+    const stdout = rawOut.toString("utf8");
+    const stderr = rawErr.toString("utf8");
     const result = {
       exit_code: p.status,
-      stdout: stripSecrets(rawOut.toString("utf8"), values),
-      stderr: stripSecrets(rawErr.toString("utf8"), values),
+      stdout,
+      stderr,
+      log_stdout: stripSecrets(stdout, values),
+      log_stderr: stripSecrets(stderr, values),
       output_sha256: sha(Buffer.concat([rawOut, rawErr])),
     };
     if (!(success_codes || [0]).includes(p.status)) {
-      throw new Failure("command failed with exit=" + p.status + "; output_sha256=" + result.output_sha256);
+      throw new Failure("command failed with exit=" + p.status + "; output_sha256=" + result.output_sha256 + "; " + result.log_stderr.slice(-1500));
     }
     return result;
   } finally {
@@ -343,6 +352,27 @@ function command(argv, { cwd, env = null, stdin = null, timeout = 300, secrets =
   }
 }
 
+function parseDockerJson(text, label) {
+  try {
+    return JSON.parse(String(text).trim());
+  } catch (e) {
+    throw new Failure(label + " is not valid JSON: " + (e.message || e));
+  }
+}
+
+export { parseDockerJson };
+
+export function inspectContainerGate(item) {
+  const st = item.State || {};
+  const name = item.Name || item.Id || "unknown";
+  if (st.Status !== "running" || st.OOMKilled || st.Restarting) {
+    throw new Failure("container not running after compose-up: " + name + " status=" + (st.Status || "unknown"));
+  }
+  if (st.Health && st.Health.Status && st.Health.Status !== "healthy") {
+    throw new Failure("container health is " + st.Health.Status + " after compose --wait; TCP/proxy listen is not sufficient");
+  }
+}
+
 function dockerBase(op) {
   const cmd = [op.docker || "docker"];
   if (op.context) cmd.push("--context", op.context);
@@ -357,7 +387,7 @@ function composeUp(op, req) {
   const base = composeBase(op);
   const docker = dockerBase(op);
   const info = command(docker.concat(["info", "--format", "{{json .}}"]), { cwd: root, timeout: 30, secrets: req.secrets || [] });
-  const daemon = JSON.parse(info.stdout.trim());
+  const daemon = parseDockerJson(info.stdout, "docker info");
   if (daemon.ID !== op.expected_docker_id) throw new Failure("Docker daemon identity changed since approval");
   const actual = daemon.DockerRootDir;
   if (req.strict_docker_root !== false) {
@@ -375,7 +405,7 @@ function composeUp(op, req) {
   for (const [name, service] of Object.entries(model.services)) {
     const image = service.image || op.compose_name + "-" + name;
     const conf = command(docker.concat(["image", "inspect", image, "--format", "{{json .Config.Volumes}}"]), { cwd: root, timeout: 30, secrets: req.secrets || [] });
-    const declared = JSON.parse(conf.stdout.trim()) || {};
+    const declared = parseDockerJson(conf.stdout, "image volumes for " + image) || {};
     const mapped = new Set([...(service.volumes || []).map((v) => v.target), ...(service.tmpfs || [])]);
     const missing = Object.keys(declared).filter((k) => !mapped.has(k));
     if (missing.length) throw new Failure("image declares unmapped VOLUME(s), refusing anonymous persistence: " + JSON.stringify(missing.sort()));
@@ -384,7 +414,8 @@ function composeUp(op, req) {
   const ids = command(base.concat(["ps", "--all", "--quiet"]), { cwd: root, timeout: 30 }).stdout.split(/\s+/).filter(Boolean);
   if (!ids.length) throw new Failure("Compose returned no containers");
   for (const cid of ids) {
-    const item = JSON.parse(command(docker.concat(["inspect", cid]), { cwd: root, timeout: 30, secrets: req.secrets || [] }).stdout)[0];
+    const item = parseDockerJson(command(docker.concat(["inspect", cid]), { cwd: root, timeout: 30, secrets: req.secrets || [] }).stdout, "docker inspect")[0];
+    inspectContainerGate(item);
     for (const mount of item.Mounts || []) {
       if (mount.Type === "volume") throw new Failure("anonymous/named persistence detected after start; stop and reconcile");
       if (mount.Type === "bind") under(mount.Source, root);
@@ -403,7 +434,7 @@ function allocation(op, req) {
   checkId(aid);
   const marker = join(provider, "allocations", aid + ".json");
   if (op.compose_name) {
-    const info = JSON.parse(command(dockerBase(op).concat(["info", "--format", "{{json .}}"]), { cwd: provider, timeout: 30 }).stdout);
+    const info = parseDockerJson(command(dockerBase(op).concat(["info", "--format", "{{json .}}"]), { cwd: provider, timeout: 30 }).stdout, "provider docker info");
     if (info.ID !== op.expected_docker_id) throw new Failure("provider Docker daemon identity drift");
   }
   const ownership = {