飞书知识库 CDC（公测中）-实时计算 Flink版(Flink)-阿里云帮助中心

本文介绍如何使用飞书知识库 CDC 连接器。

背景信息

飞书 CDC 连接器通过周期性轮询飞书开放平台 OpenAPI，按文档编辑时间持续捕获飞书知识空间（Wiki Space）中在线文档的新增和更新。连接器输出文档的标题、链接、更新时间等元数据和 Markdown 格式正文，也可以获取文档的原始块结构，适用于 RAG 知识库构建、文档检索索引和湖仓内容同步等场景。

飞书 CDC 连接器支持的信息如下。

类别	详情
连接器类型	源表
API	Flink SQL、数据摄入 YAML
同步对象	知识空间中应用有权读取的 `doc`、`docx` 类型文档节点
全增量模式	`INITIAL`，使用流模式
增量模式	`LATEST_OFFSET`、`TIMESTAMP`，使用流模式
全量模式	`SNAPSHOT`，有界读取
数据格式	固定 Schema，不支持裁剪字段
Watermark	不支持
维表和结果表	不支持

工作原理

飞书知识库没有可供直接消费的变更事件流，飞书 CDC 通过 OpenAPI 轮询实现全量和增量读取：

每个知识空间是一个独立的读取分片。连接器按 scan.discovery.interval 周期发现新授权的知识空间。
每次拉取时，连接器列出空间内的全部节点，筛选出配置范围内的 doc、docx 文档节点，并按文档编辑时间生成本次拉取的游标位置。
游标之后的文档按编辑时间排序，单个分片单次最多输出 scan.prefix-size 篇。对每篇变化的文档，连接器读取其块结构并渲染成 Markdown 正文。
无增量变化时，连接器按 scan.poll-interval 间隔重复上述检查。

变更到 changelog 的映射

连接器按主键 node_id 输出 upsert 语义的 changelog，包含 INSERT 和 UPDATE_AFTER，不输出 UPDATE_BEFORE。

场景	输出
全量阶段首次读到的文档	INSERT
增量阶段内容或元数据变化的文档	UPDATE_AFTER

当前实现不感知文档删除：文档被删除后不再出现在节点列表中，连接器不会输出 DELETE 事件，下游中该行会保留为最后一次同步的状态。

已删除文档的清理任务建议独立进行，直接调用飞书 OpenAPI 完成比对，低频、定期执行，可选择周末或夜间等业务低峰时段，避免与同步作业的轮询叠加争抢 OpenAPI 限流。比对方式如下：

完整拉取一次知识空间节点列表（GET /open-apis/wiki/v2/spaces/{space_id}/nodes，须全部分页成功），与下游已存储的 node_id 比对，找出「下游有、列表无」的节点。
对这类节点逐个调用GET /open-apis/wiki/v2/spaces/get_node二次确认：返回节点不存在类错误的，判定为真实删除；返回权限拒绝类错误的，说明文档仍存在但应用暂时失去访问权限，不得删除；限流、网络等瞬时错误则跳过本轮，下一周期再确认。
确认为真实删除后执行清理，建议软删除，行数据保留用于审计和恢复；对误删零容忍的场景，可连续多个周期均确认删除后才执行清理。

前提条件

Flink 作业需要访问飞书开放平台 OpenAPI（默认域名为 open.feishu.cn）。作业部署在 VPC 内时，请确保具备公网访问能力。

无论使用哪种启动模式，都需要先在飞书开放平台完成应用创建和知识空间授权。

登录飞书开放平台，创建企业自建应用，获取应用的 App ID 和 App Secret。连接器使用 App ID 和 App Secret 获取并自动续期 tenant_access_token。

为应用开通本连接器所需的接口权限，并发布应用版本。连接器会调用以下飞书 OpenAPI：

API	用途
`GET /open-apis/wiki/v2/spaces`	列出应用可访问的知识空间
`GET /open-apis/wiki/v2/spaces/{space_id}/nodes`	列出知识空间中的文档节点
`GET /open-apis/wiki/v2/spaces/get_node`	解析文档节点元数据
`GET /open-apis/docx/v1/documents/{document_token}/blocks`	读取文档块内容

将应用添加为目标知识空间的成员，确保应用有权读取待同步的文档。具体操作参见飞书开放平台的知识库常见问题中“如何给应用授权访问知识库文档资源”。连接器只同步应用已被授权的 doc、docx 节点。

权限点列表

上述接口对应的具体权限点（scope）名称以飞书开放平台文档为准。授权时需要覆盖以下两类能力：

能力	对应 API	是否必需
读取知识空间和节点列表	`wiki/v2/spaces`、`wiki/v2/spaces/{space_id}/nodes`、`wiki/v2/spaces/get_node`	是
读取文档块内容	`docx/v1/documents/{document_token}/blocks`	是

使用限制

