企业官网建设流程全解析

Karakeep（Hoarder）在 Unraid 上的完整部署指南：Docker Compose 与 Community Apps 两种方式详解

【免费下载链接】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（原 Hoarder，自托管书签收藏应用）部署到 Unraid NAS 上的用户，系统讲解两种官方推荐的安装路径：使用Docker Compose Manager 插件（推荐）与使用Community Apps 应用模板，并深入说明多容器服务的布线原理、必备环境变量以及搜索、AI 自动打标签等可选能力的配置方法。读完本文，你将能够在 Unraid 上独立完成 Karakeep 的安装、配置、搜索接入与日常升级维护。

Karakeep 是一个可自托管的"收藏一切"应用，支持链接、笔记与图片，并提供基于 AI 的自动打标签与全文搜索。在 Unraid 上部署它的核心挑战在于：Karakeep 是一个多容器服务，而 Unraid 默认并不原生支持多容器编排，因此你需要通过插件或应用模板把各个容器"拼装"起来。本文将从这一关键点展开。

一、部署前的架构认知：Karakeep 由哪些服务组成

在动手之前，先理解 Karakeep 的运行时架构，这决定了 Unraid 上所有布线工作的方向。

官方 Docker 部署（参考 docker/docker-compose.yml）由三个服务组成：

• web：Karakeep 主应用容器，镜像为ghcr.io/karakeep-app/karakeep，对外暴露3000端口，负责 Web UI 与 API；
• chrome：headless Chrome 服务，镜像为ghcr.io/karakeep-app/karakeep-chrome，用于抓取网页内容、截图与执行 JavaScript，通过调试端口9222对外提供连接；
• meilisearch：全文搜索引擎，镜像为getmeili/meilisearch:v1.41.0，提供全文搜索与混合搜索能力。

三个服务之间的协作关系是：web通过环境变量MEILI_ADDR连接 MeiliSearch、通过BROWSER_WEB_URL连接 headless Chrome。官方 compose 文件中已经替你做好了这三者之间的网络布线与数据卷（data卷存放数据库与默认资源，meilisearch卷存放索引数据），这也是官方推荐在 Unraid 上直接使用官方 compose 文件的原因。

二、方式一（推荐）：使用 Docker Compose Manager 插件部署

这是官方文档标注为Recommended的部署方式，核心思路是：在 Unraid 上安装 Docker Compose Manager 插件，把官方仓库提供的 docker-compose.yml 直接作为 Stack 使用，从而获得与标准 Docker 部署完全一致的容器编排体验。

1. 安装 Docker Compose Manager 插件

在 Unraid 的Apps（应用）标签页中搜索并安装Docker Compose Manager插件（其官方支持帖位于 Unraid 论坛）。安装完成后，Unraid 界面会出现 "Docker Compose" 管理入口，用于创建和管理 Stack。

2. 创建 Stack 并导入官方 compose 文件

1. 在 Docker Compose Manager 中新建一个 Stack，自定义一个名称（例如karakeep）；
2. 将官方仓库根目录下的 docker/docker-compose.yml 内容完整复制到 Stack 的 compose 编辑器中（也可以先git clone本仓库后直接引用该文件，仓库地址仅用于说明获取方式：git clone https://gitcode.com/GitHub_Trending/ho/hoarder）；
3. 保存 Stack。

官方 compose 文件的关键内容如下（已完整呈现，可直接使用）：

services: web: image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release} restart: unless-stopped volumes: # By default, the data is stored in a docker volume called "data". # If you want to mount a custom directory, change the volume mapping to: # - /path/to/your/directory:/data - data:/data ports: - 3000:3000 env_file: - .env environment: MEILI_ADDR: http://meilisearch:7700 BROWSER_WEB_URL: http://chrome:9222 # OPENAI_API_KEY: ... # 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 # DON'T CHANGE THIS chrome: image: ghcr.io/karakeep-app/karakeep-chrome:release restart: unless-stopped init: true command: - --disable-gpu - --disable-dev-shm-usage - --hide-scrollbars - --disable-blink-features=AutomationControlled - --window-size=1440,900 meilisearch: image: getmeili/meilisearch:v1.41.0 restart: unless-stopped env_file: - .env environment: MEILI_NO_ANALYTICS: "true" volumes: - meilisearch:/meili_data volumes: meilisearch: data:

