# 下载、更新与恢复

> 从版本目录下载一个版本时的每一步、断点续传、目录过期和离线时的行为，失败时保留什么，以及怎样回到以前的组合。

---

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

---

> [!IMPORTANT] 正式版本目录尚未上线
>
> Crib 默认从 `https://repo.pigsty.io/doc/catalog.json` 获取版本目录。这个地址是规划中的正式目录，还没有上传，
> 所以现在“刷新目录”拿不到正式目录。下文描述开发构建的行为，在本机测试目录上验证过，没有在公网 HTTPS 和 CDN 上测试。

## 什么时候联网 {#network}

打开 Crib 或资料库都不联网。只有两个操作会联网：点“刷新目录”，以及点某个版本的“下载”。

已安装的内容不会过期，阅读和搜索始终离线完成。导入本地资料包也不需要联网。

## 版本目录 {#catalog}

版本目录（`catalog.json`）列出可下载的版本、它们的状态、别名，以及每个归档的大小和哈希。
开发构建可以内置一份签名的目录快照，所以第一次打开、没有联网时也能看到全部版本。

点“刷新目录”时，Crib 下载新目录并检查：

- 签名必须由 App 自带的可信根签发。服务器不能自己添加可信密钥。
- 修订号不能低于本机已有的目录；修订号相同而内容不同，只接受签发时间更晚的一份。否则视为回退或冲突，保留原来的目录。
- 已过期的目录不接受。

刷新失败不改动本机文件。资料库顶部显示“版本目录更新于 …”；刷新中可以点“取消”。

## 目录过期以后 {#expiry}

目录带有效期，由发布者签名时写入。过期后，资料库显示“版本目录已过期，刷新后才能下载。”

- 版本列表照常显示，别名照常解析。
- 不能下载新版本，直到刷新到一份未过期的目录。
- 已安装的内容不受影响。

本机缓存的目录如果无法再通过校验（例如可信根换了密钥），Crib 跳过它，改用 App 内置的快照，并把旧文件移到用户目录的
`Distribution-rejected/`，保留最近 5 份。目录中个别条目有问题时，只忽略那些条目，并在资料库提示；已安装的同一版本照常可读。

## 下载一个版本 {#download}

在“全部版本”里点某一行的“下载”。进度面板显示“下载 → 校验 → 建立索引 → 启用”，下载阶段显示已下载和总字节数。

1. **确认授权。** 该版本必须在一份未过期的目录里，且状态不是“无法下载”。归档路径必须是目录给出的相对路径，只走同源 HTTPS，不跟随跨站重定向。
1. **流式下载。** 写入临时目录，总字节数以目录签名的大小为准。
1. **校验。** 核对长度、归档 SHA-256、ZIP 结构、清单哈希（必须等于目录记录的值）、清单签名、解包后的总大小。
1. **解包。** 解到暂存区，再逐个文件核对哈希并检查数据库结构。传输结束后再确认一次目录仍然授权这个版本。
1. **建立索引。** 在后台建立新的搜索世代，旧世代继续服务。
1. **启用。** 原子切换。新版本替换同一资料包当前启用的修订；旧修订仍已安装，状态变为“已停用”。
{.steps}

下载、校验或索引失败时，按钮变为“重试下载”。

## 断点续传 {#resume}

- 网络中断时（不包括你点“取消”），已下载的部分保存在用户目录的 `Distribution-partials/` 中，保留 7 天。
- 再次下载同一个归档时，Crib 先重新计算已保存部分的哈希，再用 `Range` 加 `If-Range`（强 ETag 或 Last-Modified）请求剩余部分。
- 服务器返回 206 时必须带完全匹配的 `Content-Range`；返回 200 就从头重下。最终仍以目录签名的归档哈希为准。
- 点“取消”，或者校验、大小、路径检查失败时，已下载的部分直接丢弃。
- 单次下载最长 48 小时；连续 60 秒收不到数据视为中断，已下载部分保留以便续传。目录请求最长 600 秒。

## 失败、取消与磁盘空间 {#failure}

- 切换之前的任何失败、取消或磁盘空间不足，都保留原来的组合，不做切换。
- 资料包写入资料库之前先检查磁盘空间。
- 切换一旦完成，新组合就是当前组合，即使之后又报告了错误。重试前先看资料库里实际启用的是什么。
- 失败只记在这一个版本上。之前启用的旧修订照常可读。

## 更新到新的小版本 {#update}

发布者发布新的小版本时，新增一个归档并移动版本线别名，例如把 `pg18` 从 18.6 移到 18.7；18.6 的文件不变。

刷新目录后，“全部版本”里出现 18.7，状态为未安装。刷新本身不会自动下载，也不会重建索引。下载 18.7 后，它替换 18.6 成为启用的修订；
18.6 仍已安装，可以重新启用，也可以[卸载](/docs/library/manage/#uninstall)。

下载或导入同一资料包中比当前启用修订更低的修订会被拒绝。要回到以前的修订，用“恢复资料组合…”。

Crib 没有自动更新。App 本身也没有公开的更新通道。

## 回到以前的组合 {#rollback}

每次切换组合，Crib 保留切换前启用的那一组。在资料库底栏点“恢复资料组合…”可以预览并恢复，步骤见[管理资料库](/docs/library/manage/#restore)。

启动时如果当前搜索世代损坏，或 App 换新后原来内置的资料包不在了，Crib 自动换到保留的组合或 App 内置的初始组合，
并在资料库顶部提示。提示里的“重新启用”可以把之前启用的资料包重新启用。

## 个人资料不受影响 {#personal}

下载、导入、启用、停用、卸载和恢复组合都不写个人资料：笔记、书签、标签、阅读历史、更正、片段和设置。
卸载一个版本后，挂在上面的笔记和书签保留；内容重新安装后可以再次定位。

---

反链：

- [文档](/docs/)
- [资料包格式](/docs/library/packs/)