跳到主要内容

GBrain Sync 命令详解

gbrain sync 是 GBrain 的核心数据同步命令，负责将本地 Git 仓库中的知识库内容增量同步到数据库中。当前版本：v0.41.14.0。

一、Sync 是什么？​

gbrain sync 实现了 基于 Git 的增量同步：通过对比上次同步的 commit 和当前 HEAD 之间的差异，自动识别新增、修改、删除和重命名的文件，将它们导入到 GBrain 的数据库引擎中。

核心设计理念​

特性说明
增量同步基于 git diff --name-status 检测变更，只处理变化的文件
Git 驱动以 Git commit 为锚点，确保数据一致性和可追溯性
策略感知支持 markdown / code / auto 三种同步策略
并发处理大批量文件自动并行导入，默认 4 个 worker
失败恢复解析失败的文件会被记录，支持跳过或重试
自动嵌入同步后自动生成 embedding（超过 100 个文件时跳过）

同步数据流​

Git 仓库 (本地文件系统)
       │
       │  git diff --name-status -M LAST_COMMIT..HEAD
       │
   变更清单 (Added / Modified / Deleted / Renamed)
       │
       │  isSyncable() 过滤
       │
   可同步文件
       │
       │  importFile() 逐个导入
       │
   GBrain 数据库 (Postgres / PGLite)
       │
       │  extractLinks + extractTimeline
       │
   关联关系 + 时间线
       │
       │  runEmbedCore() 自动生成 embedding
       │
   向量数据库

二、基本用法​

最简单的同步​

# 同步默认 source（增量同步）
gbrain sync

# 输出示例：
# Sync: +3 ~2 -1 R0, 15 chunks, 2340ms

这条命令会：

  1. 检查 Git 仓库的 origin remote
  2. 执行 git pull（拉取最新代码）
  3. 对比上次同步的 commit 和当前 HEAD
  4. 将变化的文件导入数据库
  5. 自动提取链接和时间线
  6. 自动生成 embedding（文件数 ≤ 100 时）

指定仓库路径​

# 同步指定路径的仓库
gbrain sync --repo ~/my-knowledge

# 同步指定 source
gbrain sync --source my-brain

如果不传 --repo 也不传 --source，默认路径按以下顺序确定：

  1. 从 sources 表读取 default source 的 local_path（即 gbrain init 或 gbrain sources add 时设定的路径）
  2. 如果 default source 的 local_path 为空（v0.18 前的旧配置），回退到全局配置 sync.repo_path
  3. 如果都找不到，报错退出

可以通过 gbrain sources status 或 gbrain config show | grep repo_path 查看当前默认 sync 的是哪个文件夹。

三、常用选项​

预览模式​

# 预览同步内容（不实际写入）
gbrain sync --dry-run

# 输出示例：
# Sync dry run: a1b2c3d4..e5f6g7h8
#   Added: note/new-article.md, people/john-doe.md
#   Modified: note/existing.md
#   Deleted: note/old-draft.md
#   Renamed: note/old-name.md -> note/new-name.md

跳过 Embedding​

# 只导入文本，不生成 embedding
gbrain sync --no-embed

# 同步完成后手动生成
gbrain embed --stale

适用场景：

  • Embedding 服务不可用时
  • 批量导入大量文件时（>100 个文件默认跳过）
  • 想控制 embedding 成本时

强制全量同步​

# 忽略上次 commit，重新导入所有文件
gbrain sync --full

使用场景：

  • 首次初始化后发现问题
  • 底层 chunker 版本升级（pipeline 变更）
  • 怀疑数据不一致时

跳过 Git Pull​

# 同步前不执行 git pull
gbrain sync --no-pull

适用场景：

  • 离线环境
  • 仓库没有 origin remote
  • 测试环境

并行 Worker 数​

# 指定导入阶段的并行 worker 数量
gbrain sync --workers 8

# 别名
gbrain sync --concurrency 8

