尧图网页设计 
Karakeep 高级工作流实战规则引擎、REST API 与 Webhooks 的自动化集成指南【免费下载链接】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/hoarderKarakeep自托管 bookmark-everything 应用支持链接、笔记与图片收藏并提供 AI 自动打标签与全文搜索为进阶用户提供了三大自动化能力规则引擎Rule Engine、HTTP API 与 Webhooks。本篇技术指南以官方文档 advanced-workflows.md 为核心骨架结合仓库源码深入讲解三者的内部实现、配置参数与真实触发链路帮助你基于 Karakeep 构建收藏即处理的端到端自动化工作流。概述Karakeep 的三大自动化支柱Karakeep 的进阶工作流由三套互补的机制构成机制定位典型用途规则引擎在应用内部自动响应收藏事件自动打标签、收藏、归档、按内容路由到列表HTTP API与外部脚本、定时任务、自研工具交互批量导入/同步、自定义工具、服务间集成Webhooks将收藏事件推送到你自己的系统推送到写作队列、团队聊天、通知服务三者可以独立使用也可以组合成完整的自动化闭环例如Webhooks 感知新收藏 → 调用 API 查询详情 → 写入外部系统而规则引擎则能在应用内部完成同等工作无需任何外部代码。下面分别深入每个机制。规则引擎Rule Engine应用内 if-this-then-that规则引擎是 Karakeep 内置的自动化能力你可以创建如果……那么……if-this-then-that风格的规则基于书签的元数据或内容自动完成打标签、收藏或将其路由进列表等操作。官方文档特别指出它的实用场景保持收件箱整洁例如自动归档新闻邮件、按域名自动打标签、或标记视频类书签。规则的数据模型规则的完整结构定义在 packages/shared/types/rules.ts一条规则包含五个部分name规则名称必填至少 1 个字符description规则描述可空enabled是否启用event触发事件当该事件发生时评估规则condition匹配条件基于书签元数据/内容的过滤条件actions满足条件后执行的动作至少 1 个触发事件Event规则何时被评估事件定义了规则的触发时机完整枚举见 rules.ts事件类型含义附加字段bookmarkAdded书签被创建无tagAdded某个标签被添加tagIdtagRemoved某个标签被移除tagIdaddedToList被加入某个列表listIds规则中可指定多个列表removedFromList从某个列表移除listIdsfavourited被标记为收藏无archived被归档无从源码看规则中的addedToList/removedFromList事件与真实事件略有不同规则配置的是listIds数组任一命中即触发而实际事件携带单个listId。这一匹配逻辑实现在 ruleEngine.ts 的doesEventMatchRule中——当事件类型为addedToList/removedFromList时会比较规则中的列表集合是否包含该事件的实际列表 ID。匹配条件Condition规则何时真正生效条件基于书签的元数据或内容进行过滤所有条件类型见 rules.ts条件类型说明alwaysTrue恒真无条件匹配urlContains/urlDoesNotContainURL 包含/不包含指定字符串titleContains/titleDoesNotContain标题包含/不包含指定字符串importedFromFeed来自指定 RSS 订阅源feedIdbookmarkTypeIs书签类型为link/text/assetbookmarkSourceIs来源为api/web/cli/mobile/extension/singlefile/rss/import等hasTag带有指定标签tagIdisFavourited已被收藏isArchived已被归档and/or组合条件可嵌套最大嵌套深度 10 层这些条件的求值逻辑在 ruleEngine.ts 的doesBookmarkMatchConditions中逐一实现。例如titleContains会同时检查书签自身的title与链接抓取得到的link.title见 bookmarkTitleimportedFromFeed需要书签关联了指定的 RSS 订阅源。执行动作Action规则命中后做什么动作类型说明addTag/removeTag添加/移除指定标签tagIdaddToList/removeFromList加入/移出指定列表listIddownloadFullPageArchive排队执行整页归档抓取favouriteBookmark标记为收藏archiveBookmark归档书签动作的执行在 ruleEngine.ts 的executeAction中完成。值得注意的细节addTag使用onConflictDoNothing保证幂等不会重复添加已存在的标签downloadFullPageArchive并非同步执行而是向低优先级抓取队列LowPriorityCrawlerQueue投递一个archiveFullPage: true、runInference: false的任务由后台 crawler 异步完成ruleEngine.ts。规则引擎的运行链路与架构从源码可以梳理出完整的执行链路事件产生书签被创建、更新、收藏或归档时trpc 路由会调用RuleEngine.triggerOnEvent例如 bookmarks.ts 在创建书签时触发bookmarkAdded事件bookmarks.ts 在收藏/归档时触发对应事件。预筛选triggerOnEvent先调用matchesAnyRule检查该用户是否存在启用的规则匹配这些事件只有命中才向规则队列投递任务避免无意义的队列负载ruleEngine.ts。异步处理RuleEngineWorker消费队列任务加载书签与用户全部规则对每个事件逐一评估并执行动作ruleEngineWorker.ts。结果记录每个动作的成功/失败都会以ruleId type message的形式写入日志便于排查。Web 端的规则配置界面位于 apps/web/components/dashboard/rules事件选择器、条件构建器、动作构建器、规则编辑器与列表说明规则完全可以在 UI 中可视化配置无需手写代码。规则的增删改查接口定义在 packages/trpc/routers/rules.tsrules.create/rules.update/rules.delete/rules.list并带有所有权校验与标签/列表归属校验中间件。规则引擎的运维配置规则引擎的处理能力可通过环境变量调整相关配置见 01-environment-variables.md 与 config.ts环境变量必需默认值说明RULE_ENGINE_NUM_WORKERS否1规则引擎并发处理 worker 数量。若你有复杂的自动化规则且需要快速处理可适当调大规则引擎实战示例结合上述事件、条件、动作可以组合出官方文档推荐的典型场景自动归档新闻邮件事件bookmarkAdded 条件urlContains: newsletter.example 动作archiveBookmark让新闻邮件类的书签不再占据收件箱按域名自动打标签事件bookmarkAdded 条件urlContains: github.com 动作addTag: dev标记视频事件bookmarkAdded 条件bookmarkTypeIs: link 条件可叠加urlContains: youtube.com 动作addToList到稍后观看列表收藏联动事件favourited 条件alwaysTrue 动作addTag: starred收藏时自动补充标签。条件支持and/or组合与嵌套深度上限 10可以构建非常精细的匹配逻辑。HTTP API与应用同源的编程接口官方文档指出Karakeep 的 HTTP API 与 Web 应用使用的是同一套表面积same surface area the apps use——这意味着你在界面上能做的操作几乎都能通过 API 完成非常适合对接个人脚本、cron 定时任务或其他服务。API 认证API Key 与 Bearer Token所有 API 端点都需要在Authorization请求头中携带 Bearer tokenJWT 格式。API Key 可以在 Web UI 的Settings API Keys中生成详见 karakeep-api.info.mdx。API Key 支持细粒度的**作用域scope**控制。中间件实现见 apiKeyScopes.ts当请求使用 API Key 认证时会校验该 Key 是否被授予了对应资源与访问级别的作用域。以书签路由为例bookmarks.ts 对上传等操作同时要求assets与bookmarks两个资源的readwrite权限。因此生成 API Key 时应遵循最小权限原则只授予所需资源如bookmarks与访问级别read/readwrite。端点布局与分页API 遵循版本化 REST 风格路由在 packages/api/index.ts 中挂载核心端点前缀为/v1/v1/bookmarks书签的创建、查询、更新、删除、重抓取等/v1/lists列表管理/v1/tags标签管理/v1/highlights高亮管理/v1/users用户信息/v1/assets资源图片/PDF上传与获取/v1/backups备份管理/v1/feedsRSS 订阅源管理/v1/rssRSS 输出列表类端点使用基于游标的分页通过cursor与limit查询参数控制响应中包含nextCursor字段将其作为下一次请求的cursor即可翻页nextCursor为null表示没有更多结果karakeep-api.info.mdx。书签类型创建书签时必须指定类型API 支持三种类型karakeep-api.info.mdxlinkURL 书签可选抓取元数据text纯文本笔记asset上传的文件图片或 PDF。创建 link 书签时若 URL 已存在API 会返回已存在的书签HTTP 200否则创建成功返回 201。请求体 schema 的完整字段如title、archived、favourited、note、source、crawlPriority、importSessionId等定义在 create-bookmark.api.mdx 的 OpenAPI 规范中。使用 curl 调用 API 的示例基于上述信息一个典型的 API 调用如下# 创建 link 类型书签 curl -X POST https://your-karakeep.example/v1/bookmarks \ -H Authorization: Bearer API_KEY \ -H Content-Type: application/json \ -d { type: link, url: https://example.com/article, title: Example Article, archived: false, favourited: false } # 分页列出书签 curl https://your-karakeep.example/v1/bookmarks?limit50 \ -H Authorization: Bearer API_KEY利用该 API 可以编写个人脚本完成批量导入、数据同步、或构建自定义工具配合 cron 定时执行即可实现定期拉取/同步收藏数据。完整的端点文档位于 docs/docs/api每个端点都有详细的参数说明与状态码定义。命令行工具CLIAPI 的便捷封装若不想直接拼 HTTP 请求Karakeep 还提供了 CLI 客户端本质上是 API 的便捷封装支持操作书签、列表、标签以及批量导入/导出。安装与使用方式见 02-command-line.md# NPM 全局安装 npm install -g karakeep/cli # 或通过 Docker 运行 docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help # 使用 karakeep --api-key key --server-addr addr bookmarks add urlCLI 支持--api-key或环境变量KARAKEEP_API_KEY、--server-addr或KARAKEEP_SERVER_ADDR、--json输出等全局选项子命令涵盖auth、bookmarks、lists、tags、whoami等。CLI 的源码位于 apps/cli在需要脚本化操作场景下比裸 curl 更直观。Webhooks把收藏事件推送到你自己的系统Webhooks 让 Karakeep 在书签被添加、更新、抓取或归档时主动向你自己系统的 HTTP 端点发送通知。官方文档特别强调将 Webhooks 与 API 组合可以构建端到端自动化——例如把新保存的内容推送到写作队列或团队聊天。Webhook 事件类型一个 Webhook 可以订阅一个或多个事件完整枚举定义在 packages/shared/types/webhooks.ts事件触发时机触发位置源码created书签创建bookmarks.tsedited书签更新含重新保存已存在 URLbookmarks.ts、bookmarks.tscrawled链接抓取完成crawlerWorker.tsai taggedAI 自动打标签完成tagging.tsdeleted书签删除删除流程中触发可以看到crawled与ai tagged事件发生在后台 worker 中——这意味着一本书签从创建到抓取完成再到AI 打标签完成最多会触发多个不同事件的 webhook你可以据此编排多阶段流水线。Webhook 的投递机制与重试策略Webhook 是异步投递的trpc 路由或 worker 调用WebhooksService.triggerWebhook后任务进入WebhookQueue由WebhookWorker消费并逐个投递webhooks.service.ts。投递实现见 webhookWorker.ts关键行为包括失败重试默认最多重试 3 次可配置只有响应非 2xx 或请求异常时才重试超时控制单次请求超时时间可配置默认 5 秒使用AbortSignal.timeout实现并发控制投递 worker 数量可配置默认 1幂等设计请求体中携带jobId官方文档建议接收方用它做幂等去重01-environment-variables.md删除场景容错deleted事件对应的书签可能已从数据库删除worker 专门允许该操作在书签不存在时继续投递webhookWorker.ts。Webhook 请求体与鉴权Webhook 以POST方式投递 JSON 负载官方文档给出的示例01-environment-variables.md{ jobId: 123, type: link, bookmarkId: exampleBookmarkId, userId: exampleUserId, url: https://example.com, operation: crawled }实际投递代码确认了这一结构webhookWorker.ts其中operation即上表的事件名。注意url仅在书签存在且为 link 类型时携带deleted事件因书签已删除url与type可能缺失。如果你在创建 Webhook 时配置了 tokenKarakeep 会在投递请求中带上鉴权头webhookWorker.tsAuthorization: Bearer WEBHOOK_TOKEN接收方应校验该 token避免伪造请求。Webhook 的运维配置Webhook 相关环境变量01-environment-variables.md、config.ts环境变量必需默认值说明WEBHOOK_TIMEOUT_SEC否5单次 webhook 请求的超时时间秒WEBHOOK_RETRY_TIMES否3请求失败时的重试次数WEBHOOK_NUM_WORKERS否1投递并发 worker 数有多个端点或高流量时可调大MAX_WEBHOOKS_PER_USER否100单个用户可创建的 Webhook 数量上限另外单个 Webhook 的 URL 最长 500 字符、token 最长 100 字符事件数组至少 1 个webhooks.ts创建超过MAX_WEBHOOKS_PER_USER会返回 400 错误webhooks.service.ts。Webhook 管理Webhook 可以在 Web UI 的 Settings 中配置界面组件见 apps/web/components/settings/WebhookSettings.tsx 与事件选择器 WebhookEventSelector.tsx也通过 trpc 接口管理webhooks.create/webhooks.update/webhooks.list/webhooks.delete见 webhooks.ts。出于安全考虑API 返回的 Webhook 对象不会暴露 token 本身只返回hasToken布尔值webhooks.ts。组合实战端到端自动化工作流结合三大机制可以设计出完整的自动化链路。以新收藏进入写作队列为例收藏通过浏览器扩展、移动端或 API 保存一个链接规则引擎应用内事件bookmarkAdded 条件urlContains: todo 动作addTag: to-writeaddToList: 写作队列书签创建瞬间即被分类Webhooks推送到外部Webhook 订阅created事件crawled与ai tagged事件随后触发你的服务依次收到已创建 → 已抓取 → AI 已打标签三阶段通知可将最终带标签、带摘要的书签推入团队聊天或写作工具API主动拉取/批量操作外部系统按需调用/v1/bookmarks查询书签详情或通过import会话批量导入历史收藏。这样Karakeep 内部由规则引擎即时完成整理外部由 Webhooks 驱动事件通知再由 API 承载数据交换——三者的职责边界清晰、互为补充。延伸阅读规则、Webhook 的数据结构与校验 packages/shared/types/rules.ts、packages/shared/types/webhooks.ts规则引擎核心实现与测试 packages/trpc/lib/ruleEngine.ts、packages/trpc/routers/rules.ts、rules.test.tsWebhook 投递 worker apps/workers/workers/webhookWorker.tsAPI 路由挂载与作用域鉴权 packages/api/index.ts、packages/api/middlewares/apiKeyScopes.ts完整 API 端点文档 docs/docs/apiCLI 使用指南 docs/docs/05-integrations/02-command-line.md环境变量完整参考 docs/docs/03-configuration/01-environment-variables.md【免费下载链接】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 高级工作流实战：规则引擎、REST API 与 Webhooks 的自动化集成指南
Karakeep 高级工作流实战规则引擎、REST API 与 Webhooks 的自动化集成指南【免费下载链接】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/hoarderKarakeep自托管 bookmark-everything 应用支持链接、笔记与图片收藏并提供 AI 自动打标签与全文搜索为进阶用户提供了三大自动化能力规则引擎Rule Engine、HTTP API 与 Webhooks。本篇技术指南以官方文档 advanced-workflows.md 为核心骨架结合仓库源码深入讲解三者的内部实现、配置参数与真实触发链路帮助你基于 Karakeep 构建收藏即处理的端到端自动化工作流。概述Karakeep 的三大自动化支柱Karakeep 的进阶工作流由三套互补的机制构成机制定位典型用途规则引擎在应用内部自动响应收藏事件自动打标签、收藏、归档、按内容路由到列表HTTP API与外部脚本、定时任务、自研工具交互批量导入/同步、自定义工具、服务间集成Webhooks将收藏事件推送到你自己的系统推送到写作队列、团队聊天、通知服务三者可以独立使用也可以组合成完整的自动化闭环例如Webhooks 感知新收藏 → 调用 API 查询详情 → 写入外部系统而规则引擎则能在应用内部完成同等工作无需任何外部代码。下面分别深入每个机制。规则引擎Rule Engine应用内 if-this-then-that规则引擎是 Karakeep 内置的自动化能力你可以创建如果……那么……if-this-then-that风格的规则基于书签的元数据或内容自动完成打标签、收藏或将其路由进列表等操作。官方文档特别指出它的实用场景保持收件箱整洁例如自动归档新闻邮件、按域名自动打标签、或标记视频类书签。规则的数据模型规则的完整结构定义在 packages/shared/types/rules.ts一条规则包含五个部分name规则名称必填至少 1 个字符description规则描述可空enabled是否启用event触发事件当该事件发生时评估规则condition匹配条件基于书签元数据/内容的过滤条件actions满足条件后执行的动作至少 1 个触发事件Event规则何时被评估事件定义了规则的触发时机完整枚举见 rules.ts事件类型含义附加字段bookmarkAdded书签被创建无tagAdded某个标签被添加tagIdtagRemoved某个标签被移除tagIdaddedToList被加入某个列表listIds规则中可指定多个列表removedFromList从某个列表移除listIdsfavourited被标记为收藏无archived被归档无从源码看规则中的addedToList/removedFromList事件与真实事件略有不同规则配置的是listIds数组任一命中即触发而实际事件携带单个listId。这一匹配逻辑实现在 ruleEngine.ts 的doesEventMatchRule中——当事件类型为addedToList/removedFromList时会比较规则中的列表集合是否包含该事件的实际列表 ID。匹配条件Condition规则何时真正生效条件基于书签的元数据或内容进行过滤所有条件类型见 rules.ts条件类型说明alwaysTrue恒真无条件匹配urlContains/urlDoesNotContainURL 包含/不包含指定字符串titleContains/titleDoesNotContain标题包含/不包含指定字符串importedFromFeed来自指定 RSS 订阅源feedIdbookmarkTypeIs书签类型为link/text/assetbookmarkSourceIs来源为api/web/cli/mobile/extension/singlefile/rss/import等hasTag带有指定标签tagIdisFavourited已被收藏isArchived已被归档and/or组合条件可嵌套最大嵌套深度 10 层这些条件的求值逻辑在 ruleEngine.ts 的doesBookmarkMatchConditions中逐一实现。例如titleContains会同时检查书签自身的title与链接抓取得到的link.title见 bookmarkTitleimportedFromFeed需要书签关联了指定的 RSS 订阅源。执行动作Action规则命中后做什么动作类型说明addTag/removeTag添加/移除指定标签tagIdaddToList/removeFromList加入/移出指定列表listIddownloadFullPageArchive排队执行整页归档抓取favouriteBookmark标记为收藏archiveBookmark归档书签动作的执行在 ruleEngine.ts 的executeAction中完成。值得注意的细节addTag使用onConflictDoNothing保证幂等不会重复添加已存在的标签downloadFullPageArchive并非同步执行而是向低优先级抓取队列LowPriorityCrawlerQueue投递一个archiveFullPage: true、runInference: false的任务由后台 crawler 异步完成ruleEngine.ts。规则引擎的运行链路与架构从源码可以梳理出完整的执行链路事件产生书签被创建、更新、收藏或归档时trpc 路由会调用RuleEngine.triggerOnEvent例如 bookmarks.ts 在创建书签时触发bookmarkAdded事件bookmarks.ts 在收藏/归档时触发对应事件。预筛选triggerOnEvent先调用matchesAnyRule检查该用户是否存在启用的规则匹配这些事件只有命中才向规则队列投递任务避免无意义的队列负载ruleEngine.ts。异步处理RuleEngineWorker消费队列任务加载书签与用户全部规则对每个事件逐一评估并执行动作ruleEngineWorker.ts。结果记录每个动作的成功/失败都会以ruleId type message的形式写入日志便于排查。Web 端的规则配置界面位于 apps/web/components/dashboard/rules事件选择器、条件构建器、动作构建器、规则编辑器与列表说明规则完全可以在 UI 中可视化配置无需手写代码。规则的增删改查接口定义在 packages/trpc/routers/rules.tsrules.create/rules.update/rules.delete/rules.list并带有所有权校验与标签/列表归属校验中间件。规则引擎的运维配置规则引擎的处理能力可通过环境变量调整相关配置见 01-environment-variables.md 与 config.ts环境变量必需默认值说明RULE_ENGINE_NUM_WORKERS否1规则引擎并发处理 worker 数量。若你有复杂的自动化规则且需要快速处理可适当调大规则引擎实战示例结合上述事件、条件、动作可以组合出官方文档推荐的典型场景自动归档新闻邮件事件bookmarkAdded 条件urlContains: newsletter.example 动作archiveBookmark让新闻邮件类的书签不再占据收件箱按域名自动打标签事件bookmarkAdded 条件urlContains: github.com 动作addTag: dev标记视频事件bookmarkAdded 条件bookmarkTypeIs: link 条件可叠加urlContains: youtube.com 动作addToList到稍后观看列表收藏联动事件favourited 条件alwaysTrue 动作addTag: starred收藏时自动补充标签。条件支持and/or组合与嵌套深度上限 10可以构建非常精细的匹配逻辑。HTTP API与应用同源的编程接口官方文档指出Karakeep 的 HTTP API 与 Web 应用使用的是同一套表面积same surface area the apps use——这意味着你在界面上能做的操作几乎都能通过 API 完成非常适合对接个人脚本、cron 定时任务或其他服务。API 认证API Key 与 Bearer Token所有 API 端点都需要在Authorization请求头中携带 Bearer tokenJWT 格式。API Key 可以在 Web UI 的Settings API Keys中生成详见 karakeep-api.info.mdx。API Key 支持细粒度的**作用域scope**控制。中间件实现见 apiKeyScopes.ts当请求使用 API Key 认证时会校验该 Key 是否被授予了对应资源与访问级别的作用域。以书签路由为例bookmarks.ts 对上传等操作同时要求assets与bookmarks两个资源的readwrite权限。因此生成 API Key 时应遵循最小权限原则只授予所需资源如bookmarks与访问级别read/readwrite。端点布局与分页API 遵循版本化 REST 风格路由在 packages/api/index.ts 中挂载核心端点前缀为/v1/v1/bookmarks书签的创建、查询、更新、删除、重抓取等/v1/lists列表管理/v1/tags标签管理/v1/highlights高亮管理/v1/users用户信息/v1/assets资源图片/PDF上传与获取/v1/backups备份管理/v1/feedsRSS 订阅源管理/v1/rssRSS 输出列表类端点使用基于游标的分页通过cursor与limit查询参数控制响应中包含nextCursor字段将其作为下一次请求的cursor即可翻页nextCursor为null表示没有更多结果karakeep-api.info.mdx。书签类型创建书签时必须指定类型API 支持三种类型karakeep-api.info.mdxlinkURL 书签可选抓取元数据text纯文本笔记asset上传的文件图片或 PDF。创建 link 书签时若 URL 已存在API 会返回已存在的书签HTTP 200否则创建成功返回 201。请求体 schema 的完整字段如title、archived、favourited、note、source、crawlPriority、importSessionId等定义在 create-bookmark.api.mdx 的 OpenAPI 规范中。使用 curl 调用 API 的示例基于上述信息一个典型的 API 调用如下# 创建 link 类型书签 curl -X POST https://your-karakeep.example/v1/bookmarks \ -H Authorization: Bearer API_KEY \ -H Content-Type: application/json \ -d { type: link, url: https://example.com/article, title: Example Article, archived: false, favourited: false } # 分页列出书签 curl https://your-karakeep.example/v1/bookmarks?limit50 \ -H Authorization: Bearer API_KEY利用该 API 可以编写个人脚本完成批量导入、数据同步、或构建自定义工具配合 cron 定时执行即可实现定期拉取/同步收藏数据。完整的端点文档位于 docs/docs/api每个端点都有详细的参数说明与状态码定义。命令行工具CLIAPI 的便捷封装若不想直接拼 HTTP 请求Karakeep 还提供了 CLI 客户端本质上是 API 的便捷封装支持操作书签、列表、标签以及批量导入/导出。安装与使用方式见 02-command-line.md# NPM 全局安装 npm install -g karakeep/cli # 或通过 Docker 运行 docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help # 使用 karakeep --api-key key --server-addr addr bookmarks add urlCLI 支持--api-key或环境变量KARAKEEP_API_KEY、--server-addr或KARAKEEP_SERVER_ADDR、--json输出等全局选项子命令涵盖auth、bookmarks、lists、tags、whoami等。CLI 的源码位于 apps/cli在需要脚本化操作场景下比裸 curl 更直观。Webhooks把收藏事件推送到你自己的系统Webhooks 让 Karakeep 在书签被添加、更新、抓取或归档时主动向你自己系统的 HTTP 端点发送通知。官方文档特别强调将 Webhooks 与 API 组合可以构建端到端自动化——例如把新保存的内容推送到写作队列或团队聊天。Webhook 事件类型一个 Webhook 可以订阅一个或多个事件完整枚举定义在 packages/shared/types/webhooks.ts事件触发时机触发位置源码created书签创建bookmarks.tsedited书签更新含重新保存已存在 URLbookmarks.ts、bookmarks.tscrawled链接抓取完成crawlerWorker.tsai taggedAI 自动打标签完成tagging.tsdeleted书签删除删除流程中触发可以看到crawled与ai tagged事件发生在后台 worker 中——这意味着一本书签从创建到抓取完成再到AI 打标签完成最多会触发多个不同事件的 webhook你可以据此编排多阶段流水线。Webhook 的投递机制与重试策略Webhook 是异步投递的trpc 路由或 worker 调用WebhooksService.triggerWebhook后任务进入WebhookQueue由WebhookWorker消费并逐个投递webhooks.service.ts。投递实现见 webhookWorker.ts关键行为包括失败重试默认最多重试 3 次可配置只有响应非 2xx 或请求异常时才重试超时控制单次请求超时时间可配置默认 5 秒使用AbortSignal.timeout实现并发控制投递 worker 数量可配置默认 1幂等设计请求体中携带jobId官方文档建议接收方用它做幂等去重01-environment-variables.md删除场景容错deleted事件对应的书签可能已从数据库删除worker 专门允许该操作在书签不存在时继续投递webhookWorker.ts。Webhook 请求体与鉴权Webhook 以POST方式投递 JSON 负载官方文档给出的示例01-environment-variables.md{ jobId: 123, type: link, bookmarkId: exampleBookmarkId, userId: exampleUserId, url: https://example.com, operation: crawled }实际投递代码确认了这一结构webhookWorker.ts其中operation即上表的事件名。注意url仅在书签存在且为 link 类型时携带deleted事件因书签已删除url与type可能缺失。如果你在创建 Webhook 时配置了 tokenKarakeep 会在投递请求中带上鉴权头webhookWorker.tsAuthorization: Bearer WEBHOOK_TOKEN接收方应校验该 token避免伪造请求。Webhook 的运维配置Webhook 相关环境变量01-environment-variables.md、config.ts环境变量必需默认值说明WEBHOOK_TIMEOUT_SEC否5单次 webhook 请求的超时时间秒WEBHOOK_RETRY_TIMES否3请求失败时的重试次数WEBHOOK_NUM_WORKERS否1投递并发 worker 数有多个端点或高流量时可调大MAX_WEBHOOKS_PER_USER否100单个用户可创建的 Webhook 数量上限另外单个 Webhook 的 URL 最长 500 字符、token 最长 100 字符事件数组至少 1 个webhooks.ts创建超过MAX_WEBHOOKS_PER_USER会返回 400 错误webhooks.service.ts。Webhook 管理Webhook 可以在 Web UI 的 Settings 中配置界面组件见 apps/web/components/settings/WebhookSettings.tsx 与事件选择器 WebhookEventSelector.tsx也通过 trpc 接口管理webhooks.create/webhooks.update/webhooks.list/webhooks.delete见 webhooks.ts。出于安全考虑API 返回的 Webhook 对象不会暴露 token 本身只返回hasToken布尔值webhooks.ts。组合实战端到端自动化工作流结合三大机制可以设计出完整的自动化链路。以新收藏进入写作队列为例收藏通过浏览器扩展、移动端或 API 保存一个链接规则引擎应用内事件bookmarkAdded 条件urlContains: todo 动作addTag: to-writeaddToList: 写作队列书签创建瞬间即被分类Webhooks推送到外部Webhook 订阅created事件crawled与ai tagged事件随后触发你的服务依次收到已创建 → 已抓取 → AI 已打标签三阶段通知可将最终带标签、带摘要的书签推入团队聊天或写作工具API主动拉取/批量操作外部系统按需调用/v1/bookmarks查询书签详情或通过import会话批量导入历史收藏。这样Karakeep 内部由规则引擎即时完成整理外部由 Webhooks 驱动事件通知再由 API 承载数据交换——三者的职责边界清晰、互为补充。延伸阅读规则、Webhook 的数据结构与校验 packages/shared/types/rules.ts、packages/shared/types/webhooks.ts规则引擎核心实现与测试 packages/trpc/lib/ruleEngine.ts、packages/trpc/routers/rules.ts、rules.test.tsWebhook 投递 worker apps/workers/workers/webhookWorker.tsAPI 路由挂载与作用域鉴权 packages/api/index.ts、packages/api/middlewares/apiKeyScopes.ts完整 API 端点文档 docs/docs/apiCLI 使用指南 docs/docs/05-integrations/02-command-line.md环境变量完整参考 docs/docs/03-configuration/01-environment-variables.md【免费下载链接】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），仅供参考