企业官网建设流程全解析

Karakeep 在 Unraid 上的完整部署指南：Docker Compose Manager 与 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 官方文档中 Unraid 安装章节 为核心骨架，系统讲解在 Unraid（一款基于 Slackware 的 NAS 操作系统）上部署自托管书签应用 Karakeep 的两种主流路径：Docker Compose Manager 插件（官方推荐）与Community Apps 社区模板。读完本文，你将掌握 Unraid 上 Karakeep 多容器服务的完整搭建流程、环境变量配置、AI 自动打标签的接入方式，以及 Headless Chrome 与 MeiliSearch 组件的互联原理，能够根据自己的网络环境选择最合适的部署方案并独立完成排障。

为什么 Unraid 上部署 Karakeep 需要专门说明

Karakeep 是一个"收藏一切"的自托管应用（链接、笔记与图片），并内置基于 AI 的自动打标签与全文搜索能力。从官方 docker-compose.yml 可以看到，一个标准部署至少包含三个相互协作的容器：

问题在于：Unraid 本身不原生支持多容器应用（Stack），它的 Docker 管理界面默认以"单个应用 = 单个容器"为粒度。这正是官方文档专门为 Unraid 写出独立安装章节、并给出两条部署路径的原因：

1. Docker Compose Manager 插件（推荐）：借助社区插件直接跑官方 compose 文件，三个容器作为一个 stack 统一管理；
2. Community Apps 社区模板：把三个服务拆成三个独立应用，手动逐个安装并互联。

无论走哪条路，Karakeep 的三个核心服务缺一不可（MeiliSearch 除外，但缺失会直接导致搜索不可用），理解这一点是后续所有配置的前提。

路径一（推荐）：使用 Docker Compose Manager 插件部署

这是官方文档明确标注的Recommended方案，也是与官方 Docker 部署体验最接近的方式。核心思路：Unraid 通过社区插件获得运行docker compose的能力，然后直接使用仓库中维护的官方 compose 文件。

第 1 步：安装 Docker Compose Manager 插件

在 Unraid 的Apps（应用）页面搜索并安装Docker Compose Manager插件。该插件为 Unraid 提供了 Compose 栈（Stack）的创建、启动、停止与更新管理界面，安装完成后在 Docker 页面会出现对应的 Compose 管理入口。

第 2 步：基于官方 compose 文件创建 Stack

官方 compose 文件位于仓库的 docker/docker-compose.yml。在 Docker Compose Manager 中新建 Stack 时，将官方 compose 文件的内容粘贴进去，或直接填写该文件的 URL 让插件拉取。官方 compose 文件已经完成了三件事：

• 服务间互联：web容器通过MEILI_ADDR: http://meilisearch:7700与BROWSER_WEB_URL: http://chrome:9222分别指向 MeiliSearch 与 Headless Chrome，容器名即网络内的主机名；
• 持久化存储：声明了data（Karakeep 数据库与资产）与meilisearch（搜索引擎索引）两个命名卷；
• 生产参数预设：Chrome 容器通过command传入--disable-gpu、--disable-dev-shm-usage、--hide-scrollbars等启动参数，MeiliSearch 关闭了遥测（MEILI_NO_ANALYTICS: "true"）。

# docker/docker-compose.yml（关键片段） services: web: image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release} restart: unless-stopped volumes: - data:/data # 数据默认存于名为 "data" 的 Docker 卷 ports: - 3000:3000 env_file: - .env environment: MEILI_ADDR: http://meilisearch:7700 BROWSER_WEB_URL: http://chrome:9222 DATA_DIR: /data # 官方注释：几乎不要修改此值 chrome: image: ghcr.io/karakeep-app/karakeep-chrome:release init: true meilisearch: image: getmeili/meilisearch:v1.41.0 environment: MEILI_NO_ANALYTICS: "true" volumes: - meilisearch:/meili_data volumes: meilisearch: data:

如果你希望把数据落到 Unraid 的数组盘或缓存盘而非 Docker 卷，可参考文件内的注释将卷映射改为- /mnt/user/appdata/karakeep:/data这类宿主机路径（对应开发版 compose 中${DATA_DIR:-/data}的挂载模式）。

第 3 步：填充环境变量（Stack 的 .env）

创建 Stack 后，还需要配置一组环境变量，其要求与 官方 Docker 安装文档 完全一致。官方 compose 通过env_file: .env读取变量，因此需要在 Stack 目录下创建.env文件，最小可用配置如下：

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

逐项说明：

