Karakeep 自托管故障排查实战指南：数据库、AI 打标签、爬虫与 Meilisearch 迁移排错全解

Karakeep 自托管故障排查实战指南：数据库、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）v0.29 时代的官方 Troubleshooting 文档为主体，逐项拆解自托管部署中最高频的五类故障——SQLite 数据库未初始化、Chrome 容器良性报错、OpenAI/Ollama 自动打标签失效、链接爬取不工作以及 Meilisearch 升级迁移。读完本文，你将能依据日志定位根因、按步骤修复环境变量与容器网络问题，并掌握重建搜索索引的标准操作流程，快速恢复服务的完整能力。

SqliteError: no such table: user——数据库未初始化

日志中出现SqliteError: no such table: user，说明 Karakeep 的 SQLite 数据库没有正确初始化。Karakeep 使用 SQLite 作为主数据库（在 packages/db 中通过 Drizzle ORM 管理 schema），这张user表属于认证模块的核心表，它不存在通常意味着程序启动时未能执行建表/迁移流程，而不是数据损坏。

常见诱因有两种：

1. DATA_DIR 被清空或更换：DATA_DIR目录被清空，或者其底层存储目录被更换。如果是你有意为之，直接重启容器，让启动流程重新初始化数据库即可。
2. DATA_DIR 缺失：如果你没有使用默认的 docker compose 文件，并且忘记配置DATA_DIR环境变量，那么数据库会被创建在与服务实际使用目录不同的位置，导致服务读取不到表结构。

在 packages/shared/config.ts 中，DATA_DIR的默认值是空字符串，而ASSETS_DIR默认会落到${DATA_DIR}/assets；这意味着一旦漏配DATA_DIR，数据与资源文件的落盘位置都会变得不可预期。默认的 docker/docker-compose.yml 中将DATA_DIR固定为/data并注释了「DON'T CHANGE THIS」——如果你想改存储位置，官方建议的做法是修改 volume 映射（- /path/to/your/directory:/data），而不是直接改DATA_DIR的值。这样既能保证数据目录一致，也避免容器重建后路径漂移。

排障建议：docker compose logs web | grep -i sqlite查看启动时是否有迁移报错；同时确认宿主机上DATA_DIR对应的 volume 是否确实存在且非空。

Chrome Failed to Read DnsConfig——可安全忽略的良性错误

如果 chrome 容器的日志里出现Failed to Read DnsConfig，这是一个良性错误，可以放心忽略。它与你在使用中遇到的任何功能故障都无关。该报错源于 Chromium 在容器化环境下读取 DNS 配置失败时打印的警告，Karakeep 的爬虫 worker 通过 Chrome DevTools 协议驱动该浏览器实例完成页面渲染与截图，DNS 解析实际由容器网络层处理，因此该警告不影响爬取行为。

AI 自动打标签不工作（使用 OpenAI 时）

先检查 web 容器的日志，通常它会直接告诉你问题所在。最常见的三类原因：

1. 环境变量名拼写错误：OPENAI_API_KEY拼错会导致日志出现类似skipping inference as it's not configured的提示。在 packages/shared/config.ts 中，inference.isConfigured的判断逻辑是!!val.OPENAI_API_KEY || !!val.OLLAMA_BASE_URL——只要该变量未正确注入，自动打标签就会被整体跳过，而且这种跳过是静默的，不会抛出异常，很容易被误判为模型问题。
2. 配置后未重启：修改完 OpenAI 配置后忘记执行docker compose up，容器仍在用旧环境变量运行。
3. 账户未预充值：OpenAI 要求先为账户充值额度才能调用 API，否则会返回insufficient funds之类的错误。

需要留意的是，OPENAI_API_KEY与OPENAI_BASE_URL是两个独立变量：若你想使用 Azure OpenAI 或其他 OpenAI 兼容端点，需额外配置OPENAI_BASE_URL（详见 docs/docs/03-configuration/01-environment-variables.md 的 Inference Configs 一节）。同时，如果同时配置了 Ollama 与 OpenAI，config.ts 中的判断会因两者其一存在而认为推理已配置，此时更要核对实际调用的是哪条链路。

AI 自动打标签不工作（使用 Ollama 时）

同样先看容器日志，常见原因按出现频率排列：

