Karakeep 極簡(jiǎn)安裝指南無(wú) Meilisearch、Chrome 與 AI 依賴的單容器部署方案【免費(fèi)下載鏈接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ho/hoarder本篇技術(shù)指南聚焦 Karakeep原 Hoarder的極簡(jiǎn)安裝Minimal Installation方案在不引入 Meilisearch 全文檢索引擎、Chrome 無(wú)頭瀏覽器與 OpenAI/Ollama 推理服務(wù)的前提下僅用單個(gè)容器完成自托管部署。你將掌握完整的最小化docker-compose.yml與docker run命令寫法、關(guān)鍵環(huán)境變量的底層校驗(yàn)邏輯以及極簡(jiǎn)模式下各功能模塊的實(shí)際降級(jí)行為并了解后續(xù)向完整安裝平滑升級(jí)的路徑。極簡(jiǎn)安裝的本質(zhì)犧牲哪些功能保留哪些能力Karakeep 的完整安裝見 Docker 安裝指南 與倉(cāng)庫(kù)根目錄的 docker/docker-compose.yml默認(rèn)由三組外部依賴共同支撐核心體驗(yàn)依賴組件在完整安裝中的角色極簡(jiǎn)安裝不部署后的行為Meilisearch全文檢索后端通過(guò)MEILI_ADDR連接搜索功能被完全禁用搜索入口與索引任務(wù)均不生效Chrome無(wú)頭瀏覽器負(fù)責(zé)頁(yè)面 JS 渲染、網(wǎng)站截圖、整頁(yè)歸檔爬取仍可工作但退化為純 HTTP 請(qǐng)求無(wú)法截取網(wǎng)站截圖含 JavaScript 動(dòng)態(tài)內(nèi)容的頁(yè)面無(wú)法被正確抓取OpenAI / OllamaAI 自動(dòng)打標(biāo)簽、摘要、圖像理解AI 自動(dòng)打標(biāo)簽被禁用這三種能力對(duì)發(fā)揮 Karakeep 的完整價(jià)值非常重要但如果你運(yùn)行在資源受限的環(huán)境低配 VPS、樹莓派、內(nèi)網(wǎng) NAS、臨時(shí)驗(yàn)證環(huán)境中完全可以用下面這份最小化編排文件跳過(guò)全部外部依賴只啟動(dòng)一個(gè)容器。方式一使用最小化 docker-compose.yml將以下內(nèi)容保存為docker-compose.yml并執(zhí)行docker compose up -dservices: web: image: ghcr.io/karakeep-app/karakeep:release restart: unless-stopped volumes: - data:/data ports: - 3000:3000 environment: DATA_DIR: /data NEXTAUTH_SECRET: super_random_string volumes: data:逐項(xiàng)拆解這份編排文件image: ghcr.io/karakeep-app/karakeep:releaseKarakeep 的 All-in-OneAIO鏡像。從 docker/Dockerfile 的構(gòu)建結(jié)構(gòu)aio_builder、aio、web、workers等多個(gè) target可以看出該鏡像內(nèi)置了 Web 服務(wù)與全部后臺(tái) worker單容器即可運(yùn)行完整應(yīng)用release標(biāo)簽指向最新穩(wěn)定版生產(chǎn)環(huán)境建議鎖定具體版本號(hào)如0.29.0以便控制升級(jí)節(jié)奏。volumes: - data:/data將數(shù)據(jù)目錄掛載為 Docker 命名卷。數(shù)據(jù)庫(kù)SQLite、默認(rèn)資產(chǎn)存儲(chǔ)${DATA_DIR}/assets都位于該目錄下請(qǐng)務(wù)必保留持久化否則容器重建會(huì)丟失全部數(shù)據(jù)。ports: - 3000:3000將容器內(nèi) 3000 端口映射到宿主機(jī)。若宿主機(jī) 3000 被占用只需修改左側(cè)宿主端口即可例如8080:3000不要去改動(dòng)容器內(nèi)端口。environment僅需兩個(gè)關(guān)鍵變量DATA_DIR指定持久化目錄NEXTAUTH_SECRET用于簽名 JWT 會(huì)話令牌詳見下文。方式二使用單條 docker run 命令不習(xí)慣 compose 的話也可以用下面這條等價(jià)命令直接啟動(dòng)docker run -d \ --restart unless-stopped \ -v data:/data \ -p 3000:3000 \ -e DATA_DIR/data \ -e NEXTAUTH_SECRETsuper_random_string \ ghcr.io/karakeep-app/karakeep:release參數(shù)與 compose 版本一一對(duì)應(yīng)-d后臺(tái)運(yùn)行、--restart unless-stopped保證崩潰后自動(dòng)拉起、-v data:/data掛載數(shù)據(jù)卷、-p 3000:3000暴露端口、兩個(gè)-e注入環(huán)境變量。啟動(dòng)后訪問(wèn)http://localhost:3000即可看到注冊(cè)/登錄頁(yè)面。必讀警告NEXTAUTH_SECRET 必須替換為真隨機(jī)串兩份配置示例中的super_random_string只是占位符必須替換為真正隨機(jī)的字符串。原文檔給出的推薦生成命令為openssl rand -hex 32為什么這個(gè)變量如此關(guān)鍵在 packages/shared/config.ts 中可以看到應(yīng)用啟動(dòng)時(shí)會(huì)調(diào)用signingSecret()若NEXTAUTH_SECRET未設(shè)置會(huì)直接拋出NEXTAUTH_SECRET is not set異常而該秘密用于簽發(fā)與校驗(yàn) NextAuth 的 JWT 令牌。使用固定弱口令意味著所有會(huì)話令牌都可被預(yù)測(cè)或偽造屬于嚴(yán)重安全風(fēng)險(xiǎn)。同理若日后啟用 Meilisearch其MEILI_MASTER_KEY也建議用openssl rand -base64 36之類的方式生成。極簡(jiǎn)模式下仍然可用的功能源碼級(jí)佐證很多用戶擔(dān)心極簡(jiǎn)安裝會(huì)殘廢實(shí)際上核心的書簽管理能力鏈接、筆記、圖片的增刪改查、標(biāo)簽、列表、導(dǎo)入導(dǎo)出、RSS 等都完整保留。以下從源碼確認(rèn)三處關(guān)鍵行為1. 爬取降級(jí)為純 HTTP 模式截圖與 JS 渲染不可用在 apps/workers/workers/crawler/crawlPage.ts 中browserlessCrawlPage()函數(shù)明確處理了無(wú)瀏覽器后端的場(chǎng)景日志會(huì)打印Running in browserless mode. Will do a plain http request ... Screenshots will be disabled.隨后通過(guò)fetchWithProxy直接抓取 URL 內(nèi)容返回的screenshot與pdf均為undefined。對(duì)應(yīng)地apps/workers/workers/crawler/browser.ts 只在配置了BROWSER_WEBSOCKET_URL直連調(diào)試 WebSocket或BROWSER_WEB_URL先取調(diào)試地址再解析 WebSocket時(shí)才啟動(dòng) Playwright 瀏覽器連接兩者都未設(shè)置時(shí)worker 走純 HTTP 路徑。因此在極簡(jiǎn)模式下純靜態(tài)頁(yè)面服務(wù)端渲染的 HTML可以正常抓取正文與元數(shù)據(jù)依賴 JS 動(dòng)態(tài)渲染的 SPA 頁(yè)面只會(huì)拿到初始 HTML內(nèi)容可能缺失網(wǎng)站截圖、整頁(yè)歸檔CRAWLER_FULL_PAGE_ARCHIVE、PDF 快照等能力無(wú)法使用。2. 搜索功能整體關(guān)閉但索引邏輯不會(huì)報(bào)錯(cuò)未設(shè)置MEILI_ADDR時(shí)搜索后端不可用全文搜索入口被整體禁用從 packages/shared/config.ts 的search配置段看搜索相關(guān) workersearchWorker的索引任務(wù)在此場(chǎng)景下不會(huì)產(chǎn)生實(shí)際效果系統(tǒng)不會(huì)因此崩潰只會(huì)靜默跳過(guò)。這也是官方文檔強(qiáng)調(diào)搜索功能會(huì)被完全禁用的底層原因。3. 后臺(tái) worker 仍然全部隨容器啟動(dòng)極簡(jiǎn)安裝并非只有一個(gè) Web 進(jìn)程。鏡像內(nèi)通過(guò) s6-overlay 同時(shí)拉起 Web 與 workers 服務(wù)見 docker/Dockerfile 中svc-web與svc-workers兩個(gè)服務(wù)定義。在 apps/workers/index.ts 中注冊(cè)的 worker 包括crawler、inference、search、adminMaintenance、video、feed、assetPreprocessing、webhook、ruleEngine、backup等。未配置對(duì)應(yīng)依賴的 worker如無(wú) Meilisearch 時(shí)的search、無(wú) OpenAI/Ollama 時(shí)的inference會(huì)保持空閑而crawler純 HTTP 模式、adminMaintenance、feed等仍正常運(yùn)轉(zhuǎn)。如需進(jìn)一步裁剪可結(jié)合WORKERS_ENABLED_WORKERS/WORKERS_DISABLED_WORKERS環(huán)境變量按需啟停。兩個(gè)必配環(huán)境變量詳解極簡(jiǎn)安裝只需要理解兩個(gè)環(huán)境變量但它們承擔(dān)了最關(guān)鍵的基礎(chǔ)職責(zé)變量必填默認(rèn)值說(shuō)明DATA_DIR是未設(shè)置持久化數(shù)據(jù)目錄數(shù)據(jù)庫(kù)SQLite存放于此資產(chǎn)圖片、截圖等默認(rèn)存儲(chǔ)在${DATA_DIR}/assets可被ASSETS_DIR覆蓋。在容器內(nèi)固定為/data與卷掛載點(diǎn)對(duì)應(yīng)不要改動(dòng)容器內(nèi)值NEXTAUTH_SECRET是未設(shè)置用于簽名 JWT 令牌的隨機(jī)字符串缺失時(shí)應(yīng)用啟動(dòng)即失敗見 packages/shared/config.ts完整的變量清單含PORT、NEXTAUTH_URL、LOG_LEVEL、DB_WAL_MODE、MAX_ASSET_SIZE_MB、CRAWLER_*、INFERENCE_*、ASSET_STORE_S3_*、SMTP_*、OTEL_*等數(shù)十項(xiàng)請(qǐng)查閱 環(huán)境變量配置文檔其權(quán)威定義位于 packages/shared/config.ts通過(guò) zod schema 解析process.env并對(duì)非法值做啟動(dòng)期校驗(yàn)。兩點(diǎn)提示若部署在非本機(jī)、且后續(xù)要接入瀏覽器擴(kuò)展或移動(dòng)端建議同時(shí)設(shè)置NEXTAUTH_URL指向?qū)嵗膶?shí)際訪問(wèn)地址如http://192.168.1.10:3000否則登出等場(chǎng)景可能出現(xiàn)跳轉(zhuǎn)地址錯(cuò)誤極簡(jiǎn)部署后若磁盤空間緊張可考慮DB_WAL_MODEtrueSQLite WAL 模式提升并發(fā)讀寫性能但不要在網(wǎng)絡(luò)盤上開啟。從極簡(jiǎn)到完整按需補(bǔ)齊依賴的升級(jí)路徑極簡(jiǎn)安裝適合受限環(huán)境但若后續(xù)需要全文搜索、截圖與 AI 打標(biāo)簽無(wú)需重新部署數(shù)據(jù)只需在 compose 中補(bǔ)齊對(duì)應(yīng)服務(wù)并增加環(huán)境變量。參照倉(cāng)庫(kù)根目錄的 docker/docker-compose.yml 完整編排services: web: image: ghcr.io/karakeep-app/karakeep:release restart: unless-stopped volumes: - data:/data ports: - 3000:3000 environment: MEILI_ADDR: http://meilisearch:7700 BROWSER_WEB_URL: http://chrome:9222 # OPENAI_API_KEY: ... # 需要自動(dòng)打標(biāo)簽時(shí)取消注釋 DATA_DIR: /data chrome: image: ghcr.io/karakeep-app/karakeep-chrome:release restart: unless-stopped init: true meilisearch: image: getmeili/meilisearch:v1.41.0 restart: unless-stopped environment: MEILI_NO_ANALYTICS: true volumes: - meilisearch:/meili_data volumes: meilisearch: data:升級(jí)要點(diǎn)啟用搜索設(shè)置MEILI_ADDR指向 Meilisearch 服務(wù)地址生產(chǎn)環(huán)境還需為 Meilisearch 配置MEILI_MASTER_KEYopenssl rand -base64 36 | tr -dc A-Za-z0-9生成。啟用瀏覽器爬取設(shè)置BROWSER_WEB_URL或直連 WebSocket 的BROWSER_WEBSOCKET_URL指向 Chrome 容器即可恢復(fù)截圖、JS 渲染、整頁(yè)歸檔能力。啟用 AI 打標(biāo)簽設(shè)置OPENAI_API_KEY或自建 Ollama 時(shí)設(shè)置OLLAMA_BASE_URL。從 packages/shared/config.ts 可見inference.isConfigured的判定邏輯正是!!OPENAI_API_KEY || !!OLLAMA_BASE_URL兩者均未配置時(shí)自動(dòng)打標(biāo)簽會(huì)被跳過(guò)。版本固定release標(biāo)簽會(huì)在鏡像更新后需要顯式拉取docker compose up --pull always -d鎖版本號(hào)則每次升級(jí)只需修改版本并docker compose up -d。結(jié)語(yǔ)極簡(jiǎn)安裝是 Karakeep 在資源受限環(huán)境下的務(wù)實(shí)之選一個(gè)容器、兩個(gè)環(huán)境變量即可跑起完整的書簽管理核心搜索、截圖、AI 打標(biāo)簽等增強(qiáng)能力按需通過(guò)MEILI_ADDR、BROWSER_WEB_URL、OPENAI_API_KEY/OLLAMA_BASE_URL逐步補(bǔ)齊。無(wú)論從極簡(jiǎn)起步還是直接完整部署都建議先通讀 環(huán)境變量配置文檔對(duì)應(yīng)本版本歸檔見 version-v0.29.0 配置章節(jié)并結(jié)合 packages/shared/config.ts 理解每一項(xiàng)配置的真實(shí)作用避免出現(xiàn)配置了卻不生效的困惑。若需要整頁(yè)歸檔、整頁(yè)截圖、推理語(yǔ)言等更多進(jìn)階能力請(qǐng)參考 完整 Docker 安裝指南?！久赓M(fèi)下載鏈接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ho/hoarder創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考