仅支持源表，不支持维表和结果表，不支持 Watermark。
只同步知识空间中应用有权读取的 doc、docx 类型节点；其他对象（表格、多维表、文件等）会被跳过。
当前实现不感知文档删除，不输出 DELETE 事件。
Flink SQL DDL 必须声明固定的 6 个物理字段和 PRIMARY KEY (node_id) NOT ENFORCED，不支持增删物理列；blocks_json 只能以 METADATA 列声明。
Flink SQL 源表虽然 workspace-id 支持逗号分隔多值，但输出到同一张源表；如需按知识库分表、维护独立 Schema，建议 YAML 数据摄入或每个知识库单独建 SQL 源表。
增量链路基于 OpenAPI 轮询，会产生持续的 API 调用。空间内文档较多时，请结合 scan.poll-interval、scan.prefix-size 和限流参数控制调用成本与新内容的同步延迟。
content 是从文档块结构渲染出的 Markdown 文本，不保证完整保留所有富媒体和结构化元素；需要原始块结构时，Flink SQL 使用 blocks_json METADATA 列，数据摄入 YAML 直接读取 blocks_json 物理列。
资源发现是累加的，调小 wiki.space-id、wiki.document-url 或 wiki.node-token 不会移除已发现的知识空间或文档。
故障恢复可能重复输出 INSERT 和 UPDATE_AFTER，建议下游按主键 node_id 幂等写入。
YAML Schema 与 SQL Schema 不同：YAML 额外包含 space_id 物理列，且 blocks_json 为物理列而非 METADATA 列。请根据接入方式选择对应的 Schema 定义。

启动模式

通过 scan.startup.mode 选择读取方式。

模式	是否读取全量	是否读取增量	首次启动行为
`INITIAL`	是	是	先全量读取范围内的文档，再持续轮询增量变化
`SNAPSHOT`	是	否	只全量读取范围内的文档，完成后结束
`TIMESTAMP`	否	是	读取更新时间不早于 `scan.startup.timestamp-millis` 的文档，再持续轮询增量变化
`LATEST_OFFSET`	否	是	只处理作业启动后发生的文档变化

运行过程中新发现的知识空间或文档按 scan.new-split.startup.mode 决定读取方式：initial 先读取当前完整内容再跟随后续变化；latest-offset 只处理发现之后发生的变化。

同步范围

Flink SQL 和数据摄入 YAML 对同步范围的配置能力不同：

能力	Flink SQL	数据摄入 YAML
`wiki.space-id`	必填，只能填写一个值	可选，支持逗号分隔多个值；不配置时自动发现全部可见空间
`wiki.document-url` / `wiki.node-token`	最多配置一个，且只能填写一篇文档	支持逗号分隔多个值
多空间同步方式	每个空间创建一张源表	单个作业内按空间自动分表（`<spaceId>.documents`）

未配置文档选择器时，空间内应用有权读取的全部 doc、docx 文档都会被同步。

注意：数据摄入 YAML 配置文档选择器后，默认整体同步配置空间并自动发现包含所选文档的未配置空间。需要严格边界时请将 wiki.restrict-documents-to-selected-spaces 设为 true，详见「数据摄入 > 空间到表的路由」。

Flink SQL 如需把范围收窄到空间内的某一篇文档，可以二选一配置：

wiki.document-url：填写飞书文档链接，连接器从链接中解析文档标识，支持常见的 wiki、docx、docs 等文档地址形式。
wiki.node-token：直接填写知识空间中的节点 Token。

两个参数最多配置一个，且所选文档必须属于 wiki.space-id 配置的空间。配置后，全量和增量都只处理这一篇文档。YAML 侧文档选择器支持多篇文档，行为详见数据摄入章节。

资源发现是累加的：知识空间或文档一旦被作业发现，即使之后调小范围配置，也不会从已有作业中移除。按整个空间同步的作业，空间内后续新增的文档会被正常轮询发现，不需要修改配置。需要彻底移除时，请停止作业并无状态重新启动。

SQL

语法结构

CREATE TEMPORARY TABLE <yourTableName> (
  node_id STRING NOT NULL,
  title STRING,
  url STRING,
  `type` STRING,
  content STRING,
  updated_time TIMESTAMP_LTZ(3),
  PRIMARY KEY (node_id) NOT ENFORCED
) WITH (
  'connector' = 'feishu-cdc',
  'object-type' = 'document',
  'app-id' = '<yourAppId>',
  'app-secret' = '<yourAppSecret>',
  'wiki.space-id' = '<yourWikiSpaceId>'
);

Flink SQL DDL 必须声明下表中全部 6 个物理字段，字段顺序和名称需保持一致。

DDL 字段	类型	说明
`node_id`	STRING NOT NULL	文档节点标识，源表主键
`title`	STRING	文档标题
`url`	STRING	文档访问链接
`type`	STRING	飞书对象类型，例如 `docx`
`content`	STRING	文档正文，由文档块结构渲染成的 Markdown 文本
`updated_time`	TIMESTAMP_LTZ(3)	文档最后更新时间

源表必须声明 PRIMARY KEY (node_id) NOT ENFORCED。

此外，DDL 可以通过 METADATA 声明以下可读元数据。元数据列不改变上述物理 Schema。

Metadata Key	类型	说明
`blocks_json`	STRING	文档原始块结构的 JSON 文本，可用于保留块级结构或自定义解析

WITH 参数

基础参数

