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

发布时间:2026/11/13 16:25:52

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),仅供参考
延伸阅读

更多相关文章

2026/11/11 3:23:50

SpringBoot宠物领养系统开发与架构设计

1. 项目背景与核心价值 流浪动物救助与领养一直是社会关注的公益热点问题。根据相关机构统计,我国每年约有4000万只流浪动物需要救助,而传统线下救助站存在信息不对称、领养流程繁琐、资源调配效率低下等问题。这个基于SpringBoot的宠物找家系统&#xf…

2026/11/11 6:32:19

网盘直链怎么获取:八大云盘解析下载地址快速指南

网盘直链怎么获取:八大云盘解析下载地址快速指南 【免费下载链接】Online-disk-direct-link-download-assistant 一个基于 JavaScript 的网盘文件下载地址获取工具。基于【网盘直链下载助手】修改 ,支持 百度网盘 / 阿里云盘 / 中国移动云盘 / 天翼云盘 …

2026/11/13 16:21:08

电车需要电工证吗 别踩坑了特种作业证到底该怎么考

电车需要电工证吗 别踩坑了特种作业证到底该怎么考 你是不是正在为找一份电工相关的工作发愁?是不是被招聘方问“电车需要电工证吗”这个问题搞得一头雾水?别急, 千万别踩坑 ,特种作业证不考清楚,不仅影响你找工作,还可能耽误你的职业发展。…

2026/11/13 16:21:08

昆山电工证如何办理?在外省考的证能转过来吗?在哪考最靠谱?

昆山电工证如何办理?在外省考的证能转过来吗?在哪考最靠谱? 之前考的证在外省能不能转过来?这是不少准备报考昆山电工证的学员最关心的问题。随着国家对特种作业人员的管理越来越严格,电工证作为高危行业的重要凭证,其重要性不言而喻。很多人已经在外省…

2026/11/13 16:21:08

水库移民免费考电工证怎么考?实操考试心里没底怕挂科

水库移民免费考电工证怎么考?实操考试心里没底怕挂科 实操考试心里没底怕挂科,尤其是对水库移民这类群体来说,想要通过电工证考试顺利拿到电子证书,备考路上的每一步都得走稳。现在国家政策支持,部分地方确实提供 水库移民免费考电工证…

2026/11/13 16:21:08

电工证等级分布怎么选?官方报名入口在哪怕被中介坑

电工证等级分布怎么选?官方报名入口在哪怕被中介坑 不知道去哪报名怕被中介坑,你不是一个人。现在特种作业操作证,尤其是电工证,是很多建筑工、劳务班组、项目管理人员的刚需,但一不小心就容易被中间人套路,多花冤枉钱还拿不到证。特别是…

2026/11/13 16:21:08

安装电工证多少钱 多久拿证 低学历也能报

安装电工证多少钱 多久拿证 低学历也能报 你是不是也担心自己学历不高,报不了安装电工证?其实很多人和你一样,学历并不高,但照样能顺利拿到证。关键是了解流程和材料,再配合一些备考技巧, 多久拿证…

2026/11/13 16:16:07

习水特种作业操作证含金量高不高?证书过期了不知道怎么复审延期

习水特种作业操作证含金量高不高?证书过期了不知道怎么复审延期 证书过期了不知道怎么复审延期?很多人在拿到特种作业操作证后,往往忽视了证书的 有效期 和 年审 要求,一不小心就错过了复审时间,导致证书失效,影响了工作的正常开展。尤其是像…

2026/11/12 20:35:13

电工证丢失还能补吗?千万别踩坑,丢了证等于失业

电工证丢失还能补吗?千万别踩坑,丢了证等于失业 你正在找工作,但手里的电工证突然丢了,这下怎么办?别急,先别慌, 电工证丢失还能补吗 ?答案是肯定的,但 千万别踩坑 ,补办流程如果不了解,可能会耽误你上岗、甚至影响到你的收入。…

2026/11/13 0:01:06

办上海高压电工证良心建议:别被中介坑了,自己看这篇就够了

办上海高压电工证良心建议:别被中介坑了,自己看这篇就够了 你是不是也像我一样,第一次听说“高压电工证”这个名词,就感觉一头雾水?其实很多人都跟我一样,不知道去哪报名、怕被中介坑,结果花了冤枉钱还考不上。今天我就从一个在商丘培训过的学员角度,…

2026/11/13 0:01:06

黎里考电工证在哪里值不值得考

黎里考电工证在哪里值不值得考 之前考的证在外省能不能转过来?这是很多在外地工作、准备回老家发展的朋友最关心的问题。特别是在黎里地区,很多从事电力相关工作的朋友,都面临这样一个难题: 外省的电工证能否在本地使用?值不值得考?…

2026/11/13 0:01:06

毕节哪里考电工证 怎么报名学历不高也能上手

毕节哪里考电工证 怎么报名学历不高也能上手 你是不是也和我一样,学历不高,想着考个电工证,但又担心自己条件不够,怕报不上名?其实不然,只要符合条件,学历不高也能考电工证。今天就来聊聊【毕节哪里考电工证】这个问题,还有怎么报名,让你一步到位不…

2026/11/12 22:10:13

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/13 12:14:39

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