📚 课程目录第2章环境搭建

2. 环境搭建：Flink集群部署、Hadoop依赖、Iceberg Catalog配置

说实话，环境搭建这块，往往是整个项目里最磨人的环节。我记得刚接触Iceberg那会儿，光Catalog配置就折腾了两天，最后发现是Hadoop依赖版本没对齐。这一章，我把那些坑都给你指出来。

咱们的目标很明确：搭一套能跑Iceberg实时写入的Flink集群，把Hadoop依赖配好，再把三种Catalog（Hive、Hadoop、REST）都讲透。你跟着我走一遍，基本就能避开我当年踩过的雷。

2.1 Flink集群部署：两种模式，按需选择

Flink的部署方式很多，但做Iceberg实时写入，我建议你重点关注两种：Standalone模式和YARN模式。前者适合开发和测试，后者适合生产。

2.1.1 Standalone模式（开发环境首选）

这种模式最简单。你只需要一台机器，或者一台虚拟机就行。

# 1. 下载Flink（我习惯用1.17版本，对Iceberg兼容性最好）
wget https://archive.apache.org/dist/flink/flink-1.17.2/flink-1.17.2-bin-scala_2.12.tgz
tar -xzf flink-1.17.2-bin-scala_2.12.tgz
cd flink-1.17.2

# 2. 修改配置文件 conf/flink-conf.yaml
# 重点参数：
jobmanager.rpc.address: localhost
jobmanager.memory.process.size: 2048m
taskmanager.memory.process.size: 4096m
taskmanager.numberOfTaskSlots: 4
parallelism.default: 2

# 3. 启动集群
./bin/start-cluster.sh

# 4. 检查是否启动成功
jps  # 应该看到 StandaloneSessionClusterEntrypoint 和 TaskManagerRunner

我的习惯：开发环境我一般把 taskmanager.numberOfTaskSlots 设成4，这样既能模拟并行度，又不会把笔记本跑死。生产环境再根据资源调整。

2.1.2 YARN模式（生产环境推荐）

生产环境里，Flink on YARN是主流。它能让Flink任务和Hadoop集群共享资源，管理起来也方便。

# 前提：Hadoop集群已部署，YARN已启动
# 设置环境变量
export HADOOP_HOME=/usr/local/hadoop
export HADOOP_CONF_DIR=$HADOOP_HOME/etc/hadoop

# 启动Flink YARN Session（申请资源）
./bin/yarn-session.sh -jm 2048m -tm 4096m -s 4 -d

# 或者直接提交任务到YARN（一次性模式）
./bin/flink run -m yarn-cluster \
  -yjm 2048m -ytm 4096m \
  -ys 4 \
  -p 4 \
  ./examples/streaming/WordCount.jar

我曾经踩过的坑：YARN模式下，Flink和Hadoop的版本必须兼容。比如Flink 1.17对应Hadoop 3.3.x。版本不匹配，任务提交时会报 ClassNotFoundException，排查起来很头疼。

2.2 Hadoop依赖：版本对齐是关键

Iceberg底层依赖Hadoop的文件系统（HDFS）和配置管理。所以Hadoop依赖必须配好。说白了，就是要把Hadoop的jar包放到Flink的classpath里。

2.2.1 下载并放置Hadoop依赖

# 1. 下载Hadoop客户端jar（以Hadoop 3.3.6为例）
wget https://repo1.maven.org/maven2/org/apache/hadoop/hadoop-client/3.3.6/hadoop-client-3.3.6.jar

# 2. 放到Flink的lib目录下
cp hadoop-client-3.3.6.jar flink-1.17.2/lib/

# 3. 还需要Hadoop的配置文件（core-site.xml, hdfs-site.xml）
# 把这些文件放到Flink的conf目录下
cp $HADOOP_HOME/etc/hadoop/core-site.xml flink-1.17.2/conf/
cp $HADOOP_HOME/etc/hadoop/hdfs-site.xml flink-1.17.2/conf/

核心要点：Flink读取Hadoop配置的顺序是：先找 conf/ 目录下的配置文件，再找环境变量 HADOOP_CONF_DIR 指向的目录。我建议你把配置文件直接放在Flink的conf目录下，这样最稳妥。

2.2.2 环境变量设置

# 在 ~/.bashrc 或 ~/.bash_profile 中添加
export HADOOP_HOME=/usr/local/hadoop
export HADOOP_CONF_DIR=$HADOOP_HOME/etc/hadoop
export FLINK_HOME=/usr/local/flink
export PATH=$PATH:$FLINK_HOME/bin

# 使配置生效
source ~/.bashrc

2.3 Iceberg Catalog配置：三种方式，各有千秋

Catalog是Iceberg的核心概念。它管理着表的元数据——表在哪儿、有哪些分区、数据文件在哪儿。Iceberg支持多种Catalog实现，我重点讲三种：Hive Catalog、Hadoop Catalog、REST Catalog。

你想想看，选哪种Catalog，其实取决于你的元数据存在哪儿。Hive Catalog存在Hive Metastore里，Hadoop Catalog存在文件系统里，REST Catalog存在远程服务里。

2.3.1 Hive Catalog（最常用）

这是生产环境最常用的方式。它把Iceberg表的元数据存在Hive Metastore里，这样Hive、Spark、Flink都能访问同一张表。

