概述
文件到 Volume 同步将半结构化文件（FTP / SFTP / COS / S3 / Azure Blob / HDFS 等）写入 DataBuddy Volume，支持两种用法：
原始文件传输 ：保留文件原始格式，直接落入 Volume，常用于归档与备份。
解析后转换格式 ：读取源文件并按目标文件类型重新输出，常用于格式转换（如 TXT 转 JSON）。
适用场景
文件归档：将业务伙伴上传到 SFTP 的原始文件按日期落入 Volume。
格式转换：将上游 TXT 文件读出后以 JSON 格式重新落到 Volume，方便下游消费。
多文件合并：将多个源路径下的文件读取后按统一格式集中输出。
前提条件
在开始本操作前，请确保满足以下条件：
已开通 DataBuddy 服务并完成空间初始化。
当前账号在目标 Workspace 中拥有 数据接入相关角色 （详见 成员与权限管理）。
已创建用于数据接入的计算资源（数据接入型）。
已创建并测试通过来源端数据源连接（详见 添加数据源连接）。
目标 Catalog 下已存在 Volume 类型 Schema，或当前账号有创建权限。
使用限制
限制项 | 说明 |
来源端类型 | 半结构化数据源（FTP / SFTP / COS / S3 / Azure Blob / HDFS 等） |
目标端类型 | DataBuddy Catalog 下的 Volume 类型 Catalog |
读取方式 | 原始文件 （原样落 Volume）/ 解析数据 （解析后按目标文件类型重新输出） |
字段映射 | 原始文件模式：来源端 / 目标端均不可设置；解析模式：来源端可设置（手动添加字段），目标端不可设置 |
输出文件类型 | 仅 txt / csv / dat / json |
操作步骤
步骤 1：进入任务创建页、填写基础信息
步骤 2：配置来源端
参数 | 说明 | 是否必填 |
数据源类型 | 选择来源数据源类型（如 SFTP） | 是 |
数据源连接 | 选择已注册的数据源连接 | 是 |
文件路径 | 文件或文件夹路径，点击文件夹图标可弹出路径选择器；支持插入参数与正则；S3 需带桶名；Azure Blob 需带容器名 | 是 |
读取方式 | 原始文件 或 解析数据 （决定是否走解析） | 是 |
文件格式 | 数据同步模式必填：.csv / .avro / .json / .parquet / .txt | 视模式 |
解析配置 | 数据同步模式必填，按文件类型配置 | 视模式 |
同步范围（仅 S3） | 全量 / 增量 | 视场景 |
高级设置 | 数据源专属扩展参数 | 否 |
步骤 3：配置目标端
当目标端选择为 Volume 类型 Catalog 时：
参数 | 说明 | 是否必填 |
目标 Catalog | 选择有权限的 Volume 类型 Catalog；不存在时可点击「新建」创建 | 是 |
目标 Schema | Catalog 下的 Schema | 是 |
Volume | 选择已存在的 Volume | 是 |
Volume 文件目录 | Volume 内子路径；为空表示落到 Volume 根目录 | 否（默认根目录） |
文件名称 | 输出文件名（仅数据同步模式必填） | 视模式 |
文件格式 | 数据同步模式必填：txt / csv / dat / json | 视模式 |
格式设置 | 数据同步模式必填，按目标类型配置 | 视模式 |
写入模式 | overwrite / append / upsert | 是 |
数据同步模式下的输出格式配置
文件类型 | 配置项 |
TXT / CSV / DAT | 压缩格式、列分隔符、行分隔符、编码、控制转换、Quote Character、包含表头 |
JSON | 压缩格式、编码、空值转换、包含表头 |
标记文件支持
文件类型 | .ok 文件 | .ctl 文件 |
txt | 有 | 有 |
csv | 有 | 有 |
dat | 有 | 无 |
json | 有 | 无 |
步骤 4：字段映射
模式 | 来源端字段映射 | 目标端字段映射 |
文件同步（原始） | ❌ 不可设置 | ❌ 不可设置 |
数据同步（解析） | ✅ 可设置（手动添加字段） | ❌ 不可设置 |
步骤 5：运行设置、调试、保存、发布
验证结果
任务保存并调试运行后，您可以通过以下方式确认：
1. 进入 数据目录 中目标 Volume，看到已写入的文件。
2. 文件同步模式下文件名与原文件一致；数据同步模式下文件名按目标端配置。
3. 下载或预览文件确认内容；如有 .ok 文件，确认内容标记符合下游约定。
常见问题
Q：选错了读取方式，能改吗？
A：可以。在任务编辑页将「读取方式」从「原始文件」切到「解析数据」，并补充必填配置项后保存即可。注意：切换会重置已有的解析配置与字段映射。
Q：读取方式选择「原始文件」时，多个源文件会合并为一个文件吗？
A：不会。文件同步模式下源文件按原结构 1:1 落入 Volume（保留原文件名），不做合并。
Q：数据同步模式下输出文件名相同会被覆盖吗？
A：取决于写入模式：
overwrite ：覆盖同名文件。
append ：在同名文件后追加内容。
upsert ：行为与 overwrite 类似（Volume 不感知主键）。
Q：源端选择了不同路径下的同名文件，将会如何？
A：将会报错，逻辑上在读取时，会将所有文件提到一个 list，如果有重名文件，会报错。
Q：能否在同一个任务中既保留原始文件又生成解析后文件？
相关文档
创建单表同步任务
