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/hoarderHoarder 已正式更名为 Karakeep本指南面向仍在运行旧版 Hoarder 的自托管用户讲解两种迁移路径通过修改 Docker Compose 文件切换镜像的容器化迁移以及通过karakeep-linux.sh migrate命令完成的裸机Baremetal无交互迁移。读完本文你将掌握镜像变更的全部细节、.env环境变量的同步要点以及迁移脚本在系统层面执行的每一步操作能够安全、无痛地完成从 Hoarder 到 Karakeep 的升级。迁移背景为什么要从 Hoarder 切换到 KarakeepHoarder 是一个自托管的收藏一切应用支持链接、笔记和图片并提供基于 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等多个容器中的职责合并进了单个容器chromeheadless 浏览器与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_VERSIONrelease NEXTAUTH_SECRETsuper_random_string MEILI_MASTER_KEYanother_random_string NEXTAUTH_URLhttp://localhost:3000其中KARAKEEP_VERSIONrelease会拉取最新稳定版你也可以固定版本如KARAKEEP_VERSION0.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的用法说明如下migratePerforms 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 字样批量替换为 karakeepsed -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四个关键路径整体搬家迁移前Hoarder迁移后Karakeep用途/opt/hoarder/opt/karakeep程序安装目录源码与构建产物/var/lib/hoarder/var/lib/karakeep数据库等持久化数据目录/etc/hoarder/etc/karakeep配置文件目录含karakeep.env/var/log/hoarder/var/log/karakeep日志目录这些路径与 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 migratedaemon-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迁移期间请勿手动改动该目录。关键注意事项备份先行无论是 Docker 迁移还是裸机迁移都建议先备份数据库与数据卷。Docker 场景可备份data与meilisearch两个 volume裸机场景备份/var/lib/hoarder或迁移后的/var/lib/karakeep。迁移范围限制karakeep-linux.sh migrate只对由该脚本安装的 Hoarder 实例生效通过其他方式如手工部署、其他发行版脚本安装的实例需走 Docker 镜像切换或手动迁移路线。版本变量一致性Docker 场景若自定义了HOARDER_VERSION/KARAKEEP_VERSION切换镜像后要确认对应版本号在新镜像仓库中存在否则拉取会失败。保持镜像跟踪切换后的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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/10 16:12:48 · 阅读 1.2k Hoarder 到 Karakeep 迁移完全指南：Docker 镜像切换与裸机迁移实战
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/hoarderHoarder 已正式更名为 Karakeep本指南面向仍在运行旧版 Hoarder 的自托管用户讲解两种迁移路径通过修改 Docker Compose 文件切换镜像的容器化迁移以及通过karakeep-linux.sh migrate命令完成的裸机Baremetal无交互迁移。读完本文你将掌握镜像变更的全部细节、.env环境变量的同步要点以及迁移脚本在系统层面执行的每一步操作能够安全、无痛地完成从 Hoarder 到 Karakeep 的升级。迁移背景为什么要从 Hoarder 切换到 KarakeepHoarder 是一个自托管的收藏一切应用支持链接、笔记和图片并提供基于 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等多个容器中的职责合并进了单个容器chromeheadless 浏览器与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_VERSIONrelease NEXTAUTH_SECRETsuper_random_string MEILI_MASTER_KEYanother_random_string NEXTAUTH_URLhttp://localhost:3000其中KARAKEEP_VERSIONrelease会拉取最新稳定版你也可以固定版本如KARAKEEP_VERSION0.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的用法说明如下migratePerforms 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 字样批量替换为 karakeepsed -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四个关键路径整体搬家迁移前Hoarder迁移后Karakeep用途/opt/hoarder/opt/karakeep程序安装目录源码与构建产物/var/lib/hoarder/var/lib/karakeep数据库等持久化数据目录/etc/hoarder/etc/karakeep配置文件目录含karakeep.env/var/log/hoarder/var/log/karakeep日志目录这些路径与 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 migratedaemon-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迁移期间请勿手动改动该目录。关键注意事项备份先行无论是 Docker 迁移还是裸机迁移都建议先备份数据库与数据卷。Docker 场景可备份data与meilisearch两个 volume裸机场景备份/var/lib/hoarder或迁移后的/var/lib/karakeep。迁移范围限制karakeep-linux.sh migrate只对由该脚本安装的 Hoarder 实例生效通过其他方式如手工部署、其他发行版脚本安装的实例需走 Docker 镜像切换或手动迁移路线。版本变量一致性Docker 场景若自定义了HOARDER_VERSION/KARAKEEP_VERSION切换镜像后要确认对应版本号在新镜像仓库中存在否则拉取会失败。保持镜像跟踪切换后的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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考