自动并发规则：

条件Worker 数
变更文件 < 501（串行）
变更文件 > 1004（默认自动）
50-100 之间取决于显式设置
PGLite 引擎始终 1

持续监听模式​

# 每 60 秒自动同步一次（默认间隔）
gbrain sync --watch

# 自定义间隔（秒）
gbrain sync --watch --interval 30

# Ctrl+C 停止

适用场景：

  • 开发调试
  • 持续集成
  • 长时间运行监控

注意：连续 5 次同步失败会自动停止。

JSON 输出​

# 输出结构化 JSON（适用于 CI/CD 或脚本处理）
gbrain sync --all --json | jq .

# 输出示例：
# {
#   "schema_version": 1,
#   "sources": [...],
#   "parallel": 4,
#   "ok_count": 3,
#   "error_count": 0
# }

四、多 Source 同步​

同步所有 Source​

# 同步所有已注册的 source
gbrain sync --all

并行多 Source 同步​

# 最多 4 个 source 并行同步（默认）
gbrain sync --all

# 指定并行数量
gbrain sync --all --parallel 8

# 串行执行
gbrain sync --all --serial

并行连接数计算：

总连接数 = parallel × workers × 2 + 父进程池

例如：--parallel 4 --workers 4 → 4 × 4 × 2 = 32 连接 + 父进程池

当连接数 > 16 时会在 stderr 输出警告。

限制 Source 数量​

# 最多同步 3 个 source
gbrain sync --all --max-sources 3

同步指定 Source​

# 只同步某个 source
gbrain sync --source my-brain

# 配合 dry-run 使用
gbrain sync --source my-brain --dry-run

五、同步策略​

三种策略​

# 只同步 Markdown 文件（默认）
gbrain sync --strategy markdown

# 只同步代码文件
gbrain sync --strategy code

# 自动检测（Markdown + 代码）
gbrain sync --strategy auto

Markdown 策略​

同步 .md 和 .mdx 文件，自动跳过以下文件：

  • schema.md、index.md、log.md、README.md（元数据文件）
  • .git/、.obsidian/、.raw/ 等隐藏目录
  • node_modules/、ops/ 等生成目录

Code 策略​

支持 50+ 种编程语言的文件扩展名，包括但不限于：

语言扩展名
TypeScript.ts .tsx .mts .cts
JavaScript.js .jsx .mjs .cjs
Python.py
Rust.rs
Go.go
Java.java
C/C++.c .h .cpp .cc .cxx .hpp
Ruby.rb
PHP.php
SQL.sql
Terraform.tf .tfvars .hcl

Slug 生成规则​

Markdown 文件：

people/Alice Smith.md      →  people/alice-smith
notes/2024-01-01.md        →  notes/2024-01-01
Apple Notes/会议记录.md     →  apple-notes/会议记录

代码文件（扁平化）：

src/core/chunkers/code.ts  →  src-core-chunkers-code-ts
lib/utils/format.py        →  lib-utils-format-py

六、故障处理​

查看同步失败记录​

# 查看诊断信息
gbrain doctor

跳过失败的文件​

# 标记当前失败为已确认，继续同步
gbrain sync --skip-failed

重试失败的文件​

# 重新尝试之前失败的文件
gbrain sync --retry-failed

失败原因分类​

sync 会自动将失败归类为以下错误码：

错误码含义
YAML_PARSEYAML 解析失败
YAML_DUPLICATE_KEYYAML 中有重复 key
SLUG_MISMATCHfrontmatter slug 与路径不匹配
MISSING_OPEN缺少 frontmatter 开始标记 ---
MISSING_CLOSE缺少 frontmatter 结束标记
FILE_TOO_LARGE文件过大
EMBEDDING_NO_CREDS缺少 API 密钥
EMBEDDING_RATE_LIMIT嵌入服务限流
TAKES_TABLE_MALFORMEDtakes 表格格式错误
PAGE_JUNK_PATTERN内容被判定为低质量