参数	类型	默认值	是否必填	说明
`connector`	STRING	无	是	固定为 `feishu-cdc`
`object-type`	STRING	无	是	同步的对象类型，当前仅支持 `document`
`app-id`	STRING	无	是	飞书应用的 App ID，用于获取 tenant_access_token
`app-secret`	STRING	无	是	飞书应用的 App Secret
`endpoint`	STRING	`https://open.feishu.cn`	否	飞书开放平台 OpenAPI 域名

读取范围参数

参数	类型	默认值	是否必填	说明
`wiki.space-id`	STRING	无	是	要读取的单个知识空间 ID
`wiki.document-url`	STRING	无	否	文档链接，将范围收窄到单篇文档；与 `wiki.node-token` 最多配置一个
`wiki.node-token`	STRING	无	否	文档节点 Token，将范围收窄到单篇文档；与 `wiki.document-url` 最多配置一个

启动和轮询参数

参数	类型	默认值	说明
`scan.startup.mode`	STRING	`initial`	启动模式，支持 `initial`、`snapshot`、`timestamp`、`latest-offset`
`scan.startup.timestamp-millis`	BIGINT	无	`timestamp` 模式必填且仅该模式可配置，Unix 毫秒时间戳
`scan.new-split.startup.mode`	STRING	`initial`	新发现知识空间的读取方式，支持 `initial`、`latest-offset`
`scan.poll-interval`	DURATION	`10s`	无增量变化时的轮询间隔
`scan.discovery.interval`	DURATION	`1min`	新知识空间的发现间隔
`scan.prefix-size`	INTEGER	`100`	单个分片单次拉取最多输出的变化文档数
`scan.parallelism`	INTEGER	无	Source 并行度；不配置时使用作业默认并行度

请求和限流参数

参数	类型	默认值	说明
`api.page-size`	INTEGER	`20`	知识空间 OpenAPI 分页大小，范围 1～50
`request.timeout`	DURATION	`30s`	单次 OpenAPI 请求超时时间
`request.max-retries`	INTEGER	`3`	瞬时请求失败的最大重试次数
`scan.discovery.rate-limit.requests-per-second`	DOUBLE	`5`	列出知识空间和节点类 OpenAPI 每秒最大请求数
`scan.metadata.rate-limit.requests-per-second`	DOUBLE	`5`	解析节点元数据类 OpenAPI 每秒最大请求数
`scan.content.rate-limit.requests-per-second`	DOUBLE	`5`	读取文档块内容类 OpenAPI 每秒最大请求数

代码示例

全量加增量同步

示例将指定知识空间的文档写入 Paimon 表，声明了 blocks_json 元数据列。

CREATE TEMPORARY TABLE feishu_wiki_source (
  node_id STRING NOT NULL,
  title STRING,
  url STRING,
  `type` STRING,
  content STRING,
  updated_time TIMESTAMP_LTZ(3),
  blocks_json STRING METADATA VIRTUAL,
  PRIMARY KEY (node_id) NOT ENFORCED
) WITH (
  'connector' = 'feishu-cdc',
  'object-type' = 'document',
  'app-id' = '<yourAppId>',
  'app-secret' = '<yourAppSecret>',
  'wiki.space-id' = '<yourWikiSpaceId>',
  'scan.startup.mode' = 'initial'
);

CREATE TABLE IF NOT EXISTS paimon.feishu_wiki.documents (
  node_id STRING,
  title STRING,
  url STRING,
  `type` STRING,
  content STRING,
  blocks_json STRING,
  updated_time TIMESTAMP_LTZ(3),
  PRIMARY KEY (node_id) NOT ENFORCED
);

INSERT INTO paimon.feishu_wiki.documents
SELECT node_id, title, url, `type`, content, blocks_json, updated_time
FROM feishu_wiki_source;

SNAPSHOT 全量扫描

SNAPSHOT 只做一次全量读取，适合内容迁移或一次性导出。

CREATE TEMPORARY TABLE feishu_wiki_snapshot (
  node_id STRING NOT NULL,
  title STRING,
  url STRING,
  `type` STRING,
  content STRING,
  updated_time TIMESTAMP_LTZ(3),
  PRIMARY KEY (node_id) NOT ENFORCED
) WITH (
  'connector' = 'feishu-cdc',
  'object-type' = 'document',
  'app-id' = '<yourAppId>',
  'app-secret' = '<yourAppSecret>',
  'wiki.space-id' = '<yourWikiSpaceId>',
  'scan.startup.mode' = 'snapshot'
);

如需只同步空间内的一篇文档，在 WITH 参数中追加 'wiki.document-url' = '<文档链接>' 或 'wiki.node-token' = '<节点Token>'。

数据摄入

使用飞书 CDC YAML 连接器，您可以将飞书知识空间中在线文档的全量和增量变化持续同步至下游数据湖或数据仓库。数据摄入连接器的 type 固定为 feishu-cdc。

特色功能

