企业官网建设流程全解析

1. 为什么流处理环境值得做成镜像

第一次在某团队帮忙排查 Flink 作业问题，进到机器里一看，flink-conf.yaml的修改时间比bin/flink晚了两周，日志目录指向的磁盘只挂了 20G，ulimit -n还是默认的 1024，三台 TaskManager 里有两台 JDK 版本不一致。那次排查最后发现是其中一台机器的 JVM 参数没同步，导致 Managed Memory 分配和另外两台差出一截，Checkpoint 时频繁超时。这类问题单看代码根本看不出来，全是环境漂移埋下的。

所谓Apache Flink 流处理环境镜像，说白了就是把一套能跑 Flink 的操作系统底座、JDK、Flink 发行包、目录结构、内核参数、启动脚本，全部打包成一个可重复分发的最小单元。以CentOS / Rocky系发行版为底座，是因为大量企业内部的老集群、离线机房、虚拟化平台，默认给的还是这一类系统的模板，生态兼容性最好，运维熟悉的排查工具链也齐全。

它解决的核心问题不是"怎么装 Flink"，而是装完之后怎么保证第十次装出来跟第一次一模一样。适合三类人参考：一是要给团队搭开发/联调环境的工程师，二是准备把跑在物理机上的 Flink 迁移到容器化平台、但对底层参数没底的运维，三是做 POC 验证时反复重建集群、被环境差异折腾过的人。下文所有内容按 Flink 1.18/1.19 这一代的内存模型和配置项来讲，更早的版本在内存参数上有差异，我会在相应位置标注。

2. 镜像的分层设计：哪些该固化，哪些该外置

2.1 四层结构拆解

把 Flink 环境做成镜像，最容易犯的错是"一把梭"，把配置文件、日志、Checkpoint、JAR 包全打进镜像层里。结果是每次改个并行度都要重新构建、重新推仓库、重新拉起，镜像体积还越滚越大。我的习惯是切成四层，各层职责明确，变更频率从下往上递增。

这张表的核心逻辑是：凡是"跟版本绑定"的固化进镜像，凡是"跟业务或环境绑定"的外置出去。JDK 版本和 Flink 版本是强绑定的，Flink 1.18 起官方主推 JDK 17，而老项目可能还卡在 JDK 11，这个组合关系必须固化，否则十台机器能跑出三种行为。反过来，jobmanager.rpc.address这种一眼就跟部署环境有关的东西，写死在镜像里等于给未来挖坑。

顺带说一个具体的好处：当配置外置后，做版本回滚就变成"把挂载的配置文件换成上一版"，而不是"重新构建一个镜像再推下去"。在故障恢复的场景里，这个时间差可能就是几分钟和半小时的区别。

2.2 目录规划与挂载点设计

Flink 默认把临时文件丢在/tmp下，这在单机上没问题，在容器里就是灾难——/tmp通常跟容器可写层绑在一起，Checkpoint 一多直接把节点磁盘顶满，容器还不会自己恢复。所以目录规划要在镜像构建阶段就定死，并且明确哪些路径必须是外部挂载的。

/opt/flink # 发行包根目录，镜像内只读为佳 /opt/flink/conf # 配置目录，建议挂载覆盖 /opt/flink/log # 日志，必须挂载 /opt/flink/checkpoints # Checkpoint 落盘，必须挂载（或指向对象存储） /opt/flink/savepoints # Savepoint，必须挂载 /opt/flink/plugins # 连接器插件，按需挂载 /opt/flink/usrlib # 用户 JAR，按需挂载 /data/flink/tmp # io.tmp.dirs 指向这里

关键点在最后一行。Flink 的三个地方会写临时文件：Shuffle 数据、RocksDB 的本地状态目录、以及部分连接器的缓冲。默认全部走/tmp，而/tmp在很多基础镜像里是 tmpfs，内存盘，状态一大直接触发节点级 OOM。所以我会在构建时把io.tmp.dirs显式指向一个位于数据盘的目录，并且这个目录不做持久卷挂载，容器重建时自然清空，避免残留的 RocksDB 文件导致下一次启动读到脏状态。

