Karakeep 入门指南自托管 Bookmark Everything 应用的 AI 自动标签、全文检索与完整架构解析【免费下载链接】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前身 Hoarder是一款以自托管为第一公民的开源收藏一切应用支持链接、笔记、图片与 PDF并内置基于 AI 的自动标签、自动摘要、全文与语义搜索。本文基于官方入门文档并结合仓库源码系统讲解其核心功能、各功能对应的实现模块与配置项帮助你快速理解架构、完成部署并精准配置推理、抓取、OCR 与搜索能力。项目概览与定位Karakeep 是一个开源、可自托管的Bookmark Everything应用把链接、简单笔记、图片和 PDF 统一收进一个个人知识库并借助 AI 自动为内容打上标签、生成摘要。官方文档在 docs/docs/01-getting-started/01-intro.md 中开宗明义地强调两点核心设计理念AI 自动化你只需要扔内容进去剩下的自动抓取标题/描述/图片、自动打标签、自动摘要都由系统完成自托管优先Self-hosting as a first class citizen从 docker-compose.yml 到 charts、kubernetes 部署清单再到 docs 的安装章节整个项目围绕在自己的服务器上跑起来这一目标设计。项目的技术栈见 README.md 的 Stack 一节包括Next.jsApp Router构建 Web 应用前端位于 apps/webDrizzle ORM管理数据库与迁移schema 定义在 packages/db/schema.tsNextAuth负责认证支持密码、OAuth/SSO 与邀请码体系见 packages/trpc/routers/auth.ts 相关实现tRPC承担客户端与服务器通信路由集中在 packages/trpc/routersPuppeteer驱动无头浏览器抓取书签页面OpenAI / Ollama提供 LLM 推理自动标签、摘要、对话Meilisearch提供全文检索插件实现在 packages/plugins/search-meilisearch/src/index.ts。功能全景一份收藏全链路自动化官方文档在 Features 一节列出的能力几乎每一项都能在仓库中找到对应的实现模块。下面按从收藏到消费的链路逐一展开。链接元数据自动抓取保存一个链接后系统自动抓取标题、描述和封面图。这一链路由抓取 Worker 驱动核心入口是 apps/workers/workers/crawlerWorker.tsWorker 从CrawlerQueue取出任务先对目标域名做限流检查checkDomainRateLimit基于 packages/shared/ratelimiting.ts再通过预探测probe快速拿到 content-type 与元数据apps/workers/workers/crawler/probe.ts如果 URL 指向的是 PDF 或图片则通过handleAsAssetBookmarkapps/workers/workers/crawler/crawlAndParse.ts把链接型书签转换为资产型书签如果是普通网页则调用crawlAndParseUrl用无头浏览器渲染页面、解析正文并落盘截图、封面图与正文内容抓取完成后通过enqueuePostCrawlJobs依次触发推理标签/摘要/向量、搜索索引重建、视频下载与 webhook 通知apps/workers/workers/crawlerWorker.ts。相关开关集中在 packages/shared/config.tsCRAWLER_STORE_SCREENSHOT默认 true、CRAWLER_DOWNLOAD_BANNER_IMAGE默认 true、CRAWLER_FULL_PAGE_SCREENSHOT默认 false等。列表与协作书签可以按列表List归类并且多人可以协作维护同一个列表。对应的 tRPC 路由、模型与测试分别位于路由packages/trpc/routers/lists.ts、packages/trpc/routers/sharedLists.ts测试packages/trpc/routers/lists.test.ts、packages/trpc/routers/sharedLists.test.ts移动端列表管理 UI 见 apps/mobile/components/lists。全文与语义搜索所有已存储内容正文、标题、标签、笔记都支持全文搜索并可叠加语义搜索。实现要点搜索索引插件接口定义在 packages/shared/search.ts默认实现是 packages/plugins/search-meilisearch/src/index.ts 中的MeiliSearchProvider抓取完成后 Worker 会调用triggerSearchReindex重建索引apps/workers/workers/crawlerWorker.ts语义搜索依赖向量嵌入EMBEDDING_ENABLE_AUTO_INDEXING开启后embeddingsWorker.ts 会为书签生成 embedding 并写入向量存储默认模型text-embedding-3-small维度 1536见 packages/shared/config.ts从配置解析看语义搜索对客户端生效还需SEMANTIC_SEARCH_ENABLED、EMBEDDING_ENABLE_AUTO_INDEXING与 embedding 配置三者同时满足见 packages/shared/config.ts 中clientConfig.search的取值逻辑搜索查询语言与解析器位于 packages/shared/searchQueryParser.ts其语法说明见 docs/docs/04-using-karakeep/search-query-language.md。LLM 自动标签与摘要支持本地 Ollama这是 Karakeep 的招牌能力保存内容后LLM 自动分析正文并给出标签可选地生成摘要。推理任务统一由 inferenceWorker.ts 消费OpenAIQueue按type分发到runTagging/runSummarizationapps/workers/workers/inference/tagging.ts、apps/workers/workers/inference/summarize.ts。推理客户端的统一工厂是InferenceClientFactorypackages/shared/inference.ts配置了OLLAMA_BASE_URL时走OllamaInferenceClient——直接使用官方ollamaSDK并通过自定义 fetch 注入超时packages/shared/inference.ts配置了OPENAI_API_KEY时走 OpenAI 兼容客户端也支持通过OPENAI_BASE_URL指向任意 OpenAI 兼容网关。关键配置项默认值来自 packages/shared/config.ts环境变量默认值说明OPENAI_API_KEY/OLLAMA_BASE_URL未设置二者任一配置即启用推理inference.isConfiguredINFERENCE_TEXT_MODELgpt-5.6-luna文本推理模型Ollama 场景下为本地模型名INFERENCE_IMAGE_MODELgpt-4o-mini图片推理模型INFERENCE_ENABLE_AUTO_TAGGINGtrue是否自动打标签INFERENCE_ENABLE_AUTO_SUMMARIZATIONfalse是否自动生成摘要INFERENCE_LANGenglish标签语言偏好INFERENCE_CONTEXT_LENGTH2048推理上下文长度INFERENCE_OUTPUT_SCHEMAstructured输出格式structured/json/plainINFERENCE_NUM_WORKERS1推理 Worker 并发数Ollama 本地部署时还可设置OLLAMA_KEEP_ALIVE控制模型驻留时间。详细的 AI 提供商配置说明见 docs/docs/03-configuration/02-different-ai-providers.md。LLM Agent 友好CLI 与官方 Skills项目面向 OpenClaw、Hermes 等 LLM Agent 提供了一等支持CLI独立子包位于 apps/cli提供增删查改书签、列表、标签等命令用法文档见 docs/docs/05-integrations/02-command-line.md官方 Skills见 skills/SKILL.md 与 docs/docs/05-integrations/07-agentic-skills.md此外还有官方 MCP 服务器apps/mcp含 assets.ts、bookmarks.ts、highlights.ts 等模块及其测试。规则引擎Rule-based Engine支持通过用户自定义规则自动化管理书签例如命中规则后自动打标签、归档、移动到列表等。实现包括Workerapps/workers/workers/ruleEngineWorker.ts消费RuleEngineQueue引擎核心packages/trpc/lib/ruleEngine.ts路由与测试packages/trpc/routers/rules.ts、packages/trpc/routers/rules.test.ts。OCR从图片中提取文字图片类书签会进入 assetPreprocessingWorker.ts 做预处理默认使用Tesseract.js提取文字createWorker见 apps/workers/workers/assetPreprocessingWorker.ts并支持OCR_LANGS默认eng识别语言列表OCR_CONFIDENCE_THRESHOLD默认 50置信度阈值低于该值的识别结果会被丢弃OCR_USE_LLM默认 false开启后改用 LLM 进行图片文字提取需要已配置推理客户端未配置时回退 TesseractOCR_CACHE_DIR模型缓存目录。OCR 提取出的文本会参与全文检索与语义搜索这正是图片也能被搜索的底层支撑。全页归档与视频自动存档全页归档Full page archival基于 monolith可用CRAWLER_FULL_PAGE_ARCHIVE、CRAWLER_MONOLITH_TIMEOUT_SEC默认 5 秒、CRAWLER_MONOLITH_ARGS控制视频自动归档基于yt-dlp由 videoWorker.ts 消费VideoWorkerQueueexeca(yt-dlp, ...)见 apps/workers/workers/videoWorker.ts。相关配置CRAWLER_VIDEO_DOWNLOAD默认 false、CRAWLER_VIDEO_DOWNLOAD_MAX_SIZE默认 50 MB、CRAWLER_VIDEO_DOWNLOAD_TIMEOUT_SEC、CRAWLER_YTDLP_ARGS。批量操作、SSO、暗色模式与多语言批量操作bulkActions.ts与bulkTagActions.tsapps/web/lib配套测试 apps/web/lib/bulkActions.test.tsSSO通过 NextAuth 与 OAuth 配置实现见 packages/trpc/auth.ts、packages/trpc/routers/users.ts配置项为OAUTH_*见 packages/shared/config.ts另支持 Cloudflare TurnstileTURNSTILE_SITE_KEY/TURNSTILE_SECRET_KEY暗色模式Web 端由 theme-provider.tsx 提供移动端见 lib/useColorScheme.tsx多语言Web 端 i18n 资源位于 apps/web/lib/i18n34 个语言的 JSON 文件翻译通过 Weblate 协作维护。客户端生态浏览器插件、移动 App 与 REST API官方文档列出 Chrome、Firefox、Safari 三种浏览器扩展以及 iOS、Android 双端原生 App浏览器扩展位于 apps/browser-extensionmanifest 见 apps/browser-extension/manifest.json支持快速收藏当前页面SavePage.tsx、右键/快捷键调起、自定义请求头CustomHeadersPage.tsx等移动 AppExpo React Native 工程位于 apps/mobile支持离线阅读lib/offlineLibrary.ts、自定义服务器地址app/server-address.tsx等REST API官方 OpenAPI 规范在 packages/open-api/karakeep-openapi-spec.json服务端 API 路由在 apps/web/app/api每个端点的用法可查 docs/docs/api 目录下的.mdx文档如 list-bookmarks.api.mdx、create-bookmark.api.mdx。RSS 自动采集支持把 RSS 源作为饲料自动收藏新条目对应 Worker 为 feedWorker.ts路由为 packages/trpc/routers/feeds.ts含测试 feeds.test.ts文档见 docs/docs/05-integrations/06-rss-feeds.md。书签导入器与浏览器同步官方文档列出的导入来源包括 Chrome、Pocket、Linkwarden、Omnivore、Tab Session Manager。从 packages/shared/import-export/parsers.ts 可以看到实际支持的ImportSource更广html、pocket、matter、omnivore、linkwarden、tab-session-manager、mymind、readwise-reader、instapaper、onetab以及karakeep自身的导入/导出格式。每种来源都有独立的解析分支packages/shared/import-export/parsers.ts并配套 parsers.test.ts 与 importer.test.ts 测试。使用说明见 docs/docs/04-using-karakeep/import.md。此外通过floccus可将浏览器书签自动同步进 KarakeepKarakeep 提供 WebDAV/API 接口与 floccus 对接官方文档已将其列为推荐同步方式。Highlights高亮标注可以对已收藏内容标记并保存高亮片段相关实现路由与模型packages/trpc/routers/highlights.ts含测试 highlights.test.ts阅读器Web 端 apps/web/app/reader移动端 apps/mobile/components/readerAPI 文档create-highlight.api.mdx、get-bookmark-highlights.api.mdx。在线 Demo 与体验账号官方文档提供了在线体验地址https://try.karakeep.app可用以下演示账号登录email: demokarakeep.app password: demodemo注意事项Demo 预置了示例内容seed 数据可在仓库 snapshots/seed-data-2026-05-20-163735.json 查看Demo 处于只读模式以防滥用对应DEMO_MODE配置项packages/shared/config.ts可通过DEMO_MODE_EMAIL/DEMO_MODE_PASSWORD指定演示账号。快速部署以 Docker 为例虽然官方入门文档未展开安装步骤详见 docs/docs/02-installation/01-docker.md仓库自带的 docker-compose.yml 展示了完整的三个核心服务services: web: image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release} restart: unless-stopped volumes: - data:/data ports: - 3000:3000 env_file: - .env environment: MEILI_ADDR: http://meilisearch:7700 BROWSER_WEB_URL: http://chrome:9222 DATA_DIR: /data # 不要修改 chrome: image: ghcr.io/karakeep-app/karakeep-chrome:release restart: unless-stopped init: true command: - --disable-gpu - --disable-dev-shm-usage - --hide-scrollbars - --disable-blink-featuresAutomationControlled - --window-size1440,900 meilisearch: image: getmeili/meilisearch:v1.41.0 restart: unless-stopped env_file: - .env environment: MEILI_NO_ANALYTICS: true volumes: - meilisearch:/meili_data volumes: meilisearch: data:三个服务职责清晰web主应用Next.js tRPC Worker 进程都在其中运行数据默认存放在 Docker volumedata中如需挂载自定义目录可把data:/data改为/path/to/your/directory:/datachromePuppeteer 驱动的无头浏览器容器暴露在http://chrome:9222负责真实渲染网页配置项BROWSER_WEB_URL/BROWSER_WEBSOCKET_URL见 packages/shared/config.tsmeilisearch全文搜索引擎端口 7700数据在meilisearchvolume。其他部署方式还包括Unraid06-unraid.md、Arch Linux03-archlinux.md、Kuberneteskubernetes、TrueNAS08-truenas.md等。关于项目名称的由来官方文档对Karakeep这个名字做了说明它受阿拉伯语词كراكيبkarakeeb启发这个词常用来形容杂七杂八的零碎物品——那些看起来杂乱、却往往承载个人价值或潜在用途的东西。它让人联想到一个塞满东西的抽屉或盒子里面装着你舍不得扔掉的一切因为它们在某种意义上很重要或者说因为你是个囤积狂 hoarder。这个名字精准地呼应了产品定位——为数据囤积者打造的收纳工具。延伸阅读完整功能截图docs/docs/01-getting-started/02-screenshots.md环境变量完整清单docs/docs/03-configuration/01-environment-variables.md安全注意事项docs/docs/06-administration/01-security-considerations.md开发环境搭建docs/docs/08-development/01-setup.md仓库目录结构说明docs/docs/08-development/02-directories.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），仅供参考