AI 助理
文档备案控制台
官方文档
首页 数据传输服务 操作指南 数据准备（新控制台） 实践手册：将钉钉接入到DTS RAGFlow知识库

实践手册：将钉钉接入到DTS RAGFlow知识库

更新时间：
复制 MD 格式
产品详情
我的收藏

本文介绍如何将钉钉中的数据同步到DTS的RAGFlow知识库。DTS支持钉盘方式（通过开放平台API）和MCP方式（通过钉钉MCP协议）两种接入方式。

前提条件

已在DTS创建RAGFlow知识库并设置IP白名单。

支持的数据类型

MCP方式

DTS RAGFlow支持通过MCP协议接入钉钉知识库中的文档。不同文档类型的处理方式如下：

文档类型

扩展名

处理方式

在线文档

adoc

通过钉钉文档MCP拉取Markdown内容，以.md格式上传至RAGFlow。

电子表格

axls

通过钉钉电子表格MCP拉取数据并导出为.csv格式上传至RAGFlow。若未配置dingDingSheetMcpEndpoint参数，则跳过该类型文件。

普通附件

其他

通过文档MCP下载原始文件并上传至RAGFlow。

演示文稿、脑图、白板、多维表

appt、amind、adraw、able

不支持，标记为unsupported-source-type并写入checkpoint。

钉盘方式

DTS RAGFlow支持接入钉钉中的钉盘（钉钉云盘）文件，支持的类型有：

  • 钉盘中创建的Word、Excel、PowerPoint。

  • 钉盘中上传的文件，例如TXT、PDF、Markdown等。

准备工作

DTS支持通过以下两种方式接入钉钉数据源，请根据实际情况选择：

  • MCP方式（推荐）：通过钉钉MCP协议接入，无需创建应用，配置更简单，性能更好。

  • 钉盘方式：通过钉钉开放平台API接入，支持钉盘文件，需要创建钉钉应用并配置权限。

MCP方式

步骤一：获取MCP Server Endpoint

钉钉文档和电子表格各对应一个独立的MCP Server，您需要分别开通并获取对应的Endpoint。

  1. 进入钉钉MCP市场，开通以下MCP服务：

    • 钉钉文档MCP（必选）：支持文档内容读取和文件下载。开通地址：钉钉文档MCP。

    • 钉钉电子表格MCP（可选）：支持电子表格数据读取。若不开通，知识库中的电子表格文件将被跳过。开通地址：钉钉电子表格MCP。

  2. 在MCP市场的服务详情页，复制Streamable-HTTP Endpoint，格式如下：

    https://mcp-gw.dingtalk.com/server/<server_id>?key=<key>
重要

Endpoint中的key参数是访问凭证，请妥善保管，不要将其提交到Git仓库或发布到公共渠道。

步骤二：获取WorkSpaceId

WorkSpaceId是钉钉知识库的唯一标识，可从知识库首页URL中获取。

  1. 在浏览器中打开目标钉钉知识库的首页，URL格式如下：

    https://alidocs.dingtalk.com/i/space/{WorkSpaceId}

  2. 从URL中复制{WorkSpaceId}部分。例如URL为https://alidocs.dingtalk.com/i/space/nb9XJj73Oxxxx，则WorkSpaceId为nb9XJj73Oxxxx。

步骤三：获取RootFolderIds（可选）

如果您只需要同步知识库下的部分子目录而非整个知识库，则需要获取目标子目录的节点ID。不配置此参数时，KBSync将从知识库根目录递归遍历全部节点。

  1. 在钉钉知识库网页端打开目标子目录，URL格式如下：

    https://alidocs.dingtalk.com/i/nodes/{nodeId}

  2. 从URL中复制{nodeId}部分。如果需要同步多个子目录，将多个nodeId用英文逗号分隔。

钉盘方式

步骤一：创建钉钉应用并配置权限

  1. 登录钉钉开放平台，并进入开发者后台。

  2. 创建应用。

    1. 单击页面右上角的我的后台。

    2. 单击应用开发页签，在左侧导航栏选择企业内部应用 > 钉钉应用。

    3. 单击创建应用。

    4. 输入应用名称和应用描述，单击保存。

    5. 在该应用的右侧，选择image > 应用详情。

    6. 在左侧导航栏，选择基础信息> 凭证与基础信息。

    7. 在应用凭证区域，记录Client ID和Client Secret。

  3. 配置权限。在左侧导航栏，选择开发配置 > 权限管理，勾选以下权限：

    • 钉盘应用盘空间读权限

    • 成员信息读权限

    • 企业存储文件读权限

    • 企业存储文件下载信息读权限

  4. 单击批量申请。

