backupdrill 2.3.0 → 2.4.0

package/dist/backup.d.ts

@@ -1,5 +1,9 @@
 import type { BackupConfig } from "./config.js";
+import { type SnapshotStore } from "./snapshot-store.js";
 import type { Manifest } from "./manifest.js";
 import { parsePgDumpMajor } from "./pgbin.js";
 export { parsePgDumpMajor };
-export declare function runBackup(config: BackupConfig): Promise<Manifest>;
+export declare function runBackup(config: BackupConfig, opts?: {
+    /** 快照写到哪;省略 = config.storage 指的 S3 兼容桶 */
+    store?: SnapshotStore;
+}): Promise<Manifest>;

package/dist/backup.js

@@ -2,18 +2,15 @@ import { spawn, execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { Transform } from "node:stream";
 import { promisify } from "node:util";
-import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
-import { Upload } from "@aws-sdk/lib-storage";
+import { s3SnapshotStore } from "./snapshot-store.js";
 import { MANIFEST_SCHEMA_VERSION } from "./manifest.js";
 import { syncStorage } from "./storage.js";
 import { inspectBucketAttrs } from "./storage-catalog.js";
-import { renderRecoveryDoc } from "./recovery-doc.js";
 import { projectRefOf, refFromStorageEndpoint, assertNoHostOverride } from "./restore-engine.js";
 import { log } from "./log.js";
 import { TOOL_VERSION } from "./version.js";
 import { parsePgDumpMajor } from "./pgbin.js";
 import { relationBytes } from "./estimate.js";
-import { dumpPartSizeFor } from "./part-size.js";
 // 解析函数搬到了 pgbin(演练与恢复都要读 pg_restore 版本,放这里会成环);保留旧出口
 export { parsePgDumpMajor };
 import { dumpUrlFor, connectPg, isSupabaseHost } from "./supabase-ca.js";
@@ -93,8 +90,8 @@ async function inspectDatabase(databaseUrl, schemas) {
         await client.end();
     }
 }
