ContextDB Sync是一款运行在本地的文档同步工具，可将钉钉、飞书和本机文件夹中的内容持续同步到RDS ContextDB知识库。您可以在同步工具的网页中配置数据来源、选择同步目录、执行同步并查看运行结果。
功能简介
ContextDB Sync支持以下数据来源：
数据来源 | 支持范围 | 连接方式 |
钉钉 | 钉钉知识库、文件夹、在线文档、电子表格和附件 | 使用钉钉文档MCP地址连接，电子表格需要单独的表格MCP地址。 |
飞书 | 当前用户可访问的团队Wiki、个人知识库、云空间和普通文件 | 登录飞书用户账号并授予只读文档权限 |
本地文件夹 | 本机普通文件夹 | 填写同步服务所在机器上的文件夹绝对路径 |
每个同步任务用于维护一个来源范围与一个目标 ContextDB 知识库之间的同步关系。您可以为不同知识库、文件夹或本地目录分别创建任务。
除ContextDB Sync同步工具外，您也可以通过Agent或控制台直接上传本地文件。
前提条件
使用ContextDB Sync前，请完成以下准备：
已开通RDS ContextDB，创建工作空间并保存API Key。
已安装Node.js 20或更高版本。
根据不同的数据源分别准备连接配置信息：
钉钉：准备完整的钉钉文档MCP地址；如需同步电子表格，还需准备钉钉表格MCP地址。
飞书：准备一个能够读取所选云盘、知识库或指定飞书链接内容的飞书用户账号。
本地文件夹：确保文件夹位于本地，且当前系统用户拥有读取权限。
使用限制
数据仅从数据源单向同步至ContextDB，不会修改或删除数据源内容。当数据源中的文档被删除、移出同步范围，或对应的同步任务被移除时，已上传至ContextDB的文档不会自动删除。若数据源中的文档被移动或重命名后，可能会作为新文档再次同步，从而产生新旧两份文档。
未发生变化的内容会在后续运行中跳过，所选范围内新增的文件和修改的内容会在下一次成功运行时同步。
同步本地文件夹数据时会跳过隐藏项、符号链接和未完整下载的临时文件，iCloud、Dropbox等云盘文件需要先完整下载到本机。
文件支持范围按最终扩展名判断。文本和代码文件最大为20 MB，复杂文档和图片最大为500 MB，音频最大为10 MB，视频最大为2 GB，无扩展名或不支持的扩展名会被跳过。
飞书在线文档同步时会导出为
.docx文件，电子表格和多维表格会导出为.xlsx文件；钉钉在线文档会转换为.md文件，电子表格会转换为.csv文件。其他普通文件保留原格式上传。
安装并启动同步服务
安装：运行以下命令安装ContextDB Sync：
npm install -g @aliyunrds/ctxdb-sync启动：安装完成后，启动同步服务并打开管理页面：
ctxdb-sync start
ctxdb-sync open --browser重启/停止：日常可使用以下命令重启或停止同步服务：
ctxdb-sync restart
ctxdb-sync stop更新：已安装ContextDB Sync时，请等待当前同步结束，然后运行以下命令更新到最新版本：
ctxdb-sync stop
npm install -g @aliyunrds/ctxdb-sync@latest首次配置与连接验证
首次打开ContextDB Sync时，页面会通过四个步骤引导您完成配置。连接检查和任务验证均为只读操作，不会在验证阶段上传文档。
步骤一：选择写入位置
填写ContextDB API Key。
等待页面连接ContextDB并加载当前账号可用的知识库。
从列表中选择目标知识库，或输入一个新的知识库名称。
单击继续选择来源。
API Key和来源连接凭据仅保存在本机。请勿将其放入聊天记录、日志、截图或代码仓库。
步骤二：选择与配置数据源
在选择数据来源页面选择钉钉、飞书或本地文件夹。首次配置只需选择一种来源，进入工作台后仍可继续接入其他来源。
根据选择的数据源完成连接配置，完成后单击继续。
钉钉
填写完整的钉钉文档 MCP 地址。
（可选）如需同步电子表格，还需填写表格 MCP 地址。
填写需要同步的知识库或文件夹链接，可添加多个范围。
飞书
连接飞书账号并授予只读文档权限，然后选择同步方式：
同步我的工作区：从工作区的云盘和知识库中选择需要同步的目录或文档。
导入指定目录：填写需要同步的知识库或文件夹链接，可添加多个范围。
本地文件夹
单击选择文件夹选择本机目录，也可以手动填写本地文件夹的绝对路径。同步服务只读扫描该目录，不会修改本地文件。
步骤三：连接验证
确认同步任务中目标知识库正确无误。
根据需要开启自动同步并设置同步间隔。首次配置默认不开启自动同步。
单击验证并进入工作台。连接检查和任务验证均为只读操作，不会在验证阶段上传文档。
如果验证未通过，请按照页面提示检查ContextDB连接、来源连接、资源权限或本地文件夹读取权限，修复后重新验证。
确认同步范围并开启同步任务
进入工作台后，新任务不会立即上传全部内容。您需要先确认该任务持续同步的范围：
在同步任务列表中单击目标任务，等待目录加载完成。目录未正常显示时，单击刷新目录。
在展开的目录树中勾选需要同步的目录或文档。选择文件夹后，该文件夹中后续新增的内容也会进入同步范围。
核对选择结果，单击确认范围并同步。系统会保存当前任务的持续同步范围，并启动首次同步。
只有已启用、配置完整且范围已经确认的任务才能参与手动同步或自动同步。
管理同步任务
取消同步：需要停止当前任务时，可以单击取消同步。取消后，已经上传的内容会保留，尚未开始的内容停止处理。任务本身不会被删除，后续仍可手动运行或按原计划自动同步。
编辑任务： 单击任务页的右上方的编辑任务，可以修改任务名称、目标知识库、来源范围或本地文件夹路径，也可以暂停或恢复任务。编辑任务时需要注意：
平台连接和同步时间等内容属于平台级共享连接，不在当前任务编辑页中修改。如需调整，请前往顶栏右上角的设置图标中修改对应平台的连接。
更换目标知识库只会改变后续同步的写入位置，不会移动或删除原知识库中已经上传的文档。
修改来源范围后，可能需要重新加载目录并确认同步范围。
修改钉钉 MCP 连接或切换飞书账号，会影响该平台下的全部同步任务。修改前请确认其他任务仍能访问其来源内容。
设置自动同步
自动同步按来源平台统一设置：
点击页面右上角的设置按钮，选择需要管理的来源平台，单击打开设置。
开启自动同步，设置同步间隔。
保存平台设置。
开启自动同步后，同一来源平台下所有已启用、配置完整且已确认同步范围的任务，使用同一间隔顺序依次运行。钉钉、飞书和本地文件夹分别调度，互不影响。
到达计划同步时间时，如果该平台上一轮同步仍未结束，本次会跳过；系统将在下一个计划时间再次检查，不会重复排队。自动同步均按设定间隔检查内容变化，并非实时事件同步。
查看运行记录
在左侧导航栏中单击运行记录，可以按同步任务、运行结果和触发方式筛选正式同步记录，接入多个平台后可以按平台筛选。每条记录会显示手动或自动触发方式、完成时间以及上传、跳过、冲突和失败数量。
打开运行详情可以查看各任务和文档的处理结果。发生失败时，请根据详情中的提示修复连接、权限、文件格式或目标冲突后重新同步。
运行记录保留最近3,000次正式同步，最长保留30天。
接入更多数据源平台
点击页面右上角的设置按钮。
在接入新平台处单击接入钉钉、接入飞书或接入本地文件夹（当前仅支持这三种数据源平台），该区域只显示尚未接入的平台。
完成平台连接并保存设置。
为新平台创建同步任务，加载目录并确认同步范围。