Karakeep 服务器迁移完全指南使用官方 CLI 在实例之间无缝迁移全部数据【免费下载链接】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/hoarderKarakeep 是一款可自托管的收藏一切应用链接、笔记与图片当你需要更换主机、从旧实例搬迁到新实例、或在不同部署环境Docker、Kubernetes 等之间转移数据时官方 CLI 的migrate命令提供了开箱即用的迁移方案。本文将基于官方迁移指南见 docs/docs/06-administration/06-server-migration.md与仓库中 迁移命令的完整源码实现系统讲解迁移命令能做什么、如何使用、每一步底层做了什么以及迁移过程中的注意事项与故障排查方法。读完本文你将能安全、可重复地在任意两台 Karakeep 服务器之间完成全量数据迁移。一、迁移命令能做什么migrate命令会把用户拥有的数据从源服务器完整复制到目标服务器复制顺序如下与源码中migrateCmd的 action 执行顺序一一对应用户设置User settings通过src.users.settings.query()读取、dest.users.updateSettings.mutate()写入列表Lists保留层级结构父子关系与各项设置名称、图标、描述、类型、智能查询、公开状态RSS 订阅源Feeds按名称、URL、启用状态原样重建AI 提示词Prompts自定义提示词及其启用状态WebhooksURL 与触发事件标签Tags按名称在目标端确保存在规则引擎规则Rules规则中引用的标签、列表、订阅源 ID 会被重映射为目标端对应 ID书签Bookmarks链接、笔记与资源书签创建后会自动附加正确的标签并加入正确的列表。三个重要的官方说明详见 迁移文档Webhook 令牌无法迁移API 无法读取令牌明文因此迁移后的 webhook 需要你在目标端手动重新填写认证令牌资源书签的迁移方式通过从源端下载原始资源、再上传到目标端完成且只有图片和 PDF 类型的资源书签被支持链接书签可能被去重如果目标端已存在相同 URL可能不会重复创建但标签和列表归属仍会应用到已有书签上。二、前置条件安装 CLI 并准备 API Key安装 CLI两种官方安装方式参见 命令行工具文档# 方式一通过 NPM 全局安装 npm install -g karakeep/cli # 方式二通过 Docker 运行每次运行一条命令无需安装 docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help准备两台服务器的 API Key 与地址需要收集四个关键参数参数含义--server-addr源服务器基础 URL--api-key源服务器 API Key--dest-server目标服务器基础 URL--dest-api-key目标服务器 API KeyAPI Key 可以在 Karakeep 的 Web 设置页面获取。获取后可用whoami命令快速验证密钥是否有效返回当前 API Key 所属用户信息karakeep --api-key key --server-addr addr whoami除了命令行参数CLI 还支持两种配置注入方式源码见 CLI 入口环境变量KARAKEEP_API_KEY、KARAKEEP_SERVER_ADDR配置文件$XDG_CONFIG_HOME/karakeep/config.json未设置XDG_CONFIG_HOME时默认读取~/.config/karakeep/config.json格式如下{ serverAddr: https://src.example.com, apiKey: your-source-api-key }优先级为命令行选项 环境变量 配置文件未提供服务器地址时CLI 默认指向https://cloud.karakeep.app见 config.ts。也可以在交互模式下用karakeep auth init生成或更新配置文件。迁移命令本身要求--dest-server与--dest-api-key为必填项源码中通过.requiredOption()声明见 migrate.ts。三、快速开始一条命令完成迁移在确认两台服务器的 API Key 与地址就绪后执行karakeep --server-addr https://src.example.com --api-key SOURCE_API_KEY migrate \ --dest-server https://dest.example.com \ --dest-api-key DEST_API_KEY运行过程说明命令是长时间运行的每个阶段都会输出实时进度源码中使用progressUpdate在 TTY 终端上动态刷新进度行开始前会提示你确认迁移方向About to migrate data from 源地址 to 目标地址. Proceed? (yes/no):输入yes或y继续不想交互确认可加--yes跳过迁移开始时还会尝试调用src.users.stats.query()预取书签总数用于显示已完成/总数形式的进度条获取失败也不影响迁移只是进度不显示总数。全部可用选项选项说明默认值--server-addr url源服务器基础 URL全局选项配置文件或云端地址--api-key key源服务器 API Key全局选项配置文件或环境变量--dest-server url目标服务器基础 URL必填无--dest-api-key key目标服务器 API Key必填无--batch-size n书签迁移的分页大小50最大 100-y, --yes跳过确认提示否除文档列出的选项外源码中还提供了细粒度的排除选项未写入官方文档但当前版本 CLI 已实现见 migrate.ts可按需裁剪迁移范围--exclude-assets跳过资源书签图片/PDF--exclude-lists排除列表及其书签归属关系--exclude-ai-prompts排除 AI 提示词--exclude-rules排除规则引擎规则--exclude-feeds排除 RSS 订阅源--exclude-webhooks排除 Webhooks--exclude-bookmarks跳过书签迁移--exclude-tags跳过标签迁移--exclude-user-settings跳过用户设置迁移。--batch-size在源码中通过Math.min(Number(v || 50), MAX_NUM_BOOKMARKS_PER_PAGE)钳制超过最大值会被自动压回上限 100见 migrate.ts。四、迁移原理与顺序深度解析结合 migrate.ts 源码迁移各阶段并非简单复制而是有明确的依赖关系与 ID 重映射逻辑1. 用户设置直接读取源端设置并整体写入目标端users.settings.query→users.updateSettings.mutate失败则整次迁移中止。2. 列表父级优先重建这是迁移中逻辑最复杂的一步migrateLists见 migrate.ts以父级优先的顺序循环创建列表保证子列表总能引用到已创建/匹配到的父列表对每个源列表先在目标端已有列表中查找名称、图标、描述、类型、查询条件、父列表全部匹配的列表命中则复用不重复创建未命中则新建若源列表带公开/私有标志会尽力在目标端对齐best-effort失败被忽略同时维护srcId → destId映射表供后续书签归属与规则重映射使用若所有源列表都无法解析出父级例如存在孤立父列表命令会以 Could not resolve list hierarchy due to missing parents 报错中止。3. RSS 订阅源逐一按name、url、enabled在目标端创建并记录 ID 映射migrateFeedsmigrate.ts。4. AI 提示词读取自定义提示词后在目标端创建若启用状态不一致则单独调用更新接口对齐migratePromptsmigrate.ts。5. Webhooks只迁移url与events不包含认证令牌令牌无法经 API 读取migrateWebhooksmigrate.ts。6. 标签按名称确保存在逐个按名称在目标端创建标签遇到重名冲突则忽略视为已存在随后基于目标端标签列表按名称构建srcId → destId映射migrateTagsmigrate.ts。7. 规则引擎规则ID 重映射规则迁移依赖前面构建的标签/列表/订阅源 ID 映射migrateRules与remapRuleIdsmigrate.ts核心是remapRuleIds递归重写规则结构条件conditionhasTag重映射tagIdimportedFromFeed重映射feedIdand/or递归重映射子条件事件eventtagAdded/tagRemoved重映射tagIdaddedToList/removedFromList重映射listIds数组动作actionsaddTag/removeTag重映射tagIdaddToList/removeFromList重映射listId。需要特别注意的是从源码结构看只要排除了标签、列表、订阅源三者中的任意一个规则迁移也会被跳过因为缺少对应的 ID 映射表无法安全重建规则见 migrate.ts。8. 书签按类型处理补标签、归列表书签迁移是耗时最长的阶段采用游标分页逐页拉取每页大小即--batch-size游标定义见 pagination.ts对每个书签按其内容类型见 bookmarks.ts 中的BookmarkTypes分别处理链接书签link在目标端以相同 URL 创建目标端可能因 URL 重复而触发去重笔记书签text以文本内容 来源 URL 创建资源书签asset先从源端GET /api/assets/{assetId}携带源端 Bearer 令牌下载原始资源再以 multipart form 方式POST /api/assets上传到目标端携带目标端 Bearer 令牌拿到新的assetId后创建资源书签。迁移失败或类型不支持时会被跳过并计入skipped统计--exclude-assets时则直接跳过——这也是官方文档仅支持图片和 PDF的底层体现其他/未知类型直接跳过。书签创建完成后还有两步收尾见migrateBookmarksmigrate.ts附加标签按标签名逐一 attach并保留每个标签的attachedBy附加方式信息归入列表迁移前会先扫描源端所有手动列表构建书签 → 所属列表的映射buildBookmarkListMembership随后通过lists.addToList把书签按重映射后的列表 ID 加入对应列表。书签的archived、favourited、note、summary、createdAt、source等元数据也会一并保留createdAt原样写入以维持时间线。五、迁移过程中的预期行为列表按父级优先重建层级结构完整保留已存在的同名列表会被复用而非重复创建订阅源、提示词、Webhooks、标签按值重建规则在标签/列表/订阅源 ID 全部重映射到目标端后重建每个书签创建后自动附加正确标签并归入正确列表全过程中各阶段都有实时进度反馈并在结束时汇总各阶段的创建数量与耗时例如Lists (created) 12/12、12 created in 5s。六、注意事项与实用建议Webhook 认证令牌必须在迁移后在目标端重新填写否则 webhook 无法通过目标端的鉴权校验目标端已有数据时重复链接可能被去重但标签与列表归属仍会应用到这个已存在的书签上不会丢失信息createdAt会被保留迁移后书签在目标端的时间排序与源端一致迁移前建议先在非生产目标实例上做一次演练确认源端 API Key 具备读取全部数据类型的权限、目标端 API Key 具备写入权限若源端或目标端负载较高请调小--batch-size降低压力默认 50上限 100。七、故障排查如果命令中途提前退出可以直接重新运行但需要了解其可重入性标签和列表已存在的会被直接复用不会产生重复链接去重避免重复创建相同 URL 的链接书签笔记书签和资源书签会重新创建规则、Webhooks、RSS 订阅源会被重新创建因此重跑后需要手动清理目标端的重复项进度日志会明确显示迁移进行到哪个阶段据此判断断点位置若源端或目标端处于高负载状态可改用更小的--batch-size重试。八、其他迁移相关资源若目标是从旧版本hoarder 时代的容器/数据迁移到新版本请参考 旧容器升级指南 与 hoarder 到 Karakeep 迁移指南官方文档同时提供了 服务器迁移指南的当前版本本文基于version-v0.30.0版本化文档编写内容与当前版本一致可对照查阅CLI 的通用用法与 API Key 获取细节见 命令行工具文档migrate命令的完整实现可在 apps/cli/src/commands/migrate.ts 中进一步研读。【免费下载链接】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），仅供参考