Karakeep 最小化安装指南单容器部署不依赖 Meilisearch、Chrome 与 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/hoarder导读KarakeepHoarder是一款可自托管的收藏一切应用默认的完整 Docker 部署包含 Web 服务、Meilisearch 全文检索引擎、Chrome 无头浏览器以及 OpenAI/Ollama AI 推理服务四个组成部分。本文基于 Karakeep v0.32.0 官方文档中的最小安装Minimal Installation指南讲解如何在资源受限的环境下仅用一个web容器完成部署并逐一说明放弃各依赖服务后功能上的取舍以及如何基于最小部署逐步补齐全量能力。读完本文你将掌握最小化docker compose与docker run两种部署姿势、两个必需环境变量的含义、随机密钥的生成规范以及从最小安装平滑升级到完整安装的路径。一、为什么需要最小安装理解完整部署的依赖结构Karakeep 的完整安装依赖三项外部服务分别支撑三类核心能力。官方文档给出的默认部署见 完整安装指南Docker 与仓库根目录的 docker/docker-compose.yml是一个三服务编排服务镜像职责webghcr.io/karakeep-app/karakeep:releaseWeb 前端 API 后台 worker 进程单体镜像chromeghcr.io/karakeep-app/karakeep-chrome:release无头浏览器用于抓取页面截图与执行 JavaScriptmeilisearchgetmeili/meilisearch:v1.41.0全文搜索索引与检索其中web容器通过MEILI_ADDR: http://meilisearch:7700和BROWSER_WEB_URL: http://chrome:9222两个环境变量与另外两个服务互联。最小安装的核心理念是这三个依赖全部可以省略——前提是你愿意接受对应功能的降级。官方文档明确列出了省略后的后果不部署 Meilisearch搜索功能被完全禁用search functionality will be completely disabled。不部署 Chrome抓取crawling仍然可用但会失去对网站截图的能力且包含 JavaScript 动态内容的页面将无法被正确抓取。不配置 OpenAI/OllamaAI 自动打标签AI tagging功能被禁用。值得强调的是文档开头的警告指出除非确有必要官方仍推荐使用完整安装以发挥 Karakeep 的全部能力最小安装适合内存、磁盘或网络受限的环境如低配 VPS、树莓派、内网离线部署。二、最小化 docker compose 部署将以下内容保存为docker-compose.yml即可启动一个最小化的 Karakeep 实例services: web: image: ghcr.io/karakeep-app/karakeep:release restart: unless-stopped volumes: - data:/data ports: - 3000:3000 environment: DATA_DIR: /data NEXTAUTH_SECRET: super_random_string volumes: data:然后在同一目录执行docker compose up -d启动完成后访问http://localhost:3000即可看到登录/注册页面。配置项逐项说明image: ghcr.io/karakeep-app/karakeep:release官方发布的单体镜像。从 docker/Dockerfile 的构建过程看aio阶段通过 s6-overlay 进程管理器同时拉起数据库迁移init-db-migration、Web 服务svc-web和全部后台 workersvc-workers因此单个容器即可承载 API、定时任务与各类 worker这是最小安装只需一个容器的根本原因。镜像内置健康检查GET /api/health见 docker/Dockerfilerestart: unless-stopped保证异常退出后自动拉起。- data:/data将命名卷data挂载到容器内/data目录这是持久化数据的落盘位置。- 3000:3000容器内 Web 服务默认监听 3000 端口见 docker/Dockerfile 中ENV PORT 3000映射到宿主机 3000 端口如需对外发布可改为8080:3000等映射。DATA_DIR: /data必需。数据库文件所在目录资产抓取的截图、归档页面等默认存放在${DATA_DIR}/assets子目录下。完整说明见 packages/shared/config.ts 中assetsDir: val.ASSETS_DIR ?? path.join(val.DATA_DIR, assets)的实现逻辑。NEXTAUTH_SECRET: super_random_string必需。用于签名 JWT 令牌的随机字符串。虽然 packages/shared/config.ts 中该变量在 schema 层面是可选字段但运行时只要用到签名逻辑signingSecret()就会在未设置时直接抛出NEXTAUTH_SECRET is not set错误见 packages/shared/config.ts所以部署时必须显式配置。必读安全警告替换随机字符串官方文档强调必须将示例中的super_random_string替换为真正的随机字符串推荐使用以下命令生成openssl rand -hex 32这是全文部署中唯一不能跳过的一步——使用公开文档里的固定示例密钥意味着任何人都可能伪造你的登录令牌。三、使用 docker run 单命令部署如果不想引入 docker compose 文件也可以直接用一条docker run命令完成同样的最小部署docker run -d \ --restart unless-stopped \ -v data:/data \ -p 3000:3000 \ -e DATA_DIR/data \ -e NEXTAUTH_SECRETsuper_random_string \ ghcr.io/karakeep-app/karakeep:release各参数与上一节的 compose 配置一一对应-d后台运行、--restart unless-stopped自动重启、-v data:/data持久化数据卷、-p 3000:3000端口映射、-e注入两个必需环境变量。请同样将密钥替换为openssl rand -hex 32的输出。四、功能取舍的源码级原理4.1 未配置 Meilisearch搜索被完全禁用搜索功能的注册逻辑位于 packages/plugins/search-meilisearch/index.ts只有MeiliSearchProvider.isConfigured()返回真时Meilisearch 搜索插件才会被注册进插件管理器。当MEILI_ADDR未设置时该检查不通过随后 packages/shared/search.ts 中的getSearchClient()返回null前端与 API 层的搜索入口随之关闭。换言之只要不给web容器设置MEILI_ADDR全文搜索在最小安装下就是完全不可用的这是搜索功能被完全禁用的底层实现。4.2 未配置 Chrome抓取降级为纯 HTTP 模式抓取工作由 crawler worker 承担注册逻辑见 apps/workers/index.ts。根据 环境变量配置文档 中BROWSER_WEB_URL与BROWSER_WEBSOCKET_URL的说明当两者都未设置时crawler 会退化为纯 HTTP 请求模式跳过截图screenshotting与 JavaScript 执行两个环节。这意味着最小安装下静态页面服务端渲染的 HTML仍能被正常抓取、提取正文并建立书签依赖 JavaScript 渲染的 SPA 页面如大部分现代前端站点内容无法被正确抓取书签卡片不会生成网站截图CRAWLER_STORE_SCREENSHOT默认开启但无浏览器可用时无法产出。4.3 未配置 OpenAI/OllamaAI 自动打标签关闭AI 推理是否可用取决于 packages/shared/config.ts 中的一行判定isConfigured: !!val.OPENAI_API_KEY || !!val.OLLAMA_BASE_URL。两个变量都为空时推理配置未就绪自动打标签、自动摘要等基于 LLM 的能力全部跳过书签仍可正常保存只是缺少 AI 生成的标签。手动打标签与标签筛选不受影响。五、从最小安装向完整能力演进最小安装并非终点。当你后续希望解锁搜索、截图与 AI 打标签时有两种演进路径路径一在原 compose 中追加服务。参照仓库根目录的 docker/docker-compose.yml为web服务补充MEILI_ADDR、BROWSER_WEB_URL环境变量并新增chrome与meilisearch两个服务及对应数据卷meilisearch:/meili_data再在.env中配置MEILI_MASTER_KEY即可。路径二直接采用完整部署。参考 完整安装指南Docker 的步骤下载官方 compose 文件、配置.env含KARAKEEP_VERSION、NEXTAUTH_SECRET、MEILI_MASTER_KEY、NEXTAUTH_URL视需要追加OPENAI_API_KEY或改用 Ollama 本地推理最后docker compose up -d。启用 AI 打标签时至少需要OPENAI_API_KEY或OLLAMA_BASE_URL之一启用搜索时还需为 Meilisearch 生成主密钥官方推荐openssl rand -base64 36 | tr -dc A-Za-z0-9启用浏览器抓取后可进一步按需开启CRAWLER_FULL_PAGE_SCREENSHOT整页截图、CRAWLER_FULL_PAGE_ARCHIVE整页归档、CRAWLER_STORE_PDFPDF 快照等高级能力具体参数与默认值见 环境变量配置文档。六、补充建议与排障要点尽早配置NEXTAUTH_URL官方配置文档标记其为必需项。未设置时应用虽可运行但登出等操作会重定向到错误地址。它应指向你的服务对外地址如https://your.domain.com。最小安装阶段可先使用默认值正式对外提供服务前务必配置。日志级别生产环境可将LOG_LEVEL设为notice或warning避免debug级别日志刷屏默认值为debug见 packages/shared/config.ts。数据备份data命名卷包含 SQLite 数据库与资产文件迁移或备份时需整体保存Karakeep 也内置了管理面板中的备份功能backup worker见 apps/workers/index.ts。常见疑问若登录后搜索框消失说明MEILI_ADDR未配置符合最小安装预期若书签卡片无截图说明BROWSER_WEB_URL未配置若书签没有 AI 标签说明推理服务未配置。这三项均可通过补全对应环境变量后重启容器恢复无需重建数据卷。总结最小安装用一个容器 两个环境变量换来了极低的资源占用代价是放弃全文搜索、浏览器级抓取与 AI 打标签三块核心能力。理解每项取舍背后的源码机制搜索插件注册、抓取降级路径、推理配置判定可以帮助你在受限环境中快速上线 Karakeep并在资源充裕后平滑地补全依赖、恢复完整功能。完整的环境变量清单与取值约束可随时查阅 环境变量配置文档 及 packages/shared/config.ts 中的 zod 校验定义。【免费下载链接】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），仅供参考
