Karakeep原 Hoarder项目全览自托管 Bookmark-Everything 应用的架构、能力与实战入门【免费下载链接】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是一个把自托管作为一等公民的开源收藏一切Bookmark Everything应用链接、笔记、图片与 PDF 都能收藏并由 AI 自动打标签、自动摘要。本文以官方入门文档为骨架结合本仓库源码配置解析、推理客户端、爬虫 Worker、OCR 与 RSS 订阅等实现为你梳理它的核心特性、技术栈、部署形态与上手路径读完即可判断它是否适合你的家庭服务器并知道从哪些文件入手深入了解。项目定位为数据囤积者而生的自托管应用Karakeep 的定位非常聚焦把你在网上随手发现的文章、工具、图片、PDF 全部收进自己的服务器并借助 AI 完成整理。入门文档 docs/versioned_docs/version-v0.29.0/01-intro.md 开篇即点明核心主张Karakeep (previously Hoarder) is an open source Bookmark Everything app that uses AI for automatically tagging the content you throw at it. The app is built with self-hosting as a first class citizen.它与传统书签管理器的最大差异在于两个关键词Bookmark Everything不止链接还有笔记、图片、PDF与AI 自动整理自动打标签、自动摘要。在版本 v0.29.0 的文档时代项目仍以 Hoarder 命名仓库根目录的 README.md 与各版本文档均保留了这一历史命名这一点在阅读历史版本资料时需要注意。功能全景从收藏到归档的完整链路入门文档用一张特性清单勾勒了产品全貌结合源码可以将其归纳为采集 → 整理 → 检索 → 沉淀 → 扩展五个环节1. 采集链接、笔记、图片与 PDF书签链接、简单笔记、图片和 PDF 存储收藏对象不限于 URL四种内容类型在共享类型定义 packages/shared/types 中有完整建模⬇️自动抓取链接标题、描述与预览图这是爬虫 Worker 的核心职责实现在 apps/workers/workers/crawlerWorker.tsRSS 订阅自动囤积Auto hoardingFeedRefreshingWorker每小时整点触发通过哈希将各订阅源均匀分散在 60 分钟内抓取见 apps/workers/workers/feedWorker.ts⬇️导入器支持从 Chrome、Pocket、Linkwarden、Omnivore、Tab Session Manager 导入存量书签浏览器书签同步可通过 floccus 实现与浏览器书签的自动同步。2. 整理列表、规则与 AI列表Lists将收藏内容归类到不同列表路由实现见 packages/trpc/routers/lists.ts✨AI 自动打标签与摘要这是项目的招牌能力支持 OpenAI 系 API也支持通过 Ollama 接入本地模型规则引擎Rule-based engine按自定义规则自动化管理收藏如自动打标签、自动归档Worker 位于 apps/workers/workers/ruleEngineWorker.ts️高亮Highlights对收藏内容做标记并保存路由见 packages/trpc/routers/highlights.ts☑️批量操作Bulk actions批量打标签、批量移动等前端逻辑在 apps/web/lib/bulkActions.ts 与 apps/web/lib/bulkTagActions.ts。3. 检索全文与语义搜索全文搜索基于 Meilisearch索引在 docker/docker-compose.yml 中以独立服务meilisearch形式部署多语言支持Web 端使用 i18next 管理多语言语言资源位于 apps/web/lib/i18n共 30 语言文件。4. 沉淀防链接腐烂与视频归档️整页归档Full page archival使用 monolith 将网页保存为单个 HTML 文件抵御链接腐烂link rot调用点见 apps/workers/workers/crawler/assetStorage.ts▶️视频自动归档使用 yt-dlp 下载视频实现在 apps/workers/workers/videoWorker.tsOCR 图片文字提取默认用 Tesseract多语言可选开启 LLM OCR 提升准确率见 apps/workers/workers/assetPreprocessingWorker.ts浏览器插件提供 Chrome 插件与 Firefox 扩展源码位于 apps/browser-extension移动端 AppiOS 与 Android 应用源码位于 apps/mobileExpo / React Native 技术栈。5. 扩展API、客户端与安全REST API 与多种客户端REST API 路由集中在 packages/api/routes同时提供 tRPC 路由packages/trpc/routers与官方 SDKpackages/sdkSSO 支持通过 OAuth/OIDC 集成实现配置项见下文深色模式Web 端通过 apps/web/components/theme-provider.tsx 提供自托管优先Self-hosting first官方提供 Docker 镜像与 Helm/Kubernetes 清单kubernetes。⚠️ 入门文档同时提醒该应用处于重度开发中under heavy development版本迭代较快升级前建议阅读 docs/docs/06-administration/07-legacy-container-upgrade.md 等迁移说明。技术栈与架构速览根目录 README.md 的 Stack 一节与 docs/docs/08-development/04-architecture.md 勾勒了核心技术选型层面技术仓库证据Web 前端Next.jsApp Routerapps/web/app/layout.tsx移动端Expo / React Nativeapps/mobile/package.json数据库SQLiteDrizzle ORM 迁移packages/db/schema.ts、packages/db/drizzle前后端通信tRPCpackages/trpc/routers/_app.ts网页爬取Puppeteer无头 Chromeapps/workers/workers/crawler全文搜索Meilisearchpackages/plugins/search-meilisearchAI 推理OpenAI 兼容 API / Ollamapackages/shared/inference.ts任务队列LiteQueue内置/ Restate可选插件packages/plugins/queue-liteque、packages/plugins/queue-restate认证NextAuth含 OAuth/OIDCapps/web/server/auth.ts架构上采用Web Workers 解耦的进程模型Web 进程负责 API 与 UI一系列独立 Workercrawler、inference、embedding、search、feed、video、webhook、rule-engine、backup、asset-preprocessing、admin-maintenance见 apps/workers/workers通过队列消费任务。这与 docker/Dockerfile 中单镜像多进程的打包方式相呼应。部署Docker Compose 一键起步官方推荐的部署方式是 Docker Compose配置见 docker/docker-compose.yml它编排了三个服务web主应用镜像ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}映射宿主机 3000 端口数据卷挂载到容器内/dataDATA_DIR固定为/data官方明确建议不要改动改挂载目录应调整 volume 映射而非该变量chrome无头浏览器容器通过BROWSER_WEB_URL: http://chrome:9222暴露给爬虫使用meilisearch搜索服务MEILI_ADDR指向它且默认关闭遥测MEILI_NO_ANALYTICS: true。启动流程详见 docs/docs/02-installation/01-docker.md先复制.env.example为.env并填入必要环境变量至少包括NEXTAUTH_SECRET可选OPENAI_API_KEY或OLLAMA_BASE_URL再执行docker compose up -d除 Docker 外仓库还提供 Kubernetes 清单kubernetes、Arch Linux、Debian/Ubuntukarakeep-linux.sh等部署方式分别见 docs/docs/02-installation 各章节。体验在线 Demo入门文档提供了一个在线演示环境用于快速体验功能而无需自建地址https://try.karakeep.app登录邮箱demokarakeep.app登录密码demodemo演示环境已预置部分示例数据且处于只读模式read-only以防滥用。需要说明的是演示站为外部托管服务与当前自托管仓库是两套环境实际自托管部署时可通过环境变量DEMO_MODE、DEMO_MODE_EMAIL、DEMO_MODE_PASSWORD配置自己的演示模式见 packages/shared/config.ts。仓库根目录的 screenshots/homepage.png 即应用主页的真实截图可作为部署后的预期效果参考。核心亮点源码深读AI 推理与自动打标签AI 自动打标签是入门文档着墨最多的能力其底层实现非常值得深入阅读。推理客户端统一封装在 packages/shared/inference.ts双后端抽象InferenceClientFactory根据配置优先选择 OpenAI 系客户端OpenAIInferenceClient否则回退到OllamaInferenceClient若两者都未配置则返回null即 AI 功能整体关闭OpenAI 客户端支持文本推理inferFromText与图像推理inferFromImage图片以 base64 data URL 传入并可按outputSchema选择structured/json/plain三种响应格式——其中structured使用zodResponseFormat强制结构化输出保证打标签结果可直接被 Zod schema 校验Ollama 本地模型通过ollama.generate流式推理stream: true把 Zod schema 用z.toJSONSchema转换为 JSON Schema 交给本地模型并透传num_ctx、num_predict、keep_alive等参数。源码注释还记录了一个已知的 ollama-js 流式响应兼容性 workaroundEmbedding 支持文本推理客户端同时实现EmbeddingClient接口OpenAI 的embeddings.create或 Ollama 的embed并校验向量维度与EMBEDDING_DIMENSIONS一致——这为语义搜索semantic search提供了基础。关键配置项来自 packages/shared/config.ts环境变量默认值说明OPENAI_API_KEY无配置后启用 OpenAI 推理后端OPENAI_BASE_URL无兼容 OpenAI 协议的自建网关/第三方地址OPENAI_PROXY_URL无推理请求的 HTTP 代理OLLAMA_BASE_URL无配置后启用 Ollama 本地模型后端OLLAMA_KEEP_ALIVE无本地模型在内存中的驻留时间INFERENCE_TEXT_MODELgpt-5.6-luna文本推理打标签/摘要模型INFERENCE_IMAGE_MODELgpt-4o-mini图像理解模型INFERENCE_ENABLE_AUTO_TAGGINGtrue是否自动打标签INFERENCE_ENABLE_AUTO_SUMMARIZATIONfalse是否自动摘要INFERENCE_LANGenglish生成标签/摘要的目标语言INFERENCE_CONTEXT_LENGTH2048上下文窗口Ollamanum_ctxINFERENCE_MAX_OUTPUT_TOKENS2048最大输出 token 数INFERENCE_OUTPUT_SCHEMAstructured输出格式structured/json/plainINFERENCE_NUM_WORKERS1推理 Worker 并发数INFERENCE_JOB_TIMEOUT_SEC30单次推理任务超时其中inference.isConfigured的判定逻辑!!OPENAI_API_KEY || !!OLLAMA_BASE_URL直接决定了 Web 端AI 功能是否可用的展示可参见 packages/shared/config.ts。摘要功能同样基于推理其 prompt 构造在 packages/shared/prompts.server.ts并通过 packages/trpc/routers/bookmarks.ts 暴露给前端。推理行为还有对应的单元测试作为行为契约例如 packages/shared/inference.test.ts 验证了不同outputSchema下response_format的正确传递。其他值得深入的功能实现OCR默认 Tesseract 方案在 apps/workers/workers/assetPreprocessingWorker.ts 中调用通过OCR_LANGS默认eng逗号分隔多语言、OCR_CONFIDENCE_THRESHOLD默认 50低于置信度的结果被丢弃与OCR_USE_LLM默认false开启后走 LLM 识别路径控制整页归档monolith 调用位于 apps/workers/workers/crawler/assetStorage.ts超时与额外参数分别由CRAWLER_MONOLITH_TIMEOUT_SEC默认 5 秒、CRAWLER_MONOLITH_ARGS控制视频归档apps/workers/workers/videoWorker.ts 通过execa(yt-dlp, ...)下载CRAWLER_VIDEO_DOWNLOAD_MAX_SIZE默认 50 MB与CRAWLER_VIDEO_DOWNLOAD_TIMEOUT_SEC默认 10 分钟约束资源消耗RSS 订阅apps/workers/workers/feedWorker.ts 每小时整点调度按 feed ID 哈希散列到分钟级避免同时抓取配额上限为MAX_RSS_FEEDS_PER_USER默认 1000。关于名字的由来入门文档专门解释了命名渊源Karakeep灵感来自阿拉伯语单词 كراكيبkarakeeb这是一个口语词常指杂七杂八的囤积物——那些看似凌乱、却往往藏着个人价值或潜在用途的小物件。它让人联想到一个塞满东西、又舍不得扔的抽屉或旧盒子——因为不知为何它们就是重要更可能的原因是你是个囤积狂。这个名字精准呼应了产品为数据囤积者服务的定位。进一步阅读入门文档docs/versioned_docs/version-v0.29.0/01-intro.md安装与配置docs/docs/02-installation/01-docker.md、docs/docs/03-configuration/01-environment-variables.md架构说明docs/docs/08-development/04-architecture.md、docs/docs/08-development/02-directories.md目录级 API 参考docs/docs/api环境变量权威清单packages/shared/config.ts【免费下载链接】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），仅供参考