Karakeep

Karakeep（前稱 Hoarder）係一套自託管書籤知識庫，專為「稍後閱讀」同「AI 自動摘要」而設。佢由三個容器組成：Web 主服務、Meilisearch 全文檢索、Chrome headless 預覽。透過 LiteLLM 統一對接多個 LLM provider，以「free-first」策略降低摘要成本。

概述

Karakeep 將收藏嘅網頁、文章、影片同筆記統一存放，並以 Meilisearch 提供高速全文檢索。佢嘅最大特色係支援自動 AI 摘要：用戶只需儲存連結，系統就會透過 LiteLLM 調用預設嘅 LLM，產生精要內容，幫你快速重溫。部署採用 Docker Compose，三個容器固定 IP 喺 cf_network 內網，經 Cloudflare Tunnel 公開訪問，無需開任何連接埠畀外界。

架構

• karakeep_web：核心應用，負責 API、用戶介面、與數據庫及 Meilisearch 通訊。使用官方 ghcr.io/hoarder-app/hoarder:release 映像，確保版本穩定。所有 metadata 同設定儲存於 /data 目錄（實際對應宿主機 /home/opc/karakeep/data）。
• karakeep_meili：全文檢索引擎，容器名 karakeep_meili，對應 Web 容器內嘅 MEILI_ADDR。鎖定 v1.11.1，避免最新版引入未知崩潰。數據持久化於 /meili_data。
• karakeep_chrome：Headless Chrome，用嚟抓取網頁預覽圖同正文內容。只對內網開放 9222 除錯埠，Web 容器透過 BROWSER_WEB_URL 連接。

三個容器都接入外部 cf_network 網絡，並設定固定 IPv4，方便 Cloudflare Tunnel 或其他內部服務精準路由。

部署（Docker Compose 片段）

以下係精簡可用嘅 docker-compose.yml。敏感值全部用環境變數 ${VAR} 代替，部署前請先喺 .env 檔案定義。

services:
  karakeep_web:
    image: ghcr.io/hoarder-app/hoarder:release
    container_name: karakeep_web
    restart: unless-stopped
    volumes:
      - /home/opc/karakeep/data:/data
    networks:
      cf_network:
        ipv4_address: 172.21.0.42
    environment:
      - NEXTAUTH_URL=https://karakeep.benhoweb.com
      - NEXTAUTH_SECRET=${NEXTAUTH_SECRET}  # 必填，36 字元隨機密碼
      - MEILI_ADDR=http://karakeep_meili:7700
      - BROWSER_WEB_URL=http://karakeep_chrome:9222
      - DATA_DIR=/data
      - TZ=Asia/Hong_Kong
      # LiteLLM 對接（free-first + DeepSeek 兜底）
      - OPENAI_API_KEY=${OPENAI_API_KEY}      # LiteLLM virtual key
      - OPENAI_BASE_URL=http://litellm:4000/v1 # 內部連線，唔經 CF Access
      - INFERENCE_TEXT_MODEL=${INFERENCE_TEXT_MODEL}        # free-first 模型
      - INFERENCE_ENABLE_AUTO_SUMMARIZATION=${INFERENCE_ENABLE_AUTO_SUMMARIZATION} # 開返自動摘要

  karakeep_meili:
    image: getmeili/meilisearch:v1.11.1
    container_name: karakeep_meili
    restart: unless-stopped
    volumes:
      - /usr/share/zoneinfo:/usr/share/zoneinfo:ro
      - /home/opc/karakeep/meili:/meili_data
    networks:
      cf_network:
        ipv4_address: 172.21.0.18
    environment:
      - TZ=Asia/Hong_Kong
      - MEILI_NO_ANALYTICS=true
      # - MEILI_MASTER_KEY=${MEILI_MASTER_KEY} # 建議設定，36 字元密碼

  karakeep_chrome:
    image: gcr.io/zenika-hub/alpine-chrome:124
    container_name: karakeep_chrome
    restart: unless-stopped
    volumes:
      - /usr/share/zoneinfo:/usr/share/zoneinfo:ro
    environment:
      - TZ=Asia/Hong_Kong
    command:
      - --no-sandbox
      - --disable-gpu
      - --disable-dev-shm-usage
      - --remote-debugging-address=0.0.0.0
      - --remote-debugging-port=9222
      - --hide-scrollbars
    networks:
      cf_network:
        ipv4_address: 172.21.0.12

