企业官网建设流程全解析

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_LENGTH）；
• archived/favourited：归档与收藏状态，正是本文接下来要讲的两个核心开关；
• note/summary：个人笔记与 AI 摘要字段；
• taggingStatus/summarizationStatus/embeddingStatus：AI 打标签、摘要、向量嵌入的后台任务状态（success/failure/pending）；
• source：书签来源，取值包括api、web、cli、mobile、extension、singlefile、rss、import，表明书签可以通过浏览器扩展、命令行、移动端、RSS 订阅甚至导入流程进入系统。

而书签的内容本身则由zBookmarkContentSchema（packages/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时，系统会触发两件额外的事：

1. 记录bookmark.favorite事件日志（logEvent，见 bookmarks.ts）；
2. 触发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并刷新createdAt（resaved = { createdAt: input.createdAt ?? now, archived: input.archived ?? false, ... }）。不过，如果书签来源是rss或import（RESAVE_EXEMPT_SOURCES集合，见 bookmarks.ts），重复保存则保持"无操作"语义，不会打乱已有书签的归档状态，这是为了批量导入和 RSS 拉取的幂等性考虑。

三种书签类型

链接（Links）：网页保存的主力军

链接书签是最常用的类型，通过浏览器扩展或 Web 端从网页保存。官方文档描述其能力为："Karakeep grabs metadata, previews, screenshots, and archives when configured"——即抓取元数据、生成预览、截图，并在配置后保存页面存档。

对应的数据结构是 zBookmarkedLinkSchema，它解释了链接书签"能存下什么"：

从源码看，创建链接书签的完整链路（bookmarks.ts 的 createBookmark）大致是：

1. 去重：attemptToDedupLink按 URL 查询是否已存在同 URL 书签，存在则走"重存"逻辑（恢复、置顶，详见上文归档部分）；
2. 落库：在事务中插入bookmarks表记录（type: link）与bookmarkLinks表（URL 等链接专属数据）；
3. 入队抓取：把bookmarkId投递到LinkCrawlerQueue（或限流触发时的LowPriorityCrawlerQueue），由 apps/workers/workers/crawlerWorker.ts 后台完成元数据、可读内容、截图、存档的抓取——这也是文档所说 "when configured" 的部分：是否生成截图/整页存档取决于你的配置；
4. 联动：并行触发搜索索引重建（triggerSearchReindex）、Webhook 通知与 RuleEngine 的bookmarkAdded事件。

此外createBookmark接受crawlPriority（low/normal）参数，用于区分用户主动保存与批量导入的抓取优先级（bookmarks.ts）；创建接口默认限流为每分钟 30 次（bookmarks.createBookmark，见 bookmarks.ts）。若抓取失败或想重新生成截图/存档，可通过recrawlBookmark重新入队（支持archiveFullPage、storePdf两个选项，见 bookmarks.ts）。

文本（Text）：快速记录灵感与片段

文本书签用于保存"你直接粘贴进去的内容"——想法、语录、随附链接的上下文说明等。它的数据结构极简（zBookmarkedTextSchema）：

• text：正文内容；
• 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 文本）并使其可被搜索。

对应的数据结构是 zBookmarkedAssetSchema：

• assetType：仅允许image或pdf；
• assetId/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 定义，一张表看清所有资产种类：

资产的上传、下载与解除由 packages/trpc/routers/assets.ts 及 packages/api/routes/assets.ts 提供接口。在数据关系上，资产通过bookmarkId挂接到书签，并可在书签详情页中被上传、下载或解除关联——对应官方文档描述的完整管理闭环。另外提醒一点：链接书签的截图/存档是在创建后的抓取流程中生成的，若当初未配置或生成失败，随时可用recrawlBookmark（携带archiveFullPage/storePdf）重新抓取补齐。

把它们组合起来：一条健康的收藏工作流

综合官方文档与源码，一个推荐的日常流程是：

1. 看到值得保存的内容，用浏览器扩展或 Web 端保存为链接书签；想法随手记成文本书签；重要图片/PDF 存为媒体书签；
2. 需要经常回访的，点星标收藏，放进专属收藏视图；
3. 读完/处理完的内容，追加笔记记录结论，划出高亮留下关键句，然后归档——首页只保留待办，已归档内容依然全量可搜；
4. 对可能失效的网页，确保抓取配置生成了截图/整页存档，必要时手动重抓。

这套"收藏—归档—搜索"的组合，正是 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