用 busabase-cli backup 和 restore 把整个 Busabase space 备份成一个可移植的归档文件——保留完整历史、原始 ID、真实文件——并随时还原。

备份与还原

busabase-cli backup 会把整个 Busabase space——每一个节点、base、记录、字段值、文档正文、上传的文件,以及(可选的)完整 Change Request / commit 历史——导出成一个可移植的 .bbdump 归档文件,busabase-cli restore 再把它还原回去。适用于灾难恢复、在本地自托管实例和 Cloud 之间搬迁 space,或者在做有风险的改动前先留一份离线快照。

本页此前介绍的是一个独立的 busabase-dump 命令行工具,命令写作 busabase-dump export / busabase-dump import。该工具从未发布过;这套工作流现在直接内置于 busabase-cli——一个工具、一次登录、一份配置文件。执行 npm i -g busabase-cli 安装。

安装与运行

npx busabase-cli backup
npx busabase-cli restore space.bbdump

如果 ~/.busabase/.env 里已经有 base URL、API key 和 space id,不需要单独配置——读取的就是 busabase-cli login 写入的同一份文件。如果你已经连接过 agent(参见接入你的 Agent),备份不需要任何额外配置即可直接使用。

备份一个 space

npx busabase-cli backup -o space.bbdump

这会遍历 space 里的每一张表——节点、base/字段/视图、记录和字段值、记录关联、asset 及其上传的字节内容、文档正文,以及(默认情况下)完整的 commit/Change Request/审核/审计历史——并写入一个 .bbdump 文件(流式 tar 归档,zstd 压缩)。

参数	作用
`-o, --out-file <file>`	归档输出路径(默认 `space.bbdump`)
`--no-history`	跳过 commits/Change Requests/operations/comments/reviews/审计事件,只保留当前状态
`--space-id <id>`	要备份的 space(默认取 `BUSABASE_SPACE_ID` / `~/.busabase/.env`)

Vault 密钥和 webhook 签名密钥永远不会被写入备份——.bbdump 归档文件可以安全地存储或传输,不会泄露凭证。

还原到一个 space

npx busabase-cli restore space.bbdump

还原是完整保真的:每一个节点、base、记录、历史记录都会带着原始 ID还原回来,记录之间的关联和引用保持完整。正因如此,目标 space 必须是真正为空的(只有自动创建的 workspace 根节点)——restore 会拒绝写入已经有内容的 space,所以还原操作永远不会悄悄合并进或覆盖掉已有的工作内容。

每张表写入完成后,restore 会做一次完整性检查,把任何悬空引用(比如某个字段值指向一个从未被还原的字段、某条记录关联缺少对端、某个文件的字节内容没能成功写入存储)作为警告报告出来,让你在信任还原结果之前明确知道该检查什么。

选择还原的目标位置

用 --base-url / --space-id 指定副本要落到哪里——同一台服务器上的另一个 space、另一个自托管实例,或是 Cloud 上的一个 workspace:

npx busabase-cli restore space.bbdump \
  --base-url https://busabase.com \
  --api-key <token> \
  --space-id <target-space-id>

backup 还是 export——我该用哪个?

两件不同的事,两种刻意区分开的格式:

	`backup` / `restore`	`export` / `install`
格式	一个压缩后的 `.bbdump` 归档文件	一棵可阅读、可 diff 的目录树,能直接推到 GitHub
携带什么	全部:原始行数据、原始 ID、历史、评论、审核记录、审计事件、权限	只有当前状态——内容本身,不含它的过去
目标 space	必须为空	装进一个已有的 space,和里面已有的内容并存
ID	原样保留	安装时重新生成
用在什么场景	灾难恢复、整体搬迁一个 space	分享一份模板、用 git 给内容做版本管理

如果你想的是"给别人一份这个 base 的副本,让他从这里开始",那你要的是 export。如果你想的是"万一服务器烧了,我能把这个 space 一模一样地重建出来",那你要的是 backup。

配置

和其他所有 Busabase 客户端一样的优先级:

内容	参数	环境变量	保存位置
服务地址	`--base-url <url>`	`BUSABASE_BASE_URL`	`~/.busabase/.env`
API key	`--api-key <token>`	`BUSABASE_API_KEY`	`~/.busabase/.env`
Space	`--space-id <id>`	`BUSABASE_SPACE_ID`	`~/.busabase/.env`

如果 backup/restore 连不上服务器,或者返回 401/403,参见故障排查——这里适用和 busabase-cli 其他部分相同的主机/鉴权规则。

不支持的功能

--state-only 能被识别,但不会实现——它的位置已经由 export / install 取代:同样是"只要内容、不要历史"的需求,而后者给出的是一种你真的能读、能 diff 的格式。执行 backup --state-only 会打印这段说明并退出。

以下选项 CLI 能识别,但目前还没实现——会直接明确报错退出,不会做出预期之外的行为:

--resume(续传一个中途中断的还原)
--into-folder(只对 state-only 归档有意义——请改用 install --into-folder)

另见:安装与导出 · 接入你的 Agent · API Tokens · REST API · 故障排查

备份与还原

On this page