Karakeep 与 SingleFile 扩展集成指南：一键保存浏览器所见页面为本地书签归档-创锋一号

Karakeep 与 SingleFile 扩展集成指南：一键保存浏览器所见页面为本地书签归档

【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder

本篇技术指南讲解如何将自托管书签应用 Karakeep（本仓库即其开源实现，仓库根目录见 README.md）接入 SingleFile 扩展（作者为 gildas-lormeau），实现"所见即所得"的页面保存：在浏览器里直接点击扩展图标，把当前页面（含样式、图片、Cookie 会话态）完整打成 HTML 归档上传到 Karakeep。读完本文，你将掌握 SingleFile 扩展的 REST Form API 接入配置、?ifexists重复书签处理策略、以及用 CLI 批量导入既有 SingleFile 归档的完整流程。

为什么需要 SingleFile 集成

Karakeep 自身具备爬虫（crawler）能力，但某些页面并不适合服务端爬取：需要登录态才能访问的页面、带烦人 Cookie 弹窗的站点、以及明确拒绝被爬虫抓取的网站。SingleFile 的核心理念是在浏览器端完成页面快照——它在你登录的会话里读取渲染完成的 DOM，把样式、图片、字体等全部内联进单个 HTML 文件。Karakeep 将这种归档称为precrawledArchive（预爬取归档），作为书签的一个资产（asset）保存，从而绕过爬虫的所有限制。

官方扩展现已内置"客户端爬取"实验特性（底层同样由 SingleFile 驱动），如果只需要保存自己浏览器会话里的页面，可以不必单独安装 SingleFile 扩展；但若想复用 SingleFile 扩展自身丰富的高级选项，本文的 REST Form API 方式依然是最灵活的选择。

扩展端配置步骤

在浏览器中安装 SingleFile 扩展后，按以下步骤将其指向你的 Karakeep 实例：

打开 SingleFile 扩展的设置页面；
选择Destinations（目标）选项；
选择upload to a REST Form API（上传到 REST 表单 API）；
在 URL 字段填入上传地址：https://YOUR_SERVER_ADDRESS/api/v1/bookmarks/singlefile（把YOUR_SERVER_ADDRESS替换为你的 Karakeep 服务地址）；
在authorization token（授权令牌）字段粘贴一个 API Key——可以在 Karakeep 设置页面中生成；
设置data field name（数据字段名）为file；
设置URL field name（URL 字段名）为url；
（可选）在 URL 末尾追加?ifexists=MODE，其中MODE取skip、overwrite、overwrite-recrawl、append、append-recrawl之一，用于控制同一 URL 已存在书签时的处理方式，详见下文"重复书签处理策略"。

配置完成后，打开任意网页点击 SingleFile 扩展图标即可。上传完成前扩展不会显示任何进度条——由于归档文件通常较大，可能需要 30 秒以上才会在 Karakeep 中出现新书签，请耐心等待。

上传端点与鉴权说明（源码视角）

从源码可以看到，POST /api/v1/bookmarks/singlefile由 packages/api/routes/bookmarks.ts 实现，它依次做了四件事：

通过rejectMutationInReadOnlyMode拒绝只读模式下的写入；
通过apiKeyScopeMiddleware("assets", "readwrite")与apiKeyScopeMiddleware("bookmarks", "readwrite")双重中间件要求 API Key 同时具备资产与书签的读写权限（这也是扩展端 authorization token 必须使用 API Key 的原因）；
用 zod 校验查询参数ifexists（枚举值即上述五种模式，缺省为skip）以及表单字段url（字符串）与file（文件对象）；
先调用uploadAsset把 HTML 文件存为资产，再以type: BookmarkTypes.LINK、precrawledArchiveId指向该资产、source: "singlefile"创建书签——source字段会被记录，便于后续区分书签来源。

用 CLI 导入既有 SingleFile 归档

如果你本地已经积累了大量 SingleFile 导出的 HTML 归档，无需逐个通过扩展上传，Karakeep 的命令行工具提供了批量导入命令。导入时需要同时传入归档文件路径和原始页面 URL：

karakeep bookmarks import-singlefile page.html --url "https://example.com/page"

使用--if-exists MODE控制同一 URL 已存在书签时的处理方式，支持的 MODE 与?ifexists完全一致（见下节）。

从 apps/cli/src/commands/bookmarks.ts 的实现可以看到，该命令内部构造FormData，把文件作为text/html类型的 Blob 追加到file字段、URL 追加到url字段，然后以Bearer <API Key>请求头 POST 到${serverAddr}/api/v1/bookmarks/singlefile端点，并把--if-exists写入ifexists查询参数——也就是说，CLI 导入与扩展上传走的是同一条服务端链路，行为完全一致。若服务端返回非 2xx，CLI 会输出失败原因并设置非零退出码，适合写进脚本批量处理。

重复书签处理策略（ifexists）

当上传的 URL 与库中已有书签重复时，通过ifexists参数（URL 上的查询参数，或 CLI 的--if-exists选项）控制行为：

模式	行为
`skip`（默认）	书签已存在则跳过，不创建新记录
`overwrite`	用新归档替换已有的最近一次预爬取归档（只保留最新一份）
`overwrite-recrawl`	替换归档，并排队触发一次重新爬取以更新正文内容
`append`	把新归档追加为书签的额外版本，与旧归档共存
`append-recrawl`	追加新归档，并排队触发一次重新爬取

使用示例：

https://YOUR_SERVER_ADDRESS/api/v1/bookmarks/singlefile?ifexists=overwrite

对应 CLI 写法：

karakeep bookmarks import-singlefile page.html --url "https://example.com/page" --if-exists overwrite-recrawl

在 packages/api/routes/bookmarks.ts 中，createBookmark返回的alreadyExists标志驱动后续分流：overwrite系列会从书签现有资产中筛选出最后一个assetType == "precrawledArchive"的资产并调用replaceAsset完成替换（若不存在则直接attachAsset）；append系列则直接attachAsset追加新归档；两种带-recrawl后缀的模式都会额外调用recrawlBookmark，让爬虫基于新归档重新提取正文与元数据。选择建议：只想保留最新快照选overwrite；希望归档随页面演变留痕则选append；需要同步更新正文、摘要等派生内容时再带上-recrawl。

已知限制

目前 SingleFile 上传的归档不支持生成截图（截图需要爬虫在无头浏览器中渲染页面，而 SingleFile 只是上传静态 HTML），官方文档声明这一限制将在未来版本中解除。此外，上传过程没有进度反馈、大归档耗时较长，属于预期行为。如果页面对实时性要求不高、仅需长期存档，这种方式是最省事、最可靠的保存路径。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析