自动建表：每个知识空间对应一张名为 <知识空间ID>.documents 的表，连接器在首次发现空间时自动创建表并同步 Schema。
多空间同步：wiki.space-id 支持逗号分隔多个值；不配置时自动发现应用有权读取的全部知识空间，每个空间自动路由到各自的表。
文档级选择器：wiki.document-url / wiki.node-token 支持逗号分隔多个值，把同步范围收窄到指定文档；wiki.restrict-documents-to-selected-spaces 控制选择器是否严格限制在配置的空间内。
按时间戳起步：timestamp 启动模式只读取更新时间不早于 scan.startup.timestamp-millis 的文档，再持续轮询增量。
有界全量导出：snapshot 启动模式为有界读取，全量读取完成后作业自动结束，完成知识空间内容的一次性迁移。
原始块结构输出：输出 Schema 固定包含 blocks_json 物理列，便于 RAG 等场景保留文档块级结构。

注意事项

数据摄入不支持 BATCH 执行模式；全量导出请使用 snapshot 启动模式：有界读取，流模式部署下作业读完自动结束。
全量阶段（snapshot 分片）输出 INSERT 事件；增量阶段输出 UPDATE_AFTER（upsert）事件，下游按主键 node_id 幂等写入即可。
运行过程中新发现的知识空间按 scan.new-split.startup.mode 决定读取方式：initial 先读取当前完整内容再跟随后续变化；latest-offset 只处理发现之后发生的变化。
仅同步应用有权读取的 doc、docx 类型节点；其他对象（表格、多维表、文件等）会被跳过；不感知文档删除。
文档选择器与 wiki.space-id 默认取并集：配置的空间仍整体同步，未配置但包含所选文档的空间也会被自动发现。需要严格边界时请将 wiki.restrict-documents-to-selected-spaces 设为 true，避免选择器静默突破边界。
运行时不支持收缩同步范围：作业运行中调小 wiki.space-id、wiki.document-url 或 wiki.node-token 只影响后续新发现的资源，不会从当前作业中移除；需要彻底移除时，请停止作业并无状态重新启动。
连接器会持续调用飞书开放平台 OpenAPI，请结合限流参数控制 API 调用成本，详见下方"控制 API 调用频率"示例。
app-secret 为敏感信息，建议通过项目变量（如 ${secret_values.feishu_app_secret}）引用，避免明文写入作业配置，详情请参见变量管理。

语法结构

YAML 固定 Schema 如下，主键为 node_id。与 Flink SQL 相比，YAML Schema 增加了 space_id 物理列，blocks_json 也作为物理列直接输出（而非 METADATA 列）。

字段	类型	说明
`node_id`	STRING NOT NULL	文档节点标识，主键
`space_id`	STRING NOT NULL	文档所属知识空间 ID
`title`	STRING	文档标题
`url`	STRING	文档访问链接
`type`	STRING	飞书对象类型，例如 docx
`content`	STRING	文档正文，由文档块结构渲染成的 Markdown 文本
`blocks_json`	STRING	文档原始块结构的 JSON 文本
`updated_time`	TIMESTAMP_LTZ(3)	文档最后更新时间

最小可用语法示例（同步单个知识空间至 Paimon）：

source:
  type: feishu-cdc
  name: Feishu Wiki Source
  app-id: <yourAppId>
  app-secret: <yourAppSecret>
  wiki.space-id: <yourWikiSpaceId>
  scan.startup.mode: initial

route:
  - source-table: <yourWikiSpaceId>.documents
    sink-table: feishu_wiki.documents

sink:
  type: paimon
  catalog.properties.metastore: rest
  catalog.properties.token.provider: dlf
  catalog.properties.uri: <yourDlfCatalogEndpoint>
  catalog.properties.warehouse: <yourWarehouse>

pipeline:
  name: Feishu Wiki to Paimon Pipeline

配置项

基础参数

参数	类型	默认值	是否必填	说明
`type`	STRING	无	是	固定为 `feishu-cdc`
`app-id`	STRING	无	是	飞书应用的 App ID，用于获取 tenant_access_token
`app-secret`	STRING	无	是	飞书应用的 App Secret
`endpoint`	STRING	`https://open.feishu.cn`	否	飞书开放平台 OpenAPI 域名
`object-type`	STRING	`document`	否	同步的对象类型，当前仅支持 `document`

同步范围参数

参数	类型	默认值	是否必填	说明
`wiki.space-id`	STRING	无	否	逗号分隔的知识空间 ID 列表；不配置时自动发现应用有权读取的全部知识空间
`wiki.document-url`	STRING	无	否	逗号分隔的文档链接列表，将同步范围收窄到指定文档
`wiki.node-token`	STRING	无	否	逗号分隔的节点 Token 列表，将同步范围收窄到指定文档
`wiki.restrict-documents-to-selected-spaces`	BOOLEAN	`false`	否	是否将显式选择的文档严格限制在 `wiki.space-id` 配置的空间内。 `false` ：未配置但包含所选文档的空间会被自动发现并同步； `true` ：所选文档不属于配置空间则作业启动报错。

启动和轮询参数

参数	类型	默认值	说明
`scan.startup.mode`	STRING	`initial`	启动模式，支持 `initial`、`snapshot`、`timestamp`、`latest-offset`
`scan.startup.timestamp-millis`	BIGINT	无	`timestamp` 模式必填且仅该模式可配置，Unix 毫秒时间戳
`scan.new-split.startup.mode`	STRING	`initial`	新发现知识空间的读取方式，支持 `initial`、`latest-offset`
`scan.poll-interval`	DURATION	`10s`	无增量变化时的轮询间隔
`scan.discovery.interval`	DURATION	`1min`	新知识空间的发现间隔
`scan.prefix-size`	INTEGER	`100`	单个分片单次拉取最多输出的变化文档数

