企业官网建设流程全解析

Hoarder 到 Karakeep 迁移完全指南：Docker 镜像切换与裸机迁移实战

【免费下载链接】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 已正式更名为 Karakeep，本指南面向仍在运行旧版 Hoarder 的自托管用户，讲解两种迁移路径：通过修改 Docker Compose 文件切换镜像的容器化迁移，以及通过karakeep-linux.sh migrate命令完成的裸机（Baremetal）无交互迁移。读完本文，你将掌握镜像变更的全部细节、.env环境变量的同步要点，以及迁移脚本在系统层面执行的每一步操作，能够安全、无痛地完成从 Hoarder 到 Karakeep 的升级。

迁移背景：为什么要从 Hoarder 切换到 Karakeep

Hoarder 是一个自托管的"收藏一切"应用（支持链接、笔记和图片，并提供基于 AI 的自动打标签与全文搜索）。项目更名为 Karakeep 后，由于 GitHub 对旧镜像命名空间存在限制，更名后的旧 Docker 镜像（ghcr.io/hoarder-app/hoarder）可能不再获得新的更新。这意味着继续停留在旧镜像上，你将无法接收到 Karakeep 后续的功能更新与安全修复，因此需要将部署指向新的镜像地址。

值得说明的是，迁移文档面向的是旧安装，因此示例中的 Compose 片段保留了HOARDER_VERSION变量名；而仓库当前主干的 docker-compose.yml 已经统一使用KARAKEEP_VERSION变量。无论变量名如何，镜像命名空间的切换逻辑是一致的。

Docker 部署迁移：修改 Compose 文件中的镜像地址

对于使用 Docker Compose 部署的用户，迁移的核心操作是修改docker-compose.yml中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}

即把镜像从ghcr.io/hoarder-app/hoarder替换为ghcr.io/karakeep-app/karakeep。这一改动只需要动web这一个服务——因为 Karakeep 的较新版本已经将原本分散在web、workers、redis等多个容器中的职责合并进了单个容器，chrome（headless 浏览器）与meilisearch（全文搜索）两个辅助服务保持不变。仓库当前的 docker-compose.yml 也印证了这一架构：web服务挂载data:/data数据卷、监听3000端口，通过MEILI_ADDR与BROWSER_WEB_URL分别连接 meilisearch 与 chrome 容器。

版本变量与.env文件的同步

镜像标签通过HOARDER_VERSION环境变量控制，其默认值为release（即latest稳定版）。文档特别强调：

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

这句话的含义是：如果你在.env文件中显式设置了HOARDER_VERSION=某个具体版本号（例如固定版本以控制升级节奏），那么在切换镜像后，必须同步检查.env文件中的变量值。因为旧镜像与 Karakeep 镜像的版本号发布节奏可能不一致——旧 Hoarder 镜像存在0.x.y版本，而 Karakeep 镜像的版本列表是独立的。如果.env中仍写着旧镜像的版本号，docker compose up拉取新镜像时可能因版本号不存在而失败。

作为对比，仓库当前的 Docker 安装文档 给出了新版.env的最小示例：

KARAKEEP_VERSION=release NEXTAUTH_SECRET=super_random_string MEILI_MASTER_KEY=another_random_string NEXTAUTH_URL=http://localhost:3000

其中KARAKEEP_VERSION=release会拉取最新稳定版；你也可以固定版本（如KARAKEEP_VERSION=0.10.0）来控制升级。NEXTAUTH_SECRET与MEILI_MASTER_KEY建议用openssl rand -base64 36生成随机字符串。每次修改.env后都需要重新执行docker compose up才会生效。

迁移后的启动与验证

完成 Compose 文件修改后，执行：

docker compose up -d

如果希望强制拉取最新镜像，可使用：

docker compose up --pull always -d

然后访问http://localhost:3000，确认登录页正常呈现、原有的书签数据完好无损。由于数据卷（data卷与meilisearch卷）在切换镜像前后保持不变，数据库、资产文件与搜索索引都会原样保留，无需手工搬运数据。

