Karakeep 服务器间数据迁移指南使用官方 CLI 的 migrate 命令完整实战【免费下载链接】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本篇技术指南以 Karakeephoarder官方 CLI 的migrate子命令为核心讲解如何把用户数据书签、列表、标签、规则、RSS 订阅源等从一台自托管服务器完整迁移到另一台服务器。读完本文你将掌握迁移命令的完整参数用法、八个迁移阶段各自的处理逻辑含列表层级、规则 ID 重映射、资源文件重传等细节以及重跑语义与故障排查方法。迁移命令做了什么karakeep migrate通过官方 HTTP API 以「源服务器读取 → 目标服务器写入」的方式按固定顺序复制用户自有数据。迁移顺序与源码中执行顺序一一对应见 migrate.ts用户设置User settings列表Lists保留层级结构与配置RSS 订阅源FeedsAI 提示词自定义提示词及其启用状态WebhookURL 与事件标签按名称确保目标端存在规则引擎规则内部 ID 重映射到目标端对应 ID书签链接、文本笔记与资源文件创建成功后立即挂接正确的标签并加入正确的列表三个关键限制原文档明确注明源码同样印证Webhook token 无法迁移API 只读得到 URL 与事件列表migrateWebhooks 只提交url和eventstoken 属于不可读的密钥迁移后需在目标端手动重新填写。资源书签通过「下载-重传」迁移从源端/api/assets/{id}下载原始文件再以multipart/form-dataPOST 到目标端/api/assets重新上传见 migrateBookmarks 的 ASSET 分支。目前仅支持图片和 PDF两类资源书签。链接书签可能被去重若目标端已存在相同 URL 的书签创建会被去重合并但标签与列表归属仍会应用到已存在的书签上。准备工作安装 CLI官方提供两种安装方式NPMnpm install -g karakeep/cli对应 cli/package.json 中bin.karakeep入口Dockerdocker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help准备两端凭证迁移需要源、目标两台服务器的基础 URL与API key用途参数源服务器--server-addr、--api-key目标服务器--dest-server、--dest-api-keyAPI key 是用户级凭据通常在 Web 端设置页面生成CLI 通过Authorization: Bearer key请求/api/trpc接口见 trpc.ts因此该 key 必须拥有源端的读取权限与目标端的写入权限。可选的全局配置少敲两个参数除了在命令行显式传参CLI 还支持环境变量与配置文件两种方式见 index.ts 与 config.ts环境变量KARAKEEP_API_KEY、KARAKEEP_SERVER_ADDR未显式传参时优先读取命令行参数其次配置文件配置文件$XDG_CONFIG_HOME/karakeep/config.json未设置XDG_CONFIG_HOME时默认~/.config/karakeep/config.json格式为{ apiKey: ..., serverAddr: ... }默认服务器地址为https://cloud.karakeep.app自托管用户务必显式指定--server-addr与--dest-server快速开始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 下的单行刷新与非 TTY 下的逐行日志见 migrate.ts。执行时会先出现交互式确认提示About to migrate data from ... to .... Proceed? (yes/no):回答yes或y才继续传入-y/--yes可跳过该提示见 migrate.ts。若中途确认输入其他内容命令会以「Migration aborted by user」安全退出不做任何写入。参数速查表参数说明默认值--server-addr url源服务器基础 URL配置文件或环境变量--api-key key源服务器 API key配置文件或环境变量--dest-server url目标服务器基础 URL必填无--dest-api-key key目标服务器 API key必填无--batch-size n书签迁移的分页大小上限 10050-y, --yes跳过确认提示关闭值得强调的是--batch-size的上限 100 并非随意设定它对应共享类型定义中的硬性约束MAX_NUM_BOOKMARKS_PER_PAGE 100见 bookmarks.ts源码中解析该参数时直接用Math.min(Number(v || 50), MAX_NUM_BOOKMARKS_PER_PAGE)做了钳制migrate.ts。细粒度控制--exclude-*系列选项源码为每个迁移阶段都提供了独立的排除开关migrate.ts适合「只要书签」「只要配置」等局部迁移场景选项排除内容--exclude-user-settings用户设置--exclude-lists列表及其成员关系也会跳过规则与书签的列表归属处理--exclude-feedsRSS 订阅源--exclude-ai-promptsAI 自定义提示词--exclude-webhooksWebhook--exclude-tags标签--exclude-rules规则引擎规则--exclude-bookmarks书签--exclude-assets资源书签跳过资源文件不下载不重传注意规则阶段依赖标签/列表/订阅源的 ID 映射表源码中的执行条件为!excludeRules !excludeLists !excludeFeeds !excludeTagsmigrate.ts即同时排除这三者中的任意一项时规则迁移会自动跳过。八个迁移阶段逐层拆解1. 用户设置直接读取源端设置并整体写入目标端migrateUserSettings。该阶段无进度分页失败即终止整个迁移。2. 列表父优先创建 按值去重这是迁移中最讲究顺序的阶段migrateLists父优先循环扫描剩余列表仅当父列表已在目标端创建或列表无父级时才创建当前列表从而完整保留层级树若出现无法解析的父级会以Could not resolve list hierarchy due to missing parents报错。按值去重对每个源列表先尝试在目标端按name icon description type query parentId全字段匹配已存在列表命中则复用best-effort 对齐public标志未命中则调用lists.create新建之后补一次lists.edit设置公开状态。返回srcListId → destListId映射供后续规则重映射与书签列表归属使用。3. RSS 订阅源遍历源端订阅源按name/url/enabled逐个在目标端重建并维护 ID 映射migrateFeeds。4. AI 提示词读取自定义提示词文本 适用类型appliesTo在目标端创建若创建后启用状态不一致再调用prompts.update对齐enabledmigratePrompts。5. Webhook不带 token按url events重建。源码注释明确写着「tokens cannot be read; created without token」migrateWebhooks迁移后必须在目标端 Webhook 设置中重新填入鉴权 token。6. 标签按名称确保存在迁移策略是「按名创建、重复忽略」逐个调用tags.create捕获重复错误后继续最后用目标端当前全部标签构建name → destId映射表migrateTags。这意味着同名标签始终复用天然幂等。7. 规则引擎规则ID 重映射规则是唯一涉及「引用关系重写」的阶段migrateRules 与 remapRuleIds。由于标签、列表、订阅源在目标端都换了新 ID规则的引用必须跟随重映射条件conditionhasTag重映射tagIdimportedFromFeed重映射feedIdand/or递归处理子条件。事件eventtagAdded/tagRemoved重映射tagIdaddedToList/removedFromList重映射listIds数组。动作actionsaddTag/removeTag重映射tagIdaddToList/removeFromList重映射listId。某条规则迁移失败不会中断整体流程打印错误后继续下一条最终返回成功迁移的条数。8. 书签游标分页 类型分派书签迁移是耗时最长、逻辑最重的一环migrateBookmarks分页以--batch-size为页大小做游标分页拉取不包含正文内容includeContent: false逐页处理直到nextCursor为空。进度预估开始前先尝试读取源端users.stats获取书签总数作为进度分母统计接口不可用时进度只显示已迁移数migrate.ts。类型分派按书签content.type分三种路径——LINK提交url创建目标端若已有同 URL 书签则去重合并TEXT提交text/sourceUrl重建文本笔记ASSET先带Bearertoken 从GET {srcServer}/api/assets/{assetId}下载再以 FormData 上传到POST {destServer}/api/assets成功后用返回的assetId/contentType/size/fileName创建资源书签下载或上传失败的书签计入skippedAssets并跳过。共有的元数据标题、归档/收藏状态、备注、摘要、创建时间、来源随创建请求一并写入crawlPriority统一设为low。归属挂接每个书签创建完成后先按名称attach其全部标签保留attachedBy归属来源再依据预先扫描的「书签 → 源列表」映射把书签加入对应的目标列表。列表归属预扫描迁移书签前先遍历所有manual类型的列表并分页拉取成员构建srcBookmarkId → [srcListIds]映射buildBookmarkListMembershipsmart/dynamic等非手工列表不参与该映射。迁移后的预期结果列表按父优先顺序重建层级完整保留订阅源、提示词、Webhook、标签按值重建规则在标签/列表/订阅源 ID 全部重映射后重建引用关系指向目标端实体每个书签创建后自动挂接标签、加入对应列表两端数据在 API 语义下等价。注意事项与建议Webhook 鉴权 token迁移后必须在目标端手动重新输入否则 Webhook 无法通过鉴权。目标端已有数据重复链接可能被去重不会产生第二个相同 URL 的书签但标签与列表归属仍会应用到已存在的书签上同名标签、同值列表同样会被复用而非新建。备份先行迁移属于批量写操作建议先通过 Web 端的备份功能或 backups 路由 导出一份目标端快照便于回滚。只读前提下核对迁移完成后可用 CLI 的whoami、bookmarks、tags、lists等命令见 index.ts 的命令注册在目标端抽查数据一致性。故障排查与重跑语义命令中途退出怎么办可以安全地重新执行但不同数据类型在重跑时的行为不同幂等可复用已存在的标签和列表会被直接复用链接书签因 URL 去重不会重复创建会重复创建文本笔记TEXT与资源书签ASSET会被重新创建产生重复条目需手动清理规则、Webhook、RSS 订阅源会被重新创建重跑后需要手动删除旧的重复项进度定位各阶段末尾都会输出✓ 成功 / ✗ 失败与耗时统计如X created in Ys进度日志会明确显示迁移推进到哪个阶段据此判断中断点。性能调优当源端或目标端服务器负载较高时调小--batch-size例如 20可以降低单次请求压力反之追求吞吐时可调大至 100但受MAX_NUM_BOOKMARKS_PER_PAGE 100的上限约束。常见错误排查确认两端 API key 权限与服务器可达性确认目标端未开启只读模式只读模式下所有写入类调用都会失败资源迁移失败通常是文件过大或目标端资源配额不足可结合--exclude-assets先迁移其余数据再单独处理资源。相关资源迁移命令实现apps/cli/src/commands/migrate.tsCLI 入口与全局参数解析apps/cli/src/index.tsCLI 配置文件与默认地址apps/cli/src/lib/config.tsCLI 与服务器通信层apps/cli/src/lib/trpc.tsCLI 包定义与安装说明apps/cli/package.json书签分页上限常量packages/shared/types/bookmarks.ts更多 CLI 用法docs/docs/05-integrations/02-command-line.md【免费下载链接】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），仅供参考