# 用户数据与迁移

> Crib 在你的 Mac 上保存哪些文件、哪些属于个人资料，怎样备份和恢复，以及从 PGDash 一次性迁移的过程。

---

LLMS 索引： [llms.txt](/llms.txt)

---

## 用户目录 {#layout}

Crib 的数据在 `~/Library/Application Support/Crib/`。下面列出与你有关的部分，有些文件在用到相应功能后才出现：

```filetree {title="~/Library/Application Support/Crib/" wrap=true}
- user.sqlite             # 个人资料：笔记、书签、标签、阅读历史、更正
- preferences.json        # 设置
- session.json            # 窗口、标签页和阅读位置
- snippets.json           # 片段库
- backups/                # 个人资料库升级结构前自动做的备份
- Library/                # 下载或导入的资料包、搜索世代和登记表
  - packs/
  - generations/
  - registry.sqlite
- Distribution/           # 版本目录缓存
- Distribution-partials/  # 中断下载的已下载部分，保留 7 天
- Distribution-rejected/  # 无法再通过校验的旧目录缓存，保留最近 5 份
- api/                    # 本地 API 的地址、密钥和锁，启用 API 后出现
- crib-migration.json     # 从 PGDash 迁移的记录，迁移过才有
```

App 内置的资料包和初始搜索索引在 `Crib.app/Contents/Resources/Library` 里，只读，随 App 一起替换。

## 个人资料与内容 {#personal-vs-content}

| 类别 | 文件 | 丢了会怎样 |
| --- | --- | --- |
| 个人资料 | `user.sqlite`、`snippets.json`、`preferences.json`、`session.json` | 无法从别处恢复，需要自己备份 |
| 内容 | `Library/`、`Distribution*/` | 可以重新下载或导入；内置内容随 App 恢复 |
| 运行状态 | `api/` | 重新启用本地 API 时重建 |

下载、导入、启用、停用、卸载资料包和恢复资料组合都不写个人资料。卸载一个版本不会删除挂在上面的笔记。

## 备份个人资料 {#backup}

| 命令 | 位置 | 得到什么 |
| --- | --- | --- |
| 备份个人资料… | “资料库 → 维护”，或个人资料列表的更多菜单 | 一个 SQLite 文件，默认名 `Crib-user-backup.sqlite`，含笔记、书签、标签、阅读历史和更正 |
| 导出个人资料… | 个人资料列表的更多菜单 | 一个可移植的文件夹，默认名 `Crib-personal` |
| 导出更正… | 个人资料列表的更多菜单 | 只含更正的文件夹，默认名 `Crib-corrections` |
| 导出片段库… | “设置 → 片段”的更多菜单 | 片段库文件 |

- 备份和导出前，Crib 先保存所有正在编辑的草稿。与其他编辑冲突的草稿另存为新笔记。
- 备份用 SQLite 的在线备份完成，包含尚未合并进主文件的已提交数据。Crib 运行时直接复制 `user.sqlite` 可能漏掉这部分。
- 备份不能保存到 Crib 的用户目录里。
- 片段和设置不在个人资料备份里，片段要单独导出。

## 恢复个人资料 {#restore}

- **导入个人资料…**：读入一个导出的文件夹，与现有个人资料合并；冲突的条目另存为副本，不覆盖。
- **从备份恢复…**：只在个人资料打不开时出现（提示“无法打开个人资料”或“个人资料需要更新版本的 Crib”）。Crib 先打开备份的副本检查，通过后把原来的 `user.sqlite` 改名为 `user-unreadable-<时间>.sqlite` 保留，再换上备份，然后重新打开。
- **新建个人资料…**：个人资料打不开时，从空白开始；原文件同样改名保留。

个人资料打不开时，阅读和搜索照常可用，只有笔记、书签、更正和阅读历史停用。

## 从 PGDash 迁移 {#migration}

Crib 以前叫 PGDash，数据在 `~/Library/Application Support/PGDash/`。Crib 启动时、打开任何数据之前，会检查是否需要迁移。

### 迁移过程 {#migration-steps}