注意：如果state.backend.type用的是rocksdb，本地状态目录默认在io.tmp.dirs下。这个目录不要配置成持久卷，进程异常退出后的残留文件有可能让新实例加载失败，报的是"state 文件无法解析"这类看不出根因的错误。

2.3 用户、权限与系统参数

这三块是"出事之后最难回溯"的部分。Flink 官方镜像默认用flink用户，UID 通常是 9999。如果你在 Kubernetes 里跑，Pod 的securityContext里必须显式声明同一个 UID，否则挂载进去的目录归属会不对，表现为 JobManager 启动时报"Permission denied"写日志。这个坑我见过不止一次，排查思路是先看id输出的 UID，再看挂载目录的 owner，两个对不上就是它。

系统参数方面，镜像里能改的有限，但下面几个我会在entrypoint里做运行时设置：

# 文件句柄数，Flink 的 Network Buffer 和 RocksDB 都会吃大量 fd ulimit -n 65536 # 关闭 swap，避免 JVM 被换出导致 GC 停顿飙升 # 容器内需宿主机配合，镜像里只能做提示检查 sysctl -w vm.swappiness=1 2>/dev/null || true

ulimit -n这个值不是拍脑袋来的。Flink 的 Network Buffer 每个 TaskManager 默认会分配taskmanager.memory.network对应的一批 buffer，加上 RocksDB 打开的文件、Checkpoint 上传的连接、日志文件的 fd，一个中等负载的 TaskManager 跑到 3000 到 5000 个 fd 很常见。默认 1024 的话，报错信息通常是"Too many open files"，但出现在业务侧的日志里，看起来像是连接器的 bug。

vm.overcommit_memory建议设成 1。Flink 的内存配置是"预分配"思路，JVM 启动时就会按process.size申请一大块，如果宿主机开了严格 overcommit，容器很容易在启动阶段就被内核拒绝。这个参数在镜像里改不了，只能在部署时通过宿主机或 Pod 的sysctls设置，我在文档里会单独标出来。

3. 从零构建一个能跑的 Flink 镜像

3.1 基础层：别省掉系统初始化

很多人直接从rockylinux:9起步，装完 JDK 和 Flink 就完事。我建议单独抽一个系统初始化层，把时区、locale、工具链这些东西一次处理掉。原因很实际：Flink 的事件时间处理、Watermark、窗口触发，全都依赖时间语义，系统时区不对会让日志时间戳和业务时间对不上，排查问题时第一眼就被带偏。

FROM rockylinux:9 ARG FLINK_VERSION=1.19.1 ARG FLINK_SCALA=2.12 ARG FLINK_HOME=/opt/flink ENV LANG=en_US.UTF-8 \ LC_ALL=en_US.UTF-8 \ TZ=Asia/Shanghai \ FLINK_HOME=${FLINK_HOME} \ PATH=${FLINK_HOME}/bin:${PATH} RUN dnf -y install \ java-17-openjdk-headless \ tar gzip procps-ng hostname which nc util-linux \ && dnf clean all \ && rm -rf /var/cache/dnf /var/log/dnf.log

几个细节值得说。java-17-openjdk-headless比完整版少了图形库，体积能小一百多兆，Flink 用不上 Swing 那套东西。procps-ng提供ps、free、top，容器里排查问题全靠它，省了它之后kubectl exec进去连进程状态都看不见。hostname和which是 Flink 启动脚本config.sh里会用到的，缺了会报一些很隐晦的错。

没有直接curl下 Flink 包，是因为很多内网构建环境访问不了外网。稳妥做法是提前把 tgz 放到构建上下文里，用COPY拷进去。这一点我在后面 3.2 会展开。

