@supacloud/lite 0.8.1 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.8.2](https://github.com/zuohuadong/supacloud/compare/supacloud-lite-v0.8.1...supacloud-lite-v0.8.2) (2026-08-15)
+
+
+### Bug Fixes
+
+* **lite:** support mirrored native postgres downloads ([#916](https://github.com/zuohuadong/supacloud/issues/916)) ([48224b7](https://github.com/zuohuadong/supacloud/commit/48224b7b067fcc56b3be8059301525cebeefb98d))
+
 ## [0.8.1](https://github.com/zuohuadong/supacloud/compare/supacloud-lite-v0.8.0...supacloud-lite-v0.8.1) (2026-08-15)
 
 

package/README.md

@@ -135,9 +135,16 @@ supacloud-lite version
 - `SUPACLOUD_LITE_STORAGE_DIR`
 - `SUPACLOUD_LITE_STORAGE_BACKEND`：`fs`（默认）、`memory` 或 `s3`
 - `SUPACLOUD_LITE_S3_PREFIX`：S3 对象 key 前缀，可被 `--s3-prefix` 覆盖
+- `SUPACLOUD_LITE_POSTGRES_MIRROR`：native 引擎下载 PostgreSQL 发布包时使用的 HTTPS 镜像前缀，例如 `https://ghproxy.net/`
 - `SUPACLOUD_LITE_JWT_SECRET`
 - `SUPACLOUD_LITE_VAULT_KEY`
 
+native 引擎首次运行会下载约 12 MB 的 Theseus PostgreSQL 发布包并缓存在 `~/.cache/supacloud-lite`。网络无法直连 GitHub 时，可设置镜像前缀；Lite 会把完整上游 URL 追加到该前缀，并在解压执行前继续校验固定或上游发布的 SHA-256。镜像不能包含 URL 凭据、query 或 fragment；除 loopback 测试地址外必须使用 HTTPS。
+
+```bash
+SUPACLOUD_LITE_POSTGRES_MIRROR=https://ghproxy.net/ supacloud-lite migrate --engine native
+```
+
 使用远端 S3 时，启动前设置 `SUPACLOUD_LITE_STORAGE_BACKEND=s3`，并按 Bun S3 约定提供 `S3_BUCKET`、`S3_ACCESS_KEY_ID`、`S3_SECRET_ACCESS_KEY`、`S3_ENDPOINT`、`S3_REGION` 等变量；也支持对应的 `AWS_*` 变量。CLI 不接受密钥参数，避免凭据出现在进程列表中。
 
 S3 模式下 `db reset` 会被拒绝，因为 Lite 不能把数据库元数据清理与远端对象删除做成原子操作；需要先明确处理远端 bucket/prefix，再切回本地或内存存储执行重置。
@@ -469,9 +476,16 @@ Environment variables:
 - `SUPACLOUD_LITE_STORAGE_DIR`
 - `SUPACLOUD_LITE_STORAGE_BACKEND`: `fs` (default), `memory`, or `s3`
 - `SUPACLOUD_LITE_S3_PREFIX`: S3 object key prefix, can be overridden by `--s3-prefix`
+- `SUPACLOUD_LITE_POSTGRES_MIRROR`: HTTPS prefix used to proxy native-engine PostgreSQL release downloads, for example `https://ghproxy.net/`
 - `SUPACLOUD_LITE_JWT_SECRET`
 - `SUPACLOUD_LITE_VAULT_KEY`
 
+On its first run, the native engine downloads an approximately 12 MB Theseus PostgreSQL release into `~/.cache/supacloud-lite`. If GitHub is not directly reachable, set a mirror prefix; Lite appends the complete upstream URL and still verifies the pinned or published SHA-256 before extracting or executing the archive. The mirror must not contain URL credentials, a query, or a fragment, and must use HTTPS except for loopback test endpoints.
+
+```bash
+SUPACLOUD_LITE_POSTGRES_MIRROR=https://ghproxy.net/ supacloud-lite migrate --engine native
+```
+
 When using remote S3, set `SUPACLOUD_LITE_STORAGE_BACKEND=s3` before starting, and provide variables such as `S3_BUCKET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_ENDPOINT`, and `S3_REGION` according to Bun S3 conventions; the corresponding `AWS_*` variables are also supported. The CLI does not accept secret parameters to avoid credentials appearing in the process list.
 
 In S3 mode, `db reset` is rejected because Lite cannot make database metadata cleanup and remote object deletion an atomic operation; you must explicitly handle the remote bucket/prefix first, then switch back to local or memory storage to perform the reset.

package/dist/cli.js

@@ -8,7 +8,7 @@ import { dirname as dirname7, join as join10, resolve as resolve4 } from "path";
 // package.json
 var package_default = {
   name: "@supacloud/lite",
-  version: "0.8.1",
+  version: "0.8.2",
   description: "Bun-native, single-project Supabase-compatible backend powered by PGlite or native PostgreSQL",
   type: "module",
   license: "Apache-2.0",
@@ -10796,6 +10796,7 @@ function toPgArrayLiteral(array) {
 
 // src/runtime/node/native/engine.ts
 var DEFAULT_PG_VERSION = "17.7.0";
+var POSTGRES_MIRROR_URL_ERROR = "SUPACLOUD_LITE_POSTGRES_MIRROR must be an absolute HTTPS URL or a loopback HTTP URL";
 var NATIVE_POSTGRES_MAJOR = DEFAULT_PG_VERSION.split(".")[0];
 function isNativeEngineSupported() {
   return (process.platform === "darwin" || process.platform === "linux") && (process.arch === "arm64" || process.arch === "x64") && (process.platform !== "linux" || isGlibcLinux());
@@ -10827,7 +10828,7 @@ var PINNED_SHA256 = {
   "postgresql-17.7.0-x86_64-apple-darwin": "0dd8c25173524bad4ae8ef6b970da1ac40f4c1f231150c416ccb8cd06feff8f2",
   "postgresql-17.7.0-aarch64-apple-darwin": "727ac08d20a704014a0d51eb3300aa0c8e292c1cf0a1c99d4f4b1002e1420220"
 };
-async function verifyTarball(tarball, key, url) {
+async function verifyTarball(tarball, key, upstreamUrl, downloadMirror) {
   const actual = createHash2("sha256").update(readFileSync(tarball)).digest("hex");
   const pinned = PINNED_SHA256[key];
   if (pinned) {
@@ -10836,7 +10837,8 @@ async function verifyTarball(tarball, key, url) {
     }
     return;
   }
-  const res = await fetchRelease(`${url}.sha256`);
+  const checksumUrl = resolvePostgresDownloadUrl(`${upstreamUrl}.sha256`, downloadMirror);
+  const res = await fetchRelease(checksumUrl);
   if (!res.ok)
     throw new Error(`could not fetch checksum for ${key}: HTTP ${res.status}`);
   const expected = (await res.text()).trim().split(/\s+/)[0].toLowerCase();
@@ -10846,13 +10848,14 @@ async function verifyTarball(tarball, key, url) {
     throw new Error(`postgres binary checksum mismatch for ${key}: expected ${expected}, got ${actual}`);
   }
 }
-async function ensurePostgres(version = DEFAULT_PG_VERSION, cacheDir, log) {
+async function ensurePostgres(version = DEFAULT_PG_VERSION, cacheDir, log, downloadMirror) {
   const t = target();
   const root = cacheDir ?? join(homedir(), ".cache", "supacloud-lite");
   const dir = join(root, `postgresql-${version}-${t}`);
   if (isCompleteInstall(dir))
     return dir;
-  const url = `https://github.com/theseus-rs/postgresql-binaries/releases/download/${version}/postgresql-${version}-${t}.tar.gz`;
+  const upstreamUrl = `https://github.com/theseus-rs/postgresql-binaries/releases/download/${version}/postgresql-${version}-${t}.tar.gz`;
+  const url = resolvePostgresDownloadUrl(upstreamUrl, downloadMirror);
   mkdirSync(root, { recursive: true });
   const uniq = `${process.pid}-${randomBytes2(6).toString("hex")}`;
   const tarball = join(root, `pg-${version}-${uniq}.tar.gz`);
@@ -10865,7 +10868,7 @@ async function ensurePostgres(version = DEFAULT_PG_VERSION, cacheDir, log) {
     if (!res.ok)
       throw new Error(`failed to download ${url}: HTTP ${res.status}`);
     await writeFile(tarball, Buffer.from(await res.arrayBuffer()));
-    await verifyTarball(tarball, `postgresql-${version}-${t}`, url);
+    await verifyTarball(tarball, `postgresql-${version}-${t}`, upstreamUrl, downloadMirror);
     mkdirSync(tmpDir, { recursive: true });
     await extractTar({ cwd: tmpDir, file: tarball, gzip: true, preserveOwner: false, strict: true, strip: 1 });
     if (!isCompleteInstall(tmpDir))
@@ -10885,6 +10888,32 @@ async function ensurePostgres(version = DEFAULT_PG_VERSION, cacheDir, log) {
     rmSync(tmpDir, { recursive: true, force: true });
   }
 }
+function resolvePostgresDownloadUrl(upstreamUrl, downloadMirror) {
+  const mirror = postgresDownloadMirror(downloadMirror);
+  return mirror ? `${mirror.toString().replace(/\/+$/, "")}/${upstreamUrl}` : upstreamUrl;
+}
+function postgresDownloadMirror(downloadMirror) {
+  const configuredMirror = downloadMirror ?? process.env.SUPACLOUD_LITE_POSTGRES_MIRROR;
+  const mirrorText = configuredMirror?.trim();
+  if (!mirrorText)
+    return;
+  let mirror;
+  try {
+    mirror = new URL(mirrorText);
+  } catch {
+    throw new Error(POSTGRES_MIRROR_URL_ERROR);
+  }
+  const loopbackHttp = mirror.protocol === "http:" && (mirror.hostname === "127.0.0.1" || mirror.hostname === "localhost" || mirror.hostname === "[::1]");
+  if (mirror.protocol !== "https:" && !loopbackHttp)
+    throw new Error(POSTGRES_MIRROR_URL_ERROR);
+  if (mirror.username || mirror.password) {
+    throw new Error("SUPACLOUD_LITE_POSTGRES_MIRROR must not contain credentials");
+  }
+  if (mirrorText.includes("?") || mirrorText.includes("#")) {
+    throw new Error("SUPACLOUD_LITE_POSTGRES_MIRROR must not contain a query or fragment");
+  }
+  return mirror;
+}
 async function fetchRelease(url) {
   let lastError;
   for (let attempt = 1;attempt <= 3; attempt++) {
@@ -10917,7 +10946,7 @@ async function createNativeEngine(opts) {
   let postgres;
   let removeExitHandler;
   try {
-    const installDir = await ensurePostgres(opts.version, opts.cacheDir, opts.log);
+    const installDir = await ensurePostgres(opts.version, opts.cacheDir, opts.log, opts.downloadMirror);
     const bin = (name) => join(installDir, "bin", name);
     if (!existsSync(join(opts.dataDir, "PG_VERSION"))) {
       mkdirSync(opts.dataDir, { recursive: true });

package/dist/index.js

@@ -85,7 +85,7 @@ function randomToken(bytes = 32) {
 // package.json
 var package_default = {
   name: "@supacloud/lite",
-  version: "0.8.1",
+  version: "0.8.2",
   description: "Bun-native, single-project Supabase-compatible backend powered by PGlite or native PostgreSQL",
   type: "module",
   license: "Apache-2.0",
@@ -10809,6 +10809,7 @@ function toPgArrayLiteral(array) {
 
 // src/runtime/node/native/engine.ts
 var DEFAULT_PG_VERSION = "17.7.0";
+var POSTGRES_MIRROR_URL_ERROR = "SUPACLOUD_LITE_POSTGRES_MIRROR must be an absolute HTTPS URL or a loopback HTTP URL";
 var NATIVE_POSTGRES_MAJOR = DEFAULT_PG_VERSION.split(".")[0];
 function isNativeEngineSupported() {
   return (process.platform === "darwin" || process.platform === "linux") && (process.arch === "arm64" || process.arch === "x64") && (process.platform !== "linux" || isGlibcLinux());
@@ -10840,7 +10841,7 @@ var PINNED_SHA256 = {
   "postgresql-17.7.0-x86_64-apple-darwin": "0dd8c25173524bad4ae8ef6b970da1ac40f4c1f231150c416ccb8cd06feff8f2",
   "postgresql-17.7.0-aarch64-apple-darwin": "727ac08d20a704014a0d51eb3300aa0c8e292c1cf0a1c99d4f4b1002e1420220"
 };
-async function verifyTarball(tarball, key, url) {
+async function verifyTarball(tarball, key, upstreamUrl, downloadMirror) {
   const actual = createHash2("sha256").update(readFileSync(tarball)).digest("hex");
   const pinned = PINNED_SHA256[key];
   if (pinned) {
@@ -10849,7 +10850,8 @@ async function verifyTarball(tarball, key, url) {
     }
     return;
   }
-  const res = await fetchRelease(`${url}.sha256`);
+  const checksumUrl = resolvePostgresDownloadUrl(`${upstreamUrl}.sha256`, downloadMirror);
+  const res = await fetchRelease(checksumUrl);
   if (!res.ok)
     throw new Error(`could not fetch checksum for ${key}: HTTP ${res.status}`);
   const expected = (await res.text()).trim().split(/\s+/)[0].toLowerCase();
@@ -10859,13 +10861,14 @@ async function verifyTarball(tarball, key, url) {
     throw new Error(`postgres binary checksum mismatch for ${key}: expected ${expected}, got ${actual}`);
   }
 }
-async function ensurePostgres(version = DEFAULT_PG_VERSION, cacheDir, log) {
+async function ensurePostgres(version = DEFAULT_PG_VERSION, cacheDir, log, downloadMirror) {
   const t = target();
   const root = cacheDir ?? join2(homedir(), ".cache", "supacloud-lite");
   const dir = join2(root, `postgresql-${version}-${t}`);
   if (isCompleteInstall(dir))
     return dir;
-  const url = `https://github.com/theseus-rs/postgresql-binaries/releases/download/${version}/postgresql-${version}-${t}.tar.gz`;
+  const upstreamUrl = `https://github.com/theseus-rs/postgresql-binaries/releases/download/${version}/postgresql-${version}-${t}.tar.gz`;
+  const url = resolvePostgresDownloadUrl(upstreamUrl, downloadMirror);
   mkdirSync(root, { recursive: true });
   const uniq = `${process.pid}-${randomBytes2(6).toString("hex")}`;
   const tarball = join2(root, `pg-${version}-${uniq}.tar.gz`);
@@ -10878,7 +10881,7 @@ async function ensurePostgres(version = DEFAULT_PG_VERSION, cacheDir, log) {
     if (!res.ok)
       throw new Error(`failed to download ${url}: HTTP ${res.status}`);
     await writeFile2(tarball, Buffer.from(await res.arrayBuffer()));
-    await verifyTarball(tarball, `postgresql-${version}-${t}`, url);
+    await verifyTarball(tarball, `postgresql-${version}-${t}`, upstreamUrl, downloadMirror);
     mkdirSync(tmpDir, { recursive: true });
     await extractTar({ cwd: tmpDir, file: tarball, gzip: true, preserveOwner: false, strict: true, strip: 1 });
     if (!isCompleteInstall(tmpDir))
@@ -10898,6 +10901,32 @@ async function ensurePostgres(version = DEFAULT_PG_VERSION, cacheDir, log) {
     rmSync(tmpDir, { recursive: true, force: true });
   }
 }
+function resolvePostgresDownloadUrl(upstreamUrl, downloadMirror) {
+  const mirror = postgresDownloadMirror(downloadMirror);
+  return mirror ? `${mirror.toString().replace(/\/+$/, "")}/${upstreamUrl}` : upstreamUrl;
+}
+function postgresDownloadMirror(downloadMirror) {
+  const configuredMirror = downloadMirror ?? process.env.SUPACLOUD_LITE_POSTGRES_MIRROR;
+  const mirrorText = configuredMirror?.trim();
+  if (!mirrorText)
+    return;
+  let mirror;
+  try {
+    mirror = new URL(mirrorText);
+  } catch {
+    throw new Error(POSTGRES_MIRROR_URL_ERROR);
+  }
+  const loopbackHttp = mirror.protocol === "http:" && (mirror.hostname === "127.0.0.1" || mirror.hostname === "localhost" || mirror.hostname === "[::1]");
+  if (mirror.protocol !== "https:" && !loopbackHttp)
+    throw new Error(POSTGRES_MIRROR_URL_ERROR);
+  if (mirror.username || mirror.password) {
+    throw new Error("SUPACLOUD_LITE_POSTGRES_MIRROR must not contain credentials");
+  }
+  if (mirrorText.includes("?") || mirrorText.includes("#")) {
+    throw new Error("SUPACLOUD_LITE_POSTGRES_MIRROR must not contain a query or fragment");
+  }
+  return mirror;
+}
 async function fetchRelease(url) {
   let lastError;
   for (let attempt = 1;attempt <= 3; attempt++) {
@@ -10930,7 +10959,7 @@ async function createNativeEngine(opts) {
   let postgres;
   let removeExitHandler;
   try {
-    const installDir = await ensurePostgres(opts.version, opts.cacheDir, opts.log);
+    const installDir = await ensurePostgres(opts.version, opts.cacheDir, opts.log, opts.downloadMirror);
     const bin = (name) => join2(installDir, "bin", name);
     if (!existsSync(join2(opts.dataDir, "PG_VERSION"))) {
       mkdirSync(opts.dataDir, { recursive: true });

package/dist/runtime/node/native/engine.d.ts

@@ -10,10 +10,17 @@ export interface NativeEngineOptions {
     cacheDir?: string;
     /** sink for progress lines (download, install); no-op when omitted */
     log?: (msg: string) => void;
+    /** Optional HTTPS or loopback HTTP prefix for proxying the PostgreSQL release download. */
+    downloadMirror?: string;
 }
 export declare function isNativeEngineSupported(): boolean;
 /** Download + unpack Postgres binaries if not already cached (concurrency-safe). Returns the install dir. */
-export declare function ensurePostgres(version?: string, cacheDir?: string, log?: (m: string) => void): Promise<string>;
+export declare function ensurePostgres(version?: string, cacheDir?: string, log?: (m: string) => void, downloadMirror?: string): Promise<string>;
+/**
+ * Prefix a trusted GitHub release URL with an operator-selected mirror. The
+ * archive is still checked against the pinned or published SHA-256 before use.
+ */
+export declare function resolvePostgresDownloadUrl(upstreamUrl: string, downloadMirror?: string): string;
 /**
  * Boot the embedded Postgres child (initdb on first run) and return a {@link DbEngine}
  * backed by two wire connections: one for queries/transactions (serialized by a mutex),

package/dist/runtime/node/native/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../../src/runtime/node/native/engine.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAKlD,eAAO,MAAM,qBAAqB,QAAoC,CAAA;AAEtE,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,sEAAsE;IACtE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAC5B;AAED,wBAAgB,uBAAuB,IAAI,OAAO,CAIjD;AA4DD,6GAA6G;AAC7G,wBAAsB,cAAc,CAAC,OAAO,SAAqB,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CA2ChI;AA4BD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAiFrF"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../../src/runtime/node/native/engine.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAOlD,eAAO,MAAM,qBAAqB,QAAoC,CAAA;AAEtE,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,sEAAsE;IACtE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3B,2FAA2F;IAC3F,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,wBAAgB,uBAAuB,IAAI,OAAO,CAIjD;AA6DD,6GAA6G;AAC7G,wBAAsB,cAAc,CAClC,OAAO,SAAqB,EAC5B,QAAQ,CAAC,EAAE,MAAM,EACjB,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,EACzB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,MAAM,CAAC,CA4CjB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAG/F;AAkDD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAiFrF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/lite",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Bun-native, single-project Supabase-compatible backend powered by PGlite or native PostgreSQL",
   "type": "module",
   "license": "Apache-2.0",