Hoarder 到 Karakeep 迁移指南镜像切换、环境变量与裸机迁移全流程【免费下载链接】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 镜像可能不再获得更新、如何把docker-compose.yml中的镜像引用切换到新的karakeep镜像以及使用karakeep-linux.sh migrate完成裸机baremetal安装无缝迁移的完整流程。读完本文你将能够独立完成一套既有 Hoarder 部署到 Karakeep 的迁移并在迁移后正确校验服务状态与版本。迁移背景为什么需要手动切换镜像Hoarder 正在品牌更名rebranding为 Karakeep。由于 GitHub 仓库层面的一些限制GitHub 限制意味着旧仓库名下的镜像仓库可能无法继续获得新版本推送更名之后旧的 Docker 镜像ghcr.io/hoarder-app/hoarder:*很可能不再收到任何更新。因此已经部署了 Hoarder 的用户需要主动把 compose 文件中的镜像指向新的 Karakeep 镜像才能继续获得后续的功能更新与安全修复。这一点可以在仓库中印证当前仓库根目录下的生产编排文件 docker/docker-compose.yml 中web服务使用的镜像已经是ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}同时配套的chrome服务使用ghcr.io/karakeep-app/karakeep-chrome:release全文不再出现任何hoarder镜像引用开发环境编排文件 docker/docker-compose.dev.yml 同样如此。也就是说镜像仓库名称已经整体迁移到了karakeep-app组织下旧部署只需对齐这一改动即可。Docker 部署迁移修改镜像引用对于使用 Docker Compose 部署的用户迁移的核心操作是在docker-compose.yml中把web服务的镜像引用从旧的 Hoarder 镜像改为新的 Karakeep 镜像。官方给出的 diff 如下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:${HOARDER_VERSION:-release} image: ghcr.io/karakeep-app/karakeep:${HOARDER_VERSION:-release}也就是说只需把image一行从ghcr.io/hoarder-app/hoarder:${HOARDER_VERSION:-release}改为ghcr.io/karakeep-app/karakeep:${HOARDER_VERSION:-release}即可。注意这里 diff 中保留了${HOARDER_VERSION:-release}这个变量写法其含义是优先读取环境变量HOARDER_VERSION若未设置则回退到release标签即最新稳定版。如果你的 compose 文件中镜像标签不是通过变量注入的而是直接写死了版本号那么同样只需要替换镜像仓库名部分即可。修改完成后重新拉取并启动服务镜像即可完成切换docker compose pull docker compose up -d关于 HOARDER_VERSION 环境变量的注意事项官方文档特别提醒你也可以选择保留镜像引用中${HOARDER_VERSION}变量、直接修改这个环境变量的值来迁移。但这样做时必须记住该变量同样被.env文件所引用需要同步修改.env文件中的对应项否则环境变量与镜像引用之间会出现不一致。对比当前仓库的 docker/docker-compose.yml 可以看到新版本编排已经将变量名统一为KARAKEEP_VERSIONservices: web: image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}而在 docs/docs/02-installation/01-docker.md 的 Docker 安装指南中最小.env文件也相应变成了KARAKEEP_VERSIONrelease NEXTAUTH_SECRETsuper_random_string MEILI_MASTER_KEYanother_random_string NEXTAUTH_URLhttp://localhost:3000因此迁移时最省事也最彻底的做法是将 compose 文件与.env中的变量名统一升级为KARAKEEP_VERSION随机字符串建议用openssl rand -base64 36重新生成NEXTAUTH_URL应指向你的实际服务器地址并确认数据卷映射、MEILI_ADDR、BROWSER_WEB_URL、DATA_DIR等配置保持不变——这些持久化存储与各服务之间的连接关系在新 compose 中已经替你处理好了。与旧版多容器架构的衔接如果你的部署比 rebranding 更早还在使用hoarder-web、hoarder-workers与redis共存的旧版多容器架构那么本次镜像切换实际上是叠加在 docs/versioned_docs/version-v0.33.0/06-administration/07-legacy-container-upgrade.md 描述的「旧容器升级」之上的。那份指南要求删除redis容器及其卷、把workers容器的专属环境变量移到web容器、删除workers容器并把 web 镜像从hoarder-app/hoarder-web改为hoarder-app/hoarder。如今只需一步到位直接升级到ghcr.io/karakeep-app/karakeep即可同时完成两个变更。可以推断这两份迁移文档针对的是同一演进路径上的不同阶段先合并 web/workers 容器、弃用 redis再完成品牌更名后的镜像仓库切换。裸机安装迁移使用 karakeep-linux.sh migrate如果你不是用 Docker而是通过官方 Debian/Ubuntu 安装脚本对应文档 docs/docs/02-installation/06-debuntu.md在裸机上安装的 Hoarder迁移方式更加简单——脚本本身就内置了migrate子命令bash karakeep-linux.sh migrate官方文档明确说明该命令会在无任何用户输入的情况下完成整个迁移并且迁移完成后脚本还会自动检查并应用一次更新migrate之后紧接着执行update流程。需要注意的是这个脚本只认「自己安装的」部署仓库根目录下的 karakeep-linux.sh 在其usage()帮助信息中明确写道This script WILL NOT update or migrate a Karakeep/Hoarder install that was installed in any other way. Please back up your existing installation before running this script!也就是说脚本不会也无法迁移通过其他方式如手动部署、Docker、第三方脚本安装的 Hoarder并且官方强烈建议在运行迁移前先备份现有安装。脚本的-h/--help、-v/--verbose、--no-color选项同样适用于migrate子命令。migrate 命令的底层执行流程从 karakeep-linux.sh 源码中的migrate_karakeep()函数约第 472–499 行可以看出整个「无交互迁移」实际上是一系列确定性的自动化步骤前置检查只有当/opt/karakeep不存在时才执行迁移即目标应用尚未安装如果 Karakeep 已就位脚本会提示「无需迁移」并直接退出。停止旧服务执行systemctl stop hoarder-browser hoarder-workers hoarder-web避免迁移过程中数据仍在被写入。替换标识符用sed把/etc/hoarder/hoarder.env和/etc/systemd/system/hoarder-{browser,web,workers}.service、/etc/systemd/system/hoarder.target中的hoarder全部替换为karakeep、Hoarder替换为Karakeep。重命名 systemd 单元遍历/etc/systemd/system/hoarder*.service逐个改名为karakeep*.service并将hoarder.target改为karakeep.target。目录整体搬迁/opt/hoarder → /opt/karakeep、/var/lib/hoarder → /var/lib/karakeep、/etc/hoarder → /etc/karakeep、/var/log/hoarder → /var/log/karakeep同时把hoarder.env改名为karakeep.env两个日志文件也同步改名。用户与组重命名通过usermod -l karakeep hoarder与groupmod -n karakeep hoarder将低权限运行用户和用户组从hoarder改名为karakeep并递归修正四个目录的属主。重载并启动systemctl daemon-reload后systemctl enable --now karakeep.target随后调用service_check migrate校验karakeep-browser、karakeep-workers、karakeep-web、meilisearch四个服务是否全部处于active状态任一服务失败都会提示通过journalctl -xeu service-name排查。从这段实现可以看出迁移本质上是「目录 systemd 单元 用户/组 环境变量文件」的一次性整体更名数据库文件、Meilisearch 数据与既有书签数据都原样保留在迁移后的目录中不会重建或清空因此迁移前后的数据是连续的。迁移完成后的校验与更新karakeep.target下的四个服务对应文档 docs/docs/02-installation/06-debuntu.md「Services and Ports」一节与迁移后的目录布局如下服务职责默认端口meilisearch.service提供全文搜索配置位于/etc/meilisearch.toml数据在/var/lib/meilisearch7700karakeep-web.service提供 Web 服务环境变量文件为/etc/karakeep/karakeep.env3000karakeep-workers.service后台任务爬取、推理、搜索索引等无karakeep-browser.service无头浏览器服务9222迁移后的关键路径/etc/karakeep/karakeep.envKarakeep 环境变量文件修改后需sudo systemctl restart karakeep-workers karakeep-web生效、/var/lib/karakeep数据库目录删除内容将丢失全部数据、/var/log/karakeep日志目录已配置 logrotate 轮转。由于migrate子命令在case分支中定义为migrate_karakeep update_karakeep迁移完成后脚本会立即比对version.txt与 GitHub 最新 release 标签若版本不一致则自动执行更新流程停止服务 → 重新拉取源码 →pnpm i --frozen-lockfile→ 构建 → 执行pnpm migrate数据库迁移 → 重启karakeep.target并在最终输出Karakeep migration complete!。验证迁移是否成功可以依次执行systemctl status karakeep.target systemctl is-active karakeep-browser karakeep-workers karakeep-web meilisearch若四个服务全部输出active并能在浏览器中打开http://服务器IP:3000正常登录、看到原有书签数据迁移即宣告完成。迁移要点速查Docker 部署把web服务镜像从ghcr.io/hoarder-app/hoarder改为ghcr.io/karakeep-app/karakeep重新docker compose up -d若直接修改HOARDER_VERSION变量务必同步更新.env。变量名升级推荐新版本统一使用KARAKEEP_VERSION可顺势将 compose 与.env一并升级对齐。裸机部署仅限通过官方 Debian/Ubuntu 脚本安装的场景执行bash karakeep-linux.sh migrate即可全自动迁移并附带一次更新检查迁移前请先备份。数据安全迁移只做更名与搬迁不触碰数据内容/var/lib/karakeep是全部数据的所在务必谨慎操作。多容器旧架构若仍在使用含redis、独立workers容器的旧版架构请参照 docs/versioned_docs/version-v0.33.0/06-administration/07-legacy-container-upgrade.md 先完成容器合并再执行本次镜像切换。【免费下载链接】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），仅供参考