docs: clarify SQLite production viability and backup strategies

os-zhuang · os-zhuang · commit 0dabe13cbe36 · 2026-05-27T21:21:53.000+08:00
diff --git a/content/docs/configure/storage.cn.mdx b/content/docs/configure/storage.cn.mdx
@@ -41,7 +41,13 @@ new StorageServicePlugin({
 
 在 standalone 模式（无项目执行 `os start`）下，运行时会在 `~/.objectstack/data/uploads/` 下自动配置本地存储。
 
-**不适合生产**，除非你只有一个节点并能容忍该节点磁盘故障导致的文件丢失。多节点或需要持久化的场景请使用 S3 兼容存储。
+**是否适合生产取决于部署形态：**
+
+- ✅ 桌面端应用、单节点内部工具、边缘 / 本地一体机 —— 本地存储完全可以，
+  只要把 `uploads/` 目录纳入文件系统备份（桌面端应用也可以把它放在
+  用户控制的同步目录里）。
+- ❌ 多节点、多可用区，或者任何需要跨区域持久化的场景 —— 请使用 S3
+  兼容存储。
 
 ## S3 兼容（生产）
 
diff --git a/content/docs/configure/storage.mdx b/content/docs/configure/storage.mdx
@@ -47,9 +47,14 @@ new StorageServicePlugin({
 In standalone mode (`os start` with no project), the runtime configures
 local storage automatically under `~/.objectstack/data/uploads/`.
 
-**Not suitable for production** unless you have one node and tolerate
-file loss on that node's disk. Use S3-compatible storage for anything
-multi-node or durable.
+**Production fit depends on the deployment shape:**
+
+- ✅ Desktop apps, single-node internal tools, edge / on-prem
+  appliances — local storage is fine, as long as the `uploads/`
+  directory is included in your filesystem backup (or lives on a
+  user-controlled sync folder for desktop apps).
+- ❌ Multi-node, multi-AZ, or anything that needs cross-region
+  durability — use S3-compatible storage.
 
 ## S3-compatible (production)
 
diff --git a/content/docs/operate/backup.cn.mdx b/content/docs/operate/backup.cn.mdx
@@ -31,14 +31,68 @@ ObjectOS **不**需要对其容器文件系统做单独备份。缓存目录
 | PostgreSQL | 持续 WAL 归档 + 基础备份;支持时间点恢复 |
 | Turso / libSQL | 使用平台的备份功能;本地导出为 SQLite 作冷备 |
 | MongoDB | 副本集快照;通过 oplog 实现 PITR |
-| SQLite（仅限单节点评估） | 运行时空闲时做文件级快照;**不适合**生产 |
+| SQLite（单节点 / 桌面） | 启用 WAL 模式 + 用 `VACUUM INTO` 或 Online Backup API 做热快照;如需更低 RPO 可叠加 Litestream 持续复制 —— 见下方 [SQLite 部署](#sqlite-部署) |
 
 无论使用哪种驱动，都需验证：
 
 - 备份能在客户的 RPO 内完成;
 - 一个全新数据库能基于同一份产物启动 ObjectOS 并对外服务;
 - 至少每季度执行一次端到端的恢复演练。
 
+## SQLite 部署
+
+SQLite 是默认驱动，对于**单节点**形态的 ObjectOS 完全可以用于生产
+—— 桌面端应用、小团队内部工具、边缘 / 本地一体机、评估环境。它的
+取舍是结构性的：SQLite 是单写者，因此不适合多节点 ObjectOS、高并发
+写入或共享数据库的部署。这些场景请使用 PostgreSQL。
+
+当你确实在生产中使用 SQLite 时，让它稳定运行的配置和备份方案是配套的：
+
+**运行时配置**
+
+- 启用 WAL：`PRAGMA journal_mode=WAL`（读不阻塞写;崩溃安全）。
+- `PRAGMA synchronous=NORMAL` 是桌面 / 单机生产的常用默认值 —— 在
+  WAL 下安全，且比 `FULL` 快得多。
+- 数据库文件放在**本地磁盘**上。**不要**放在 NFS、SMB，或者在运行时
+  正在使用的情况下放在被 Dropbox / OneDrive / iCloud 同步的目录里
+  —— SQLite 的文件锁在这些位置不可靠，这是 SQLite 部署最常见的损坏
+  原因。
+
+**热快照（无需停机）**
+
+运行时继续对外服务的同时，可以用 SQLite 的 Online Backup API 或
+`VACUUM INTO` 生成一致性快照：
+
+```sql
+VACUUM INTO '/var/backups/objectos/db-2026-05-27T13-00Z.sqlite';
+```
+
+按照你的 RPO 节奏用 cron、systemd timer 或运行时内置 scheduler 触发。
+给每份快照打上当时所用的产物版本标签，以便将数据库和产物作为一组
+回滚（见下方 [产物版本化](#产物版本化)）。
+
+**异地副本**
+
+本地快照扛不住磁盘故障。把每份快照推送到可持续存储：
+
+- 服务器 / VM：推到 S3 或任何 S3 兼容 bucket（你大概率已经为
+  `storage` 能力配过一个了）。
+- 桌面端应用：把快照写入用户控制的同步目录（OneDrive / iCloud /
+  Google Drive）—— 这里可以接受，因为快照文件是**关闭且不可变**的，
+  和活动数据库不同。
+
+**持续复制（更低 RPO）**
+
+在不放弃 SQLite 的前提下要拿到分钟级以下的 RPO，把
+[Litestream](https://litestream.io) 与 ObjectOS 进程一起跑。它把 WAL
+流式复制到 S3 兼容存储，并支持时间点恢复。当单节点 SQLite 部署需要
+近零数据丢失时，这是推荐路径。
+
+**恢复**
+
+停掉运行时，用选定的快照替换数据库文件（或执行 `litestream
+restore`），用产生该快照时所对应的产物版本重新启动运行时。
+
 ## 产物版本化
 
 把发布的产物视为不可变。给每份产物打上其编译所用的发布 id 标签
@@ -57,6 +111,7 @@ ObjectOS **不**需要对其容器文件系统做单独备份。缓存目录
 | 等级 | RPO | RTO | 备注 |
 |---|---|---|---|
 | 评估 / 演示 | 尽力而为 | 尽力而为 | SQLite 快照即可 |
+| 桌面端应用 / 小团队单节点 | ≤ 1 小时（快照）或 ≤ 秒级（Litestream） | 分钟级 | SQLite + WAL + 定时 `VACUUM INTO` + 异地副本 |
 | 单租户生产 | ≤ 15 分钟 | ≤ 1 小时 | 托管 PostgreSQL + PITR + 热镜像 |
 | 多租户 / 受监管 | ≤ 5 分钟 | ≤ 30 分钟 | 高可用数据库 + 多可用区 ObjectOS + 经过演练的 runbook |
 
diff --git a/content/docs/operate/backup.mdx b/content/docs/operate/backup.mdx
@@ -31,7 +31,7 @@ Match the strategy to the driver:
 | PostgreSQL | Continuous WAL archiving + base backup; point-in-time restore |
 | Turso / libSQL | Use the platform's backup feature; export to SQLite locally for cold copy |
 | MongoDB | Replica-set snapshots; oplog for PITR |
-| SQLite (single-node evaluation only) | File-level snapshot when the runtime is idle; **not** production-grade |
+| SQLite (single-node / desktop) | WAL mode + hot snapshots via `VACUUM INTO` or the Online Backup API; optionally Litestream for continuous replication — see [SQLite deployments](#sqlite-deployments) below |
 
 Whatever the driver, validate that:
 
@@ -40,6 +40,68 @@ Whatever the driver, validate that:
   traffic;
 - restore tests are exercised end-to-end at least once a quarter.
 
+## SQLite deployments
+
+SQLite is the default driver and is a legitimate production choice for
+**single-node** ObjectOS — desktop apps, internal tools for a small
+team, edge / on-prem appliances, evaluation environments. The trade-off
+is structural: SQLite is single-writer, so it does not fit multi-node
+ObjectOS, high concurrent write throughput, or shared-database
+deployments. For those, use PostgreSQL.
+
+When you do run SQLite in production, the configuration that makes it
+safe and the backup recipe go together:
+
+**Runtime configuration**
+
+- Enable WAL: `PRAGMA journal_mode=WAL` (readers don't block the
+  writer; crash-safe).
+- `PRAGMA synchronous=NORMAL` is the usual desktop/single-node default
+  — safe with WAL, much faster than `FULL`.
+- Keep the database file on **local disk**. Do **not** put it on NFS,
+  SMB, or inside a folder synced by Dropbox / OneDrive / iCloud while
+  the runtime is running — SQLite's locking is unreliable on those and
+  this is the most common way SQLite deployments corrupt.
+
+**Hot snapshot (no downtime)**
+
+The runtime keeps serving traffic while you take a snapshot using
+SQLite's Online Backup API or `VACUUM INTO`:
+
+```sql
+VACUUM INTO '/var/backups/objectos/db-2026-05-27T13-00Z.sqlite';
+```
+
+Schedule it (cron, systemd timer, or the in-process scheduler) at a
+cadence matching your RPO. Tag each snapshot with the artifact version
+that produced it so you can roll database + artifact back together
+(see [Artifact versioning](#artifact-versioning) below).
+
+**Offsite copy**
+
+A local snapshot doesn't survive disk loss. Push each snapshot to
+durable storage:
+
+- Server / VM: push to S3 or any S3-compatible bucket (you likely
+  already have one configured for the `storage` capability).
+- Desktop app: write the snapshot to a user-controlled sync folder
+  (OneDrive / iCloud / Google Drive) — acceptable here because the
+  snapshot file is **closed and immutable**, unlike the live database.
+
+**Continuous replication (lower RPO)**
+
+For sub-minute RPO without giving up SQLite, run
+[Litestream](https://litestream.io) alongside the ObjectOS process. It
+streams the WAL to S3-compatible storage and supports point-in-time
+restore. This is the recommended path when a single-node SQLite
+deployment needs near-zero data loss.
+
+**Restore**
+
+Stop the runtime, replace the database file with the chosen snapshot
+(or run `litestream restore`), start the runtime against the same
+artifact version that produced the snapshot.
+
 ## Artifact versioning
 
 Treat published artifacts as immutable. Tag each artifact with the
@@ -61,6 +123,7 @@ A workable starting target for customer deployments:
 | Class | RPO | RTO | Notes |
 |---|---|---|---|
 | Evaluation / demo | best-effort | best-effort | SQLite snapshot is fine |
+| Desktop app / small-team single-node | ≤ 1 hour (snapshots) or ≤ seconds (Litestream) | minutes | SQLite + WAL + scheduled `VACUUM INTO` + offsite copy |
 | Single-tenant production | ≤ 15 min | ≤ 1 hour | Managed PostgreSQL with PITR + warm image |
 | Multi-tenant / regulated | ≤ 5 min | ≤ 30 min | HA database + multi-AZ ObjectOS + tested runbook |
 
