用 CdcUp CLI 一键搭好 Flink CDC 演练环境 - 教程

1. 前置条件

• 一台 Linux 或 macOS 电脑
• Docker 与 Docker Compose v2（可用 docker compose version 验证）
• bash 终端环境

Windows 建议用 WSL2 + Docker Desktop（启用 Compose v2 插件）。

2. 获取并进入 CdcUp

git clone https://github.com/apache/flink-cdc.git --depth=1
cd flink-cdc/tools/cdcup/
./cdcup.sh

你会看到用法帮助：

Usage: ./cdcup.sh { init | up | pipeline  | flink | mysql | stop | down | help }

• init：生成演练环境配置并选择 Flink/CDC 版本与 Source/Sink 连接器
• up：拉起并启动所有容器
• pipeline <yaml>：提交 YAML 定义的 Flink CDC 作业
• flink：打印 Flink Web UI 地址
• mysql：打开 MySQL 控制台（若选择了 MySQL 源）
• stop：停止容器（保留数据卷）
• down：停止并删除容器、网络与卷（清库）

3. 初始化与启动

3.1 交互式初始化

./cdcup.sh init

按提示用方向键选择：

• Flink 版本（推荐 1.20.1）
• Flink CDC 版本
• Source/Sink 连接器（如 MySQL、StarRocks、Doris、Elastic、Print 等）

CdcUp 会生成对应的 Compose 文件与样例配置。

3.2 启动容器

./cdcup.sh up

提示：StarRocks/Doris 等目标库初始化较慢，第一次启动需稍等；可 docker compose logs -f 观察健康状态。

4. 在 MySQL 造数（示例）

如果选了 MySQL 作为 Source：

./cdcup.sh mysql

执行示例 SQL（建库/建表/插数/校验）：

CREATE DATABASE cdc_playground;
USE cdc_playground;
CREATE TABLE test_table (id INT PRIMARY KEY, name VARCHAR(32));
INSERT INTO test_table VALUES
(1,'alice'),(2,'bob'),(3,'cicada'),(4,'derrida');
SELECT * FROM test_table;

5. 编写与提交管道

你可以用任意 YAML。下面给两份常用模板：

5.1 最小可跑（MySQL → Print Sink）

适合首次验证：无需下游依赖，控制台直接可见同步结果。

# mysql-to-print.yaml
source:
type: mysql
hostname: mysql
port: 3306
username: root
password: 123456
tables: cdc_playground\.*
server-id: 5400-5404
server-time-zone: UTC
sink:
type: print
pipeline:
name: MySQL to Print
parallelism: 2

提交：

./cdcup.sh pipeline mysql-to-print.yaml

此时对 cdc_playground 下任意表做 INSERT/UPDATE/DELETE，在 Flink 日志中能看到事件被打印出来。

5.2 切换到 StarRocks（MySQL → StarRocks）

需在 init 时选择了 StarRocks 连接器，并确保 FE MySQL 端口（默认 9030）与 FE HTTP/Load 端口（常见 8030 或 8080）开放。

# mysql-to-starrocks.yaml
source:
type: mysql
hostname: mysql
port: 3306
username: root
password: 123456
tables: cdc_playground\..*
server-id: 5400-5404
server-time-zone: UTC
sink:
type: starrocks
jdbc-url: jdbc:mysql://starrocks:9030
load-url: starrocks:8030       # 若镜像是 8080 暴露 FE HTTP，请改 8080
username: root
password: ""
table.create.properties.replication_num: 1
# 如需 Upsert 语义，可启用主键模型（取决于实际版本能力）：
# table.create.properties.duplicate_key: false
# table.create.properties.primary_key: "id"
pipeline:
name: MySQL to StarRocks
parallelism: 2

提交：

./cdcup.sh pipeline mysql-to-starrocks.yaml

验证：用 DBeaver/DataGrip 或 mysql -h starrocks -P9030 -uroot 连上 StarRocks，查询对应库表是否已创建并有数据。

6. 打开 Flink Web UI

./cdcup.sh flink
# 输出类似：
#  Visit Flink Dashboard at: http://localhost:33448

浏览器访问该地址即可查看拓扑、吞吐、延时、反压与 Checkpoint 状态。

7. 在线验证：增删改与 Schema 演进

在 ./cdcup.sh mysql 打开的会话里执行：

-- 新增
INSERT INTO cdc_playground.test_table VALUES (5, 'eve');
-- 演进：加列
ALTER TABLE cdc_playground.test_table ADD COLUMN note VARCHAR(64) NULL;
-- 更新
UPDATE cdc_playground.test_table SET note='hello' WHERE id=1;
-- 删除
DELETE FROM cdc_playground.test_table WHERE id=2;

• Print Sink：变化会实时打印到 Flink 日志
• StarRocks/Doris：刷新客户端即可看到目标表同步更新

8. 分表并表与路由（可选）

把多张分表写入同一目标表（注意当前不支持不同分表里存在相同主键的并表场景）：

route:
- source-table: cdc_playground.order_.*
sink-table: ods_db.ods_orders

按表改名/跨库迁移：

route:
- source-table: cdc_playground.test_table
sink-table: ods_db.ods_test_table

9. 停止与清理

./cdcup.sh stop   # 停止所有容器，保留数据卷
./cdcup.sh down   # 停止并删除容器/网络/卷（清空数据）

10. 常见坑与排障清单

• Compose 版本：CdcUp 依赖 Docker Compose v2（命令是 docker compose 而非 docker-compose）。
• 端口差异：StarRocks FE HTTP 端口常见为 8030，部分 all-in-one 镜像是 8080；load-url 与浏览器访问请一致。
• Server ID 冲突：server-id: 5400-5404 与现有复制/采集冲突会报错，换个区间即可。
• 时区偏移：务必设 server-time-zone: UTC（或与你源库一致的时区），避免 TIMESTAMP/DATETIME 偏移。
• 初始化等待：首次 up 后下游（StarRocks/Doris）可能需要几分钟 ready；观察 docker compose logs -f。
• Down 会清库：down 会删除卷，演练数据会丢；用 stop 可保留数据。
• Exactly-Once：开箱即用依赖 Flink Checkpoint，建议在生产演练里合理调节间隔/超时，并优先使用主键/唯一键支持的 upsert 模型。