尧图网站建设 
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 服务器完整迁移到另一台服务器。文章以 v0.31.0 官方管理文档为主体结合当前仓库中 migrate 命令的完整实现深入剖析迁移顺序、各数据类型的迁移策略、全部命令行参数、重跑幂等性以及故障排查方法。读完本文你将能独立完成一次安全、可预期的 Karakeep 服务器迁移。迁移命令能做什么数据范围与迁移顺序karakeep migrate是官方 CLI 提供的一站式数据迁移工具它把用户拥有user-owned的数据从源服务器复制到目标服务器覆盖范围包括用户设置user settings列表lists并保留层级结构与设置RSS 订阅源RSS feedsAI 提示词自定义 prompt 及其启用状态WebhookURL 与触发事件标签按名称确保在目标端存在规则引擎规则规则中的 ID 会重映射为目标端对应的 ID书签链接、文本、资源文件创建完成后会自动挂接正确的标签并加入正确的列表这些阶段的执行顺序在源码中与文档完全一致见 migrate.ts 的 action 主流程用户设置 → 列表 → 订阅源 → AI 提示词 → Webhook → 标签 → 规则 → 书签。这一顺序并非随意排列而是严格遵循依赖关系标签、列表、订阅源必须先迁移才能在迁移规则时把规则内部引用的 ID 重映射为目标端 ID列表必须先迁移才能在迁移书签时把书签加入对应列表。迁移边界重要说明Webhook token 无法迁移token 无法通过 API 读取因此迁移后需要在目标端手动重新添加认证 token。资源类书签的迁移方式资源书签通过「从源端下载原始资源 → 重新上传到目标端」实现目前仅支持图片和 PDF 类型的资源书签。链接书签可能被去重如果目标端已存在相同 URL 的链接书签可能被去重去重后标签与列表归属仍会应用到已存在的书签上。从源码看迁移实现阶段化、实时进度与幂等设计阶段化执行与实时进度迁移命令被设计为**长时间运行long-running**任务每个阶段都会输出独立的进度。源码中定义了stepStart/stepEndSuccess/stepEndFail/progressUpdate等辅助函数migrate.ts执行效果如下每阶段开始打印阶段名 …过程中通过progressUpdate实时刷新当前数/总数例如Bookmarks 123/456阶段结束输出✓成功或✗失败以及耗时例如25 created in 3s在 TTY 终端下进度会原地刷新clearLinecursorTo非 TTY如管道重定向则逐行打印方便记录日志。另外在开始迁移前命令会调用源端的用户统计接口预取书签总数migrate.ts用于显示总进度若统计接口失败则只显示累计数量不影响迁移继续。确认提示与--yes不带-y/--yes时命令会通过readline交互式询问About to migrate data from https://src.example.com to https://dest.example.com. Proceed? (yes/no):输入y或yes继续其余输入含直接回车均视为中止migrate.ts。自动化场景请使用--yes跳过确认。前置条件安装 CLI 与准备凭证安装 CLI两种官方安装方式# NPM 全局安装 npm install -g karakeep/cli # Docker 方式直接查看帮助确认可用性 docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help在仓库中CLI 位于 apps/cli包名为karakeep/cli版本为 0.33.2见 apps/cli/package.json二进制入口为karakeep。收集两台服务器的 API Key 与 Base URL角色参数说明源服务器--server-addr url源服务器基础 URL源服务器--api-key key源服务器 API Key目标服务器--dest-server url目标服务器基础 URL目标服务器--dest-api-key key目标服务器 API Key--server-addr与--api-key是 CLI 的全局参数在 index.ts 中定义支持通过环境变量KARAKEEP_SERVER_ADDR与KARAKEEP_API_KEY传入也可以写入配置文件。配置文件的默认路径为$XDG_CONFIG_HOME/karakeep/config.json未设置XDG_CONFIG_HOME时为~/.config/karakeep/config.json格式为{apiKey: ..., serverAddr: ...}解析逻辑见 apps/cli/src/lib/config.ts。若未显式指定且配置文件中没有--api-keyCLI 会直接报错退出。注意CLI 的默认服务器地址为https://cloud.karakeep.app官方云服务见 config.ts自托管用户务必显式指定自己的服务器地址。快速开始一条命令完成迁移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该命令会依序执行全部迁移阶段并实时展示进度最后询问是否确认执行如需无人值守追加--yeskarakeep --server-addr https://src.example.com --api-key SOURCE_API_KEY migrate \ --dest-server https://dest.example.com \ --dest-api-key DEST_API_KEY --yes全部参数详解全局参数作用于所有子命令参数环境变量说明--server-addr addrKARAKEEP_SERVER_ADDR连接的服务器地址此处为源服务器--api-key keyKARAKEEP_API_KEYAPI Key--json—以 JSON 格式输出结果migrate 子命令专属参数参数说明--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排除用户设置迁移这些--exclude-*开关在 migrate.ts 的命令定义 中逐一声明可以让迁移范围精细化到单一数据类别例如只想迁移书签而不动其他配置时可组合使用多个 exclude 参数。关于--batch-size源码中通过Math.min(Number(v || 50), MAX_NUM_BOOKMARKS_PER_PAGE)限制最大值其中MAX_NUM_BOOKMARKS_PER_PAGE 100定义于 packages/shared/types/bookmarks.ts这也与服务端 API 对分页 limit 的上限约束一致。此外从源码可以看到规则迁移要求列表、订阅源、标签三个 ID 映射表都已建立migrate.ts因此若同时排除列表、订阅源或标签规则迁移会被自动跳过。各数据类型的迁移细节源码级解析用户设置User Settings直接调用源端users.settings查询、目标端users.updateSettings写入migrate.ts。该阶段失败会导致整个迁移终止。列表Lists父级优先、按属性匹配列表迁移是最有技巧性的部分migrate.ts父级优先创建采用循环扫描的方式先创建没有父级的列表再逐层创建子列表保证层级完整若因缺少父级无法解析会抛出 Could not resolve list hierarchy due to missing parents 错误。按属性匹配复用迁移时会先拉取目标端现有列表按name、icon、description、type、query、parentId六项属性寻找完全一致的列表找到则复用而非新建计入already exists。public 可见性对齐若源列表设置了 public 布尔值且与目标端不一致会尽力通过lists.edit对齐失败则忽略。迁移过程建立srcListId - destListId的映射表供后续规则重映射与书签归属使用。RSS 订阅源Feeds按name、url、enabled三个字段逐一在目标端重建并建立 ID 映射migrate.ts。AI 提示词Prompts先按text与appliesTo创建若源端enabled状态与创建后的默认值不同再调用prompts.update对齐启用状态migrate.ts从而保证「提示词内容 启用状态」都得到迁移。Webhook仅迁移url与eventsmigrate.ts。token 不迁移因为 API 无法读取已保存的 token——这正是文档强调迁移后需在目标端重新输入 token的根因。标签Tags按名称确保存在迁移策略是按名称在目标端创建标签重复名称的创建请求会被静默忽略migrate.ts。随后拉取目标端全部标签构建源标签ID - 目标标签ID的名称映射表供规则重映射与书签标签挂接使用。规则引擎规则RulesID 三重映射规则迁移的核心是remapRuleIds函数migrate.ts它递归处理规则的**事件event、条件condition、动作action**三部分hasTag条件 /tagAdded、tagRemoved事件 /addTag、removeTag动作 → 重映射tagIdimportedFromFeed条件 → 重映射feedIdaddedToList、removedFromList事件 /addToList、removeToList动作 → 重映射listIds/listIdand/or复合条件 → 递归处理子条件。这样规则在目标端得以按新的 ID 体系重建。单条规则迁移失败只会记录错误并继续计入失败日志不会中断整体流程。书签Bookmarks三类内容 标签 列表归属书签迁移是数据量最大的阶段migrate.ts按--batch-size分页拉取链接书签以 URL 创建保留标题、归档/收藏状态、笔记、摘要、创建时间、来源等信息文本书签以text与可选的sourceUrl创建资源书签从源端/api/assets/{assetId}携带 Bearer token下载资源再以 multipart 表单上传到目标端/api/assets拿到新assetId后创建书签资源下载或上传失败会跳过该书签并计入 skipped 计数进度中显示(skipped N assets)。使用--exclude-assets可完全跳过资源书签同样计入 skipped。书签创建后会通过bookmarks.updateTags按标签名挂接标签保留attachedBy归属信息列表归属通过预建的bookmarkListsMap源书签 ID → 源列表 ID 列表由 buildBookmarkListMembership 逐列表扫描构建仅处理手动类型列表与listIdMap映射后调用lists.addToList加入对应目标列表。从实现可以推断书签迁移阶段将createdAt一并保留因此目标端书签的时间线会与源端一致同时crawlPriority被固定为low避免迁移过程对目标端爬虫队列造成压力。迁移后的预期结果列表按父级优先重建层级结构完整保留订阅源、提示词、Webhook、标签均按值by value重建规则在标签/列表/订阅源 ID 重映射完成后重建规则逻辑与原规则等价每个书签创建后自动挂接正确标签并加入正确列表全程进度日志清晰记录每个阶段完成了多少、耗时多久。注意事项与实用技巧Webhook 认证 token 需手动补录迁移只复制 URL 与事件token 必须在目标端重新输入否则 Webhook 无法正常鉴权。目标端已有数据时的行为重复链接可能被去重URL 已存在时不会新建重复书签但标签与列表归属仍会应用到已存在的书签上列表、标签按属性/名称匹配后复用。资源类型限制资源书签的迁移依赖「下载-重传」目前仅支持图片与 PDF。建议先小规模验证可在测试服务器或空目标端先跑一次观察进度日志确认各阶段正常后再进行正式迁移。故障排查中断后重跑是安全的迁移被设计为可重跑。如果命令中途退出可以再次执行同一命令但需要注意重跑时的行为差异文档原文 源码均印证标签与列表已存在的会被复用按名称/属性匹配不会产生重复链接书签URL 去重机制避免重复创建链接书签文本书签与资源书签会被重新创建可能产生重复需自行留意规则、Webhook、RSS 订阅源会重新创建重跑后需要手动清理多余副本进度日志记录了迁移进行到哪个阶段据此判断重跑起点。此外如果源端或目标端负载较高建议调小--batch-size如--batch-size 20降低单次请求压力避免超时或限流导致中断。相关资源当前版本文档docs/docs/06-administration/06-server-migration.md以及本文所依据的 v0.31.0 版本 docs/versioned_docs/version-v0.31.0/06-administration/06-server-migration.mdCLI 使用文档docs/docs/05-integrations/02-command-line.mdmigrate 命令完整实现apps/cli/src/commands/migrate.tsCLI 全局参数与入口apps/cli/src/index.tsCLI 配置文件解析apps/cli/src/lib/config.ts分页上限常量定义packages/shared/types/bookmarks.ts服务器部署方式可参考 docs/docs/02-installation/01-docker.md 与 docs/docs/03-configuration/01-environment-variables.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），仅供参考 Karakeep 服务器迁移指南：使用官方 CLI 在服务器之间无缝迁移全部数据
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 服务器完整迁移到另一台服务器。文章以 v0.31.0 官方管理文档为主体结合当前仓库中 migrate 命令的完整实现深入剖析迁移顺序、各数据类型的迁移策略、全部命令行参数、重跑幂等性以及故障排查方法。读完本文你将能独立完成一次安全、可预期的 Karakeep 服务器迁移。迁移命令能做什么数据范围与迁移顺序karakeep migrate是官方 CLI 提供的一站式数据迁移工具它把用户拥有user-owned的数据从源服务器复制到目标服务器覆盖范围包括用户设置user settings列表lists并保留层级结构与设置RSS 订阅源RSS feedsAI 提示词自定义 prompt 及其启用状态WebhookURL 与触发事件标签按名称确保在目标端存在规则引擎规则规则中的 ID 会重映射为目标端对应的 ID书签链接、文本、资源文件创建完成后会自动挂接正确的标签并加入正确的列表这些阶段的执行顺序在源码中与文档完全一致见 migrate.ts 的 action 主流程用户设置 → 列表 → 订阅源 → AI 提示词 → Webhook → 标签 → 规则 → 书签。这一顺序并非随意排列而是严格遵循依赖关系标签、列表、订阅源必须先迁移才能在迁移规则时把规则内部引用的 ID 重映射为目标端 ID列表必须先迁移才能在迁移书签时把书签加入对应列表。迁移边界重要说明Webhook token 无法迁移token 无法通过 API 读取因此迁移后需要在目标端手动重新添加认证 token。资源类书签的迁移方式资源书签通过「从源端下载原始资源 → 重新上传到目标端」实现目前仅支持图片和 PDF 类型的资源书签。链接书签可能被去重如果目标端已存在相同 URL 的链接书签可能被去重去重后标签与列表归属仍会应用到已存在的书签上。从源码看迁移实现阶段化、实时进度与幂等设计阶段化执行与实时进度迁移命令被设计为**长时间运行long-running**任务每个阶段都会输出独立的进度。源码中定义了stepStart/stepEndSuccess/stepEndFail/progressUpdate等辅助函数migrate.ts执行效果如下每阶段开始打印阶段名 …过程中通过progressUpdate实时刷新当前数/总数例如Bookmarks 123/456阶段结束输出✓成功或✗失败以及耗时例如25 created in 3s在 TTY 终端下进度会原地刷新clearLinecursorTo非 TTY如管道重定向则逐行打印方便记录日志。另外在开始迁移前命令会调用源端的用户统计接口预取书签总数migrate.ts用于显示总进度若统计接口失败则只显示累计数量不影响迁移继续。确认提示与--yes不带-y/--yes时命令会通过readline交互式询问About to migrate data from https://src.example.com to https://dest.example.com. Proceed? (yes/no):输入y或yes继续其余输入含直接回车均视为中止migrate.ts。自动化场景请使用--yes跳过确认。前置条件安装 CLI 与准备凭证安装 CLI两种官方安装方式# NPM 全局安装 npm install -g karakeep/cli # Docker 方式直接查看帮助确认可用性 docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help在仓库中CLI 位于 apps/cli包名为karakeep/cli版本为 0.33.2见 apps/cli/package.json二进制入口为karakeep。收集两台服务器的 API Key 与 Base URL角色参数说明源服务器--server-addr url源服务器基础 URL源服务器--api-key key源服务器 API Key目标服务器--dest-server url目标服务器基础 URL目标服务器--dest-api-key key目标服务器 API Key--server-addr与--api-key是 CLI 的全局参数在 index.ts 中定义支持通过环境变量KARAKEEP_SERVER_ADDR与KARAKEEP_API_KEY传入也可以写入配置文件。配置文件的默认路径为$XDG_CONFIG_HOME/karakeep/config.json未设置XDG_CONFIG_HOME时为~/.config/karakeep/config.json格式为{apiKey: ..., serverAddr: ...}解析逻辑见 apps/cli/src/lib/config.ts。若未显式指定且配置文件中没有--api-keyCLI 会直接报错退出。注意CLI 的默认服务器地址为https://cloud.karakeep.app官方云服务见 config.ts自托管用户务必显式指定自己的服务器地址。快速开始一条命令完成迁移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该命令会依序执行全部迁移阶段并实时展示进度最后询问是否确认执行如需无人值守追加--yeskarakeep --server-addr https://src.example.com --api-key SOURCE_API_KEY migrate \ --dest-server https://dest.example.com \ --dest-api-key DEST_API_KEY --yes全部参数详解全局参数作用于所有子命令参数环境变量说明--server-addr addrKARAKEEP_SERVER_ADDR连接的服务器地址此处为源服务器--api-key keyKARAKEEP_API_KEYAPI Key--json—以 JSON 格式输出结果migrate 子命令专属参数参数说明--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排除用户设置迁移这些--exclude-*开关在 migrate.ts 的命令定义 中逐一声明可以让迁移范围精细化到单一数据类别例如只想迁移书签而不动其他配置时可组合使用多个 exclude 参数。关于--batch-size源码中通过Math.min(Number(v || 50), MAX_NUM_BOOKMARKS_PER_PAGE)限制最大值其中MAX_NUM_BOOKMARKS_PER_PAGE 100定义于 packages/shared/types/bookmarks.ts这也与服务端 API 对分页 limit 的上限约束一致。此外从源码可以看到规则迁移要求列表、订阅源、标签三个 ID 映射表都已建立migrate.ts因此若同时排除列表、订阅源或标签规则迁移会被自动跳过。各数据类型的迁移细节源码级解析用户设置User Settings直接调用源端users.settings查询、目标端users.updateSettings写入migrate.ts。该阶段失败会导致整个迁移终止。列表Lists父级优先、按属性匹配列表迁移是最有技巧性的部分migrate.ts父级优先创建采用循环扫描的方式先创建没有父级的列表再逐层创建子列表保证层级完整若因缺少父级无法解析会抛出 Could not resolve list hierarchy due to missing parents 错误。按属性匹配复用迁移时会先拉取目标端现有列表按name、icon、description、type、query、parentId六项属性寻找完全一致的列表找到则复用而非新建计入already exists。public 可见性对齐若源列表设置了 public 布尔值且与目标端不一致会尽力通过lists.edit对齐失败则忽略。迁移过程建立srcListId - destListId的映射表供后续规则重映射与书签归属使用。RSS 订阅源Feeds按name、url、enabled三个字段逐一在目标端重建并建立 ID 映射migrate.ts。AI 提示词Prompts先按text与appliesTo创建若源端enabled状态与创建后的默认值不同再调用prompts.update对齐启用状态migrate.ts从而保证「提示词内容 启用状态」都得到迁移。Webhook仅迁移url与eventsmigrate.ts。token 不迁移因为 API 无法读取已保存的 token——这正是文档强调迁移后需在目标端重新输入 token的根因。标签Tags按名称确保存在迁移策略是按名称在目标端创建标签重复名称的创建请求会被静默忽略migrate.ts。随后拉取目标端全部标签构建源标签ID - 目标标签ID的名称映射表供规则重映射与书签标签挂接使用。规则引擎规则RulesID 三重映射规则迁移的核心是remapRuleIds函数migrate.ts它递归处理规则的**事件event、条件condition、动作action**三部分hasTag条件 /tagAdded、tagRemoved事件 /addTag、removeTag动作 → 重映射tagIdimportedFromFeed条件 → 重映射feedIdaddedToList、removedFromList事件 /addToList、removeToList动作 → 重映射listIds/listIdand/or复合条件 → 递归处理子条件。这样规则在目标端得以按新的 ID 体系重建。单条规则迁移失败只会记录错误并继续计入失败日志不会中断整体流程。书签Bookmarks三类内容 标签 列表归属书签迁移是数据量最大的阶段migrate.ts按--batch-size分页拉取链接书签以 URL 创建保留标题、归档/收藏状态、笔记、摘要、创建时间、来源等信息文本书签以text与可选的sourceUrl创建资源书签从源端/api/assets/{assetId}携带 Bearer token下载资源再以 multipart 表单上传到目标端/api/assets拿到新assetId后创建书签资源下载或上传失败会跳过该书签并计入 skipped 计数进度中显示(skipped N assets)。使用--exclude-assets可完全跳过资源书签同样计入 skipped。书签创建后会通过bookmarks.updateTags按标签名挂接标签保留attachedBy归属信息列表归属通过预建的bookmarkListsMap源书签 ID → 源列表 ID 列表由 buildBookmarkListMembership 逐列表扫描构建仅处理手动类型列表与listIdMap映射后调用lists.addToList加入对应目标列表。从实现可以推断书签迁移阶段将createdAt一并保留因此目标端书签的时间线会与源端一致同时crawlPriority被固定为low避免迁移过程对目标端爬虫队列造成压力。迁移后的预期结果列表按父级优先重建层级结构完整保留订阅源、提示词、Webhook、标签均按值by value重建规则在标签/列表/订阅源 ID 重映射完成后重建规则逻辑与原规则等价每个书签创建后自动挂接正确标签并加入正确列表全程进度日志清晰记录每个阶段完成了多少、耗时多久。注意事项与实用技巧Webhook 认证 token 需手动补录迁移只复制 URL 与事件token 必须在目标端重新输入否则 Webhook 无法正常鉴权。目标端已有数据时的行为重复链接可能被去重URL 已存在时不会新建重复书签但标签与列表归属仍会应用到已存在的书签上列表、标签按属性/名称匹配后复用。资源类型限制资源书签的迁移依赖「下载-重传」目前仅支持图片与 PDF。建议先小规模验证可在测试服务器或空目标端先跑一次观察进度日志确认各阶段正常后再进行正式迁移。故障排查中断后重跑是安全的迁移被设计为可重跑。如果命令中途退出可以再次执行同一命令但需要注意重跑时的行为差异文档原文 源码均印证标签与列表已存在的会被复用按名称/属性匹配不会产生重复链接书签URL 去重机制避免重复创建链接书签文本书签与资源书签会被重新创建可能产生重复需自行留意规则、Webhook、RSS 订阅源会重新创建重跑后需要手动清理多余副本进度日志记录了迁移进行到哪个阶段据此判断重跑起点。此外如果源端或目标端负载较高建议调小--batch-size如--batch-size 20降低单次请求压力避免超时或限流导致中断。相关资源当前版本文档docs/docs/06-administration/06-server-migration.md以及本文所依据的 v0.31.0 版本 docs/versioned_docs/version-v0.31.0/06-administration/06-server-migration.mdCLI 使用文档docs/docs/05-integrations/02-command-line.mdmigrate 命令完整实现apps/cli/src/commands/migrate.tsCLI 全局参数与入口apps/cli/src/index.tsCLI 配置文件解析apps/cli/src/lib/config.ts分页上限常量定义packages/shared/types/bookmarks.ts服务器部署方式可参考 docs/docs/02-installation/01-docker.md 与 docs/docs/03-configuration/01-environment-variables.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），仅供参考