feat(ops): W4-B single-container packaging, DATA_DIR, backup/restore

- DATA_DIR (/data: agent-sessions, backups, exports, tmp); entrypoint chowns it
  to PUID/PGID then drops privileges via gosu; /app binary stays root read-only
- compile with --allow-read --allow-write so mounted library roots are writable
- preflight: DATA_DIR/session dir must be writable (fatal); enabled library
  roots and downloader path mappings checked read/write (warn + audit)
- --role export-mappings (mapping manifest JSON, --compare row counts) and
  --role read-only-on (automation.readOnlyReconcile=true + audit)
- scripts/backup.sh (pg_dump custom + mappings + agent sessions, SHA256SUMS,
  BACKUP_KEEP rotation) and scripts/restore.sh (checksum, refuses with live
  connections, psql single-transaction replay compatible with PG16, read-only
  reconcile on, row-count verification)
- compose: app + postgres only, data volume, env example with key generation
- docs: runbook deploy.md, backup-restore.md with verification record

Co-Authored-By: Claude Opus 5.5 <[email protected]>

apps/server/test/preflight.test.ts

@@ -1,10 +1,11 @@
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { DB, Kysely } from "@umt/db";
 import { afterAll, describe, expect, it } from "vitest";
-import { type Config, ConfigSchema } from "../src/config.ts";
-import { runPreflight } from "../src/preflight.ts";
+import { type Config, ConfigSchema, DATA_SUBDIRS, dataPaths } from "../src/config.ts";
+import { diffCounts } from "../src/ops.ts";
+import { checkStorage, runPreflight } from "../src/preflight.ts";
 
 const dir = mkdtempSync(join(tmpdir(), "umt-pre-"));
 afterAll(() => rmSync(dir, { recursive: true, force: true }));
@@ -45,3 +46,59 @@ describe("启动自检", () => {
     expect(await runPreflight({ config, db: fakeDb(true), uid: 1000 })).toEqual([]);
   });
 });
+
+describe("存储自检", () => {
+  it("DATA_DIR 缺省为 ./data,会话目录缺省在其下", () => {
+    const p = dataPaths(cfg({}), "/srv/app");
+    expect(p.dataDir).toBe("/srv/app/data");
+    expect(p.sessionDir).toBe("/srv/app/data/agent-sessions");
+    expect(dataPaths(cfg({ DATA_DIR: "/data", AGENT_SESSION_DIR: "/x/s" })).sessionDir).toBe("/x/s");
+  });
+
+  it("建数据子目录并探测可写;挂载路径不存在/不可写只告警", async () => {
+    const dataDir = join(dir, "data");
+    const ok = join(dir, "lib-ok");
+    const ro = join(dir, "lib-ro");
+    mkdirSync(ok);
+    mkdirSync(ro);
+    chmodSync(ro, 0o555);
+    const isRoot = Deno.uid() === 0;
+    const { problems, warnings } = await checkStorage({
+      dataDir,
+      sessionDir: join(dataDir, "agent-sessions"),
+      subdirs: DATA_SUBDIRS,
+      mounts: [
+        { kind: "library_root", id: "1", name: "ok", path: ok },
+        { kind: "library_root", id: "2", name: "ro", path: ro },
+        { kind: "path_mapping", id: "3", name: "/downloads", path: join(dir, "missing") },
+      ],
+    });
+    expect(problems).toEqual([]);
+    expect(readdirSync(dataDir).sort()).toEqual([...DATA_SUBDIRS].sort());
+    // 探针文件已删除
+    expect(readdirSync(ok)).toEqual([]);
+    expect(warnings.map((w) => w.id)).toEqual(isRoot ? ["3"] : ["2", "3"]);
+    chmodSync(ro, 0o755);
+  });
+
+  it("数据目录不可写 → problem", async () => {
+    if (Deno.uid() === 0) return; // root 无视权限位
+    const locked = join(dir, "locked");
+    mkdirSync(locked);
+    chmodSync(locked, 0o555);
+    const { problems } = await checkStorage({
+      dataDir: join(locked, "data"),
+      sessionDir: join(locked, "data", "agent-sessions"),
+      subdirs: DATA_SUBDIRS,
+      mounts: [],
+    });
+    expect(problems.every((p) => p.check === "data_dir")).toBe(true);
+    expect(problems.length).toBe(DATA_SUBDIRS.length);
+    chmodSync(locked, 0o755);
+  });
+
+  it("映射清单行数比对", () => {
+    expect(diffCounts({ a: 1, b: 2 }, { a: 1, b: 2 })).toEqual([]);
+    expect(diffCounts({ a: 1, b: 2 }, { a: 1, b: 3 })).toEqual([{ table: "b", expected: 2, actual: 3 }]);
+  });
+});