失败的记录位置​

失败记录保存在 ~/.gbrain/sync-failures.jsonl 中，每行一条 JSONL 记录：

{"path":"note/broken.md","error":"YAML parse failed","code":"YAML_PARSE","commit":"a1b2c3d4","line":3,"ts":"2026-06-11T03:00:00.000Z"}

七、分布式脑同步​

Push-Triggered 同步​

适用于联邦脑（Federated Brain）场景，通过 webhook 或手动触发异步同步：

# 为指定 source 排队一个同步任务
gbrain sync trigger --source <id> [--priority high|normal|low]

# 输出：
# job_id=42

优先级说明：

优先级数值说明
high-10最高，抢占自动同步
normal0默认
low5最低

典型场景：

  • GitHub webhook → gbrain sync trigger --source <repo>
  • 手动 git pull 后手动触发
  • CI/CD 流水线集成

自动 Embed 回填​

当使用 --all 模式时，sync 会自动为每个 source 排队 embed-backfill 任务：

# 同步所有 source，自动回填 embedding
gbrain sync --all

# 禁止自动回填
gbrain sync --all --no-auto-embed

回填任务会受以下限制：

  • 24 小时花费上限（默认 $20）
  • Source 级别冷却时间（D19 配置）

八、锁机制​

锁的类型​

锁类型锁 ID适用场景
全局锁gbrain-sync单 source（向后兼容）
按 Source 锁gbrain-sync:<sourceId>多 source / 联邦脑

锁的竞争处理​

当检测到锁被占用时，会输出详细信息：

Another sync is in progress (lock gbrain-sync:my-brain held by pid 12345 on hostname, 
started 5m30s ago).
If pid 12345 is dead, re-run with --break-lock to clear it:
  gbrain sync --break-lock --source my-brain
Or wait for the holder to finish.

安全解锁​

# 安全解锁（自动检查持有者状态）
gbrain sync --break-lock --source my-brain

安全条件（满足其一即可）：

  1. 持有者在本机 + TTL 已过期
  2. 持有者在本机 + PID 已死亡 + 锁超过 60 秒

拒绝条件：

  • 持有者在远程主机（跨主机解锁不安全）
  • PID 还存活

强制解锁​

# 强制解锁（跳过检查，危险！）
gbrain sync --force-break-lock --source my-brain

⚠️ 强制解锁会直接删除锁记录，可能导致数据竞争。仅在确定持有者已死时使用。

批量解锁​

# 解锁所有 source
for src in $(gbrain sources list --json | jq -r '.[].id'); do
  gbrain sync --break-lock --source "$src"
done

九、同步状态与监控​

查看 Source 状态​

# 查看所有 source 的同步状态
gbrain sources status

输出包含：

  • 最后同步时间
  • 页面数量
  • Chunk 总数和未嵌入数量
  • Embedding 覆盖率
  • 新鲜度分类（fresh / stale / severe / unknown）

新鲜度阈值：

状态距上次同步
fresh< 24 小时
stale24-72 小时
severe> 72 小时
unknown从未同步

同步结果状态码​

状态含义
up_to_date没有变更
synced增量同步完成
first_sync首次全量同步完成
dry_run预览模式
blocked_by_failures有文件解析失败，已阻止

十、高级场景​

分离嵌入步骤​

# 第一步：只导入文本
gbrain sync --no-embed

# 第二步：单独生成 embedding
gbrain embed --stale

适用场景：

  • Embedding 服务 API 配额不足
  • 需要先确认导入内容再付费
  • 大批量导入时控制成本

成本预估​

# 预览多 source 同步的成本
gbrain sync --all --dry-run

# 输出示例：
# sync --all preview: 1500 files across 3 source(s),
# ~500,000 tokens, est. $2.50 on text-embedding-3-small

非 TTY 环境下（如 CI/CD），需要使用 --yes 确认：