3. 填充环境变量（关键步骤）

Stack 创建完成后，需要参照 Docker 安装指南 中第 3 步的方法配置环境变量。在 Stack 的.env文件（或 compose 管理界面提供的环境变量区域）中添加如下最小配置：

KARAKEEP_VERSION=release NEXTAUTH_SECRET=super_random_string MEILI_MASTER_KEY=another_random_string NEXTAUTH_URL=http://localhost:3000

各项说明：

生成随机字符串可以使用openssl rand -base64 36（在单独终端执行）。对于MEILI_MASTER_KEY，官方建议使用openssl rand -base64 36 | tr -dc 'A-Za-z0-9'生成纯字母数字的密钥，避免特殊字符带来的配置问题。

注意：每次修改.env文件后，都需要重新执行docker compose up使变更生效。

4. 启动服务并验证

在 Docker Compose Manager 中启动该 Stack（等效于执行docker compose up -d）。启动完成后，访问http://你的NAS地址:3000，看到登录页即表示部署成功。

5.（可选）启用 AI 自动打标签

自动打标签需要配置推理服务，二者至少配置其一：

• OpenAI：在.env中添加OPENAI_API_KEY=<key>，即可启用基于 OpenAI 的自动打标签与自动摘要能力（相关成本说明见 OpenAI 配置说明）；
• 本地推理（Ollama）：设置OLLAMA_BASE_URL指向本地 Ollama API 地址，即可在无外部 API 依赖的情况下完成本地推理，详见 不同 AI 提供方指南。

6.（可选）启用更多能力

完整的可配置项见 环境变量配置文档，常用可选能力包括：整页归档（CRAWLER_FULL_PAGE_ARCHIVE）、整页截图（CRAWLER_FULL_PAGE_SCREENSHOT）、PDF 快照（CRAWLER_STORE_PDF）、视频下载（CRAWLER_VIDEO_DOWNLOAD）、推理语言（INFERENCE_LANG）等。快捷收藏扩展（浏览器扩展与移动端 App）的安装方式见 快速收藏指南。

三、方式二：通过 Community Apps 应用模板安装

1. 背景与适用前提

Community Apps 模板由社区维护（官方文档特别注明"社区维护"字样）。由于 Karakeep 是多容器服务，而 Unraid 的 Community Apps 机制不原生支持多容器编排，因此你需要把各个部件作为独立应用分别安装，再手动把它们"接线"起来。

2. 需要安装的三个服务

官方文档列出的服务总览如下：

3. 手动布线：让三个应用相互通信

安装完成后，需要在 Karakeep 应用的环境变量中手动完成以下接线：

• 连接 MeiliSearch：设置MEILI_ADDR指向 MeiliSearch 容器的地址与端口，例如http://<MeiliSearch容器IP>:7700，同时设置MEILI_MASTER_KEY为安装 MeiliSearch 时配置的主密钥。如果跳过这一步，Karakeep 将禁用搜索功能；
• 连接 Browserless：由于 Browserless 通过 WebSocket 提供调试连接，应使用BROWSER_WEBSOCKET_URL变量，填入 Browserless 提供的 WebSocket 地址（这正是配置文档中对BROWSER_WEBSOCKET_URL的说明："If you want to use browserless, use their websocket address here"，即"若使用 browserless，请在此填入其 websocket 地址"）。作为对照，官方 compose 中连接自建 Chrome 容器时使用的是BROWSER_WEB_URL: http://chrome:9222这一 HTTP 调试地址形式；
• 基础变量：同样需要设置NEXTAUTH_SECRET与NEXTAUTH_URL（见上文变量表）。

从源码看，Karakeep 的爬虫配置中BROWSER_WEB_URL与BROWSER_WEBSOCKET_URL二选一即可（见 packages/shared/config.ts）：前者是浏览器调试控制台的 HTTP 地址，worker 会通过它解析出 WebSocket 地址；后者是直接的 WebSocket 地址。两者都未设置时，worker 将退化为纯 HTTP 请求，跳过截图与 JavaScript 执行。

4. 数据持久化

三个应用各自的数据需要持久化存放：

