做数据同步这么多年，我一直觉得 HTTP 接口是最"鸡肋"的数据源——说它难吧，无非是发个请求解析 JSON；说它简单吧，等你在生产环境跑上一周，各种超时、502、连接耗尽接踵而至。最近用 Apache SeaTunnel 接了一批 HTTP 接口同步到 Doris，从最初的"能跑通"到后来"跑得稳、跑得快"，中间踩了不少坑，尤其是那个unexpected status 502 bad gateway: unknown error的错误，排查了整整一个下午。这篇就把我的配置优化过程和问题排查思路完整写出来，给正在用 SeaTunnel 做接口类数据同步的朋友一个参考。
标题里的三个关键词——SeaTunnel、HTTP、Doris——组合起来其实是一套很典型的数据接入方案：从第三方系统或内部老系统的 HTTP API 拉数据，落到 Doris 里做 OLAP 分析。适合谁看？正在搭建数据中台、BI 报表底座，或者想把散落的接口数据统一汇聚的工程师，尤其是第一次用 SeaTunnel 的读者。下面的内容不会只给配置，我会把每一步选型逻辑和配置原因也讲清楚，这样你遇到相似问题的时候能自己去推，而不是靠猜。
1. 为什么我会用 SeaTunnel 来接 HTTP 接口和 Doris
1.1 这个方案解决的真实业务场景
当时项目背景是这样：公司内部的订单系统和库存系统对外暴露了一批 REST API，没有提供数据库直连权限，数据以 JSON 形式分页返回。BI 部门要做经营看板，需要把这些接口数据每天同步到 Doris 里做 OLAP 分析。接口有十来个，单个接口一天的数据量在几十万条左右，不大，但接口数量多、字段结构乱、鉴权方式还不统一。
最早是用 Python 脚本写的同步任务，每个接口一个脚本，requests 库发请求、解析 JSON、批量写入。跑了两周问题就来了：某个接口偶尔超时，脚本没有重试机制，数据就少了；接口调整了字段，脚本直接报 KeyError；调度靠 crontab，挂了没有告警，等到 BI 看板数据对不上才被发现。说白了，脚本不是不能做，但把"请求-解析-转换-写入-重试-监控"这一整套逻辑在每个接口脚本里都实现一遍，维护成本太高了。
这时候我意识到需要一个统一的同步框架，把"从数据源拿数据"和"把数据写到目标端"这两件事做成配置化的能力。SeaTunnel 就是在这个背景下进入选型视野的。
1.2 选型逻辑：框架那么多，为什么是 SeaTunnel
当时也对比了其他方案，这里直接说我的判断依据：
| 方案 | HTTP 数据源支持 | Doris 写入支持 | 维护成本 | 结论 |
|---|---|---|---|---|
| DataX | 需要自己写 Reader 插件 | 有 writer 但版本维护一般 | 中 | 不够顺手 |
| Kettle | 支持 HTTP 组件 | 依赖 JDBC 写入，性能一般 | 高 | 太重了 |
| 自研同步脚本 | 自己实现 | 自己实现 | 高 | 不推荐 |
| SeaTunnel | 原生 Http 插件 | 原生 Doris 插件（Stream Load 方式） | 低 | 选定 |
SeaTunnel 最吸引我的点有三个。第一，它原生支持 HTTP Source 和 Doris Sink，不需要自己写插件，配置声明式声明字段映射就行，这对接口类数据同步来说太关键了。第二，Doris 的 Sink 是基于 Stream Load 实现的，这是 Doris 官方推荐的导入方式，性能远好过 JDBC 一条条 insert。第三，SeaTunnel 本身支持多数据源并行同步，同一个任务里可以配置多个 Source，这在以后接口数量增长时非常有价值。
当然它也有边界。SeaTunnel 不是一个通用的 ETL 计算引擎，它强在"同步"而不是"复杂加工"。如果你的数据在同步过程中需要做大量的窗口计算、多流 join，那应该用 Flink，而不是 SeaTunnel。我们这里场景就是接口数据到数仓，中间偶有简单的字段清洗转换，SeaTunnel 的 transform 插件足够应付，选它是合理的。
提示：如果你的需求是以实时流式计算为主，SeaTunnel 不适合，它是批式和微批同步工具。如果只是把接口数据周期性搬到 Doris，它就是很合适的选择。
2. HTTP Source 配置细节：从"能通"到"稳定"
2.1 最小可跑通的配置
先给一个最基础的配置，版本以 SeaTunnel 2.3.x 为例（不同小版本的参数名可能略有差异，以官方文档为准）。假设接口地址是http://127.0.0.1:1572/api/v1/orders，返回 JSON 中数据放在data字段里面：
source { Http { url = "http://127.0.0.1:1572/api/v1/orders" method = "GET" header = { Content-Type = "application/json" } result_table_name = "orders_raw" schema { fields { id = BIGINT amount = DECIMAL(10, 2) status = STRING create_time = STRING } } } } sink { Doris { fenodes = "doris-fe:8030" username = "root" password = "" table.identifier = "ods.orders" sink.label.prefix = "ods_orders_http" doris.config { format = "json" read_json_by_line = "true" } } }这个配置里有几个关键点需要理解。schema.fields定义了从 HTTP 接口拿到的 JSON 数据的结构，SeaTunnel 会按照这里声明去解析；result_table_name是数据在 SeaTunnel 内部的临时表名，Transformer 和 Sink 都通过这个名字引用数据。Doris 端的read_json_by_line = "true"表示 Stream Load 导入时按行解析 JSON，这个必须和上游输出的格式对应上。
我第一次跑通时，最容易被坑的就是 schema 字段类型对不上。接口返回的amount是字符串 "12.30" 而不是数字 12.30，我声明成 DECIMAL 就报错。后来统一做法：不确定类型的字段全部先按 STRING 接，落到 Doris 之后再用 SQL 转。这不是最优解，但能减少同步层不必要的解析失败。
2.2 鉴权、分页和响应结构处理
生产环境的接口不会像上面那么简单，这里把高频场景的操作方式说一遍。
鉴权。常见的有两种。一种是静态 token，直接放在 header 里：
header = { Content-Type = "application/json" Authorization = "Bearer eyJhbGciOiJIUzI1Ni..." }另一种是动态鉴权，比如先调用鉴权接口拿 token，再带着 token 请求业务接口。这种情况 SeaTunnel 的 Http 插件本身不支持"先请求 A 再拿返回值拼到 B 的请求头"，我的做法是写一个简单的脚本定时刷新 token 到本地文件，再用header里读取文件内容的方式（如果版本支持）或者干脆在业务接口前面加一层轻量代理，把鉴权逻辑收敛到代理里。更建议后者，因为同步框架不应该承担过多业务鉴权逻辑。
分页。接口分页通常有几种风格：page/pageSize、offset/limit、cursor 游标。每一页的 URL 最好传参方式如下：
url = "http://127.0.0.1:1572/api/v1/orders?page=1&pageSize=1000"SeaTunnel 的 Http Source 插件每次任务启动时请求一次 URL，所以它是"单次拉取"还是"自动翻页"，取决于插件版本。较新版本有pagination相关配置，但我在实践过程中发现稳定做法是：写一个外层 Shell 脚本循环传入 page 参数，每个 page 启动一个 SeaTunnel 任务，或者干脆在接口侧提供一个支持时间范围 + 大分页（比如一次 5000 条）的批量查询接口，同步层只拉一次。
响应结构。绝大多数接口不会直接返回数组，而是包一层{ "code": 0, "data": [...] }这种结构。SeaTunnel Http 插件默认会把整个响应体交给 schema 解析，如果外层不是数组而是对象，就需要用json_field指定数据字段（具体参数名因版本而异），或者在上游接口做约束。我们在实际项目中就是和接口提供方约定：同步用的数据接口统一返回 JSON 数组，省去解析层损耗。
2.3 连接复用的原理与配置
这是本文最想展开的地方，因为"HTTP 连接复用"直接关系到一个 502 排错。先补一下基础。
HTTP 协议本身是无状态的，每次请求都要走 TCP 三次握手、发送数据、四次挥手。如果每次请求都新建 TCP 连接，那在高频请求场景下，握手和挥手的开销占比非常大，同时目标服务器的连接数会被快速打满。连接复用（也叫 keep-alive 或连接池）解决了这个问题：客户端与服务端建立一条 TCP 连接之后，在这条连接上连续发送多个 HTTP 请求，避免反复建连断开。
SeaTunnel 的 Http Source 插件底层用的是 Apache HttpClient，它本身有连接池机制。但在实际使用中，如果插件没有妥善处理连接释放——比如响应体没有读取完就关闭，或者没有正确配置 keep-alive——就会出现"连接没有真正被复用"的情况。
我们在配置侧能控制的，主要是并发度和超时参数。Http Source 不适合开高并行度去拉同一个接口，因为目标接口多数没有针对大数据量同步做过并发优化，开高了反而把对端打挂。我后来把任务的并行度压到 1 或 2，同时在接口侧确认开启了 keep-alive，并检查了网关层（如果接口前面有 Nginx）的 keepalive_timeout 配置，确保长连接不被快速回收。
这一节总结一句：HTTP 连接复用不是 SeaTunnel 一个参数就能解决的，它需要客户端（SeaTunnel）、网络链路、目标服务器（或网关）三端配合。遇到连接相关的问题，先画一条"请求从 SeaTunnel 到目标服务的完整链路"，然后逐层排查。
3. 502 Bad Gateway 排查实录：问题就藏在连接复用上
3.1 错误现场和初步判断
任务跑了一段时间后，日志里开始频繁出现这个错误：
unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:1572/api/v1/orders注意这里 URL 是127.0.0.1:1572，说明 SeaTunnel 和目标服务在同一台机器上。当时第一反应是"目标服务挂了"，但 curl 手动请求接口完全正常，服务进程也在，内存 CPU 都没异常。这就排除掉了服务本身宕机的情况。
既然目标服务还活着，为什么网关会返回 502？502 的标准含义是网关从上游服务器收到了无效响应——换句话说，SeaTunnel 的请求经过了某个代理层（或者是目标服务前面的网关），网关尝试连接后端服务时失败了，或者后端响应超时被网关判定为不可用。
3.2 完整排查链路：从现象到根因
我把自己排错的过程完整列出来，你可以按这个顺序复现：
- 用 curl 直接请求目标地址，确认服务本身正常。结果正常返回，说明应用层没问题。
- 检查 SeaTunnel 日志，确认是哪个 Source 的哪个任务在报错。发现报错集中在早上 10 点那批任务——正好是上游系统集中推送数据、同步并发最高的时候。
- 查看目标服务的访问日志和连接数。这是转折点。日志显示在报错时间段，来自 SeaTunnel 的请求频繁创建新连接，目标服务的 ESTABLISHED 连接数飙升到几千，达到了服务的连接数上限，之后新的连接请求就被拒绝或排队超时，网关于是返回 502。
- 抓包确认连接复用情况。在目标服务上用 tcpdump 抓包，能明显看到同一批请求中，TCP 三次握手的 SYN 包比例异常高。正常情况下，大量请求应该通过已建立的连接发送，不会反复 SYN/SYN-ACK。
- 定位到连接没有按预期复用。根源在于两个层面：一是 SeaTunnel Http Source 在高频请求场景下，由于响应体消费不完整导致 HttpClient 连接池里的连接被判定为不可复用，不断新建连接；二是目标服务侧并发剧增后，网关健康检查或后端连接 backlog 参数偏小，加剧了 502 的产生。
3.3 解决方案与效果
针对上面的根因，我从三个方向做了调整：
| 调整项 | 操作 | 目的 |
|---|---|---|
| SeaTunnel 并行度 | 将涉及该接口的任务并行度调为 1，避免同时建立大量连接 | 从客户端减少连接风暴 |
| 目标服务网关 keep-alive | 网关 keepalive_timeout 调大到 75s，确保已建立的连接不被过早回收 | 让连接池里的连接生命周期更长 |
| 响应体消费 | 升级到修复了连接释放问题的 SeaTunnel 版本，并在接口侧调整响应数据量 | 从源头避免连接被 HttpClient 判定为不可复用 |
调整之后跑了 48 小时，任务零报错。从连接数看，高峰值明显下降了一个数量级，稳定多了。
这次排错给我最大的启发是：502 不一定是对端服务挂了，更多时候是"对端忙不过来"或者"连接没能复用"。遇到类似错误，先别急着重启服务，去看看对端连接数和连接建立频率，那里往往藏着真正的问题。
4. Doris Sink 写入优化：除了能写，还要写得快、查得快
4.1 Doris Sink 的核心参数解读
Doris 的写入走 Stream Load 是性能最稳的路线，SeaTunnel 的 Doris Sink 插件封装好了这套协议。配置上几个关键参数：
sink { Doris { fenodes = "doris-fe:8030" username = "root" password = "" table.identifier = "ods.orders" sink.label.prefix = "ods_orders_http" sink.enable.batch.update = false doris.config { format = "json" read_json_by_line = "true" column_separator = "\\t" } max_retries = 3 } }这里注意几个容易出错的地方。
sink.label.prefix是 Stream Load 的 label 前缀，Doris 通过 label 实现导入的幂等性。同一个 label 不能重复，所以这里一定要带上足够区分任务实例的信息（比如日期或批次号），否则重复导入时会报 label conflict。
sink.enable.batch.update默认关闭。如果你不需要更新已有行的部分字段，保持默认关着就好。开启它会影响写入性能。
max_retries是失败重试次数。要特别强调：Doris Stream Load 失败重试可能造成数据重复。如果导入任务在数据已经写入 Doris 但响应超时的情况下失败，重试会再次写入一遍相同的数据。所以在上游同步层尽量保证 sink 的幂等，或者在 Doris 表设计上做好去重约束。
4.2 表模型选择对写入的影响
Doris 表有三种模型，选择直接影响写性能和查询性能：
| 模型 | 去重/更新策略 | 适合场景 | 写入性能 |
|---|---|---|---|
| Duplicate Key | 不去重，保留多份 | 明细流水、日志、事实表 | 最高 |
| Unique Key | 按 Key 去重，后写入覆盖先写入 | 业务实体表、状态类数据 | 中（merge-on-write 后性能提升明显） |
| Aggregate Key | 按 Key 做预聚合 | 汇总表、指标表 | 中 |
HTTP 接口同步过来的数据，如果是订单流水这种明细数据，果断用 Duplicate Key，写入性能最好，查询也灵活。如果是客户信息表这种需要按 ID 覆盖更新的，用 Unique Key。有一点提醒：Unique Key 模型如果用的是默认的 merge-on-write 关闭状态，大批量高频导入会产生较多版本，查询时会有 merge 开销，建议在 Doris 2.0+ 上开启 merge-on-write，导入和查询性能都稳定不少。
我当时从接口拉的订单流水就是用的 Duplicate Key，同步稳定后 BI 查询秒级返回。后来加了一个客户维表，用了 Unique Key，也在开启 merge-on-write 之后性能恢复正常。
4.3 小文件堆积与手动触发合并
用 SeaTunnel 同步的常见问题之一，是任务频率高、每批数据量小，Doris 里产生大量小版本。小版本多了之后，查询时需要合并的版本数变多，慢查询就会冒出来。这时候除了降低导入频率、增大批次数据量之外，Doris 也支持手动触发合并操作让表先完成一次 compaction。
触发方式是执行 SQL：
ALTER TABLE ods.orders COMPACT;或者是通过 FE 的 HTTP API 触发（版本不同命令有差异）。手动触发的意义在于：当系统因为某些原因没有及时对高频写入的表做 compaction 时，可以让它在查询高峰期之前先完成一次合并，减少查询时的 merge 开销。
这类问题最有效的预防方式还是在源头：单次导入数据量不要太小。经验值是 Stream Load 单次导入最好在几十 MB 以上，如果单次数据量太小，就延长同步周期或者积攒数据批量写入，避免小文件风暴。
5. 接入调度后的坑与增量同步方案
5.1 DolphinScheduler + SeaTunnel 的落地注意点
同步任务稳定之后，就要接入调度系统了。我们用的是 DolphinScheduler（热词里也出现了 ds + seatunnel），这里说几个落地时容易踩的坑。
第一，任务提交方式。DS 调用 SeaTunnel 一般是执行命令行脚本，类似seatunnel.sh --config xxx.conf。要注意 DS worker 节点的环境变量和 SeaTunnel 的安装路径，最好在脚本里显式 exportSEATUNNEL_HOME，避免出现"手动执行没问题，调度执行找不到命令"的情况。
第二，资源目录权限。SeaTunnel 运行时会在$SEATUNNEL_HOME/logs和 checkpoint 目录写文件。DS 默认任务运行用户可能是dolphinscheduler，如果这个用户对 SeaTunnel 目录没有写权限，任务会在启动阶段静默失败。提前用chown把关联目录权限放好。
第三，任务隔离。SeaTunnel 任务分一次性同步任务和常驻流式任务，DS 上如果是定时调度，一定要用一次性任务模式，否则任务不退出，DS 会一直判定任务在运行中，造成任务堆积。
5.2 增量同步的常用手段
HTTP 接口同步天然没有 binlog 这类机制，增量全靠自己设计。两种常见路径：
路径一：接口有业务时间字段。比如订单有create_time，那就把同步时间参数化。SeaTunnel 支持在配置中使用变量，提交时通过-i传入：
seatunnel.sh -i date=20240520 -i page=1 --config orders.conf配置文件里：
url = "http://127.0.0.1:1572/api/v1/orders?date=${date}&page=${page}"调度系统每天跑任务时，把当天日期传进去，就能实现按天的增量拉取。
路径二：接口没有增量字段。这种接口最少见但也最麻烦。我的处理方式是全量拉到 Doris 的临时表，然后用一次INSERT INTO target SELECT ... FROM temp去重合并。注意临时表和目标表要分开，避免导入中途失败污染目标表数据。这种方案要求数据量不能太大，几十万条级别的方案完全可行。
关于增量这里还有一个小提醒：如果接口支持按时间范围查询，不要把"增量"做成"最近 24 小时"这种简单粗暴的逻辑，遇到上游补数会漏数据。更稳的做法是留一个可配置的时间窗口偏移，比如默认拉最近 3 天的数据，然后目标表用 Unique Key 做覆盖，既有增量同步的效率，又能兜住补数场景。
6. 排查问题时的工具与方法论
这个章节是我额外加给自己的经验总结。排查数据同步问题，尤其是 HTTP 接口层的问题，很多情况下靠看日志和猜是低效的。这里分享一套我用的方法。
网络层问题用 tcpdump 和 ss。先看连接数：
ss -s ss -ant | grep 1572 | wc -l当连接数异常高时，基本可以排除接口逻辑问题，转向连接管理方向。
应用层问题用 curl 快速确认。在目标机上直接 curl 请求接口，对比 SeaTunnel 的报错信息。如果 curl 正常但 SeaTunnel 报错，说明问题出在 SeaTunnel 的请求方式（Headers、连接管理、超时配置）而不是服务端。
日志定位法。遇到问题先看 SeaTunnel 的完整堆栈，而不是只看最后的错误信息。错误信息往往只告诉你"哪一步失败了"，堆栈才会告诉你"为什么失败"。很多 502 错误的原因其实是前面哪次请求超时把连接池里的连接搞掉了。
批量验证配置。修改完配置后，不要只跑一次任务就认为解决了。我会用一个循环脚本连续触发 10 次同步，看是否仍然报错，同时观察目标服务的连接数曲线，确认真的是平稳了。一次成功不代表问题修复，100 次稳定才是。
7. 写在最后的心得
这套 HTTP 到 Doris 的同步链路，现在已经稳定跑了几个月。从一开始用 Python 脚本的手忙脚乱，到 SeaTunnel 配置化后的省心，再到踩了 502、小版本堆积这些坑，整个过程让我重新理解了数据同步这件事：工具只是把同步的"最后一公里"做好了，真正的挑战在连接管理、幂等设计和写入节奏控制上。
如果让我给刚开始做这个方向的朋友一个建议，那就是：先小规模跑通，再逐步加接口和调度；不要把所有的并发和性能优化在一开始就全部堆上去。同步链路这个领域，问题往往是在运行几天之后才出现的，不要太早相信"已经稳定了"。
最后分享一个小技巧：SeaTunnel 配置尽量用 Git 管理起来，每个接口一个配置文件，文件名带上接口名称和同步类型（如orders_full.conf、orders_incr.conf）。这样无论是排查问题还是新增接口，都能快速定位。遇到问题先在测试环境复现，别在生产环境反复试，这个习惯能帮你省下大量的时间和晚上的好觉。