networks:
  cf_network:
    external: true

部署前先建立網絡：docker network create cf_network，再確認 .env 有齊 NEXTAUTH_SECRET、OPENAI_API_KEY、INFERENCE_TEXT_MODEL、INFERENCE_ENABLE_AUTO_SUMMARIZATION。之後執行 docker compose up -d 即可。

配置與環境變數

• NEXTAUTH_URL 必須同公開網域一致，否則登入回調會出錯。
• NEXTAUTH_SECRET：登入加密用，務必用 openssl rand -hex 32 生成，並唔好同 MEILI_MASTER_KEY 共用。
• MEILI_ADDR：Web 容器內訪問 Meilisearch 嘅地址，直接用容器名稱 karakeep_meili:7700。若 Meilisearch 啟用 master key，必須同時喺 Web 環境變數提供 MEILI_MASTER_KEY（官方支援，但片段中冇列出，需要時加入）。
• BROWSER_WEB_URL 指向 Chrome 除錯埠，避免 expose 到宿主機。
• OPENAI_BASE_URL 用 http://litellm:4000/v1，表示經 LiteLLM 內部路由，唔經 Cloudflare Access，減低延遲。LiteLLM 容器必須同喺 cf_network，並有對應 virtual key。
• INFERENCE_TEXT_MODEL 控制摘要所用模型，可以係 gpt-4o-mini、deepseek-chat 或任何 LiteLLM 支援嘅型號，按 free-first 原則揀選。

維運與監控

日常維運要留意以下幾點：

• 日誌：用 docker compose logs -f karakeep_web 查看主服務。若 LiteLLM 出錯，檢查 litellm 容器日誌。
• 健康檢查：Meilisearch 健康端點為 http://karakeep_meili:7700/health，可喺 Web 容器內用 curl 測試。Chrome 可檢查 http://karakeep_chrome:9222/json/version。
• 備份：備份 /home/opc/karakeep/data 同 /home/opc/karakeep/meili。前者係 SQLite 數據庫（Karakeep 用 SQLite 儲存收藏記錄），後者係 Meilisearch 索引。建議每日 tar 壓縮，並同步至異地儲存。
• 排障命令：
• 確認三個容器都運行：docker compose ps。
• 測試內網連線：docker exec karakeep_web curl http://karakeep_meili:7700/health。
• 重建 Meilisearch 索引：docker compose restart karakeep_meili 後，由 Web 自動重新索引（需要一段時間）。
• 若 Chrome 崩潰，docker compose restart karakeep_chrome 即可。
• 網絡注意：固定 IP 必須喺 cf_network 子網範圍內（例如 172.21.0.0/24），但唔好同其他服務衝突。若 CIDR 有出入，改返對應 IP。

常見問題

問：自動摘要一直冇反應？
檢查 INFERENCE_ENABLE_AUTO_SUMMARIZATION 係咪設為 true，以及 OPENAI_BASE_URL 能否連通 LiteLLM。再睇 karakeep_web 日誌有冇 model 相關錯誤。

問：Meilisearch 容器成日重啟？
可能係版本太新或數據壞咗。刪除 /home/opc/karakeep/meili 內數據重嚟（會失去搜尋索引，但收藏記錄仍喺 SQLite），或確認鎖定 v1.11.1。

問：登入後跳返去 localhost？
必定係 NEXTAUTH_URL 未設定或錯咗。要同 https://karakeep.benhoweb.com 完全一致。

問：Chrome 抓取頁面失敗？
確認 BROWSER_WEB_URL 有冇用 http://，同埋 Chrome 容器有冇正常啟動。可以試下 docker exec karakeep_chrome wget -qO- http://localhost:9222/json/version。

相關鏈接

• docker
• litellm
• cloudflare-tunnel
• Meilisearch
• oracle-cloud
• 書籤管理