Karakeep 迁移指南：从 Hoarder 更名到新镜像与裸机升级全流程-编程实验室

Karakeep 迁移指南：从 Hoarder 更名到新镜像与裸机升级全流程

【免费下载链接】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

Hoarder 已正式更名（rebranding）为 Karakeep。受 GitHub 平台限制，更名后旧的 Hoarder Docker 镜像可能不再获得新版本更新，因此存量部署需要将镜像地址切换到新的 Karakeep 镜像；此前通过 Debian/Ubuntu 安装脚本部署的裸机实例，也可以一键完成目录、服务与数据迁移。读完本文，你将掌握 Docker Compose 镜像迁移、.env版本变量处理，以及裸机安装调用karakeep-linux.sh migrate的完整迁移原理与操作步骤。

一、为什么需要迁移：更名背后的镜像分发问题

Hoarder 项目更名为 Karakeep 后，项目仓库、组织名称与容器镜像地址一并发生了变更。官方迁移文档（docs/versioned_docs/version-v0.30.0/06-administration/08-hoarder-to-karakeep-migration.md）明确指出：

Due to github limitations, the old docker image might not be getting new updates after the rebranding.

也就是说，受 GitHub 平台限制，旧的ghcr.io/hoarder-app/hoarder镜像在更名后很可能不再推送新版本。如果你仍在使用旧镜像，将无法获得后续的 bug 修复与功能更新，因此需要把镜像地址切换到新仓库。

二、Docker Compose 迁移：修改镜像地址

最直接的迁移方式，是修改 Docker Compose 文件中的web服务镜像地址。原文档给出的 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}

对照当前仓库中的 docker/docker-compose.yml，迁移后的镜像地址应为：

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 DATA_DIR: /data # DON'T CHANGE THIS

2.1 为什么要改这两处

ghcr.io/hoarder-app/hoarder→ghcr.io/karakeep-app/karakeep：镜像仓库地址（镜像名）本身。
镜像 tag 的占位变量：旧仓库使用${HOARDER_VERSION:-release}，新仓库已统一为${KARAKEEP_VERSION:-release}。变量名不影响镜像拉取结果，但为了语义清晰，建议同步改名（见下文第三节）。

2.2 数据卷不受影响

迁移不涉及数据搬迁：应用数据存放在名为data的 Docker volume 中，全文检索数据存放在meilisearchvolume 中（见 docker/docker-compose.yml 末尾的volumes声明）。旧镜像与新镜像读取的是同一批 volume，因此仅替换镜像名即可平滑升级，无需导出/导入数据。

三、版本环境变量：HOARDER_VERSION 与 KARAKEEP_VERSION

原文档特别提醒：

You can also change theHOARDER_VERSIONenvironment variable but if you do so remember to change it in the.envfile as well.

即：如果你选择把镜像 tag 的变量名从HOARDER_VERSION改成KARAKEEP_VERSION，必须同步修改.env文件，否则 Compose 文件引用的变量在.env中找不到定义，会回落使用默认值release。

3.1 .env 的推荐写法

参考当前仓库 Docker 安装文档（docs/versioned_docs/version-v0.30.0/02-installation/01-docker.md）中的最小.env：

KARAKEEP_VERSION=release

使用KARAKEEP_VERSION=release会拉取最新的稳定版；
想要可控升级，可以固定到具体版本号，例如KARAKEEP_VERSION=0.10.0；
每次修改.env后都需要重新执行docker compose up使改动生效。

3.2 更新与重新拉取

按 docker/docker-compose.yml 与安装文档的约定：

固定了版本号时：在.env中提高版本号，然后重新执行docker compose up -d拉取新镜像；
使用release标签时：需要强制 Docker 重新拉取，执行docker compose up --pull always -d。

四、裸机安装迁移：karakeep-linux.sh migrate

如果你之前是通过 Debian/Ubuntu 安装脚本（对应仓库根目录的 karakeep-linux.sh）在裸机上安装的 Hoarder，迁移只需一条命令：

bash karakeep-linux.sh migrate

按原文档说明，该命令全程无需用户交互输入，迁移完成后脚本还会自动检查并安装更新。

4.1 前置条件与脚本约束

从 karakeep-linux.sh 的源码可以看到脚本的硬性约束：

必须以 root 权限运行：脚本末尾有[ "$(id -u)" -ne 0 ] && die "This script requires root privileges. Please run with sudo or as the root user."；
只支持该脚本自身安装的实例：脚本 usage 中明确说明This script WILL NOT update or migrate a Karakeep/Hoarder install that was installed in any other way；
强烈建议先备份：usage 中提示Please back up your existing installation before running this script!；
支持-h/--help、-v/--verbose、--no-color三个可选参数。

4.2 迁移过程源码级拆解（migrate_karakeep）

对应源码位置：karakeep-linux.sh。整个函数按顺序完成以下动作：

