Karakeep 旧版容器架构升级指南从 web/workers/redis 三容器迁移到 All-in-One 单容器【免费下载链接】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旧版 Docker 部署的用户讲解其 0.16 版本引入的容器架构变革Web 与 Worker 合并为单个容器并彻底移除对 Redis 的依赖。读完本文你将掌握旧容器架构与新 All-in-One 架构的差异、四步无损迁移的操作流程、以及迁移过程中环境变量与数据卷的处理细节并了解这一架构变化在源码与镜像构建层面的具体实现。背景0.16 版本为何要合并容器Karakeep此前名为 Hoarder在 0.16 版本对 Docker 部署方式做了一次重大精简将原先独立的 web 容器与 workers 容器合并为单个 All-in-One 容器同时移除了对 Redis 容器的依赖。旧架构下一条完整的部署链路通常包含以下容器web容器镜像ghcr.io/hoarder-app/hoarder-web提供 Web 界面与 APIworkers容器镜像ghcr.io/hoarder-app/hoarder-workers负责爬虫、AI 打标、搜索索引、视频下载等后台任务redis容器镜像redis:7.2-alpine作为任务队列的中间件以及至今仍保留的chrome无头浏览器用于抓取页面截图与meilisearch全文搜索引擎容器。新架构下web 与 workers 的能力被打包进同一个镜像ghcr.io/karakeep-app/karakeep由容器内部的进程管理器s6-overlay同时拉起 Web 服务与全部后台 WorkerRedis 则被完全移除——任务队列不再需要外部中间件。官方文档同时明确提醒旧版容器将很快停止支持因此存量部署应当尽快完成迁移。迁移前必读新旧架构对比在动手之前先理解新旧 compose 文件的差异。旧架构的docker-compose.yml大致如下关键差异已在文档的 diff 中给出version: 3.8 services: web: image: ghcr.io/hoarder-app/hoarder-web:${KARAKEEP_VERSION:-release} restart: unless-stopped volumes: - data:/data ports: - 3000:3000 env_file: - .env environment: REDIS_HOST: redis MEILI_ADDR: http://meilisearch:7700 DATA_DIR: /data redis: image: redis:7.2-alpine restart: unless-stopped volumes: - redis:/data chrome: image: gcr.io/zenika-hub/alpine-chrome:123 restart: unless-stopped meilisearch: image: getmeili/meilisearch:v1.41.0 restart: unless-stopped env_file: - .env environment: MEILI_NO_ANALYTICS: true volumes: - meilisearch:/meili_data workers: image: ghcr.io/hoarder-app/hoarder-workers:${KARAKEEP_VERSION:-release} restart: unless-stopped volumes: - data:/data env_file: - .env environment: REDIS_HOST: redis MEILI_ADDR: http://meilisearch:7700 BROWSER_WEB_URL: http://chrome:9222 DATA_DIR: /data # OPENAI_API_KEY: ... depends_on: web: condition: service_started而当前仓库中的 docker/docker-compose.yml 已经完整呈现了新架构只剩web、chrome、meilisearch三个服务workers与redis均已消失镜像名也统一为ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}services: web: image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release} restart: unless-stopped volumes: - data:/data ports: - 3000:3000 env_file: - .env environment: MEILI_ADDR: http://meilisearch:7700 BROWSER_WEB_URL: http://chrome:9222 # OPENAI_API_KEY: ... DATA_DIR: /data # DONT 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-featuresAutomationControlled - --window-size1440,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:四步迁移操作指南根据原文档从旧架构升级到新容器只需依次完成以下四步移除 redis 容器及其数据卷如果配置了数据卷的话将原本只配置在workers容器上的环境变量迁移到web容器上删除workers容器将 web 容器镜像从hoarder-app/hoarder-web改名为hoarder-app/hoarder。文档同时给出了这份完整的 diff可以直接对照修改自己的 compose 文件diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index cdfc908..6297563 100644 --- a/docker/docker-compose.yml b/docker/docker-compose.yml -1,7 1,7 version: 3.8 services: web: - image: ghcr.io/hoarder-app/hoarder-web:${KARAKEEP_VERSION:-release} image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release} restart: unless-stopped volumes: - data:/data -10,14 10,10 services: env_file: - .env environment: - REDIS_HOST: redis MEILI_ADDR: http://meilisearch:7700 BROWSER_WEB_URL: http://chrome:9222 # OPENAI_API_KEY: ... DATA_DIR: /data - redis: - image: redis:7.2-alpine - restart: unless-stopped - volumes: - - redis:/data chrome: image: gcr.io/zenika-hub/alpine-chrome:123 restart: unless-stopped -37,24 33,7 services: MEILI_NO_ANALYTICS: true volumes: - meilisearch:/meili_data - workers: - image: ghcr.io/hoarder-app/hoarder-workers:${KARAKEEP_VERSION:-release} - restart: unless-stopped - volumes: - - data:/data - env_file: - - .env - environment: - REDIS_HOST: redis - MEILI_ADDR: http://meilisearch:7700 - BROWSER_WEB_URL: http://chrome:9222 - DATA_DIR: /data - # OPENAI_API_KEY: ... - depends_on: - web: - condition: service_started volumes: - redis: meilisearch: data:注意这份 diff 还隐含了镜像源的迁移——ghcr.io/hoarder-app/hoarder-web变为ghcr.io/karakeep-app/karakeep。这与 Karakeep 更名Hoarder rebranding保持了一致仓库中 08-hoarder-to-karakeep-migration.md 同样说明由于 GitHub 的限制更名后旧镜像可能不再获得新更新因此需要将 compose 中的镜像指向新的ghcr.io/karakeep-app/karakeep镜像如果是裸机安装则执行bash karakeep-linux.sh migrate自动迁移。环境变量迁移要点迁移中最容易出错的环节是第 2 步把 workers 容器专属的环境变量搬进 web 容器。根据 diff 与 03-configuration/01-environment-variables.md 中的配置说明需要特别关注以下几类变量变量迁移说明BROWSER_WEB_URL原本只在 workers 容器中配置用于让爬虫连接无头浏览器如http://chrome:9222。合并后必须迁移到 web 容器否则抓取功能会退化为纯 HTTP 请求跳过截图与 JavaScript 执行OPENAI_API_KEY原本常配在 workers 容器上用于 AI 自动打标合并后需迁移到 web 容器REDIS_HOST旧架构中 web 与 workers 都依赖它新架构已不再需要 Redis直接删除MEILI_ADDR、DATA_DIR两个容器原本都有合并后保留一份即可DATA_DIR官方建议不要修改其值/data如需自定义数据目录应改 volume 映射从源码层面看REDIS_HOST这类旧变量的彻底移除是有据可查的当前 packages/shared/config.ts 中仅保留了REDIS_URL用于可选的外部 Redis 配置任务队列已不再需要本地 Redis 中间件而BROWSER_WEB_URL则被解析为crawler.browserWebUrl供抓取链路使用。也就是说迁移后 redis 容器的删除不会影响任何核心功能。合并后的镜像内部单容器如何同时跑 Web 与 Workers理解新镜像的内部结构有助于在迁移后排查问题。仓库中的 docker/Dockerfile 清晰地展示了镜像构建的多阶段设计aio_builderAll-in-One 基础层打包了 Web 应用Next.js standalone 输出、db_migrations数据库迁移脚本、apps/workersWorker 代码并内置 monolith整页归档工具、yt-dlp视频下载、ffmpeg、ghostscript、graphicsmagick 等运行依赖通过 s6-overlay 作为进程管理器ENTRYPOINT [/init]启动aio最终 All-in-One 镜像在aio_builder之上启用init-db-migration、svc-web、svc-workers三个服务即启动时依次执行数据库迁移、拉起 Web 服务、拉起全部后台 Worker并带有/api/health健康检查web/workers镜像遗留兼容通过设置USING_LEGACY_SEPARATE_CONTAINERStrue并选择性启用svc-web或svc-workers仍然提供旧的分容器部署方式——这正对应了packages/shared/config.ts中的USING_LEGACY_SEPARATE_CONTAINERS配置项注释明确写着 A flag to detect if the user is running in the old separete containers setup。s6-overlay 的服务脚本同样直观svc-web/run 执行node server.js启动 Next.js 服务svc-workers/run 执行node dist/index.js启动 Worker 进程两个服务都依赖init-db-migration保证数据库迁移先于服务启动完成。而 Worker 侧的能力边界可以参考 apps/workers/index.ts 中的workerBuilders映射它列出了单容器内会同时启动的全部后台任务crawler爬虫、inferenceAI 推理/打标、search搜索索引、adminMaintenance管理维护、video视频下载、feedRSS 订阅刷新、assetPreprocessing图片/OCR 预处理、webhookWebhook 投递、ruleEngine自动化规则、backup定时备份外加import导入轮询。这些任务过去分散在独立的 workers 容器中现在统一由同一个进程拉起如果希望按需裁剪可以在新容器上使用WORKERS_ENABLED_WORKERS/WORKERS_DISABLED_WORKERS环境变量逗号分隔的 Worker 名称列表来控制启用或禁用范围。数据与启动顺序迁移不会丢数据迁移最关心的是数据安全。新旧架构中data数据卷默认挂载到容器的/data目录SQLite 数据库与默认资产存储均位于此始终由web服务挂载新架构的 compose 中依然保留volumes: - data:/data因此data与meilisearch两个数据卷在迁移后原样保留书签、资产与搜索索引不会丢失。唯一需要清理的是redis卷——它只存放任务队列的瞬时状态删除不会影响持久数据。另外需要留意启动顺序的变化旧架构中 workers 通过depends_on: web: condition: service_started保证 Web 先启动新架构通过 s6-overlay 的服务依赖svc-web、svc-workers均依赖init-db-migration确保数据库迁移先执行完毕再并发启动 Web 与 Workers避免了旧架构下Worker 先跑但迁移未完成的竞态问题。迁移后的验证清单完成 compose 文件修改后建议按以下顺序执行并验证备份迁移前先备份data卷例如docker run --rm -v karakeep_data:/data -v $(pwd):/backup alpine tar czf /backup/karakeep-backup.tar.gz -C /data .并确认.env文件中的KARAKEEP_VERSION指向的目标版本可用拉起新栈docker compose up -d观察docker compose ps确认只有web、chrome、meilisearch三个服务处于运行状态redis与workers已消失清理旧资源确认新栈正常后删除旧的 redis 容器与 redis 卷如docker compose down后再按需清理遗留容器健康检查访问 Web 界面确认登录、书签列表、搜索均正常在管理面板确认后台 Worker爬虫抓取新链接、AI 自动打标、RSS 刷新等实际工作而不是仅仅容器起来了。附关于版本号与镜像名的注意事项compose 中使用的版本变量是${KARAKEEP_VERSION:-release}缺省时拉取release标签即最新的稳定发布版若你仍在使用旧的HOARDER_VERSION变量请同步将其重命名为KARAKEEP_VERSION或保持镜像名与.env中变量名一致否则 compose 会因变量未定义而退回默认的release标签更名期间Hoarder → Karakeep旧的ghcr.io/hoarder-app/*镜像可能不再接收新更新务必让镜像地址指向ghcr.io/karakeep-app/karakeep。总结Karakeep 0.16 的容器合并是一次典型的化繁为简通过 All-in-One 镜像将 Web、Workers 与数据库迁移统一进单个容器并顺势移除 Redis 中间件显著降低了自托管者的运维负担。整个迁移过程只需四步——删 redis、搬环境变量、删 workers、改镜像名——且data与meilisearch卷原样保留数据零丢失。本文涉及的当前版本 compose 配置、Dockerfile 多阶段构建、s6-overlay 服务编排与 Worker 清单均可直接在仓库的 docker/docker-compose.yml、docker/Dockerfile、docker/root/etc/s6-overlay 与 apps/workers/index.ts 中进一步核对。【免费下载链接】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），仅供参考