Flink Standalone 本地一键起集群、Session/Application 两种模式、HA 高可用与排障清单

1. Standalone 适合什么场景？

• 本地快速验证：SQL/Connector/UDF 先跑通
• 测试环境：不想引入 K8s/YARN 的复杂度
• 小规模稳定集群：资源固定、运维能接受手工管理
• 想把“Flink 运行机制”看得更清楚：进程、日志、端口、类加载都一目了然

如果你需要自动扩缩容、资源隔离、作业弹性调度，通常就要上 Kubernetes 或 YARN。

2. 准备工作

Standalone 的基本要求很简单：

• Java 1.8+（Flink 2.x 生产更建议 Java 17）
• 下载并解压 Flink 发行版
• 类 UNIX 环境（Linux / macOS / Cygwin）

你只要记住一个路径：Flink 解压后的根目录，后面所有脚本都从这里跑。

3. 30 秒起一个 Standalone 集群（Session Mode）

Session Mode 的特点：先启动一个长期运行的集群，再往里面提交多个作业。最适合本地/测试/共享集群。

3.1 启动集群

# 进入 Flink 根目录./bin/start-cluster.sh

启动后至少会起来两个进程：

• JobManager（含 Web UI）
• TaskManager（执行算子）

Web UI 默认在：

• http://localhost:8081

3.2 提交一个示例作业

./bin/flink run ./examples/streaming/TopSpeedWindowing.jar

3.3 停止集群

./bin/stop-cluster.sh

很多同学第一次跑到这里就结束了，但真正实战的关键在下面：Session/Application、脚本管理、HA 与排障。

4. Session Mode vs Application Mode：怎么选不纠结

4.1 Session Mode（start-cluster.sh）

• 你先起一个集群，多个作业共享 TaskManager 资源
• 优点：启动快、成本低、适合多人共用测试
• 风险：一个作业搞崩 TM，可能影响同机器上其他作业；资源抢占更明显

典型用法：

• 本地 SQL Client 提交 SQL 作业
• 测试集群长期在线，大家都往里投作业

4.2 Application Mode（standalone-job.sh）

Application Mode 的特点：为一个应用（通常一个 main）启动一个 JobManager，作业“贴着 JobManager 跑”，资源隔离更好。

核心脚本：

• bin/standalone-job.sh启动带应用的 JobManager
• bin/taskmanager.sh启动 TaskManager

方式 A：把作业 JAR 放到 lib/（最省事）

cp./examples/streaming/TopSpeedWindowing.jar lib/ ./bin/standalone-job.sh start\--job-classname org.apache.flink.streaming.examples.windowing.TopSpeedWindowing# 再启动一个或多个 TaskManager./bin/taskmanager.sh start

Web UI 仍然默认：

• http://localhost:8081

方式 B：用 --jars 拉取（适合管理 artifacts）

./bin/standalone-job.sh start\-D user.artifacts.base-dir=/tmp/flink-artifacts\--jars local:///path/to/TopSpeedWindowing.jar

如果你发现 application 启不起来，大概率是你忘了先起 TaskManager。

停止（多实例时可反复 stop）

./bin/taskmanager.sh stop ./bin/standalone-job.sh stop

4.3 一句话决策

• 本地快速跑通、多人共享：Session Mode
• 想要更强隔离、每个应用单独生命周期：Application Mode

5. 从本地扩展到“分布式 Standalone”

Standalone 的分布式靠两个文件驱动：

• conf/masters：JobManager 主机
• conf/workers：TaskManager 主机列表

5.1 本地起多个 TaskManager（模拟集群）

conf/masters：

localhost

conf/workers：

localhost localhost

再启动：

./bin/start-cluster.sh

5.2 真分布式（多机器）

假设 4 台机器：master1 / worker1 / worker2 / worker3

conf/masters：

master1

conf/workers：

worker1 worker2 worker3

并且要在conf/flink-conf.yaml里指定：

jobmanager.rpc.address:master1

然后在 master1 上执行：

./bin/start-cluster.sh

前提条件：

• 机器之间网络互通
• 配好免密 SSH（脚本支持远程拉起）
• 各机器 Flink 目录结构一致（脚本默认依赖一致的路径）

6. Standalone 的排障入口：先看日志再说

Standalone 出问题，第一入口永远是日志：

• 日志目录：log/
• 每个组件都有独立日志：JM/TM/HistoryServer 等
• 默认每次启动会做日志轮转，旧日志会带数字后缀

