Karakeep 旧版容器升级指南：从多容器架构迁移到 All-in-One 单体容器-开发者社区

Karakeep 旧版容器升级指南：从多容器架构迁移到 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

文章内容

本文基于 docs/versioned_docs/version-v0.30.0/06-administration/07-legacy-container-upgrade.md 编写。

背景：0.16 版本的多容器到单体容器架构演进

Karakeep 在 0.16 版本完成了一次重要的部署架构整合：将原来的web容器与workers容器合并为单一容器，同时移除了对 Redis 容器的依赖。这一变更对自托管用户的运维方式有直接影响，本文完整还原官方升级步骤，并结合当前仓库中的 docker/docker-compose.yml 与 docker/Dockerfile 等源码佐证其底层原理。

一、架构变更概览：旧版 vs 新版

旧版（0.16 之前）容器拓扑（以 docker/docker-compose.yml 中被移除的片段为准）：

web容器：运行 Web 界面与 API，镜像为ghcr.io/hoarder-app/hoarder-web。
workers容器：运行后台任务（爬虫、推理、导入等），镜像为ghcr.io/hoarder-app/hoarder-workers，并通过depends_on: web保证启动顺序。
redis容器：提供队列存储，镜像redis:7.2-alpine，挂载redis:/data数据卷。
chrome与meilisearch容器保持不变。

新版（0.16 之后）容器拓扑：

仅保留web容器，镜像改为ghcr.io/karakeep-app/karakeep。
web容器内部通过s6-overlay 进程管理器同时启动 Web 服务与 Worker 进程，实现单容器一体化运行。
彻底移除redis容器及其数据卷，队列功能由内置的 SQLite 或其他持久化机制替代（可参见 docker/Dockerfile 中aio构建阶段对svc-web、svc-workers两个服务的启用）。
chrome（浏览器抓取）与meilisearch（全文搜索）仍作为独立容器保留。

二、官方升级步骤详解

升级共 4 步，核心是将原本分散在 3 个容器中的职责收敛到 1 个容器：

移除 Redis 容器及其数据卷：删除 compose 文件中的redis服务定义与volumes下的redis卷声明。若你曾为 Redis 配置过持久化卷，一并删除，新版不再需要它。
将workers容器的环境变量合并到web容器：把原本仅设置在workers服务下的environment项（如REDIS_HOST、MEILI_ADDR、BROWSER_WEB_URL、DATA_DIR等）全部移到web服务的environment中，因为新容器需要同时承担 Worker 的职责。
删除workers服务定义：从 compose 文件中移除整个workers服务块。
更新web镜像：将镜像从ghcr.io/hoarder-app/hoarder-web:${KARAKEEP_VERSION:-release}改为ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}。

注意事项：

如果你的 compose 文件中使用了KARAKEEP_VERSION或HOARDER_VERSION环境变量来控制镜像版本，升级时注意在.env文件中同步修改，确保镜像标签正确。
升级后web容器将自动执行数据库迁移（见 docker/root/etc/s6-overlay/s6-rc.d/init-db-migration/run），首次启动请耐心等待迁移完成。

三、完整的升级 diff 对照

官方文档提供了完整的docker-compose.ymldiff，此处完整呈现（含新增行+与删除行-），便于你精确对照自己的配置：

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:

关键点总结：

BROWSER_WEB_URL必须加入web容器，否则单体容器无法连接chrome完成网页抓取。
DATA_DIR保持为/data不要改动，官方注释明确提示“几乎不需要修改该值”，如需自定义存储目录应改卷映射而非该变量。
若你使用了 AI 自动打标（如 OpenAI），需要将OPENAI_API_KEY一并注入web容器环境变量（diff 中以注释形式保留）。

四、升级后的目标 compose 文件（当前仓库标准配置）

升级完成后，你的docker-compose.yml应与当前仓库 docker/docker-compose.yml 保持一致（仅保留 web/chrome/meilisearch 三个服务与两个数据卷）：

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:

参数说明：

MEILI_ADDR：Meilisearch 地址，用于全文搜索，默认指向 compose 内部的meilisearch服务。
BROWSER_WEB_URL：Chrome 抓取服务地址，默认http://chrome:9222。
DATA_DIR：数据目录，官方明确标注“DON'T CHANGE THIS”，如需自定义路径请修改卷映射为- /path/to/your/directory:/data。
chrome的command参数为无头浏览器优化项：--disable-gpu禁用 GPU 加速、--disable-dev-shm-usage避免共享内存不足、--hide-scrollbars隐藏滚动条、--window-size=1440,900设定抓取视口尺寸。
MEILI_NO_ANALYTICS: "true"关闭 Meilisearch 匿名统计。

五、升级后的验证与常见问题

验证方法：

执行docker compose up -d重启服务，观察web容器日志确认数据库迁移完成、Web 与 Worker 进程均正常启动。
访问http://localhost:3000验证 Web 界面可用。
尝试保存一个链接，确认后台抓取（依赖chrome）与全文索引（依赖meilisearch）正常工作。

常见问题：

镜像拉取失败：若仍指向旧镜像hoarder-app/hoarder-*，请确认已更新为ghcr.io/karakeep-app/karakeep（官方说明旧镜像在品牌更名后可能不再获得更新，参见 08-hoarder-to-karakeep-migration.md）。
环境变量丢失导致功能异常：升级时容易漏掉workers独有变量（如BROWSER_WEB_URL），务必逐项核对合并。
数据卷残留：删除 Redis 后，如不再需要旧 Redis 数据可执行docker volume rm <项目名>_redis（请先确认数据已无用）。

六、底层原理：单体容器如何同时跑 Web 与 Worker

升级的本质是进程管理方式的变化。从 docker/Dockerfile 可以看到，新镜像基于s6-overlay构建（ENTRYPOINT ["/init"]），并通过 docker/root/etc/s6-overlay/s6-rc.d 下的服务定义管理进程：

init-db-migration：启动时先执行数据库迁移（node index.js，位于/db_migrations）。
svc-web：启动 Next.js Web 服务（cd /app/apps/web && exec node server.js）。
svc-workers：启动后台 Worker 进程（cd /app/apps/workers && exec node dist/index.js）。

在aio构建阶段，Dockerfile 通过touch /etc/s6-overlay/s6-rc.d/user/contents.d/svc-web与svc-workers两个文件，同时启用Web 与 Worker 服务；而web与workers单独构建目标（FROM aio_builder AS web/AS workers）则分别只启用其中一个，并设置USING_LEGACY_SEPARATE_CONTAINERS=true（见 packages/shared/config.ts 中该环境变量的定义），用于兼容旧版分离部署。这解释了为什么升级后无需再单独运行workers容器——两个进程已被合并进同一个容器生命周期内。