3.2 JDK 与 Flink 安装的细节坑

Flink 1.18 之后官方推荐 JDK 17，1.15 到 1.17 用 JDK 11 更稳。这里的"稳"不是说 JDK 17 有问题，而是指存量连接器生态。很多老版本的 Kafka、HBase、JDBC 连接器在 JDK 17 上会遇到模块访问限制，报InaccessibleObjectException。这种情况要么升连接器，要么在env.java.opts.all里加--add-opens参数，后者属于打补丁，不推荐长期用。

# 方式一：外网可达时直接下载并校验 RUN curl -fsSL -o /tmp/flink.tgz \ https://archive.apache.org/dist/flink/flink-${FLINK_VERSION}/flink-${FLINK_VERSION}-bin-scala_${FLINK_SCALA}.tgz \ && tar -xzf /tmp/flink.tgz -C /opt \ && mv /opt/flink-${FLINK_VERSION} ${FLINK_HOME} \ && rm -f /tmp/flink.tgz # 方式二：离线构建，tgz 放在构建上下文目录 dist/ 下 # COPY dist/flink-${FLINK_VERSION}-bin-scala_${FLINK_SCALA}.tgz /tmp/flink.tgz # RUN tar -xzf /tmp/flink.tgz -C /opt \ # && mv /opt/flink-${FLINK_VERSION} ${FLINK_HOME}

Scala 版本这个参数很多人会忽略。Flink 发行包分scala_2.12和scala_2.11（老版本）两种，选用哪个取决于你要提交的作业 JAR 是用哪个 Scala 版本编译的。如果作业 JAR 和发行包不一致，运行时会报NoSuchMethodError或者ClassNotFoundException，指向的还是 Scala 标准库里的类，很容易被误判成业务代码问题。

非 root 用户的创建要放在安装之前还是之后，其实都可以，但我会放在解压之后，然后用chown一次性把整个FLINK_HOME归给flink用户。这样镜像里所有文件归属干净，后续挂载卷时只需要关心外部目录的权限。

RUN groupadd -g 9999 flink \ && useradd -u 9999 -g flink -m -d /home/flink -s /bin/bash flink RUN mkdir -p ${FLINK_HOME}/checkpoints \ ${FLINK_HOME}/savepoints \ ${FLINK_HOME}/log \ ${FLINK_HOME}/usrlib \ /data/flink/tmp \ && chown -R flink:flink ${FLINK_HOME} /data/flink USER flink WORKDIR ${FLINK_HOME}

3.3 配置文件逐条拆解

flink-conf.yaml是整个环境的灵魂，但官方模板里有几百行注释，全打开会让人抓不住重点。我按"必须显式配置"和"保持默认"两类拆，下面这份是单机/小集群场景的起点配置。

# ---------- 集群身份 ---------- jobmanager.rpc.address: flink-jobmanager jobmanager.rpc.port: 6123 jobmanager.bind-host: 0.0.0.0 taskmanager.bind-host: 0.0.0.0 rest.address: 0.0.0.0 rest.port: 8081 # ---------- 内存（详见第 4 章的计算）---------- jobmanager.memory.process.size: 2048m taskmanager.memory.process.size: 4096m taskmanager.memory.managed.fraction: 0.4 taskmanager.memory.network.fraction: 0.1 # ---------- 并发与槽位 ---------- taskmanager.numberOfTaskSlots: 4 parallelism.default: 4 # ---------- 状态与检查点 ---------- state.backend.type: hashmap state.checkpoints.dir: file:///opt/flink/checkpoints state.savepoints.dir: file:///opt/flink/savepoints execution.checkpointing.interval: 60s execution.checkpointing.mode: EXACTLY_ONCE execution.checkpointing.timeout: 10min execution.checkpointing.min-pause: 30s # ---------- 临时目录 ---------- io.tmp.dirs: /data/flink/tmp # ---------- JVM ---------- env.java.opts.all: -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/opt/flink/log

