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/hoarder本指南以 Karakeep原 Hoarder官方文档中的服务器迁移章节为核心讲解如何使用官方 CLI 的migrate命令将用户设置、列表、RSS 源、AI 提示词、Webhook、标签、规则引擎规则以及书签链接、笔记、图片/PDF 资产从源服务器完整迁移到目标服务器。读完本文你将掌握迁移命令的完整参数、内部执行顺序与底层实现原理并能在换机、换部署环境或服务器升级时安全、可靠地完成数据搬迁。迁移命令能做什么migrate命令负责把用户自有数据从源服务器复制到目标服务器迁移顺序固定依次为用户设置User settings列表Lists保留层级结构与配置RSS 源RSS feedsAI 提示词AI prompts含自定义提示词及其启用状态WebhookURL 与事件标签Tags确保按名称存在规则引擎规则Rule engine rulesID 重映射为目标服务器的对应 ID书签Bookmarks链接、文本与资产创建后补挂正确的标签并加入正确的列表上述顺序与源码中migrate命令的执行步骤完全一致见 apps/cli/src/commands/migrate.ts每一步都先打印Migrating xxx …的阶段提示完成后输出耗时与数量统计最后以Migration completed successfully结束。需要注意的迁移边界Webhook token 无法通过 API 读取因此不会被迁移如目标端需要必须手动重新填写。资产类书签通过“下载原资产 → 重新上传到目标服务器”的方式迁移且仅支持图片和 PDF。链接类书签在目标端可能被去重若目标服务器已存在相同 URL 的书签则不会重复创建。前置条件安装 CLI两种安装方式任选其一NPM 全局安装npm install -g karakeep/cliDocker 运行不需要本地 Node.js 环境docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help准备两端凭证迁移需要同时拿到源服务器与目标服务器的 API Key 和 Base URL用途参数源服务器--server-addr、--api-key目标服务器--dest-server、--dest-api-key从源码看CLI 通过 tRPC 客户端访问服务器的/api/trpc端点并将 API Key 以Bearer形式放入authorization请求头见 apps/cli/src/lib/trpc.ts。因此两端服务器都需要开放 API 访问且提供的 API Key 必须具备读取/创建数据的权限。另外--api-key与--server-addr也可以省略改由环境变量KARAKEEP_API_KEY、KARAKEEP_SERVER_ADDR提供或写入 CLI 配置文件默认路径为~/.config/karakeep/config.json可用XDG_CONFIG_HOME调整这些解析逻辑见 apps/cli/src/index.ts 与 apps/cli/src/lib/config.ts。未提供任何形式的 API Key 时CLI 会直接报错退出。快速开始在准备好两端凭证后执行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说明该命令是长时运行任务会为每个阶段实时显示进度在 TTY 终端中进度条会原地刷新见 apps/cli/src/commands/migrate.ts。执行前会弹出一个确认提示询问是否从源地址迁移到目标地址回答yes/y继续其他输入则中止迁移apps/cli/src/commands/migrate.ts。传入--yes或-y可跳过确认提示适合脚本化、无人值守执行。完整参数说明参数说明--server-addr url源服务器 Base URL--api-key key源服务器 API Key--dest-server url目标服务器 Base URL必填--dest-api-key key目标服务器 API Key必填--batch-size n书签迁移的分页大小默认 50最大 100-y,--yes跳过确认提示提示--batch-size在源码中会通过Math.min(Number(v || 50), MAX_NUM_BOOKMARKS_PER_PAGE)进行钳制MAX_NUM_BOOKMARKS_PER_PAGE定义于 packages/shared/types/bookmarks.ts即使传入超过 100 的值也会被自动限制在 100 以内。按需排除部分数据源码扩展除文档列出的基础参数外源码还提供了一组--exclude-*选项允许按需裁剪迁移范围apps/cli/src/commands/migrate.ts--exclude-assets跳过资产书签的迁移--exclude-lists不迁移列表及列表成员关系--exclude-ai-prompts不迁移 AI 提示词--exclude-rules不迁移规则引擎规则--exclude-feeds不迁移 RSS 源--exclude-webhooks不迁移 Webhook--exclude-bookmarks跳过书签迁移--exclude-tags不迁移标签--exclude-user-settings不迁移用户设置典型场景目标服务器已存在完整的标签体系只想迁移书签时可组合使用--exclude-tags --exclude-lists --exclude-rules等选项精简迁移内容。迁移过程详解每阶段做了什么1. 用户设置从源服务器读取用户设置原样写入目标服务器apps/cli/src/commands/migrate.ts实现上是src.users.settings.query()读取 →dest.users.updateSettings.mutate()写入。2. 列表保留层级列表迁移采用父级优先策略apps/cli/src/commands/migrate.ts先尝试在目标端查找“同名、同图标、同描述、同类型、同查询条件、同父列表”的现有列表找到则复用并尽力对齐public可见性标志找不到则创建。子列表只有在其父列表创建/匹配成功之后才会处理从而完整保留层级结构。迁移过程中会建立srcId - destId的映射表供后续规则与书签的列表归属使用。3. RSS 源逐条读取源端 RSS 源按name、url、enabled在目标端创建并建立新旧 ID 映射apps/cli/src/commands/migrate.ts。4. AI 提示词读取源端自定义提示词列表逐个在目标端创建text与appliesTo字段若创建后的默认启用状态与源端不一致再调用更新接口对齐enabled状态apps/cli/src/commands/migrate.ts。5. Webhook只迁移 Webhook 的url与events事件配置由于 API 无法读取 tokentoken 一律不迁移apps/cli/src/commands/migrate.ts。迁移完成后需要在目标端手动重新配置认证 token。6. 标签按名称确保存在遍历源端标签按name在目标端创建目标端已存在同名标签时忽略重复错误apps/cli/src/commands/migrate.ts。之后重新拉取目标端标签列表建立“标签名 → 目标端 ID”的映射供规则重映射与书签标签挂接使用。7. 规则引擎规则ID 重映射规则中引用了标签、列表、RSS 源等实体的 ID迁移时必须把旧 ID 替换为目标端对应实体的新 IDapps/cli/src/commands/migrate.ts条件hasTag中的tagId、importedFromFeed中的feedId以及and/or组合条件会被递归重映射事件tagAdded/tagRemoved的tagId、addedToList/removedFromList的listIds会被重映射动作addTag/removeTag的tagId、addToList/removeFromList的listId会被重映射。注意规则迁移依赖标签、列表、RSS 源的 ID 映射表。源码中的规则迁移步骤只有在--exclude-rules、--exclude-lists、--exclude-feeds、--exclude-tags四个选项均未启用时才会执行apps/cli/src/commands/migrate.ts即排除了列表/源/标签后规则也不会迁移。8. 书签链接、文本与资产书签迁移是整个流程的核心按分页游标分批读取源端书签apps/cli/src/commands/migrate.ts链接书签按url创建目标端相同 URL 已存在时会被去重但后续仍会为其挂接标签与列表文本书签笔记迁移text内容与可选的sourceUrl资产书签先从源服务器下载原始文件GET /api/assets/{assetId}携带源端 Bearer token再以 multipart 表单上传到目标服务器POST /api/assets最后用返回的新assetId创建书签下载或上传失败的资产会被跳过并计入 skipped 统计不影响其余书签书签创建后会按名称把源端标签挂接到新书签保留attachedBy归属信息并通过之前建立的列表 ID 映射把书签加入对应的目标端列表。每条书签会保留title、archived、favourited、note、summary、createdAt、source等元信息迁移时源 URL 通过srcServer/srcApiKey传入目标上传地址通过destServer/destApiKey传入这意味着两端服务器均需能被 CLI 所在机器访问。迁移前需要了解的预期行为列表以父级优先的顺序重建层级关系完整保留。RSS 源、提示词、Webhook、标签按“值”重建按内容/名称而非按 ID。规则在所有 ID标签、列表、RSS 源重映射为目标端对应 ID 之后创建。每条书签创建后都会自动挂上正确的标签并加入正确的列表。注意事项与建议Webhook 认证 token 必须迁移后在目标端手动重新填写这是 API 层面的硬限制。若目标服务器已包含数据重复的链接会被去重即便如此标签和列表归属仍会应用到已存在的书签上不会丢失关联关系。迁移是长时任务建议在网络稳定、负载较低的时段执行并保持终端会话不被中断必要时配合--yes与nohup/tmux等方式运行。故障排查命令中途退出怎么办migrate命令整体上不是原子操作中途失败后可以直接重跑但需要注意各类数据的幂等性不同apps/cli/src/commands/migrate.ts 在异常时会打印失败原因并退出标签与列表已存在的会被直接复用不会重复创建链接书签URL 去重避免产生重复链接笔记与资产书签则会被重新创建资产书签可能因此产生重复需人工核对规则、Webhook、RSS 源会再次创建重跑后需要手动清理目标端重复的旧记录进度日志每阶段的进度输出会明确显示已完成的量可根据日志判断中断点与剩余进度。性能与负载如果源或目标服务器处于高负载状态请调小--batch-size例如--batch-size 25来降低单页请求压力反之希望加快迁移时可尝试调大但不会超过 100 的上限。其他排查思路确认两端 API Key 有效且未过期可先用karakeep --server-addr url --api-key key whoami验证连通性与鉴权whoami命令定义于 apps/cli/src/commands/whoami.ts。确认两端版本兼容迁移通过标准 tRPC/HTTP API 进行若目标端为旧版本建议先升级目标端再迁移。资产迁移失败时命令会跳过该资产并累计 skipped 数量可先定位是源端下载失败还是目标端上传失败如存储配额、上传大小限制再决定重跑或手动处理。相关资源CLI 命令注册入口apps/cli/src/index.ts迁移命令完整实现apps/cli/src/commands/migrate.tsCLI 与服务器通信层apps/cli/src/lib/trpc.tsCLI 配置与默认服务器地址apps/cli/src/lib/config.tsCLI 包信息与安装方式apps/cli/package.json当前版本文档含本主题的未版本化版本docs/docs/06-administration/06-server-migration.md命令行集成综述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），仅供参考
