Hoarder 到 Karakeep 迁移指南：镜像切换、环境变量与裸机迁移全流程-育师

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_VERSION：

services: web: image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}

而在 docs/docs/02-installation/01-docker.md 的 Docker 安装指南中，最小.env文件也相应变成了：

KARAKEEP_VERSION=release NEXTAUTH_SECRET=super_random_string MEILI_MASTER_KEY=another_random_string NEXTAUTH_URL=http://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/meilisearch`	7700
`karakeep-web.service`	提供 Web 服务，环境变量文件为`/etc/karakeep/karakeep.env`	3000
`karakeep-workers.service`	后台任务（爬取、推理、搜索索引等）	无
`karakeep-browser.service`	无头浏览器服务	9222

迁移后的关键路径：/etc/karakeep/karakeep.env（Karakeep 环境变量文件，修改后需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 先完成容器合并，再执行本次镜像切换。