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原 Hoarder中启用 SingleFile 浏览器扩展作为书签存档的来源当你浏览网页时SingleFile 会把当前页面含样式、脚本、图片内联后的完整 HTML打包上传到 Karakeep 的专用 REST APIKarakeep 会将其保存为带precrawledArchive资产的链接书签。这套方案特别适合不愿被爬虫抓取、带有烦人 Cookie 弹窗或需要登录才能访问的网站。读完本文你将掌握 SingleFile 扩展的完整配置步骤、ifexists冲突处理五种模式的选择、推荐的服务端参数调优以及背后的 API 实现原理。SingleFile 集成解决了什么痛点Karakeep 默认通过后端爬虫抓取网页内容但现实中有三类页面很难被抓取禁止爬虫的网站robots 协议或反爬策略会拦截服务端抓取带 Cookie 弹窗的页面抓取结果可能只有弹窗层拿不到真实内容需要登录的页面服务端没有你的会话无法获取登录后的内容。SingleFile 扩展运行在你的浏览器里拥有你当前的登录态与渲染环境。它把页面所见即所得地保存为单个自包含 HTML 文件样式、图片、脚本全部内联再通过 Karakeep 的专用上传端点保存。这样归档内容与你在浏览器里看到的完全一致Karakeep 无需再次访问原始站点。第一步安装并配置 SingleFile 扩展1. 安装扩展在浏览器商店安装 SingleFile 扩展支持 Chrome / Firefox / Edge 等主流浏览器。2. 配置上传目标Destinations打开扩展的设置面板依次操作进入Destinations上传目标设置选择upload to a REST Form API上传到 REST 表单 API在URL字段填入 Karakeep 的上传地址https://YOUR_SERVER_ADDRESS/api/v1/bookmarks/singlefile在authorization token授权令牌字段粘贴 API Key。该 Key 可在 Karakeep 的设置页面中生成详见下文API Key 的权限要求将data field name数据字段名设置为file将URL field nameURL 字段名设置为url可选如需处理已存在书签的场景可在 URL 末尾追加ifexistsMODEMODE取skip、overwrite、overwrite-recrawl、append、append-recrawl之一详见下文处理已存在的书签。注意SingleFile 的设置项在部分版本中字段名可能写作 query string 拼接形式。URL 中以?开头、多个参数用连接即可例如.../singlefile?ifexistsoverwrite。3. 首次上传验证配置完成后打开任意网页点击 SingleFile 扩展图标。扩展会先保存页面、再执行上传。上传期间扩展不会显示任何进度条而归档文件通常较大可能需要30 秒以上才会在 Karakeep 中看到书签出现请耐心等待。上传成功后Karakeep 中会出现一个类型为LINK的书签其关联资产类型为precrawledArchive。第二步服务端上传端点是如何工作的POST /api/v1/bookmarks/singlefile端点的实现在 packages/api/routes/bookmarks.ts 中其处理逻辑可以概括为权限校验依次通过apiKeyScopeMiddleware(assets, readwrite)与apiKeyScopeMiddleware(bookmarks, readwrite)中间件要求调用方 API Key 同时具备资产与书签的读写权限rejectMutationInReadOnlyMode会在只读模式下拒绝写入参数校验查询参数ifexists被限制为skip/overwrite/overwrite-recrawl/append/append-recrawl五种取值缺省为skip表单字段要求url字符串与file文件同时存在资产入库将上传的 HTML 文件作为资产保存得到assetId创建书签调用createBookmark以type: BookmarkTypes.LINK、precrawledArchiveId指向新上传资产、source: singlefile创建书签source字段标记了书签来源冲突处理若同 URL 书签已存在bookmark.alreadyExists为真根据ifexists参数决定后续动作。从实现可以看出无论哪种模式新上传的 HTML 文件都会先入库区别只在于它与既有书签的挂接方式。第三步API Key 的权限要求端点要求 API Key 同时具备assets:readwrite允许上传资产文件bookmarks:readwrite允许创建/更新书签。缺少任一权限都会被拒绝。这一点在端到端测试 packages/e2e_tests/tests/api/bookmarks.test.ts 中有专门用例验证仅持有bookmarks:readwrite的受限 Key 调用该端点会返回403。因此在 Karakeep 设置中生成 API Key 时请使用具备完整书签与资产权限的 Key或直接使用默认的全权限 Key。处理已存在的书签ifexists 五种模式当上传的 URL 在库中已有书签时通过ifexists查询参数控制行为模式行为底层实现要点skip默认已存在则跳过不新建直接break保留原有资产不动overwrite替换已有预抓取归档只保留最新一份replaceAsset用新资产替换最后一个precrawledArchive资产overwrite-recrawl替换归档并排队重新爬取更新内容在overwrite基础上追加recrawlBookmarkappend在既有归档旁追加新版本attachAsset挂接新资产多版本共存append-recrawl追加新归档并排队重新爬取在append基础上追加recrawlBookmark使用方式在上传 URL 上追加?ifexistsMODE扩展配置中注意用连接多个参数例如https://YOUR_SERVER_ADDRESS/api/v1/bookmarks/singlefile?ifexistsoverwrite源码层面的行为印证在 packages/api/routes/bookmarks.ts 中可以看到每种模式的具体实现skip不做任何额外操作直接返回已存在的书签overwrite/overwrite-recrawl先从现有资产中筛选出最后一个precrawledArchive资产存在则调用replaceAsset原地替换否则调用attachAsset挂接随后若为overwrite-recrawl则再调用recrawlBookmark触发重新抓取append/append-recrawl直接attachAsset挂接新归档因此会产生多个归档版本随后若为append-recrawl再触发recrawlBookmark。对应的行为已由端到端测试逐一验证见 packages/e2e_tests/tests/api/bookmarks.test.tsskip模式下重复上传书签资产 ID 保持不变expect(assetIds2).toEqual([firstAssetId])overwrite模式下重复上传后precrawledArchive资产数量恒为 1但资产 ID 已更换append模式下重复上传后归档资产数量变为 2且新旧资产同时存在。如何选择模式希望一页只存一份、但内容保持最新用overwrite或overwrite-recrawl后者适合原始页面经常变动、需要同步抓取正文的场景希望保留页面随时间演化的多个快照用append或append-recrawl不确定、保守起见保持默认skip避免误覆盖历史归档。推荐配置扩展侧与服务端侧调优SingleFile 扩展推荐设置为获得更好的存档质量与体积控制建议在扩展设置中开启Stylesheets compress CSS content: on压缩 CSS 内容减小归档体积Stylesheets group duplicate stylesheets together: on将重复样式表合并分组HTML content remove frames: on移除页面内嵌的 frame 框架避免无关内容进入归档。服务端调大 MAX_ASSET_SIZE_MBSingleFile 归档通常比普通网页大得多单文件内联了全部资源Karakeep 默认的资产大小上限可能不够用。默认值定义在 packages/shared/config.tsMAX_ASSET_SIZE_MB: z.coerce.number().default(50),即默认50 MB推荐调高到100。可通过环境变量覆盖对应配置文档见 docs/docs/03-configuration/01-environment-variables.mdMAX_ASSET_SIZE_MB100设置后需重启 Karakeep 服务生效。若归档上传后始终失败或报资产过大错误优先检查该值。已知限制当前版本不支持为 SingleFile 上传生成截图书签卡片无缩略图该能力官方计划在未来版本中提供。延伸用 CLI 导入已有的 SingleFile 归档如果你本地已经积累了大量 SingleFile 保存的 HTML 文件也可以不通过扩展上传而是直接用 Karakeep CLI 导入对应文档见 docs/docs/05-integrations/05-singlefile.mdkarakeep bookmarks import-singlefile page.html --url https://example.com/page该命令要求同时传入归档文件路径与原始页面 URL并用--if-exists MODE控制同 URL 冲突处理模式与上文一致。其实现见 apps/cli/src/commands/bookmarks.tsCLI 读取本地文件后通过FormData携带url与file两个字段携带BearerAPI Key 调用同一个/api/v1/bookmarks/singlefile端点并将ifexists作为查询参数透传。也就是说CLI 与浏览器扩展最终走的是同一套服务端逻辑。总结Karakeep 对 SingleFile 的集成本质上是把浏览器端完整渲染 服务端归档存储结合起来浏览器扩展负责解决登录态、Cookie 弹窗、反爬等抓取难题Karakeep 负责存储、索引与后续的全文检索。配置时只需记住三个要点上传 URL 指向/api/v1/bookmarks/singlefile、字段名固定为file与url、API Key 需要资产与书签的双重读写权限再结合ifexists五种模式与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），仅供参考
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原 Hoarder中启用 SingleFile 浏览器扩展作为书签存档的来源当你浏览网页时SingleFile 会把当前页面含样式、脚本、图片内联后的完整 HTML打包上传到 Karakeep 的专用 REST APIKarakeep 会将其保存为带precrawledArchive资产的链接书签。这套方案特别适合不愿被爬虫抓取、带有烦人 Cookie 弹窗或需要登录才能访问的网站。读完本文你将掌握 SingleFile 扩展的完整配置步骤、ifexists冲突处理五种模式的选择、推荐的服务端参数调优以及背后的 API 实现原理。SingleFile 集成解决了什么痛点Karakeep 默认通过后端爬虫抓取网页内容但现实中有三类页面很难被抓取禁止爬虫的网站robots 协议或反爬策略会拦截服务端抓取带 Cookie 弹窗的页面抓取结果可能只有弹窗层拿不到真实内容需要登录的页面服务端没有你的会话无法获取登录后的内容。SingleFile 扩展运行在你的浏览器里拥有你当前的登录态与渲染环境。它把页面所见即所得地保存为单个自包含 HTML 文件样式、图片、脚本全部内联再通过 Karakeep 的专用上传端点保存。这样归档内容与你在浏览器里看到的完全一致Karakeep 无需再次访问原始站点。第一步安装并配置 SingleFile 扩展1. 安装扩展在浏览器商店安装 SingleFile 扩展支持 Chrome / Firefox / Edge 等主流浏览器。2. 配置上传目标Destinations打开扩展的设置面板依次操作进入Destinations上传目标设置选择upload to a REST Form API上传到 REST 表单 API在URL字段填入 Karakeep 的上传地址https://YOUR_SERVER_ADDRESS/api/v1/bookmarks/singlefile在authorization token授权令牌字段粘贴 API Key。该 Key 可在 Karakeep 的设置页面中生成详见下文API Key 的权限要求将data field name数据字段名设置为file将URL field nameURL 字段名设置为url可选如需处理已存在书签的场景可在 URL 末尾追加ifexistsMODEMODE取skip、overwrite、overwrite-recrawl、append、append-recrawl之一详见下文处理已存在的书签。注意SingleFile 的设置项在部分版本中字段名可能写作 query string 拼接形式。URL 中以?开头、多个参数用连接即可例如.../singlefile?ifexistsoverwrite。3. 首次上传验证配置完成后打开任意网页点击 SingleFile 扩展图标。扩展会先保存页面、再执行上传。上传期间扩展不会显示任何进度条而归档文件通常较大可能需要30 秒以上才会在 Karakeep 中看到书签出现请耐心等待。上传成功后Karakeep 中会出现一个类型为LINK的书签其关联资产类型为precrawledArchive。第二步服务端上传端点是如何工作的POST /api/v1/bookmarks/singlefile端点的实现在 packages/api/routes/bookmarks.ts 中其处理逻辑可以概括为权限校验依次通过apiKeyScopeMiddleware(assets, readwrite)与apiKeyScopeMiddleware(bookmarks, readwrite)中间件要求调用方 API Key 同时具备资产与书签的读写权限rejectMutationInReadOnlyMode会在只读模式下拒绝写入参数校验查询参数ifexists被限制为skip/overwrite/overwrite-recrawl/append/append-recrawl五种取值缺省为skip表单字段要求url字符串与file文件同时存在资产入库将上传的 HTML 文件作为资产保存得到assetId创建书签调用createBookmark以type: BookmarkTypes.LINK、precrawledArchiveId指向新上传资产、source: singlefile创建书签source字段标记了书签来源冲突处理若同 URL 书签已存在bookmark.alreadyExists为真根据ifexists参数决定后续动作。从实现可以看出无论哪种模式新上传的 HTML 文件都会先入库区别只在于它与既有书签的挂接方式。第三步API Key 的权限要求端点要求 API Key 同时具备assets:readwrite允许上传资产文件bookmarks:readwrite允许创建/更新书签。缺少任一权限都会被拒绝。这一点在端到端测试 packages/e2e_tests/tests/api/bookmarks.test.ts 中有专门用例验证仅持有bookmarks:readwrite的受限 Key 调用该端点会返回403。因此在 Karakeep 设置中生成 API Key 时请使用具备完整书签与资产权限的 Key或直接使用默认的全权限 Key。处理已存在的书签ifexists 五种模式当上传的 URL 在库中已有书签时通过ifexists查询参数控制行为模式行为底层实现要点skip默认已存在则跳过不新建直接break保留原有资产不动overwrite替换已有预抓取归档只保留最新一份replaceAsset用新资产替换最后一个precrawledArchive资产overwrite-recrawl替换归档并排队重新爬取更新内容在overwrite基础上追加recrawlBookmarkappend在既有归档旁追加新版本attachAsset挂接新资产多版本共存append-recrawl追加新归档并排队重新爬取在append基础上追加recrawlBookmark使用方式在上传 URL 上追加?ifexistsMODE扩展配置中注意用连接多个参数例如https://YOUR_SERVER_ADDRESS/api/v1/bookmarks/singlefile?ifexistsoverwrite源码层面的行为印证在 packages/api/routes/bookmarks.ts 中可以看到每种模式的具体实现skip不做任何额外操作直接返回已存在的书签overwrite/overwrite-recrawl先从现有资产中筛选出最后一个precrawledArchive资产存在则调用replaceAsset原地替换否则调用attachAsset挂接随后若为overwrite-recrawl则再调用recrawlBookmark触发重新抓取append/append-recrawl直接attachAsset挂接新归档因此会产生多个归档版本随后若为append-recrawl再触发recrawlBookmark。对应的行为已由端到端测试逐一验证见 packages/e2e_tests/tests/api/bookmarks.test.tsskip模式下重复上传书签资产 ID 保持不变expect(assetIds2).toEqual([firstAssetId])overwrite模式下重复上传后precrawledArchive资产数量恒为 1但资产 ID 已更换append模式下重复上传后归档资产数量变为 2且新旧资产同时存在。如何选择模式希望一页只存一份、但内容保持最新用overwrite或overwrite-recrawl后者适合原始页面经常变动、需要同步抓取正文的场景希望保留页面随时间演化的多个快照用append或append-recrawl不确定、保守起见保持默认skip避免误覆盖历史归档。推荐配置扩展侧与服务端侧调优SingleFile 扩展推荐设置为获得更好的存档质量与体积控制建议在扩展设置中开启Stylesheets compress CSS content: on压缩 CSS 内容减小归档体积Stylesheets group duplicate stylesheets together: on将重复样式表合并分组HTML content remove frames: on移除页面内嵌的 frame 框架避免无关内容进入归档。服务端调大 MAX_ASSET_SIZE_MBSingleFile 归档通常比普通网页大得多单文件内联了全部资源Karakeep 默认的资产大小上限可能不够用。默认值定义在 packages/shared/config.tsMAX_ASSET_SIZE_MB: z.coerce.number().default(50),即默认50 MB推荐调高到100。可通过环境变量覆盖对应配置文档见 docs/docs/03-configuration/01-environment-variables.mdMAX_ASSET_SIZE_MB100设置后需重启 Karakeep 服务生效。若归档上传后始终失败或报资产过大错误优先检查该值。已知限制当前版本不支持为 SingleFile 上传生成截图书签卡片无缩略图该能力官方计划在未来版本中提供。延伸用 CLI 导入已有的 SingleFile 归档如果你本地已经积累了大量 SingleFile 保存的 HTML 文件也可以不通过扩展上传而是直接用 Karakeep CLI 导入对应文档见 docs/docs/05-integrations/05-singlefile.mdkarakeep bookmarks import-singlefile page.html --url https://example.com/page该命令要求同时传入归档文件路径与原始页面 URL并用--if-exists MODE控制同 URL 冲突处理模式与上文一致。其实现见 apps/cli/src/commands/bookmarks.tsCLI 读取本地文件后通过FormData携带url与file两个字段携带BearerAPI Key 调用同一个/api/v1/bookmarks/singlefile端点并将ifexists作为查询参数透传。也就是说CLI 与浏览器扩展最终走的是同一套服务端逻辑。总结Karakeep 对 SingleFile 的集成本质上是把浏览器端完整渲染 服务端归档存储结合起来浏览器扩展负责解决登录态、Cookie 弹窗、反爬等抓取难题Karakeep 负责存储、索引与后续的全文检索。配置时只需记住三个要点上传 URL 指向/api/v1/bookmarks/singlefile、字段名固定为file与url、API Key 需要资产与书签的双重读写权限再结合ifexists五种模式与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），仅供参考