1. OLLAMA_BASE_URL拼写错误：会得到与 OpenAI 类似的skipping inference as it's not configured日志。
2. 配置后未重启：忘记执行docker compose up。
3. 未修改INFERENCE_TEXT_MODEL：这是最容易踩的坑。当前仓库 packages/shared/config.ts 中INFERENCE_TEXT_MODEL的默认值是gpt-5.6-luna（OpenAI 系模型），如果你接的是 Ollama 却沿用默认值，Karakeep 会尝试用 GPT 模型请求 Ollama 的/api/chat接口，两者协议与模型名完全不匹配，必然失败。使用 Ollama 时务必显式设置为本机已拉取的模型，例如llama3、qwen2.5等。
4. Ollama 服务对 Karakeep 容器不可达：
   • Ollama 与 Karakeep 容器不在同一个 docker 网络；
   • 把OLLAMA_BASE_URL写成了localhost。注意：localhost指向的是容器自身，而不是 docker 宿主机。正确的做法是在宿主机上配置 Ollama 监听0.0.0.0，然后在容器内使用宿主机在 docker 网络中的地址（Linux 下通常是172.17.0.1，macOS/Windows 桌面版可用宿主机专用地址），或用host.docker.internal（需 docker 支持）。

此外 docs/docs/03-configuration/01-environment-variables.md 还提示：Ollama 场景下建议同步调大INFERENCE_FETCH_TIMEOUT_SEC（默认 300 秒）与INFERENCE_JOB_TIMEOUT_SEC（默认 30 秒），本地无 GPU 时推理耗时较长，容易先于模型响应而超时。INFERENCE_IMAGE_MODEL也需替换为支持视觉的模型（如llava），否则图片类书签的推理同样会失败。

爬取（Crawling）不工作

先看日志。最常见的原因是：你改了 chrome 容器的名字，却没有同步修改BROWSER_WEB_URL环境变量。默认的 docker/docker-compose.yml 中该值写死为http://chrome:9222，其中chrome正是 compose 服务名——一旦容器被重命名，该地址立即失效。

从源码看这个变量的重要性：在 apps/workers/workers/crawlerWorker.ts 中，爬虫 worker 会检查browserWebUrl/browserWebSocketUrl是否配置。若两者都为空，crawlPage()会静默回退为纯 HTTP 抓取（browserlessCrawlPage），这意味着不执行 JavaScript、不产生截图——页面行为看起来"能抓"但功能残缺，这正是排障时容易被忽略的点。若要彻底关闭浏览器路径，行为是可控的；但你多半是想要浏览器渲染能力，因此请确保：

• BROWSER_WEB_URL指向实际可用的 Chrome 调试端口（compose 默认http://chrome:9222）；
• 若使用 Browserless 等外部服务，可改用BROWSER_WEBSOCKET_URL直接指定 websocket 调试地址（见 docs/docs/03-configuration/01-environment-variables.md 的 Crawler Configs 一节）；
• 改完环境变量后务必docker compose up -d让 web 容器重建生效。

升级 Meilisearch：版本不兼容与索引重建

Meilisearch 是 Karakeep 的书签全文搜索后端。v0.29 文档明确指出项目锁定 Meilisearch1.13.3版本，不建议无充分理由自行升级；而当前仓库主线的 docker/docker-compose.yml 已固定镜像getmeili/meilisearch:v1.41.0——无论哪个版本线，原则一致：跟着项目锁定的版本走，别擅自升级。一旦引擎版本与数据版本不匹配，就会看到类似：

Your database version (1.11.1) is incompatible with your current engine version (1.13.3).

好在有标准且安全的工作流可以绕过：

1. 停止 Meilisearch 容器；
2. 进入挂载到/meili_data的 volume，删除或重命名其中的data.ms文件夹；
3. 重新启动 Meilisearch 容器；
4. 以管理员身份登录 Karakeep，进入Admin Settings > Background Jobs，点击Reindex All Bookmarks；
5. 等待重建索引完成，搜索功能恢复正常。

该步骤的底层逻辑可以在源码中得到印证：在 packages/trpc/routers/admin.ts 中，reindexAllBookmarks这个 admin 接口会先通过searchIdx.clearIndex()清空 Meilisearch 索引，再把所有书签按低优先级批量入队到搜索索引队列，由搜索 worker 逐个重建。因此清空data.ms只是重置引擎侧的数据，真正的索引内容靠这次全量重放生成，二者缺一不可。

操作提醒：data.ms里是 Meilisearch 的原始索引数据，删除后仅需重建搜索索引，不会影响 SQLite 中的书签、标签等主数据；但如果你的自定义搜索设置（如停用词、同义词）存放在 Meilisearch 侧，重装后需要重新配置。

小结：一套可复用的排障思路

纵览上述五类问题，Karakeep 自托管的故障大多可归结为三类根因：环境变量未正确注入或拼写错误（OpenAI/Ollama/爬虫）、容器间网络与命名不一致（Ollama 地址、chrome 服务名）、底层存储状态异常（SQLite 目录、Meilisearch 版本）。建议每次排障都从docker compose logs开始，对照 packages/shared/config.ts 中声明的全部环境变量逐一核对，再结合 docs/docs/03-configuration/01-environment-variables.md 的参数表确认默认值与取值约束——大多数"神秘故障"在这一步就会现出原形。

【免费下载链接】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