KarakeepHoarder部署故障排查完全指南数据库初始化、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/hoarder本文是 Karakeep前身 Hoarder自托管部署场景下的故障排查实战指南覆盖 Docker Compose 部署中最常遇到的六类问题SQLite 数据库未初始化SqliteError: no such table: user、Chrome 容器告警日志、OpenAI / Ollama 两种推理后端的 AI 自动打标失效、爬虫无法工作以及升级 Meilisearch 后的索引版本不兼容迁移。读完本文你将掌握如何通过容器日志与环境变量逐一定位根因并能在不影响已有书签数据的前提下完成索引重建与版本迁移。排查前置先看日志与数据目录Karakeep 的部署采用多容器架构核心服务在 docker/docker-compose.yml 中定义web主应用 API、chrome无头浏览器负责页面抓取、meilisearch书签全文搜索。绝大多数故障都会以日志形式输出因此排查的第一步永远是docker compose logs -f web # 主服务日志 docker compose logs -f chrome # 爬虫容器日志 docker compose logs -f meilisearch同时在源码层面Karakeep 的所有环境变量统一由 packages/shared/config.ts 中的 Zod schema 解析校验。这意味着环境变量名拼写错误、取值非法例如OLLAMA_BASE_URL不是合法 URL都会导致配置解析异常或功能静默关闭。排查时可以对照该文件确认变量名与默认值例如OPENAI_API_KEYconfig.tsOpenAI 推理密钥可选OLLAMA_BASE_URLconfig.tsOllama 服务地址要求必须是合法 URLINFERENCE_TEXT_MODELconfig.ts推理文本模型名默认值随版本而定DATA_DIRconfig.ts数据目录默认空字符串Compose 部署下固定为/dataBROWSER_WEB_URLconfig.tsChrome 容器地址可选。SqliteError: no such table: user数据库未初始化该错误表示 SQLite 数据库不存在或为空——具体而言是服务在启动时没有找到已初始化的数据库文件即user表尚未被创建。Karakeep 的主数据库是 SQLite其文件路径由DATA_DIR决定packages/db/drizzle.config.ts 中明确写为serverConfig.dataDir ? \${serverConfig.dataDir}/db.db : ./db.db即数据库文件为DATA_DIR/db.db。原因一DATA_DIR被清空或底层存储目录变更默认 Compose 部署中docker/docker-compose.yml 将名为data的 Docker volume 挂载到容器内/data同时DATA_DIR/datadocker-compose.yml 中明确注释“DONT CHANGE THIS”。如果你的DATA_DIR指向的目录被误清空、volume 被删除重建或底层存储目录被更换数据库文件就随之消失。处理方式若是有意清空例如希望重置环境直接重启容器让服务重新执行数据库迁移db:migrate以初始化全部表结构。但若数据原本有备份切勿直接重启覆盖应先恢复备份文件再启动。原因二未配置DATA_DIR自定义部署场景如果你没有使用仓库自带的默认 Compose 文件而是自建部署最容易犯的错误是忘记设置DATA_DIR环境变量。此时服务端与爬虫/搜索等子进程各自计算出的数据库位置不一致——一个进程在目录 A 写入数据另一个进程却去目录 B 读取自然找不到表。处理方式在所有服务进程web、worker 等上保持DATA_DIR一致例如统一设为/data并保证该目录挂载了持久化卷。修改后需重启全部相关容器使配置生效。这一点同样适用于ASSETS_DIR未设置时会默认取path.join(DATA_DIR, assets)见 packages/shared/config.ts可见数据目录的一致性直接关系到资产文件是否可读。Chrome Failed to Read DnsConfig良性错误可安全忽略在chrome容器的日志中如果看到类似Failed to Read DnsConfig的报错可以放心忽略。这是无头 Chromium 在容器化环境尤其是缺少 systemd-resolved 或完整 DNS 配置的容器中的常见噪音日志属于浏览器内部的 DNS 配置探测失败并不影响实际抓取功能。判断依据很简单如果爬虫功能链接抓取、截图、PDF 存储工作正常那么这条日志与你的任何问题都无关不要围绕它浪费时间排查。若确实存在抓取异常请转向下一节的BROWSER_WEB_URL检查。AI 自动打标不工作OpenAI 后端启用 AI 打标INFERENCE_ENABLE_AUTO_TAGGING默认开启见 config.ts后如果书签始终没有生成标签先查看web容器日志日志通常会直接指出问题。常见原因如下OPENAI_API_KEY变量名拼写错误变量名拼错会导致配置解析不到密钥日志中会出现类似 “No inference client configured, nothing to do now” 的信息。这一现象有明确的源码依据推理 worker 在 apps/workers/workers/inference/inferenceWorker.ts 中先通过InferenceClientFactory.build()构建客户端若返回空则直接打印该日志并跳过任务而工厂的构建逻辑packages/shared/inference.ts只认OPENAI_API_KEY或OLLAMA_BASE_URL是否已配置。因此请核对.env文件中变量名拼写与 config.ts 完全一致。配置后忘了重启容器环境变量在进程启动时读取修改.env后必须执行docker compose up -d或docker compose restart web让变更生效。Karakeep 的 Compose 文件通过env_file: .env注入配置docker-compose.yml不重启就不会重新加载。OpenAI 账户余额不足OpenAI 要求账户预充值后才能调用 API。余额不足时 API 会返回insufficient funds之类的错误日志中会体现为推理任务失败。此时需要到 OpenAI 平台为账户充值后再重试。进阶OpenAI 相关可调参数除了OPENAI_API_KEYconfig.ts 还支持以下可选参数用于对接代理或定制请求行为OPENAI_BASE_URL自定义 API 端点兼容 OpenAI 协议的网关OPENAI_PROXY_URL出站代理地址OPENAI_TIMEOUT_SEC请求超时秒数OPENAI_SERVICE_TIER取值auto/default/flex控制服务层级OPENAI_REASONING_EFFORT取值none/minimal/low/medium/high/xhigh控制推理强度。这些参数最终会通过 packages/shared/inference.ts 中的OpenAIInferenceClient.fromConfig()组装进 OpenAI 客户端并透传到chat.completions.create请求中inference.ts。AI 自动打标不工作Ollama 后端使用本地 Ollama 时排查思路类似先看容器日志。常见原因OLLAMA_BASE_URL变量名拼写错误拼错后工厂检测不到配置日志同样会出现 “No inference client configured, nothing to do now”。同时注意该变量要求是合法 URLz.string().url()见 config.ts格式非法也会导致解析失败。配置后忘了重启容器同样需要docker compose up -d使.env变更生效。未修改INFERENCE_TEXT_MODEL导致仍在使用 GPT 模型名请求 Ollama这是最容易踩的坑。INFERENCE_TEXT_MODEL的默认值是 OpenAI 系模型名config.ts而 Ollama 客户端fromConfig()中textModel直接取自该变量packages/shared/inference.ts并以该名字调用ollama.generateinference.ts。如果 Ollama 本地没有拉取同名模型请求必然失败。必须将其改为 Ollama 中实际存在的模型名例如llama3、qwen2.5等并确认ollama pull 模型名已完成。Ollama 服务与 Karakeep 容器网络不通常见两种子情况不在同一 Docker 网络Karakeep 容器无法解析/访问 Ollama 容器。可让两者加入同一个docker network或用 Compose 的external_links/ 自定义网络编排。OLLAMA_BASE_URL误用localhost在容器内部localhost指向的是容器自身而非 Docker 宿主机。应改用宿主机在 Docker 网络中的地址Linux 下通常为http://host.docker.internal:11434需 Docker 20.10 支持或宿主机局域网 IPWindows/macOS 的 Docker Desktop 下可用host.docker.internal。总之要让该 URL 能从 Karakeep 容器内实际访问到 Ollama 的 11434 端口。爬虫不工作Crawling not working书签抓取依赖chrome无头浏览器容器Karakeep 通过BROWSER_WEB_URL与之通信。默认 Compose 文件中该值为http://chrome:9222docker-compose.yml这里的chrome是服务名在 Docker 网络内可解析。最常见的原因你修改了 chrome 容器的名称例如在自定义 Compose 中命名为headless-browser却没有同步修改BROWSER_WEB_URL。此时 web 容器仍按旧名chrome解析无法连接浏览器爬虫任务全部失败。处理方式将BROWSER_WEB_URL改为实际容器名对应的地址例如http://headless-browser:9222然后重启容器。开发环境的 Composedocker/docker-compose.dev.yml也采用同样的BROWSER_WEB_URL环境变量约定便于本地调试时覆盖。若使用远程浏览器服务可配合BROWSER_WEBSOCKET_URLWebSocket 方式连接见 config.ts接入。升级 Meilisearch数据库版本迁移与索引重建Meilisearch 是 Karakeep 用于书签全文搜索的引擎Compose 中独立容器见 docker-compose.yml其数据 volume 挂载于/meili_data。Meilisearch 对数据格式有版本兼容约束随意升级引擎版本可能触发类似下面的错误Your database version (1.11.1) is incompatible with your current engine version (1.13.3).出现该错误说明旧的data.ms数据目录格式与新版引擎不兼容。Karakeep 为此提供了低成本的工作区恢复方案无需手工迁移数据文件停止 Meilisearch 容器例如docker compose stop meilisearch清除索引数据进入挂载到/meili_data的 volume 内部将名为data.ms的目录重命名或删除建议先改名备份如data.ms.bak确认无误后再清理重新启动 Meilisearch 容器此时引擎会用空索引启动全量重建索引以管理员身份登录 Karakeep Web 界面进入Admin Settings Background Jobs对应源码组件 apps/web/components/admin/BackgroundJobs.tsxi18n 文案 “Reindex All Bookmarks” 见 apps/web/lib/i18n/locales/en/translation.json点击Reindex All Bookmarks。该按钮在服务端的实现位于 packages/trpc/routers/admin.tsreindexAllBookmarks会先清空搜索索引searchIdx?.clearIndex()再取出全量书签 ID 逐条投递到低优先级重索引队列triggerSearchReindex(b.id, { priority: QueuePriority.Low })。因此点击后无需盯着页面任务会在后台批量完成。等待重索引完成后搜索功能即恢复正常——书签本体数据SQLite 与资产文件不受影响丢失的只是搜索引擎的索引副本。版本建议官方对 Meilisearch 的态度是“没有充分理由不建议升级”因为每次升级都可能引入数据格式变更与重新索引的额外操作成本。具体引擎版本随 Karakeep 发行版本演进v0.28.0 文档时代对应的引擎版本为 1.13.3而当前仓库的 docker/docker-compose.yml 中固定为getmeili/meilisearch:v1.41.0。升级前请以你所部署版本对应的 Compose 文件为准保持引擎版本与官方锁定版本一致即可避免绝大多数兼容性问题。若重索引过程中遇到异常可在Background Jobs页面观察任务状态并结合meilisearch容器日志定位确认迁移无误后再删除data.ms.bak备份目录。小结一张排查速查表症状首选检查项关键证据位置no such table: userDATA_DIR是否被清空 / 是否一致配置packages/db/drizzle.config.ts、docker-compose.ymlChrome 容器 DNS 报错无需处理良性日志—AI 打标失效OpenAIOPENAI_API_KEY拼写、重启容器、账户余额packages/shared/inference.ts、inferenceWorker.tsAI 打标失效OllamaOLLAMA_BASE_URL拼写、INFERENCE_TEXT_MODEL改为本地模型、容器网络互通packages/shared/inference.ts爬虫不工作BROWSER_WEB_URL是否匹配 chrome 容器名docker-compose.ymlMeilisearch 版本不兼容清空data.ms并触发 Reindex All Bookmarkspackages/trpc/routers/admin.ts、BackgroundJobs.tsx总体而言Karakeep 的故障面高度集中在“环境变量配置一致性与容器网络互通”两点上只要.env变量名与 packages/shared/config.ts 定义严格一致、修改后记得docker compose up -d重启、容器间地址解析正确绝大多数问题都能在几分钟内定位并恢复。【免费下载链接】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），仅供参考
Karakeep（Hoarder）部署故障排查完全指南：数据库初始化、AI 打标、爬虫与 Meilisearch 索引迁移
KarakeepHoarder部署故障排查完全指南数据库初始化、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/hoarder本文是 Karakeep前身 Hoarder自托管部署场景下的故障排查实战指南覆盖 Docker Compose 部署中最常遇到的六类问题SQLite 数据库未初始化SqliteError: no such table: user、Chrome 容器告警日志、OpenAI / Ollama 两种推理后端的 AI 自动打标失效、爬虫无法工作以及升级 Meilisearch 后的索引版本不兼容迁移。读完本文你将掌握如何通过容器日志与环境变量逐一定位根因并能在不影响已有书签数据的前提下完成索引重建与版本迁移。排查前置先看日志与数据目录Karakeep 的部署采用多容器架构核心服务在 docker/docker-compose.yml 中定义web主应用 API、chrome无头浏览器负责页面抓取、meilisearch书签全文搜索。绝大多数故障都会以日志形式输出因此排查的第一步永远是docker compose logs -f web # 主服务日志 docker compose logs -f chrome # 爬虫容器日志 docker compose logs -f meilisearch同时在源码层面Karakeep 的所有环境变量统一由 packages/shared/config.ts 中的 Zod schema 解析校验。这意味着环境变量名拼写错误、取值非法例如OLLAMA_BASE_URL不是合法 URL都会导致配置解析异常或功能静默关闭。排查时可以对照该文件确认变量名与默认值例如OPENAI_API_KEYconfig.tsOpenAI 推理密钥可选OLLAMA_BASE_URLconfig.tsOllama 服务地址要求必须是合法 URLINFERENCE_TEXT_MODELconfig.ts推理文本模型名默认值随版本而定DATA_DIRconfig.ts数据目录默认空字符串Compose 部署下固定为/dataBROWSER_WEB_URLconfig.tsChrome 容器地址可选。SqliteError: no such table: user数据库未初始化该错误表示 SQLite 数据库不存在或为空——具体而言是服务在启动时没有找到已初始化的数据库文件即user表尚未被创建。Karakeep 的主数据库是 SQLite其文件路径由DATA_DIR决定packages/db/drizzle.config.ts 中明确写为serverConfig.dataDir ? \${serverConfig.dataDir}/db.db : ./db.db即数据库文件为DATA_DIR/db.db。原因一DATA_DIR被清空或底层存储目录变更默认 Compose 部署中docker/docker-compose.yml 将名为data的 Docker volume 挂载到容器内/data同时DATA_DIR/datadocker-compose.yml 中明确注释“DONT CHANGE THIS”。如果你的DATA_DIR指向的目录被误清空、volume 被删除重建或底层存储目录被更换数据库文件就随之消失。处理方式若是有意清空例如希望重置环境直接重启容器让服务重新执行数据库迁移db:migrate以初始化全部表结构。但若数据原本有备份切勿直接重启覆盖应先恢复备份文件再启动。原因二未配置DATA_DIR自定义部署场景如果你没有使用仓库自带的默认 Compose 文件而是自建部署最容易犯的错误是忘记设置DATA_DIR环境变量。此时服务端与爬虫/搜索等子进程各自计算出的数据库位置不一致——一个进程在目录 A 写入数据另一个进程却去目录 B 读取自然找不到表。处理方式在所有服务进程web、worker 等上保持DATA_DIR一致例如统一设为/data并保证该目录挂载了持久化卷。修改后需重启全部相关容器使配置生效。这一点同样适用于ASSETS_DIR未设置时会默认取path.join(DATA_DIR, assets)见 packages/shared/config.ts可见数据目录的一致性直接关系到资产文件是否可读。Chrome Failed to Read DnsConfig良性错误可安全忽略在chrome容器的日志中如果看到类似Failed to Read DnsConfig的报错可以放心忽略。这是无头 Chromium 在容器化环境尤其是缺少 systemd-resolved 或完整 DNS 配置的容器中的常见噪音日志属于浏览器内部的 DNS 配置探测失败并不影响实际抓取功能。判断依据很简单如果爬虫功能链接抓取、截图、PDF 存储工作正常那么这条日志与你的任何问题都无关不要围绕它浪费时间排查。若确实存在抓取异常请转向下一节的BROWSER_WEB_URL检查。AI 自动打标不工作OpenAI 后端启用 AI 打标INFERENCE_ENABLE_AUTO_TAGGING默认开启见 config.ts后如果书签始终没有生成标签先查看web容器日志日志通常会直接指出问题。常见原因如下OPENAI_API_KEY变量名拼写错误变量名拼错会导致配置解析不到密钥日志中会出现类似 “No inference client configured, nothing to do now” 的信息。这一现象有明确的源码依据推理 worker 在 apps/workers/workers/inference/inferenceWorker.ts 中先通过InferenceClientFactory.build()构建客户端若返回空则直接打印该日志并跳过任务而工厂的构建逻辑packages/shared/inference.ts只认OPENAI_API_KEY或OLLAMA_BASE_URL是否已配置。因此请核对.env文件中变量名拼写与 config.ts 完全一致。配置后忘了重启容器环境变量在进程启动时读取修改.env后必须执行docker compose up -d或docker compose restart web让变更生效。Karakeep 的 Compose 文件通过env_file: .env注入配置docker-compose.yml不重启就不会重新加载。OpenAI 账户余额不足OpenAI 要求账户预充值后才能调用 API。余额不足时 API 会返回insufficient funds之类的错误日志中会体现为推理任务失败。此时需要到 OpenAI 平台为账户充值后再重试。进阶OpenAI 相关可调参数除了OPENAI_API_KEYconfig.ts 还支持以下可选参数用于对接代理或定制请求行为OPENAI_BASE_URL自定义 API 端点兼容 OpenAI 协议的网关OPENAI_PROXY_URL出站代理地址OPENAI_TIMEOUT_SEC请求超时秒数OPENAI_SERVICE_TIER取值auto/default/flex控制服务层级OPENAI_REASONING_EFFORT取值none/minimal/low/medium/high/xhigh控制推理强度。这些参数最终会通过 packages/shared/inference.ts 中的OpenAIInferenceClient.fromConfig()组装进 OpenAI 客户端并透传到chat.completions.create请求中inference.ts。AI 自动打标不工作Ollama 后端使用本地 Ollama 时排查思路类似先看容器日志。常见原因OLLAMA_BASE_URL变量名拼写错误拼错后工厂检测不到配置日志同样会出现 “No inference client configured, nothing to do now”。同时注意该变量要求是合法 URLz.string().url()见 config.ts格式非法也会导致解析失败。配置后忘了重启容器同样需要docker compose up -d使.env变更生效。未修改INFERENCE_TEXT_MODEL导致仍在使用 GPT 模型名请求 Ollama这是最容易踩的坑。INFERENCE_TEXT_MODEL的默认值是 OpenAI 系模型名config.ts而 Ollama 客户端fromConfig()中textModel直接取自该变量packages/shared/inference.ts并以该名字调用ollama.generateinference.ts。如果 Ollama 本地没有拉取同名模型请求必然失败。必须将其改为 Ollama 中实际存在的模型名例如llama3、qwen2.5等并确认ollama pull 模型名已完成。Ollama 服务与 Karakeep 容器网络不通常见两种子情况不在同一 Docker 网络Karakeep 容器无法解析/访问 Ollama 容器。可让两者加入同一个docker network或用 Compose 的external_links/ 自定义网络编排。OLLAMA_BASE_URL误用localhost在容器内部localhost指向的是容器自身而非 Docker 宿主机。应改用宿主机在 Docker 网络中的地址Linux 下通常为http://host.docker.internal:11434需 Docker 20.10 支持或宿主机局域网 IPWindows/macOS 的 Docker Desktop 下可用host.docker.internal。总之要让该 URL 能从 Karakeep 容器内实际访问到 Ollama 的 11434 端口。爬虫不工作Crawling not working书签抓取依赖chrome无头浏览器容器Karakeep 通过BROWSER_WEB_URL与之通信。默认 Compose 文件中该值为http://chrome:9222docker-compose.yml这里的chrome是服务名在 Docker 网络内可解析。最常见的原因你修改了 chrome 容器的名称例如在自定义 Compose 中命名为headless-browser却没有同步修改BROWSER_WEB_URL。此时 web 容器仍按旧名chrome解析无法连接浏览器爬虫任务全部失败。处理方式将BROWSER_WEB_URL改为实际容器名对应的地址例如http://headless-browser:9222然后重启容器。开发环境的 Composedocker/docker-compose.dev.yml也采用同样的BROWSER_WEB_URL环境变量约定便于本地调试时覆盖。若使用远程浏览器服务可配合BROWSER_WEBSOCKET_URLWebSocket 方式连接见 config.ts接入。升级 Meilisearch数据库版本迁移与索引重建Meilisearch 是 Karakeep 用于书签全文搜索的引擎Compose 中独立容器见 docker-compose.yml其数据 volume 挂载于/meili_data。Meilisearch 对数据格式有版本兼容约束随意升级引擎版本可能触发类似下面的错误Your database version (1.11.1) is incompatible with your current engine version (1.13.3).出现该错误说明旧的data.ms数据目录格式与新版引擎不兼容。Karakeep 为此提供了低成本的工作区恢复方案无需手工迁移数据文件停止 Meilisearch 容器例如docker compose stop meilisearch清除索引数据进入挂载到/meili_data的 volume 内部将名为data.ms的目录重命名或删除建议先改名备份如data.ms.bak确认无误后再清理重新启动 Meilisearch 容器此时引擎会用空索引启动全量重建索引以管理员身份登录 Karakeep Web 界面进入Admin Settings Background Jobs对应源码组件 apps/web/components/admin/BackgroundJobs.tsxi18n 文案 “Reindex All Bookmarks” 见 apps/web/lib/i18n/locales/en/translation.json点击Reindex All Bookmarks。该按钮在服务端的实现位于 packages/trpc/routers/admin.tsreindexAllBookmarks会先清空搜索索引searchIdx?.clearIndex()再取出全量书签 ID 逐条投递到低优先级重索引队列triggerSearchReindex(b.id, { priority: QueuePriority.Low })。因此点击后无需盯着页面任务会在后台批量完成。等待重索引完成后搜索功能即恢复正常——书签本体数据SQLite 与资产文件不受影响丢失的只是搜索引擎的索引副本。版本建议官方对 Meilisearch 的态度是“没有充分理由不建议升级”因为每次升级都可能引入数据格式变更与重新索引的额外操作成本。具体引擎版本随 Karakeep 发行版本演进v0.28.0 文档时代对应的引擎版本为 1.13.3而当前仓库的 docker/docker-compose.yml 中固定为getmeili/meilisearch:v1.41.0。升级前请以你所部署版本对应的 Compose 文件为准保持引擎版本与官方锁定版本一致即可避免绝大多数兼容性问题。若重索引过程中遇到异常可在Background Jobs页面观察任务状态并结合meilisearch容器日志定位确认迁移无误后再删除data.ms.bak备份目录。小结一张排查速查表症状首选检查项关键证据位置no such table: userDATA_DIR是否被清空 / 是否一致配置packages/db/drizzle.config.ts、docker-compose.ymlChrome 容器 DNS 报错无需处理良性日志—AI 打标失效OpenAIOPENAI_API_KEY拼写、重启容器、账户余额packages/shared/inference.ts、inferenceWorker.tsAI 打标失效OllamaOLLAMA_BASE_URL拼写、INFERENCE_TEXT_MODEL改为本地模型、容器网络互通packages/shared/inference.ts爬虫不工作BROWSER_WEB_URL是否匹配 chrome 容器名docker-compose.ymlMeilisearch 版本不兼容清空data.ms并触发 Reindex All Bookmarkspackages/trpc/routers/admin.ts、BackgroundJobs.tsx总体而言Karakeep 的故障面高度集中在“环境变量配置一致性与容器网络互通”两点上只要.env变量名与 packages/shared/config.ts 定义严格一致、修改后记得docker compose up -d重启、容器间地址解析正确绝大多数问题都能在几分钟内定位并恢复。【免费下载链接】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），仅供参考