请求和限流参数

参数	类型	默认值	说明
`api.page-size`	INTEGER	`20`	知识空间 OpenAPI 分页大小，范围 1～50
`request.timeout`	DURATION	`30s`	单次 OpenAPI 请求超时时间
`request.max-retries`	INTEGER	`3`	瞬时请求失败的最大重试次数
`scan.discovery.rate-limit.requests-per-second`	DOUBLE	`5`	列出知识空间和节点类 OpenAPI 每秒最大请求数
`scan.metadata.rate-limit.requests-per-second`	DOUBLE	`5`	解析节点元数据类 OpenAPI 每秒最大请求数
`scan.content.rate-limit.requests-per-second`	DOUBLE	`5`	读取文档块内容类 OpenAPI 每秒最大请求数

空间到表的路由

未配置 wiki.space-id 时，连接器自动发现应用有权读取的全部知识空间，每个空间生成对应的 <知识空间ID>.documents 表。配置 wiki.space-id（支持逗号分隔多个值）后，只同步指定的空间。

配置文档选择器 wiki.document-url 或 wiki.node-token（均支持逗号分隔多个值）后，选择器与 wiki.space-id 默认取并集：配置的空间仍整体同步，选择器不做收窄；未配置的空间如果包含所选文档，也会被自动发现并同步这些文档。wiki.restrict-documents-to-selected-spaces 控制是否把选择器严格限制在 wiki.space-id 配置的空间内。

假设 wiki.space-id 配置为空间 A，文档选择器包含属于 A 的文档 X 和属于 B 的文档 Y：

wiki.restrict-documents-to-selected-spaces	同步结果
`false`（默认）	空间 A 整体同步；空间 B 被自动发现并同步文档 Y
`true`	仅同步文档 X；文档 Y 不属于配置空间，作业启动时报错

如想让 wiki.space-id 作为严格同步边界，建议设置为 true，避免选择器静默突破边界、同步到预期外的空间。

代码示例

以下示例均为数据摄入 YAML 作业的完整配置，您可以根据自己的作业场景直接复制修改。

示例中的 app-id、app-secret 含义与获取方式请参见前提条件。源端与所有数据摄入目标端连接器（Paimon、Hologres、MaxCompute 等）兼容，目标端配置请参见对应连接器文档；统一以 Paimon 为例。

同步单个知识空间（全量加增量）

最基础的用法：先全量读取指定知识空间的全部文档，再持续同步后续的修改，写入 Paimon（DLF Catalog）。适合构建始终与飞书知识空间保持一致的 RAG 索引或湖仓内容底座。

source:
  type: feishu-cdc                      # 固定值。飞书知识库 CDC 连接器类型
  name: Feishu Wiki Source              # 数据源名称
  app-id: <yourAppId>                   # 必填。飞书应用的 App ID，用于获取 tenant_access_token
  app-secret: <yourAppSecret>           # 必填。飞书应用的 App Secret
  wiki.space-id: <yourWikiSpaceId>      # 可选。指定要同步的知识空间 ID；不配置时自动发现应用有权读取的全部空间
  scan.startup.mode: initial            # 可选。启动模式，取值 initial（默认，全量加增量）、snapshot（仅全量）、timestamp（按时间戳起步）、latest-offset（仅增量）

route:
  # 连接器为每个知识空间自动创建名为 <知识空间ID>.documents 的源表，
  # 通过 route 可以把它映射到指定的下游表；不配置 route 时按 <知识空间ID>.documents 原样写入下游。
  - source-table: <yourWikiSpaceId>.documents   # 源表，格式固定为 <知识空间ID>.documents
    sink-table: feishu_wiki.documents           # 下游表名，可按需修改

sink:
  type: paimon                                  # 目标端类型，本示例写入 Paimon
  catalog.properties.metastore: rest            # Metastore 类型，使用 DLF 时固定为 rest
  catalog.properties.token.provider: dlf        # Token 提供方，使用 DLF 时固定为 dlf
  catalog.properties.uri: <yourDlfCatalogEndpoint>    # DLF Rest Catalog Server 地址，格式为 http://<region-id>-vpc.dlf.aliyuncs.com
  catalog.properties.warehouse: <yourWarehouse>       # DLF Catalog 名称
  #（可选）开启删除向量，提升下游读取性能
  table.properties.deletion-vectors.enabled: true

pipeline:
  name: Feishu Wiki to Paimon Pipeline          # 作业名称

同步多个知识空间，每空间一张下游表

一次作业同步多个知识空间。每个空间自动创建一张 <知识空间ID>.documents 下游表，互不混淆。适合按空间维度分别管理和查询同步结果的场景。

source:
  type: feishu-cdc                      # 固定值。飞书知识库 CDC 连接器类型
  name: Feishu Wiki Source              # 数据源名称
  app-id: <yourAppId>                   # 必填。飞书应用的 App ID
  app-secret: <yourAppSecret>           # 必填。飞书应用的 App Secret
  wiki.space-id: <spaceId1>,<spaceId2>  # 可选。逗号分隔的多个知识空间 ID
  #（可选）新知识空间的发现间隔，默认 1min
  scan.discovery.interval: 1min