这里挑几个容易写错的讲。

jobmanager.bind-host和taskmanager.bind-host不设成0.0.0.0的话，容器内的服务只会监听在回环地址上，外面的 TaskManager 连不进来。这个问题在裸机上不明显，因为默认就是localhost，本机通信没问题；一旦上了容器网络就暴露。

state.backend.type在新版本里替代了老的state.backend，后者在 1.19 里已经标记为废弃，虽然还能用但会打警告。hashmap适合状态量在几百 MB 级别的场景，超过这个量级换rocksdb，代价是序列化开销增加、吞吐下降一到两成。

execution.checkpointing.min-pause是我强烈建议显式设置的。它的作用是两次 Checkpoint 之间留出最小间隔，默认是 0，意味着上一次刚结束马上开始下一次。如果 Checkpoint 耗时接近间隔时间，会出现"一直在做 Checkpoint"的情况，业务吞吐直接腰斩。设成间隔的一半左右（60s 间隔配 30s）是个合理的起点。

env.java.opts.all里的HeapDumpOnOutOfMemoryError和路径也要配。没有 heap dump 的 OOM 排查基本靠猜，而默认路径经常落在只读目录或者容量很小的卷上，等于白配。

3.4 启动脚本与健康检查

官方镜像的jobmanager.sh start是后台启动，容器里这么干会导致主进程立刻退出、容器被判定为结束。必须用start-foreground。另外角色切换我用一个ROLE环境变量控制，同一个镜像既能起 JobManager 也能起 TaskManager，省得维护两个镜像标签。

#!/usr/bin/env bash set -euo pipefail ROLE="${ROLE:-taskmanager}" echo "[entrypoint] role=${ROLE} flink_home=${FLINK_HOME}" ulimit -n 65536 || true case "${ROLE}" in jobmanager) exec "${FLINK_HOME}/bin/jobmanager.sh" start-foreground ;; taskmanager) exec "${FLINK_HOME}/bin/taskmanager.sh" start-foreground ;; *) echo "[entrypoint] unknown ROLE: ${ROLE}" >&2 exit 64 ;; esac

exec这个关键字不能少。不写exec的话，shell 会成为 PID 1，Flink 进程变成它的子进程，容器收到 SIGTERM 时信号传不到 Flink，表现为停止容器要等满 30 秒宽限期然后被强杀，Checkpoint 来不及做完，状态就成了最后一次成功的那份lias。这个现象在滚动升级时会集中爆发。

健康检查分角色写：

# JobManager 检查 REST 接口 HEALTHCHECK --interval=15s --timeout=5s --start-period=40s --retries=3 \ CMD ["sh", "-c", "curl -fsS http://127.0.0.1:8081/overview >/dev/null || exit 1"]

TaskManager 没有 REST 端口，只能用nc探 RPC 端口或者查进程。我通常用进程检查，因为它更贴近"服务还活着"这个语义：

pgrep -f "org.apache.flink.taskmanager.TaskManagerRunner" >/dev/null

start-period这个参数别省。Flink 冷启动要加载一堆类、初始化内存池、注册到 JobManager，40 秒是个保守值，如果你的镜像里插件多，可能要调到 60 秒以上。不设的话，容器还没起来就被判成不健康，编排系统会反复重启，陷入启动死循环。

4. 资源规划与内存参数换算

4.1 TaskManager 数量与槽位的计算

这块最常见的误区是"slot 越多越好"。slot 的本质是一个 TaskManager 上能并行跑的任务组数量，每个 slot 会分到一份独立的 Managed Memory 和 Network Buffer。slot 数过多，单 slot 分到的内存就少，RocksDB 容易报MemoryAllocationException；slot 数过少，资源利用率上不去。

我的计算顺序是这样的：

