Karakeep 书签Bookmarking完全指南收藏、归档、笔记、高亮与附件管理【免费下载链接】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的官方使用文档 bookmarking.md 为核心骨架结合仓库源码数据模型、tRPC 路由、服务实现深入讲解书签体系。你将掌握三种书签类型链接、文本、媒体的区别与创建方式理解收藏Favourites与归档Archive如何帮助你维护整洁的主页并学会用笔记Notes、高亮Highlights和附件Attachments为书签补充上下文。阅读本文后你不仅能熟练操作书签还能理解这些功能在数据库与 API 层是如何实现的从而更高效地使用 Karakeep 自托管实例。一切从书签开始Karakeep 的核心数据模型在 Karakeep 中一切内容都以书签Bookmark为起点。无论你保存的是网页链接、随手记录的文本片段还是图片/PDF 文件最终都会落成一条书签记录。这一设计在数据层体现得非常直观数据库中的bookmarks表定义见 packages/db/schema.ts是整张内容网络的枢纽其他内容——链接元数据、文本正文、标签、高亮、附件——都围绕它展开。从源码看每条书签的核心字段包括type书签类型取值为link、text、asset三者之一枚举定义见 packages/shared/types/bookmarks.ts对应文档中的 Links、Text、Media 三类。archived与favourited两个布尔字段默认均为false分别控制书签是否被归档、是否被标星收藏这正是主页整洁度两个管理维度的数据基础。note书签级个人笔记支持全文检索。taggingStatus/summarizationStatus/embeddingStatus后台任务的状态机字段取值pending/failure/success分别记录 AI 自动打标签、摘要生成、向量嵌入的进度其中summarizationStatus仅对链接类型书签启用见 packages/trpc/routers/bookmarks.ts。source书签来源枚举值为api、web、extension、cli、mobile、singlefile、rss、import即保存动作来自 Web 界面、浏览器扩展、CLI、移动端、RSS 抓取还是批量导入。一个值得注意的细节bookmarks表里名为createdAt的列实际存储的是lastSavedAt最近一次保存时间而真正的首次创建时间以dbCreatedAt记录、对外暴露为firstCreatedAt。源码注释packages/db/schema.ts明确说明重新保存一个已存在的书签会把它顶回列表顶部所有排序与筛选都基于最近保存时间。这一点会直接影响到下文提到的重新保存行为。Favourites把喜欢的书签固定在专属视图文档中指出收藏Favourites用于给喜欢的书签加星使其进入独立的收藏视图方便快速回访——比如值得反复阅读的文章、经常查阅的参考资料、准备分享给别人的内容。在实现层面收藏并不是独立的数据结构而是bookmarks表上的一个布尔标志favourited。数据库还为此建立了复合索引bookmarks_userId_favourited_lastSavedAt_id_idxpackages/db/schema.ts专门加速按用户 收藏状态 最近保存时间的分页查询——也就是说收藏视图的加载本质上是一次带索引的筛选查询。操作上你可以在 Web 界面书签卡片或详情页点击星标切换收藏状态。API 层面收藏/取消收藏统一走updateBookmark这个 tRPC mutationpackages/trpc/routers/bookmarks.ts当传入favourited: true或favourited: false时路由会更新书签公共字段并同步刷新modifiedAt。此外在重新保存一个已存在的链接时如果请求里带上了favourited字段也会一并覆盖原有收藏状态packages/trpc/routers/bookmarks.ts。使用建议收藏适合放常青内容——精读过的文章、长期参考的文档、需要反复查阅的资料。它和归档是互补的收藏是置顶关注归档是暂时移开视线。Archiving归档而不删除保持主页清爽文档对归档Archiving的定义非常清晰归档将书签从主页隐藏但不会删除归档后的书签仍然可被搜索并且保留全部标签、高亮和附件归档是实现主页收件箱归零inbox-zero式整洁的理想手段。这与收藏一样同样是bookmarks表上的布尔字段archived默认false在起作用。归档状态同样有专用复合索引bookmarks_userId_archived_lastSavedAt_id_idxpackages/db/schema.ts支撑首页未归档列表的快速分页。也就是说主页默认展示的就是archived false的书签而归档只是把标志位翻转为true数据本身标签、高亮、附件等外键关联原封不动。归档/取消归档同样通过updateBookmark完成传入archived: true或archived: false即可。值得注意的是归档动作会触发事件日志路由中记录了event.name: bookmark.archive与bookmark.archived状态packages/trpc/routers/bookmarks.ts说明归档是一个被纳入可观测体系的一等操作。一个容易被忽略但非常有用的联动行为重新保存re-save一个已归档的链接书签会自动把它恢复回主页顶部。在createBookmark的去重逻辑中packages/trpc/routers/bookmarks.ts当检测到 URL 已存在时会执行resaved更新其中archived被重置为false同时更新createdAtlastSavedAt使书签回到列表顶端。这意味着随手把文章再存一遍天然具备取消归档 置顶的效果。三种书签类型Links、Text 与 Media文档将书签划分为三类每类的保存方式与后台处理都不同。在类型枚举BookmarkTypespackages/shared/types/bookmarks.ts和创建路由createBookmarkpackages/trpc/routers/bookmarks.ts中三者有清晰的实现分支。Links网页链接书签链接书签用于保存来自 Web 或浏览器扩展的 URL。保存后Karakeep 会抓取crawl页面并提取元数据、预览图、截图并在配置了归档服务如 SingleFile时生成页面归档。数据上链接书签的核心记录在bookmarkLinks表中packages/db/schema.ts与bookmarks表一对一主键即书签 ID存储url必填保存时会被trim()去除首尾空白packages/trpc/routers/bookmarks.ts抓取得到的元数据title、description、author、publisher、datePublished、dateModified、imageUrlbanner 图、favicon正文与阅读视图htmlContent、readerViewStatus取值readable/not_readable/uncertain/unavailable、readerViewScore、readerViewReasons抓取状态机crawlStatuspending/failure/success、crawlStatusCode默认 200、crawledAt。创建链接书签时路由还会执行URL 去重attemptToDedupLinkpackages/trpc/routers/bookmarks.ts如果该 URL 已经存在则按上文所述执行重新保存逻辑并返回alreadyExists: true而不是创建重复条目。去重并非严格串行源码注释也说明了这一点This doesnt 100% protect from duplicates because of races但对日常使用已经足够。Text文本书签文本书签适合粘贴快速笔记、灵感、引用或为链接补充上下文。它的正文存放在bookmarkTexts表中包含text字段以及可选的sourceUrl来源链接。从createBookmark的 TEXT 分支packages/trpc/routers/bookmarks.ts可以看到文本书签的创建非常轻量直接写入text与sourceUrl不触发抓取。创建后文本内容同样进入搜索索引可以被全文检索命中。Media媒体书签图片 / PDF媒体书签用于保存图片或 PDF 文件。文档强调Karakeep 会自动从这些文件中提取内容并使其可搜索。这是书签一切理念的关键体现——不只是存下文件而是让文件内容进入检索体系。创建媒体书签的流程packages/trpc/routers/bookmarks.ts比前两类多一步必须先上传文件获得一个资产Asset再携带assetId创建书签路由会校验资产归属Asset.ensureOwnership并检查其contentType是否在受支持列表SUPPORTED_BOOKMARK_ASSET_TYPES中否则返回BAD_REQUESTUnsupported asset type。随后在事务中写入bookmarkAssets记录并把上传的资产标记为BOOKMARK_ASSET类型packages/trpc/routers/bookmarks.ts。文件内容可搜索的底层支持来自资产预处理Asset Preprocessing图片会走 OCR / 视觉理解管线PDF 会走文本提取管线提取出的内容进入搜索索引与向量库。这是独立于书签路由的后台任务体系由 apps/workers/workers/assetPreprocessingWorker.ts 负责消费队列。Notes给书签附加个人上下文文档将 Notes 描述为附加到任意书签的个人笔记用于记录上下文、提醒或下一步行动且笔记随书签一起被搜索。实现上笔记就是一个note文本字段直挂bookmarks表packages/db/schema.ts。你可以通过以下方式写入/更新笔记创建书签时直接携带note字段通过updateBookmark传入note更新packages/trpc/routers/bookmarks.ts在 Web 界面的书签详情视图中编辑。由于笔记属于书签记录本身它天然进入搜索索引——这正是可搜索、能回忆起当初为什么存它的实现基础。updateBookmark更新公共字段时总是会刷新modifiedAtpackages/trpc/routers/bookmarks.ts因此修改笔记也会让书签在排序上变新。补充一点从导入流程看笔记同样是受保护的内容。导入解析器在合并重复书签时会拼接笔记而非覆盖——existing.notes \${existing.notes}\n---\n${bookmark.notes}packages/shared/import-export/parsers.ts说明笔记被视为需要保留的珍贵上下文。Highlights在阅读中划重点高亮Highlights用于在阅读时保存引用、摘要或待办事项。文档强调高亮会显示在书签详情视图/阅读器中并且可搜索让你能直接跳转到关键想法。高亮是独立于书签正文的二级实体表结构见 packages/db/schema.tsbookmarkId所属书签删除书签时级联删除onDelete: cascadestartOffset/endOffset高亮在正文中的起止偏移用于在阅读器中精准定位文本text高亮选中的原文片段note附加在高亮上的个人批注color标记颜色枚举为red/green/blue/yellow默认yellow。高亮的增删改查由独立的 tRPC 路由highlightsAppRouter提供packages/trpc/routers/highlights.ts包括create、getForBookmark、get、getAll分页、search按文本搜索高亮、delete、update。其中search端点支持关键词检索高亮内容配合书签全文检索可以做到记得一句话就找回整篇书签。在 Web 端高亮主要在阅读器reader中创建与管理——选中正文片段即可划词高亮。数据库按bookmarks.id建立了highlights_bookmarkId_idx索引packages/db/schema.ts保证取某个书签的全部高亮是高效的。Attachments把补充资料和书签放一起附件Attachments用于在书签旁存放额外上下文文档列出的用途包括截图与页面归档作为原网页变更或消失时的兜底fallback上传的文件把 PDF、笔记或支撑素材与链接放在一起管理方式在书签详情视图中上传、下载或分离detach附件。在数据模型中附件对应assets表packages/db/schema.ts每条资产记录包含assetType、size、contentType、fileName并通过bookmarkId外键挂到书签上删除书签时级联删除。assetType枚举packages/db/schema.ts揭示了附件生态的丰富程度自动生成的附件LINK_BANNER_IMAGEbanner 图、LINK_SCREENSHOT页面截图、LINK_PDF页面转 PDF、LINK_FULL_PAGE_ARCHIVE完整页面归档、LINK_PRECRAWLED_ARCHIVE预抓取归档、LINK_VIDEO、LINK_HTML_CONTENTHTML 正文快照用户产生的附件BOOKMARK_ASSET媒体书签本体、USER_UPLOADED手动上传的文件系统资产AVATAR头像、BACKUP备份文件、UNKNOWN未知/兜底。可以看到文档所说的截图与归档是页面消失时的兜底是有明确实现支撑的抓取流水线packages/workers/workers/crawler 目录下的各 worker会把页面快照、截图、归档全部落为资产对象即使原网页 404 或改版你仍然拥有当时的完整内容。附件管理由 packages/trpc/routers/assets.ts 提供 API上传、下载、分离、替换等存储后端可插拔文件系统或 S3见 packages/plugins/assetstore-filesystem 与 packages/plugins/assetstore-s3具体存储方式由部署配置决定。实操建议围绕书签构建个人知识流结合官方文档与源码实现这里给出几条可直接落地的使用模式主页收件箱归零每天保存的新内容会堆在主页读完后用归档archived true移走归档内容随时可通过搜索找回标签、高亮、附件一个不少。收藏驱动高频回访把准备精读的文章、长期参考的 API 文档、要分享的资料加星在收藏视图集中处理阅读完毕后再取消收藏并归档。链接 文本 附件的组合遇到值得深读的网页保存为链接书签并附加一条note记录为什么存它若原文可能消失依靠截图/归档附件兜底想记录独立灵感时直接建文本书签图片/PDF 则作为媒体书签上传让内容进入全文检索。用高亮沉淀阅读产出在阅读器中给关键段落划高亮、附批注之后用高亮搜索快速回到原文的精确位置。利用重新保存机制归档后的书签再次保存同一 URL 会自动恢复并置顶——非常适合旧文新读的场景。这些操作在 Web 界面apps/web、移动端apps/mobile、浏览器扩展apps/browser-extension与 CLIapps/cli中均有对应入口API 层面则统一由 packages/trpc/routers/bookmarks.ts 与 packages/trpc/routers/highlights.ts 承载配合 packages/shared/types/bookmarks.ts 中定义的 Zod Schema 保证前后端类型一致。小结Karakeep 的书签体系设计遵循一个核心实体 多维补充的思路bookmarks表承载类型、状态与笔记bookmarkLinks/bookmarkTexts/bookmarkAssets按类型拆分内容assets表统一管理截图、归档与上传文件highlights表提供细粒度的阅读标注。收藏与归档只是两个布尔标志却通过精心设计的复合索引支撑起整洁主页与完整检索的双重体验。理解了这一数据模型无论是日常使用、通过 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考