Karakeep 自托管故障排查完全指南SqliteError、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本文以 KarakeepHoarder 的后续迭代项目官方 Troubleshooting 文档为主线系统性梳理自托管部署中最常见的五类故障——SQLite 数据库未初始化、Chrome 容器日志告警、OpenAI/Ollama AI 打标不工作、爬虫抓取失效、Meilisearch 版本升级引发的索引不兼容——并给出可复现的排查步骤与修复命令。读完本文你将能够独立定位自托管实例的日志线索正确配置DATA_DIR、BROWSER_WEB_URL、推理服务相关环境变量并安全地完成 Meilisearch 数据目录重建与全量重建索引。原始故障排查文档位于 docs/versioned_docs/version-v0.30.0/06-administration/05-troubleshooting.md当前分支版本见 docs/docs/06-administration/05-troubleshooting.md文中涉及的配置项均可对照 docs/docs/03-configuration/01-environment-variables.md 查阅。一、排查总原则一切先从容器日志入手Karakeep 由多个容器协同工作web、chrome、meilisearch见 docker/docker-compose.yml绝大多数故障都会在对应容器日志中留下明确线索。官方文档反复强调一句话Check the logs of the container and this will usually tell you whats wrong。查看所有服务日志docker compose logs -f只看某个服务docker compose logs -f web、docker compose logs -f chrome、docker compose logs -f meilisearch日志级别由LOG_LEVEL控制默认debug源码见 packages/shared/config.ts生产环境建议调高为notice或warning以降低日志噪音。下面每个故障小节都会先给出日志里应该找什么再给出修复动作。二、SqliteError: no such table: user数据库未初始化2.1 错误含义SqliteError: no such table: user这个错误几乎总是意味着数据库没有正确初始化——SQLite 文件虽然存在或路径错误但其中还没有 Karakeep 所需的表结构。它通常由两类配置问题引发2.2 原因一DATA_DIR被清空或存储目录被更换DATA_DIR是 Karakeep 的持久化数据目录SQLite 数据库就存放在这里。如果该目录被清空或挂载的存储卷发生了更换数据库自然不存在。修复如果是有意清空例如全新部署直接重启容器即可Karakeep 会自动重新初始化数据库。初始化逻辑在 packages/db/migrate.ts 中启动时通过 drizzle 的 migrator 将./drizzle目录下的迁移 SQL 全部应用到数据库迁移文件见 packages/db/drizzle随后建表完成。2.3 原因二未配置DATA_DIR自定义 compose 文件场景如果你没有使用仓库自带的 docker/docker-compose.yml而是自己编写了 compose 文件很容易忘记配置DATA_DIR环境变量。此时数据库会被初始化到与 web 服务实际使用的目录不一致的位置导致服务读不到表。官方 compose 中的关键注释值得注意见 docker/docker-compose.yml# You almost never want to change the value of the DATA_DIR variable. # If you want to mount a custom directory, change the volume mapping above instead. DATA_DIR: /data # DONT CHANGE THIS修复要点不要修改 compose 里的DATA_DIR值它固定指向容器内的/data要换存储位置请修改 volume 映射例如把- data:/data换成- /path/to/your/directory:/data自定义 compose 时务必显式传入DATA_DIR并且与卷映射保持一致。DATA_DIR同时决定了资源的默认存放位置当ASSETS_DIR未设置时资源默认存在${DATA_DIR}/assets下见 packages/shared/config.ts 的assetsDir计算逻辑。2.4 源码侧补充数据库打开与初始化细节数据库连接由 packages/db/sqlite.ts 的openSqliteDatabase建立会设置foreign_keys ON、temp_store MEMORY等 pragma若开启DB_WAL_MODEtrue则启用journal_mode WAL并配合synchronous NORMAL提升并发性能默认false时使用journal_mode DELETE见 packages/shared/config.ts。文档建议除非数据库跑在网络挂载盘上否则没有理由不开启 WALdegradedMode下会跳过迁移见 packages/db/migrate.ts排查时注意不要误开该模式。三、Chrome Failed to Read DnsConfig良性告警可忽略如果你在chrome 容器的日志中看到类似下面的报错Chrome Failed to Read DnsConfig这是无害的良性错误可以放心忽略。官方文档明确说明Whatever problems youre having, is unrelated to this error.——即你遇到的其他任何问题都与它无关不要被这条日志误导去排查 DNS 配置。该错误来源于 Karakeep 使用的独立 Chrome 容器镜像ghcr.io/karakeep-app/karakeep-chrome见 docker/docker-compose.yml在启动时尝试读取宿主机 DNS 配置失败但不影响其作为无头浏览器提供页面抓取能力。四、AI 打标不工作OpenAI 场景Karakeep 的自动打标依赖推理配置其判定逻辑在 packages/shared/config.tsinference: { isConfigured: !!val.OPENAI_API_KEY || !!val.OLLAMA_BASE_URL, ... }只要OPENAI_API_KEY与OLLAMA_BASE_URL都未设置推理就会被判定为未配置日志中会出现类似 skipping inference as its not configured 的提示。常见原因按出现频率排列环境变量名拼写错误把OPENAI_API_KEY写错例如OPENAI_KEY、OPENAI_APIKEY。由于配置项通过 zod schema 解析见 packages/shared/config.ts拼写错误的变量会被静默忽略最终表现为推理未配置日志。配置后忘记重启修改.env后没有执行docker compose up或docker compose restart web新环境变量未生效。OpenAI 账户余额不足OpenAI 要求先充值才能调用 API否则会得到类似 insufficient funds 的错误。修复检查.env中变量名是否与官方一致完整列表见 docs/docs/03-configuration/01-environment-variables.md重新加载配置docker compose up -d登录 OpenAI 平台确认账户有可用额度之后到用户设置 → AI 设置中检查自动打标开关INFERENCE_ENABLE_AUTO_TAGGING默认true见 packages/shared/config.ts。进阶调优参数详见环境变量文档INFERENCE_TEXT_MODEL文本打标模型默认gpt-5.6-lunav0.30.0 版本快照中为gpt-4.1-miniINFERENCE_IMAGE_MODEL图片打标模型默认gpt-4o-miniINFERENCE_CONTEXT_LENGTH传给模型的 token 上限默认 2048。文档特别提醒默认值偏小调大可提升打标质量但会同时增加 OpenAI 费用与 Ollama 资源开销INFERENCE_JOB_TIMEOUT_SEC推理任务超时默认 30 秒OPENAI_BASE_URL使用 Azure OpenAI 等兼容接口时指定OPENAI_PROXY_URLOpenAI 请求走 HTTP 代理时指定。五、AI 打标不工作Ollama 本地推理场景Ollama 场景的排查思路与 OpenAI 类似但多了几个本地部署特有的坑环境变量名拼写错误OLLAMA_BASE_URL写错同样会导致 skipping inference as its not configured。忘记重新docker compose up配置后未重启容器。未修改INFERENCE_TEXT_MODEL这是最容易忽略的一点。默认推理模型是 GPT 系列gpt-5.6-luna/gpt-4.1-miniOllama 无法加载这些模型。必须显式改为 Ollama 已拉取的模型名例如INFERENCE_TEXT_MODELllama3.1 INFERENCE_IMAGE_MODELllava # 图片打标需支持视觉 API 的模型 OLLAMA_BASE_URLhttp://host.docker.internal:11434Ollama 服务不可达通常是以下子原因网络隔离Ollama 与 Karakeep 容器不在同一个 Docker 网络。把两者加入同一自定义网络或在 compose 中为 web 服务显式加入 Ollama 所在网络误用localhost容器内的localhost指向容器自身而非宿主机。要访问宿主机上的 Ollama应使用http://host.docker.internal:11434Linux 下需在 compose 中为容器添加extra_hosts: - host.docker.internal:host-gateway或直接使用宿主机的局域网 IP。其他可调参数OLLAMA_KEEP_ALIVE控制模型在推理请求后驻留内存的时间如5m驻留 5 分钟、-1m长期驻留、0立即卸载INFERENCE_FETCH_TIMEOUT_SEC请求 Ollama 的抓取超时默认 300 秒慢速无 GPU 机器可调大INFERENCE_OUTPUT_SCHEMA默认structured若模型不支持结构化输出可降级为json或plain见 packages/shared/config.ts。调试技巧先在宿主机执行curl http://localhost:11434/api/tags确认 Ollama 正常再进入 web 容器执行docker compose exec web sh后用wget/curl测试容器到 Ollama 的连通性即可定位是网络问题还是变量问题。六、爬虫不工作Crawling not workingKarakeep 的爬虫通过 Chrome 容器的调试端口执行 JavaScript 与截图。官方文档指出的最常见原因只有一个你改了 Chrome 容器的名称却没有同步修改BROWSER_WEB_URL环境变量。官方 compose 中的对应配置见 docker/docker-compose.ymlenvironment: BROWSER_WEB_URL: http://chrome:9222 # chrome 即 chrome 服务的名称BROWSER_WEB_URL是 Chrome 调试端口的 HTTP 地址爬虫 worker 通过它解析出调试协议的 WebSocket 地址。如果你把chrome服务改名为browser、headless-chrome等必须同步把BROWSER_WEB_URL改为http://新名称:9222否则爬虫连不上浏览器。相关参数补充BROWSER_WEBSOCKET_URL若你已直接拿到调试 WebSocket 地址例如使用 browserless 等按需浏览器服务可直接指定它此时优先于BROWSER_WEB_URLBROWSER_CONNECT_ONDEMAND默认false常驻连接使用按需提供浏览器实例的服务时设为true若BROWSER_WEB_URL与BROWSER_WEBSOCKET_URL都未设置爬虫会退化为纯 HTTP 请求跳过截图与 JavaScript 执行见 docs/docs/03-configuration/01-environment-variables.md 的 Crawler Configs 一节CRAWLER_NUM_WORKERS并发抓取数默认 1避免资源占用过高。验证步骤确认 chrome 容器健康docker compose ps确认 web 容器内能访问http://chrome:9222docker compose exec web wget -qO- http://chrome:9222/json/version对比BROWSER_WEB_URL中的服务名与 compose 中 chrome 服务的实际名称是否一致。七、升级 Meilisearch迁移搜索引擎数据库版本7.1 背景与典型报错Meilisearch 是 Karakeep 的书签全文搜索引擎。不同版本的 Meilisearch 数据目录data.ms互不兼容升级后可能出现Your database version (x.x.x) is incompatible with your current engine version (y.y.y). To migrate data between Meilisearch versions, please follow our guide on ...官方文档明确建议不要在没有充分理由的情况下升级 Meilisearch。仓库当前在 docker/docker-compose.yml 中固定镜像版本为getmeili/meilisearch:v1.41.0值得注意的是v0.30.0 版本快照文档中记录的是1.13.3可见版本随迭代不断更新——因此以你实际部署的 compose 文件锁定的版本为准不要盲目跟随镜像 tag 漂移。7.2 官方推荐的变通修复步骤Meilisearch 官方不提供数据库自动迁移Karakeep 给出的变通方案是清空索引数据并全量重建停止 Meilisearch 容器docker compose stop meilisearch清空数据目录在挂载到/meili_data的卷中删除或重命名data.ms文件夹。例如# 先找到卷的实际路径 docker volume inspect project_meilisearch # 然后重命名保留备份而非直接删除 mv volume_path/data.ms volume_path/data.ms.bak注意官方原文是 erase/rename——重命名比删除更稳妥万一需要回滚还能恢复。重新启动 Meilisearchdocker compose up -d meilisearch全量重建索引以管理员身份登录 Karakeep Web 界面进入Admin Settings Background Jobs点击Reindex All Bookmarks。等待重建任务完成后搜索功能即恢复正常。7.3 源码侧验证重建索引的完整调用链Reindex All Bookmarks 按钮在后台实际调用的是管理员 APIreindexAllBookmarks其完整调用链可从源码确认tRPC 路由packages/trpc/routers/admin.ts 定义了reindexAllBookmarks管理员过程Web 管理界面apps/web/components/admin/BackgroundJobs.tsx 中通过api.admin.reindexAllBookmarks.mutationOptions(...)触发该操作CLI 备用入口若 Web 界面不方便操作也可通过官方 CLI 触发apps/cli/src/commands/admin.ts 中的api.admin.reindexAllBookmarks.mutate(...)API 层packages/api/routes/admin.ts 也暴露了同名 HTTP 端点供外部调用对应测试见 packages/trpc/routers/admin.test.ts。也就是说重建索引的三种途径Web 后台 / CLI / HTTP API底层都指向同一逻辑任选其一即可。7.4 预防性建议升级 Meilisearch 前先备份卷docker run --rm -v project_meilisearch:/data -v $(pwd):/backup alpine tar czf /backup/meili_data_backup.tar.gz -C /data .尽量保持镜像版本与官方 compose 锁定版本一致避免:latest漂移升级后若遇到问题官方 Meilisearch 升级文档提供了更完整的迁移指南可按需查阅。八、综合预防让自托管实例少出故障把本文涉及的故障归纳成几条可落地的运维习惯预防动作对应故障不要修改 compose 中的DATA_DIR/data改卷映射来换存储位置SqliteError: no such table自定义 compose 必须显式配置DATA_DIR并与卷一致SqliteError: no such table修改.env后务必执行docker compose up -d使其生效AI 打标 / 爬虫不工作环境变量名严格对照官方文档尤其OPENAI_API_KEY、OLLAMA_BASE_URLAI 打标不工作Ollama 场景必须修改INFERENCE_TEXT_MODEL为本地模型并使用host.docker.internal而非localhostAI 打标不工作Ollama修改 chrome 容器名称时同步修改BROWSER_WEB_URL爬虫不工作锁定 Meilisearch 镜像版本升级前备份/meili_data卷搜索报版本不兼容错误备份DATA_DIRSQLite 与资源文件所在目录数据丢失 / 误清空所有环境变量的权威清单与默认值均可对照 docs/docs/03-configuration/01-environment-variables.md 及 packages/shared/config.ts 中的 zod schema 逐一核对。掌握先看日志 → 对照配置 → 按链条验证的方法论后绝大多数自托管问题都能在十分钟内定位并修复。【免费下载链接】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），仅供参考