Karakeep 旧版容器架构升级指南：从 web/workers/redis 三容器迁移到 All-in-One 单容器-育师

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 界面与 API；
workers容器（镜像ghcr.io/hoarder-app/hoarder-workers）：负责爬虫、AI 打标、搜索索引、视频下载等后台任务；
redis容器（镜像redis:7.2-alpine）：作为任务队列的中间件；
以及至今仍保留的chrome（无头浏览器，用于抓取页面截图）与meilisearch（全文搜索引擎）容器。

新架构下，web 与 workers 的能力被打包进同一个镜像（ghcr.io/karakeep-app/karakeep），由容器内部的进程管理器（s6-overlay）同时拉起 Web 服务与全部后台 Worker，Redis 则被完全移除——任务队列不再需要外部中间件。官方文档同时明确提醒：旧版容器将很快停止支持，因此存量部署应当尽快完成迁移。

迁移前必读：新旧架构对比

在动手之前，先理解新旧 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 # 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:

四步迁移操作指南

根据原文档，从旧架构升级到新容器只需依次完成以下四步：

移除 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_builder（All-in-One 基础层）：打包了 Web 应用（Next.js standalone 输出）、db_migrations（数据库迁移脚本）、apps/workers（Worker 代码），并内置 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_CONTAINERS=true并选择性启用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（爬虫）、inference（AI 推理/打标）、search（搜索索引）、adminMaintenance（管理维护）、video（视频下载）、feed（RSS 订阅刷新）、assetPreprocessing（图片/OCR 预处理）、webhook（Webhook 投递）、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 中进一步核对。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考