3.4 文件系统插件（LocalFS, FTP, SFTP, OSS等）

3.4 文件系统插件（LocalFS, FTP, SFTP, OSS等）

文件系统类插件处理的是「文件」而非「表」。源可以是本地、FTP、SFTP、OSS，目标同理。这类同步常用于和上下游以文件交换数据的系统对接。

读文件：路径与编码

filereader / ftpreader / sftpreader / ossreader 都围绕「给一批路径，按行或按分隔读」。编码要和目标文件一致，否则中文乱码。压缩文件部分插件能识别，但最好提前解好或确认支持。

{
  "reader": {
    "name": "ossreader",
    "parameter": {
      "endpoint": "oss-cn-hangzhou.aliyuncs.com",
      "bucket": "etl-bucket",
      "object": ["/raw/orders/2024-01-*.csv"],
      "encoding": "utf-8"
    }
  }
}
​

写文件：命名与覆盖

文件 Writer 关心文件名、是否覆盖、是否加后缀。writeMode 有 append、nonConflict、truncate 等，语义各异。nonConflict 在目标已存在时直接报错，避免误覆盖——我们在生产环境偏好它，宁可失败重来，也不愿悄悄吃掉昨天的数据。

网络与稳定性

FTP/SFTP 在大数据量下容易因网络抖动断连。我们会在外层脚本加重试，并尽量用支持断点续传的对象存储（OSS/S3）做中转，而不是直接 FTP 拉几亿行。文件系统同步的坑多在「网络」而非「格式」。

选型建议

能用对象存储就别用 FTP 直连。OSS 既做源又做目标时，DataX 走内网 endpoint 几乎不占公网带宽。这是我们在跨机房搬运时总结出的省心方案。

编码与格式陷阱

文件系统同步最常见的坑是编码不一致导致中文乱码，以及压缩格式插件不支持。我们规定源文件统一 utf-8，并在 Reader 里显式声明 encoding。压缩文件若插件不支持，提前解压或换用支持的工具，别指望 DataX 自动识别。

我们跨机房搬大文件时，几乎不用 FTP 直连，而是先落到 OSS，再让目标端从 OSS 拉。对象存储支持断点、内网快，比裸 FTP 稳得多。

延伸与提醒

星型拓扑把 N 乘 M 的对接降到 N 加 M，变更成本随之下降。
JVM 堆要给 Channel 缓冲留足空间，否则 GC 频繁拖慢吞吐。
限速不是限制能力，而是给其他任务留出生存空间。
orc 加 snappy 是 Hive 落地的常见稳妥组合，省空间且查询快。
Web 平台解决协作与可观测，不提升同步能力本身。
任务的读写速率差，比绝对速率更能说明瓶颈在哪一段。
退出码接进调度系统，才能让失败在半夜被及时发现。
权限收得越紧，凭据泄露的爆炸半径越小。
writeMode 必须和数据更新语义对齐，不能凭感觉选。
Channel 是有界缓冲，填满即触发反压保护内存。
反压机制保护内存，看到任务变慢应去优化下游而非加并发。
监控指标和 DataX 日志交叉看，能锁定九成瓶颈。
preSql 里带 truncate 的任务，上线前必须二次确认目标表名。
调优的本质是在 CPU、网络带宽和磁盘 IO 之间找平衡点，不是堆资源。
配置进版本库、密码进环境变量，是跨环境复用的基础。
Reader 和 Writer 互不知晓，正是插件能独立扩展的原因。
把转换逻辑下推到源库，通常比在 DataX 内部处理更高效。
关系型 Writer 的批量提交大小，要在往返开销和回滚成本间权衡。
Redis 同步重跑要防重复 key，靠固定模板才能幂等。
把 DataX 当搬运工而非加工车间，链路才简单可排查。
日志里周期打印的读写速率，是定位瓶颈的第一手材料。
源库索引评审应作为同步查询上线的前置环节。
数据湖贴源层保留原始形态，方便后续 schema 演化。
DataX 的设计哲学是把连接差异收敛到插件，让核心只管调度与缓冲。
插件目录名必须和 job.json 的 name 完全一致，大小写都不能错。
eswriter 的批量 bulk 写入，比逐条插入快一个数量级。
测试样本先小后大，几分钟校验能省下几小时排错。
splitPk 的列若分布不均，分片会倾斜，部分 Task 拖慢整体。
全量基线加增量补充，是批流配合的常见稳妥组合。
多租户隔离交给编排层，DataX 保持简单最稳妥。

用对象存储做中转时，endpoint 走内网能省公网带宽。

{
  "reader": {
    "name": "ossreader",
    "parameter": { "endpoint": "oss-cn-hangzhou-internal.aliyuncs.com" }
  }
}
​

背景

LocalFS、FTP、SFTP、OSS 等文件系统类插件，常用于「把数据库导出成文件」或「把文件搬进云存储」。它们的配置重心在路径与格式，而非连接池。

操作：本地文件到 OSS

{
  "job": {
    "content": [
      {
        "reader": { "name": "txtfilereader", "parameter": {
          "path": ["/data/export/"], "fileName": "order_*.csv",
          "column": [ {"index":0,"type":"long"}, {"index":1,"type":"string"}, {"index":2,"type":"double"} ],
          "fieldDelimiter": ","
        } },
        "writer": { "name": "osswriter", "parameter": {
          "endpoint": "oss-endpoint", "bucket": "etl", "path": "archive/order/",
          "fieldDelimiter": ",", "fileSuffix": ".csv",
          "column": [ {"name":"id","type":"long"}, {"name":"name","type":"string"}, {"name":"amount","type":"double"} ]
        } }
      }
    ],
    "setting": { "speed": { "channel": 3 } }
  }
}
​

启动命令

# 3.4 文件系统插件（LocalFS, FTP, SFTP, OSS等）
ossutil ls oss://etl/archive/order/
​

结果解读

txtfilereader 用 path + fileName 通配一批文件，column 按 index 或 name 解析列；osswriter 把行写成对象存储上的文件，fileSuffix 控制扩展名。FTP / SFTP writer 类似，只是把 endpoint/bucket 换成 host/port/username/password 与远程目录。

变式

把 reader 换成 ftpreader、writer 换成 ftpreader 的目标端，就能做「FTP 到 FTP」的跨机房搬运；换成 hdfswriter 则进数仓。文件系统插件的好处是「不挑源端格式」，但它本身不做类型强校验，脏数据更易混入。

文件系统插件对照

💡 关键直觉：文件类同步的本质是「按路径搬运字节流，再按分隔符解释成行」。它最灵活，但也最依赖你保证文件格式稳定，否则读出来的列会错位。

⚠️ 常见坑：源文件用 分隔但 reader 写成 ,，结果整列被读成一个字段，下游全部错位；文件格式变更（加列 / 改分隔符）务必同步改 job 的 column 与 fieldDelimiter。