4.4 导入排错工单实录
4.4 导入排错工单实录
本节摘要：这一节是全书的"事故黑板"：十一张真实工单，每张按"现象—初判—确诊—处置—预防"五段记录。它们覆盖了 Doris 导入链路上绝大多数高频故障，其中版本堆积、内存超限、消费位点漂移三类占了全部导入类工单的一半以上。读法建议：先记住诊断顺序，再逐案对照细节。
学习目标
阅读完本节，你应当能够：
- 把任何一条新报错归位到数据层/资源层/集群层的某一层；
- 独立处理一次版本堆积引起的写入拒绝；
- 排查 Routine Load 从 PAUSED 到彻底失联的演进过程；
- 为自己团队沉淀一份同结构的工单模板。
一、总纲：三层定位法
导入类故障几乎都能塞进三个抽屉：
- 数据层：格式、编码、空值表达、字段数量、列映射——错误样本里有具体行号；
- 资源层：内存上限、磁盘水位、版本计数保护、连接并发——错误文案指向限额词；
- 集群层：BE 宕机、网络分区、元数据服务抖动——表现为批量任务同时阵亡。
判定优先级永远是：看错误 URL 拿证据，再按抽屉排除，最后动手。以下各案例的标题就是值班时最先看到的那句话。
图 4-4：症状到病因的诊断路由图
二、十一个工单速览
工单一：too many tablet versions / 写入被拒。 现象：Stream Load 高峰段整批返回失败，文案指向版本上限。确诊：某热点日分区在半小时内被上游脚本切成两万个小批。处置：上游改为一分钟聚合批发送，集群侧放宽后台压缩线程权重过渡；二十分钟后恢复。预防：为每张实时表配置"导入速率 × 批次大小"的下限校验。
工单二：close index channel failed（深层多为 BE 节点退出）。 现象：Routine Load 整体 PAUSED，重试无效。确诊：一台 BE 因宿主机 OOM 重启中，其上 Tablet 无法形成发布多数派。处置：等 BE 回归并自动补副本后 RESUME PAUSED 的作业。预防：PAUSED 告警叠加 BE 存活检测做联动。
工单三：Label Already Exists 但上游说没写过。 现象：新任务莫名拒收。确诊：上游把 Label 的日期部分写成了固定常量，昨天成功的那次还占着名字。处置：修正生成逻辑加入序列号。预防：Code Review 清单加一条"Label 必含递增成分"。
工单四：json 格式解析大量失败于凌晨三点。 现象：同样代码白天正常夜间雪崩。确诊：上游工程夜间开启日志压缩合并，嵌套结构从一层变为两层。处置：该来源切换 jsonpath 显式声明取值路径。预防：Schema 变更走契约通知，禁止静默升级。
工单五：Broker Load 卡在 LOADING 四小时不动。 现象：进度条停在同一百分比。确诊：HDFS 源目录有一条文件正被上游追加写出。处置：等上游收口或改用快照路径。预防：批源目录只允许原子改名进入。
工单六：Insert Into Select 中途取消。 现象：库内加工语句频繁失败。确诊：默认查询超时对亿级扫描太紧，且执行内存撞上单查询限额。处置：调高该会话的超时与内存参数。预防：库内加工纳入调度平台统一管理长参数。
工单七：Routine Load 消费延迟持续增长但状态 RUNNING。 现象：大屏延迟从秒级爬到十分钟。确诊：目标表分桶过少导致单作业并行度顶死，吞吐天花板低于生产速率。处置：配合 3.4 的换桶方案迁移。预防：容量评估必须包含"导入吞吐天花板"一栏。
工单八：删除标记差异引发下游翻倍口径。 现象：报表 GMV 与财务系统差出退款金额。确诊：上游以软删除字段标记作废订单，Doris 侧没人实现过滤。处置：视图层加过滤并约定硬同步节奏。预防：接入清单强制回答"删除如何表达"。
工单九：时区偏移八小时的幽灵分区。 现象：海外采集的数据全进了错误的日分区。确诊：上游时间戳带时区而列定义按本地零区解析。处置：入库前显式转换标准化。预防：全公司事件时间戳规范统一为 UTC 毫秒。
工单十：内存限额导致空跑成功却无数据。 现象：极小批次偶发无响应被网关超时，重试又撞 Label 保护。确诊：表处于频繁 Compaction，微批等待发布超时。处置：开源攒批粒度，避开压缩高峰。预防：监控里加"发布等待时长"分布。
工单十一：权限变更后整组作业熄火。 现象：故障发生在例行权限梳理次日。确诊：作业运行账号被回收导入权限，PAUSED 重试全部拒绝。处置：恢复账号授权后 RESUME。预防：账号生命周期流程必须包含"现有作业影响面检查"步骤。
三、两个案例的完整展开
选前两类最高频的案子把五段式走完整。
版本堆积案（工单一）深描。 背景：营销活动当天埋点量翻了五倍，采集端沿用每条事件一次 Stream Load 的旧策略。操作：先冻结上游增量（启用缓冲队列保序），期间用管理接口确认分数阈值突破情况，随后把采集端改造为本地队列一分钟聚合提交，恢复灌入后观察两小时曲线回稳。结果：实际中断二十二分钟，无数据丢失——缓冲队列按序重放靠 Label 幂等兜底。解读：这类事故的本质是"写入节奏超出存储消化的常数速度"，根治只能动节奏，放宽保护阀只是续命。变式：若上游无法改造，可用 Group Commit 在服务端合并小写，代价是可见延迟略增。
消费延迟案（工单七）深描。 背景：订单流业务量随大促预告逐步抬升，Cluster 未扩容。现象发现于例行大盘：kafka 分组滞后值曲线出现台阶式抬升。操作：核对作业内部并行度=三、Kafka 分区数=十二、单 BE 吞吐实测约持平于当前流量下限，判断瓶颈在表级并行度而非集群总体资源。结果与解读：由于短周期不能改桶，先临时增设第二个作业实例分组消费不同分区做双通道写入（同表异组不冲突），争取一周内完成宽表换桶迁移。变式教训：容量规划要写进上线评审——"这张表的灌入天花板是多少 QPS"应有实测答案而非纸面估计。
⚠️ 常见坑：把"放宽保护阀"当成万能解法。版本上限与内存限制的保护动作都在替你挡更大范围的雪崩，先修形态再谈参数。
四、为你自己的团队留一份模板
工单五段式之所以有效，在于它强迫记录三样东西：确诊依据（不是猜测）、实际处置（不是计划）、以及预防条款（可进 Code Review 或监控项）。建议每周例会挑一张本周最贵的工单全文朗读，半年后你会发现新同学的排障直觉明显更像老司机——因为黑板上挂着的都是你们自己的案例。
常见疑问
问：工单速览里的现象怎么快速对应到三层抽屉？ 记关键词：错误文案里带行号、格式、字段的一律进"数据层"；带 limit、memory、timeout 的一律进"资源层"；整批任务同时失败、状态集体异常的进"集群层"。文案不会直接给答案，但几乎总会暗示抽屉——训练自己先读文案再动手，能省掉一半的弯路。
本节要点回顾
- 三层抽屉定位：数据有样本、资源有限额词、集群批量阵亡。
- 版本堆积治理顺序：稳上游、松调度、修形态，最后才碰阈值。
- PAUSED 是过程不是结论：连着 BE 存活与账号状态一起查。
- 口径类事故占隐性成本大头：删除语义与时区规范要制度化。
- 五段式模板的复利：每张工单都在训练下一个值班的人。
导入链路至此收官。下一章我们把注意力转向另一半日常——已经进来的数据为什么查得慢。