步骤二：获取钉钉账号的员工UserID

  1. 使用具有企业或团队管理员权限的钉钉账号，登录钉钉管理后台。

  2. 在左侧导航栏，选择通讯录 > 成员管理。

  3. 选择部门，记录目标钉钉账号的员工UserID。

    重要

    钉钉账号须具备目标文件（钉盘）的管理权限，能够查看和下载目标文件。

操作步骤

  1. 获取KBSync文件。

    说明

    您可以添加钉钉群（群号：79690034672），联系技术支持人员以获取KBSync文件。

  2. 准备KBSync程序的运行环境。

    说明

    运行KBSync程序需要Linux环境，且网络需能访问钉钉MCP服务和RAGFlow服务。

  3. 准备配置文件config。

    1. 创建名为config的Linux系统文件。

    2. 将以下代码复制到config文件中。

      MCP方式

      whiteList=
blackList=
sinkType=RagFlowV2
sourceType=DingDingV3
ragflowUrl=http://XX.XX.XX.XX
ragflowApiKey=Bearer ragflow-Rh******BiYWY3MDAxNj
ragflowDatasetId=b2af7c4c******dbae
dingDingMcpEndpoint=https://mcp-gw.dingtalk.com/server/<server_id>?key=<key>
dingDingSheetMcpEndpoint=https://mcp-gw.dingtalk.com/server/<server_id>?key=<key>
dingDingWorkSpaceId=nb9XJj73Oxxxx
dingDingRootFolderIds=

      钉盘方式

      whiteList=
blackList=
sinkType=RagFlowV2
sourceType=DingDing
ragflowUrl=http://XX.XX.XX.XX
ragflowApiKey=Bearer ragflow-Rh******BiYWY3MDAxNj
ragflowDatasetId=b2af7c4c******dbae
dingDingClientId=dingz******k66u
dingDingClientSecret=sa4vI******xrJT-OmEf_fgF0GpbKi4L******tzugFn-_
dingDingUserId=012******815010

  4. 替换config文件中的参数。

    重要

    • 无需配置的参数，将其取值设置为空值即可。

    • 参数blackList的优先级高于参数whiteList。

    参数

    是否必填

    说明

    获取方式

    whiteList

    否

    需要传输（白名单）和无需传输（黑名单）的路径，包含知识库中文档所在的路径。

    说明

    支持正则表达式，多个路径需使用空格分隔。

    自行在钉钉知识库中获取。

    blackList

    否

    sinkType

    是

    目标端的类型。

    固定为RagFlowV2。

    sourceType

    是

    源端的类型。

    • 钉盘方式取值DingDingV2。

    • MCP方式取值DingDingV3。

    ragflowUrl

    是

    RAGFlow的地址（API服务器）。

    获取RAGFlow知识库的API服务地址。

    ragflowApiKey

    是

    RAGFlow知识库的API Key。

    获取RAGFlow知识库的API Key。

    ragflowDatasetId

    是

    RAGFlow知识库的ID。

    获取RAGFlow知识库的ID。

    dingDingClientId

    是（钉盘方式）

    钉钉应用的Client ID。仅钉盘方式需要配置。

    准备工作-钉盘方式中获取。

    dingDingClientSecret

    是（钉盘方式）

    钉钉应用的Client Secret。仅钉盘方式需要配置。

    准备工作-钉盘方式中获取。

    dingDingUserId

    是（钉盘方式）

    导出钉盘文件的钉钉账号的员工UserID。仅钉盘方式需要配置。

    准备工作-钉盘方式中获取。

    dingDingMcpEndpoint

    是（MCP方式）

    钉钉文档MCP的Endpoint地址，用于读取在线文档内容和下载附件。仅MCP方式需要配置。

    获取MCP Server Endpoint。

    dingDingSheetMcpEndpoint

    否（MCP方式）

    钉钉电子表格MCP的Endpoint地址，用于读取电子表格数据。仅MCP方式需要配置。未配置时，axls类型的文件将被跳过并写入checkpoint。

    获取MCP Server Endpoint。

    dingDingWorkSpaceId

    是（MCP方式）

    目标钉钉知识库的ID。仅MCP方式需要配置。

    获取WorkSpaceId。

    dingDingRootFolderIds

    否（MCP方式）

    限定同步的根目录ID，多个ID之间使用英文逗号分隔。不配置时，KBSync将同步整个知识库。

    获取RootFolderIds。

  5. 将KBSync文件和配置文件config，放在Linux环境中的同一目录中。

  6. 在Linux环境中执行./KBSync --config config命令，运行KBSync程序。

  7. MCP方式

    等待KBSync程序同步数据，若运行结果如下所示，则表示KBSync已成功连接并开始同步。

    ./KBSync --config config
 
