Karakeep原 Hoarder自托管故障排查完全指南数据库、AI 打标、抓取与 Meilisearch 升级【免费下载链接】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 是一款可自托管的收藏一切应用书签、笔记与图片支持基于 AI 的自动打标与全文搜索。本指南以 v0.32.0 官方 Troubleshooting 文档为骨架结合仓库源码与 Docker 编排配置系统梳理自托管部署中最常见的五类故障——SQLite 数据库未初始化、Chrome 容器日志噪音、OpenAI/Ollama AI 打标失效、抓取失败以及 Meilisearch 版本迁移——并给出可复现的定位方法与修复步骤。读完本文你将能够根据容器日志与 docker-compose.yml 中的环境变量逐项排查并安全完成 Meilisearch 索引重建。故障排查的通用方法论先看日志再查配置原文档在每一节都强调同一件事先检查容器日志。这一原则在源码层面有直接对应——例如推理 worker 在onError回调中会记录失败信息见 inferenceWorker.ts爬虫在连接浏览器失败时会输出Failed to connect to the browser instance, will retry in 5 secs见 browser.ts。因此所有排查都应从以下命令开始# 查看 web 容器日志数据库、推理、抓取等核心逻辑都在 web 容器中 docker compose logs -f web # 查看 Meilisearch 容器日志索引与版本兼容问题 docker compose logs -f meilisearch # 查看 Chrome 容器日志抓取相关 docker compose logs -f chrome此外Karakeep 的日志级别由LOG_LEVEL环境变量控制默认值为debug见 config.ts这意味着默认部署下日志信息已经足够详细可直接用于定位绝大多数问题。SqliteError: no such table: user错误含义与产生原理这个错误通常意味着数据库没有完成初始化。Karakeep 使用 SQLite 作为主数据库通过 Drizzle ORM 管理 schema首次启动时应用会自动执行数据库迁移、创建user等核心表。如果应用启动时发现已有数据库文件但内容不完整或根本没有数据库文件就会出现no such table: user。两种常见原因与修复原文档给出了两类典型触发场景DATA_DIR 被清空Wiped DATA_DIRDATA_DIR指向的目录被清空或者底层存储目录发生了变更。如果是有意清空数据只需重启容器让应用重新初始化数据库即可docker compose restart webDATA_DIR 未配置Missing DATA_DIR如果你没有使用默认的 docker-compose.yml而是自定义了编排文件却忘了设置DATA_DIR环境变量就会导致数据库被初始化到服务实际读取目录之外的其他位置从而出现表不存在。源码级补充DATA_DIR 的默认值与其派生路径从 config.ts 可以看到DATA_DIR的 schema 定义为z.string().default()——即默认是空字符串这解释了为什么自定义编排时漏配该变量会出问题。更重要的是DATA_DIR还会派生其他关键路径assetsDir默认为path.join(val.DATA_DIR, assets)见 config.ts即附件目录默认挂在数据目录之下。而在默认编排中官方明确写死了DATA_DIR: /data并注释DONT CHANGE THIS见 docker-compose.yml同时通过卷映射data:/datadocker-compose.yml把 Docker 卷持久化到宿主机。官方注释还指出如果你希望把数据挂载到自定义目录应该修改卷映射volume mapping而不是 DATA_DIR 的值例如volumes: - /path/to/your/directory:/data也就是说容器内的/data是固定约定宿主机侧的持久化位置由卷映射决定擅自改动DATA_DIR值反而容易造成数据库与附件目录分裂、读写错位。Chrome Failed to Read DnsConfig如果你在 Chrome 容器日志中看到Failed to Read DnsConfig这是一个良性错误可以安全忽略。它与你在 Karakeep 中遇到的任何实际问题都无关。该错误源于 Chromium 在读取宿主 DNS 配置时的一种已知行为属于噪音日志。AI Tagging not workingOpenAI 场景Karakeep 的 AI 打标、摘要等功能由独立的推理 worker 执行。当使用 OpenAI 时打标不生效先看web容器日志通常问题出在以下几点OPENAI_API_KEY变量名拼写错误这会导致日志出现类似skipping inference as its not configured跳过推理因为它未配置的提示。源码中推理功能是否配置取决于!!val.OPENAI_API_KEY || !!val.OLLAMA_BASE_URL见 config.ts——只要这两个变量都为空系统就认为推理未配置并跳过而不会明确报错因此拼写错误极易被忽视。配置后忘记执行docker compose up修改.env或环境变量后必须重建/重启容器使配置生效docker compose up -d注意仅仅是docker compose restart不一定会重新加载所有环境变量稳妥做法是up -d让编排重新解析配置。OpenAI 账户余额不足OpenAI 要求账户预先充值否则会返回类似insufficient funds的错误。源码级补充推理相关的关键环境变量从 config.ts 可以整理出 OpenAI 场景下与推理直接相关的变量及其默认值环境变量默认值说明OPENAI_API_KEY无可选OpenAI API 密钥推理配置的判定依据之一OPENAI_BASE_URL无可选自定义 OpenAI 兼容端点OPENAI_PROXY_URL无可选代理 URLINFERENCE_TEXT_MODELgpt-5.6-luna文本推理模型打标/摘要INFERENCE_IMAGE_MODELgpt-4o-mini图片推理模型INFERENCE_ENABLE_AUTO_TAGGINGtrue是否启用自动打标INFERENCE_ENABLE_AUTO_SUMMARIZATIONfalse是否启用自动摘要另外若你设置了自定义OPENAI_BASE_URL但未显式设置INFERENCE_USE_MAX_COMPLETION_TOKENS源码会默认将其置为false见 config.ts这是因为默认的 gpt 5.6 系列模型需要该开关为true——这条逻辑同样适用于 Ollama 场景值得留意。AI Tagging not workingOllama 场景使用 Ollama 本地模型时打标失效同样先从日志入手。原文档列出的常见原因OLLAMA_BASE_URL变量名拼写错误同样会导致skipping inference as its not configured日志。该变量在 config.ts 中定义为z.string().url().optional()——注意它是URL 类型校验如果你填写的值不是一个合法 URL例如漏了协议头http://配置解析本身就会失败。配置后忘记执行docker compose up同上修改后需重建容器。没有修改INFERENCE_TEXT_MODEL这是 Ollama 场景最典型的坑。INFERENCE_TEXT_MODEL的默认值是gpt-5.6-luna见 config.ts如果不改Karakeep 会拿着 GPT 模型名去请求 Ollama而 Ollama 中并不存在该模型自然无法工作。使用 Ollama 时应显式指定为已拉取的模型例如INFERENCE_TEXT_MODEL: llama3.1Ollama 服务对 Karakeep 容器不可达具体又分两种情况Ollama 服务器与 Karakeep 容器不在同一个 Docker 网络network中把OLLAMA_BASE_URL配成了localhost。在 Docker 中localhost指向的是容器自身而非 Docker 宿主机。要访问宿主机服务需要按你的 Docker 平台选择正确的主机地址Linux 可用host.docker.internal或宿主机网关 IPmacOS/Windows 桌面版通常直接支持host.docker.internal或让 Ollama 与 Karakeep 加入同一自定义网络并使用服务名。源码级补充推理 worker 的实际执行路径Ollama/OpenAI 的推理任务最终由OpenAiWorker消费队列执行runOpenAI会读取serverConfig.inference中的模型与端点配置见 inferenceWorker.ts任务完成后通过attemptMarkStatus把书签的taggingStatus/summarizationStatus更新为success或failureinferenceWorker.ts。因此当你在管理界面看到书签的 tagging 状态一直处于 pending/failure 时直接去 web 容器日志里查推理 worker 输出的具体错误如模型不存在、连接超时、余额不足是最快的定位路径。Crawling not working抓取失效抓取功能依赖独立的 Chrome 容器karakeep-app/karakeep-chrome通过 CDP 协议提供浏览器能力。爬虫 worker 在启动时会读取BROWSER_WEB_URL并调用chromium.connectOverCDP连接该地址同时解析其主机名对应的 IP 后再发起连接见 browser.ts连接失败时每 5 秒重试一次并记录错误。原文档指出的最常见原因是你改了 Chrome 容器的名字service 名称却没有同步修改BROWSER_WEB_URL环境变量。默认编排中web 容器通过服务名chrome访问浏览器BROWSER_WEB_URL: http://chrome:9222见 docker-compose.yml。一旦你把 Chrome 服务的名字改成my-chrome之类的自定义名称而BROWSER_WEB_URL仍指向http://chrome:9222Docker 内部 DNS 将无法解析该主机名抓取随即失败。修复方法保持两者一致。改容器名时同步更新environment: BROWSER_WEB_URL: http://my-chrome:9222 # 与新的 service 名保持一致若你完全没有独立的 Chrome 容器例如browserless模式爬虫会记录Running in browserless mode并返回undefinedbrowser.ts这种情况下请确认你的部署方式确实不需要浏览器容器。Upgrading Meilisearch数据库版本迁移与索引重建为什么 Meilisearch 版本不能随意升级Meilisearch 是 Karakeep 用于书签搜索的全文检索引擎。当前仓库锁定的版本是v1.41.0见 docker-compose.yml官方建议没有充分理由不要升级。Meilisearch 的数据文件格式与引擎版本强绑定升级后你会看到类似这样的错误Your database version (x.x.x) is incompatible with your current engine version (x.x.x). To migrate data between Meilisearch versions, please follow our guide on ...官方推荐的变通修复步骤好消息是这个问题可以快速绕过——因为书签数据本身存在 SQLite 主数据库中Meilisearch 里的索引只是可重建的派生数据。步骤如下停止 Meilisearch 容器docker compose stop meilisearch删除或重命名数据目录进入 Meilisearch 卷挂载到/meili_data的位置删除或重命名其中的data.ms文件夹。使用默认编排时该目录位于名为meilisearch的 Docker 卷中见 docker-compose.yml# 重命名比删除更稳妥可在确认一切正常后再清理 docker compose run --rm -v meilisearch:/meili_data alpine mv /meili_data/data.ms /meili_data/data.ms.bak重新启动 Meilisearchdocker compose up -d meilisearch在管理界面触发全量重建索引以管理员身份登录 Karakeep进入Admin Settings Background Jobs管理设置 后台任务点击Reindex All Bookmarks重建所有书签索引。等待重建完成索引重建完成后搜索功能恢复正常。源码级补充Reindex All Bookmarks 到底做了什么Reindex All Bookmarks对应 tRPC 路由admin.reindexAllBookmarks见 admin.ts。其内部逻辑分为两步若未指定modifiedWithinSeconds过滤条件先调用搜索客户端执行clearIndex()清空现有索引admin.ts从 SQLite 中查出全部或指定时间窗口内修改的书签 ID逐个以低优先级QueuePriority.Low投递triggerSearchReindex任务admin.ts由搜索 worker 异步完成重建。对应的测试用例也验证了这条链路reindexAllBookmarks会调用triggerSearchReindex且优先级为低见 admin.test.ts。因此你可以放心清空索引后只要等待后台任务跑完搜索即可恢复无需手动恢复任何数据——书签数据从未丢失丢失的只是可重建的搜索索引。另外如果你只想重建部分书签例如最近 7 天修改过的也可以利用该接口支持的modifiedWithinSeconds参数做定向重建避免全量扫描。排查速查表症状优先查看的日志最常见根因一键修复SqliteError: no such table: userwebDATA_DIR 缺失或被清空配置DATA_DIR: /data或重启容器Chrome Failed to Read DnsConfigchrome良性噪音忽略AI 打标不生效OpenAIwebOPENAI_API_KEY拼写错误 / 未up/ 余额不足修正变量名、docker compose up -d、充值AI 打标不生效OllamawebOLLAMA_BASE_URL拼错、INFERENCE_TEXT_MODEL未改、网络不可达修正配置并指定本地模型名抓取失效web chrome容器改名后BROWSER_WEB_URL未同步让两者保持一致Meilisearch 版本不兼容meilisearch升级了非 1.41.0 引擎删除data.ms并重建索引延伸阅读完整的环境变量说明见 环境变量文档 与解析实现 config.ts不同 AI 提供商的配置方式见 AI 提供商配置默认部署编排与卷定义见 docker-compose.yml更多部署方式Docker、K8s、Unraid 等见 安装文档数据库迁移脚本与 schema 定义位于 packages/db如需彻底重建数据库可参考 数据库文档。【免费下载链接】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），仅供参考