sink:
  type: paimon                          # 目标端类型，本示例写入 Paimon
  catalog.properties.metastore: rest    # Metastore 类型，使用 DLF 时固定为 rest
  catalog.properties.token.provider: dlf        # Token 提供方，使用 DLF 时固定为 dlf
  catalog.properties.uri: <yourDlfCatalogEndpoint>    # DLF Rest Catalog Server 地址
  catalog.properties.warehouse: <yourWarehouse>       # DLF Catalog 名称
  table.properties.deletion-vectors.enabled: true     #（可选）开启删除向量，提升下游读取性能

# 未配置 route：两个空间分别写入 <spaceId1>.documents 和 <spaceId2>.documents 两张下游表

pipeline:
  name: Feishu Wikis to Paimon Pipeline # 作业名称
  #（可选）作业并行度。每个知识空间是一个独立的读取分片，同步多个空间时适当调大并行度可以加快全量读取
  parallelism: 2

合并多个知识空间到同一张下游表

多个知识空间的文档 Schema 完全相同，可以把它们合并写入同一张下游表统一检索，适合跨空间的 RAG 召回场景。合并后请以下游主键 node_id 保证幂等；如需区分文档来源，下游表中可保留 space_id 字段。

source:
  type: feishu-cdc                      # 固定值。飞书知识库 CDC 连接器类型
  name: Feishu Wiki Source              # 数据源名称
  app-id: <yourAppId>                   # 必填。飞书应用的 App ID
  app-secret: <yourAppSecret>           # 必填。飞书应用的 App Secret
  wiki.space-id: <spaceId1>,<spaceId2>  # 可选。逗号分隔的多个知识空间 ID

route:
  # 多条 route 规则指向同一张下游表，即可实现多空间合并。
  - source-table: <spaceId1>.documents  # 第一个空间的源表
    sink-table: feishu_wiki.documents   # 合并写入的下游表名
  - source-table: <spaceId2>.documents  # 第二个空间的源表
    sink-table: feishu_wiki.documents   # 与上一条规则写入同一张表

sink:
  type: paimon                          # 目标端类型，本示例写入 Paimon
  catalog.properties.metastore: rest    # Metastore 类型，使用 DLF 时固定为 rest
  catalog.properties.token.provider: dlf        # Token 提供方，使用 DLF 时固定为 dlf
  catalog.properties.uri: <yourDlfCatalogEndpoint>    # DLF Rest Catalog Server 地址
  catalog.properties.warehouse: <yourWarehouse>       # DLF Catalog 名称
  table.properties.deletion-vectors.enabled: true     #（可选）开启删除向量，提升下游读取性能

pipeline:
  name: Merge Feishu Wikis to One Paimon Table  # 作业名称

自动发现全部知识空间

不配置 wiki.space-id 时，连接器周期性发现应用有权读取的全部知识空间并自动同步，之后新授权的空间也会在发现周期内被自动纳入同步范围。适合同步范围随应用授权自动扩展的场景。

source:
  type: feishu-cdc                      # 固定值。飞书知识库 CDC 连接器类型
  name: Feishu Wiki Source              # 数据源名称
  app-id: <yourAppId>                   # 必填。飞书应用的 App ID
  app-secret: <yourAppSecret>           # 必填。飞书应用的 App Secret
  # 不配置 wiki.space-id：自动发现应用有权读取的全部知识空间
  #（可选）新知识空间的发现间隔，默认 1min
  scan.discovery.interval: 1min

sink:
  type: paimon                          # 目标端类型，本示例写入 Paimon
  catalog.properties.metastore: rest    # Metastore 类型，使用 DLF 时固定为 rest
  catalog.properties.token.provider: dlf        # Token 提供方，使用 DLF 时固定为 dlf
  catalog.properties.uri: <yourDlfCatalogEndpoint>    # DLF Rest Catalog Server 地址
  catalog.properties.warehouse: <yourWarehouse>       # DLF Catalog 名称
  table.properties.deletion-vectors.enabled: true     #（可选）开启删除向量，提升下游读取性能

pipeline:
  name: Sync All Feishu Wikis to Paimon # 作业名称
  #（可选）作业并行度。空间较多时适当调大并行度可以加快全量读取
  parallelism: 4

说明

运行时不支持收缩同步范围：作业运行中调小 wiki.space-id、wiki.document-url 或 wiki.node-token 只影响后续新发现的资源，不会从当前作业中移除；需要彻底移除时，请停止作业并无状态重新启动。

收窄到指定文档并严格限定边界

只同步若干篇指定文档时用文档选择器：wiki.document-url 填飞书文档链接（支持 wiki、docx、docs 等常见地址形式），或 wiki.node-token 直接填节点 Token，均支持逗号分隔多个值。