INFO config SourceType=DingDingV3, SinkType=RagFlowV2
INFO config whiteList=, blackList=
INFO config ragflowUrl=http://XX.XX.XX.XX, ragflowApiKey=Bearer ragflow-RhMjc0NjFhNTZmNTExZjBiYWY****
INFO config ragflowDatasetId=b2af7c4c56f511f0a3d700163e0****
INFO config dingDingMcpEndpoint=https://mcp-gw.dingtalk.com/server/<server_id>?key=****
INFO config dingDingSheetMcpEndpoint=https://mcp-gw.dingtalk.com/server/<server_id>?key=****
INFO config dingDingWorkSpaceId=nb9XJj73Ox37lXyA
INFO Verifying RAGFlow connection...
INFO Attempting to list datasets to validate the connection...
INFO Successfully found matching dataset: Name='test', ID='b2af7c4c56f511f0a3d700163e****'
INFO RAGFlow connection verified successfully.
INFO Starting DingTalk MCP connection...
INFO MCP connection established successfully.
INFO Listing workspace nodes...
INFO Found 42 nodes in workspace.
INFO Syncing documents...
    说明

    KBSync程序会持续运行并定时同步数据。您可以根据需要手动暂停或重新启动程序。

    钉盘方式

    1. 选择目标文档来源，并运行KBSync程序。

      说明

      KBSync程序会定时（每隔一段时间）同步目标文档的数据。您可以根据需要设置间隔时间、手动暂停或重新启动KBSync程序。

    2. 输入2并按回车键。

      等待KBSync程序同步数据，若运行结果如下所示，则表示KBSync程序正常运行。

      ./KBSync --config config

INFO config SourceType=DingDingV2, SinkType=RagFlowV2
INFO config whiteList=, blackList=
INFO config ragflowUrl=http:///XX.XX.XX.XX, ragflowApiKey=Bearer ragflow-RhMjc0NjFhNTZmNTExZjBiYWY****
INFO config ragflowDatasetId=b2af7c4c56f511f0a3d700163e0****
INFO config dingDingClientId=ding9nyefxviedv****, dingDingClientSecret=Kh3qQZafV9vZZIwvP****-V7f3tkmYmcYibwT7zWNXrvOm4UbETOhqEt****
INFO config dingDingUserId=012713339****
NFO Verifying RAGFlow connection...
INFO Attempting to list datasets to validate the connection...
INFO Successfully found matching dataset: Name='test', ID='b2af7c4c56f511f0a3d700163e****'
INFO RAGFlow connection verified successfully.
INFO Starting DingTalk authentication process...
INFO Waiting for the initial app access token...
INFO App access token refresh loop started.
INFO Attempting to refresh the app access token...
INFO {'headers': {'server': 'DingTalk/1.0.0', 'date': 'Tue, 29 Jul 2025 09:14:19 GMT', 'content-type': 'application/json;charset=utf-8', 'transfer-encoding': 'chunked', 'connection': 'keep-alive', 'access-control-allow-origin': '*', 'access-control-expose-headers': '*', 'x-acs-request-id': 'AD15D9B5-C47D-7C06-BCE7-03AA76A****', 'x-acs-trace-id': 'ad2c67867d7153507b9a74e399****', 'access-control-allow-headers': 'X-Requested-With, X-Sequence, _aop_secret, _aop_signature, x-acs-dingtalk-access-token', 'content-encoding': 'gzip'}, 'statusCode': 200, 'body': {'accessToken': '38a7d120903c35a7aa2e866dca****', 'expireIn': 7200}}
INFO set dingding access token: 38a7d120903c35a7aa2e866dca****
INFO set dingding access token expires in: 7200
INFO App access token refreshed successfully. Next refresh scheduled in 6600 seconds.
INFO Waiting 6600 seconds until the next token refresh.
INFO Initial app access token acquired.
INFO Fetching user UnionID...
INFO set dingding union id: XYesTh9u****
INFO Successfully fetched UnionID.

附录

获取RAGFlow知识库的API服务地址

  1. 登录RAGFlow页面。

  2. 在左侧导航栏，单击API。

  3. 获取API服务器。

获取RAGFlow知识库的API Key

  1. 登录RAGFlow页面。

  2. 在左侧导航栏，单击API。

  3. 在RAGFlow API右侧，单击API KEY。

  4. 在弹出的API KEY对话框，单击创建新密钥。

  5. 单击image，记录Token。

获取RAGFlow知识库的ID

  1. 登录RAGFlow页面。

  2. 在知识库页面，单击目标知识库。

  3. 在当前页面的URL中，记录知识库的ID。

    说明

    id=之后的信息即为知识库的ID。

上一篇：实践手册：将OSS接入到DTS RAGFlow知识库下一篇：实践手册：使用DTS RAGFlow构建云原生数据仓库AnalyticDB PostgreSQL版GraphRAG