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原 Hoarderv0.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表属于认证模块的核心表它不存在通常意味着程序启动时未能执行建表/迁移流程而不是数据损坏。常见诱因有两种DATA_DIR 被清空或更换DATA_DIR目录被清空或者其底层存储目录被更换。如果是你有意为之直接重启容器让启动流程重新初始化数据库即可。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并注释了「DONT 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 容器的日志通常它会直接告诉你问题所在。最常见的三类原因环境变量名拼写错误OPENAI_API_KEY拼错会导致日志出现类似skipping inference as its not configured的提示。在 packages/shared/config.ts 中inference.isConfigured的判断逻辑是!!val.OPENAI_API_KEY || !!val.OLLAMA_BASE_URL——只要该变量未正确注入自动打标签就会被整体跳过而且这种跳过是静默的不会抛出异常很容易被误判为模型问题。配置后未重启修改完 OpenAI 配置后忘记执行docker compose up容器仍在用旧环境变量运行。账户未预充值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 与 OpenAIconfig.ts 中的判断会因两者其一存在而认为推理已配置此时更要核对实际调用的是哪条链路。AI 自动打标签不工作使用 Ollama 时同样先看容器日志常见原因按出现频率排列OLLAMA_BASE_URL拼写错误会得到与 OpenAI 类似的skipping inference as its not configured日志。配置后未重启忘记执行docker compose up。未修改INFERENCE_TEXT_MODEL这是最容易踩的坑。当前仓库 packages/shared/config.ts 中INFERENCE_TEXT_MODEL的默认值是gpt-5.6-lunaOpenAI 系模型如果你接的是 Ollama 却沿用默认值Karakeep 会尝试用 GPT 模型请求 Ollama 的/api/chat接口两者协议与模型名完全不匹配必然失败。使用 Ollama 时务必显式设置为本机已拉取的模型例如llama3、qwen2.5等。Ollama 服务对 Karakeep 容器不可达Ollama 与 Karakeep 容器不在同一个 docker 网络把OLLAMA_BASE_URL写成了localhost。注意localhost指向的是容器自身而不是 docker 宿主机。正确的做法是在宿主机上配置 Ollama 监听0.0.0.0然后在容器内使用宿主机在 docker 网络中的地址Linux 下通常是172.17.0.1macOS/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).好在有标准且安全的工作流可以绕过停止 Meilisearch 容器进入挂载到/meili_data的 volume删除或重命名其中的data.ms文件夹重新启动 Meilisearch 容器以管理员身份登录 Karakeep进入Admin Settings Background Jobs点击Reindex All Bookmarks等待重建索引完成搜索功能恢复正常。该步骤的底层逻辑可以在源码中得到印证在 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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原 Hoarderv0.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表属于认证模块的核心表它不存在通常意味着程序启动时未能执行建表/迁移流程而不是数据损坏。常见诱因有两种DATA_DIR 被清空或更换DATA_DIR目录被清空或者其底层存储目录被更换。如果是你有意为之直接重启容器让启动流程重新初始化数据库即可。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并注释了「DONT 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 容器的日志通常它会直接告诉你问题所在。最常见的三类原因环境变量名拼写错误OPENAI_API_KEY拼错会导致日志出现类似skipping inference as its not configured的提示。在 packages/shared/config.ts 中inference.isConfigured的判断逻辑是!!val.OPENAI_API_KEY || !!val.OLLAMA_BASE_URL——只要该变量未正确注入自动打标签就会被整体跳过而且这种跳过是静默的不会抛出异常很容易被误判为模型问题。配置后未重启修改完 OpenAI 配置后忘记执行docker compose up容器仍在用旧环境变量运行。账户未预充值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 与 OpenAIconfig.ts 中的判断会因两者其一存在而认为推理已配置此时更要核对实际调用的是哪条链路。AI 自动打标签不工作使用 Ollama 时同样先看容器日志常见原因按出现频率排列OLLAMA_BASE_URL拼写错误会得到与 OpenAI 类似的skipping inference as its not configured日志。配置后未重启忘记执行docker compose up。未修改INFERENCE_TEXT_MODEL这是最容易踩的坑。当前仓库 packages/shared/config.ts 中INFERENCE_TEXT_MODEL的默认值是gpt-5.6-lunaOpenAI 系模型如果你接的是 Ollama 却沿用默认值Karakeep 会尝试用 GPT 模型请求 Ollama 的/api/chat接口两者协议与模型名完全不匹配必然失败。使用 Ollama 时务必显式设置为本机已拉取的模型例如llama3、qwen2.5等。Ollama 服务对 Karakeep 容器不可达Ollama 与 Karakeep 容器不在同一个 docker 网络把OLLAMA_BASE_URL写成了localhost。注意localhost指向的是容器自身而不是 docker 宿主机。正确的做法是在宿主机上配置 Ollama 监听0.0.0.0然后在容器内使用宿主机在 docker 网络中的地址Linux 下通常是172.17.0.1macOS/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).好在有标准且安全的工作流可以绕过停止 Meilisearch 容器进入挂载到/meili_data的 volume删除或重命名其中的data.ms文件夹重新启动 Meilisearch 容器以管理员身份登录 Karakeep进入Admin Settings Background Jobs点击Reindex All Bookmarks等待重建索引完成搜索功能恢复正常。该步骤的底层逻辑可以在源码中得到印证在 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考