裸机（Baremetal）部署迁移：一键无交互迁移

如果你此前是通过 Debian/Ubuntu 安装脚本 在裸机上安装的 Hoarder，那么迁移更加简单——karakeep-linux.sh脚本内置了migrate命令：

bash karakeep-linux.sh migrate

该命令会在无需任何用户输入的情况下完成整机迁移，并且迁移完成后脚本会自动检查并安装 Karakeep 的最新更新。仓库根目录下的 karakeep-linux.sh 脚本（v3.0.0，来自 community-scripts/ProxmoxVE 的改编版）中，migrate的用法说明如下：

'migrate'Performs a full Hoarder ==> Karakeep migration on a previous install. Also checks for updates afterwards.

同时脚本也给出了两条重要提示：

• 仅支持由该脚本安装的 Hoarder 实例：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!

在 Debian 12 / Ubuntu 24.04 系统上，脚本支持三个子命令：install（全新安装）、update（升级已由脚本安装的实例）、migrate（从 Hoarder 迁移），并支持-h/--help、-v/--verbose、--no-color等选项，且必须以 root 身份运行。

迁移脚本源码解析：migrate 到底做了什么

为了让你对迁移过程心里有底，这里基于 karakeep-linux.sh 的migrate_karakeep()函数（第 472 行起）逐步拆解其内部流程。整个迁移围绕"把旧实例的目录、服务、用户全部改名"展开，核心是复用原有数据、只改命名：

1. 前置检查与停服

if [[ ! -d /opt/karakeep ]]; then systemctl stop hoarder-browser hoarder-workers hoarder-web

如果/opt/karakeep目录已存在，说明 Karakeep 已经安装，脚本会提示 "There is no need for a migration" 并直接跳过；否则先停止 Hoarder 的三个 systemd 服务（浏览器、workers、web），确保迁移过程中没有进程占用文件。

2. 内容替换：把 hoarder 字样批量替换为 karakeep

sed -i -e "s|hoarder|karakeep|g" /etc/hoarder/hoarder.env /etc/systemd/system/hoarder-{browser,web,workers}.service /etc/systemd/system/hoarder.target \ -e "s|Hoarder|Karakeep|g" /etc/systemd/system/hoarder-{browser,web,workers}.service /etc/systemd/system/hoarder.target

这一步用sed对.env文件与所有 systemd 服务文件做全局文本替换，包括hoarder→karakeep、Hoarder→Karakeep（同时覆盖描述字段Description）。

3. 重命名 systemd 服务单元

for path in /etc/systemd/system/hoarder*.service; do new_path="${path//hoarder/karakeep}" mv "$path" "$new_path" done mv /etc/systemd/system/hoarder.target /etc/systemd/system/karakeep.target

将所有hoarder-*.service服务单元与hoarder.target目标单元重命名为karakeep前缀，这样 systemd 才能找到与更新后服务名匹配的单元文件。

4. 迁移数据目录与配置文件

mv /opt/hoarder "$INSTALL_DIR" # /opt/karakeep mv /var/lib/hoarder "$DATA_DIR" # /var/lib/karakeep mv /etc/hoarder "$CONFIG_DIR" # /etc/karakeep mv /var/log/hoarder "$LOG_DIR" # /var/log/karakeep mv "$CONFIG_DIR"/hoarder.env "$ENV_FILE" # /etc/karakeep/karakeep.env mv "$LOG_DIR"/hoarder-web.log "$LOG_DIR"/karakeep-web.log mv "$LOG_DIR"/hoarder-workers.log "$LOG_DIR"/karakeep-workers.log

四个关键路径整体搬家：

这些路径与 Debian/Ubuntu 安装文档 中描述的 Karakeep 标准布局完全一致（/etc/meilisearch.toml、/var/lib/meilisearch、/etc/karakeep/karakeep.env、/var/lib/karakeep），迁移后无需再调整路径习惯。

