指南：數(shù)據(jù)庫、AI 打標簽、爬蟲與 Meilisearch 遷移排錯全解)
Karakeep 自托管故障排查實戰(zhàn)指南數(shù)據(jù)庫、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 數(shù)據(jù)庫未初始化、Chrome 容器良性報錯、OpenAI/Ollama 自動打標簽失效、鏈接爬取不工作以及 Meilisearch 升級遷移。讀完本文你將能依據(jù)日志定位根因、按步驟修復環(huán)境變量與容器網(wǎng)絡問題并掌握重建搜索索引的標準操作流程快速恢復服務的完整能力。SqliteError: no such table: user——數(shù)據(jù)庫未初始化日志中出現(xiàn)SqliteError: no such table: user說明 Karakeep 的 SQLite 數(shù)據(jù)庫沒有正確初始化。Karakeep 使用 SQLite 作為主數(shù)據(jù)庫在 packages/db 中通過 Drizzle ORM 管理 schema這張user表屬于認證模塊的核心表它不存在通常意味著程序啟動時未能執(zhí)行建表/遷移流程而不是數(shù)據(jù)損壞。常見誘因有兩種DATA_DIR 被清空或更換DATA_DIR目錄被清空或者其底層存儲目錄被更換。如果是你有意為之直接重啟容器讓啟動流程重新初始化數(shù)據(jù)庫即可。DATA_DIR 缺失如果你沒有使用默認的 docker compose 文件并且忘記配置DATA_DIR環(huán)境變量那么數(shù)據(jù)庫會被創(chuàng)建在與服務實際使用目錄不同的位置導致服務讀取不到表結構。在 packages/shared/config.ts 中DATA_DIR的默認值是空字符串而ASSETS_DIR默認會落到${DATA_DIR}/assets這意味著一旦漏配DATA_DIR數(shù)據(jù)與資源文件的落盤位置都會變得不可預期。默認的 docker/docker-compose.yml 中將DATA_DIR固定為/data并注釋了「DONT CHANGE THIS」——如果你想改存儲位置官方建議的做法是修改 volume 映射- /path/to/your/directory:/data而不是直接改DATA_DIR的值。這樣既能保證數(shù)據(jù)目錄一致也避免容器重建后路徑漂移。排障建議docker compose logs web | grep -i sqlite查看啟動時是否有遷移報錯同時確認宿主機上DATA_DIR對應的 volume 是否確實存在且非空。Chrome Failed to Read DnsConfig——可安全忽略的良性錯誤如果 chrome 容器的日志里出現(xiàn)Failed to Read DnsConfig這是一個良性錯誤可以放心忽略。它與你在使用中遇到的任何功能故障都無關。該報錯源于 Chromium 在容器化環(huán)境下讀取 DNS 配置失敗時打印的警告Karakeep 的爬蟲 worker 通過 Chrome DevTools 協(xié)議驅動該瀏覽器實例完成頁面渲染與截圖DNS 解析實際由容器網(wǎng)絡層處理因此該警告不影響爬取行為。AI 自動打標簽不工作使用 OpenAI 時先檢查 web 容器的日志通常它會直接告訴你問題所在。最常見的三類原因環(huán)境變量名拼寫錯誤OPENAI_API_KEY拼錯會導致日志出現(xiàn)類似skipping inference as its not configured的提示。在 packages/shared/config.ts 中inference.isConfigured的判斷邏輯是!!val.OPENAI_API_KEY || !!val.OLLAMA_BASE_URL——只要該變量未正確注入自動打標簽就會被整體跳過而且這種跳過是靜默的不會拋出異常很容易被誤判為模型問題。配置后未重啟修改完 OpenAI 配置后忘記執(zhí)行docker compose up容器仍在用舊環(huán)境變量運行。賬戶未預充值OpenAI 要求先為賬戶充值額度才能調(diào)用 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 一節(jié)。同時如果同時配置了 Ollama 與 OpenAIconfig.ts 中的判斷會因兩者其一存在而認為推理已配置此時更要核對實際調(diào)用的是哪條鏈路。AI 自動打標簽不工作使用 Ollama 時同樣先看容器日志常見原因按出現(xiàn)頻率排列OLLAMA_BASE_URL拼寫錯誤會得到與 OpenAI 類似的skipping inference as its not configured日志。配置后未重啟忘記執(zhí)行docker compose up。未修改INFERENCE_TEXT_MODEL這是最容易踩的坑。當前倉庫 packages/shared/config.ts 中INFERENCE_TEXT_MODEL的默認值是gpt-5.6-lunaOpenAI 系模型如果你接的是 Ollama 卻沿用默認值Karakeep 會嘗試用 GPT 模型請求 Ollama 的/api/chat接口兩者協(xié)議與模型名完全不匹配必然失敗。使用 Ollama 時務必顯式設置為本機已拉取的模型例如llama3、qwen2.5等。Ollama 服務對 Karakeep 容器不可達Ollama 與 Karakeep 容器不在同一個 docker 網(wǎng)絡把OLLAMA_BASE_URL寫成了localhost。注意localhost指向的是容器自身而不是 docker 宿主機。正確的做法是在宿主機上配置 Ollama 監(jiān)聽0.0.0.0然后在容器內(nèi)使用宿主機在 docker 網(wǎng)絡中的地址Linux 下通常是172.17.0.1macOS/Windows 桌面版可用宿主機專用地址或用host.docker.internal需 docker 支持。此外 docs/docs/03-configuration/01-environment-variables.md 還提示Ollama 場景下建議同步調(diào)大INFERENCE_FETCH_TIMEOUT_SEC默認 300 秒與INFERENCE_JOB_TIMEOUT_SEC默認 30 秒本地無 GPU 時推理耗時較長容易先于模型響應而超時。INFERENCE_IMAGE_MODEL也需替換為支持視覺的模型如llava否則圖片類書簽的推理同樣會失敗。爬取Crawling不工作先看日志。最常見的原因是你改了 chrome 容器的名字卻沒有同步修改BROWSER_WEB_URL環(huán)境變量。默認的 docker/docker-compose.yml 中該值寫死為http://chrome:9222其中chrome正是 compose 服務名——一旦容器被重命名該地址立即失效。從源碼看這個變量的重要性在 apps/workers/workers/crawlerWorker.ts 中爬蟲 worker 會檢查browserWebUrl/browserWebSocketUrl是否配置。若兩者都為空crawlPage()會靜默回退為純 HTTP 抓取browserlessCrawlPage這意味著不執(zhí)行 JavaScript、不產(chǎn)生截圖——頁面行為看起來能抓但功能殘缺這正是排障時容易被忽略的點。若要徹底關閉瀏覽器路徑行為是可控的但你多半是想要瀏覽器渲染能力因此請確保BROWSER_WEB_URL指向實際可用的 Chrome 調(diào)試端口compose 默認http://chrome:9222若使用 Browserless 等外部服務可改用BROWSER_WEBSOCKET_URL直接指定 websocket 調(diào)試地址見 docs/docs/03-configuration/01-environment-variables.md 的 Crawler Configs 一節(jié)改完環(huán)境變量后務必docker compose up -d讓 web 容器重建生效。升級 Meilisearch版本不兼容與索引重建Meilisearch 是 Karakeep 的書簽全文搜索后端。v0.29 文檔明確指出項目鎖定 Meilisearch1.13.3版本不建議無充分理由自行升級而當前倉庫主線的 docker/docker-compose.yml 已固定鏡像getmeili/meilisearch:v1.41.0——無論哪個版本線原則一致跟著項目鎖定的版本走別擅自升級。一旦引擎版本與數(shù)據(jù)版本不匹配就會看到類似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 索引再把所有書簽按低優(yōu)先級批量入隊到搜索索引隊列由搜索 worker 逐個重建。因此清空data.ms只是重置引擎?zhèn)鹊臄?shù)據(jù)真正的索引內(nèi)容靠這次全量重放生成二者缺一不可。操作提醒data.ms里是 Meilisearch 的原始索引數(shù)據(jù)刪除后僅需重建搜索索引不會影響 SQLite 中的書簽、標簽等主數(shù)據(jù)但如果你的自定義搜索設置如停用詞、同義詞存放在 Meilisearch 側重裝后需要重新配置。小結一套可復用的排障思路縱覽上述五類問題Karakeep 自托管的故障大多可歸結為三類根因環(huán)境變量未正確注入或拼寫錯誤OpenAI/Ollama/爬蟲、容器間網(wǎng)絡與命名不一致Ollama 地址、chrome 服務名、底層存儲狀態(tài)異常SQLite 目錄、Meilisearch 版本。建議每次排障都從docker compose logs開始對照 packages/shared/config.ts 中聲明的全部環(huán)境變量逐一核對再結合 docs/docs/03-configuration/01-environment-variables.md 的參數(shù)表確認默認值與取值約束——大多數(shù)神秘故障在這一步就會現(xiàn)出原形。【免費下載鏈接】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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Karakeep 自托管故障排查實戰(zhàn)指南：數(shù)據(jù)庫、AI 打標簽、爬蟲與 Meilisearch 遷移排錯全解
Karakeep 自托管故障排查實戰(zhàn)指南數(shù)據(jù)庫、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 數(shù)據(jù)庫未初始化、Chrome 容器良性報錯、OpenAI/Ollama 自動打標簽失效、鏈接爬取不工作以及 Meilisearch 升級遷移。讀完本文你將能依據(jù)日志定位根因、按步驟修復環(huán)境變量與容器網(wǎng)絡問題并掌握重建搜索索引的標準操作流程快速恢復服務的完整能力。SqliteError: no such table: user——數(shù)據(jù)庫未初始化日志中出現(xiàn)SqliteError: no such table: user說明 Karakeep 的 SQLite 數(shù)據(jù)庫沒有正確初始化。Karakeep 使用 SQLite 作為主數(shù)據(jù)庫在 packages/db 中通過 Drizzle ORM 管理 schema這張user表屬于認證模塊的核心表它不存在通常意味著程序啟動時未能執(zhí)行建表/遷移流程而不是數(shù)據(jù)損壞。常見誘因有兩種DATA_DIR 被清空或更換DATA_DIR目錄被清空或者其底層存儲目錄被更換。如果是你有意為之直接重啟容器讓啟動流程重新初始化數(shù)據(jù)庫即可。DATA_DIR 缺失如果你沒有使用默認的 docker compose 文件并且忘記配置DATA_DIR環(huán)境變量那么數(shù)據(jù)庫會被創(chuàng)建在與服務實際使用目錄不同的位置導致服務讀取不到表結構。在 packages/shared/config.ts 中DATA_DIR的默認值是空字符串而ASSETS_DIR默認會落到${DATA_DIR}/assets這意味著一旦漏配DATA_DIR數(shù)據(jù)與資源文件的落盤位置都會變得不可預期。默認的 docker/docker-compose.yml 中將DATA_DIR固定為/data并注釋了「DONT CHANGE THIS」——如果你想改存儲位置官方建議的做法是修改 volume 映射- /path/to/your/directory:/data而不是直接改DATA_DIR的值。這樣既能保證數(shù)據(jù)目錄一致也避免容器重建后路徑漂移。排障建議docker compose logs web | grep -i sqlite查看啟動時是否有遷移報錯同時確認宿主機上DATA_DIR對應的 volume 是否確實存在且非空。Chrome Failed to Read DnsConfig——可安全忽略的良性錯誤如果 chrome 容器的日志里出現(xiàn)Failed to Read DnsConfig這是一個良性錯誤可以放心忽略。它與你在使用中遇到的任何功能故障都無關。該報錯源于 Chromium 在容器化環(huán)境下讀取 DNS 配置失敗時打印的警告Karakeep 的爬蟲 worker 通過 Chrome DevTools 協(xié)議驅動該瀏覽器實例完成頁面渲染與截圖DNS 解析實際由容器網(wǎng)絡層處理因此該警告不影響爬取行為。AI 自動打標簽不工作使用 OpenAI 時先檢查 web 容器的日志通常它會直接告訴你問題所在。最常見的三類原因環(huán)境變量名拼寫錯誤OPENAI_API_KEY拼錯會導致日志出現(xiàn)類似skipping inference as its not configured的提示。在 packages/shared/config.ts 中inference.isConfigured的判斷邏輯是!!val.OPENAI_API_KEY || !!val.OLLAMA_BASE_URL——只要該變量未正確注入自動打標簽就會被整體跳過而且這種跳過是靜默的不會拋出異常很容易被誤判為模型問題。配置后未重啟修改完 OpenAI 配置后忘記執(zhí)行docker compose up容器仍在用舊環(huán)境變量運行。賬戶未預充值OpenAI 要求先為賬戶充值額度才能調(diào)用 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 一節(jié)。同時如果同時配置了 Ollama 與 OpenAIconfig.ts 中的判斷會因兩者其一存在而認為推理已配置此時更要核對實際調(diào)用的是哪條鏈路。AI 自動打標簽不工作使用 Ollama 時同樣先看容器日志常見原因按出現(xiàn)頻率排列OLLAMA_BASE_URL拼寫錯誤會得到與 OpenAI 類似的skipping inference as its not configured日志。配置后未重啟忘記執(zhí)行docker compose up。未修改INFERENCE_TEXT_MODEL這是最容易踩的坑。當前倉庫 packages/shared/config.ts 中INFERENCE_TEXT_MODEL的默認值是gpt-5.6-lunaOpenAI 系模型如果你接的是 Ollama 卻沿用默認值Karakeep 會嘗試用 GPT 模型請求 Ollama 的/api/chat接口兩者協(xié)議與模型名完全不匹配必然失敗。使用 Ollama 時務必顯式設置為本機已拉取的模型例如llama3、qwen2.5等。Ollama 服務對 Karakeep 容器不可達Ollama 與 Karakeep 容器不在同一個 docker 網(wǎng)絡把OLLAMA_BASE_URL寫成了localhost。注意localhost指向的是容器自身而不是 docker 宿主機。正確的做法是在宿主機上配置 Ollama 監(jiān)聽0.0.0.0然后在容器內(nèi)使用宿主機在 docker 網(wǎng)絡中的地址Linux 下通常是172.17.0.1macOS/Windows 桌面版可用宿主機專用地址或用host.docker.internal需 docker 支持。此外 docs/docs/03-configuration/01-environment-variables.md 還提示Ollama 場景下建議同步調(diào)大INFERENCE_FETCH_TIMEOUT_SEC默認 300 秒與INFERENCE_JOB_TIMEOUT_SEC默認 30 秒本地無 GPU 時推理耗時較長容易先于模型響應而超時。INFERENCE_IMAGE_MODEL也需替換為支持視覺的模型如llava否則圖片類書簽的推理同樣會失敗。爬取Crawling不工作先看日志。最常見的原因是你改了 chrome 容器的名字卻沒有同步修改BROWSER_WEB_URL環(huán)境變量。默認的 docker/docker-compose.yml 中該值寫死為http://chrome:9222其中chrome正是 compose 服務名——一旦容器被重命名該地址立即失效。從源碼看這個變量的重要性在 apps/workers/workers/crawlerWorker.ts 中爬蟲 worker 會檢查browserWebUrl/browserWebSocketUrl是否配置。若兩者都為空crawlPage()會靜默回退為純 HTTP 抓取browserlessCrawlPage這意味著不執(zhí)行 JavaScript、不產(chǎn)生截圖——頁面行為看起來能抓但功能殘缺這正是排障時容易被忽略的點。若要徹底關閉瀏覽器路徑行為是可控的但你多半是想要瀏覽器渲染能力因此請確保BROWSER_WEB_URL指向實際可用的 Chrome 調(diào)試端口compose 默認http://chrome:9222若使用 Browserless 等外部服務可改用BROWSER_WEBSOCKET_URL直接指定 websocket 調(diào)試地址見 docs/docs/03-configuration/01-environment-variables.md 的 Crawler Configs 一節(jié)改完環(huán)境變量后務必docker compose up -d讓 web 容器重建生效。升級 Meilisearch版本不兼容與索引重建Meilisearch 是 Karakeep 的書簽全文搜索后端。v0.29 文檔明確指出項目鎖定 Meilisearch1.13.3版本不建議無充分理由自行升級而當前倉庫主線的 docker/docker-compose.yml 已固定鏡像getmeili/meilisearch:v1.41.0——無論哪個版本線原則一致跟著項目鎖定的版本走別擅自升級。一旦引擎版本與數(shù)據(jù)版本不匹配就會看到類似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 索引再把所有書簽按低優(yōu)先級批量入隊到搜索索引隊列由搜索 worker 逐個重建。因此清空data.ms只是重置引擎?zhèn)鹊臄?shù)據(jù)真正的索引內(nèi)容靠這次全量重放生成二者缺一不可。操作提醒data.ms里是 Meilisearch 的原始索引數(shù)據(jù)刪除后僅需重建搜索索引不會影響 SQLite 中的書簽、標簽等主數(shù)據(jù)但如果你的自定義搜索設置如停用詞、同義詞存放在 Meilisearch 側重裝后需要重新配置。小結一套可復用的排障思路縱覽上述五類問題Karakeep 自托管的故障大多可歸結為三類根因環(huán)境變量未正確注入或拼寫錯誤OpenAI/Ollama/爬蟲、容器間網(wǎng)絡與命名不一致Ollama 地址、chrome 服務名、底層存儲狀態(tài)異常SQLite 目錄、Meilisearch 版本。建議每次排障都從docker compose logs開始對照 packages/shared/config.ts 中聲明的全部環(huán)境變量逐一核對再結合 docs/docs/03-configuration/01-environment-variables.md 的參數(shù)表確認默認值與取值約束——大多數(shù)神秘故障在這一步就會現(xiàn)出原形。【免費下載鏈接】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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考