做数据对接的人大概都经历过这种时刻第三方接口限流、分页翻不到底、token 半小时过期一次你写好的 Python 脚本凌晨三点挂了然后你被电话叫醒。这不是段子是我这次把 HTTP 接口数据同步到 Doris 之前的真实状态。后来我用 SeaTunnel 把这条链路彻底改造成配置化任务跑了一周稳定无报错。这篇不是官方文档的复述是这次实战里所有踩过的坑、看过的日志、最后证明有效的配置适合正在为 HTTP 数据源接 Doris 发愁的同行参考。1. 为什么是 SeaTunnelHTTP 到 Doris 的选型逻辑1.1 原始方案Python 脚本和三座大山在切换到 SeaTunnel 之前我们用的是 Python requests 手写同步脚本。接口返回结构是常见的{code:0,data:{list:[...],has_more:true}}脚本要循环翻页每次还要处理 token 刷新。数据量小的时候没感觉等表从 1 万行涨到 500 万行三个问题彻底暴露故障恢复无状态跑到第 80 页挂了重启脚本时只能从第 1 页重新拉要么自己记游标要么忍受重复数据。网络波动靠重试硬扛requests 写重试看着简单但超时、连接重置、接口限流三种异常处理方式完全不同代码越补越乱。多表接入成本高每接一个 HTTP 接口就要复制一套分页和解析逻辑团队里有人喜欢用 dataclass有人喜欢写 dict维护成本直接失控。这些痛点不是不能解决但解决它们需要投入大量工程时间而这恰恰是最不值得写代码的部分。对接 HTTP 接口的本质无非是“发请求、拿数据、落库”真正复杂的是状态管理和异常恢复这部分交给成熟工具比自研靠谱得多。1.2 为什么最后是 SeaTunnel 而不是 Flink SQL 或 DataX我们内部其实对比过三个方向Flink SQL、DataX、SeaTunnel。当时的情况是方案运行环境同步复杂度断点续传扩展性自研脚本任意完全自己写需自己实现不灵活Flink SQL需要维护 Flink 集群需要写 SQL DDL 和 Connector自带强但运维成本高DataX独立进程插件丰富但写 HTTP 源要二次开发无依赖版本较老SeaTunnel轻量引擎可单机可集群配置化HTTP/Doris 官方插件自带支持大量 Connector还在扩展为了一个同步任务去起一套 Flink 集群对我们这种十人左右的数据组来说性价比太低。DataX 确实很成熟但官方没有特别顺手的 HTTP Source想接自定义接口还得自己写插件和自研没本质区别。SeaTunnel 的 HTTP Source 插件能直接解析 JSON 响应、支持 schema 映射Doris Sink 走 Stream Load几行配置就能把链路串起来是最快能落地的方案。这里多说一句后来我们团队里也有人试过用 Flink SQL 写 Doris Union Key 模型的表底层同样是 Stream Load。但对我们这种批量任务为主、峰值并发不高的场景SeaTunnel 的轻量特性非常舒服。它不需要常驻集群任务失败后通过 REST API 重新提交一次就能从上次 checkpoint 恢复省掉了很多维护成本。1.3 这条链路在 SeaTunnel 里的完整形态SeaTunnel 里一条 HTTP 同步任务大致长这样HTTP Source 按配置定时或按批次发起请求拿到 JSON 响应后经过 Transform 做字段处理最后交给 Doris Sink 通过 Stream Load 写入目标表。整个过程全部由一个配置驱动没有一行业务代码。架构上可以概括为Source 端HTTP 连接器负责鉴权、分页、解析把接口返回的嵌套 JSON 打平成一行行记录。Transform 端可以重命名字段、处理时间戳、补默认值、做简单的过滤。Sink 端Doris 连接器负责建 label、提交导入、处理失败重试走 Stream Load 通道进入 Doris 的 BE。这个形态最大的好处是每个环节都可以单独调试。后面的配置拆解部分我会把一份真实跑通的配置拿出来一行一行说。2. 部署阶段绕不开的版本与端口问题2.1 Doris 安装部署时我调整的几个参数刚开始我们图省事想在 Windows 开发机上直接装 Doris 客户端测试结果发现 Doris 官方对 Windows 原生部署并不友好FE 和 BE 都是以 Linux 为目标平台的。推荐的方式是用 Docker Desktop 起 Linux 容器或者直接在 Linux 服务器上部署。Windows 上也并非跑不了只是要绕一层虚拟机或容器调试时很多路径和权限问题会让你怀疑人生。Docker 方式部署 Doris 时我建议至少调整这几个地方BE 的mem_limit默认可能认为占满物理内存没问题但如果你不是一台独占机器建议手动限制否则很容易跟其他服务抢内存。我一般设成 8GB 左右。sys_log_level默认 INFO 日志量非常大排查问题时可以临时调成 DEBUG但平时保持 INFO 即可。数据目录挂载Docker 容器重启后数据会丢必须把 FE 和 BE 的数据目录挂到宿主机。还有一个容易被忽略的点BE 启动时的系统参数max open files要调大否则运行一段时间会出现文件句柄耗尽。这个在容器里尤其隐蔽外面看一切正常但任务莫名其妙失败最后看 BE 日志才发现是Too many open files。2.2 SeaTunnel 2.3.x 和 Doris Connector 的配套选择SeaTunnel 版本我推荐直接用官方最新的稳定发行版当时我们用的是 2.3.8。装好之后要确认connector-doris和connector-http这两个插件都在connectors/目录里。如果是从源码或者旧版本升上来的最容易遇到的问题是缺少 Doris 的客户端依赖导致任务提交后报ClassNotFoundException: doris这种问题基本就是 jar 没放全把对应 connector 的依赖包重新拷到lib/下即可。判断插件是否生效的简单办法bin/seatunnel.sh -l这个命令会列出引擎加载到的所有连接器。如果你能看到Doris和Http相关条目说明环境没问题。看不到就先别急着调配置回去检查connectors/目录的 jar 是否完整。还有一个经验SeaTunnel 和 Doris 都在快速迭代connector 和引擎版本不要相差太远。我在网上看到很多诡异问题最后都指向“用户把最新的 Doris connector 塞进了老版 SeaTunnel”字段解析方式变了自然跑不通。2.3 端口与网络Stream Load 走的是哪个口SeaTunnel 的 Doris Sink 底层用的是 Doris Stream Load它通过 FE 的 HTTP 端口提交导入请求默认是8030。所以你的任务调度机只要能访问到 FE 的8030就行不需要直接访问 BE 的8040数据端口。这一点容易踩坑很多人在安全组里只开了 Doris 的 MySQL 端口9030结果 SeaTunnel 一直连不上其实 Stream Load 走的是另一个端口。等到提交数据时如果日志出现unexpected status 502 bad gateway且 URL 指向 FE 或某个网关优先检查端口连通性和 FE 负载这就是我后面会展开排查的案例。3. 一份能跑通的 HTTP 到 Doris 同步配置拆解3.1 HTTP Source把嵌套 JSON 拍平我以实际项目中的一个订单接口为例。这个接口返回结构是{data:{list:[...]},code:0}接口要求 POST需要带Authorization头。SeaTunnel 的 Http Source 配置大概长这样source { HTTP { url http://127.0.0.1:1572/api/orders method POST headers { Authorization Bearer eyJhbGciOiJIUzI1NiJ9.example Content-Type application/json } body {page:1,page_size:100} json_field data.list result_table_name raw_orders schema { fields { order_id { type BIGINT } user_id { type BIGINT } total_amount { type DOUBLE } create_time { type STRING } } } } }这里的几个关键参数json_field从接口返回的 JSON 里提取数组的路径。如果返回是data.list就在这写data.list如果返回就是纯数组可以不配这项。schema.fields告诉连接器外部数据长什么样。建议所有字段都提前声明好尤其是大数字字段不显式标成 BIGINT 很容易在后续解析时被当成 DOUBLE 丢失精度。result_table_name给这块数据起个名字下游 Transform 或 Sink 里引用它用。有个容易被忽略的点body里如果用包裹实际提交时会是逐字发送的字符串。如果接口要求动态页码多数批量同步场景下我们可以通过外部调度把翻页次数拆成多个任务每个任务只拉一页或几页避免在 Source 里做复杂循环。3.2 Transform我在这里做了三件小事HTTP 接口返回的数据很少能直接落库我习惯在 Sink 之前加一层简单 Transform。就拿订单表来说做了三件事transform { FieldMapper { source_table_name raw_orders result_table_name transformed_orders field_mapper { order_id order_id user_id user_id total_amount amount create_time create_time } } }第一是字段重命名把外部的total_amount换成内部统一的amount第二是类型校正有些字段接口里返回字符串但 Doris 表里是 DECIMAL我一般在后续处理里统一转换第三是默认值兜底比如status字段可能为空如果直接写进 Doris可能会因为空串导致导入失败。关于 Transform我的建议是能用简单 Transform 解决的不要写成大逻辑。SeaTunnel 的 Transform 不是写 SQL 的地方复杂清洗还是应该放在 Doris 外部或者上游数仓里。轻量清洗留在链路里可以显著降低排错成本。3.3 Doris SinkStream Load 和 2PC 配置Doris Sink 的配置我用的是下面这组sink { Doris { fenodes doris-fe:8030 username root password 123456 table.identifier ods.orders sink.label-prefix seatunnel_orders sink.enable-2pc true sink.properties.format json sink.properties.read_json_by_line true } }讲三个重点fenodes填 FE 的 HTTP 地址和端口不要写 9030要用 8030。sink.label-prefixStream Load 的 label 前缀。label 在 Doris 里是幂等导入的核心凭证同一个 label 重复提交不会产生重复数据。SeaTunnel 会自动在 label 前缀后面拼上 task 和 checkpoint 信息。sink.enable-2pc两阶段提交。我强烈建议打开这样可以做到精确一次语义任务失败重跑时不用担心重复写入。如果关掉 2PC至少也要保证 label 前缀稳定否则恢复任务时无法去重。另外sink.properties.format设为json时一定要配合read_json_by_line true否则 Stream Load 会认为整个 JSON 是一行导致解析失败。这个坑我在第一次跑通时踩过日志里会报JSON parse error排查了半天最后发现是少了一个布尔配置。4. 排查 502 Bad Gateway那次让我看了一晚上日志的事故4.1 事故现场任务跑到一半抛了 unexpected status 502某天下午我把 SeaTunnel 的并行度从 2 调到 8想要“加快速度”结果任务跑了两分钟后直接失败控制台日志里的报错信息是unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:1572/api/orders注意这里的127.0.0.1:1572不是 Doris而是我们内部一个数据网关服务。它负责把内部接口的请求转发到后端的某个 SaaS 平台。看到 502 的第一反应是网关挂了但实际上网关本身还活着只是它在向上游转发请求时得不到及时响应于是向 SeaTunnel 返回了 502。4.2 排查链路curl、压测、线程池、连接复用我没有直接调配置而是按顺序做了这几件事用 curl 试一下接口本身一模一样的请求手动发一次返回 200数据正常。看 SeaTunnel 日志发现失败前连续发了几十次请求时间间隔越来越长明显是上游响应变慢。压测网关接口用简单的并发脚本模拟 20 个并发发现后端服务的 Tomcat 线程池被打满ActiveCount接近最大值。看网关日志大量Connection timeout进一步确认是后端服务处理不过来而不是网关拒绝对外提供服务。到这里问题其实已经清晰了SeaTunnel 并行度 8每个并行任务都会建立自己的 HTTP 请求流而我们的网关服务前面还有一层负载均衡连接被分散到不同后端节点热节点被持续打满以后就表现为 502。4.3 修复手段与最终配置最后我做了三件事缺一不可把 SeaTunnel 并行度降回 2并发太高是诱因但不是根因。降并行度只是缓解不能根治所以还得配合后两条。让网关服务的后端把超时阈值调大原来内部接口 5 秒没响应就超时数据量大时经常超过 5 秒调到 30 秒后 502 立刻少了很多。调整分页大小把body里的page_size从 100 调到 500同样数据量下请求次数变成原来的五分之一网关压力大幅下降。如果你不想动接口方也可以考虑在网关前加一层本地缓存或临时文件先把响应落盘再批量导入但这属于绕过问题不如从并发和分页两个源头控制来得直接。4.4 关于 HTTP 连接复用有一点必须说清楚很多人一看到 502 就怀疑是连接复用失效。我查了一轮代码和文档后确认 SeaTunnel 的 HTTP Source 底层使用 Apache HttpClient对同一个宿主机的连接默认是支持 Keep-Alive 复用的。但在实际使用中连接能不能复用还取决于服务端是否返回Keep-Alive头。如果服务端不配合客户端每次发请求都相当于重新建立 TCP 连接性能必然下降。在 SeaTunnel 这一层可以通过调整并行度和请求间隔来控制连接压力但连接池的具体大小、连接空闲回收时间这些参数目前没有完全暴露给用户。所以如果你的接口本身支持长连接可以在服务端确认Keep-Alive配置如果不支持那就别把并行度拉太高否则只会换来一堆 TIME_WAIT 和 502。5. 数据进来以后Doris 侧的合并与慢查询优化5.1 为什么刚导完数据要手动触发一下 Compaction用 SeaTunnel 连续导几轮订单数据后如果你用SHOW TABLET检查某个 tablet会发现版本数量非常多。这通常是因为 Stream Load 每次导入都会生成一个新的版本而 Doris 后台的 compaction 任务默认是按节奏跑的。频繁小批量导入时compaction 可能来不及消化查询就要合并很多版本性能肉眼可见地下降。这个时候可以手动触发一次合并命令大致是ALTER TABLE ods.orders COMPACT (MAJOR);合并完成后再用SHOW TABLET FROM ods.orders;检查每个 tablet 的版本数和数据量。生产环境我不建议频繁手动合并因为大部分场景下后台 compaction 调度已经够用但每次用 SeaTunnel 导完一批大增量手动触发一次能明显看到查询响应变快。需要注意的是不同 Doris 小版本的这个命令格式有差异以你部署版本的官方文档为准。5.2 慢查询优化的常见套路数据落库之后最容易被投诉的就是“报表怎么这么慢”。我总结过三类常见原因分区粒度不合适很多表是按天分区但查询只查最近一周结果扫到了半年数据。优化方式是建表时按天或按小时分区SQL 里尽量带上分区字段。分桶键选错如果user_id是常规过滤字段就不要拿order_id当唯一分桶键否则每个查询都要广播。合理做法是高频查询条件上的高基数字段作为分桶键。模型选择不对Duplicate 模型适合不更新的明细数据Unique 模型适合需要按主键去重的场景Aggregate 模型适合预聚合。如果选错了模型查询再优化也白搭。拿我们订单表举例最后改成CREATE TABLE ods.orders ( order_id BIGINT, user_id BIGINT, amount DECIMAL(12,2), create_time DATETIME ) DUPLICATE KEY(order_id) PARTITION BY RANGE(create_time) (...) DISTRIBUTED BY HASH(user_id) BUCKETS 16 PROPERTIES (replication_num 1);改完之后按create_time过滤并按user_id聚合的查询时间从 8 秒降到 1 秒以内。Doris 的前缀索引和分区裁剪在这个表结构下都能起作用。5.3 和 Flink SQL 写入 Doris 时的模型语义对照之前有人问过我Flink SQL 写 Doris 时Union Key 模型的表经常出现“实时结果对不上”的问题SeaTunnel 会不会也有类似情况。其实底层都是 Stream Load只是上层封装不同。这里的关键是搞清楚每种 Doris 模型的合并语义Unique 模型按 key 去重后到的数据覆盖先到的。SeaTunnel 写入时只要保证同一批次内 key 唯一加上 label 幂等不会有问题。Aggregate 模型按 key 做聚合比如 SUM/MAX/MIN。如果同步任务是批量导入要避免重复导入造成重复累加。Duplicate 模型不去重按理说不会出现“结果对不上”但如果重复导入明细数据就会翻倍。所以无论你用 Flink SQL 还是 SeaTunnel真正影响结果的是“源端有没有重复数据”和“Sink 侧有没有保证幂等”。在 SeaTunnel 里2PC 开启后 label 前缀固定重放不会产生重复导入这就是我强调打开 2PC 的原因。6. 复盘后最想留给后来者的话最后聊几个不那么技术、但能省几晚上觉的经验。第一不要在任务失败时才看日志要提前把 schema 和类型钉死。HTTP 接口返回的数字有时是字符串有时是数字SeaTunnel 解析时如果类型定义太宽泛Doris 导入就会在中途报错。与其事后变来变去不如第一版就把BIGINT、DECIMAL、DATETIME全部声明好。第二重视 label-prefix 和 2PC而不是依赖“重试就能成功”。同步任务最怕重复数据污染报表。SeaTunnel 的 Doris Sink 把这两个参数暴露出来是给生产环境兜底的建议从第一天起就打开别等出了重复数据再后悔。第三时区和时间格式一定要在 Transform 阶段统一。HTTP 接口返回的时间可能是2025-06-01 12:00:00也可能是 ISO 8601 格式Doris 的 DATETIME 并不接受所有格式。我在 Transform 里写过一个简单的Replace规则来统一格式这个步骤看起来小但能避免大量导入失败。第四监控至少看两个指标任务失败数和数据延迟。SeaTunnel 提供了简单的 Web 和 REST APIDoris 也有审计日志。任务挂了不要紧重要的是挂之前有没有暴露前兆。我现在每次上线新任务第一周都会每天看一眼这两个指标稳定后再降到每周。以上就是这次 HTTP 到 Doris 同步的全部实战内容。如果你也卡在类似的 502 或者连接复用问题上建议先压测上游接口再回头调 SeaTunnel 的并行度和分页大小大概率能解决。
SeaTunnel实战：HTTP接口数据同步到Doris的配置与排错指南
做数据对接的人大概都经历过这种时刻第三方接口限流、分页翻不到底、token 半小时过期一次你写好的 Python 脚本凌晨三点挂了然后你被电话叫醒。这不是段子是我这次把 HTTP 接口数据同步到 Doris 之前的真实状态。后来我用 SeaTunnel 把这条链路彻底改造成配置化任务跑了一周稳定无报错。这篇不是官方文档的复述是这次实战里所有踩过的坑、看过的日志、最后证明有效的配置适合正在为 HTTP 数据源接 Doris 发愁的同行参考。1. 为什么是 SeaTunnelHTTP 到 Doris 的选型逻辑1.1 原始方案Python 脚本和三座大山在切换到 SeaTunnel 之前我们用的是 Python requests 手写同步脚本。接口返回结构是常见的{code:0,data:{list:[...],has_more:true}}脚本要循环翻页每次还要处理 token 刷新。数据量小的时候没感觉等表从 1 万行涨到 500 万行三个问题彻底暴露故障恢复无状态跑到第 80 页挂了重启脚本时只能从第 1 页重新拉要么自己记游标要么忍受重复数据。网络波动靠重试硬扛requests 写重试看着简单但超时、连接重置、接口限流三种异常处理方式完全不同代码越补越乱。多表接入成本高每接一个 HTTP 接口就要复制一套分页和解析逻辑团队里有人喜欢用 dataclass有人喜欢写 dict维护成本直接失控。这些痛点不是不能解决但解决它们需要投入大量工程时间而这恰恰是最不值得写代码的部分。对接 HTTP 接口的本质无非是“发请求、拿数据、落库”真正复杂的是状态管理和异常恢复这部分交给成熟工具比自研靠谱得多。1.2 为什么最后是 SeaTunnel 而不是 Flink SQL 或 DataX我们内部其实对比过三个方向Flink SQL、DataX、SeaTunnel。当时的情况是方案运行环境同步复杂度断点续传扩展性自研脚本任意完全自己写需自己实现不灵活Flink SQL需要维护 Flink 集群需要写 SQL DDL 和 Connector自带强但运维成本高DataX独立进程插件丰富但写 HTTP 源要二次开发无依赖版本较老SeaTunnel轻量引擎可单机可集群配置化HTTP/Doris 官方插件自带支持大量 Connector还在扩展为了一个同步任务去起一套 Flink 集群对我们这种十人左右的数据组来说性价比太低。DataX 确实很成熟但官方没有特别顺手的 HTTP Source想接自定义接口还得自己写插件和自研没本质区别。SeaTunnel 的 HTTP Source 插件能直接解析 JSON 响应、支持 schema 映射Doris Sink 走 Stream Load几行配置就能把链路串起来是最快能落地的方案。这里多说一句后来我们团队里也有人试过用 Flink SQL 写 Doris Union Key 模型的表底层同样是 Stream Load。但对我们这种批量任务为主、峰值并发不高的场景SeaTunnel 的轻量特性非常舒服。它不需要常驻集群任务失败后通过 REST API 重新提交一次就能从上次 checkpoint 恢复省掉了很多维护成本。1.3 这条链路在 SeaTunnel 里的完整形态SeaTunnel 里一条 HTTP 同步任务大致长这样HTTP Source 按配置定时或按批次发起请求拿到 JSON 响应后经过 Transform 做字段处理最后交给 Doris Sink 通过 Stream Load 写入目标表。整个过程全部由一个配置驱动没有一行业务代码。架构上可以概括为Source 端HTTP 连接器负责鉴权、分页、解析把接口返回的嵌套 JSON 打平成一行行记录。Transform 端可以重命名字段、处理时间戳、补默认值、做简单的过滤。Sink 端Doris 连接器负责建 label、提交导入、处理失败重试走 Stream Load 通道进入 Doris 的 BE。这个形态最大的好处是每个环节都可以单独调试。后面的配置拆解部分我会把一份真实跑通的配置拿出来一行一行说。2. 部署阶段绕不开的版本与端口问题2.1 Doris 安装部署时我调整的几个参数刚开始我们图省事想在 Windows 开发机上直接装 Doris 客户端测试结果发现 Doris 官方对 Windows 原生部署并不友好FE 和 BE 都是以 Linux 为目标平台的。推荐的方式是用 Docker Desktop 起 Linux 容器或者直接在 Linux 服务器上部署。Windows 上也并非跑不了只是要绕一层虚拟机或容器调试时很多路径和权限问题会让你怀疑人生。Docker 方式部署 Doris 时我建议至少调整这几个地方BE 的mem_limit默认可能认为占满物理内存没问题但如果你不是一台独占机器建议手动限制否则很容易跟其他服务抢内存。我一般设成 8GB 左右。sys_log_level默认 INFO 日志量非常大排查问题时可以临时调成 DEBUG但平时保持 INFO 即可。数据目录挂载Docker 容器重启后数据会丢必须把 FE 和 BE 的数据目录挂到宿主机。还有一个容易被忽略的点BE 启动时的系统参数max open files要调大否则运行一段时间会出现文件句柄耗尽。这个在容器里尤其隐蔽外面看一切正常但任务莫名其妙失败最后看 BE 日志才发现是Too many open files。2.2 SeaTunnel 2.3.x 和 Doris Connector 的配套选择SeaTunnel 版本我推荐直接用官方最新的稳定发行版当时我们用的是 2.3.8。装好之后要确认connector-doris和connector-http这两个插件都在connectors/目录里。如果是从源码或者旧版本升上来的最容易遇到的问题是缺少 Doris 的客户端依赖导致任务提交后报ClassNotFoundException: doris这种问题基本就是 jar 没放全把对应 connector 的依赖包重新拷到lib/下即可。判断插件是否生效的简单办法bin/seatunnel.sh -l这个命令会列出引擎加载到的所有连接器。如果你能看到Doris和Http相关条目说明环境没问题。看不到就先别急着调配置回去检查connectors/目录的 jar 是否完整。还有一个经验SeaTunnel 和 Doris 都在快速迭代connector 和引擎版本不要相差太远。我在网上看到很多诡异问题最后都指向“用户把最新的 Doris connector 塞进了老版 SeaTunnel”字段解析方式变了自然跑不通。2.3 端口与网络Stream Load 走的是哪个口SeaTunnel 的 Doris Sink 底层用的是 Doris Stream Load它通过 FE 的 HTTP 端口提交导入请求默认是8030。所以你的任务调度机只要能访问到 FE 的8030就行不需要直接访问 BE 的8040数据端口。这一点容易踩坑很多人在安全组里只开了 Doris 的 MySQL 端口9030结果 SeaTunnel 一直连不上其实 Stream Load 走的是另一个端口。等到提交数据时如果日志出现unexpected status 502 bad gateway且 URL 指向 FE 或某个网关优先检查端口连通性和 FE 负载这就是我后面会展开排查的案例。3. 一份能跑通的 HTTP 到 Doris 同步配置拆解3.1 HTTP Source把嵌套 JSON 拍平我以实际项目中的一个订单接口为例。这个接口返回结构是{data:{list:[...]},code:0}接口要求 POST需要带Authorization头。SeaTunnel 的 Http Source 配置大概长这样source { HTTP { url http://127.0.0.1:1572/api/orders method POST headers { Authorization Bearer eyJhbGciOiJIUzI1NiJ9.example Content-Type application/json } body {page:1,page_size:100} json_field data.list result_table_name raw_orders schema { fields { order_id { type BIGINT } user_id { type BIGINT } total_amount { type DOUBLE } create_time { type STRING } } } } }这里的几个关键参数json_field从接口返回的 JSON 里提取数组的路径。如果返回是data.list就在这写data.list如果返回就是纯数组可以不配这项。schema.fields告诉连接器外部数据长什么样。建议所有字段都提前声明好尤其是大数字字段不显式标成 BIGINT 很容易在后续解析时被当成 DOUBLE 丢失精度。result_table_name给这块数据起个名字下游 Transform 或 Sink 里引用它用。有个容易被忽略的点body里如果用包裹实际提交时会是逐字发送的字符串。如果接口要求动态页码多数批量同步场景下我们可以通过外部调度把翻页次数拆成多个任务每个任务只拉一页或几页避免在 Source 里做复杂循环。3.2 Transform我在这里做了三件小事HTTP 接口返回的数据很少能直接落库我习惯在 Sink 之前加一层简单 Transform。就拿订单表来说做了三件事transform { FieldMapper { source_table_name raw_orders result_table_name transformed_orders field_mapper { order_id order_id user_id user_id total_amount amount create_time create_time } } }第一是字段重命名把外部的total_amount换成内部统一的amount第二是类型校正有些字段接口里返回字符串但 Doris 表里是 DECIMAL我一般在后续处理里统一转换第三是默认值兜底比如status字段可能为空如果直接写进 Doris可能会因为空串导致导入失败。关于 Transform我的建议是能用简单 Transform 解决的不要写成大逻辑。SeaTunnel 的 Transform 不是写 SQL 的地方复杂清洗还是应该放在 Doris 外部或者上游数仓里。轻量清洗留在链路里可以显著降低排错成本。3.3 Doris SinkStream Load 和 2PC 配置Doris Sink 的配置我用的是下面这组sink { Doris { fenodes doris-fe:8030 username root password 123456 table.identifier ods.orders sink.label-prefix seatunnel_orders sink.enable-2pc true sink.properties.format json sink.properties.read_json_by_line true } }讲三个重点fenodes填 FE 的 HTTP 地址和端口不要写 9030要用 8030。sink.label-prefixStream Load 的 label 前缀。label 在 Doris 里是幂等导入的核心凭证同一个 label 重复提交不会产生重复数据。SeaTunnel 会自动在 label 前缀后面拼上 task 和 checkpoint 信息。sink.enable-2pc两阶段提交。我强烈建议打开这样可以做到精确一次语义任务失败重跑时不用担心重复写入。如果关掉 2PC至少也要保证 label 前缀稳定否则恢复任务时无法去重。另外sink.properties.format设为json时一定要配合read_json_by_line true否则 Stream Load 会认为整个 JSON 是一行导致解析失败。这个坑我在第一次跑通时踩过日志里会报JSON parse error排查了半天最后发现是少了一个布尔配置。4. 排查 502 Bad Gateway那次让我看了一晚上日志的事故4.1 事故现场任务跑到一半抛了 unexpected status 502某天下午我把 SeaTunnel 的并行度从 2 调到 8想要“加快速度”结果任务跑了两分钟后直接失败控制台日志里的报错信息是unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:1572/api/orders注意这里的127.0.0.1:1572不是 Doris而是我们内部一个数据网关服务。它负责把内部接口的请求转发到后端的某个 SaaS 平台。看到 502 的第一反应是网关挂了但实际上网关本身还活着只是它在向上游转发请求时得不到及时响应于是向 SeaTunnel 返回了 502。4.2 排查链路curl、压测、线程池、连接复用我没有直接调配置而是按顺序做了这几件事用 curl 试一下接口本身一模一样的请求手动发一次返回 200数据正常。看 SeaTunnel 日志发现失败前连续发了几十次请求时间间隔越来越长明显是上游响应变慢。压测网关接口用简单的并发脚本模拟 20 个并发发现后端服务的 Tomcat 线程池被打满ActiveCount接近最大值。看网关日志大量Connection timeout进一步确认是后端服务处理不过来而不是网关拒绝对外提供服务。到这里问题其实已经清晰了SeaTunnel 并行度 8每个并行任务都会建立自己的 HTTP 请求流而我们的网关服务前面还有一层负载均衡连接被分散到不同后端节点热节点被持续打满以后就表现为 502。4.3 修复手段与最终配置最后我做了三件事缺一不可把 SeaTunnel 并行度降回 2并发太高是诱因但不是根因。降并行度只是缓解不能根治所以还得配合后两条。让网关服务的后端把超时阈值调大原来内部接口 5 秒没响应就超时数据量大时经常超过 5 秒调到 30 秒后 502 立刻少了很多。调整分页大小把body里的page_size从 100 调到 500同样数据量下请求次数变成原来的五分之一网关压力大幅下降。如果你不想动接口方也可以考虑在网关前加一层本地缓存或临时文件先把响应落盘再批量导入但这属于绕过问题不如从并发和分页两个源头控制来得直接。4.4 关于 HTTP 连接复用有一点必须说清楚很多人一看到 502 就怀疑是连接复用失效。我查了一轮代码和文档后确认 SeaTunnel 的 HTTP Source 底层使用 Apache HttpClient对同一个宿主机的连接默认是支持 Keep-Alive 复用的。但在实际使用中连接能不能复用还取决于服务端是否返回Keep-Alive头。如果服务端不配合客户端每次发请求都相当于重新建立 TCP 连接性能必然下降。在 SeaTunnel 这一层可以通过调整并行度和请求间隔来控制连接压力但连接池的具体大小、连接空闲回收时间这些参数目前没有完全暴露给用户。所以如果你的接口本身支持长连接可以在服务端确认Keep-Alive配置如果不支持那就别把并行度拉太高否则只会换来一堆 TIME_WAIT 和 502。5. 数据进来以后Doris 侧的合并与慢查询优化5.1 为什么刚导完数据要手动触发一下 Compaction用 SeaTunnel 连续导几轮订单数据后如果你用SHOW TABLET检查某个 tablet会发现版本数量非常多。这通常是因为 Stream Load 每次导入都会生成一个新的版本而 Doris 后台的 compaction 任务默认是按节奏跑的。频繁小批量导入时compaction 可能来不及消化查询就要合并很多版本性能肉眼可见地下降。这个时候可以手动触发一次合并命令大致是ALTER TABLE ods.orders COMPACT (MAJOR);合并完成后再用SHOW TABLET FROM ods.orders;检查每个 tablet 的版本数和数据量。生产环境我不建议频繁手动合并因为大部分场景下后台 compaction 调度已经够用但每次用 SeaTunnel 导完一批大增量手动触发一次能明显看到查询响应变快。需要注意的是不同 Doris 小版本的这个命令格式有差异以你部署版本的官方文档为准。5.2 慢查询优化的常见套路数据落库之后最容易被投诉的就是“报表怎么这么慢”。我总结过三类常见原因分区粒度不合适很多表是按天分区但查询只查最近一周结果扫到了半年数据。优化方式是建表时按天或按小时分区SQL 里尽量带上分区字段。分桶键选错如果user_id是常规过滤字段就不要拿order_id当唯一分桶键否则每个查询都要广播。合理做法是高频查询条件上的高基数字段作为分桶键。模型选择不对Duplicate 模型适合不更新的明细数据Unique 模型适合需要按主键去重的场景Aggregate 模型适合预聚合。如果选错了模型查询再优化也白搭。拿我们订单表举例最后改成CREATE TABLE ods.orders ( order_id BIGINT, user_id BIGINT, amount DECIMAL(12,2), create_time DATETIME ) DUPLICATE KEY(order_id) PARTITION BY RANGE(create_time) (...) DISTRIBUTED BY HASH(user_id) BUCKETS 16 PROPERTIES (replication_num 1);改完之后按create_time过滤并按user_id聚合的查询时间从 8 秒降到 1 秒以内。Doris 的前缀索引和分区裁剪在这个表结构下都能起作用。5.3 和 Flink SQL 写入 Doris 时的模型语义对照之前有人问过我Flink SQL 写 Doris 时Union Key 模型的表经常出现“实时结果对不上”的问题SeaTunnel 会不会也有类似情况。其实底层都是 Stream Load只是上层封装不同。这里的关键是搞清楚每种 Doris 模型的合并语义Unique 模型按 key 去重后到的数据覆盖先到的。SeaTunnel 写入时只要保证同一批次内 key 唯一加上 label 幂等不会有问题。Aggregate 模型按 key 做聚合比如 SUM/MAX/MIN。如果同步任务是批量导入要避免重复导入造成重复累加。Duplicate 模型不去重按理说不会出现“结果对不上”但如果重复导入明细数据就会翻倍。所以无论你用 Flink SQL 还是 SeaTunnel真正影响结果的是“源端有没有重复数据”和“Sink 侧有没有保证幂等”。在 SeaTunnel 里2PC 开启后 label 前缀固定重放不会产生重复导入这就是我强调打开 2PC 的原因。6. 复盘后最想留给后来者的话最后聊几个不那么技术、但能省几晚上觉的经验。第一不要在任务失败时才看日志要提前把 schema 和类型钉死。HTTP 接口返回的数字有时是字符串有时是数字SeaTunnel 解析时如果类型定义太宽泛Doris 导入就会在中途报错。与其事后变来变去不如第一版就把BIGINT、DECIMAL、DATETIME全部声明好。第二重视 label-prefix 和 2PC而不是依赖“重试就能成功”。同步任务最怕重复数据污染报表。SeaTunnel 的 Doris Sink 把这两个参数暴露出来是给生产环境兜底的建议从第一天起就打开别等出了重复数据再后悔。第三时区和时间格式一定要在 Transform 阶段统一。HTTP 接口返回的时间可能是2025-06-01 12:00:00也可能是 ISO 8601 格式Doris 的 DATETIME 并不接受所有格式。我在 Transform 里写过一个简单的Replace规则来统一格式这个步骤看起来小但能避免大量导入失败。第四监控至少看两个指标任务失败数和数据延迟。SeaTunnel 提供了简单的 Web 和 REST APIDoris 也有审计日志。任务挂了不要紧重要的是挂之前有没有暴露前兆。我现在每次上线新任务第一周都会每天看一眼这两个指标稳定后再降到每周。以上就是这次 HTTP 到 Doris 同步的全部实战内容。如果你也卡在类似的 502 或者连接复用问题上建议先压测上游接口再回头调 SeaTunnel 的并行度和分页大小大概率能解决。