5. 用户与组改名

usermod -l karakeep hoarder -d "$INSTALL_DIR" groupmod -n karakeep hoarder chown -R karakeep:karakeep "$INSTALL_DIR" "$CONFIG_DIR" "$DATA_DIR" "$LOG_DIR"

将低权限系统用户hoarder重命名为karakeep（并同步其家目录），将同名用户组重命名，最后递归修正四个目录的属主。这正是裸机安装脚本的设计理念——"Karakeep and Meilisearch are run in the context of their low-privilege user environments for more security"（低权限用户运行以提升安全性）。

6. 重载 systemd 并启动

systemctl daemon-reload systemctl -q enable --now karakeep.target service_check migrate

daemon-reload让 systemd 识别重命名后的单元文件，随后启用并启动karakeep.target（该 target 聚合了meilisearch.service、karakeep-web.service、karakeep-workers.service、karakeep-browser.service四个服务），最后通过service_check校验四个服务是否全部处于 active 状态，全部正常则输出 "Karakeep migration complete!"。

7. 迁移后自动检查更新

脚本入口处migrate分支执行的是：

migrate_karakeep && update_karakeep

即迁移完成后紧接着调用update_karakeep()：它会比对 GitHub 最新 release 与/opt/karakeep/version.txt中记录的版本，若存在新版本则下载源码、重新构建web、workers、cli三个子应用、执行数据库迁移（cd "$INSTALL_DIR"/packages/db && pnpm migrate）并重启服务。这正是文档所说"After the migration, the script will also check for an update"的源码实现。

迁移后的验证与注意事项

验证清单

• 服务状态：systemctl status karakeep.target应显示 karakeep-web、karakeep-workers、karakeep-browser、meilisearch 四个服务均为 active；如有异常可用journalctl -xeu <service-name>查看日志。
• Web 界面：访问http://<服务器IP>:3000（脚本会输出本机 IP），确认原有账号可登录、书签与列表数据完好。
• 环境变量：检查/etc/karakeep/karakeep.env，确认NEXTAUTH_SECRET、MEILI_MASTER_KEY等关键变量未被sed误伤。完整的环境变量清单见 环境变量配置文档。
• 数据完整性：/var/lib/karakeep是数据库所在地，"If you delete the contents of this folder you will lose all your data"，迁移期间请勿手动改动该目录。

关键注意事项

1. 备份先行：无论是 Docker 迁移还是裸机迁移，都建议先备份数据库与数据卷。Docker 场景可备份data与meilisearch两个 volume；裸机场景备份/var/lib/hoarder（或迁移后的/var/lib/karakeep）。
2. 迁移范围限制：karakeep-linux.sh migrate只对由该脚本安装的 Hoarder 实例生效，通过其他方式（如手工部署、其他发行版脚本）安装的实例需走 Docker 镜像切换或手动迁移路线。
3. 版本变量一致性：Docker 场景若自定义了HOARDER_VERSION/KARAKEEP_VERSION，切换镜像后要确认对应版本号在新镜像仓库中存在，否则拉取会失败。
4. 保持镜像跟踪：切换后的ghcr.io/karakeep-app/karakeep才是持续获得更新的镜像，后续升级请沿用新地址执行docker compose up -d或定期--pull always。

小结

Hoarder 到 Karakeep 的迁移本质上是品牌更名带来的镜像与服务命名切换：Docker 用户只需把web服务镜像指向ghcr.io/karakeep-app/karakeep并保证.env版本变量一致；裸机用户则直接运行bash karakeep-linux.sh migrate，脚本会自动完成停服、改名、目录迁移、用户重命名、服务重启与版本检查的全流程。由于数据卷与数据库目录全程被保留，两种方式都不会丢失既有书签、标签与搜索索引，迁移风险主要来自镜像版本号不匹配或非官方脚本安装的实例，前者可通过核对.env规避，后者建议改用 Docker 方案完成切换。

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