source:
  type: feishu-cdc                      # 固定值。飞书知识库 CDC 连接器类型
  name: Feishu Wiki Source              # 数据源名称
  app-id: <yourAppId>                   # 必填。飞书应用的 App ID
  app-secret: <yourAppSecret>           # 必填。飞书应用的 App Secret
  wiki.space-id: <yourWikiSpaceId>      # 可选。配置的空间整体同步，同时作为严格边界
  wiki.document-url: <yourDocUrl1>,<yourDocUrl2>        # 可选。逗号分隔的文档链接列表，将范围收窄到指定文档
  # wiki.node-token: <nodeToken1>,<nodeToken2>          # 可选。与 wiki.document-url 二选一风格的收窄方式，也可逗号分隔多个
  wiki.restrict-documents-to-selected-spaces: true      # 可选。true：所选文档必须属于 wiki.space-id 配置的空间，否则作业启动报错；false（默认）：包含所选文档的未配置空间会被自动发现

sink:
  type: paimon                          # 目标端类型，本示例写入 Paimon
  catalog.properties.metastore: rest    # Metastore 类型，使用 DLF 时固定为 rest
  catalog.properties.token.provider: dlf        # Token 提供方，使用 DLF 时固定为 dlf
  catalog.properties.uri: <yourDlfCatalogEndpoint>    # DLF Rest Catalog Server 地址
  catalog.properties.warehouse: <yourWarehouse>       # DLF Catalog 名称

pipeline:
  name: Feishu Selected Docs to Paimon  # 作业名称

说明

选择器与 wiki.space-id 默认取并集——未配置但包含所选文档的空间也会被自动发现；要把同步范围严格限制在配置的空间内，请将 wiki.restrict-documents-to-selected-spaces 设为 true（此时不属于配置空间的文档会让作业启动报错）。

从指定时间戳开始同步

下游已有更早的存量数据、只需要追平某时间点之后的变更时，用 timestamp 启动模式：只读取更新时间不早于 scan.startup.timestamp-millis 的文档，再持续轮询增量。该参数为 Unix 毫秒时间戳，且仅在 timestamp 模式下可配置。

source:
  type: feishu-cdc                      # 固定值。飞书知识库 CDC 连接器类型
  name: Feishu Wiki Source              # 数据源名称
  app-id: <yourAppId>                   # 必填。飞书应用的 App ID
  app-secret: <yourAppSecret>           # 必填。飞书应用的 App Secret
  wiki.space-id: <yourWikiSpaceId>      # 可选。指定要同步的知识空间 ID
  scan.startup.mode: timestamp          # 按时间戳起步：读取更新时间不早于下方时间戳的文档，再持续轮询增量
  scan.startup.timestamp-millis: 1756166400000  # timestamp 模式必填。Unix 毫秒时间戳

route:
  - source-table: <yourWikiSpaceId>.documents   # 源表，格式固定为 <知识空间ID>.documents
    sink-table: feishu_wiki.documents           # 下游表名，可按需修改

sink:
  type: paimon                          # 目标端类型，本示例写入 Paimon
  catalog.properties.metastore: rest    # Metastore 类型，使用 DLF 时固定为 rest
  catalog.properties.token.provider: dlf        # Token 提供方，使用 DLF 时固定为 dlf
  catalog.properties.uri: <yourDlfCatalogEndpoint>    # DLF Rest Catalog Server 地址
  catalog.properties.warehouse: <yourWarehouse>       # DLF Catalog 名称
  table.properties.deletion-vectors.enabled: true     #（可选）开启删除向量，提升下游读取性能

pipeline:
  name: Feishu Wiki Timestamp Startup   # 作业名称

仅同步作业启动后的增量变化

跳过全部存量文档，只处理作业启动之后新增或修改的文档。适合下游已有完整存量、只需要追平后续变更的场景。

source:
  type: feishu-cdc                      # 固定值。飞书知识库 CDC 连接器类型
  name: Feishu Wiki Source              # 数据源名称
  app-id: <yourAppId>                   # 必填。飞书应用的 App ID
  app-secret: <yourAppSecret>           # 必填。飞书应用的 App Secret
  wiki.space-id: <yourWikiSpaceId>      # 可选。指定要同步的知识空间 ID；不配置时自动发现全部可见空间
  scan.startup.mode: latest-offset      # 跳过全量阶段，仅同步作业启动后发生变化的文档

route:
  - source-table: <yourWikiSpaceId>.documents   # 源表，格式固定为 <知识空间ID>.documents
    sink-table: feishu_wiki.documents           # 下游表名，可按需修改

sink:
  type: paimon                          # 目标端类型，本示例写入 Paimon
  catalog.properties.metastore: rest    # Metastore 类型，使用 DLF 时固定为 rest
  catalog.properties.token.provider: dlf        # Token 提供方，使用 DLF 时固定为 dlf
  catalog.properties.uri: <yourDlfCatalogEndpoint>    # DLF Rest Catalog Server 地址
  catalog.properties.warehouse: <yourWarehouse>       # DLF Catalog 名称
  table.properties.deletion-vectors.enabled: true     #（可选）开启删除向量，提升下游读取性能

pipeline:
  name: Feishu Wiki Incremental Sync    # 作业名称

一次性全量导出（snapshot）

snapshot 启动模式为有界读取：一次性把知识空间当前内容全量导出到下游，作业读完即自动结束，适合内容迁移、一次性备份或离线分析准备。