1. 先算作业的总并行度需求。假设作业里有 5 个算子，最大并行度分别是 8、8、4、4、2，那么作业默认并行度可以取 4，总 slot 需求是4 × 5 = 20个（考虑 slot 共享的话会更少，但保守起来按算子链断开估算）。
2. 再看单机资源。假设给 Flink 的容器配额是 16 核 32G，taskmanager.memory.process.size取 8G，那么一台机器放 4 个 TaskManager 比较合适，留一半内存给系统和页缓存。
3. 每个 TaskManager 配 4 个 slot，4 台机器就是4 × 4 × 4 = 64个 slot，覆盖上面 20 个需求绰绰有余。

用表格更直观：

那个"余量"是刻意留的。Flink 在做故障恢复、或者做 Savepoint 后重启作业时，需要有空闲 slot 才能重新调度。如果 slot 卡得死死的，一次 TaskManager 掉线就会导致整个作业无法恢复，卡在RESTARTING状态。

4.2 内存模型拆解与手算示例

Flink 1.10 之后统一了内存模型，1.15 起进一步收敛。现在只需要配taskmanager.memory.process.size一个值，其他按比例自动切分。但自动切分的结果未必符合你的场景，所以还得知道怎么手算。

整体结构：

Total Process Memory ├── Total Flink Memory │ ├── Framework Heap（默认 128m） │ ├── Framework Off-heap（默认 128m） │ ├── Task Heap（剩余部分） │ ├── Task Off-heap（默认 0） │ ├── Managed Memory（默认 fraction=0.4） │ └── Network（默认 fraction=0.1） ├── JVM Metaspace（默认 256m） └── JVM Overhead（默认 fraction=0.1，min=192m，max=1024m）

以taskmanager.memory.process.size: 4096m为例，逐步算：

算出来 Task Heap 大约 1.4G，这个量级跑一般业务够用。但如果作业里有大窗口聚合、或者用了堆内状态后端，1.4G 很容易不够，表现是频繁 Full GC。这时候的调整方向不是简单加大process.size，而是先把managed.fraction降下来，把内存让给 Task Heap，因为 Managed Memory 是给 RocksDB 和批处理算子用的，堆内状态后端用不上它。

# 堆内状态后端场景：压缩 Managed，扩大 Task Heap taskmanager.memory.managed.fraction: 0.1 taskmanager.memory.network.fraction: 0.1 taskmanager.memory.task.heap.size: 2048m # 剩余部分自动补足

反过来，如果用 RocksDB 做状态后端、状态量在几十 GB，就要把managed.fraction提到 0.5 甚至 0.6，因为 RocksDB 的写缓冲、Block Cache 全靠这块内存。有个经验值：状态量每 10G，Managed Memory 至少配 1G，否则 RocksDB 会频繁刷盘，写放大严重。

JobManager 的内存相对简单，jobmanager.memory.process.size默认 1600m，中小集群够用。但如果你的作业数量超过 50 个，或者用了大量广播状态，建议提到 2048m 到 3072m，因为 JobManager 要维护所有作业的 ExecutionGraph 和 Checkpoint 元数据。

4.3 磁盘、网络与时间同步

磁盘这块被低估得最多。除了 Checkpoint 目录，还有两个地方吃盘：日志和本地状态。日志默认在$FLINK_HOME/log，开了 DEBUG 级别之后一天几 GB 很正常。我通常配log4j2.properties做滚动，保留 7 天、单文件 100MB、最多 10 个。

appender.rolling.strategy.type = DefaultRolloverStrategy appender.rolling.strategy.max = 10 appender.rolling.policies.size.size = 100MB

网络方面，容器环境要注意 MTU。宿主机 MTU 是 1500，overlay 网络会减去封装头，变成 1450 左右。如果 Flink 的 Network Buffer 尺寸（默认 32KB）在路径上被分片，吞吐会明显下降。这个不是配置能解决的，只能确认网络插件的 MTU 设置，并且在压测时观察numRecordsOutPerSecond是否有异常抖动。

