尧图网站建设 
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/hoarderHoarder 已正式更名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 # DONT CHANGE THIS2.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中的最小.envKARAKEEP_VERSIONrelease使用KARAKEEP_VERSIONrelease会拉取最新的稳定版想要可控升级可以固定到具体版本号例如KARAKEEP_VERSION0.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*.servicehoarder.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.envhoarder-web.log→karakeep-web.loghoarder-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_karakeepkarakeep-linux.sh这正是原文档所说迁移完成后还会检查更新的底层实现。update_karakeepkarakeep-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 单元默认端口作用Meilisearchmeilisearch.service7700全文检索后端Webkarakeep-web.service3000Karakeep Web 界面Workerskarakeep-workers.service无后台任务抓取、推理等无头浏览器karakeep-browser.service9222网页抓取渲染关键配置与数据位置由 karakeep-linux.sh 定义/etc/karakeep/karakeep.envKarakeep 环境变量文件修改后需重启karakeep-workers与karakeep-web服务/var/lib/karakeep应用数据库目录删除该目录内容将丢失全部数据/etc/meilisearch.toml与/var/lib/meilisearchMeilisearch 配置与数据库。验证迁移是否成功可以执行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.mdDebian/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【免费下载链接】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），仅供参考 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/hoarderHoarder 已正式更名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 # DONT CHANGE THIS2.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中的最小.envKARAKEEP_VERSIONrelease使用KARAKEEP_VERSIONrelease会拉取最新的稳定版想要可控升级可以固定到具体版本号例如KARAKEEP_VERSION0.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*.servicehoarder.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.envhoarder-web.log→karakeep-web.loghoarder-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_karakeepkarakeep-linux.sh这正是原文档所说迁移完成后还会检查更新的底层实现。update_karakeepkarakeep-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 单元默认端口作用Meilisearchmeilisearch.service7700全文检索后端Webkarakeep-web.service3000Karakeep Web 界面Workerskarakeep-workers.service无后台任务抓取、推理等无头浏览器karakeep-browser.service9222网页抓取渲染关键配置与数据位置由 karakeep-linux.sh 定义/etc/karakeep/karakeep.envKarakeep 环境变量文件修改后需重启karakeep-workers与karakeep-web服务/var/lib/karakeep应用数据库目录删除该目录内容将丢失全部数据/etc/meilisearch.toml与/var/lib/meilisearchMeilisearch 配置与数据库。验证迁移是否成功可以执行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.mdDebian/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【免费下载链接】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），仅供参考