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 官方 CLI 的migrate命令把一台 Karakeep 服务器上的全部用户数据用户设置、列表、RSS 订阅、AI 提示词、Webhook、标签、规则引擎规则、书签与附件安全、有序地迁移到另一台服务器。读完本文你将掌握迁移命令的完整参数体系、各阶段迁移的内部执行顺序与底层实现原理含规则 ID 重映射、资产下载重传、链接去重等机制以及迁移中断后的断点续跑与排错策略。迁移命令能做什么migrate子命令的定位是服务器到服务器的整库迁移它从源服务器读取用户拥有的全部数据再通过目标服务器的 API 逐项写入目标服务器全程无需手工导出/导入文件。迁移按以下固定顺序执行每一阶段都有独立的进度输出见 migrate.ts 中action的实现用户设置User settings——读取src.users.settings并整体写入目标服务器列表Lists——保留父子层级与列表设置RSS 订阅源RSS feedsAI 提示词AI prompts——包含自定义提示词文本及其启用状态Webhook——只迁移 URL 与监听事件标签Tags——按名称在目标服务器上确保存在规则引擎规则Rule engine rules——把规则中引用的标签/列表/订阅源 ID 重映射为目标服务器上的对应 ID书签Bookmarks——链接、文本与附件书签创建完成后自动挂上正确标签并加入正确的列表。顺序不是随意编排的后续阶段依赖前一阶段建立的ID 映射表listIdMap、tagIdMap、feedIdMap例如规则重映射必须等标签、列表、订阅源迁移完成之后才能进行。需要特别注意的三条限制Webhook 令牌token无法通过 API 读取因此不会迁移。若目标服务器上的 Webhook 需要鉴权迁移完成后必须手动重新填写 token。附件书签Asset bookmarks通过下载原附件 → 重新上传到目标服务器的方式迁移且目前仅支持图片和 PDF两类附件书签迁移失败或被--exclude-assets跳过的附件会记入进度中的skipped计数。目标服务器上若已存在相同 URL 的链接书签新书签可能被**去重de-duplicated**合并但标签与列表归属仍会挂接到已有的那条书签上。前置条件迁移前需要准备两样东西CLI 本身以及两套服务器的访问凭据。安装 CLI官方提供两种安装方式NPM 全局安装npm install -g karakeep/cli安装后命令为karakeep在 apps/cli/package.json 中通过bin字段注册为dist/index.mjs。Docker 一次性运行docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help收集两套服务器的 API Key 与地址源服务器--server-addr基础 URL、--api-key目标服务器--dest-server、--dest-api-key。API Key 除了通过命令行参数传入CLI 还支持从环境变量读取KARAKEEP_API_KEY、KARAKEEP_SERVER_ADDR见 index.ts或写入 CLI 配置文件。配置文件默认位于~/.config/karakeep/config.json遵循XDG_CONFIG_HOME见 config.ts内容格式为{ apiKey: your-api-key, serverAddr: https://your-server.example.com }未显式指定--server-addr时CLI 会回退到默认地址https://cloud.karakeep.app请务必在迁移前确认你的源/目标服务器地址正确。快速开始迁移命令最简用法如下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命令是长时间运行的每个阶段都会打印实时进度列表显示Lists (created)、书签显示Bookmarks 123/456等。启动后 CLI 会先弹出确认提示需要输入yes或y才会真正开始若希望跳过确认可加-y/--yes。关于连接细节CLI 通过 tRPC 客户端访问两端的/api/trpc端点见 trpc.ts请求头携带authorization: Bearer API_KEY因此源/目标服务器都必须允许 API Key 认证访问。完整参数说明migrate命令的全部选项如下定义见 migrate.ts 中migrateCmd参数说明--dest-server url目标服务器基础 URL例如https://dest.example.com必填--dest-api-key key目标服务器的 API Key必填-y, --yes跳过迁移前的确认提示--batch-size n书签迁移的每页大小默认50最大100--exclude-assets排除附件书签的迁移--exclude-lists排除列表及其书签归属关系的迁移--exclude-ai-prompts排除 AI 提示词迁移--exclude-rules排除规则引擎规则迁移--exclude-feeds排除 RSS 订阅源迁移--exclude-webhooks排除 Webhook 迁移--exclude-bookmarks排除书签迁移--exclude-tags排除标签迁移--exclude-user-settings排除用户设置迁移注意--batch-size的上限100不是随意定的它在 packages/shared/types/bookmarks.ts 中定义为MAX_NUM_BOOKMARKS_PER_PAGE 100服务端分页接口getBookmarks的limit参数本身就限制单页最多 100 条。CLI 侧解析时也会用Math.min(Number(v || 50), MAX_NUM_BOOKMARKS_PER_PAGE)做钳制防止传入越界值。原文档只列出 6 个参数但从源码看 CLI 还提供了上面这一整套--exclude-*开关适合只迁移部分数据、或目标服务器已有部分数据的场景。不过要注意排除某个阶段会影响依赖它的后续阶段。例如源码中规则迁移有一个前置条件——只有excludeRules、excludeLists、excludeFeeds、excludeTags四个开关全部未开启时才会执行规则迁移因为规则 ID 重映射需要这三张映射表同理书签的列表归属buildBookmarkListMembership仅在列表与书签都未排除时执行。迁移过程中会发生什么1. 列表父级优先创建保留层级列表迁移在 migrateLists 中实现采用**父级优先parent-first**策略先读取源服务器全部列表再反复扫描剩余列表只有当某个列表的父列表已在目标服务器创建完成后才处理它。若所有列表都因缺少父级而无法解析命令会抛出Could not resolve list hierarchy due to missing parents错误。创建时会按name、icon、description、type、query、parentId这几个属性尝试匹配目标服务器上已有的同名列表匹配到则直接复用否则新建。列表的public可见性标志如果源上是布尔值会在创建后通过edit尽力对齐。整个过程会维护一张srcListId → destListId映射表供后续规则重映射与书签归属使用。2. 订阅源、提示词与 Webhook按值重建RSS 订阅源逐个读取name、url、enabled并创建同时记录 ID 映射AI 提示词创建text与appliesTo若目标上新创建的提示词默认启用状态与源不一致会再调用update把enabled对齐Webhook只创建url与events不携带 tokenAPI 无法读取源码注释明确说明tokens cannot be read; created without token。3. 标签按名称确保存在标签迁移在 migrateTags 中实现对源服务器的每个标签按名称调用create若目标已存在同名标签创建会失败并被静默忽略Ignore duplicate errors。随后拉取目标服务器当前全部标签构建tagName → destTagId映射再反推srcTagId → destTagId映射供规则使用。4. 规则引擎规则ID 重映射这是整个迁移中最精巧的部分。规则Rule由event触发事件、condition条件树、actions动作列表三部分组成其中会引用标签、列表、订阅源的 ID。由于目标服务器上的 ID 与原服务器完全不同remapRuleIds 会对规则的每个组成部分做递归重映射条件conditionhasTag重映射tagIdimportedFromFeed重映射feedIdand/or递归处理子条件事件eventtagAdded/tagRemoved重映射tagIdaddedToList/removedFromList重映射listIds数组动作actionsaddTag/removeTag重映射tagIdaddToList/removeFromList重映射listId。映射不到的 ID 会保留原值maps.xxx.get(id) ?? id单条规则迁移失败不会中断整体流程而是打印错误后继续下一条。5. 书签链接、文本与附件分类型处理书签迁移是耗时最长的阶段按--batch-size分页拉取游标分页见ZCursor对每条书签按内容类型分流链接书签在目标创建LINK类型书签写入url以及通用字段title、archived、favourited、note、summary、createdAt、source并固定使用crawlPriority: low以降低对目标服务器的抓取压力文本书签创建TEXT类型书签写入text与可选的sourceUrl附件书签先从源服务器GET /api/assets/{assetId}携带源 API Key下载原始二进制再以multipart/form-data形式POST到目标服务器的/api/assets完成上传最后用返回的新assetId创建ASSET书签。任一步骤失败都会计入skipped并继续下一条。书签创建完成后还有两步收尾挂标签调用updateTags按tagNameattachedBy附加源书签的全部标签加列表利用迁移早期建立的bookmarkListsMap源书签 → 源列表 ID 列表与listIdMap把书签加入目标服务器上对应的列表。注意bookmarkListsMap只扫描type manual的列表动态列表不存成员关系。6. 进度与统计命令启动时会先尝试调用src.users.stats预取书签总数用于进度百分比显示若统计接口不可用则进度不带总数。迁移完成后会打印各阶段耗时与总数例如Lists (created) 5 created in 12s、Bookmarks 123 migrated, 2 skipped in 300s。所有进度渲染逻辑stepStart/stepEndSuccess/progressUpdate都在同一文件中实现在 TTY 下用回车覆盖式刷新非 TTY 下退化为逐行打印。注意事项与实用技巧Webhook 鉴权令牌需手动补齐迁移后到目标服务器设置页为每个 Webhook 重新填写 token目标服务器已有数据时同名列表、同名列表情形会被复用相同 URL 的链接书签可能被去重合并但标签与列表归属仍会正确挂接到已有书签上善用--exclude-*做定向迁移例如只想搬书签时可加--exclude-user-settings --exclude-lists --exclude-ai-prompts --exclude-rules --exclude-feeds --exclude-webhooks --exclude-tags但要注意排除列表会导致书签不再附加列表归属控制批量大小源或目标服务器负载较高时调小--batch-size如--batch-size 20可降低单次 API 请求的压力代价是请求次数变多、整体更慢。排错与断点续跑如果命令中途退出网络抖动、服务器过载、API 限流等直接重新运行同一命令即可因为各阶段天然具备幂等性标签与列表已存在的会直接复用不会重复创建链接书签URL 去重机制避免产生重复链接书签文本与附件书签会被重新创建可能产生重复需留意规则、Webhook、RSS 订阅源会被重新创建重跑后需要手动清理目标服务器上的重复项进度日志退出前的进度日志From:/To:头、各阶段计数能直观指示上次跑到哪一步。其余常见问题提示缺少 API Key确认--api-key已传入或已设置KARAKEEP_API_KEY环境变量 / 配置文件index.ts 中会优先合并命令行、环境变量与配置文件三者都缺失才报错--dest-server或--dest-api-key缺失这是必填项命令会直接拒绝执行列表层级无法解析报Could not resolve list hierarchy due to missing parents检查源服务器列表数据是否完整附件书签全部被跳过确认附件类型是图片或 PDF且源/目标服务器都启用了附件存储。相关资源CLI 迁移命令完整实现apps/cli/src/commands/migrate.tsCLI 入口与全局参数解析apps/cli/src/index.tsCLI 配置加载与默认服务器地址apps/cli/src/lib/config.tstRPC 客户端源/目标双客户端构造apps/cli/src/lib/trpc.ts分页大小上限定义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），仅供参考