时间同步必须提。Flink 的 Watermark 依赖事件时间，而 Checkpoint 的对齐、超时判定依赖处理时间。如果容器所在节点的时间漂移超过几秒，会出现 Checkpoint 明明做完了却被判定超时的情况。Rocky 系用 chrony，容器里通常不装守护进程，靠宿主机同步，所以部署前必须确认所有节点的时间偏差在 1 秒以内：

chronyc tracking | grep -E "System time|Last offset"

5. 集群编排与提交作业的实操过程

5.1 编排模板与配置注入

前面提到配置文件外置，具体怎么注入？Flink 从 1.9 起支持FLINK_PROPERTIES环境变量，里面写的配置项会覆盖flink-conf.yaml里的同名项。这个机制特别适合容器场景，因为不用改文件、不用重新构建镜像。

services: jobmanager: image: flink-stream:1.19.1-rocky9 container_name: flink-jobmanager environment: ROLE: jobmanager FLINK_PROPERTIES: | jobmanager.rpc.address: flink-jobmanager jobmanager.memory.process.size: 2048m taskmanager.numberOfTaskSlots: 4 parallelism.default: 4 state.checkpoints.dir: file:///opt/flink/checkpoints execution.checkpointing.interval: 60s ports: - "8081:8081" volumes: - ./conf/log4j2.properties:/opt/flink/conf/log4j2.properties:ro - ./data/checkpoints:/opt/flink/checkpoints - ./data/logs/jm:/opt/flink/log healthcheck: test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8081/overview || exit 1"] interval: 15s timeout: 5s retries: 3 start_period: 40s taskmanager: image: flink-stream:1.19.1-rocky9 environment: ROLE: taskmanager FLINK_PROPERTIES: | jobmanager.rpc.address: flink-jobmanager taskmanager.memory.process.size: 4096m taskmanager.numberOfTaskSlots: 4 state.checkpoints.dir: file:///opt/flink/checkpoints volumes: - ./data/checkpoints:/opt/flink/checkpoints - ./data/logs/tm:/opt/flink/log depends_on: jobmanager: condition: service_healthy deploy: replicas: 2

depends_on里的condition: service_healthy是关键的。不写这个，TaskManager 会比 JobManager 先起来，然后陷入重试注册的循环，日志里全是Connection refused，看起来像网络问题，实际上是启动顺序问题。Flink 本身有重试机制，最终能连上，但会浪费一两分钟，而且日志噪音很大。

FLINK_PROPERTIES的写法有个坑：多行配置要用 YAML 的|块标量，每行一个key: value，前面不能有 tab，只能用空格。用 tab 缩进会被 Flink 解析成非法配置项，报的错是"Unrecognized option"，但不会告诉你是哪一行。

5.2 作业提交的三种方式对比

提交作业这件事，选哪种方式决定了后续的运维复杂度。

在镜像方案的语境下，如果你只是做 POC 或者内部工具，Session 模式最省事，JobManager 常驻，docker exec进去提交就行：

docker exec -it flink-jobmanager /opt/flink/bin/flink run \ -d \ -c com.example.StreamJob \ /opt/flink/usrlib/stream-job.jar

如果是生产环境，我更倾向 Application 模式。因为 Session 模式下所有作业共享一个 JobManager 的 JVM 堆，作业一多，JobManager 的 GC 就成了瓶颈，而且一个作业的类加载冲突会波及全部作业。Application 模式每个作业独立一套，隔离性最好，代价是资源利用率低一些。

还有一个常被忽略的点：作业 JAR 的依赖冲突。如果作业 JAR 里有和 Flink 内置版本冲突的库（比如不同的 Jackson 版本），Session 模式下会直接影响其他作业。所以无论哪种模式，我都会在构建作业 JAR 时用 shade 插件做 relabel，把com.fasterxml.jackson重定位到自己的包名下。

5.3 Checkpoint 与状态落盘的落地配置