gbrain sync --all --yes

CJK 路径支持​

sync 命令支持中文、日文、韩文等非 ASCII 路径：

# 内部设置 git core.quotepath=false
# 确保 diff 输出为 UTF-8 而非转义

# 中文路径正常工作
gbrain sync --repo ~/知识库

Detached HEAD 处理​

当 Git 仓库处于 detached HEAD 状态时：

Detached HEAD on /path/to/repo; skipping git pull. 
Syncing from local working tree.

sync 会跳过 git pull，直接从本地工作树同步。

十一、常见问题​

Q1: Sync 时提示 "Not a git repository"​

# 确保目录是 Git 仓库
cd ~/my-knowledge
git init
git add .
git commit -m "initial"

# 然后再同步
gbrain sync --repo ~/my-knowledge

Q2: 同步卡住不动​

# 检查是否有锁在运行
gbrain doctor

# 如果锁超时，强制解锁
gbrain sync --force-break-lock

Q3: Embedding 失败怎么办​

# 先跳过 embedding
gbrain sync --no-embed

# 修复 API 配置后重新生成
gbrain embed --stale

Q4: 如何查看同步了哪些文件​

# 使用 dry-run 预览
gbrain sync --dry-run

# 或者检查日志
gbrain sync 2>&1 | grep "Added\|Modified\|Deleted"

Q5: 增量同步不生效​

# 检查上次同步的 commit
gbrain doctor

# 强制全量同步
gbrain sync --full

Q6: 文件被跳过但原因不明​

# 检查 sync-failures 日志
cat ~/.gbrain/sync-failures.jsonl | jq .

# 跳过已知失败，继续同步
gbrain sync --skip-failed

十二、最佳实践​

1. 日常同步​

# 开发环境：watch 模式
gbrain sync --watch

# 生产环境：定时同步
# crontab -e
0 * * * * cd ~/knowledge && gbrain sync 2>&1 >> ~/gbrain-sync.log

2. CI/CD 集成​

#!/bin/bash
# .github/workflows/sync.sh

# 同步所有 source，JSON 输出供后续处理
gbrain sync --all --json --yes > sync-result.json

# 检查是否有错误
ERROR_COUNT=$(cat sync-result.json | jq '.error_count')
if [ "$ERROR_COUNT" -gt 0 ]; then
  echo "Sync failed!"
  exit 1
fi

3. 控制 Embedding 成本​

# 大批量导入时跳过 embedding
gbrain sync --no-embed --all --yes

# 在低峰时段生成 embedding
gbrain embed --stale

4. 联邦脑管理​

# 添加远程 source
gbrain sources add my-repo --url https://github.com/user/repo.git

# 手动触发同步
gbrain sync trigger --source my-repo --priority high

# 查看状态
gbrain sources status

5. 监控同步健康度​

# 定期检查
gbrain doctor

# 检查 embedding 覆盖率
gbrain sources status | jq '.sources[] | {name: .name, coverage: .embedding_coverage_pct}'

十三、相关命令​

命令用途
gbrain init初始化 GBrain
gbrain import一次性导入（非 Git）
gbrain embed --stale重新生成 embedding
gbrain sources add添加 data source
gbrain sources list列出所有 source
gbrain sources status查看同步状态
gbrain export导出数据
gbrain doctor诊断问题
gbrain query查询知识库

总结​

gbrain sync 是 GBrain 数据管理的核心命令，实现了基于 Git 的增量同步机制。关键要点：

  1. 增量同步：基于 Git commit 差异，只处理变化的文件
  2. 多策略支持：markdown / code / auto 三种同步策略
  3. 并发处理：大文件量自动并行导入
  4. 失败恢复：解析失败自动记录，支持跳过和重试
  5. 联邦脑：支持多 source 并行同步和异步触发
  6. 锁保护：防止并发同步导致数据竞争

相关文档​

本文档基于 GBrain v0.41.14.0 源码分析整理