前置检查：若/opt/karakeep目录已存在，则打印There is no need for a migration: Karakeep is already installed.并直接退出，避免重复迁移造成破坏；
停止旧服务：systemctl stop hoarder-browser hoarder-workers hoarder-web；
文本替换：用sed将/etc/hoarder/hoarder.env与 systemd 单元文件中的hoarder全部替换为karakeep、Hoarder替换为Karakeep（保证服务描述与日志标识一致）；
重命名 systemd 单元文件：遍历/etc/systemd/system/hoarder*.service并重命名为karakeep*.service，hoarder.target同样改为karakeep.target；
目录搬迁：
- /opt/hoarder→/opt/karakeep（安装目录，即脚本中的INSTALL_DIR）
- /var/lib/hoarder→/var/lib/karakeep（数据目录，即DATA_DIR）
- /etc/hoarder→/etc/karakeep（配置目录，即CONFIG_DIR）
- /var/log/hoarder→/var/log/karakeep（日志目录，即LOG_DIR）
配置文件与日志重命名：hoarder.env→karakeep.env，hoarder-web.log→karakeep-web.log，hoarder-workers.log→karakeep-workers.log；
系统用户与组迁移：usermod -l karakeep hoarder -d /opt/karakeep重命名用户，groupmod -n karakeep hoarder重命名用户组；
权限修正：chown -R karakeep:karakeep安装目录、配置目录、数据目录与日志目录；
重载并启动：systemctl daemon-reload后systemctl -q enable --now karakeep.target；
服务健康检查：调用service_check migrate，依次确认karakeep-browser、karakeep-workers、karakeep-web、meilisearch四个服务均处于 active 状态，全部就绪后输出Karakeep migration complete!。

4.3 迁移后的自动更新

migrate分支的调用链是migrate_karakeep && update_karakeep（karakeep-linux.sh），这正是原文档所说"迁移完成后还会检查更新"的底层实现。update_karakeep（karakeep-linux.sh）会：

对比 GitHub 最新 release 的 tag 与/opt/karakeep/version.txt中记录的旧版本号；
若存在新版本：停止 web/workers 服务 → 下载新版本源码 → 重新构建 web、workers、cli 三个子包 → 执行数据库迁移（packages/db下的pnpm migrate）→ 更新version.txt→ 重启karakeep.target；
若版本一致，则输出No update required.。

五、迁移后的验证与目录布局

裸机迁移成功后，Karakeep 的运行目录与端口布局（依据 06-debuntu.md 的 "Services and Ports" 一节）：

服务	systemd 单元	默认端口	作用
Meilisearch	`meilisearch.service`	7700	全文检索后端
Web	`karakeep-web.service`	3000	Karakeep Web 界面
Workers	`karakeep-workers.service`	无	后台任务（抓取、推理等）
无头浏览器	`karakeep-browser.service`	9222	网页抓取渲染

关键配置与数据位置（由 karakeep-linux.sh 定义）：

/etc/karakeep/karakeep.env：Karakeep 环境变量文件，修改后需重启karakeep-workers与karakeep-web服务；
/var/lib/karakeep：应用数据库目录，删除该目录内容将丢失全部数据；
/etc/meilisearch.toml与/var/lib/meilisearch：Meilisearch 配置与数据库。

验证迁移是否成功，可以执行：

systemctl status karakeep.target systemctl is-active karakeep-web karakeep-workers karakeep-browser meilisearch

如果个别服务启动失败，可使用脚本内置的排查提示：

journalctl -xeu <service-name>

六、常见问题与注意事项

旧镜像还能用吗？可以继续运行，但更名后旧镜像大概率不再接收新版本更新（官方文档明确说明），建议尽早迁移以获取修复与功能迭代。
Docker 部署需要备份吗？镜像替换不触碰 volume 数据，但任何升级操作前都建议先对data与meilisearchvolume 做快照或备份。
裸机迁移脚本提示"无需迁移"？说明/opt/karakeep已存在，脚本检测到目标实例已就绪，直接跳过迁移逻辑。
迁移失败如何排查？使用journalctl -xeu karakeep-web等命令查看具体服务日志；脚本的-v/--verbose参数可以打印完整输出便于定位问题。
版本回退：Docker 部署只需在.env中把KARAKEEP_VERSION指回旧版本并重新docker compose up -d；裸机迁移后如需回退，请依赖迁移前自行创建的系统备份恢复。

七、延伸阅读

Docker 完整安装与升级：docs/versioned_docs/version-v0.30.0/02-installation/01-docker.md
Debian/Ubuntu 裸机安装与更新：docs/versioned_docs/version-v0.30.0/02-installation/06-debuntu.md
旧版多容器（含 Redis、独立 workers 容器）升级说明：docs/docs/06-administration/07-legacy-container-upgrade.md
迁移脚本源码：karakeep-linux.sh
迁移后的 Compose 参考：docker/docker-compose.yml

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考