企业官网建设流程全解析

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_idx（packages/db/schema.ts），专门加速"按用户 + 收藏状态 + 最近保存时间"的分页查询——也就是说，收藏视图的加载本质上是一次带索引的筛选查询。

操作上，你可以在 Web 界面（书签卡片或详情页）点击星标切换收藏状态。API 层面，收藏/取消收藏统一走updateBookmark这个 tRPC mutation（packages/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_idx（packages/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，同时更新createdAt（lastSavedAt）使书签回到列表顶端。这意味着"随手把文章再存一遍"天然具备"取消归档 + 置顶"的效果。

三种书签类型：Links、Text 与 Media

文档将书签划分为三类，每类的保存方式与后台处理都不同。在类型枚举BookmarkTypes（packages/shared/types/bookmarks.ts）和创建路由createBookmark（packages/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、imageUrl（banner 图）、favicon；
• 正文与阅读视图：htmlContent、readerViewStatus（取值readable/not_readable/uncertain/unavailable）、readerViewScore、readerViewReasons；
• 抓取状态机：crawlStatus（pending/failure/success）、crawlStatusCode（默认 200）、crawledAt。

创建链接书签时，路由还会执行URL 去重（attemptToDedupLink，packages/trpc/routers/bookmarks.ts）：如果该 URL 已经存在，则按上文所述执行"重新保存"逻辑并返回alreadyExists: true，而不是创建重复条目。去重并非严格串行，源码注释也说明了这一点（"This doesn't 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_REQUEST（Unsupported 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更新公共字段时总是会刷新modifiedAt（packages/trpc/routers/bookmarks.ts），因此修改笔记也会让书签在排序上"变新"。

补充一点：从导入流程看，笔记同样是受保护的内容。导入解析器在合并重复书签时会拼接笔记而非覆盖——existing.notes = \${existing.notes}\n---\n${bookmark.notes}``（packages/shared/import-export/parsers.ts），说明笔记被视为需要保留的珍贵上下文。

Highlights：在阅读中划重点

高亮（Highlights）用于在阅读时保存引用、摘要或待办事项。文档强调：高亮会显示在书签详情视图/阅读器中，并且可搜索，让你能直接跳转到关键想法。

高亮是独立于书签正文的二级实体，表结构见 packages/db/schema.ts：

• bookmarkId：所属书签，删除书签时级联删除（onDelete: "cascade"）；
• startOffset/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_IMAGE（banner 图）、LINK_SCREENSHOT（页面截图）、LINK_PDF（页面转 PDF）、LINK_FULL_PAGE_ARCHIVE（完整页面归档）、LINK_PRECRAWLED_ARCHIVE（预抓取归档）、LINK_VIDEO、LINK_HTML_CONTENT（HTML 正文快照）；
• 用户产生的附件：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），具体存储方式由部署配置决定。

实操建议：围绕书签构建个人知识流

结合官方文档与源码实现，这里给出几条可直接落地的使用模式：

1. 主页收件箱归零：每天保存的新内容会堆在主页，读完后用归档（archived = true）移走；归档内容随时可通过搜索找回，标签、高亮、附件一个不少。
2. 收藏驱动高频回访：把准备精读的文章、长期参考的 API 文档、要分享的资料加星，在收藏视图集中处理；阅读完毕后再取消收藏并归档。
3. 链接 + 文本 + 附件的组合：遇到值得深读的网页，保存为链接书签并附加一条note记录"为什么存它"；若原文可能消失，依靠截图/归档附件兜底；想记录独立灵感时直接建文本书签；图片/PDF 则作为媒体书签上传，让内容进入全文检索。
4. 用高亮沉淀阅读产出：在阅读器中给关键段落划高亮、附批注，之后用高亮搜索快速回到原文的精确位置。
5. 利用重新保存机制：归档后的书签再次保存同一 URL 会自动恢复并置顶——非常适合"旧文新读"的场景。

这些操作在 Web 界面（apps/web）、移动端（apps/mobile）、浏览器扩展（apps/browser-extension）与 CLI（apps/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