跳到主要内容

gbrain export 命令详解

GBrain 的 export 命令用于将数据库中的内容批量导出到本地文件系统。
区别于 sync 的持续双向同步，export 是一次性操作，适合备份、迁移和离线查看场景。

📖 背景：为什么需要导出？​

GBrain 的知识数据默认存储在数据库中。export 命令可以将其还原为 Markdown 文件，主要用于：

场景说明
备份将数据库内容转储为可读的文件，可版本控制
迁移将旧版 GBrain 数据库迁移到新实例
离线查看导出后无需数据库即可浏览内容
文件恢复从数据库中恢复仅存储在 DB 中的页面（--restore-only）

📋 命令概览​

gbrain export [选项]

主要选项​

选项说明默认值
--dir <路径>导出目录./export
--repo <路径>GBrain 仓库路径自动解析
--type <类型>按页面类型过滤不过滤
--slug-prefix <前缀>按 slug 前缀过滤不过滤
--restore-only仅恢复 DB-only 文件关闭

🚀 子命令详解​

基础导出​

最简单的用法，将整个数据库导出为 Markdown 文件：

gbrain export --dir ~/my-export

这会：

  1. 读取数据库中的所有页面
  2. 将每个页面渲染为 Markdown 文件（包含 frontmatter、内容、标签）
  3. 写入到 ~/my-export/ 目录下
  4. 配合原始数据（raw data）作为侧边 JSON 文件（.raw/ 目录）

导出目录结构示例：

my-export/
├── index.md
├── projects/
│   ├── project-a.md
│   └── .raw/
│       └── project-a.json     ← 原始数据（元数据、嵌入向量等）
├── wiki/
│   ├── getting-started.md
│   └── .raw/
│       └── getting-started.json
└── ...

每条页面都有一个对应的 .raw/{slug}.json 侧边文件，包含该页面的所有原始元数据（包括来自不同来源的额外数据字段）。

按类型过滤​

如果只想导出特定类型的页面，使用 --type 参数：

gbrain export --dir ./wiki-only --type wiki
gbrain export --dir ./code-only --type code
gbrain export --dir ./pages-only --type page

常见的页面类型包括 wiki、code、page、doc 等。

按前缀过滤​

按 slug 前缀筛选要导出的页面：

gbrain export --dir ./kb-export --slug-prefix knowledge

这会只导出 slug 以 knowledge 开头的页面（如 knowledge/ai, knowledge/frontend 等）。

可以与其他选项组合使用：

gbrain export --dir ./kb-wiki --type wiki --slug-prefix knowledge

恢复仅数据库存储的文件（--restore-only）​

GBrain 的存储分层（Storage Tiering）功能允许部分页面仅存储在数据库中（db_only），而不在文件系统上保留文件。--restore-only 选项用于将这些仅存在于 DB 中的文件还原到本地文件系统。

gbrain export --restore-only --repo /path/to/gbrain/repo --dir ./restored

工作原理：

  1. 读取仓库的 gbrain.yml 中的 storage.db_only 配置
  2. 对于每个标记为 db_only 的目录，查询数据库中存在的页面
  3. 如果该页面在文件系统上不存在（db_only 的正常行为），则将其导出到指定目录
  4. 如果文件已存在于文件系统上，则跳过

典型使用场景：

# 1. 查看当前存储配置
gbrain storage status

# 2. 恢复所有 db_only 文件
gbrain export --restore-only --repo /path/to/repo --dir ./restored

# 3. 仅恢复特定前缀下的 db_only 文件
gbrain export --restore-only --repo /path/to/repo --dir ./restored --slug-prefix "archive/"

⚠️ 注意： --restore-only 要求 --repo 指向一个包含有效 gbrain.yml 的仓库，否则会报错退出。

指定仓库路径​

如果你的当前工作目录不在 GBrain 仓库内，或者需要显式指定仓库位置：

gbrain export --repo /path/to/braindir --dir /tmp/export

这会读取 /path/to/braindir 下的存储配置和数据库进行导出。

常规导出（非 --restore-only）不需要 --repo 也能运行，因为导出操作本身不依赖仓库文件。只有当使用了 --restore-only 时，--repo 才是必须的。

📝 输出格式​

Markdown 文件​

每个页面导出为一个 .md 文件，包含完整的 frontmatter 和内容：

---
title: 页面标题
type: wiki
tags: [tag1, tag2]
created: 2024-01-01
modified: 2024-06-01
---

# 页面标题

页面内容…

原始数据侧边文件​

每个 / / 文件所在目录 下会生成 .raw/{slug}.json 文件，包含：

{
  "source1": { ... },
  "source2": { ... }
}

这些原始数据可能包含：

  • 嵌入向量（embedding）
  • 来源元数据
  • 外部系统同步的额外字段
  • 自定义属性

侧边文件是为了保留那些无法映射到 Markdown frontmatter 的原始结构化数据，在重新导入（gbrain import）时重建完整状态。

⚡ 完整示例​

示例 1：日常备份​

# 完整数据库备份
gbrain export --dir /backup/gbrain-$(date +%Y%m%d)

# 仅备份 wiki 类型
gbrain export --dir /backup/gbrain-wiki-$(date +%Y%m%d) --type wiki

示例 2：迁移数据​

# 从旧数据库导出
cd /old-braindir
gbrain export --dir /tmp/migration

# 导入到新数据库
cd /new-braindir
gbrain import --dir /tmp/migration

示例 3：恢复 DB-only 文件​

# 查看存储配置
gbrain storage status

# 恢复所有丢失的 db_only 文件
gbrain export --restore-only --repo /path/to/repo --dir /path/to/restore

# 恢复特定范围的 db_only 文件
gbrain export --restore-only --repo /path/to/repo --dir ./archive-restore --slug-prefix "archive/"

示例 4：带过滤的组合导出​

# 导出所有 code 类型 + 以 "docs/" 开头的页面
gbrain export --dir ./code-export --type code
gbrain export --dir ./docs-export --slug-prefix docs

🔧 高级用法​

导出后的导入​

导出的马克数据可以通过 gbrain import 命令重新导入：

# 导入之前导出的文件
gbrain import --dir /path/to/export

导入会读取 Markdown 文件及其对应的 .raw/{slug}.json 侧边文件，恢复完整的页面状态。

与 sync 的区别​

特性export（导出）sync（同步）
操作方式一次性持续监听
数据流向数据库 → 文件系统双向（数据库 ⇄ 文件系统）
自动更新❌ 需要手动重新执行✅ 自动同步变化
适用场景备份、迁移、恢复日常编辑工作流
资源占用低（任务结束后退出）中（后台进程持续运行）

更多关于 sync 命令的细节，请参考 Sync 命令详解 和 导出 vs 同步。

📚 相关文档​

提示： export 是 GBrain 数据生命周期管理的重要工具。对于日常编辑，建议使用 sync 保持文件与数据库的双向同步；对于备份和迁移场景，export 是更合适的选择。