Karakeep（前身 Hoarder）自托管书签应用全解析：AI 自动打标签、全文搜索与 Docker 部署实战

Karakeep前身 Hoarder自托管书签应用全解析AI 自动打标签、全文搜索与 Docker 部署实战【免费下载链接】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 实现自动打标签与摘要、全文与语义搜索。本文以仓库根目录的 README.md 为骨架结合 docker/docker-compose.yml、packages/shared/config.ts、apps/workers/index.ts 等源码与 docs 目录下的官方文档完整梳理其功能全景、技术栈、Docker 部署步骤、环境变量与 AI 推理配置帮助读者在自建服务器上一站式落地这套数据囤积者的收藏工作流。项目定位与命名来源Karakeep 的定位是self-hostable bookmark-everything app with a touch of AI for the data hoarders——一个面向数据囤积者的、带一点 AI 能力的自托管收藏应用。它不只是收藏链接还可以承载笔记、图片、PDF并围绕收藏内容提供搜索、归档、协作与自动化能力。项目名称 Karakeep 的灵感来自阿拉伯语单词كراكيبkarakeeb这是一个口语化词汇泛指杂七杂八、看似凌乱却往往承载个人价值或潜在用处的小物件类似于装满了舍不得扔的东西的抽屉。这个命名精准呼应了产品的核心使用场景把散落各处、难以归类的内容统一收进来供日后随时翻找。功能特性全景README 中列出的功能覆盖了从收藏到消费再到自动化治理的完整链路逐项展开如下收藏与内容捕获收藏链接、速记笔记、图片与 PDF三种基础内容类型link / note / asset并支持批量操作Bulk actions。自动抓取链接标题、描述与图片由爬虫工作器完成链接被收藏后自动补充元数据与预览图。Mark 并保存收藏内容中的高亮highlights可以在已收藏的阅读内容上标记高亮片段并保存。浏览器扩展快速收藏提供 Chrome 插件、Firefox 扩展与 Safari 扩展对应源码位于 apps/browser-extension。iOS / Android 原生应用源码位于 apps/mobile并支持移动端离线阅读。导入器支持从 Chrome、Pocket、Linkwarden、Omnivore、Tab Session Manager 导入收藏并可借助 floccus 与浏览器书签自动同步。组织、检索与消费列表Lists将收藏整理进不同的列表并支持多人协作同一个列表。全文与语义搜索基于 Meilisearch 的全文索引加上 embedding 向量化后的语义搜索覆盖所有已存储内容。AI 自动打标签与摘要基于 LLM支持通过 Ollama 使用本地模型自动为收藏内容生成标签和摘要标签语言可通过INFERENCE_LANG配置。规则引擎基于规则的自动化管理例如按条件自动打标签、归档等由独立的ruleEngine工作器驱动见 apps/workers/index.ts。OCR 图片文字提取默认基于 tesseract.js也可切换为 LLM 驱动的 OCR。RSS 自动囤积Auto hoarding订阅 RSS 源后自动把新内容收藏入库。REST API 与多客户端项目提供 OpenAPI 规格 与官方 SDKdocs/docs/api 下收录了完整的 API 文档。归档与防链接腐坏整页归档Full page archival使用 monolith 将页面完整保存为单文件 HTML抵御链接腐坏link rot。自动视频归档使用 yt-dlp 下载页面视频。爬虫可选的PDF 快照、全页截图、banner 图本地缓存等均在环境变量文档中有对应开关见下文爬虫配置。平台与体验多语言支持通过 Weblate 管理翻译。SSO 支持支持 OIDC 兼容的 OAuth 登录。暗色模式、自托管优先的设计哲学。技术栈与仓库结构README 明确列出的技术栈如下组件用途Next.jsApp RouterWeb 应用主体Drizzle数据库 ORM 与迁移NextAuth认证tRPC客户端与服务端通信Puppeteer爬取收藏的网页OpenAIAI 打标签等推理可通过 Ollama 换本地模型Meilisearch全文内容搜索仓库是一个 pnpm Turbo 的 monorepo根 package.json 提供pnpm dev、pnpm build、pnpm db:migrate等脚本。官方 目录结构文档 给出了清晰的模块划分应用层apps/web主 Web 应用、apps/workers后台工作器、apps/mobileReact Native 移动应用、apps/browser-extension浏览器扩展、apps/landing落地页。共享包packages/db数据库 schema 与迁移、packages/trpc大部分业务逻辑以 tRPC 路由形式存在、packages/shared各应用共享的日志与配置、packages/shared-server队列、资产存储等仅服务端可用的服务、packages/plugins可插拔服务实现如文件系统与 S3 存储。工具链tooling/typescript、tooling/eslint、tooling/prettier、tooling/tailwind存放共享配置。从 apps/workers/index.ts 可以看到后台按职责拆成了 12 类工作器crawler、lowPriorityCrawler、embeddings、inference、search、adminMaintenance、video、feed、assetPreprocessing、webhook、ruleEngine、backup外加一个import轮询工作器它们各自消费独立的队列如LinkCrawlerQueue、OpenAIQueue、SearchIndexingQueue并通过WORKERS_ENABLED_WORKERS/WORKERS_DISABLED_WORKERS两个环境变量按需启停。Docker 部署实战Docker Compose 是官方推荐、也是最快上手的部署方式详见 Docker 安装指南。1. 创建目录并下载 compose 文件新建一个目录例如karakeep-app把官方提供的 docker/docker-compose.yml 放进去。该文件定义了三个服务web主应用镜像为ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}端口3000:3000数据卷data:/data并通过环境变量把MEILI_ADDR指向 meilisearch、BROWSER_WEB_URL指向 chrome 服务DATA_DIR固定为/data官方注释强调不要改要改数据目录应改卷映射。chrome爬虫用的 headless 浏览器容器镜像ghcr.io/karakeep-app/karakeep-chrome:release启动参数包含--disable-gpu、--disable-dev-shm-usage、--hide-scrollbars等。meilisearch搜索服务镜像getmeili/meilisearch:v1.41.0启用MEILI_NO_ANALYTICS: true数据卷meilisearch:/meili_data。2. 填写 .env 环境变量在 compose 文件同目录创建.env最小可用配置如下KARAKEEP_VERSIONrelease NEXTAUTH_SECRETsuper_random_string MEILI_MASTER_KEYanother_random_string NEXTAUTH_URLhttp://localhost:3000要点两个随机字符串务必替换可用openssl rand -base64 36生成MEILI_MASTER_KEY建议用openssl rand -base64 36 | tr -dc A-Za-z0-9生成避免特殊字符。NEXTAUTH_URL要指向你实际访问 Karakeep 的地址否则登出等场景会跳转到错误地址。KARAKEEP_VERSIONrelease会拉取最新稳定版要控制升级节奏可固定到具体版本如0.10.0。每次修改.env后都需要重新执行docker compose up使配置生效。3. 配置 AI可选但强烈推荐要启用自动打标签在.env中追加OPENAI_API_KEYkey即可。也可以改用其他 OpenAI 兼容服务或本地 Ollama见下文AI Provider 配置一节。4. 启动与验证docker compose up -d随后访问http://localhost:3000即可看到登录页。持久化存储与服务间联调web ↔ chrome ↔ meilisearch已由 compose 文件处理。5. 升级升级方式取决于KARAKEEP_VERSION的取值固定版本改版本号后重新docker compose up -d拉取新镜像使用release执行docker compose up --pull always -d强制拉取最新版本。若自定义 compose 仍在使用旧版 Alpine Chrome 镜像需参考 Chrome 镜像迁移指南升级/迁移 Meilisearch 版本时可参考 故障排查文档。环境变量配置详解Karakeep 以环境变量为主要配置入口全部变量统一定义在 packages/shared/config.ts使用 zod schema 做解析、默认值与校验完整参数说明见 环境变量文档。以下是按功能域划分的核心变量基础与安全变量必填默认值说明PORT否3000Web 服务监听端口用 Docker 时不要改它改外部端口映射即可WORKERS_PORT否0随机工作器导出 Prometheus 指标的端口/metricsWORKERS_HOST否127.0.0.1指标监听地址容器内运行需改为可外部访问的地址WORKERS_ENABLED_WORKERS否未设置逗号分隔的工作器白名单crawler,inference,search,adminMaintenance,video,feed,assetPreprocessing,webhook,ruleEngine,backupWORKERS_DISABLED_WORKERS否未设置逗号分隔的工作器黑名单优先级高于WORKERS_ENABLED_WORKERSLOG_LEVEL否debug按 winston 的日志级别定义生产环境建议notice或warningDATA_DIR是未设置持久数据目录数据库所在处未设置ASSETS_DIR时资产也存于此ASSETS_DIR否${DATA_DIR}/assets爬取资产的存储路径NEXTAUTH_URL是未设置服务器对外地址NEXTAUTH_SECRET是未设置用于签名 JWT 的随机串MEILI_ADDR否未设置Meilisearch 地址未设置则搜索被禁用MEILI_MASTER_KEY仅生产 启用搜索未设置Meilisearch 主密钥开发环境不需要MAX_ASSET_SIZE_MB否50允许上传的资产大小上限MBDB_WAL_MODE否false为 SQLite 开启 WAL 模式提升性能数据库在网络盘上时不要开启DISABLE_NEW_RELEASE_CHECK否false关闭管理面板中的新版本检查认证与注册变量默认值说明DISABLE_SIGNUPSfalse禁止新用户注册DISABLE_PASSWORD_AUTHfalse仅允许 OAuth 登录EMAIL_VERIFICATION_REQUIREDfalse注册需邮箱验证需配置 SMTPOAUTH_WELLKNOWN_URL未设置OAuth 提供商的 OpenID 配置地址OAUTH_CLIENT_ID/OAUTH_CLIENT_SECRET未设置OAuth 客户端凭证OAUTH_ID_TOKEN_SIGNED_RESPONSE_ALG未设置ID token 的 JWS 签名算法可选RS256…EdDSA与提供商实际算法不符会导致回调报 JWT 算法错误OAUTH_SCOPEopenid email profile请求的 scope 列表空格分隔OAUTH_PROVIDER_NAMECustom Provider登录页显示的提供商名OAUTH_AUTO_REDIRECTfalse仅 OAuth 认证时自动跳转提供商OAUTH_TIMEOUT3500等待提供商响应毫秒数遇outgoing request timed out可调大注意仅支持 OIDC 兼容的 OAuth 提供商且回调地址需配置为NEXTAUTH_URL/api/auth/callback/custom。资产存储本地磁盘 vs S3默认使用本地文件系统传入 S3 端点后自动切换为 S3 兼容对象存储变量说明ASSET_STORE_S3_ENDPOINTS3 端点 URL如 MinIO设置即启用 S3ASSET_STORE_S3_REGIONS3 区域ASSET_STORE_S3_BUCKET桶名使用 S3 时必填ASSET_STORE_S3_ACCESS_KEY_ID/ASSET_STORE_S3_SECRET_ACCESS_KEYS3 认证凭证ASSET_STORE_S3_FORCE_PATH_STYLEMinIO 等需设为true文档明确警告存储后端一经写入数据即不可随意切换否则需要手工迁移既有资产部署前应规划好存储方案。爬虫配置Crawler变量默认值说明CRAWLER_NUM_WORKERS1并发爬取任务数BROWSER_WEB_URL/BROWSER_WEBSOCKET_URL未设置浏览器调试地址都不设置时退化为纯 HTTP 请求跳过截图与 JS 执行CRAWLER_STORE_SCREENSHOTtrue存储网页截图作为图片提取失败的兜底CRAWLER_FULL_PAGE_SCREENSHOTfalse存储整页截图磁盘占用高默认关闭CRAWLER_STORE_PDFfalse存储页面 PDF 快照默认关闭CRAWLER_FULL_PAGE_ARCHIVEfalse整页本地归档默认关闭仅归档可读文本CRAWLER_VIDEO_DOWNLOADfalse用 yt-dlp 下载页面视频CRAWLER_VIDEO_DOWNLOAD_MAX_SIZE50视频最大体积MB-1禁用限制CRAWLER_JOB_TIMEOUT_SEC60爬取任务超时CRAWLER_ENABLE_ADBLOCKERtrue爬虫内置广告拦截CRAWLER_ENABLE_AUTOCONSENTtrue自动选择退出支持的同意弹窗CRAWLER_YTDLP_ARGS/CRAWLER_MONOLITH_ARGS[]追加 yt-dlp / monolith 参数多个参数用%%分隔BROWSER_COOKIE_PATH未设置加载到浏览器上下文的 cookie JSON 文件路径数组name/value必填domain、expires、httpOnly、sameSite等可选OCR 配置变量默认值说明OCR_CACHE_DIR$TEMP_DIRtesseract 模型下载目录OCR_LANGSeng逗号分隔的语言码置空可禁用 OCROCR_CONFIDENCE_THRESHOLD50置信度阈值0–100低于阈值不保存识别文本OCR_USE_LLMfalse改用推理模型OpenAI/Ollama做 OCR复杂图片效果更好Webhook 配置变量默认值说明WEBHOOK_TIMEOUT_SEC5webhook 请求超时WEBHOOK_RETRY_TIMES3重试次数Webhook 触发时请求头携带Authorization: Bearer WEBHOOK_TOKEN请求体为包含jobId、type、bookmarkId、userId、url、operation的 JSON。SMTP 与代理SMTPSMTP_HOST、SMTP_PORT默认587、SMTP_SECURE、SMTP_USER、SMTP_PASSWORD、SMTP_FROM用于注册邮箱验证等邮件功能。代理CRAWLER_HTTP_PROXY/CRAWLER_HTTPS_PROXY支持逗号分隔多代理随机选用作用于爬取、RSS 拉取与 webhook、CRAWLER_NO_PROXY绕过列表、CRAWLER_ALLOWED_INTERNAL_HOSTNAMES默认拦截解析到内网/回环/link-local 地址的请求用点前缀支持域名通配。可观测性变量默认值说明OTEL_TRACING_ENABLEDfalse启用 OpenTelemetry 分布式追踪OTEL_EXPORTER_OTLP_TRACES_ENDPOINT未设置追踪 OTLP 端点未设置则打到控制台OTEL_SAMPLE_RATE1.0追踪采样率EVENT_LOGS_ENABLEDfalse结构化事件日志登录、书签创建等PROMETHEUS_AUTH_TOKEN随机/api/metrics的 Bearer 认证令牌AI Provider 配置从 OpenAI 到本地 OllamaAI 能力自动打标签、摘要、语义搜索的 embedding是本项目的核心卖点之一。配置全貌见 AI Provider 指南核心规则是OPENAI_API_KEY与OLLAMA_BASE_URL至少设置其一自动打标签才会启用。OpenAI默认只需设置OPENAI_API_KEY默认推理模型为gpt-5.6-luna文本、gpt-4o-mini图片embedding 默认text-embedding-3-small/ 1536 维均可在.env中覆盖OPENAI_API_KEYsk-xxxxxxxxxxxxxxxx # INFERENCE_TEXT_MODELgpt-4.1-mini # INFERENCE_IMAGE_MODELgpt-4o-mini # EMBEDDING_TEXT_MODELtext-embedding-3-small # EMBEDDING_DIMENSIONS1536补充说明OPENAI_BASE_URL可指向任意 OpenAI 兼容 APIAzure、Gemini、OpenRouter、Perplexity、Cloudflare 等均可用此方式接入OPENAI_TIMEOUT_SEC未设置时沿用 OpenAI SDK 默认 10 分钟OPENAI_SERVICE_TIERflex可换取更低成本响应更慢、偶发资源不可用OPENAI_REASONING_EFFORT控制推理模型的思考强度。Ollama 本地推理Ollama 提供两种接入方式且地址必须能被 Karakeep 容器访问不能用 localhost方式一OpenAI 兼容端点推荐走/v1chat 接口消息格式化更可靠OPENAI_API_KEYollama OPENAI_BASE_URLhttp://ollama.mylab.com:11434/v1 INFERENCE_TEXT_MODELgemma3 INFERENCE_IMAGE_MODELllava EMBEDDING_TEXT_MODELembeddinggemma EMBEDDING_DIMENSIONS768 EMBEDDING_CONTEXT_LENGTH2048方式二原生 Ollama API注意此时绝不能设置OPENAI_API_KEY否则优先走 OpenAIOLLAMA_BASE_URLhttp://ollama.mylab.com:11434 # INFERENCE_OUTPUT_SCHEMAplain # 模型不支持结构化输出时需要OLLAMA_KEEP_ALIVE控制模型在内存中的驻留时长如5m、-1m永久驻留、0即时卸载INFERENCE_FETCH_TIMEOUT_SEC默认 300针对 Ollama 请求超时。其他 OpenAI 兼容提供商文档还给出了可直接套用的配置模板GeminiOPENAI_BASE_URLhttps://generativelanguage.googleapis.com/v1beta示例模型gemini-2.5-flash-lite、OpenRouterhttps://openrouter.ai/api/v1、Perplexityhttps://api.perplexity.ai、Azure模型名即部署名、Cloudflare Workers AI建议INFERENCE_OUTPUT_SCHEMAjson。Embedding 与语义搜索三个关键变量EMBEDDING_TEXT_MODEL、EMBEDDING_DIMENSIONS向量维度必须与模型一致、EMBEDDING_CONTEXT_LENGTH默认 8000 字符超出截断。Embedding 可独立使用另一家 OpenAI 兼容提供商EMBEDDING_OPENAI_API_KEY、EMBEDDING_OPENAI_BASE_URL未设置时回落到对应的OPENAI_*变量。支持可变维度的模型可设EMBEDDING_TEXT_MODEL_DIMENSION_OVERRIDE其值必须等于EMBEDDING_DIMENSIONS否则 Karakeep 启动失败。配置好 embedding 后需开启EMBEDDING_ENABLE_AUTO_INDEXINGtrueSEMANTIC_SEARCH_ENABLED默认true控制混合/语义搜索模式实验性。重要提醒不同模型的向量互不兼容更换 embedding 模型或维度后需要为全部书签重新生成向量。打标签/摘要相关调优INFERENCE_CONTEXT_LENGTH默认 2048 token决定送入模型的内容量调大提升标签质量但更费钱/费资源INFERENCE_MAX_OUTPUT_TOKENS默认 2048控制生成长度INFERENCE_LANG默认english指定标签语言INFERENCE_ENABLE_AUTO_TAGGING默认true与INFERENCE_ENABLE_AUTO_SUMMARIZATION默认false分别开关自动打标签与摘要INFERENCE_OUTPUT_SCHEMA默认structured可选json/plain适配模型的结构化输出能力。此外可在用户设置 → AI Settings中给自动打标签的 prompt 追加自定义指令并支持$tags、$aiTags、$userTags三个占位符分别替换为全部标签、AI 标签、人工标签。体验 Demo 与快速上手官方提供了在线 Demo访问https://try.karakeep.app使用demokarakeep.app/demodemo登录。Demo 预置了示例内容但处于只读模式以防滥用——适合在部署前先直观感受界面与交互。部署完成后可以继续阅读 docs 下的使用指南书签、列表、标签、搜索语法、导入、快速分享等以及 命令行工具 与 MCP 服务 的接入文档实现LLM Agent 友好的自动化工作流。项目背景、动机与生态构建动机作者长期在手机端浏览 Reddit/Twitter/Hacker News需要把值得稍后细读的内容收藏下来在尝试 Pocket、memos 等工具后发现它们缺少链接预览 自动打标签的组合能力于是决定自建。README 中也客观列举了作者参考过的同类工具memos、mymind、raindrop、Pocket、Linkwarden、Wallabag、Shiori这些内容可作为选型时的背景参考。翻译项目通过 Weblate 管理多语言翻译欢迎贡献。托管云服务若不想自托管官方提供 Karakeep Cloud 托管服务订阅收入用于支持项目开发。社区渠道官方 Discord 与 Twitterkarakeep_app是主要的交流渠道。许可证项目采用 AGPL-3.0 协议见 LICENSE。总结Karakeep 把收藏 AI 治理 全文/语义检索 归档防腐坏整合进一个自托管优先的 monorepo 中Web 端由 Next.js tRPC Drizzle 驱动后台按队列模型拆分成 12 类可独立启停的工作器资产存储支持本地磁盘与 S3 双后端AI 推理既可直连 OpenAI 也能通过 Ollama 完全本地化。对个人用户而言按 Docker 安装指南 三步即可完成部署对开发者而言目录结构文档、环境变量文档 与 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），仅供参考