-- Flink SQL中配置Hive Catalog
CREATE CATALOG hive_catalog WITH (
  'type' = 'iceberg',
  'catalog-type' = 'hive',
  'uri' = 'thrift://localhost:9083',  -- Hive Metastore地址
  'clients' = '5',                     -- 连接池大小
  'warehouse' = 'hdfs://namenode:8020/user/iceberg/warehouse',
  'property-version' = '1'
);

USE CATALOG hive_catalog;

我的建议：如果你公司已经有Hive Metastore了，直接用Hive Catalog就行。它最大的好处是——表对Hive可见，你可以用Hive SQL查Iceberg表，做批处理分析。

2.3.2 Hadoop Catalog（轻量级）

Hadoop Catalog不需要Hive Metastore，它把元数据直接存在HDFS或本地文件系统里。适合测试环境，或者不想依赖Hive的场景。

-- Flink SQL中配置Hadoop Catalog
CREATE CATALOG hadoop_catalog WITH (
  'type' = 'iceberg',
  'catalog-type' = 'hadoop',
  'warehouse' = 'hdfs://namenode:8020/user/iceberg/warehouse',
  'property-version' = '1'
);

USE CATALOG hadoop_catalog;

注意：Hadoop Catalog不支持多引擎并发写同一张表。如果你有Flink和Spark同时写一张表的需求，别用Hadoop Catalog，否则会出现数据一致性问题。我吃过这个亏。

2.3.3 REST Catalog（云原生趋势）

REST Catalog是Iceberg社区力推的新方式。它通过REST API暴露元数据操作，解耦了底层存储。说白了，你只要部署一个REST Catalog服务，任何语言的客户端都能通过HTTP操作Iceberg表。

-- Flink SQL中配置REST Catalog
CREATE CATALOG rest_catalog WITH (
  'type' = 'iceberg',
  'catalog-type' = 'rest',
  'uri' = 'http://localhost:8181/iceberg/',  -- REST服务地址
  'warehouse' = 'hdfs://namenode:8020/user/iceberg/warehouse',
  'property-version' = '1'
);

USE CATALOG rest_catalog;

趋势判断：我个人觉得REST Catalog是未来方向。它让Iceberg的元数据操作标准化了，而且容易做权限控制。如果你在搭建新的数据平台，可以考虑直接上REST Catalog。

2.4 三种Catalog对比

为了方便你选型，我整理了一张对比表：

特性	Hive Catalog	Hadoop Catalog	REST Catalog
元数据存储	Hive Metastore	文件系统（HDFS/本地）	REST服务后端
多引擎支持	强（Hive/Spark/Flink）	弱（不支持并发写）	强（标准化API）
部署复杂度	中（需要Hive Metastore）	低（无需额外服务）	高（需要部署REST服务）
适用场景	生产环境，已有Hive	测试/开发环境	云原生，新平台
权限控制	依赖Hive权限	依赖文件系统权限	可自定义

2.5 整体架构图

下面这张图展示了Flink + Iceberg的完整环境架构。你可以看到数据从Flink写入Iceberg表，元数据通过Catalog管理，底层数据存在HDFS上。

2.6 验证环境：跑一个简单的Iceberg写入任务

环境搭好了，咱们验证一下。写个最简单的Flink SQL任务，往Iceberg表里写几条数据。

-- 1. 创建Catalog（以Hadoop Catalog为例）
CREATE CATALOG my_catalog WITH (
  'type' = 'iceberg',
  'catalog-type' = 'hadoop',
  'warehouse' = 'hdfs://localhost:9000/user/iceberg/warehouse'
);

USE CATALOG my_catalog;

-- 2. 创建数据库和表
CREATE DATABASE IF NOT EXISTS test_db;
USE test_db;

CREATE TABLE IF NOT EXISTS sample_table (
  id INT,
  name STRING,
  ts TIMESTAMP(3)
) WITH (
  'format-version' = '2',
  'write.format.default' = 'parquet'
);

-- 3. 写入数据
INSERT INTO sample_table VALUES
  (1, 'Alice', TIMESTAMP '2024-01-01 10:00:00'),
  (2, 'Bob', TIMESTAMP '2024-01-01 10:05:00'),
  (3, 'Charlie', TIMESTAMP '2024-01-01 10:10:00');

-- 4. 查询验证
SELECT * FROM sample_table;

如果查询能返回三条记录，恭喜你，环境搭建成功了！

一个小技巧：验证环境时，我习惯先用Hadoop Catalog，因为它最简单，不需要额外服务。等确认Flink和Iceberg能正常工作了，再切换到Hive Catalog或REST Catalog。这样排查问题更方便。

2.7 常见问题与避坑指南

ClassNotFoundException：通常是Hadoop依赖没放对位置。检查 flink/lib/ 目录下有没有hadoop-client的jar包。
连接Hive Metastore超时：检查 hive.metastore.uris 配置是否正确，以及Metastore服务是否启动。
权限不足：HDFS写入权限问题。检查 hdfs dfs -chmod 或Kerberos认证。
版本不兼容：Flink、Iceberg、Hadoop三者的版本必须匹配。我建议用Flink 1.17 + Iceberg 1.4 + Hadoop 3.3。