Karakeep 书签系统完全指南收藏、归档、三种书签类型与笔记、高亮、附件的实战解析【免费下载链接】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 官方文档《Bookmarking》为核心系统讲解这款自托管书签应用中最基础也最关键的概念收藏Favourites、归档Archiving、链接/文本/媒体三种书签类型以及依附于书签之上的笔记、高亮与附件体系。读完本文你将清楚理解每种书签的内部数据模型与后台处理流程掌握用 Karakeep 实现收件箱清零inbox-zero式知识库管理的完整方法并能从源码层面理解保存一个链接后系统究竟做了什么。一切从一次保存开始Karakeep 中的书签是什么在 Karakeep 中所有内容都以书签bookmark为起点——无论是网页链接、随手粘贴的片段还是图片与 PDF。书签是数据组织的最小单元其余一切标签、列表、高亮、笔记、附件都围绕书签展开。从源码层面看书签的公共字段定义在 packages/shared/types/bookmarks.ts 的zBareBookmarkSchema中它揭示了每个书签的核心状态title标题最长 1000 字符MAX_BOOKMARK_TITLE_LENGTHarchived/favourited归档与收藏状态正是本文接下来要讲的两个核心开关note/summary个人笔记与 AI 摘要字段taggingStatus/summarizationStatus/embeddingStatusAI 打标签、摘要、向量嵌入的后台任务状态success/failure/pendingsource书签来源取值包括api、web、cli、mobile、extension、singlefile、rss、import表明书签可以通过浏览器扩展、命令行、移动端、RSS 订阅甚至导入流程进入系统。而书签的内容本身则由zBookmarkContentSchemapackages/shared/types/bookmarks.ts这一可辨识联合类型discriminated union承载按type字段区分为四种link、text、asset和unknown。这四种类型即官方文档中描述的 Links、Text、Media 三类外加一个历史兼容的unknown。接下来我们逐一展开。收藏Favourites给重要内容一个专属视图收藏是 Karakeep 中最轻量级的组织手段给喜欢的书签打上星标它们就会出现在专属的收藏视图中方便快速回访。官方文档的建议使用场景是反复重读的好文章、需要经常回来查阅的参考资料、值得分享的内容——一句话凡是想再打开一次的收藏品都值得星标。在数据模型层面收藏只是一个布尔字段zBareBookmarkSchema中的favourited: z.boolean()。修改它的入口是 packages/trpc/routers/bookmarks.ts 的updateBookmark变更操作调用方传入favourited: true/false即可切换状态。值得一提的是收藏状态并非只是改一个字段这么简单。从源码可以看到当input.favourited true时系统会触发两件额外的事记录bookmark.favorite事件日志logEvent见 bookmarks.ts触发RuleEngine的favourited事件bookmarks.ts这意味着你可以用 Karakeep 的自动化规则如收藏某类书签时自动打标签/发 Webhook把收藏行为变成工作流触发器。在前端收藏操作散布于各个书签卡片组件中如 BookmarkLayoutAdaptingCard.tsx 中通过bookmark.favourited切换星标图标BookmarkActionBar.tsx 则在卡片顶部展示收藏状态徽标批量场景下BulkBookmarksAction.tsx 支持对多选书签一次性收藏/取消收藏。归档Archiving把首页收拾干净却不丢失任何东西归档解决的是首页信息过载问题。它的行为模型非常清晰归档会把书签从首页隐藏但绝不删除已归档的书签仍然可被搜索到且保留全部标签、高亮和附件它的目标用户场景是收件箱清零——让首页只呈现待处理/未读完的内容处理完的内容一键归档眼不见心不烦但随时可以找回。与favourited一样archived也是zBareBookmarkSchema中的布尔字段通过updateBookmark传入archived: true/false切换。归档同样会触发事件日志bookmark.archive和 RuleEngine 的archived事件因此同样可以接入自动化规则。重要细节重新保存一个已归档的书签会自动将其恢复并置顶。这在 createBookmark 的去重逻辑中体现——当检测到 URL 已存在时系统默认会把archived重置为false并刷新createdAtresaved { createdAt: input.createdAt ?? now, archived: input.archived ?? false, ... }。不过如果书签来源是rss或importRESAVE_EXEMPT_SOURCES集合见 bookmarks.ts重复保存则保持无操作语义不会打乱已有书签的归档状态这是为了批量导入和 RSS 拉取的幂等性考虑。三种书签类型链接Links网页保存的主力军链接书签是最常用的类型通过浏览器扩展或 Web 端从网页保存。官方文档描述其能力为Karakeep grabs metadata, previews, screenshots, and archives when configured——即抓取元数据、生成预览、截图并在配置后保存页面存档。对应的数据结构是 zBookmarkedLinkSchema它解释了链接书签能存下什么字段含义url原始链接仅允许 http/https 协议由zBookmarkUrlSchema校验见 bookmarks.ts 类型文件title/description抓取到的标题与描述imageUrl/imageAssetId封面图 URL 及其资产 IDscreenshotAssetId/pdfAssetId/fullPageArchiveAssetId/videoAssetId截图、PDF、整页存档、视频等资产关联favicon站点图标readerViewStatus/readerViewScore阅读器视图可用性判定及 0–100 评分crawledAt/crawlStatus抓取时间与状态success/failure/pendingauthor/publisher/datePublished/dateModified文章级元数据从源码看创建链接书签的完整链路bookmarks.ts 的 createBookmark大致是去重attemptToDedupLink按 URL 查询是否已存在同 URL 书签存在则走重存逻辑恢复、置顶详见上文归档部分落库在事务中插入bookmarks表记录type: link与bookmarkLinks表URL 等链接专属数据入队抓取把bookmarkId投递到LinkCrawlerQueue或限流触发时的LowPriorityCrawlerQueue由 apps/workers/workers/crawlerWorker.ts 后台完成元数据、可读内容、截图、存档的抓取——这也是文档所说 when configured 的部分是否生成截图/整页存档取决于你的配置联动并行触发搜索索引重建triggerSearchReindex、Webhook 通知与 RuleEngine 的bookmarkAdded事件。此外createBookmark接受crawlPrioritylow/normal参数用于区分用户主动保存与批量导入的抓取优先级bookmarks.ts创建接口默认限流为每分钟 30 次bookmarks.createBookmark见 bookmarks.ts。若抓取失败或想重新生成截图/存档可通过recrawlBookmark重新入队支持archiveFullPage、storePdf两个选项见 bookmarks.ts。文本Text快速记录灵感与片段文本书签用于保存你直接粘贴进去的内容——想法、语录、随附链接的上下文说明等。它的数据结构极简zBookmarkedTextSchematext正文内容sourceUrl可选的来源链接例如从某篇文章摘录时保留出处。创建文本书签时后台会根据配置走不同路径bookmarks.ts若开启了嵌入自动索引serverConfig.embedding.enableAutoIndexing则投递到EmbeddingsQueue执行嵌入并顺带打标签否则投递到OpenAIQueue仅做标签任务。因此文本书签同样能获得自动标签与全文搜索能力。媒体Media图片与 PDF 的自动化内容提取媒体书签用于保存图片或 PDF 文件。官方文档强调其杀手锏是Karakeep automatically extracts content out of those files and makes them searchable——系统会自动从图片/PDF 中提取内容如 OCR 文本、PDF 文本并使其可被搜索。对应的数据结构是 zBookmarkedAssetSchemaassetType仅允许image或pdfassetId/fileName关联的上传资产sourceUrl来源链接size/content文件大小与提取出的内容。创建媒体书签时bookmarks.ts系统会先校验资产归属并检查其contentType是否在SUPPORTED_BOOKMARK_ASSET_TYPES集合内随后将bookmarkId写入资产记录并把任务投递到AssetPreprocessingQueue——由资产预处理 Worker 完成内容提取。这就是图片/PDF 内容可搜索背后的实现路径。笔记Notes给书签补充为什么重要官方文档对笔记的定义是给任意书签附加个人笔记用来记录上下文、提醒或下一步行动。笔记与书签绑定、可被搜索因此你可以在日后通过关键词找回当时为什么收藏它。在数据层笔记就是zBareBookmarkSchema中的note字段创建时可通过createBookmark的note参数一并写入之后通过updateBookmark的note参数随时修改bookmarks.ts。由于笔记字段参与搜索索引写入后系统会触发triggerSearchReindex重建索引确保笔记内容立即可搜。高亮Highlights阅读时划重点日后直达关键想法高亮用于在阅读过程中保存引文、摘要或 TODO。官方文档强调两点高亮会显示在书签详情视图/阅读器中且可被搜索让你能直接跳回关键观点所在位置。高亮的完整 CRUD 由 packages/trpc/routers/highlights.ts 提供包括按书签查询高亮列表、创建、更新与删除对应的数据模型定义在 packages/shared/types/highlights.ts。值得留意的是Karakeep 还支持阅读进度追踪updateReadingProgress仅对链接书签生效bookmarks.ts保存阅读偏移量、锚点文本与百分比配合阅读器让下次接着读成为可能。附件Attachments给书签挂上更多上下文附件是书签的外部存储舱截图、页面存档、视频、你上传的文件都可以挂在一个书签下。官方文档将其价值概括为截图与存档Screenshots archives当原网页变更或消失时充当回退副本——这就是自托管书签的网页快照保障上传文件Uploaded files把 PDF、笔记或配套素材与链接放在一起管理方式在书签详情视图上传、下载或解除detach附件。源码中附件的类型由 zAssetTypesSchema 定义一张表看清所有资产种类资产类型用途screenshot网页截图fullPageArchive整页存档SingleFile 类归档precrawledArchive预抓取存档linkHtmlContent链接 HTML 内容pdf/assetScreenshotPDF 与媒体书签截图bannerImage封面横幅图video视频bookmarkAsset媒体书签对应的原始文件userUploaded用户手动上传的文件avatar/unknown用户头像与未知类型资产的上传、下载与解除由 packages/trpc/routers/assets.ts 及 packages/api/routes/assets.ts 提供接口。在数据关系上资产通过bookmarkId挂接到书签并可在书签详情页中被上传、下载或解除关联——对应官方文档描述的完整管理闭环。另外提醒一点链接书签的截图/存档是在创建后的抓取流程中生成的若当初未配置或生成失败随时可用recrawlBookmark携带archiveFullPage/storePdf重新抓取补齐。把它们组合起来一条健康的收藏工作流综合官方文档与源码一个推荐的日常流程是看到值得保存的内容用浏览器扩展或 Web 端保存为链接书签想法随手记成文本书签重要图片/PDF 存为媒体书签需要经常回访的点星标收藏放进专属收藏视图读完/处理完的内容追加笔记记录结论划出高亮留下关键句然后归档——首页只保留待办已归档内容依然全量可搜对可能失效的网页确保抓取配置生成了截图/整页存档必要时手动重抓。这套收藏—归档—搜索的组合正是 Karakeep 实现收件箱清零式知识管理的内核。延伸阅读想继续深入可参考当前仓库中的相关文档使用 Karakeep标签tags.md使用 Karakeep列表lists.md使用 Karakeep搜索查询语法search-query-language.md使用 Karakeep快速分享quick-sharing.md书签相关源码书签类型定义、书签路由实现、高亮路由实现、抓取 Worker【免费下载链接】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 书签系统完全指南收藏、归档、三种书签类型与笔记、高亮、附件的实战解析【免费下载链接】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 官方文档《Bookmarking》为核心系统讲解这款自托管书签应用中最基础也最关键的概念收藏Favourites、归档Archiving、链接/文本/媒体三种书签类型以及依附于书签之上的笔记、高亮与附件体系。读完本文你将清楚理解每种书签的内部数据模型与后台处理流程掌握用 Karakeep 实现收件箱清零inbox-zero式知识库管理的完整方法并能从源码层面理解保存一个链接后系统究竟做了什么。一切从一次保存开始Karakeep 中的书签是什么在 Karakeep 中所有内容都以书签bookmark为起点——无论是网页链接、随手粘贴的片段还是图片与 PDF。书签是数据组织的最小单元其余一切标签、列表、高亮、笔记、附件都围绕书签展开。从源码层面看书签的公共字段定义在 packages/shared/types/bookmarks.ts 的zBareBookmarkSchema中它揭示了每个书签的核心状态title标题最长 1000 字符MAX_BOOKMARK_TITLE_LENGTHarchived/favourited归档与收藏状态正是本文接下来要讲的两个核心开关note/summary个人笔记与 AI 摘要字段taggingStatus/summarizationStatus/embeddingStatusAI 打标签、摘要、向量嵌入的后台任务状态success/failure/pendingsource书签来源取值包括api、web、cli、mobile、extension、singlefile、rss、import表明书签可以通过浏览器扩展、命令行、移动端、RSS 订阅甚至导入流程进入系统。而书签的内容本身则由zBookmarkContentSchemapackages/shared/types/bookmarks.ts这一可辨识联合类型discriminated union承载按type字段区分为四种link、text、asset和unknown。这四种类型即官方文档中描述的 Links、Text、Media 三类外加一个历史兼容的unknown。接下来我们逐一展开。收藏Favourites给重要内容一个专属视图收藏是 Karakeep 中最轻量级的组织手段给喜欢的书签打上星标它们就会出现在专属的收藏视图中方便快速回访。官方文档的建议使用场景是反复重读的好文章、需要经常回来查阅的参考资料、值得分享的内容——一句话凡是想再打开一次的收藏品都值得星标。在数据模型层面收藏只是一个布尔字段zBareBookmarkSchema中的favourited: z.boolean()。修改它的入口是 packages/trpc/routers/bookmarks.ts 的updateBookmark变更操作调用方传入favourited: true/false即可切换状态。值得一提的是收藏状态并非只是改一个字段这么简单。从源码可以看到当input.favourited true时系统会触发两件额外的事记录bookmark.favorite事件日志logEvent见 bookmarks.ts触发RuleEngine的favourited事件bookmarks.ts这意味着你可以用 Karakeep 的自动化规则如收藏某类书签时自动打标签/发 Webhook把收藏行为变成工作流触发器。在前端收藏操作散布于各个书签卡片组件中如 BookmarkLayoutAdaptingCard.tsx 中通过bookmark.favourited切换星标图标BookmarkActionBar.tsx 则在卡片顶部展示收藏状态徽标批量场景下BulkBookmarksAction.tsx 支持对多选书签一次性收藏/取消收藏。归档Archiving把首页收拾干净却不丢失任何东西归档解决的是首页信息过载问题。它的行为模型非常清晰归档会把书签从首页隐藏但绝不删除已归档的书签仍然可被搜索到且保留全部标签、高亮和附件它的目标用户场景是收件箱清零——让首页只呈现待处理/未读完的内容处理完的内容一键归档眼不见心不烦但随时可以找回。与favourited一样archived也是zBareBookmarkSchema中的布尔字段通过updateBookmark传入archived: true/false切换。归档同样会触发事件日志bookmark.archive和 RuleEngine 的archived事件因此同样可以接入自动化规则。重要细节重新保存一个已归档的书签会自动将其恢复并置顶。这在 createBookmark 的去重逻辑中体现——当检测到 URL 已存在时系统默认会把archived重置为false并刷新createdAtresaved { createdAt: input.createdAt ?? now, archived: input.archived ?? false, ... }。不过如果书签来源是rss或importRESAVE_EXEMPT_SOURCES集合见 bookmarks.ts重复保存则保持无操作语义不会打乱已有书签的归档状态这是为了批量导入和 RSS 拉取的幂等性考虑。三种书签类型链接Links网页保存的主力军链接书签是最常用的类型通过浏览器扩展或 Web 端从网页保存。官方文档描述其能力为Karakeep grabs metadata, previews, screenshots, and archives when configured——即抓取元数据、生成预览、截图并在配置后保存页面存档。对应的数据结构是 zBookmarkedLinkSchema它解释了链接书签能存下什么字段含义url原始链接仅允许 http/https 协议由zBookmarkUrlSchema校验见 bookmarks.ts 类型文件title/description抓取到的标题与描述imageUrl/imageAssetId封面图 URL 及其资产 IDscreenshotAssetId/pdfAssetId/fullPageArchiveAssetId/videoAssetId截图、PDF、整页存档、视频等资产关联favicon站点图标readerViewStatus/readerViewScore阅读器视图可用性判定及 0–100 评分crawledAt/crawlStatus抓取时间与状态success/failure/pendingauthor/publisher/datePublished/dateModified文章级元数据从源码看创建链接书签的完整链路bookmarks.ts 的 createBookmark大致是去重attemptToDedupLink按 URL 查询是否已存在同 URL 书签存在则走重存逻辑恢复、置顶详见上文归档部分落库在事务中插入bookmarks表记录type: link与bookmarkLinks表URL 等链接专属数据入队抓取把bookmarkId投递到LinkCrawlerQueue或限流触发时的LowPriorityCrawlerQueue由 apps/workers/workers/crawlerWorker.ts 后台完成元数据、可读内容、截图、存档的抓取——这也是文档所说 when configured 的部分是否生成截图/整页存档取决于你的配置联动并行触发搜索索引重建triggerSearchReindex、Webhook 通知与 RuleEngine 的bookmarkAdded事件。此外createBookmark接受crawlPrioritylow/normal参数用于区分用户主动保存与批量导入的抓取优先级bookmarks.ts创建接口默认限流为每分钟 30 次bookmarks.createBookmark见 bookmarks.ts。若抓取失败或想重新生成截图/存档可通过recrawlBookmark重新入队支持archiveFullPage、storePdf两个选项见 bookmarks.ts。文本Text快速记录灵感与片段文本书签用于保存你直接粘贴进去的内容——想法、语录、随附链接的上下文说明等。它的数据结构极简zBookmarkedTextSchematext正文内容sourceUrl可选的来源链接例如从某篇文章摘录时保留出处。创建文本书签时后台会根据配置走不同路径bookmarks.ts若开启了嵌入自动索引serverConfig.embedding.enableAutoIndexing则投递到EmbeddingsQueue执行嵌入并顺带打标签否则投递到OpenAIQueue仅做标签任务。因此文本书签同样能获得自动标签与全文搜索能力。媒体Media图片与 PDF 的自动化内容提取媒体书签用于保存图片或 PDF 文件。官方文档强调其杀手锏是Karakeep automatically extracts content out of those files and makes them searchable——系统会自动从图片/PDF 中提取内容如 OCR 文本、PDF 文本并使其可被搜索。对应的数据结构是 zBookmarkedAssetSchemaassetType仅允许image或pdfassetId/fileName关联的上传资产sourceUrl来源链接size/content文件大小与提取出的内容。创建媒体书签时bookmarks.ts系统会先校验资产归属并检查其contentType是否在SUPPORTED_BOOKMARK_ASSET_TYPES集合内随后将bookmarkId写入资产记录并把任务投递到AssetPreprocessingQueue——由资产预处理 Worker 完成内容提取。这就是图片/PDF 内容可搜索背后的实现路径。笔记Notes给书签补充为什么重要官方文档对笔记的定义是给任意书签附加个人笔记用来记录上下文、提醒或下一步行动。笔记与书签绑定、可被搜索因此你可以在日后通过关键词找回当时为什么收藏它。在数据层笔记就是zBareBookmarkSchema中的note字段创建时可通过createBookmark的note参数一并写入之后通过updateBookmark的note参数随时修改bookmarks.ts。由于笔记字段参与搜索索引写入后系统会触发triggerSearchReindex重建索引确保笔记内容立即可搜。高亮Highlights阅读时划重点日后直达关键想法高亮用于在阅读过程中保存引文、摘要或 TODO。官方文档强调两点高亮会显示在书签详情视图/阅读器中且可被搜索让你能直接跳回关键观点所在位置。高亮的完整 CRUD 由 packages/trpc/routers/highlights.ts 提供包括按书签查询高亮列表、创建、更新与删除对应的数据模型定义在 packages/shared/types/highlights.ts。值得留意的是Karakeep 还支持阅读进度追踪updateReadingProgress仅对链接书签生效bookmarks.ts保存阅读偏移量、锚点文本与百分比配合阅读器让下次接着读成为可能。附件Attachments给书签挂上更多上下文附件是书签的外部存储舱截图、页面存档、视频、你上传的文件都可以挂在一个书签下。官方文档将其价值概括为截图与存档Screenshots archives当原网页变更或消失时充当回退副本——这就是自托管书签的网页快照保障上传文件Uploaded files把 PDF、笔记或配套素材与链接放在一起管理方式在书签详情视图上传、下载或解除detach附件。源码中附件的类型由 zAssetTypesSchema 定义一张表看清所有资产种类资产类型用途screenshot网页截图fullPageArchive整页存档SingleFile 类归档precrawledArchive预抓取存档linkHtmlContent链接 HTML 内容pdf/assetScreenshotPDF 与媒体书签截图bannerImage封面横幅图video视频bookmarkAsset媒体书签对应的原始文件userUploaded用户手动上传的文件avatar/unknown用户头像与未知类型资产的上传、下载与解除由 packages/trpc/routers/assets.ts 及 packages/api/routes/assets.ts 提供接口。在数据关系上资产通过bookmarkId挂接到书签并可在书签详情页中被上传、下载或解除关联——对应官方文档描述的完整管理闭环。另外提醒一点链接书签的截图/存档是在创建后的抓取流程中生成的若当初未配置或生成失败随时可用recrawlBookmark携带archiveFullPage/storePdf重新抓取补齐。把它们组合起来一条健康的收藏工作流综合官方文档与源码一个推荐的日常流程是看到值得保存的内容用浏览器扩展或 Web 端保存为链接书签想法随手记成文本书签重要图片/PDF 存为媒体书签需要经常回访的点星标收藏放进专属收藏视图读完/处理完的内容追加笔记记录结论划出高亮留下关键句然后归档——首页只保留待办已归档内容依然全量可搜对可能失效的网页确保抓取配置生成了截图/整页存档必要时手动重抓。这套收藏—归档—搜索的组合正是 Karakeep 实现收件箱清零式知识管理的内核。延伸阅读想继续深入可参考当前仓库中的相关文档使用 Karakeep标签tags.md使用 Karakeep列表lists.md使用 Karakeep搜索查询语法search-query-language.md使用 Karakeep快速分享quick-sharing.md书签相关源码书签类型定义、书签路由实现、高亮路由实现、抓取 Worker【免费下载链接】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），仅供参考
核心概念与实战解析)
