Karakeep 常见故障排查指南从数据库初始化到 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自托管书签应用v0.31.0 版本官方 Troubleshooting 文档为骨架系统梳理了自托管部署中最常遇到的五类问题——SQLite 数据库初始化失败、Chrome 容器日志噪音、AI 自动打标失效OpenAI / Ollama 两种场景、网页爬取不工作以及 Meilisearch 版本升级后的数据迁移。结合仓库源码与 Docker Compose 配置本文将为每类问题给出可落地的排查路径、修复步骤与源码级原理解析帮助读者在几分钟内定位并解决问题。排查前的通用方法论无论遇到哪一类问题Karakeep 官方文档给出的第一条建议始终是先查看容器日志。大多数故障都会在日志中留下明确线索例如推理服务未配置时的skipping inference as its not configured、数据库缺失时的SqliteError: no such table等。使用以下命令可以快速捕获相关容器的输出# 查看全部容器日志 docker compose logs -f # 只看某个容器的日志例如 web、chrome、meilisearch docker compose logs -f web docker compose logs -f chrome docker compose logs -f meilisearch同时Karakeep 的全部运行时行为都由环境变量驱动这些变量在 packages/shared/config.ts 中以 zod schema 集中定义和校验。排查问题前建议先核对.env文件中的变量名拼写是否与源码定义完全一致这是大量配置不生效类问题的根源。SqliteError: no such table: user报错含义与本质当日志中出现SqliteError: no such table: user时通常意味着数据库没有被正确初始化。Karakeep 使用 SQLite 作为主数据库见 packages/db所有用户、书签、标签等核心数据都存储在由DATA_DIR指定的数据目录中。该错误并非某张表损坏而是整库缺失或指向了错误的目录。常见诱因与修复步骤诱因一DATA_DIR 被清空或存储目录被更换DATA_DIR目录被清空或被有意更换了备份存储位置后数据库文件随之丢失。如果这是你有意为之只需重启容器让应用重新执行数据库初始化流程docker compose restart web重启后 Karakeep 会重建 SQLite 数据库结构并完成 schema 迁移迁移脚本位于 packages/db/migrate.ts历史迁移记录见 packages/db/drizzle。注意重新初始化意味着旧数据不再存在请务必在清空目录前做好备份。诱因二未使用默认 docker-compose 文件且遗漏了 DATA_DIR 变量如果你使用自定义 Compose 文件部署却忘记配置DATA_DIR环境变量会导致数据库被创建在服务实际使用的目录之外服务自然读不到表。在默认的 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也就是说官方建议的做法是保持DATA_DIR: /data不变通过修改 volume 映射来更换数据目录例如volumes: - /path/to/your/directory:/data从源码看DATA_DIR的默认值为空字符串packages/shared/config.ts而资源目录ASSETS_DIR在未配置时会被解析为DATA_DIR下的assets子目录packages/shared/config.ts可见DATA_DIR是整个数据体系的地基一旦错位不止数据库附件等资源同样会找不到。开发模式下的 Compose 文件docker/docker-compose.dev.yml也遵循同一约定支持通过${DATA_DIR:-/data}覆盖。排查命令速查# 确认 web 容器的实际 DATA_DIR 与挂载情况 docker compose exec web env | grep DATA_DIR docker inspect karakeep-web-1 --format {{json .Mounts}}Chrome Failed to Read DnsConfig如果 chrome 容器的日志中出现Failed to Read DnsConfig这是一个良性benign错误可以直接忽略。它并不代表 Karakeep 的爬虫或任何功能出了故障——如果你此时恰好遇到了其他问题两者之间没有因果关系请继续按其他章节排查。从源码角度看爬虫容器本质上是一个运行 Chrome 的独立服务docker/docker-compose.yml 中的chrome服务负责渲染网页、执行 JS、截图与整页归档等任务。这类容器在启动阶段读取宿主 DNS 配置时偶尔会抛出该警告但随后会回退到默认解析方式不影响功能无需任何处理。AI 自动打标不工作OpenAI 场景Karakeep 的 AI 自动打标由inference推理链路驱动相关的推理服务配置集中定义在 packages/shared/config.ts。使用 OpenAI 时按以下顺序排查1. 检查环境变量拼写确认变量名是否为OPENAI_API_KEY注意下划线位置不要写成OPENAI-API-KEY之类。拼写错误时日志中会出现类似skipping inference as its not configured的提示——这是因为推理功能是否启用直接由该变量是否存在决定。从源码看推理服务的isConfigured判定为isConfigured: !!val.OPENAI_API_KEY || !!val.OLLAMA_BASE_URL见 packages/shared/config.ts——只要OPENAI_API_KEY为空推理服务就被整体视为未配置自动打标自然静默跳过。如果只是临时验证配置是否生效也可以直接使用官方在 Compose 文件中预留的注释占位environment: # OPENAI_API_KEY: ...docker/docker-compose.yml2. 修改配置后必须重新拉起容器.env文件或 Compose 中的环境变量修改后仅docker restart不会重新读取环境变量必须执行docker compose up -d让 Compose 根据最新的.env重建容器。这也是明明配了 key 却还是不生效最常见的操作失误。3. OpenAI 账户需要预充值OpenAI 的 API 采用预付费模式账户余额不足时推理请求会直接失败日志中通常会出现insufficient funds之类的错误。请到 OpenAI 控制台确认账户有可用余额credits并留意服务 tier 与限额设置。可选的进阶调优变量除上述排障项外源码中还存在一组可选的 OpenAI 行为调优变量遇到超时或输出异常时可酌情设置packages/shared/config.ts变量说明OPENAI_BASE_URL自定义 OpenAI 兼容 API 地址OPENAI_TIMEOUT_SEC请求超时时间秒OPENAI_SERVICE_TIER取值auto/default/flexOPENAI_REASONING_EFFORT推理强度取值none/minimal/low/medium/high/xhighINFERENCE_TEXT_MODEL默认gpt-5.6-luna指定文本打标使用的模型INFERENCE_IMAGE_MODEL默认gpt-4o-mini指定图片打标使用的模型AI 自动打标不工作Ollama 场景使用 Ollama 本地推理时排障思路与 OpenAI 类似但多了几个本地化特有的坑1. 检查环境变量拼写确认变量名为OLLAMA_BASE_URL源码中定义于 packages/shared/config.ts。同样地拼写错误会导致日志出现skipping inference as its not configured。修改后同样需要docker compose up -d重新创建容器。2. 必须更换 INFERENCE_TEXT_MODEL这是 Ollama 场景最典型的坑Ollama 上并没有 GPT 系列模型如果你沿用默认的INFERENCE_TEXT_MODEL默认值为gpt-5.6-luna见 packages/shared/config.tsKarakeep 会拿 GPT 模型名去请求 Ollama必然失败。请将其改为你本地已拉取的模型例如environment: OLLAMA_BASE_URL: http://host.docker.internal:11434 INFERENCE_TEXT_MODEL: llama3.13. 检查容器间的网络可达性Ollama 服务器需要能被 Karakeep 容器访问到常见两类问题网络隔离Ollama 与 Karakeep 不在同一个 Docker 网络互相不可达。请确认两者使用同一 network或在 Compose 中显式声明网络。localhost 指向错误在容器内localhost指向容器自身而不是 Docker 宿主机。若你在宿主机上运行 OllamaOLLAMA_BASE_URL不能写http://localhost:11434应使用宿主机在 Docker 网络中的地址Linux 下通常可用host.docker.internal或通过docker network inspect查到宿主机网桥 IP例如http://172.17.0.1:11434。验证可达性docker compose exec web curl -s http://OLLAMA_HOST:11434/api/tags其他推理相关变量源码中还提供了一组与推理行为相关的开关packages/shared/config.ts排障时可关注变量默认值说明INFERENCE_ENABLE_AUTO_TAGGINGtrue是否启用自动打标INFERENCE_ENABLE_AUTO_SUMMARIZATIONfalse是否启用自动摘要INFERENCE_JOB_TIMEOUT_SEC30推理任务超时秒INFERENCE_FETCH_TIMEOUT_SEC300推理请求抓取超时秒INFERENCE_OUTPUT_SCHEMAstructured输出格式structured/json/plain网页爬取Crawling不工作Karakeep 的网页爬取由crawlerWorker驱动源码见 apps/workers/workers/crawlerWorker.ts它通过 WebSocket 连接 Chrome 容器执行渲染、截图与归档。排查要点核心排查项BROWSER_WEB_URL 是否与容器名匹配最常见的错误是你改了 chrome 容器的名字却没有同步修改BROWSER_WEB_URL环境变量。默认 Compose 中web 服务通过以下配置连接 Chromedocker/docker-compose.ymlBROWSER_WEB_URL: http://chrome:9222chrome是 Compose 服务名Docker 内部 DNS 会将其解析为 chrome 容器的地址。如果你把 chrome 服务改名为my-chrome就必须同步把BROWSER_WEB_URL改为http://my-chrome:9222否则 web 容器找不到爬虫浏览器爬取任务会失败。从源码看BROWSER_WEB_URL对应crawler.browserWebUrl配置packages/shared/config.ts同时还有一个可选的BROWSER_WEBSOCKET_URL用于直接指定 WebSocket 地址。在 adhoc 爬取 CLIapps/workers/scripts/crawlAdhoc.ts中可以看到其典型用法例如指向本机调试实例BROWSER_WEB_URLhttp://127.0.0.1:9222源码中的自我保护逻辑值得注意的是apps/workers/workers/crawlerWorker.ts 中有一个值得了解的细节当BROWSER_WEB_URL与BROWSER_WEBSOCKET_URL均未配置时crawlPage()会静默回退为纯 HTTP 抓取不执行 JS、不截图。adhoc CLI 为了避免这种悄悄降级污染测试结果会在无浏览器后端时直接抛错拒绝运行[adhoc] No browser backend configured — refusing to run. crawlPage() would silently fall back to a plain HTTP fetch. Set BROWSER_WEB_URL or BROWSER_WEBSOCKET_URL to a reachable Chrome.这提醒我们如果爬取结果缺少 JS 渲染内容或截图先确认浏览器连接确实建立成功而不是只看到抓到了 HTML就认为功能正常。相关调优变量爬取链路的超时与资源控制变量packages/shared/config.ts中排障时常关注变量默认值说明CRAWLER_HEADLESS_BROWSERtrue是否使用无头浏览器BROWSER_CONNECT_ONDEMANDfalse是否按需建立浏览器连接CRAWLER_JOB_TIMEOUT_SEC60爬取任务超时秒CRAWLER_NAVIGATE_TIMEOUT_SEC30页面导航超时秒CRAWLER_STORE_SCREENSHOTtrue是否保存截图CRAWLER_FULL_PAGE_ARCHIVEfalse是否做整页归档升级 Meilisearch索引版本迁移指南背景为什么不能随意升级Meilisearch 是 Karakeep 用于书签全文搜索的检索引擎。官方文档给出的约束是当前仓库锁定使用的 Meilisearch 版本为1.41.0见 docker/docker-compose.yml 中的getmeili/meilisearch:v1.41.0并建议没有充分理由不要升级。注意v0.31.0 文档撰写时版本为1.37.0而当前仓库docker-compose 与 docker/docker-compose.build.yml已随项目演进升级到1.41.0具体以你部署的镜像标签为准。如果强行升级很可能会遇到类似这样的版本不兼容报错Your database version (1.13.3) is incompatible with your current engine version (1.37.0). To migrate data between Meilisearch versions, please follow our guide on https://www.meilisearch.com/docs/learn/update_and_migration/updating.其本质是Meilisearch 的数据文件data.ms目录与引擎二进制之间存在版本强绑定跨大版本直接启动会拒绝加载旧索引。官方推荐的迁移步骤workaroundKarakeep 官方给出了一个简洁可靠的工作流核心思路是放弃旧索引、重建新索引停止 Meilisearch 容器docker compose stop meilisearch进入 Meilisearch 挂载到/meili_data的 volume删除或重命名data.ms目录。/meili_data的挂载声明见 docker/docker-compose.ymlvolumes: - meilisearch:/meili_data若使用默认 volume可先找到其位置再操作docker volume inspect karakeep_meilisearch # 删除旧索引目录或先改名备份 # 例如: mv data.ms data.ms.bak重新启动 Meilisearchdocker compose up -d meilisearch以管理员身份登录 Karakeep进入Admin Settings Background Jobs点击Reindex All Bookmarks该入口对应的后台接口为POST /admin/jobs/trigger/reindex实现见 packages/api/routes/admin.ts。等待重新索引完成。从接口语义packages/open-api/lib/admin.ts看不带modifiedWithinSeconds参数时该任务会清空现有索引并把全部书签重新入队完成后 Meilisearch 即可正常使用。从源码理解 Reindex 任务reindexAllBookmarks的完整实现位于 packages/trpc/routers/admin.ts它通过后台任务队列逐个重建书签的搜索索引。仓库测试用例packages/trpc/routers/admin.test.ts覆盖了两种关键行为可作为理解依据时间窗口限定的 reindex传入modifiedWithinSeconds时只重新索引该时间窗口内修改过的书签并保留已有索引适合日常增量修复无界 reindex不传参数则清空并重建全部索引适合 Meilisearch 版本迁移后的场景。因此迁移后应使用不带时间窗口参数的完整 reindex以确保旧版本数据被完整替换。升级前的重要提醒该 workaround 会丢弃 Meilisearch 中的全部索引数据但书签本体仍安全保存在 SQLite 主库中因此重新索引后即可恢复全部搜索能力若迁移过程中遇到问题Meilisearch 官方提供了一份升级迁移指南建议对照执行日常使用中若不需要新功能保持镜像标签不变即可规避整类问题升级前务必阅读对应版本的变更说明。附常见排障命令速查表场景推荐命令查看全部日志docker compose logs -f查看指定容器日志docker compose logs -f web/chrome/meilisearch应用环境变量修改docker compose up -d检查容器环境变量docker compose exec web env \| grep DATA_DIR验证 Ollama 可达性docker compose exec web curl -s http://host:11434/api/tags停止/启动 Meilisearchdocker compose stop meilisearch/docker compose up -d meilisearch查看 Meilisearch volumedocker volume inspect karakeep_meilisearch小结Karakeep 的常见故障虽然表象各异但背后遵循统一规律数据库路径一致性、环境变量拼写正确性、容器间网络可达性以及搜索索引与引擎版本匹配。掌握本文的五类排查路径再配合docker compose logs与 packages/shared/config.ts 中的变量定义交叉核对绝大多数自托管问题都能在数分钟内定位解决。遇到 Meilisearch 升级类问题请牢记停容器 → 清理data.ms→ 重启 → 管理后台全量 Reindex四步法即可平稳完成索引版本迁移。【免费下载链接】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 常见故障排查指南：从数据库初始化到 Meilisearch 索引迁移的完整排障手册
Karakeep 常见故障排查指南从数据库初始化到 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自托管书签应用v0.31.0 版本官方 Troubleshooting 文档为骨架系统梳理了自托管部署中最常遇到的五类问题——SQLite 数据库初始化失败、Chrome 容器日志噪音、AI 自动打标失效OpenAI / Ollama 两种场景、网页爬取不工作以及 Meilisearch 版本升级后的数据迁移。结合仓库源码与 Docker Compose 配置本文将为每类问题给出可落地的排查路径、修复步骤与源码级原理解析帮助读者在几分钟内定位并解决问题。排查前的通用方法论无论遇到哪一类问题Karakeep 官方文档给出的第一条建议始终是先查看容器日志。大多数故障都会在日志中留下明确线索例如推理服务未配置时的skipping inference as its not configured、数据库缺失时的SqliteError: no such table等。使用以下命令可以快速捕获相关容器的输出# 查看全部容器日志 docker compose logs -f # 只看某个容器的日志例如 web、chrome、meilisearch docker compose logs -f web docker compose logs -f chrome docker compose logs -f meilisearch同时Karakeep 的全部运行时行为都由环境变量驱动这些变量在 packages/shared/config.ts 中以 zod schema 集中定义和校验。排查问题前建议先核对.env文件中的变量名拼写是否与源码定义完全一致这是大量配置不生效类问题的根源。SqliteError: no such table: user报错含义与本质当日志中出现SqliteError: no such table: user时通常意味着数据库没有被正确初始化。Karakeep 使用 SQLite 作为主数据库见 packages/db所有用户、书签、标签等核心数据都存储在由DATA_DIR指定的数据目录中。该错误并非某张表损坏而是整库缺失或指向了错误的目录。常见诱因与修复步骤诱因一DATA_DIR 被清空或存储目录被更换DATA_DIR目录被清空或被有意更换了备份存储位置后数据库文件随之丢失。如果这是你有意为之只需重启容器让应用重新执行数据库初始化流程docker compose restart web重启后 Karakeep 会重建 SQLite 数据库结构并完成 schema 迁移迁移脚本位于 packages/db/migrate.ts历史迁移记录见 packages/db/drizzle。注意重新初始化意味着旧数据不再存在请务必在清空目录前做好备份。诱因二未使用默认 docker-compose 文件且遗漏了 DATA_DIR 变量如果你使用自定义 Compose 文件部署却忘记配置DATA_DIR环境变量会导致数据库被创建在服务实际使用的目录之外服务自然读不到表。在默认的 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也就是说官方建议的做法是保持DATA_DIR: /data不变通过修改 volume 映射来更换数据目录例如volumes: - /path/to/your/directory:/data从源码看DATA_DIR的默认值为空字符串packages/shared/config.ts而资源目录ASSETS_DIR在未配置时会被解析为DATA_DIR下的assets子目录packages/shared/config.ts可见DATA_DIR是整个数据体系的地基一旦错位不止数据库附件等资源同样会找不到。开发模式下的 Compose 文件docker/docker-compose.dev.yml也遵循同一约定支持通过${DATA_DIR:-/data}覆盖。排查命令速查# 确认 web 容器的实际 DATA_DIR 与挂载情况 docker compose exec web env | grep DATA_DIR docker inspect karakeep-web-1 --format {{json .Mounts}}Chrome Failed to Read DnsConfig如果 chrome 容器的日志中出现Failed to Read DnsConfig这是一个良性benign错误可以直接忽略。它并不代表 Karakeep 的爬虫或任何功能出了故障——如果你此时恰好遇到了其他问题两者之间没有因果关系请继续按其他章节排查。从源码角度看爬虫容器本质上是一个运行 Chrome 的独立服务docker/docker-compose.yml 中的chrome服务负责渲染网页、执行 JS、截图与整页归档等任务。这类容器在启动阶段读取宿主 DNS 配置时偶尔会抛出该警告但随后会回退到默认解析方式不影响功能无需任何处理。AI 自动打标不工作OpenAI 场景Karakeep 的 AI 自动打标由inference推理链路驱动相关的推理服务配置集中定义在 packages/shared/config.ts。使用 OpenAI 时按以下顺序排查1. 检查环境变量拼写确认变量名是否为OPENAI_API_KEY注意下划线位置不要写成OPENAI-API-KEY之类。拼写错误时日志中会出现类似skipping inference as its not configured的提示——这是因为推理功能是否启用直接由该变量是否存在决定。从源码看推理服务的isConfigured判定为isConfigured: !!val.OPENAI_API_KEY || !!val.OLLAMA_BASE_URL见 packages/shared/config.ts——只要OPENAI_API_KEY为空推理服务就被整体视为未配置自动打标自然静默跳过。如果只是临时验证配置是否生效也可以直接使用官方在 Compose 文件中预留的注释占位environment: # OPENAI_API_KEY: ...docker/docker-compose.yml2. 修改配置后必须重新拉起容器.env文件或 Compose 中的环境变量修改后仅docker restart不会重新读取环境变量必须执行docker compose up -d让 Compose 根据最新的.env重建容器。这也是明明配了 key 却还是不生效最常见的操作失误。3. OpenAI 账户需要预充值OpenAI 的 API 采用预付费模式账户余额不足时推理请求会直接失败日志中通常会出现insufficient funds之类的错误。请到 OpenAI 控制台确认账户有可用余额credits并留意服务 tier 与限额设置。可选的进阶调优变量除上述排障项外源码中还存在一组可选的 OpenAI 行为调优变量遇到超时或输出异常时可酌情设置packages/shared/config.ts变量说明OPENAI_BASE_URL自定义 OpenAI 兼容 API 地址OPENAI_TIMEOUT_SEC请求超时时间秒OPENAI_SERVICE_TIER取值auto/default/flexOPENAI_REASONING_EFFORT推理强度取值none/minimal/low/medium/high/xhighINFERENCE_TEXT_MODEL默认gpt-5.6-luna指定文本打标使用的模型INFERENCE_IMAGE_MODEL默认gpt-4o-mini指定图片打标使用的模型AI 自动打标不工作Ollama 场景使用 Ollama 本地推理时排障思路与 OpenAI 类似但多了几个本地化特有的坑1. 检查环境变量拼写确认变量名为OLLAMA_BASE_URL源码中定义于 packages/shared/config.ts。同样地拼写错误会导致日志出现skipping inference as its not configured。修改后同样需要docker compose up -d重新创建容器。2. 必须更换 INFERENCE_TEXT_MODEL这是 Ollama 场景最典型的坑Ollama 上并没有 GPT 系列模型如果你沿用默认的INFERENCE_TEXT_MODEL默认值为gpt-5.6-luna见 packages/shared/config.tsKarakeep 会拿 GPT 模型名去请求 Ollama必然失败。请将其改为你本地已拉取的模型例如environment: OLLAMA_BASE_URL: http://host.docker.internal:11434 INFERENCE_TEXT_MODEL: llama3.13. 检查容器间的网络可达性Ollama 服务器需要能被 Karakeep 容器访问到常见两类问题网络隔离Ollama 与 Karakeep 不在同一个 Docker 网络互相不可达。请确认两者使用同一 network或在 Compose 中显式声明网络。localhost 指向错误在容器内localhost指向容器自身而不是 Docker 宿主机。若你在宿主机上运行 OllamaOLLAMA_BASE_URL不能写http://localhost:11434应使用宿主机在 Docker 网络中的地址Linux 下通常可用host.docker.internal或通过docker network inspect查到宿主机网桥 IP例如http://172.17.0.1:11434。验证可达性docker compose exec web curl -s http://OLLAMA_HOST:11434/api/tags其他推理相关变量源码中还提供了一组与推理行为相关的开关packages/shared/config.ts排障时可关注变量默认值说明INFERENCE_ENABLE_AUTO_TAGGINGtrue是否启用自动打标INFERENCE_ENABLE_AUTO_SUMMARIZATIONfalse是否启用自动摘要INFERENCE_JOB_TIMEOUT_SEC30推理任务超时秒INFERENCE_FETCH_TIMEOUT_SEC300推理请求抓取超时秒INFERENCE_OUTPUT_SCHEMAstructured输出格式structured/json/plain网页爬取Crawling不工作Karakeep 的网页爬取由crawlerWorker驱动源码见 apps/workers/workers/crawlerWorker.ts它通过 WebSocket 连接 Chrome 容器执行渲染、截图与归档。排查要点核心排查项BROWSER_WEB_URL 是否与容器名匹配最常见的错误是你改了 chrome 容器的名字却没有同步修改BROWSER_WEB_URL环境变量。默认 Compose 中web 服务通过以下配置连接 Chromedocker/docker-compose.ymlBROWSER_WEB_URL: http://chrome:9222chrome是 Compose 服务名Docker 内部 DNS 会将其解析为 chrome 容器的地址。如果你把 chrome 服务改名为my-chrome就必须同步把BROWSER_WEB_URL改为http://my-chrome:9222否则 web 容器找不到爬虫浏览器爬取任务会失败。从源码看BROWSER_WEB_URL对应crawler.browserWebUrl配置packages/shared/config.ts同时还有一个可选的BROWSER_WEBSOCKET_URL用于直接指定 WebSocket 地址。在 adhoc 爬取 CLIapps/workers/scripts/crawlAdhoc.ts中可以看到其典型用法例如指向本机调试实例BROWSER_WEB_URLhttp://127.0.0.1:9222源码中的自我保护逻辑值得注意的是apps/workers/workers/crawlerWorker.ts 中有一个值得了解的细节当BROWSER_WEB_URL与BROWSER_WEBSOCKET_URL均未配置时crawlPage()会静默回退为纯 HTTP 抓取不执行 JS、不截图。adhoc CLI 为了避免这种悄悄降级污染测试结果会在无浏览器后端时直接抛错拒绝运行[adhoc] No browser backend configured — refusing to run. crawlPage() would silently fall back to a plain HTTP fetch. Set BROWSER_WEB_URL or BROWSER_WEBSOCKET_URL to a reachable Chrome.这提醒我们如果爬取结果缺少 JS 渲染内容或截图先确认浏览器连接确实建立成功而不是只看到抓到了 HTML就认为功能正常。相关调优变量爬取链路的超时与资源控制变量packages/shared/config.ts中排障时常关注变量默认值说明CRAWLER_HEADLESS_BROWSERtrue是否使用无头浏览器BROWSER_CONNECT_ONDEMANDfalse是否按需建立浏览器连接CRAWLER_JOB_TIMEOUT_SEC60爬取任务超时秒CRAWLER_NAVIGATE_TIMEOUT_SEC30页面导航超时秒CRAWLER_STORE_SCREENSHOTtrue是否保存截图CRAWLER_FULL_PAGE_ARCHIVEfalse是否做整页归档升级 Meilisearch索引版本迁移指南背景为什么不能随意升级Meilisearch 是 Karakeep 用于书签全文搜索的检索引擎。官方文档给出的约束是当前仓库锁定使用的 Meilisearch 版本为1.41.0见 docker/docker-compose.yml 中的getmeili/meilisearch:v1.41.0并建议没有充分理由不要升级。注意v0.31.0 文档撰写时版本为1.37.0而当前仓库docker-compose 与 docker/docker-compose.build.yml已随项目演进升级到1.41.0具体以你部署的镜像标签为准。如果强行升级很可能会遇到类似这样的版本不兼容报错Your database version (1.13.3) is incompatible with your current engine version (1.37.0). To migrate data between Meilisearch versions, please follow our guide on https://www.meilisearch.com/docs/learn/update_and_migration/updating.其本质是Meilisearch 的数据文件data.ms目录与引擎二进制之间存在版本强绑定跨大版本直接启动会拒绝加载旧索引。官方推荐的迁移步骤workaroundKarakeep 官方给出了一个简洁可靠的工作流核心思路是放弃旧索引、重建新索引停止 Meilisearch 容器docker compose stop meilisearch进入 Meilisearch 挂载到/meili_data的 volume删除或重命名data.ms目录。/meili_data的挂载声明见 docker/docker-compose.ymlvolumes: - meilisearch:/meili_data若使用默认 volume可先找到其位置再操作docker volume inspect karakeep_meilisearch # 删除旧索引目录或先改名备份 # 例如: mv data.ms data.ms.bak重新启动 Meilisearchdocker compose up -d meilisearch以管理员身份登录 Karakeep进入Admin Settings Background Jobs点击Reindex All Bookmarks该入口对应的后台接口为POST /admin/jobs/trigger/reindex实现见 packages/api/routes/admin.ts。等待重新索引完成。从接口语义packages/open-api/lib/admin.ts看不带modifiedWithinSeconds参数时该任务会清空现有索引并把全部书签重新入队完成后 Meilisearch 即可正常使用。从源码理解 Reindex 任务reindexAllBookmarks的完整实现位于 packages/trpc/routers/admin.ts它通过后台任务队列逐个重建书签的搜索索引。仓库测试用例packages/trpc/routers/admin.test.ts覆盖了两种关键行为可作为理解依据时间窗口限定的 reindex传入modifiedWithinSeconds时只重新索引该时间窗口内修改过的书签并保留已有索引适合日常增量修复无界 reindex不传参数则清空并重建全部索引适合 Meilisearch 版本迁移后的场景。因此迁移后应使用不带时间窗口参数的完整 reindex以确保旧版本数据被完整替换。升级前的重要提醒该 workaround 会丢弃 Meilisearch 中的全部索引数据但书签本体仍安全保存在 SQLite 主库中因此重新索引后即可恢复全部搜索能力若迁移过程中遇到问题Meilisearch 官方提供了一份升级迁移指南建议对照执行日常使用中若不需要新功能保持镜像标签不变即可规避整类问题升级前务必阅读对应版本的变更说明。附常见排障命令速查表场景推荐命令查看全部日志docker compose logs -f查看指定容器日志docker compose logs -f web/chrome/meilisearch应用环境变量修改docker compose up -d检查容器环境变量docker compose exec web env \| grep DATA_DIR验证 Ollama 可达性docker compose exec web curl -s http://host:11434/api/tags停止/启动 Meilisearchdocker compose stop meilisearch/docker compose up -d meilisearch查看 Meilisearch volumedocker volume inspect karakeep_meilisearch小结Karakeep 的常见故障虽然表象各异但背后遵循统一规律数据库路径一致性、环境变量拼写正确性、容器间网络可达性以及搜索索引与引擎版本匹配。掌握本文的五类排查路径再配合docker compose logs与 packages/shared/config.ts 中的变量定义交叉核对绝大多数自托管问题都能在数分钟内定位解决。遇到 Meilisearch 升级类问题请牢记停容器 → 清理data.ms→ 重启 → 管理后台全量 Reindex四步法即可平稳完成索引版本迁移。【免费下载链接】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），仅供参考
