@supacloud/lite 0.2.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [0.5.0](https://github.com/zuohuadong/supacloud/compare/supacloud-lite-v0.4.0...supacloud-lite-v0.5.0) (2026-07-29)
+
+
+### Features
+
+* **lite:** build standalone single-file binaries with embedded PGlite assets ([#644](https://github.com/zuohuadong/supacloud/issues/644)) ([50da574](https://github.com/zuohuadong/supacloud/commit/50da574a4643fba9d5027464b501e18afe79926b))
+
+## [0.4.0](https://github.com/zuohuadong/supacloud/compare/supacloud-lite-v0.3.0...supacloud-lite-v0.4.0) (2026-07-29)
+
+
+### Features
+
+* **lite:** align auth queue and cache compatibility ([f6efcd3](https://github.com/zuohuadong/supacloud/commit/f6efcd3168392f96b36ad4a9b89fafd379f523a4))
+
+
+### Bug Fixes
+
+* resolve remaining reported runtime and console issues ([5fda9f0](https://github.com/zuohuadong/supacloud/commit/5fda9f0960fe7c1a03765f69cc59ebe847016a2c))
+* resolve reported console and Lite issues ([781fba4](https://github.com/zuohuadong/supacloud/commit/781fba47412ed44272dc355d484c9d2c283151c9))
+
+## [0.3.0](https://github.com/zuohuadong/supacloud/compare/supacloud-lite-v0.2.0...supacloud-lite-v0.3.0) (2026-07-28)
+
+
+### Features
+
+* extend Supabase-compatible platform capabilities ([adef019](https://github.com/zuohuadong/supacloud/commit/adef019261f82f123043ab4c7a047e6ad6956e56))
+* harden Supabase Cloud compatibility ([ab64374](https://github.com/zuohuadong/supacloud/commit/ab643743b058ad08a0d32c124d26bed0863db397))
+
+
+### Bug Fixes
+
+* use installed TypeScript in Lite smoke ([8a64050](https://github.com/zuohuadong/supacloud/commit/8a64050833c47778e931067f8f30e541141256bf))
+
+
+### Documentation
+
+* **lite:** document snapshot archive dependency ([1c0a8cc](https://github.com/zuohuadong/supacloud/commit/1c0a8cccc4e6cbb0804c7badf6573d6d986c2528))
+
 ## [0.2.0](https://github.com/zuohuadong/supacloud/compare/supacloud-lite-v0.1.0...supacloud-lite-v0.2.0) (2026-07-28)
 
 

package/LICENSES/BUN-1.3.14-RUNTIME-NOTICES.txt

@@ -0,0 +1,78 @@
+---
+title: License
+description: License for Bun
+---
+
+Bun itself is MIT-licensed.
+
+## JavaScriptCore
+
+Bun statically links JavaScriptCore (and WebKit) which is LGPL-2 licensed. WebCore files from WebKit are also licensed under LGPL2. Per LGPL2:
+
+> (1) If you statically link against an LGPL'd library, you must also provide your application in an object (not necessarily source) format, so that a user has the opportunity to modify the library and relink the application.
+
+You can find the patched version of WebKit used by Bun here: https://github.com/oven-sh/webkit. If you would like to relink Bun with changes:
+
+- `git submodule update --init --recursive`
+- `make jsc`
+- `zig build`
+
+This compiles JavaScriptCore, compiles Bun's `.cpp` bindings for JavaScriptCore (which are the object files using JavaScriptCore) and outputs a new `bun` binary with your changes.
+
+## Linked libraries
+
+Bun statically links these libraries:
+
+| Library                                                                                                                                          | License                                                                                      |
+| ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| [`boringssl`](https://boringssl.googlesource.com/boringssl/)                                                                                     | [several licenses](https://boringssl.googlesource.com/boringssl/+/refs/heads/master/LICENSE) |
+| [`brotli`](https://github.com/google/brotli)                                                                                                     | MIT                                                                                          |
+| [`libarchive`](https://github.com/libarchive/libarchive)                                                                                         | [several licenses](https://github.com/libarchive/libarchive/blob/master/COPYING)             |
+| [`lol-html`](https://github.com/cloudflare/lol-html/tree/master/c-api)                                                                           | BSD 3-Clause                                                                                 |
+| [`mimalloc`](https://github.com/microsoft/mimalloc)                                                                                              | MIT                                                                                          |
+| [`picohttp`](https://github.com/h2o/picohttpparser)                                                                                              | dual-licensed under the Perl License or the MIT License                                      |
+| [`zstd`](https://github.com/facebook/zstd)                                                                                                       | dual-licensed under the BSD License or GPLv2 license                                         |
+| [`simdutf`](https://github.com/simdutf/simdutf)                                                                                                  | Apache 2.0                                                                                   |
+| [`tinycc`](https://github.com/tinycc/tinycc)                                                                                                     | LGPL v2.1                                                                                    |
+| [`uSockets`](https://github.com/uNetworking/uSockets)                                                                                            | Apache 2.0                                                                                   |
+| [`zlib-ng`](https://github.com/zlib-ng/zlib-ng)                                                                                                  | zlib                                                                                         |
+| [`c-ares`](https://github.com/c-ares/c-ares)                                                                                                     | MIT licensed                                                                                 |
+| [`libicu`](https://github.com/unicode-org/icu) 72                                                                                                | [license here](https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE)                   |
+| [`libbase64`](https://github.com/aklomp/base64/blob/master/LICENSE)                                                                              | BSD 2-Clause                                                                                 |
+| [`libuv`](https://github.com/libuv/libuv) (on Windows)                                                                                           | MIT                                                                                          |
+| [`libdeflate`](https://github.com/ebiggers/libdeflate)                                                                                           | MIT                                                                                          |
+| A fork of [`uWebsockets`](https://github.com/jarred-sumner/uwebsockets)                                                                          | Apache 2.0 licensed                                                                          |
+| Parts of [Tigerbeetle's IO code](https://github.com/tigerbeetle/tigerbeetle/blob/532c8b70b9142c17e07737ab6d3da68d7500cbca/src/io/windows.zig#L1) | Apache 2.0 licensed                                                                          |
+
+## Polyfills
+
+For compatibility reasons, the following packages are embedded into Bun's binary and injected if imported.
+
+| Package                                                                  | License |
+| ------------------------------------------------------------------------ | ------- |
+| [`assert`](https://npmjs.com/package/assert)                             | MIT     |
+| [`browserify-zlib`](https://npmjs.com/package/browserify-zlib)           | MIT     |
+| [`buffer`](https://npmjs.com/package/buffer)                             | MIT     |
+| [`constants-browserify`](https://npmjs.com/package/constants-browserify) | MIT     |
+| [`crypto-browserify`](https://npmjs.com/package/crypto-browserify)       | MIT     |
+| [`domain-browser`](https://npmjs.com/package/domain-browser)             | MIT     |
+| [`events`](https://npmjs.com/package/events)                             | MIT     |
+| [`https-browserify`](https://npmjs.com/package/https-browserify)         | MIT     |
+| [`os-browserify`](https://npmjs.com/package/os-browserify)               | MIT     |
+| [`path-browserify`](https://npmjs.com/package/path-browserify)           | MIT     |
+| [`process`](https://npmjs.com/package/process)                           | MIT     |
+| [`punycode`](https://npmjs.com/package/punycode)                         | MIT     |
+| [`querystring-es3`](https://npmjs.com/package/querystring-es3)           | MIT     |
+| [`stream-browserify`](https://npmjs.com/package/stream-browserify)       | MIT     |
+| [`stream-http`](https://npmjs.com/package/stream-http)                   | MIT     |
+| [`string_decoder`](https://npmjs.com/package/string_decoder)             | MIT     |
+| [`timers-browserify`](https://npmjs.com/package/timers-browserify)       | MIT     |
+| [`tty-browserify`](https://npmjs.com/package/tty-browserify)             | MIT     |
+| [`url`](https://npmjs.com/package/url)                                   | MIT     |
+| [`util`](https://npmjs.com/package/util)                                 | MIT     |
+| [`vm-browserify`](https://npmjs.com/package/vm-browserify)               | MIT     |
+
+## Additional credits
+
+- Bun's JS transpiler, CSS lexer, and Node.js module resolver source code is a Zig port of [@evanw](https://github.com/evanw)’s [esbuild](https://github.com/evanw/esbuild) project.
+- Credit to [@kipply](https://github.com/kipply) for the name "Bun"!

package/LICENSES/CHOWNR-BLUEOAK-1.0.0.txt

@@ -0,0 +1,63 @@
+All packages under `src/` are licensed according to the terms in
+their respective `LICENSE` or `LICENSE.md` files.
+
+The remainder of this project is licensed under the Blue Oak
+Model License, as follows:
+
+-----
+
+# Blue Oak Model License
+
+Version 1.0.0
+
+## Purpose
+
+This license gives everyone as much permission to work with
+this software as possible, while protecting contributors
+from liability.
+
+## Acceptance
+
+In order to receive this license, you must agree to its
+rules.  The rules of this license are both obligations
+under that agreement and conditions to your license.
+You must not do anything with this software that triggers
+a rule that you cannot or will not follow.
+
+## Copyright
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe that contributor's
+copyright in it.
+
+## Notices
+
+You must ensure that everyone who gets a copy of
+any part of this software from you, with or without
+changes, also gets the text of this license or a link to
+<https://blueoakcouncil.org/license/1.0.0>.
+
+## Excuse
+
+If anyone notifies you in writing that you have not
+complied with [Notices](#notices), you can keep your
+license by taking all practical steps to comply within 30
+days after the notice.  If you do not do so, your license
+ends immediately.
+
+## Patent
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe any patent claims
+they can license or become able to license.
+
+## Reliability
+
+No contributor can revoke this license.
+
+## No Liability
+
+***As far as the law allows, this software comes as is,
+without any warranty or condition, and no contributor
+will be liable to anyone for any damages related to this
+software or this license, under any kind of legal claim.***

package/LICENSES/FS-MINIPASS-ISC.txt

@@ -0,0 +1,15 @@
+The ISC License
+
+Copyright (c) Isaac Z. Schlueter and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/LICENSES/MINIPASS-BLUEOAK-1.0.0.txt

@@ -0,0 +1,55 @@
+# Blue Oak Model License
+
+Version 1.0.0
+
+## Purpose
+
+This license gives everyone as much permission to work with
+this software as possible, while protecting contributors
+from liability.
+
+## Acceptance
+
+In order to receive this license, you must agree to its
+rules.  The rules of this license are both obligations
+under that agreement and conditions to your license.
+You must not do anything with this software that triggers
+a rule that you cannot or will not follow.
+
+## Copyright
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe that contributor's
+copyright in it.
+
+## Notices
+
+You must ensure that everyone who gets a copy of
+any part of this software from you, with or without
+changes, also gets the text of this license or a link to
+<https://blueoakcouncil.org/license/1.0.0>.
+
+## Excuse
+
+If anyone notifies you in writing that you have not
+complied with [Notices](#notices), you can keep your
+license by taking all practical steps to comply within 30
+days after the notice.  If you do not do so, your license
+ends immediately.
+
+## Patent
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe any patent claims
+they can license or become able to license.
+
+## Reliability
+
+No contributor can revoke this license.
+
+## No Liability
+
+***As far as the law allows, this software comes as is,
+without any warranty or condition, and no contributor
+will be liable to anyone for any damages related to this
+software or this license, under any kind of legal claim.***

package/LICENSES/MINIZLIB-MIT.txt

@@ -0,0 +1,26 @@
+Minizlib was created by Isaac Z. Schlueter.
+It is a derivative work of the Node.js project.
+
+"""
+Copyright (c) 2017-2023 Isaac Z. Schlueter and Contributors
+Copyright (c) 2017-2023 Node.js contributors. All rights reserved.
+Copyright (c) 2017-2023 Joyent, Inc. and other Node contributors. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+"""

package/LICENSES/NODE-TAR-BLUEOAK-1.0.0.txt

@@ -0,0 +1,55 @@
+# Blue Oak Model License
+
+Version 1.0.0
+
+## Purpose
+
+This license gives everyone as much permission to work with
+this software as possible, while protecting contributors
+from liability.
+
+## Acceptance
+
+In order to receive this license, you must agree to its
+rules.  The rules of this license are both obligations
+under that agreement and conditions to your license.
+You must not do anything with this software that triggers
+a rule that you cannot or will not follow.
+
+## Copyright
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe that contributor's
+copyright in it.
+
+## Notices
+
+You must ensure that everyone who gets a copy of
+any part of this software from you, with or without
+changes, also gets the text of this license or a link to
+<https://blueoakcouncil.org/license/1.0.0>.
+
+## Excuse
+
+If anyone notifies you in writing that you have not
+complied with [Notices](#notices), you can keep your
+license by taking all practical steps to comply within 30
+days after the notice.  If you do not do so, your license
+ends immediately.
+
+## Patent
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe any patent claims
+they can license or become able to license.
+
+## Reliability
+
+No contributor can revoke this license.
+
+## No Liability
+
+***As far as the law allows, this software comes as is,
+without any warranty or condition, and no contributor
+will be liable to anyone for any damages related to this
+software or this license, under any kind of legal claim.***

package/LICENSES/YALLIST-BLUEOAK-1.0.0.txt

@@ -0,0 +1,63 @@
+All packages under `src/` are licensed according to the terms in
+their respective `LICENSE` or `LICENSE.md` files.
+
+The remainder of this project is licensed under the Blue Oak
+Model License, as follows:
+
+-----
+
+# Blue Oak Model License
+
+Version 1.0.0
+
+## Purpose
+
+This license gives everyone as much permission to work with
+this software as possible, while protecting contributors
+from liability.
+
+## Acceptance
+
+In order to receive this license, you must agree to its
+rules.  The rules of this license are both obligations
+under that agreement and conditions to your license.
+You must not do anything with this software that triggers
+a rule that you cannot or will not follow.
+
+## Copyright
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe that contributor's
+copyright in it.
+
+## Notices
+
+You must ensure that everyone who gets a copy of
+any part of this software from you, with or without
+changes, also gets the text of this license or a link to
+<https://blueoakcouncil.org/license/1.0.0>.
+
+## Excuse
+
+If anyone notifies you in writing that you have not
+complied with [Notices](#notices), you can keep your
+license by taking all practical steps to comply within 30
+days after the notice.  If you do not do so, your license
+ends immediately.
+
+## Patent
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe any patent claims
+they can license or become able to license.
+
+## Reliability
+
+No contributor can revoke this license.
+
+## No Liability
+
+***As far as the law allows, this software comes as is,
+without any warranty or condition, and no contributor
+will be liable to anyone for any damages related to this
+software or this license, under any kind of legal claim.***

package/README.md

@@ -6,7 +6,7 @@ V1 的目标不是复刻完整 Supabase 平台控制面，而是让现有应用
 
 ## 状态
 
-- 运行时：Bun 1.3+
+- 运行时：npm 包需要 Bun 1.3+；单二进制发行版已内嵌 Bun 和 PGlite 资源
 - 数据库：PGlite 0.5.4
 - 项目模型：单进程、单项目，内部 project ref 固定为 `local`
 - 客户端：直接使用官方 `@supabase/supabase-js`
@@ -21,6 +21,15 @@ bun add @supacloud/lite
 bunx supacloud-lite start
 ```
 
+也可以从 GitHub Release 下载当前平台的 `supacloud-lite-*` 单二进制。该文件不需要预装 Bun、Node、npm 或 Docker：
+
+```bash
+chmod +x ./supacloud-lite-linux-x64
+./supacloud-lite-linux-x64 start --project-dir /path/to/project
+```
+
+单二进制仍读取项目的 `supabase/` 目录，并在项目外部写入 `.supacloud-lite/` 持久化状态；它不包含 Web 控制台或 Supabase Studio。Linux x64/arm64、macOS x64/arm64 和 Windows x64 分别使用独立产物，不能跨操作系统或 CPU 架构混用。
+
 获取匿名 key：
 
 ```bash
@@ -59,6 +68,19 @@ supabase/
 
 `config.toml` 当前支持 Auth、API schema/max rows、Storage bucket/size limit、seed 和 function entrypoint 等常用配置。
 
+### Auth 运行方式
+
+Lite 不下载、安装或启动独立的 GoTrue 进程。`/auth/v1/*` 由同一个 Bun 进程中的内置 Auth 实现处理，并与该 Lite 项目的 PGlite `auth` schema 共享生命周期；这避免了 sidecar 的配置、端口和会话一致性负担。
+
+Auth 默认启用。如项目不需要客户端登录接口，可在 `supabase/config.toml` 中关闭该路由：
+
+```toml
+[auth]
+enabled = false
+```
+
+关闭后 `/auth/v1/*` 返回 `404`，但不会把 Lite 变成完整 GoTrue 运行时，也不会自动移除已有的 `auth` schema 或 API key。需要完整 GoTrue 行为、多项目鉴权或独立鉴权进程时，应使用完整 SupaCloud 平台。
+
 ## CLI
 
 ```text
@@ -70,6 +92,9 @@ supacloud-lite gen types [-o database.types.ts]
 supacloud-lite db reset
 supacloud-lite db diff [-f migration_name]
 supacloud-lite db pull [migration_name]
+supacloud-lite snapshot create [-o backup.tar.gz]
+supacloud-lite snapshot restore <backup.tar.gz> [--force]
+supacloud-lite upgrade [-o pre-upgrade.tar.gz]
 supacloud-lite inspect
 supacloud-lite version
 ```
@@ -107,15 +132,91 @@ S3 模式下 `db reset` 会被拒绝，因为 Lite 不能把数据库元数据
 
 网络暴露时必须提供足够强的 JWT secret 和独立 vault key。默认生成的密钥适合单机项目；不要把 `.supacloud-lite/secrets.json` 提交到版本库。
 
+## Windows 内嵌终端排障
+
+Lite 需要 Bun 读取已安装的 `dist/cli.js`、项目配置和 PGlite WASM 文件。若在 TRAE 等 IDE 内嵌 PowerShell 中出现 `EPERM reading`，先在同一终端运行最小文件读取测试：
+
+```powershell
+Set-Content .\bun-read-test.js 'console.log("ok")'
+bun .\bun-read-test.js
+```
+
+如果这个不含 Lite 的命令也返回 `EPERM`，故障发生在 Bun 启动应用之前，Lite 无法在应用代码内绕过宿主终端的文件访问限制。请切换到系统 PowerShell 或 Windows Terminal；随后升级到当前稳定版 Bun，并检查 IDE 沙箱、终端隔离和安全软件策略。`node` 能读取同一文件不代表 Bun 进程获得了相同的宿主权限。修复环境后再运行 `npx supacloud-lite --help` 验证。
+
+若最小测试成功而 Lite 仍失败，请保留完整错误、`bun --version`、终端类型和项目路径，再提交 Lite 问题。不要为绕过 `EPERM` 放宽项目目录的全局 ACL。
+
+## 升级、快照与恢复
+
+生产或持久化环境升级时，必须先停止当前 Lite 进程。npm 安装先更新项目锁定的依赖，再运行受控升级命令：
+
+```bash
+# 明确指定目标版本；不要在生产启动命令中隐式使用 @latest
+bun add @supacloud/lite@0.2.0
+
+# 自动创建升级前快照，然后执行尚未应用的 supabase/migrations
+bunx supacloud-lite upgrade
+```
+
+单二进制安装需要先下载并校验候选文件，再由候选二进制迁移现有项目：
+
+```bash
+./supacloud-lite-new version
+./supacloud-lite-new upgrade --project-dir /path/to/project
+./supacloud-lite-new start --project-dir /path/to/project
+```
+
+替换程序文件与数据库迁移是两个独立动作。`upgrade` 不会联网、自我替换二进制或修改 `package.json`；它默认先把升级前快照写入 `.supacloud-lite/backups/pre-upgrade-<timestamp>.tar.gz`，快照成功后才执行尚未记录的 migrations 和 seed。升级失败时快照会保留，并打印恢复命令。需要回滚时，停止候选进程，用升级前快照恢复状态，再重新启动上一个已验证版本。
+
+也可以单独创建可移植快照：
+
+```bash
+# 使用默认文件名和目录
+bunx supacloud-lite snapshot create
+
+# 指定输出位置
+bunx supacloud-lite snapshot create -o ./backups/project-a.tar.gz
+```
+
+快照是一个 gzip 压缩的 tar 文件，包含：
+
+- PGlite 数据目录；
+- `fs` 模式的对象文件；
+- `secrets.json`，用于保持 JWT、会话和 Vault 解密兼容；
+- 快照格式、Lite 版本和 Storage backend 清单。
+
+快照包含敏感密钥，输出文件在 Unix 系统上会设置为 `0600`；仍应按数据库备份级别加密、限制访问并设置保留周期。创建快照前必须停止 Lite。若检测到数据目录锁，命令会拒绝继续；只有确认进程已退出后才能人工删除陈旧锁。
+
+恢复到新项目或空状态目录：
+
+```bash
+bunx supacloud-lite snapshot restore ./backups/project-a.tar.gz
+```
+
+目标状态目录非空时默认拒绝覆盖。确认要替换现有状态时显式使用：
+
+```bash
+bunx supacloud-lite snapshot restore ./backups/project-a.tar.gz --force
+```
+
+`--force` 不会直接删除旧数据，而是把旧状态目录重命名为 `.supacloud-lite.restore-<id>` 形式的回滚副本，并在输出中打印完整路径。验证新状态后再由运维人员清理该目录。
+
+使用自定义 `--state-dir`、`--data-dir` 或 `--storage-dir` 时，创建和恢复必须传入相同参数。数据库与 Storage 目录不得重叠，也不能指向文件系统根目录或符号链接。
+
+S3 模式的快照只包含数据库中的 Storage 元数据和密钥，不复制远端对象，也不会读取或保存 S3 凭据。恢复时必须传入 `--storage-backend s3`，并重新提供原 bucket/prefix 的环境变量；跨 bucket 迁移仍需使用对象存储自身的复制工具。
+
+内存数据库没有可持久化的数据，因此 `snapshot` 和 `upgrade` 会拒绝 `--memory`。
+
 ## 兼容范围
 
 | 能力 | V1 状态 | 说明 |
 | --- | --- | --- |
 | `supabase.from()` | 已验证核心 | 自动测试覆盖 CRUD、过滤、RLS；嵌套关系、RPC 和高级 PostgREST 语法属于实验性兼容 |
-| `supabase.auth` | 已验证核心 | 自动测试覆盖邮箱密码、会话和 bcrypt；OTP/Magic Link、匿名用户、OAuth、MFA 属于实验性兼容 |
+| `supabase.auth` | 已验证核心 | 由内置 Auth 实现而非独立 GoTrue 进程提供；自动测试覆盖邮箱密码、会话和 bcrypt；OTP/Magic Link、匿名用户、OAuth、MFA 属于实验性兼容 |
 | `supabase.storage` | 已验证核心 | 覆盖上传下载、列表、删除、TUS/RLS、远端 S3 驱动，以及 Bun.Image 的 `contain`/`fill`、格式和质量变换子集；`cover` 明确不支持 |
 | `supabase.channel()` | 已验证核心 | 自动测试覆盖 `postgres_changes`、DELETE RLS 隔离和事件快照校验；Broadcast、Presence 属于实验性兼容 |
 | `supabase.functions.invoke()` | 已验证核心 | 自动测试覆盖 Bun.build、`Deno.serve()`、公开函数和同进程重启 |
+| Supabase Queues / PGMQ | 已验证核心 | 提供 `pgmq_public` 的 `send`、`send_batch`、`read`、`pop`、`archive`、`delete` RPC；队列数据持久化在同一 PGlite 项目中 |
+| Edge Functions `SupaCloud.pgredis` | 已验证核心 | 提供单项目持久 KV、TTL、原子 `getset`/`getdel`；绑定只在当前函数请求内可用 |
 | Supabase migrations | 支持 | 按文件名排序，记录到 `supabase_migrations` |
 | PostgreSQL RLS | 支持 | 使用 `anon`、`authenticated`、`service_role` 数据库角色执行 |
 | PostgREST 完整线协议 | 部分支持 | 目标是常用 `supabase-js` 行为，不承诺所有 PostgREST 边角行为 |
@@ -136,6 +237,44 @@ RLS 表的 Realtime DELETE 无法在行删除后安全重放 SELECT policy，因
 
 Lite 使用 Bun 原生 bcrypt，并兼容验证常见 GoTrue bcrypt 密码散列，因此经过映射的 `auth.users` 用户可保留密码。Auth 表结构、identity、refresh token 和 provider metadata 仍需通过受控迁移脚本转换；不要直接覆盖整个 `auth` schema。迁移后必须抽样验证登录，并为无法识别的散列准备密码重置流程。
 
+## 队列与 Edge 缓存
+
+Lite 在同一个 PGlite 数据库中提供 Supabase Queues 的公开 RPC façade。应用可以直接使用官方客户端的
+`supabase.schema('pgmq_public').rpc(...)`，无需额外的队列进程：
+
+```sql
+-- 队列创建属于管理操作，应放在项目 migration 中，而不是匿名请求路径。
+select pgmq.create('emails');
+```
+
+```ts
+const queues = supabase.schema('pgmq_public')
+const { data: ids } = await queues.rpc('send_batch', {
+  queue_name: 'emails',
+  messages: [{ to: 'user@example.com' }],
+  sleep_seconds: 0,
+})
+const { data: messages } = await queues.rpc('read', {
+  queue_name: 'emails',
+  sleep_seconds: 60,
+  n: 10,
+})
+```
+
+Lite 的 `pgmq` 模拟层还提供 `set_vt`，支持直接 SQL 调整可见性超时。消息按 PGMQ 语义至少投递一次；`pop` 会立即删除消息，`archive` 是确认路径。队列创建、指标、purge、设置和管理 API 不属于 Lite 的公开 RPC façade，仍需由项目 SQL 或完整 SupaCloud 控制面处理。
+队列名遵循标准版的 1-128 位小写字母、数字、下划线和短横线规则，并且必须以字母或数字开头；Lite 会安全映射超出 PostgreSQL 63-byte 标识符上限的名称，避免截断后串队。默认 Data API 暴露 `public` 和 `pgmq_public`；如果显式设置 `dbSchemas`，Lite 会严格使用该列表，需要队列 RPC 时应把 `pgmq_public` 明确加入。
+
+Edge Function 内可使用 `globalThis.SupaCloud.pgredis`：
+
+```ts
+const cache = globalThis.SupaCloud.pgredis
+await cache.set('welcome:user:42', { rendered: true }, 60_000)
+const value = await cache.get<{ rendered: boolean }>('welcome:user:42')
+```
+
+缓存实现使用项目自己的 PGlite 表，支持 `get`、`set`、`delete`、`ttl`、原子 `getset` 和原子 `getdel`。默认边界与标准版一致：key 最长 512 个字符、JSON 值最大 1,048,576 bytes、TTL 最大 31,536,000,000ms。有 TTL 的值在读取时会惰性清理，Lite 的 retention sweeper 还会周期性删除过期行；文件数据库会跨重启保留缓存，`--memory` 数据库则随进程退出丢失。绑定按函数请求和项目隔离，函数返回后启动的 detached Promise 不能继续访问它；Lite 不提供跨项目共享、Redis 协议、队列或限流能力。
+Lite 的缓存调用是进程内数据库操作，不具备标准版跨进程 HTTP binding 的超时和请求中止传播；不要在同一 JavaScript 进程中混合加载 Lite 与标准 Edge Runtime，两者都拥有全局 `SupaCloud` binding，Lite 检测到已有其他实现时会拒绝启动。
+
 ## 多项目
 
 V1 不在一个进程内复用多个 PGlite 项目。需要多个项目时，为每个项目配置独立的工作目录、端口和 `.supacloud-lite` 状态目录，并用进程管理器分别启动。这样可保持数据库、JWT、Storage 和 Realtime 的故障域隔离。
@@ -144,7 +283,7 @@ V1 不在一个进程内复用多个 PGlite 项目。需要多个项目时，为
 
 PGlite 是 WebAssembly PostgreSQL，不是 SQLite。它换来了 PostgreSQL SQL、角色、RLS 和 Supabase 迁移兼容性，但内存占用通常高于 PocketBase/SQLite。生产部署前应按真实 schema、并发和 Realtime 负载做容量测试。
 
-当前 npm 包依赖 PGlite 的 WASM 资源，不承诺 Bun `--compile` 单文件二进制可直接携带全部资源。V1 推荐通过 Bun + npm 包部署。
+npm 包继续通过依赖目录加载 PGlite。GitHub Release 的平台单二进制则内嵌 Bun、PGlite JS、核心 WASM/data 和 Lite 使用的 contrib 扩展；启动时会把扩展压缩包释放到受限的临时目录，PGlite 初始化完成后立即清理。项目配置、Functions、数据库、对象存储和密钥仍保持外置。
 
 ## API
 

package/RELEASING.md

@@ -19,4 +19,17 @@ bun run check
 bun audit --audit-level high
 ```
 
-`bun run check` 会构建包、执行真实 `supabase-js` 集成测试、生成 npm tarball、在临时消费者项目中安装 tarball，并验证 CLI、公开 API、PGlite WASM 和版本一致性。
+`bun run check` 会构建包、执行真实 `supabase-js` 集成测试、生成 npm tarball、在临时消费者项目中安装 tarball，并验证 npm CLI、公开 API、PGlite WASM 和版本一致性。它还会构建 host 单二进制，在不含 Bun/Node/npm 的 `PATH` 下验证 Functions、PGlite contrib 扩展、持久数据升级、升级前快照和恢复。
+
+## Standalone binaries
+
+本地构建当前平台：
+
+```bash
+bun run build:standalone:host
+bun run test:standalone
+```
+
+Release workflow 为 Linux x64 baseline/arm64、macOS x64/arm64 和 Windows x64 baseline 构建独立产物。Linux x64 产物必须在发布 runner 上完成真实黑盒测试；其他交叉编译产物在具备对应原生 runner 前只视为已构建，不能替代平台验收。
+
+Lite release 会同时上传 `SHA256SUMS`、项目自身的 `SUPACLOUD-LITE-APACHE-2.0.txt`、`THIRD_PARTY_NOTICES.md` 和 `LICENSES/*.txt`，并为发布资产生成 provenance。正式对外分发 macOS 或 Windows 产物前，还应按项目发布策略完成代码签名；构建成功不代表已经签名或公证。