本地文件系统的 Checkpoint 只适合 POC。一旦上生产，必须换成分布式存储。在最简的容器方案里，可以用 NFS 挂载，把state.checkpoints.dir指向挂载点：

state.checkpoints.dir: file:///mnt/flink-state/checkpoints state.savepoints.dir: file:///mnt/flink-state/savepoints state.backend.type: rocksdb state.backend.incremental: true

state.backend.incremental这个开关对 RocksDB 特别重要。开启增量 Checkpoint 后，每次只上传变化的 SST 文件，Checkpoint 的耗时和网络带宽占用能降一个数量级。代价是恢复时需要读更多的文件，恢复时间会变长。在我的实测里，状态量 50G 左右、每小时增量 1G 的场景下，全量 Checkpoint 要 4 分钟，增量只要 20 秒，但恢复从 1 分钟涨到了 3 分钟。这个取舍要看你的 RTO 要求。

还有一点：state.checkpoints.dir必须在所有 JobManager 和 TaskManager 上路径一致且可写。容器里如果只有 TaskManager 挂载了这个目录、JobManager 没挂，Checkpoint 会在最后一步失败，报的错是"Could not complete checkpoint"，但不会明确说是权限问题。这个坑我在某项目上踩过，排查了半天才发现是挂载配置漏了一行。

6. 常见问题排查实录

6.1 容器起来就退出

这是最高频的问题，按可能性排序：

第一，ROLE变量没设或拼错。脚本里默认值是taskmanager，所以如果拼成TaskManager，会走到*)分支直接exit 64。

第二，jobmanager.rpc.address解析不到。容器里没配 DNS，或者服务名写错，jobmanager.sh start-foreground会在启动阶段抛异常退出。排查方法是看完整日志，别只看最后几行。

第三，内存参数不合法。比如taskmanager.memory.process.size: 4096m而taskmanager.memory.task.heap.size: 4096m，两者冲突，Flink 会在校验阶段报错。这类错信息比较明确，一般不会卡太久。

第四，挂载的flink-conf.yaml是 Windows 换行符。CRLF 会让 YAML 解析失败，报的错指向第一行，看起来莫名其妙。构建镜像时统一用 LF，或者用dos2unix处理一遍。

6.2 Checkpoint 超时与失败的排查路径

我整理了一张速查表，从左到右是排查顺序：

反压这一项值得展开。Flink UI 上的 Backpressure 面板显示 HIGH 时，说明下游消费速度跟不上。但"下游"是相对概念，要在拓扑图里逐个算子看，找到第一个显示 HIGH 的节点，问题就在它和它上游之间。常见原因是外部存储的写吞吐瓶颈，比如 Kafka 分区数不够、数据库连接池太小。这类问题改 Flink 配置没用，得从外部系统下手。

6.3 反压、数据倾斜与并行度调整

数据倾斜的表现是：整体反压很高，但每个 TaskManager 的 CPU 使用率都上不去，只有个别 slot 打满。原因是某个 key 的数据量远超其他 key，全部落到同一个 subtask 上。

排查方法是在作业里加一段临时的 key 统计，或者打开 Flink 的metrics.latency.interval，看各个 subtask 的numRecordsInPerSecond。如果最大值和最小值差 10 倍以上，基本可以确认。

处理手段按侵入性排序：先在业务侧做两阶段聚合（加随机前缀打散，聚合后再去前缀二次聚合），这是最彻底的；其次是调整 keyBy 的逻辑，把热点 key 拆分；最后才是加大并行度，但这招对真热点无效，只是把其他 key 摊薄了。

关于并行度调整，有个经验：并行度不要超过 Kafka 分区数。Kafka source 的并行度受分区数限制，你设 16 个并行度但 topic 只有 4 个分区，那 12 个 source subtask 就是空转的，白白占着 slot。这个数字在扩容时最容易忘记同步。

6.4 磁盘写满与日志膨胀

