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 可以看到一个标准部署至少包含三个相互协作的容器服务镜像职责webghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}Karakeep 主 Web 应用负责 API、Web UI 与数据库读写chromeghcr.io/karakeep-app/karakeep-chrome:releaseHeadless Chrome用于抓取页面内容、执行 JS 与截图meilisearchgetmeili/meilisearch:v1.41.0全文搜索引擎可选但强烈推荐未配置时搜索功能将被禁用问题在于Unraid 本身不原生支持多容器应用Stack它的 Docker 管理界面默认以单个应用 单个容器为粒度。这正是官方文档专门为 Unraid 写出独立安装章节、并给出两条部署路径的原因Docker Compose Manager 插件推荐借助社区插件直接跑官方 compose 文件三个容器作为一个 stack 统一管理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容器名即网络内的主机名持久化存储声明了dataKarakeep 数据库与资产与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_VERSIONrelease NEXTAUTH_SECRETsuper_random_string MEILI_MASTER_KEYanother_random_string NEXTAUTH_URLhttp://localhost:3000逐项说明KARAKEEP_VERSION镜像标签release表示拉取最新稳定版若要精确控制升级节奏可钉死为具体版本号如KARAKEEP_VERSION0.10.0升级时只需改这个值再重新upNEXTAUTH_SECRET用于签名 JWT 会话令牌的随机字符串。在源码 packages/shared/config.ts 中可以看到NEXTAUTH_SECRET未设置时配置校验会直接抛出NEXTAUTH_SECRET is not set因此必填MEILI_MASTER_KEYMeiliSearch 的 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至少配置其一否则自动打标签会被跳过。这一步可选但官方强烈推荐。方式 AOpenAI云端在.env中加入OPENAI_API_KEYkey即可启用自动打标签。关于成本与模型细节可参阅 OpenAI 使用说明。方式 BOllama本地推理如果你希望完全本地化推理官方 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 -dCompose 会自动拉取新镜像使用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主 Web 应用社区维护有对应的论坛支持帖BrowserlessHeadless Chrome 服务用于抓取页面内容Karakeep 官方 compose 并不使用它但它是当时 Unraid 社区里唯一可用的 Headless Chrome 模板因此只能用它MeiliSearch全文搜索引擎可选但强烈推荐不配置则搜索功能被禁用安装完成后关键的手动互联工作集中在 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 的 CDPChrome DevTools ProtocolHTTP 调试端口两者都未配置时日志输出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 为准不同版本可能有差异请以你部署的版本文档为准变量是否必需默认值作用PORT否3000Web 服务监听端口Docker 下不要改应改宿主机端口映射DATA_DIR是未设置持久化数据目录数据库所在地容器内固定为/dataNEXTAUTH_URL是http://localhost:3000服务器对外地址登出等场景的重定向依据NEXTAUTH_SECRET是未设置JWT 签名密钥未设置则启动校验直接失败MEILI_ADDR否未设置MeiliSearch 地址未设置则搜索禁用MEILI_MASTER_KEY生产 开启搜索时未设置MeiliSearch master keyOPENAI_API_KEY/OLLAMA_BASE_URL二选一未设置自动打标签的推理后端两者皆无则跳过打标签INFERENCE_TEXT_MODEL否OpenAI 默认模型文本推理模型使用 Ollama 时必须更换INFERENCE_IMAGE_MODEL否OpenAI 默认视觉模型图像推理模型Ollama 需选支持视觉的模型如llavaINFERENCE_CONTEXT_LENGTH否2048传给推理模型的 token 上限越大质量越好但成本越高INFERENCE_LANG否english生成标签的语言CRAWLER_NUM_WORKERS否1并发抓取任务数CRAWLER_JOB_TIMEOUT_SEC否60单次抓取任务超时LOG_LEVEL否debug日志级别生产建议调为notice或warningDB_WAL_MODE否false开启 SQLite WAL 模式提升性能数据库位于网络盘时勿开启几个值得注意的细节config.ts中signingSecret在NEXTAUTH_SECRET缺失时抛错验证了官方文档必填的结论NEXTAUTH_URL的解析会剥离末尾斜杠.replace(/\/$/, )配置时带不带结尾/均无碍推理相关变量在inference与embedding两个配置块中被引用EMBEDDING_ENABLE_AUTO_INDEXING在默认 OpenAI 配置下会自动启用支撑语义搜索等实验特性见 环境变量配置文档 中的SEMANTIC_SEARCH_ENABLEDconfig.ts还内置了跨变量一致性校验例如启用邮箱验证EMAIL_VERIFICATION_REQUIREDtrue时必须配置 SMTP否则启动校验失败——这类联动约束在排障时值得留意。常见问题与排障思路结合上述配置项与源码Unraid 场景下高频问题可归纳如下能打开界面但无法抓取/无截图检查 Karakeep 容器中BROWSER_WEB_URL或BROWSER_WEBSOCKET_URL是否正确指向浏览器容器。若两者都未配置抓取会静默退化为纯 HTTP 模式见 browser.ts 的日志分支JS 执行与截图全部缺失且日志会出现Running in browserless mode搜索不生效未设置MEILI_ADDR时搜索功能整体禁用另外需确保MEILI_MASTER_KEY在 Karakeep 与 MeiliSearch 两端一致没有自动标签OPENAI_API_KEY与OLLAMA_BASE_URL均未配置或 Ollama 模型未pull、INFERENCE_CONTEXT_LENGTH过小导致推理质量差数据丢失风险Community Apps 方案下手动映射/data与 MeiliSearch 数据目录到 Unraid 持久盘Compose 方案下确保data卷未被误删升级后异常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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考