• Karakeep 应用需挂载一个持久目录到容器的/data（对应DATA_DIR环境变量，此变量在官方 compose 中标注为 "DON'T CHANGE THIS"，如需自定义目录应改卷映射而非该变量）；
• MeiliSearch 需挂载持久目录到/meili_data存放索引数据。

四、关键环境变量速查表（部署必读）

以下为部署与运维最常用的环境变量，完整清单以 环境变量配置文档 为准，全部变量的解析与校验逻辑可在 packages/shared/config.ts 中查看：

从源码实现看（packages/shared/config.ts），所有环境变量在启动时通过 Zod schema 一次性解析并校验，非法取值会导致应用启动失败——例如EMBEDDING_TEXT_MODEL_DIMENSION_OVERRIDE与EMBEDDING_DIMENSIONS不一致时会直接报错拒绝启动。这提醒我们：在 Unraid 上修改环境变量后，务必观察容器日志确认启动成功。

五、搜索与 AI 能力的可选配置

• 全文搜索：启用 MeiliSearch（MEILI_ADDR+MEILI_MASTER_KEY）后即可获得全文搜索。SEARCH_NUM_WORKERS（默认 1）控制搜索索引并发数，高内容量场景可调大；SEARCH_JOB_TIMEOUT_SEC（默认 30）控制索引任务超时；
• 语义/混合搜索：SEMANTIC_SEARCH_ENABLED（默认 true）为实验性功能，需同时启用EMBEDDING_ENABLE_AUTO_INDEXING（默认在使用默认 OpenAI 配置时自动开启）与嵌入模型配置（EMBEDDING_TEXT_MODEL默认text-embedding-3-small，维度EMBEDDING_DIMENSIONS默认 1536）；
• 自动打标签/摘要：配置OPENAI_API_KEY或OLLAMA_BASE_URL后即启用。INFERENCE_ENABLE_AUTO_TAGGING默认 true，INFERENCE_ENABLE_AUTO_SUMMARIZATION默认 false。INFERENCE_CONTEXT_LENGTH（默认 2048）控制送入模型的 token 数，越大标签质量越好但推理成本越高；无 GPU 的 Ollama 场景可调大INFERENCE_JOB_TIMEOUT_SEC（默认 30）避免任务超时；
• OCR：默认使用 Tesseract 从图片提取文字（OCR_LANGS默认eng），也可设置OCR_USE_LLM=true改用已配置的推理模型进行 LLM 式 OCR，复杂图片效果更好。

六、升级与维护

版本策略决定升级方式

升级方式取决于KARAKEEP_VERSION变量的取值：

• 固定版本：修改KARAKEEP_VERSION为新版本号后重新运行docker compose up -d，会自动拉取新镜像；
• 使用release标签：需要强制拉取最新镜像，执行docker compose up --pull always -d。

升级注意事项

• 若你的自定义 compose 文件仍在使用旧的 Alpine Chrome 镜像，请参考 Chrome 镜像迁移指南 迁移到 Karakeep 官方发布的ghcr.io/karakeep-app/karakeep-chrome镜像（迁移不涉及数据变更，无需数据库迁移，只需更新镜像后docker compose pull chrome && docker compose up -d chrome）；
• 若需要升级/迁移 MeiliSearch 版本，参考 故障排查文档 中的相关说明；
• 在 Unraid 上通过 Community Apps 安装时，各应用的升级需分别在各自的应用管理页面完成，并保持三个组件版本之间的兼容性。

七、总结

在 Unraid 上部署 Karakeep 有两条清晰路径：推荐使用 Docker Compose Manager 插件直接复用官方 docker-compose.yml，容器编排、网络与数据卷都由官方维护，体验最接近标准 Docker 部署，只需按 Docker 安装指南 填充环境变量即可；Community Apps 方式则需要分别安装 Karakeep、Browserless、MeiliSearch 三个应用并手动接线（MEILI_ADDR、BROWSER_WEBSOCKET_URL），适合习惯使用 Unraid 原生应用模板、不引入额外插件的用户。无论选择哪种方式，配置的最终落点都是 packages/shared/config.ts 中定义的整套环境变量体系，理解这张变量表，就等于掌握了 Karakeep 在 Unraid 上的一切调优入口。

【免费下载链接】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