镜像方案里磁盘写满的根因通常是三个：日志没滚动、Checkpoint 没清理、本地状态没清。

日志的滚动配置前面讲过。Checkpoint 的清理由state.checkpoints.num-retained控制，默认是 1，也就是只保留最新一份。但如果你的 Checkpoint 目录里堆了几百个文件夹，说明这个参数被改过，或者有历史残留。清理时要小心，删之前先确认最新的那份是完整的（有_metadata文件且大小正常）。

本地状态目录是/data/flink/tmp，这个目录在 RocksDB 场景下会随状态量增长。正常情况下作业停止时会清空，异常退出则残留。所以我在启动脚本里加了一段可选清理：

if [ "${CLEAN_TMP_ON_START:-false}" = "true" ]; then rm -rf /data/flink/tmp/* echo "[entrypoint] tmp dir cleaned" fi

默认关掉是有原因的：如果进程是被误杀的，残留的本地状态其实还能用，清掉反而要全量从 Checkpoint 恢复。只有在明确遇到"加载本地状态失败"时才手动开这个开关。

7. 版本升级与镜像维护

7.1 滚动升级的顺序不能错

Flink 的版本升级不是停一套起一套那么简单，尤其是带状态的作业。正确的顺序是：

1. 用旧版本做一次 Savepoint，确认路径和大小正常。
2. 停掉所有 TaskManager，再停 JobManager。反过来的话，JobManager 会以为 TaskManager 掉线，触发不必要的故障恢复。
3. 换新版本镜像，先起 JobManager。
4. 从 Savepoint 恢复作业。
5. 确认作业状态正常后，再逐步替换 TaskManager。

跨大版本升级时，Savepoint 的兼容性要提前验证。Flink 官方提供了Stateful Functions的迁移工具，但对于自定义状态类型（比如自己实现的TypeSerializer），升级后可能读不出来。稳妥做法是先在测试环境完整走一遍，用生产的 Savepoint 副本恢复，看能不能成功。

还有一点：state.savepoints.dir的路径在升级前后必须一致，否则恢复命令里的路径对不上。我见过有人在升级时顺手改了目录结构，结果 Savepoint 找不到，只能从更早的 Checkpoint 恢复，丢了一段数据。

7.2 镜像瘦身与构建缓存

镜像体积直接影响分发速度和节点拉取时间。几个有效的手段：

第一，dnf clean all之后删掉/var/cache/dnf，这个目录在 Rocky 上能有几百兆。第二，Flink 发行包里的examples/目录和opt/下的部分可选 JAR 可以删掉，能省一百多兆。第三，用多阶段构建，把下载和解压放在一个阶段，只把最终目录COPY到运行阶段。

FROM rockylinux:9 AS builder # ... 下载、解压、裁剪 ... RUN rm -rf ${FLINK_HOME}/examples ${FLINK_HOME}/opt/flink-*-*.jar FROM rockylinux:9 COPY --from=builder /opt/flink /opt/flink

构建缓存的利用上，把变更频率低的层放前面。flink-conf.yaml和entrypoint.sh这两层要放在最后，因为它们改动最频繁。如果把COPY conf/放在安装 JDK 之前，每次改配置都会导致后面所有层重新构建，一次构建从 30 秒变成 5 分钟。

我在实际维护这套镜像的过程中体会最深的是，镜像的价值不在于"装好了"，而在于"装的东西可以被审计"。每一次参数改动、每一个 JDK 补丁，都留下了可追溯的记录，而不是散落在某台机器的/etc/sysctl.conf里。这件事在单机时代看起来多余，等到集群规模上去、人员换过两轮之后，就成了救命的东西。最后分享一个小习惯：我会在镜像的LABEL里打上构建时间、Flink 版本、JDK 版本三个字段，排查问题时docker inspect一眼就能确认对方跑的是不是我以为的那个版本，省掉很多"你这版本对吗"的来回确认。