1. 确认 PGDash 没有在运行。PGDash 仍在运行时迁移失败，提示退出 PGDash 后重试。
1. 清点旧目录中每个文件的大小和 SHA-256。遇到符号链接、多个硬链接或特殊文件就停止。
1. 把整个旧目录复制到用户资料目录旁边的暂存目录 `.crib-migration-<编号>`，再清点一次；复制期间旧目录有变化就停止。
1. 用 SQLite 在线备份从副本重建 `user.sqlite` 和 `Library/registry.sqlite`，并把登记表里的路径改到新目录。
1. 旧的 `api/` 改名为 `legacy-api-<编号>` 存档。在 Crib 中需要重新启用本地 API。
1. 写入迁移记录 `crib-migration.json`，同步到磁盘，然后一次性改名为 `Crib/`。
{.steps}

旧目录从头到尾只读：不写入、不创建 WAL 文件，也不删除。迁移完成后它原样留在原处。

### 状态文件 {#migration-state}

迁移状态记在 `~/Library/Application Support/.Crib-migration-state.json`，在 Crib 目录之外，因此失败的尝试不会被误认为已迁移。

| 状态 | 含义 |
| --- | --- |
| `pending` | 正在迁移 |
| `failed` | 上次迁移失败 |
| `done` | 已完成 |
| `declined` | 你选择了跳过，不再尝试 |
| `replaceRequested` | 你要求用旧资料替换现有的 Crib 资料，下次启动时执行 |

### 迁移失败 {#migration-failed}

迁移失败时不创建 Crib 目录，Crib 以只读方式运行：内置文档照常阅读和搜索，笔记、书签、更正、阅读历史、下载和设置都不能修改。
每次启动都会重试。提示窗口有三个按钮：

- **重试迁移**：立即再试一次，成功后 Crib 重新打开。
- **稍后处理**：保持只读，下次启动再试。
- **跳过迁移…**：确认后 Crib 从空白的个人资料开始，旧资料原样留在原目录，以后不再提示。

### 已有 Crib 资料时 {#migration-existing}

如果 Crib 目录已经存在、没有迁移记录，而 PGDash 目录也还在，Crib 提示“发现 PGDash 旧资料”：

- **迁移旧资料**：Crib 重新打开时，把现有 Crib 目录整体改名为 `Crib-before-migration-<时间>` 保留，再迁移旧资料。迁移失败时改回原名。
- **稍后处理**：下次启动再提示。
- **不再提示**：继续使用现有的 Crib 资料。

### 迁移之后 {#after-migration}

- 旧的 `pgdash://` 链接仍能打开，见[深链接](/docs/integrations/deep-links/#legacy)。
- MCP 客户端里旧的 `pgdash` 配置不会被自动修改。在 Crib 中重新[复制 MCP 配置](/docs/integrations/mcp/#configure)。

## 环境变量 {#environment}

这些变量用于开发和测试，日常使用不需要设置。

| 变量 | 作用 |
| --- | --- |
| `CRIB_USER_DATA` | 改用另一个用户目录。设置后不会自动从 PGDash 迁移 |
| `CRIB_MIGRATE_FROM` | 指定迁移的来源目录 |
| `CRIB_LIBRARY` | 用另一个资料库代替 App 内置的内容 |
| `CRIB_CATALOG_URL` | 版本目录地址，默认 `https://repo.pigsty.io/doc/catalog.json` |
| `CRIB_ALLOW_DEVELOPMENT_CONTENT` | 设为 `1` 时接受开发签名的内容 |
| `CRIB_ALLOW_LOOPBACK_HTTP` | 设为 `1` 且可信根是开发可信根时，允许从 `127.0.0.1` 的 HTTP 地址获取目录 |
{.fields}

- `CRIB_LIBRARY`、`CRIB_CATALOG_URL` 和两个 `CRIB_ALLOW_*` 变量没有设置时，Crib 读取同名的旧变量 `PGDASH_*`；两者都设置时以 `CRIB_*` 为准。
- `PGDASH_USER_DATA` 不再指定 Crib 的用户目录，只被当作迁移来源。
- 设置了任何 `CRIB_*` 或 `PGDASH_*` 变量时，需要重新打开的操作（例如迁移完成后）只退出 Crib，不会自动重新打开。

---

反链：

- [从 PGDash 改名为 Crib](/blog/devlog/pgdash-to-crib/)
- [文档](/docs/)
- [安装与首次启动](/docs/guide/install/)
- [收录内容](/docs/intro/content/)
- [发布状态](/docs/intro/status/)
- [管理资料库](/docs/library/manage/)
- [常见问题](/docs/reference/faq/)
- [下载](/download/)