ARTICLE DETAIL

资讯详情

深耕编程入门与网站建设的一线实战洞察。

Karakeep 旧版容器架构升级指南:从 web/workers/redis 三容器合并为单容器部署

Karakeep 旧版容器架构升级指南:从 web/workers/redis 三容器合并为单容器部署 Karakeep 旧版容器架构升级指南从 web/workers/redis 三容器合并为单容器部署【免费下载链接】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自 0.16 版本起的重要架构变更展开项目将原先分离的web与workers容器合并为单一容器并移除了对 Redis 容器的依赖。文中完整收录官方升级文档的迁移步骤与 diff 示例并结合仓库内当前的 docker-compose.yml、Dockerfile 及 s6-overlay 进程管理配置深入讲解新架构的工作原理、环境变量的归属变化与验证方法帮助自托管用户平滑完成旧版容器到新容器的升级。升级背景为什么要合并容器在 Karakeep 0.16 版本之前Docker 部署由三个核心容器组成web 容器hoarder-app/hoarder-web负责 Web 界面与 API 服务workers 容器hoarder-app/hoarder-workers负责后台任务包括爬虫crawler、AI 推理inference、搜索索引search、视频下载video、RSS 抓取feed、资产预处理assetPreprocessing、Webhook 派发、规则引擎ruleEngine、备份backup等redis 容器作为任务队列的消息代理协调 web 与 workers 之间的任务分发。0.16 版本将 web 与 workers 合并进同一个镜像与容器同时不再需要 Redis。官方文档明确指出旧版容器将在不久后停止支持因此所有仍在使用旧架构的部署都应尽快升级。从当前仓库源码看这一决策的底层原因清晰可见任务队列已从依赖外部 Redis 的 BullMQ 方案切换为基于 SQLite 的Liteque队列实现。在 packages/plugins/queue-liteque/src/index.ts 中可以看到队列数据库直接建立在本地数据目录下private db buildDBClient(path.join(serverConfig.dataDir, queue.db), { walEnabled: serverConfig.database.walMode, });也就是说任务队列数据与 Karakeep 自身的 SQLite 数据库一起存放在DATA_DIR指定的持久化卷中既简化了部署拓扑也消除了 Redis 这一额外的有状态组件及其数据卷的运维负担。官方升级四步操作官方文档给出的升级步骤非常明确核心思路是删掉 Redis → 迁移环境变量 → 删掉 workers 容器 → 更换镜像名。第一步移除 Redis 容器及其数据卷旧架构中的redis服务及其redis数据卷不再需要。若你的部署为 Redis 配置了独立的持久化卷如下方旧 compose 中的- redis:/data需一并删除避免留下无用的卷占用磁盘空间。redis: image: redis:7.2-alpine restart: unless-stopped volumes: - redis:/data第二步将 workers 容器专属的环境变量迁移到 web 容器旧架构下workers容器单独声明了REDIS_HOST、MEILI_ADDR、BROWSER_WEB_URL、DATA_DIR等环境变量。合并之后这些变量需要全部改由web容器承担。其中REDIS_HOST: redis已彻底不需要直接删除BROWSER_WEB_URL: http://chrome:9222是爬虫调用无头浏览器chrome 容器的关键配置必须保留并迁移OPENAI_API_KEY或OLLAMA_BASE_URL是 AI 自动打标签所必需的推理配置注释示例中原样保留MEILI_ADDR、DATA_DIR等公共配置保持原值迁移即可。第三步删除 workers 容器合并后 workers 的后台任务由 web 容器内部自动拉起详见下文单容器内部架构因此整个workers服务定义及它声明的depends_on: web依赖关系都可以移除。第四步更换 web 容器镜像名将镜像从旧仓库的ghcr.io/hoarder-app/hoarder-web更换为新的统一镜像。官方 diff 中给出的新镜像名为image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}注意项目从 Hoarder 更名为 Karakeep 后镜像仓库地址也相应更新${KARAKEEP_VERSION:-release}变量沿用旧机制默认为release稳定版。官方 diff 详解旧 compose 到新 compose 的完整变化官方文档提供了一个从旧版到新版的完整git diff针对docker/docker-compose.yml下面逐段解读其含义。web 服务的变化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 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_HOST: redisRedis 依赖已移除新增BROWSER_WEB_URL: http://chrome:9222这是原先只出现在 workers 容器中的爬虫浏览器地址现在由 web 容器统一管理保留MEILI_ADDR全文搜索依赖 Meilisearch与DATA_DIR: /data数据持久化目录并保留OPENAI_API_KEY的注释占位。redis 服务整体删除- redis: - image: redis:7.2-alpine - restart: unless-stopped - volumes: - - redis:/dataworkers 服务整体删除- 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:顶层volumes段只保留meilisearch全文索引数据与dataKarakeep 主数据两个卷。升级后的完整 compose 结构对照当前仓库根目录的 docker/docker-compose.yml升级完成后新架构只保留三个服务且 web 容器承担全部职责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:这里有一个值得注意的细节升级后的chrome服务镜像也更新为ghcr.io/karakeep-app/karakeep-chrome:release与旧版基于gcr.io/zenika-hub/alpine-chrome:123不同建议在升级时同步替换保证与新版 web 容器的兼容性。环境变量迁移核对清单合并前后环境变量的归属变化可归纳如下升级时请逐项核对.env文件与 compose 中的environment段变量旧版位置新版位置说明REDIS_HOSTweb workers删除队列改为 SQLite 实现Liteque不再需要 RedisBROWSER_WEB_URLworkersweb无头浏览器调试地址指向http://chrome:9222MEILI_ADDRweb workerswebMeilisearch 地址DATA_DIRweb workersweb数据持久化目录官方注释建议不要改动OPENAI_API_KEYworkerswebAI 自动打标签所需可选OLLAMA_BASE_URLworkersweb本地 Ollama 推理地址可选单容器内部架构s6-overlay 如何同时跑 Web 与 Workers合并后的单一容器为什么能同时承载 Web 服务与全部后台任务答案在 docker/Dockerfile 的镜像构建逻辑中。镜像最终目标阶段为aioAll-in-One其入口是 s6-overlay 的初始化进程FROM aio_builder AS aio RUN touch /etc/s6-overlay/s6-rc.d/user/contents.d/init-db-migration \ /etc/s6-overlay/s6-rc.d/user/contents.d/svc-web \ /etc/s6-overlay/s6-rc.d/user/contents.d/svc-workers ENTRYPOINT [/init]s6-overlay 是一个容器进程监督器会在容器启动时按依赖关系拉起多个常驻服务。从 docker/root/etc/s6-overlay/s6-rc.d 的目录结构可以看到容器内部实际运行的三类服务init-db-migration一次性任务启动时先执行数据库迁移脚本。其 run 脚本内容为echo Running db migration script; cd /db_migrations; exec node index.js;svc-weblongrun常驻服务负责启动 Next.js Web 服务器run 脚本为cd /app/apps/web; exec node server.js;svc-workerslongrun常驻服务负责启动全部后台 worker 进程run 脚本为cd /app/apps/workers; exec node dist/index.jss6-overlay 通过dependencies.d/init-db-migration依赖声明确保 Web 与 Workers 都等待数据库迁移完成后才启动。此外镜像中还提供了健康检查每 30 秒探测一次/api/health接口HEALTHCHECK --interval30s --timeout10s --start-period5s --retries3 \ CMD wget --no-verbose --tries1 --spider http://127.0.0.1:${PORT:-3000}/api/health || exit 1需要特别指出的是旧版镜像并未被删除Dockerfile 中仍保留web与workers两个目标阶段分别设置USING_LEGACY_SEPARATE_CONTAINERStrue环境变量这是为尚未完成迁移的旧部署保留的过渡产物。新部署应当使用aio阶段产出的统一镜像。Workers 内部到底跑了哪些任务统一镜像内的 workers 进程实际启动的任务队列在 apps/workers/index.ts 中集中注册包括crawler链接爬取网页内容、截图、PDF 快照提取lowPriorityCrawler低优先级爬取inferenceAI 自动打标签与摘要生成embeddings向量化与语义搜索索引search全文搜索索引adminMaintenance管理员后台维护任务video视频下载yt-dlpfeedRSS 订阅抓取刷新assetPreprocessing图片预处理与 OCRruleEngine自动化规则处理webhookWebhook 事件派发backup定时备份调度。如需精细控制可通过 环境变量文档 中说明的WORKERS_ENABLED_WORKERS白名单逗号分隔与WORKERS_DISABLED_WORKERS黑名单优先级更高在合并后的容器中按需启停具体 worker。升级操作与验证执行升级在完成上述 compose 文件修改与镜像名替换后执行docker compose up -d若你使用了KARAKEEP_VERSIONrelease且希望强制拉取最新镜像可改用docker compose up --pull always -d验证升级结果升级完成后可通过以下方式确认迁移成功查看容器列表docker compose ps应只看到web、chrome、meilisearch三个服务不再存在workers与redis访问健康检查浏览器打开http://localhost:3000正常出现登录页验证后台任务新建一条链接书签确认其能被正常爬取、自动打标签说明容器内部的 workers 进程运行正常检查日志docker compose logs web中应能看到 s6-overlay 依次执行数据库迁移、启动 Web 服务器与 Workers 的记录。回滚注意事项升级本质上是在同一个data数据卷上运行新镜像Karakeep 的数据书签、标签、列表、队列数据库queue.db均保存在DATA_DIR中不会因容器拓扑变化而丢失。但鉴于官方声明旧容器将停止支持建议升级前仍对data卷做一次快照备份可参考仓库中的 backupWorker.ts 定时备份机制或直接卷级备份以便异常时回滚。常见问题Q1升级后 Redis 卷里的数据还要吗不需要。Redis 仅作为旧版任务队列的消息代理任务数据本身不具备持久价值升级后可直接删除redis卷。Q2我在 workers 容器里额外设置了WORKERS_NUM_WORKERS之类的变量迁到哪里所有 worker 相关变量统一迁移到web容器的environment段或保持放在.env中通过env_file注入。完整的变量清单见 环境变量文档其中CRAWLER_NUM_WORKERS、INFERENCE_NUM_WORKERS、SEARCH_NUM_WORKERS、EMBEDDING_NUM_WORKERS、ASSET_PREPROCESSING_NUM_WORKERS、WEBHOOK_NUM_WORKERS、RULE_ENGINE_NUM_WORKERS等并发控制参数都适用于新架构。Q3我仍在使用旧镜像hoarder-web/hoarder-workers还能继续跑吗短期内可以Dockerfile 中保留了这两个镜像目标阶段但官方已明确旧容器将很快停止支持建议尽快按本文步骤迁移。Q4升级会影响 Meilisearch 索引吗不会。meilisearch服务与卷在新旧架构中完全一致全文搜索索引原样保留若需升级 Meilisearch 版本可参考 故障排查文档。【免费下载链接】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),仅供参考
返回列表