跳轉至

Karakeep_Web

Overview

Karakeep_Web 係 benhoweb 自架嘅書籤、網頁收藏同知識管理服務，部署喺 oracle-cloud 上，並以 docker Compose 管理。佢係 karakeep-web（前稱 Hoarder）生態入面嘅核心網頁應用容器，對外網址為 https://karakeep.benhoweb.com。用家可以透過瀏覽器收藏網頁、文章、連結同筆記，系統會自動擷取內容、建立索引、產生標籤，亦可配合 litellm 做 AI 摘要同自動筆記。

Karakeep_Web 嘅設計目標係「自己資料自己管」：書籤、全文索引同 AI 摘要流程都喺自架環境完成，唔依賴第三方 SaaS。服務以 Oracle Cloud 虛擬機器為宿主，透過 Docker 網絡 cf_network 同其他內部服務互通，並以固定 IP 172.21.0.42 接入，方便反向代理、防火牆規則同服務發現。時區設定為 Asia/Hong_Kong，符合香港用家日常使用。

Architecture

Karakeep_Web 採用多容器架構，主要組件如下：

  • karakeep_web：Karakeep 主應用，使用官方穩定 release 映像 ghcr.io/hoarder-app/hoarder:release，對外提供 Web UI 同 API。
  • karakeep_meili：Meilisearch 搜尋引擎，使用 getmeili/meilisearch:v1.11.1，負責全文搜尋同索引。
  • karakeep_chrome：Headless Chrome 容器，提供 http://karakeep_chrome:9222，用嚟抓取網頁、截圖同解析內容。
  • litellm：litellm 閘道，提供 http://litellm:4000/v1，統一對接免費模型同 DeepSeek 等後端。

網絡流向大致係：用家經 cloudflare 或反向代理進入 cf_network，再連到 karakeep_web。Karakeep_Web 會將搜尋請求送去 karakeep_meili:7700，將網頁抓取請求送去 karakeep_chrome:9222，並將 AI 推論請求送去 litellm:4000。呢種內部連線方式可以繞過 Cloudflare Access 同公開網域，減少延遲同避免不必要的對外暴露。

資料持久化方面，Karakeep 主資料掛載到 /home/opc/karakeep/data:/data。Meilisearch 容器亦掛載系統時區目錄，確保索引同排程時間一致。AI 部分以 OPENAI_BASE_URL 指向 LiteLLM，並用 INFERENCE_TEXT_MODEL 指定免費優先模型，DeepSeek 作為兜底。自動 AI note 功能已於 2026-08-02 重新開啟。

Deployment

部署 Karakeep_Web 前，需要準備 Oracle Cloud VM、已安裝 docker 同 Docker Compose、可用的 cf_network 外部網絡，以及一個包含敏感環境變數嘅 .env 檔案。建議步驟如下：

  1. 建立資料目錄：mkdir -p /home/opc/karakeep/data。
  2. 建立 .env，填入 NEXTAUTH_SECRET、OPENAI_API_KEY、INFERENCE_TEXT_MODEL、INFERENCE_ENABLE_AUTO_SUMMARIZATION 等值。
  3. 將以下 Compose 內容儲存為 docker-compose.yml。
  4. 確認 cf_network 已存在，或先建立對應 Docker network。
  5. 執行 docker compose up -d，再以 docker compose ps 檢查狀態。
services:
  karakeep_web:
    # [關鍵修正 1] 改用官方且保證穩定的 release 版本
    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 (Karakeep)
      - 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}  # 自動 AI note（2026-08-02 開返）

  karakeep_meili:
    # [關鍵修正 3] 強制鎖定相容版本，防禦最新版造成的不可預期崩潰
    image: getmeili/meilisearch:v1.11.1
    container_name: karakeep_meili
    restart: unless-stopped
    volumes:
      - /usr/share/zoneinfo:/usr/share/zoneinfo

注意：上述節錄只包含 karakeep_web 同 karakeep_meili；實際環境仍需定義 karakeep_chrome 同 litellm 服務。另外，Meilisearch 建議補上持久化資料卷，例如 /meili_data，避免重建容器時失去索引。

Configuration

主要環境變數如下：

變數 說明
NEXTAUTH_URL 對外網址，必須同 https://karakeep.benhoweb.com 一致。
NEXTAUTH_SECRET NextAuth 簽章密鑰，建議用 36 字元高強度密碼。
MEILI_ADDR Meilisearch 內部位址，指向 karakeep_meili:7700。
BROWSER_WEB_URL Headless Chrome 位址，指向 karakeep_chrome:9222。
DATA_DIR 容器內資料目錄，一般為 /data。
TZ 時區，設為 Asia/Hong_Kong。
OPENAI_API_KEY LiteLLM virtual key，供 Karakeep 呼叫 AI。
OPENAI_BASE_URL 指向 http://litellm:4000/v1，走內部網絡。
INFERENCE_TEXT_MODEL 文字推論模型，採 free-first 策略。
INFERENCE_ENABLE_AUTO_SUMMARIZATION 控制自動 AI note，2026-08-02 已開啟。

網絡方面，karakeep_web 使用 cf_network 並固定 IP 172.21.0.42。固定 IP 方便其他容器、防火牆或反向代理設定白名單。映像版本方面，Karakeep 主程式用 release 標籤，Meilisearch 則鎖定 v1.11.1，以避免最新版造成不可預期崩潰。所有密鑰應放喺 .env，唔好提交到 Git。

Operations

日常運維指令包括：

  • docker compose ps：檢查容器狀態。
  • docker compose logs -f karakeep_web：追蹤主應用日誌。
  • docker compose pull：拉取新映像。
  • docker compose up -d：套用更新。
  • docker compose restart karakeep_web：重啟單一服務。
  • docker compose down：停止並移除容器。

備份應涵蓋 /home/opc/karakeep/data、Meilisearch 資料目錄（如有掛載）同 .env。更新前建議先備份，並喺測試環境驗證 Meilisearch 版本相容性。若 AI 摘要失敗，可檢查 LiteLLM 日誌、virtual key 同模型名稱；若搜尋異常，先確認 Meilisearch 版本同索引狀態；若網頁抓取失敗，檢查 karakeep_chrome:9222 是否可連線。

FAQ

Karakeep_Web 同 Karakeep 有咩分別？
Karakeep 係整體專案名稱，Karakeep_Web 係本 wiki 指涉嘅自架網頁應用容器。

點解要用 release 映像？
因為官方 release 標籤通常比最新開發版穩定，適合長期運作。

點解 Meilisearch 要鎖 v1.11.1？
避免最新版同 Karakeep 之間出現相容性問題或不可預期崩潰。

點解 OPENAI_BASE_URL 要用內部 LiteLLM？
內部連線可繞過 Cloudflare Access 同公開網域，減少延遲同攻擊面。

自動摘要點運作？
Karakeep_Web 經 LiteLLM 呼叫免費優先模型，失敗時由 DeepSeek 兜底，並按設定自動產生 AI note。

可唔可以唔用 Oracle Cloud？
可以，任何支援 Docker 嘅 Linux 主機都可，但本文以 Oracle Cloud 為例。

Source

Coverage auto (container scan)