• KARAKEEP_VERSION：镜像标签，release表示拉取最新稳定版；若要精确控制升级节奏，可钉死为具体版本号（如KARAKEEP_VERSION=0.10.0），升级时只需改这个值再重新up；
• NEXTAUTH_SECRET：用于签名 JWT 会话令牌的随机字符串。在源码 packages/shared/config.ts 中可以看到，NEXTAUTH_SECRET未设置时配置校验会直接抛出"NEXTAUTH_SECRET is not set"，因此必填；
• MEILI_MASTER_KEY：MeiliSearch 的 master key。生产环境（非开发模式）且开启搜索时必需，用于保护搜索索引的读写权限；
• NEXTAUTH_URL：应指向你的服务器对外地址。未正确设置时应用仍能运行，但登出等场景会被重定向到错误地址。

两个随机字符串可以用openssl rand -base64 36在独立终端中生成；MEILI_MASTER_KEY也可以进一步过滤为字母数字：openssl rand -base64 36 | tr -dc 'A-Za-z0-9'。务必修改默认的随机串，不要直接使用示例值。

注意：每次修改.env后，都需要重新执行docker compose up（在 Docker Compose Manager 中即"重新创建/Recreate"该 Stack），改动才会生效。

第 4 步：接入 AI 推理，启用自动打标签

Karakeep 的自动打标签依赖推理服务。源码 packages/shared/config.ts 中inference.isConfigured的判断条件是!!val.OPENAI_API_KEY || !!val.OLLAMA_BASE_URL——即OPENAI_API_KEY与OLLAMA_BASE_URL至少配置其一，否则自动打标签会被跳过。这一步可选但官方强烈推荐。

方式 A：OpenAI（云端）

在.env中加入：

OPENAI_API_KEY=<key>

即可启用自动打标签。关于成本与模型细节，可参阅 OpenAI 使用说明。

方式 B：Ollama（本地推理）

如果你希望完全本地化推理，官方 Docker 文档给出了完整指引：

• 确保 Ollama 服务正在运行；
• 设置OLLAMA_BASE_URL为 Ollama API 的地址；
• 设置INFERENCE_TEXT_MODEL为文本推理模型（例如llama3.1）；
• 设置INFERENCE_IMAGE_MODEL为图像推理模型（例如llava，需支持视觉 API）；
• 提前用ollama pull拉取所需模型；
• 按需调大INFERENCE_CONTEXT_LENGTH——默认值较小，值越大打标签质量越好，但推理成本（Ollama 侧为资源开销）也越高。

需要说明的是，打标签质量取决于所选模型的水平，这一结论同样适用于 OpenAI 方案。

第 5 步：启动并验证

在 Docker Compose Manager 中启动 Stack（等价于docker compose up -d）。启动完成后，浏览器访问http://<Unraid-IP>:3000，应能看到 Karakeep 的登录/注册页面。首次登录后即可创建书签，系统会触发后台抓取与自动打标签任务。

第 6 步：更新与升级

更新策略取决于KARAKEEP_VERSION的设置方式：

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

若涉及 MeiliSearch 的版本升级/迁移，请参考 故障排查文档。

第 7 步（可选）：启用更多能力

完整的环境变量清单见 环境变量配置文档，可按需开启整页归档（CRAWLER_FULL_PAGE_ARCHIVE）、整页截图（CRAWLER_FULL_PAGE_SCREENSHOT）、推理语言（INFERENCE_LANG）等功能。此外，快速分享文档 介绍了如何安装移动端 App 与浏览器扩展，借助它们可以更快地收藏内容。

路径二：使用 Community Apps 手动组装多容器

如果不想引入 Compose 插件，也可以走 Unraid 传统的 Community Apps 路线。官方文档特别注明：该社区应用模板由社区维护。由于 Karakeep 是多容器服务而 Unraid 不原生支持，需要将各组件作为独立应用安装，再手动互联。需要安装的高层服务概览如下：

安装完成后，关键的"手动互联"工作集中在 Karakeep 应用的容器环境变量上：

• 在 Karakeep 容器中设置MEILI_ADDR（指向 MeiliSearch 容器，如http://<meilisearch-容器IP或主机名>:7700）与MEILI_MASTER_KEY（与 MeiliSearch 容器中设置的 master key 保持一致）；
• 将抓取浏览器指向 Browserless。根据 环境变量配置文档 的说明，BROWSER_WEB_URL用于"浏览器的 HTTP 调试地址"，而BROWSER_WEBSOCKET_URL是"浏览器调试控制台的 WebSocket 地址，若使用 browserless 请使用其 WebSocket 地址"。因此对于 Browserless 社区模板，应设置BROWSER_WEBSOCKET_URL；
• 数据目录：将 Karakeep 容器内的/data（即DATA_DIR）映射到 Unraid 的 appdata 目录，保证数据库与资产持久化；
• 若配置了 AI 推理（OPENAI_API_KEY或OLLAMA_BASE_URL二选一），自动打标签才会工作。

