十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

Karakeep 书签导入完全指南:从 Chrome、Firefox、Pocket、Omnivore 迁移到自托管书签库

Karakeep 书签导入完全指南:从 Chrome、Firefox、Pocket、Omnivore 迁移到自托管书签库 Karakeep 书签导入完全指南从 Chrome、Firefox、Pocket、Omnivore 迁移到自托管书签库【免费下载链接】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自托管 bookmark-everything 应用的「书签导入」能力展开系统讲解 Karakeep 支持的导入格式Netscape HTML、Pocket CSV、Omnivore JSON 等、Chrome/Firefox/Pocket/Omnivore 四大主流来源的导出到导入完整链路以及面向技术用户的 CLI 批量导入方案。读完本文你将掌握如何把既有书签库无损迁移进 Karakeep——标题、标签、收藏日期均会被保留所有书签自动归入一个新建的列表并自动触发抓取与 AI 打标流程。导入能力总览Karakeep 的导入功能位于「设置」页面入口对应两个按钮「Import Bookmarks from HTML file」与「Import Bookmarks from Pocket export」。它支持三类官方文档承诺的格式格式来源文件类型保留字段Netscape HTML FormatChrome、Firefox 导出.html标题、标签、添加日期、文件夹层级Pocket CSVPocket 新导出格式.csv标题、标签、添加日期、归档状态Omnivore JSONOmnivore 导出数据.json可合并标题、标签、保存时间、归档状态导入时标题title、标签tags与添加日期addition date会被完整保留并且系统会自动创建一个新列表list收纳本次导入的全部书签方便你事后统一管理与迁移核对。一个必须提前知晓的约束官方文档以 info 提示框特别强调书签文件中的所有 URL 都会被自动添加你无法在导入时挑选哪些书签要导入、哪些不要。因此建议在导出前先自行清理目标书签库避免把不需要的链接一并灌入 Karakeep。从源码角度看导入格式的实际支持面比文档承诺的更广。在 packages/shared/import-export/parsers.ts 中ImportSource类型枚举了全部受支持的导入源export type ImportSource | html // Netscape HTMLChrome / Firefox | pocket // Pocket CSV | matter // Matter CSV | omnivore // Omnivore JSON | karakeep // Karakeep 自身导出 JSON | linkwarden // Linkwarden JSON | tab-session-manager // 浏览器标签会话 JSON | mymind // mymind CSV | readwise-reader // Readwise Reader CSV | instapaper // Instapaper CSV | onetab; // OneTab 纯文本每种来源在parsers.ts中都对应一个独立的解析函数如parseNetscapeBookmarkFile、parsePocketBookmarkFile、parseOmnivoreBookmarkFile并由统一的入口parseImportFile(source, textContent)分发调用。这些解析器均使用 zod schema 校验输入结构格式不符会抛出明确的错误信息例如上传的 HTML 缺少!DOCTYPE NETSCAPE-Bookmark-file-1声明时会提示 The uploaded html file does not seem to be a bookmark file。不同来源的标签分隔符差异也在解析层被归一化Netscape HTML 用逗号分隔、Pocket 用|分隔、Matter 用;分隔、mymind 用逗号分隔、Readwise Reader 的标签是 JSON 数组字符串最终都会统一转换成 Karakeep 的标签数组。从 Chrome 导入书签Chrome 是存量书签最多的浏览器Karakeep 通过 Netscape HTML 格式与 Chrome 互通。完整操作步骤打开 Chrome在地址栏输入chrome://bookmarks进入书签管理器点击右上角的三个点⋮菜单选择Export bookmarks导出书签浏览器会下载一个包含全部书签的 HTML 文件文件名形如bookmarks_YYYY-MM-DD.html打开 Karakeep 的「设置」页面点击Import Bookmarks from HTML file选择刚下载的 HTML 文件即可。导入后Chrome 书签栏中的文件夹层级会被保留parseNetscapeBookmarkFilepackages/shared/import-export/parsers.ts通过 cheerio 递归遍历书签文件中的DT/H3文件夹与A书签节点把文件夹路径记录在paths字段中同时读取add_date属性作为添加日期、读取tags属性作为标签。Karakeep 会在后续流程中依据这些路径重建列表结构。从 Firefox 导入书签Firefox 同样导出 Netscape HTML 格式操作路径稍有不同打开 Firefox点击右上角的菜单按钮☰进入书签 管理书签或直接按快捷键Ctrl Shift O/Cmd Shift O打开书签库窗口在书签库顶部点击导入和备份Import and Backup按钮选择将书签导出为 HTML...Export Bookmarks to HTML...把全部书签保存为 HTML 文件回到「导入和备份」菜单选择从 HTML 导入书签...Import Bookmarks from HTML...选中你保存的 HTML 文件即可完成导入。Firefox 导出的文件同样以!DOCTYPE NETSCAPE-Bookmark-file-1开头与 Chrome 文件在 Karakeep 解析层走的是同一条parseNetscapeBookmarkFile代码路径因此标题、标签、添加日期与文件夹层级的行为完全一致。从 Pocket 导入书签Pocket 的导出采用其新版 CSV 格式流程如下访问 Pocket 的导出页面getpocket.com/export按页面指引发起导出几分钟后 Pocket 会把包含全部书签的 zip 压缩包发送到你的邮箱解压 zip 得到 CSV 文件打开 Karakeep「设置」页面点击Import Bookmarks from Pocket export选择该 CSV 文件。在解析层parsePocketBookmarkFilepackages/shared/import-export/parsers.ts使用csv-parse/sync按列读取记录title映射标题、url映射链接、time_addedUnix 秒级时间戳映射添加日期、tags以|分隔拆成标签数组、status为archive的记录会标记为已归档archived: true。这意味着 Pocket 中「已归档」的书签导入 Karakeep 后也会保持归档状态不会混入你的活跃书签流。从 Omnivore 导入书签Omnivore 的导出是一个包含全部数据的 zip 包其中书签数据以多个metadata_*.json文件形式存在。导入方式有两种逐个导入手动把每个metadata_*.json文件分别上传导入适合文件数量少的情况合并后导入把多个 JSON 合并成单个omnivore.json再导入推荐一次完成。合并命令需要在解压目录下执行且系统需安装 [jq] 工具即 jqlang/jqjq -r .[] metadata_*.json | jq -s omnivore.json命令含义拆解jq -r .[]把每个metadata_*.json中的数组元素展开为 JSON Lines 流jq -sslurp再把流中的全部对象收集成一个 JSON 数组最终写入omnivore.json。之后在 Karakeep 设置中选择导入该文件。从解析实现看parseOmnivoreBookmarkFilepackages/shared/import-export/parsers.ts期望一个 JSON 数组每个元素包含title、url、labels标签数组、savedAt保存时间与可选的state字段state为Archived的书签会被标记为归档。这也解释了为什么合并命令必须产出「对象数组」——单个metadata_*.json本身已经是数组多个文件若不合并就无法一次解析。使用 CLI 批量导入书签当书签数量庞大、或来源格式不在上述标准格式之列时可以使用 Karakeep CLI 逐条导入。官方文档明确提示该方式需要一定技术基础对非技术用户可能不够直观遇到问题可在 GitHub Discussions 或 Discord 中提问。前提条件你手头有一份每行一个链接的纯文本文件例如all_links.txt且已安装并配置好 karakeep CLI配置方式见 命令行工具文档需要--api-key与--server-addr两个全局参数。批量导入命令Linux/macOS shellwhile IFS read -r url; do karakeep --api-key KEY --server-addr SERVER_ADDR bookmarks add --link $url done all_links.txt命令逻辑while IFS read -r url逐行读取all_links.txt并把每行内容赋给变量urlIFS保证行首行尾空格不被吞掉-r防止反斜杠被转义循环体内调用karakeep ... bookmarks add --link $url逐条创建书签。每条 URL 调用一次 CLI 进程适合中等规模迁移若 URL 量极大可自行加上并发或改用导入 API。从源码看CLI 的bookmarks add子命令定义在 apps/cli/src/commands/bookmarks.ts 中它通过 tRPC 客户端调用bookmarks.createBookmarkmutation 完成创建该 mutation 自带重复检测能力URL 已存在时返回alreadyExists标记因此即便文本文件里有重复链接也不会在 Karakeep 中生成重复书签。CLI 也支持--json等全局输出选项便于脚本化处理。导入背后的工作原理理解导入的内部机制有助于预判导入耗时、排查失败项。Karakeep 的导入并非一次性同步写入而是「暂存staging→ 后台异步处理」的架构。前端到服务端的调用链Web 端的导入流程封装在 apps/web/lib/hooks/useBookmarkImport.ts 与 apps/web/lib/hooks/useImportSessions.ts 中对应的服务端路由位于 packages/trpc/routers/importSessions.ts。核心 tRPC 接口包括createImportSession创建导入会话含会话名称与根列表 idstageImportedBookmarks把解析出的书签分批单次最多 50 条写入暂存表importStagingBookmarksfinalizeImportStaging暂存完成后将会话置为待处理pending通知后台 worker 开工pauseImportSession/resumeImportSession暂停/恢复导入可在后台抓取压力大时手动控制getImportSessionResults分页查询每个暂存书签的处理结果accepted/rejected/skipped_duplicate/pending。底层编排逻辑见 packages/shared/import-export/importer.ts 的importBookmarksFromFile它会先用createList创建一个以「⬆️」为图标的根列表名称由调用方指定再创建导入会话把解析出的书签批量 stage 进去最后finalizeImportStaging触发后台处理。若导入文件是 Karakeep 自身的导出 JSON还会顺带重建其内部列表层级importer.ts中的externalListIdToCreatedListId映射负责把源文件中的列表 id 关联到新创建的列表。后台 ImportWorker 的处理状态机真正的书签落库由独立 worker 完成实现位于 apps/workers/workers/importWorker.ts 的ImportWorker类。它以 5 秒为轮询间隔pollIntervalMs 5000扫描暂存表核心机制包括分批认领claim每批最多 10 条batchSize通过原子 UPDATE 把pending状态置为processing避免多个 worker 实例重复处理同一条记录背压控制backpressure同时在途处理上限为 50 条maxInFlight达到上限后暂停认领防止瞬时创建过多书签压垮抓取队列用户间公平调度getNextBatchFairly按「用户最近处理时间 暂存创建时间」排序取批保证多用户实例中每个用户的导入都能推进下游联动书签创建后暂存项保持processing直到其**抓取crawl**与AI 打标tagging都完成checkAndCompleteProcessingItems检查crawlStatus与taggingStatus才标记为completed——这就是导入后书签会陆续出现标题、标签的原因失败与重试抓取或打标失败的书签标记为failed原因分别为 Crawl failed / Tagging failed超过 1 小时仍卡在processing且未创建书签的僵尸项会被重置回pending重新尝试重复 URL 直接记为skipped_duplicate不会重复入库会话收尾一个会话下所有暂存项处理完毕后会话状态置为completed并记录事件日志含导入来源与成功数量超过 30 天的已完成会话会被归档清理。这些行为意味着导入大文件后无需守在页面上Karakeep 会在后台持续消化队列最终可在导入会话详情页中按accepted、rejected、skipped_duplicate等筛选条件查看每一条的最终结果。常见问题与注意事项无法挑选导入的书签这是设计约束导入即全量写入请先在原工具中清理再导出。文件格式报错上传 HTML 时提示 does not seem to be a bookmark file通常是文件不是 Netscape 格式例如是浏览器「另存为网页」产物Omnivore 提示 invalid omnivore bookmark file 时检查 JSON 是否为对象数组可用上述 jq 合并命令修复。重复书签URL 已在库中时导入会跳过并标记为skipped_duplicate不会产生重复记录且已有书签的标签会被合并补充。标签与日期保留只有源文件确实携带对应字段时才会保留例如 Chrome 导出的标签依赖书签原本有标签属性标签分隔符差异由解析器自动归一化无需手动处理。归档状态Pocket 的archive、Omnivore 的Archived、Instapaper 的Archive文件夹等来源的归档状态会被映射为 Karakeep 的归档标记导入后不会出现在活跃列表。导入速度取决于后台 worker 的抓取与 AI 打标吞吐可通过导入会话页面的分页结果持续观察进度。本文对应的官方文档见 docs/versioned_docs/version-v0.28.0/10-import.md当前版本的镜像见 docs/docs/04-using-karakeep/import.md导入解析器、编排逻辑与后台 worker 的完整源码分别位于 packages/shared/import-export/parsers.ts、packages/shared/import-export/importer.ts 与 apps/workers/workers/importWorker.ts感兴趣的读者可继续深入研读。【免费下载链接】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),仅供参考
返回列表