source:
  type: feishu-cdc                      # 固定值。飞书知识库 CDC 连接器类型
  name: Feishu Wiki Source              # 数据源名称
  app-id: <yourAppId>                   # 必填。飞书应用的 App ID
  app-secret: <yourAppSecret>           # 必填。飞书应用的 App Secret
  wiki.space-id: <yourWikiSpaceId>      # 可选。指定要导出的知识空间 ID；不配置时导出应用有权读取的全部空间
  scan.startup.mode: snapshot           # 仅全量读取，读完作业自动结束（有界）

route:
  - source-table: <yourWikiSpaceId>.documents   # 源表，格式固定为 <知识空间ID>.documents
    sink-table: feishu_wiki.documents           # 下游表名，可按需修改

sink:
  type: paimon                          # 目标端类型，本示例写入 Paimon
  catalog.properties.metastore: rest    # Metastore 类型，使用 DLF 时固定为 rest
  catalog.properties.token.provider: dlf        # Token 提供方，使用 DLF 时固定为 dlf
  catalog.properties.uri: <yourDlfCatalogEndpoint>    # DLF Rest Catalog Server 地址
  catalog.properties.warehouse: <yourWarehouse>       # DLF Catalog 名称

pipeline:
  name: Feishu Wiki One-Time Export     # 作业名称

裁剪同步字段（Transform）

您可以通过 Transform 规则在同步链路中裁剪字段，只把下游真正需要的列写入结果表，节省存储成本。主键 node_id 必须保留在投影中。

source:
  type: feishu-cdc                      # 固定值。飞书知识库 CDC 连接器类型
  name: Feishu Wiki Source              # 数据源名称
  app-id: <yourAppId>                   # 必填。飞书应用的 App ID
  app-secret: <yourAppSecret>           # 必填。飞书应用的 App Secret
  wiki.space-id: <yourWikiSpaceId>      # 可选。指定要同步的知识空间 ID

transform:
  - source-table: <yourWikiSpaceId>.documents   # 对哪个空间的源表应用转换规则
    # 投影：仅保留 RAG 索引需要的字段，丢弃 type、blocks_json 等不需要的列。主键 node_id 必须保留。
    projection: node_id, space_id, title, url, content, updated_time
    description: keep only fields required by the RAG index

route:
  - source-table: <yourWikiSpaceId>.documents   # 源表，格式固定为 <知识空间ID>.documents
    sink-table: feishu_wiki.documents           # 下游表名，可按需修改

sink:
  type: paimon                          # 目标端类型，本示例写入 Paimon
  catalog.properties.metastore: rest    # Metastore 类型，使用 DLF 时固定为 rest
  catalog.properties.token.provider: dlf        # Token 提供方，使用 DLF 时固定为 dlf
  catalog.properties.uri: <yourDlfCatalogEndpoint>    # DLF Rest Catalog Server 地址
  catalog.properties.warehouse: <yourWarehouse>       # DLF Catalog 名称

pipeline:
  name: Feishu Wiki to Paimon with Transform    # 作业名称

控制同步速度与 API 调用成本

增量链路基于 OpenAPI 轮询，会产生持续的 API 调用。空间内文档较多时，您可以通过以下参数降低调用频率，或在新内容同步延迟可接受的前提下控制 API 成本；反向调大这些参数则可以加快同步。

source:
  type: feishu-cdc                      # 固定值。飞书知识库 CDC 连接器类型
  name: Feishu Wiki Source              # 数据源名称
  app-id: <yourAppId>                   # 必填。飞书应用的 App ID
  app-secret: <yourAppSecret>           # 必填。飞书应用的 App Secret
  wiki.space-id: <yourWikiSpaceId>      # 可选。指定要同步的知识空间 ID
  #（可选）无增量变化时的轮询间隔，默认 10s。调大可降低空闲期 API 调用量，代价是新内容同步延迟增大
  scan.poll-interval: 30s
  #（可选）单个分片单次拉取最多输出的变化文档数，默认 100。调大后单轮可同步更多变更文档
  scan.prefix-size: 100
  #（可选）知识空间 OpenAPI 分页大小，范围 1-50，默认 20
  api.page-size: 20
  #（可选）以下三个限流参数默认均为 5 QPS，按客户端生效，请结合飞书应用配额整体评估
  # 列出知识空间和节点类请求限流
  scan.discovery.rate-limit.requests-per-second: 5
  # 解析节点元数据类请求限流
  scan.metadata.rate-limit.requests-per-second: 5
  # 读取文档块内容类请求限流
  scan.content.rate-limit.requests-per-second: 5

route:
  - source-table: <yourWikiSpaceId>.documents   # 源表，格式固定为 <知识空间ID>.documents
    sink-table: feishu_wiki.documents           # 下游表名，可按需修改

sink:
  type: paimon                          # 目标端类型，本示例写入 Paimon
  catalog.properties.metastore: rest    # Metastore 类型，使用 DLF 时固定为 rest
  catalog.properties.token.provider: dlf        # Token 提供方，使用 DLF 时固定为 dlf
  catalog.properties.uri: <yourDlfCatalogEndpoint>    # DLF Rest Catalog Server 地址
  catalog.properties.warehouse: <yourWarehouse>       # DLF Catalog 名称

pipeline:
  name: Feishu Wiki Rate-Limited Sync   # 作业名称