从源码理解两种浏览器连接方式

为什么官方 compose 用BROWSER_WEB_URL而 Community Apps 场景要用BROWSER_WEBSOCKET_URL？看抓取模块的实现即可明白。在 apps/workers/workers/crawler/browser.ts 的startBrowserInstance()中：

• 若配置了BROWSER_WEBSOCKET_URL，走chromium.connect(websocketUrl)——直接连接浏览器调试端点的 WebSocket 地址（Browserless 对外暴露的正是这种端点）；
• 否则若配置了BROWSER_WEB_URL，先对该地址做 DNS 解析，再通过chromium.connectOverCDP(httpUrl)连接——官方 compose 中的http://chrome:9222就是 Chrome 的 CDP（Chrome DevTools Protocol）HTTP 调试端口；
• 两者都未配置时，日志输出Running in browserless mode，抓取退化为纯 HTTP 请求，会跳过 JS 执行与截图能力。

抓取任务的整体调度在 apps/workers/workers/crawlerWorker.ts 中，其并发数与超时分别取自CRAWLER_NUM_WORKERS（默认 1）与CRAWLER_JOB_TIMEOUT_SEC（默认 60）。默认单并发是为了避免抓取消耗过多资源——在 Unraid 这类 NAS 硬件上，保持默认值通常是更稳妥的选择。

环境变量全景与源码级解析

Unraid 部署的核心工作量集中在环境变量上。所有变量都在 packages/shared/config.ts 中通过 Zod schema 统一定义、解析与校验（serverConfigSchema.parse(process.env)），这意味着任何非法取值都会在启动时被拦截，而非运行中静默失效。下表列出部署阶段最常涉及的变量（默认值与说明以当前仓库 环境变量配置文档 与 config.ts 为准，不同版本可能有差异，请以你部署的版本文档为准）：

几个值得注意的细节：

• config.ts中signingSecret在NEXTAUTH_SECRET缺失时抛错，验证了官方文档"必填"的结论；
• NEXTAUTH_URL的解析会剥离末尾斜杠（.replace(/\/+$/, "")），配置时带不带结尾/均无碍；
• 推理相关变量在inference与embedding两个配置块中被引用，EMBEDDING_ENABLE_AUTO_INDEXING在默认 OpenAI 配置下会自动启用，支撑语义搜索等实验特性（见 环境变量配置文档 中的SEMANTIC_SEARCH_ENABLED）；
• config.ts还内置了跨变量一致性校验，例如启用邮箱验证（EMAIL_VERIFICATION_REQUIRED=true）时必须配置 SMTP，否则启动校验失败——这类联动约束在排障时值得留意。

常见问题与排障思路

结合上述配置项与源码，Unraid 场景下高频问题可归纳如下：

1. 能打开界面但无法抓取/无截图：检查 Karakeep 容器中BROWSER_WEB_URL或BROWSER_WEBSOCKET_URL是否正确指向浏览器容器。若两者都未配置，抓取会静默退化为纯 HTTP 模式（见 browser.ts 的日志分支），JS 执行与截图全部缺失，且日志会出现Running in browserless mode；
2. 搜索不生效：未设置MEILI_ADDR时搜索功能整体禁用；另外需确保MEILI_MASTER_KEY在 Karakeep 与 MeiliSearch 两端一致；
3. 没有自动标签：OPENAI_API_KEY与OLLAMA_BASE_URL均未配置，或 Ollama 模型未pull、INFERENCE_CONTEXT_LENGTH过小导致推理质量差；
4. 数据丢失风险：Community Apps 方案下手动映射/data与 MeiliSearch 数据目录到 Unraid 持久盘；Compose 方案下确保data卷未被误删；
5. 升级后异常：MeiliSearch 大版本迁移请参照 故障排查文档 的指引执行。

小结

在 Unraid 上部署 Karakeep 的两条路径各有适用场景：追求与官方部署一致、管理成本最低，优先选择Docker Compose Manager 插件，直接复用 docker/docker-compose.yml 并补齐.env变量即可；希望沿用 Unraid 社区应用习惯、且能接受手动互联成本，则走Community Apps路线，分别安装 Karakeep、Browserless 与 MeiliSearch 三个应用并正确设置BROWSER_WEBSOCKET_URL、MEILI_ADDR等互联变量。无论哪条路径，都需确保环境变量满足源码层的启动校验（尤其是NEXTAUTH_SECRET与DATA_DIR），并至少配置一种 AI 推理后端以启用自动打标签。掌握这些要点后，一个具备全文搜索与 AI 打标签能力的自托管收藏中心即可在 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