使用 SingleFile 扩展将网页原样归档到 Karakeep配置、API 与导入实战【免费下载链接】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导读本文以 Karakeephoarder 开源书签应用v0.31.0 版本的集成文档为主线系统讲解如何将 [SingleFile 扩展]接入 Karakeep把浏览器中看到的网页「所见即所得」地保存为完整归档。文章覆盖扩展端配置步骤、/api/v1/bookmarks/singlefile上传端点的认证与表单约束、五种ifexists去重策略的底层实现、CLI 批量导入历史归档的方法以及MAX_ASSET_SIZE_MB等关键环境变量的调优建议。读完本文你将能独立搭建一条「浏览器原样存档 → Karakeep 自动归档」的完整链路并理解其内部的资源替换与重爬取机制。为什么需要 SingleFile 集成Karakeep原 hoarder本身自带爬虫能够抓取网页链接、正文与元数据。但传统的服务端爬虫有两个天然盲区拒绝被爬取的网站部分站点通过 robots 协议、反爬策略或 JS 动态渲染阻止服务端抓取需要登录态的页面Cookie 会话、付费墙后的内容服务端无痕访问拿不到完整页面烦人的 Cookie 横幅爬虫得到的页面往往夹杂横幅与弹窗阅读体验差。SingleFile 是浏览器端的页面归档扩展它把当前页面含 CSS、图片、字体等资源内联打包成一个独立的 HTML 文件。Karakeep 支持将 SingleFile 扩展作为「上传目的地」你在浏览器中看到什么就原样保存什么——页面交互后的状态、已登录的内容、无横幅的渲染结果全部随归档一并入库。从 v0.31.0 版本起集成文档额外提示官方 Karakeep 扩展也已在实验性特性中支持基于 SingleFile 的客户端爬取。如果你只需要归档自己浏览器会话内的页面可能不再需要单独安装 SingleFile 扩展但本文介绍的独立 SingleFile 扩展方案仍是兼容性最好、不依赖 Karakeep 官方扩展的通用路径。注意本节及全文以 docs/versioned_docs/version-v0.31.0/05-integrations/05-singlefile.md 为骨架该文档与当前主线文档 docs/docs/05-integrations/05-singlefile.md 内容一致主线版额外包含 CLI 导入章节与官方扩展提示。扩展端配置五步接入上传目的地在浏览器中安装 [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——该 Key 可在 Karakeep 设置页中生成将data field name设为file、URL field name设为url可选在 URL 后追加?ifexistsMODE控制同 URL 已存在书签时的处理策略详见下文「处理已存在的书签」。配置完成后打开任意网页点击 SingleFile 扩展图标即可触发归档。需要留意的是SingleFile 扩展不会显示上传进度而完整的页面归档通常体积较大从点击到书签出现在 Karakeep 中可能需要 30 秒以上请耐心等待。表单字段与认证字段名不是随意定的data field namefile、URL field nameurl这两个约定与 Karakeep 服务端对上传表单的严格校验一一对应。在 packages/api/routes/bookmarks.ts 中上传端点通过 zod 校验multipart/form-datazValidator( form, z.object({ url: z.string(), file: z.instanceof(File), }), ),即表单必须包含url字符串页面原始地址与file文件对象归档 HTML。若字段名不一致请求将直接因校验失败被拒绝。认证方面该路由挂载了两个中间件见 packages/api/routes/bookmarks.tsrejectMutationInReadOnlyMode, // 只读模式下拒绝写入 apiKeyScopeMiddleware(assets, readwrite), // 需要 assets 读写权限 apiKeyScopeMiddleware(bookmarks, readwrite), // 需要 bookmarks 读写权限这意味着生成 API Key 时需同时勾选assets与bookmarks的读写权限且实例处于只读模式时该接口不可用。认证通过Authorization: Bearer API_KEY头传递SingleFile 扩展设置中的 authorization token 字段即对应此头。处理已存在的书签ifexists 五种策略当上传的 URL 在库中已存在书签时通过 URL 查询参数?ifexistsMODE控制行为MODE取值如下默认skip模式行为说明skip默认书签已存在则跳过不创建新记录overwrite用新归档替换旧的预爬取归档只保留最近一份overwrite-recrawl替换旧归档并排队触发一次重新爬取以更新内容append在既有归档旁新增一份归档版本append-recrawl新增归档版本并排队触发重新爬取使用示例https://YOUR_SERVER_ADDRESS/api/v1/bookmarks/singlefile?ifexistsoverwrite五种策略的服务端实现解析该参数在服务端同样经过 zod 严格枚举校验packages/api/routes/bookmarks.tsz.object({ ifexists: z .enum([skip, overwrite, overwrite-recrawl, append, append-recrawl]) .optional() .default(skip), }),上传文件首先经uploadAsset落盘并返回资产 ID随后创建书签并携带precrawledArchiveId预爬取归档资产。当bookmark.alreadyExists为真时依据模式执行不同分支packages/api/routes/bookmarks.tsskip什么都不做直接返回已存在的书签overwrite / overwrite-recrawl从书签资产中筛选出最后一个assetType precrawledArchive的资产作为旧归档调用replaceAsset用新资产替换它若无旧归档则退化为attachAsset直接附加。随后若为overwrite-recrawl额外调用recrawlBookmark排队重新爬取append / append-recrawl直接调用attachAsset将新归档附加为一份新版本若为append-recrawl同样追加一次recrawlBookmark。这解释了各模式在「归档版本数量」上的差异overwrite系列只保留最新一份预爬取归档append系列则保留多版本历史。而recrawlBookmark的存在意味着——归档上传与全文爬取是两条独立管线SingleFile 提供的是「所见即所得」的静态快照recrawl 则用于刷新 Karakeep 提取的可读正文、标题与元数据。用 CLI 导入已有 SingleFile 归档如果你本地已经积累了一批 SingleFile HTML 归档例如从旧书签系统导出无需逐个手动上传Karakeep CLI 提供import-singlefile子命令批量导入karakeep bookmarks import-singlefile page.html --url https://example.com/page命令要求同时提供归档文件路径与页面原始 URL--url必填因为 Karakeep 需要真实 URL 才能建立书签记录并关联归档内容。同样可用--if-exists MODE控制同 URL 已存在书签时的行为支持的五种模式与上文完全一致。该子命令在 v0.31.0 版本文档中尚未出现属于主线文档新增内容本文一并收录以保证方案完整性。CLI 导入的底层实现从源码看import-singlefile的实现apps/cli/src/commands/bookmarks.ts本质上是对上述 REST 端点的封装定义并校验skip/overwrite/overwrite-recrawl/append/append-recrawl五种模式非法值直接抛错提示可选范围读取本地文件为 Buffer构造FormData将文件以text/htmlMIME 类型、原文件名写入file字段并将--url写入url字段目标端点为${serverAddr}/api/v1/bookmarks/singlefile并自动附加?ifexistsmode查询参数携带Authorization: Bearer apiKey发起 POST失败时输出可读错误信息并置退出码为 1。因此 CLI 与扩展走的是同一条上传链路行为完全一致本地批量导入历史归档时你可以放心把--if-exists当成?ifexists的等价物使用。推荐配置扩展设置与服务器调优为了获得更好的归档质量官方建议在 SingleFile 扩展中开启以下选项Stylesheets compress CSS content: on压缩 CSS 内容减小归档体积Stylesheets group duplicate stylesheets together: on合并重复样式表进一步瘦身HTML content remove frames: on移除 iframe 框架避免多余嵌套内容。服务器端最重要的调优项是MAX_ASSET_SIZE_MB。该环境变量默认值为50MB见 packages/shared/config.ts 与 docs/docs/03-configuration/01-environment-variables.md 的环境变量表而 SingleFile 产出的完整页面归档经常超过 50MB图片、字体全内联。若不调高上传会被服务端直接拒绝。从实现看该上限在服务端被换算为字节级硬限制packages/api/utils/upload.tsconst MAX_UPLOAD_SIZE_BYTES serverConfig.maxAssetSizeMb * 1024 * 1024;官方建议将MAX_ASSET_SIZE_MB提高至100左右。在 Docker Compose 或环境变量文件中加入MAX_ASSET_SIZE_MB100然后重启 Karakeep 容器即可生效。已知限制与适用前提官方文档明确标注了两点限制暂不支持截图当前 SingleFile 上传产生的书签不会附带页面截图官方表示未来版本会支持。因此在书签卡片视图中这类书签可能缺少缩略图上传无进度反馈归档上传期间 SingleFile 扩展不显示进度大文件归档可能需要 30 秒以上才出现在 Karakeep 中。此外请结合你的部署方式核对前提条件需要可被浏览器访问的 Karakeep 实例地址自托管需暴露 HTTPS 端点API Key 必须同时具备assets与bookmarks的读写权限实例处于只读模式read-only mode时上传接口会被rejectMutationInReadOnlyMode中间件拒绝上传文件大小受MAX_ASSET_SIZE_MB默认 50限制归档较大的页面请先调高该值。小结Karakeep 与 SingleFile 的集成提供了一条绕过服务端爬虫限制的「浏览器原样归档」路径扩展端只需配置一个 REST 表单 API 目的地/api/v1/bookmarks/singlefile服务端以fileurl两个表单字段严格校验、以assetsbookmarks双读写权限保护并通过?ifexists参数提供 skip / overwrite / overwrite-recrawl / append / append-recrawl 五种去重策略CLI 的import-singlefile子命令则把同一条链路复用到了本地历史归档的批量导入。配合MAX_ASSET_SIZE_MB调优与扩展端的压缩/去重选项即可获得稳定、高效、所见即所得的网页归档体验。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
`)