-/** 流式跑 pg_dump,边写 S3 边算 sha256 与字节数。返回校验和与大小。 */
-async function dumpToS3(config, s3, key, pgDumpBin, partSize) {
+/** 流式跑 pg_dump,边写快照边算 sha256 与字节数。返回校验和与大小。 */
+async function dumpToSnapshot(config, writer, pgDumpBin, dumpRelationBytes) {
     const hash = createHash("sha256");
     let bytes = 0;
     const meter = new Transform({
@@ -136,33 +133,26 @@ async function dumpToS3(config, s3, key, pgDumpBin, partSize) {
             ? resolve()
             : reject(new Error(`pg_dump exited with code ${code}: ${stderr.trim()}`)));
     });
-    const upload = new Upload({
-        client: s3,
-        partSize,
-        params: {
-            Bucket: config.storage.bucket,
-            Key: key,
-            Body: meter,
-            ContentType: "application/octet-stream",
-        },
-    });
-    const uploadDone = upload.done();
     // 失败双向联动:dump 失败要中止上传(绝不把半截转储当成功);上传失败也必须
     // 杀掉 pg_dump —— 否则上传侧停止消费后,背压会让 pg_dump 永远阻塞在 stdout
     // 写入上,调用方(worker 的串行队列)随之永久挂起。Promise.all 会订阅两侧,
     // 先失败的一方抛出后,另一方稍后的 rejection 也已被视为 handled。
+    // 开始上传也放进 try:实现可能在建上传时就同步抛错,那时 pg_dump 已经在跑,同样要杀掉。
+    let upload = null;
     try {
-        await Promise.all([dumpDone, uploadDone]);
+        upload = writer.uploadDump(meter, dumpRelationBytes);
+        await Promise.all([dumpDone, upload.done]);
     }
     catch (error) {
+        dumpDone.catch(() => { }); // 没走到 Promise.all 时,被杀的 pg_dump 的退出也得有人接住
         dump.kill("SIGKILL");
         meter.destroy();
-        await upload.abort().catch(() => { });
+        await upload?.abort().catch(() => { });
         throw error;
     }
     return { bytes, sha256: hash.digest("hex") };
 }
-export async function runBackup(config) {
+export async function runBackup(config, opts = {}) {
     // 源身份先于一切传输(评审第 12 轮):①连接串不许带 ?host=/user= 覆盖——否则
     // 快照记的 ref 与实际读取对象脱节,恢复端的同源保护随之失真;②库与 Storage
     // 跨项目 = 配置错误,全量 dump+同步之后才发现会白烧 egress 还留下半截快照前缀
@@ -190,29 +180,26 @@ export async function runBackup(config) {
             `pg_dump must be >= the server major version. Install postgresql-client-${serverMajor} ` +
             `(or newer) and/or point BACKUPDRILL_PG_DUMP at it.`);
     }
-    const s3 = new S3Client({
-        region: config.storage.region,
-        endpoint: config.storage.endpoint,
-        forcePathStyle: config.storage.forcePathStyle,
-        credentials: {
-            accessKeyId: config.storage.accessKeyId,
-            secretAccessKey: config.storage.secretAccessKey,
-        },
-    });
+    const store = opts.store ?? s3SnapshotStore(config);
     const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-    const base = `${config.storage.prefix}/${config.projectName}/${timestamp}`;
-    const dumpKey = `${base}/dump.pgcustom`;
-    log.step(`Dumping → s3://${config.storage.bucket}/${dumpKey}`);
-    const { bytes, sha256 } = await dumpToS3(config, s3, dumpKey, pgDumpBin, dumpPartSizeFor(db.relationBytes));
+    const writer = await store.createSnapshot(timestamp);
+    const storageFiles = writer.storageFiles;
+    // 在转储之前拦下:目标放不了 Storage 文件却配了 Storage,转储完才发现等于白跑一遍
+    if (config.supabaseStorage && !storageFiles) {
+        throw new Error("Storage file backup needs an S3-compatible bucket; this backup destination only holds the database.");
+    }
+    const dumpKey = writer.dumpKey;
+    log.step(`Dumping → ${writer.describe("dump.pgcustom")}`);
+    const { bytes, sha256 } = await dumpToSnapshot(config, writer, pgDumpBin, db.relationBytes);
     log.ok(`Database dumped (${(bytes / 1024 / 1024).toFixed(1)} MB, sha256 ${sha256.slice(0, 12)}…)`);
     // Storage 文件同步(源配置存在才做;否则只备数据库)
     let storageResult = null;
-    if (config.supabaseStorage) {
+    if (config.supabaseStorage && storageFiles) {
         log.step("Syncing Storage files…");
         const synced = await syncStorage(config.supabaseStorage, {
-            client: s3,
-            bucket: config.storage.bucket,
-            base, // syncStorage 内部会加 /storage/<bucket>/<key>
+            client: storageFiles.s3,
+            bucket: storageFiles.bucket,
+            base: storageFiles.base, // syncStorage 内部会加 /storage/<bucket>/<key>
         });
         // v2 bucket 属性采集,通道 = 已有的只读库连接(per-file 元数据已随 GetObject
         // 响应在 syncStorage 内原子捕获)。失败只降级不报错:storage schema 读不到
@@ -257,26 +244,9 @@ export async function runBackup(config) {
     // RECOVERY.md(PRD §5.9.2.1)先于 manifest 落桶:manifest 是快照的"完成标记"
     // (演练/恢复按它找快照)——先写手册再写标记,"快照完成"就蕴含"手册在场";
     // 手册写失败 = 备份失败(同桶同权限,与 manifest 自身的写入风险一致)。
-    await s3.send(new PutObjectCommand({
-        Bucket: config.storage.bucket,
-        Key: `${base}/RECOVERY.md`,
-        Body: renderRecoveryDoc(manifest, {
-            snapshot: timestamp,
-            bucket: config.storage.bucket,
-            endpoint: config.storage.endpoint,
-            region: config.storage.region,
-            prefix: config.storage.prefix,
-            projectName: config.projectName,
-        }),
-        ContentType: "text/markdown",
-    }));
-    log.ok(`Recovery runbook written → s3://${config.storage.bucket}/${base}/RECOVERY.md`);
-    await s3.send(new PutObjectCommand({
-        Bucket: config.storage.bucket,
-        Key: `${base}/manifest.json`,
-        Body: JSON.stringify(manifest, null, 2),
-        ContentType: "application/json",
-    }));
-    log.ok(`Manifest written → s3://${config.storage.bucket}/${base}/manifest.json`);
+    await writer.writeRecoveryDoc(manifest);
+    log.ok(`Recovery runbook written → ${writer.describe("RECOVERY.md")}`);
+    await writer.writeManifest(manifest);
+    log.ok(`Manifest written → ${writer.describe("manifest.json")}`);
     return manifest;
 }

package/dist/config.d.ts

@@ -26,9 +26,15 @@ export interface BackupConfig {
     databaseUrl: string;
     projectName: string;
     schemas: string[];
-    storage: StorageConfig;
+    storage?: StorageConfig;
     supabaseStorage?: SupabaseStorageConfig;
 }
+/** CLI 读出来的配置一定带桶:loadConfig 缺了桶直接报错,所以返回类型里 storage 是必填 */
+export type LoadedBackupConfig = BackupConfig & {
+    storage: StorageConfig;
+};
+/** 需要桶的地方先过这一道:没配桶时给一句能看懂的报错,而不是读 undefined 的属性。 */
+export declare function requireBucket(config: BackupConfig): StorageConfig;
 interface RawConfig {
     databaseUrl?: string;
     projectName?: string;
@@ -40,5 +46,5 @@ interface RawConfig {
 export declare function loadConfig(opts: {
     configPath: string;
     overrides: RawConfig;
-}): Promise<BackupConfig>;
+}): Promise<LoadedBackupConfig>;
 export {};

package/dist/config.js

@@ -1,4 +1,11 @@
 import { readFile } from "node:fs/promises";
+/** 需要桶的地方先过这一道:没配桶时给一句能看懂的报错,而不是读 undefined 的属性。 */
+export function requireBucket(config) {
+    if (!config.storage) {
+        throw new Error("No S3-compatible bucket configured (storage) — set storage.bucket and its keys.");
+    }
+    return config.storage;
+}
 function fromEnv() {
     const env = process.env;
     const storage = {};

package/dist/drill.d.ts

@@ -1,5 +1,6 @@
 import type { BackupConfig } from "./config.js";
 import type { Manifest } from "./manifest.js";
+import { type SnapshotStore } from "./snapshot-store.js";
 /**
  * 无放回随机抽样:部分 Fisher-Yates,只洗出前 n 位(O(n) 次交换,不必全 shuffle)。
  * 此前恒取 manifest 顺序的前 CAP 个 → 超过 CAP 的项目里排序靠后的文件永远不被校验;
@@ -92,5 +93,7 @@ export declare function runDrill(config: BackupConfig, opts?: {
     appCheckCommand?: string;
     keepSandboxOnFailure?: boolean;
     supervision?: DrillSupervision;
+    /** 快照从哪读;省略 = config.storage 指的 S3 兼容桶 */
+    store?: SnapshotStore;
 }): Promise<DrillReport>;
 export {};

package/dist/drill.js

@@ -4,7 +4,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import { parseManifest } from "./manifest.js";
-import { targetClient, resolveSnapshot, getObjectText, downloadToFile, hashObject, } from "./snapshots.js";
+import { hashObject } from "./snapshots.js";
+import { s3SnapshotStore } from "./snapshot-store.js";
 import { SANDBOX_MANAGED_ERROR, classifyBlocks, finalizePass, installExtensions, quoteIdent, restoreDatabaseArtifact, installSandboxShim, } from "./restore-engine.js";
 import { connectPg } from "./supabase-ca.js";
 import { localPgRestoreMajor, restoreToolBreaksOnTarget, sandboxMajorFor } from "./pgbin.js";
@@ -329,16 +330,15 @@ export async function verifyRestored(connString, manifest) {
  * Storage 完整性校验:从备份桶重新读回文件、比对 manifest 里记录的 sha256,
  * 证明备份的文件副本真实存在且未损坏。文件多时抽样(默认上限),避免大量 egress。
  */
-async function verifyStorage(s3, config, manifest, verifyAll) {
+async function verifyStorage(location, manifest, verifyAll) {
     const files = manifest.storage.files;
     const sample = verifyAll ? files : sampleStorageFiles(files, STORAGE_SAMPLE_CAP);
-    // 备份写入时的键:<snapshot base>/storage/<bucket>/<key>,base 从 dump.key 反推
-    const base = manifest.dump.key.replace(/\/dump\.pgcustom$/, "");
+    // 备份写入时的键:<snapshot base>/storage/<bucket>/<key>
     const mismatches = [];
     for (const f of sample) {
-        const objectKey = `${base}/storage/${f.bucket}/${f.key}`;
+        const objectKey = `${location.base}/storage/${f.bucket}/${f.key}`;
         try {
-            const { sha256 } = await hashObject(s3, config.storage.bucket, objectKey);
+            const { sha256 } = await hashObject(location.s3, location.bucket, objectKey);
             if (sha256 !== f.sha256)
                 mismatches.push(`${f.bucket}/${f.key}`);
         }
@@ -569,17 +569,17 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], op
 /** 演练一份快照:从桶里下载→drillDump(含 Storage 校验)→报告。 */
 export async function runDrill(config, opts = {}) {
     validateSupervision(opts.supervision, opts.appCheckCommand, opts.keepSandboxOnFailure);
-    const s3 = targetClient(config);
-    const snapshotPrefix = await resolveSnapshot(s3, config, opts.snapshot);
-    const snapshot = snapshotPrefix.replace(/\/$/, "").split("/").pop();
+    const store = opts.store ?? s3SnapshotStore(config);
+    const reader = await store.openSnapshot(opts.snapshot);
+    const snapshot = reader.name;
     log.step(`Drilling snapshot ${snapshot}`);
-    const manifest = parseManifest(await getObjectText(s3, config.storage.bucket, `${snapshotPrefix}manifest.json`));
+    const manifest = parseManifest(await reader.readManifest());
     const workdir = opts.supervision?.workdir ?? await mkdtemp(join(tmpdir(), "backupdrill-"));
     const dumpPath = join(workdir, "dump.pgcustom");
     try {
         await opts.supervision?.observe({ phase: "download", dumpBytes: manifest.dump.bytes });
         log.step("Downloading dump…");
-        const { sha256: sha } = await downloadToFile(s3, config.storage.bucket, manifest.dump.key, dumpPath);
+        const { sha256: sha } = await reader.downloadDump(manifest, dumpPath);
         const integrityPass = sha === manifest.dump.sha256;
         const preChecks = [
             {
@@ -605,7 +605,14 @@ export async function runDrill(config, opts = {}) {
         if (manifest.storage && manifest.storage.files.length) {
             await opts.supervision?.observe({ phase: "storage" });
             log.step("Verifying Storage files…");
-            preChecks.push(await verifyStorage(s3, config, manifest, opts.verifyAllFiles ?? false));
+            const location = reader.storageFiles(manifest);
+            preChecks.push(location
+                ? await verifyStorage(location, manifest, opts.verifyAllFiles ?? false)
+                : {
+                    name: "storage file integrity",
+                    pass: false,
+                    detail: "the manifest lists Storage files, but this snapshot location cannot hold them",
+                });
         }
         return await drillDump(dumpPath, manifest, snapshot, preChecks, {
             appCheckCommand: opts.appCheckCommand,

package/dist/lib.d.ts

@@ -5,9 +5,11 @@ export { runRestore } from "./restore.js";
 export { projectRefOf, assertNoHostOverride, libpqChildEnv } from "./restore-engine.js";
 export { sameDatabaseTarget } from "./restore.js";
 export { runEstimate, project } from "./estimate.js";
-export { loadConfig } from "./config.js";
+export { loadConfig, requireBucket } from "./config.js";
 export { targetClient, resolveSnapshot, getObjectText, downloadToFile, hashObject, } from "./snapshots.js";
-export type { BackupConfig, StorageConfig, SupabaseStorageConfig, } from "./config.js";
+export { s3SnapshotStore } from "./snapshot-store.js";
+export type { SnapshotStore, SnapshotWriter, SnapshotReader, DumpUpload, StorageFilesLocation, } from "./snapshot-store.js";
+export type { BackupConfig, LoadedBackupConfig, StorageConfig, SupabaseStorageConfig, } from "./config.js";
 export type { BucketAttrs, ExtensionInfo, Manifest, StorageFile, TableStat } from "./manifest.js";
 export type { DrillReport, DrillCheck, DrillSupervision, DrillPhase } from "./drill.js";
 export type { RestoreResult } from "./restore.js";

package/dist/lib.js

@@ -10,5 +10,7 @@ export { runRestore } from "./restore.js";
 export { projectRefOf, assertNoHostOverride, libpqChildEnv } from "./restore-engine.js";
 export { sameDatabaseTarget } from "./restore.js";
 export { runEstimate, project } from "./estimate.js";
-export { loadConfig } from "./config.js";
+export { loadConfig, requireBucket } from "./config.js";
 export { targetClient, resolveSnapshot, getObjectText, downloadToFile, hashObject, } from "./snapshots.js";
+// 快照位置接口:备份、演练、恢复都可以传入自己的实现(托管 worker 的 Google Drive 目标)
+export { s3SnapshotStore } from "./snapshot-store.js";

package/dist/restore.d.ts

@@ -1,5 +1,6 @@
 import type { BackupConfig } from "./config.js";
 import type { Manifest } from "./manifest.js";
+import { type SnapshotStore } from "./snapshot-store.js";
 import { type DrillCheck } from "./drill.js";
 import { type StorageRestoreSummary } from "./storage-restore.js";
 /** 归档可读性要求:pg_restore 必须 ≥ max(写入工具版本, 源服务端版本)——格式跟随写入工具。 */
@@ -88,4 +89,6 @@ export declare function runRestore(config: BackupConfig, opts: {
     skipStorage?: boolean;
     snapshot?: string;
     storageDir?: string;
+    /** 快照从哪读;省略 = config.storage 指的 S3 兼容桶 */
+    store?: SnapshotStore;
 }): Promise<RestoreResult>;

package/dist/restore.js

@@ -5,7 +5,7 @@ import { join, dirname, resolve, sep } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { GetObjectCommand } from "@aws-sdk/client-s3";
 import { parseManifest } from "./manifest.js";
-import { targetClient, resolveSnapshot, getObjectText, downloadToFile, } from "./snapshots.js";
+import { s3SnapshotStore } from "./snapshot-store.js";
 import { restoreDatabaseArtifact, installExtensions, projectRefOf, refFromStorageEndpoint, assertNoHostOverride, normalizeHost, } from "./restore-engine.js";
 import { verifyRestored } from "./drill.js";
 import { restoreStorage, planStorageRestore, } from "./storage-restore.js";
@@ -335,11 +335,10 @@ export async function runRestore(config, opts) {
         assertNoHostOverride(config.databaseUrl);
     if (opts.targetDatabaseUrl)
         assertNoHostOverride(opts.targetDatabaseUrl);
-    const s3 = targetClient(config);
-    const snapshotPrefix = await resolveSnapshot(s3, config, opts.snapshot);
-    const snapshot = snapshotPrefix.replace(/\/$/, "").split("/").pop();
-    const manifest = parseManifest(await getObjectText(s3, config.storage.bucket, `${snapshotPrefix}manifest.json`));
-    const base = manifest.dump.key.replace(/\/dump\.pgcustom$/, "");
+    const store = opts.store ?? s3SnapshotStore(config);
+    const reader = await store.openSnapshot(opts.snapshot);
+    const snapshot = reader.name;
+    const manifest = parseManifest(await reader.readManifest());
     // Storage 目标构造即校验(https + 恰为 <ref>.supabase.co):service key 只发往
     // 已验证的 Supabase 项目源;目标库连接串拒绝 host 覆盖(身份判定=实际写入目标)
     // 两个字段必须成对:只给其一时静默退回"本地下载"会让库级调用方把受保护文件
@@ -389,6 +388,11 @@ export async function runRestore(config, opts) {
     // 这次运行会不会碰 Storage(回传到目标,或下载到本地)。只有会碰时,空目标门才该
     // 提示"库已恢复、只重试 Storage";skipStorage 的纯数据库运行(托管恢复)不该看到这句。
     const alsoRestoringStorage = !!manifest.storage && !opts.skipStorage;
+    const storageSource = manifest.storage ? reader.storageFiles(manifest) : null;
+    if (alsoRestoringStorage && !storageSource) {
+        throw new Error("the manifest lists Storage files, but this snapshot location cannot hold them — " +
+            "restore the database only (skip Storage).");
+    }
     // dry-run:只读预检后直接返回,零写入(PRD §5.3.2)
     if (opts.dryRun) {
         log.step(`Dry run for snapshot ${snapshot} — nothing will be written`);
@@ -461,7 +465,7 @@ export async function runRestore(config, opts) {
                 throw new Error(toolTargetBlocker);
             log.step("Downloading dump…");
             const dumpPath = join(workdir, "dump.pgcustom");
-            const { sha256 } = await downloadToFile(s3, config.storage.bucket, manifest.dump.key, dumpPath);
+            const { sha256 } = await reader.downloadDump(manifest, dumpPath);
             // 归档完整性是恢复的前提:哈希不符还继续,只会把"备份坏了"变成一堆误导性
             // 恢复错误(演练侧同一裁决:integrity FAIL 即短路)
             if (sha256 !== manifest.dump.sha256) {
@@ -505,7 +509,7 @@ export async function runRestore(config, opts) {
             // DB-only 阶段(hosted 检查点重试):既不回传也不本地下载,Storage 单独一段跑
         }
         else if (manifest.storage && storageTarget) {
-            const summary = await restoreStorage({ s3, bucket: config.storage.bucket, base }, storageTarget, manifest);
+            const summary = await restoreStorage(storageSource, storageTarget, manifest);
             result.storageSummary = summary;
             result.storageFilesWritten = summary.filesUploaded;
             log.ok(`Storage restored: ${summary.filesUploaded}/${manifest.storage.files.length} files uploaded` +
@@ -568,9 +572,9 @@ export async function runRestore(config, opts) {
                     throw new Error(`unsafe storage path escapes output directory: ${f.bucket}/${f.key}`);
                 }
                 await mkdir(dirname(dest), { recursive: true });
-                const res = await s3.send(new GetObjectCommand({
-                    Bucket: config.storage.bucket,
-                    Key: `${base}/storage/${f.bucket}/${f.key}`,
+                const res = await storageSource.s3.send(new GetObjectCommand({
+                    Bucket: storageSource.bucket,
+                    Key: `${storageSource.base}/storage/${f.bucket}/${f.key}`,
                 }));
                 await pipeline(res.Body, createWriteStream(dest));
                 result.storageFilesWritten += 1;

package/dist/snapshot-store.d.ts

@@ -0,0 +1,54 @@
+import type { Readable } from "node:stream";
+import { type S3Client } from "@aws-sdk/client-s3";
+import { type BackupConfig } from "./config.js";
+import type { Manifest } from "./manifest.js";
+/**
+ * 快照放在哪里,对引擎来说只是这几个动作:建一份新快照往里写、打开一份已有快照往外读。
+ * 备份、演练、恢复都只经这层读写快照。CLI 只用 S3 兼容桶(s3SnapshotStore);托管服务
+ * 的 worker 可以传入自己的实现(Google Drive 目标,实现不进公开包)。
+ */
+export interface SnapshotStore {
+    /** name = 快照名(备份开始时的 UTC 时间戳) */
+    createSnapshot(name: string): Promise<SnapshotWriter>;
+    /** name 省略 = 最新一份 */
+    openSnapshot(name?: string): Promise<SnapshotReader>;
+}
+/** 快照里 Storage 文件的位置(<base>/storage/<bucket>/<key>)。只有 S3 兼容目标能放 Storage 文件。 */
+export interface StorageFilesLocation {
+    s3: S3Client;
+    bucket: string;
+    base: string;
+}
+export interface DumpUpload {
+    /** 转储全部写完才 resolve;任何失败都 reject */
+    done: Promise<void>;
+    /** 中止写入,尽量不留下半截文件 */
+    abort(): Promise<void>;
+}
+export interface SnapshotWriter {
+    /** 记进 manifest.dump.key 的值 */
+    readonly dumpKey: string;
+    /** 这份快照能不能放 Storage 文件;不能时为 null */
+    readonly storageFiles: StorageFilesLocation | null;
+    /** 日志里显示的位置 */
+    describe(file: string): string;
+    /** relationBytes = 要转储的表的磁盘占用(量不出为 null),实现可据此决定分块 */
+    uploadDump(body: Readable, relationBytes: number | null): DumpUpload;
+    /** RECOVERY.md 写的是"从这个位置怎么恢复",所以由各实现自己渲染 */
+    writeRecoveryDoc(manifest: Manifest): Promise<void>;
+    /** manifest 是快照的"完成标记",调用方保证最后写 */
+    writeManifest(manifest: Manifest): Promise<void>;
+}
+export interface SnapshotReader {
+    readonly name: string;
+    readManifest(): Promise<string>;
+    /** 断点续传下载转储到本地文件,返回实际落盘的字节数与 sha256 */
+    downloadDump(manifest: Manifest, dest: string): Promise<{
+        bytes: number;
+        sha256: string;
+    }>;
+    /** 这份快照的 Storage 文件从哪读;实现不支持 Storage 文件时为 null */
+    storageFiles(manifest: Manifest): StorageFilesLocation | null;
+}
+/** S3 兼容桶(S3 / R2 / B2 / Wasabi)。行为与抽出这层之前逐字一致。 */
+export declare function s3SnapshotStore(config: BackupConfig): SnapshotStore;

package/dist/snapshot-store.js

@@ -0,0 +1,76 @@
+import { PutObjectCommand } from "@aws-sdk/client-s3";
+import { Upload } from "@aws-sdk/lib-storage";
+import { requireBucket } from "./config.js";
+import { targetClient, resolveSnapshot, getObjectText, downloadToFile } from "./snapshots.js";
+import { renderRecoveryDoc } from "./recovery-doc.js";
+import { dumpPartSizeFor } from "./part-size.js";
+/** 写入时的键都在 <prefix>/<projectName>/<快照名>/ 下;读取时 Storage 文件的 base 从 dump.key 反推。 */
+function storageBaseOf(manifest) {
+    return manifest.dump.key.replace(/\/dump\.pgcustom$/, "");
+}
+/** S3 兼容桶(S3 / R2 / B2 / Wasabi)。行为与抽出这层之前逐字一致。 */
+export function s3SnapshotStore(config) {
+    const storage = requireBucket(config);
+    let client = null;
+    // 客户端推迟到第一次真正读写时才建:与抽层之前一致,配置错误先由前面的检查报出来
+    const s3 = () => (client ??= targetClient(config));
+    return {
+        async createSnapshot(name) {
+            const base = `${storage.prefix}/${config.projectName}/${name}`;
+            const location = (file) => `s3://${storage.bucket}/${base}/${file}`;
+            return {
+                dumpKey: `${base}/dump.pgcustom`,
+                storageFiles: { s3: s3(), bucket: storage.bucket, base },
+                describe: location,
+                uploadDump(body, relationBytes) {
+                    const upload = new Upload({
+                        client: s3(),
+                        partSize: dumpPartSizeFor(relationBytes),
+                        params: {
+                            Bucket: storage.bucket,
+                            Key: `${base}/dump.pgcustom`,
+                            Body: body,
+                            ContentType: "application/octet-stream",
+                        },
+                    });
+                    return {
+                        done: upload.done().then(() => { }),
+                        abort: () => upload.abort(),
+                    };
+                },
+                async writeRecoveryDoc(manifest) {
+                    await s3().send(new PutObjectCommand({
+                        Bucket: storage.bucket,
+                        Key: `${base}/RECOVERY.md`,
+                        Body: renderRecoveryDoc(manifest, {
+                            snapshot: name,
+                            bucket: storage.bucket,
+                            endpoint: storage.endpoint,
+                            region: storage.region,
+                            prefix: storage.prefix,
+                            projectName: config.projectName,
+                        }),
+                        ContentType: "text/markdown",
+                    }));
+                },
+                async writeManifest(manifest) {
+                    await s3().send(new PutObjectCommand({
+                        Bucket: storage.bucket,
+                        Key: `${base}/manifest.json`,
+                        Body: JSON.stringify(manifest, null, 2),
+                        ContentType: "application/json",
+                    }));
+                },
+            };
+        },
+        async openSnapshot(name) {
+            const prefix = await resolveSnapshot(s3(), config, name);
+            return {
+                name: prefix.replace(/\/$/, "").split("/").pop(),
+                readManifest: () => getObjectText(s3(), storage.bucket, `${prefix}manifest.json`),
+                downloadDump: (manifest, dest) => downloadToFile(s3(), storage.bucket, manifest.dump.key, dest),
+                storageFiles: (manifest) => ({ s3: s3(), bucket: storage.bucket, base: storageBaseOf(manifest) }),
+            };
+        },
+    };
+}

package/dist/snapshots.d.ts

@@ -1,5 +1,5 @@
 import { S3Client } from "@aws-sdk/client-s3";
-import type { BackupConfig } from "./config.js";
+import { type BackupConfig } from "./config.js";
 /** 读备份桶(用户自己的桶)的 S3 客户端。drill/restore 共用。 */
 export declare function targetClient(config: BackupConfig): S3Client;
 /** 定位快照:显式指定,否则取字典序最大(时间戳格式天然可排序)。返回带尾斜杠的前缀。 */

package/dist/snapshots.js

@@ -4,28 +4,31 @@ import { pipeline } from "node:stream/promises";
 import { Writable } from "node:stream";
 import { log } from "./log.js";
 import { S3Client, ListObjectsV2Command, GetObjectCommand, } from "@aws-sdk/client-s3";
+import { requireBucket } from "./config.js";
 /** 读备份桶(用户自己的桶)的 S3 客户端。drill/restore 共用。 */
 export function targetClient(config) {
+    const storage = requireBucket(config);
     return new S3Client({
-        region: config.storage.region,
-        endpoint: config.storage.endpoint,
-        forcePathStyle: config.storage.forcePathStyle,
+        region: storage.region,
+        endpoint: storage.endpoint,
+        forcePathStyle: storage.forcePathStyle,
         credentials: {
-            accessKeyId: config.storage.accessKeyId,
-            secretAccessKey: config.storage.secretAccessKey,
+            accessKeyId: storage.accessKeyId,
+            secretAccessKey: storage.secretAccessKey,
         },
     });
 }
 /** 定位快照:显式指定,否则取字典序最大(时间戳格式天然可排序)。返回带尾斜杠的前缀。 */
 export async function resolveSnapshot(s3, config, explicit) {
-    const root = `${config.storage.prefix}/${config.projectName}/`;
+    const storage = requireBucket(config);
+    const root = `${storage.prefix}/${config.projectName}/`;
     if (explicit)
         return `${root}${explicit}/`;
     const prefixes = [];
     let token;
     do {
         const res = await s3.send(new ListObjectsV2Command({
-            Bucket: config.storage.bucket,
+            Bucket: storage.bucket,
             Prefix: root,
             Delimiter: "/",
             ContinuationToken: token,
@@ -37,7 +40,7 @@ export async function resolveSnapshot(s3, config, explicit) {
         token = res.IsTruncated ? res.NextContinuationToken : undefined;
     } while (token);
     if (!prefixes.length) {
-        throw new Error(`No snapshots found under s3://${config.storage.bucket}/${root}. Run a backup first.`);
+        throw new Error(`No snapshots found under s3://${storage.bucket}/${root}. Run a backup first.`);
     }
     prefixes.sort();
     return prefixes[prefixes.length - 1];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backupdrill",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Open-source CLI to back up a Supabase project — Postgres database and Storage files — to your own S3/R2/B2 bucket, with a checksummed manifest.",
   "type": "module",
   "bin": {