另一个很方便的入口：

• Web UI 里也能直接看 JobManager / TaskManager 日志

6.1 什么时候要把日志级别开到 DEBUG？

当你遇到这些情况：

• 作业行为不符合预期（例如数据没进来、checkpoint 一直卡）
• 连接器初始化失败但提示不够
• 类加载冲突、NoClassDefFoundError

修改conf/log4j.properties：

• 把 rootLogger.level 调成 DEBUG（注意别长期在线上开，日志量会爆）

7. 动态参数覆盖：脚本 -D 的优先级更高

你可以在启动脚本里用-D直接覆盖配置项（优先级高于 flink-conf.yaml），非常适合临时改端口、改 rpc address：

./bin/jobmanager.sh start\-D jobmanager.rpc.address=localhost\-D rest.port=8081

同理适用于：

• standalone-job.sh
• taskmanager.sh
• historyserver.sh

实战建议：

• 本地端口冲突时，优先用-D rest.port=xxxx临时改，比改配置文件快很多

8. Standalone 开 HA：ZooKeeper + 多 JobManager

Standalone 要高可用（HA），就离不开 ZooKeeper，并且要启动多个 JobManager 做主备切换。

8.1 flink-conf.yaml 关键配置（示例）

high-availability.type:zookeeperhigh-availability.zookeeper.quorum:localhost:2181high-availability.zookeeper.path.root:/flinkhigh-availability.cluster-id:/cluster_onehigh-availability.storageDir:hdfs:///flink/recovery

这里最容易踩坑的是：

• high-availability.cluster-id：不同集群必须不一样，不然元数据会串
• high-availability.storageDir：需要可靠存储（通常 HDFS / 分布式 FS），别指望单机磁盘扛住故障恢复

8.2 masters 配置多 JM（并指定 Web UI 端口）

conf/masters：

localhost:8081 localhost:8082

你还可以通过high-availability.jobmanager.port固定/范围化 JM 通信端口，方便防火墙与运维管理。

8.3 启动 ZooKeeper Quorum + 启集群

./bin/start-zookeeper-quorum.sh ./bin/start-cluster.sh

停止：

./bin/stop-cluster.sh ./bin/stop-zookeeper-quorum.sh

9. Standalone 的 Classpath：为什么你“加了 jar 还是找不到类”？

Standalone 下，哪些 jar 会进用户 classpath，取决于模式：

• Session Mode：提交命令里指定的 JAR
• Application Mode：启动命令指定的 JAR +usrlib/目录下所有 JAR

这意味着一个非常实用的技巧：

• Application Mode 想让所有 TM/JM 都“天然带着某些依赖”，就把依赖丢到usrlib/
• Session Mode 下则更依赖你提交时的打包与 classpath 管理

遇到类加载冲突时（尤其多个 connector / 不同版本依赖）：

• 先明确你是在 Session 还是 Application
• 再检查 JAR 到底是通过提交命令带进去，还是放在 usrlib/lib
• 最后才去看“谁覆盖了谁”

10. Windows + Cygwin 常见坑：脚本报 $‘\r’ command not found

如果你在 Windows Git Shell/Cygwin 下跑脚本出现：

$'\r': command not found

本质原因是：git 把 UNIX 换行转换成了 Windows CRLF，Cygwin 解析不了。

修复思路（按文档做）：

• 在 Cygwin 的 home 目录.bash_profile追加：

  • export SHELLOPTS
  • set -o igncr

• 重开一个 bash shell

更省心的替代方案：

• 在 WSL2/Linux 环境运行 Flink（更推荐）

11. 你可以直接复用的“最短闭环”操作手册

本地验证（Session Mode）：

1. ./bin/start-cluster.sh
2. 打开 Web UIlocalhost:8081
3. ./bin/flink run ...
4. 出问题先看log/或 Web UI 日志
5. ./bin/stop-cluster.sh

本地验证（Application Mode）：

1. cp xxx.jar lib/或--jars local:///...
2. ./bin/standalone-job.sh start --job-classname ...
3. ./bin/taskmanager.sh start（可多起几个）
4. ./bin/taskmanager.sh stop/./bin/standalone-job.sh stop

分布式扩展：

• 配conf/masters+conf/workers
• 配jobmanager.rpc.address
• 确保免密 SSH 与目录一致

HA：

• 配 ZK + 多 masters + storageDir
• start-zookeeper-quorum.sh再start-cluster.sh