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

1. 前置条件

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

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

2. 获取并进入 CdcUp

bash 复制代码

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

你会看到用法帮助：

复制代码

Usage: ./cdcup.sh { init | up | pipeline <yaml> | 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 交互式初始化

bash 复制代码

./cdcup.sh init

按提示用方向键选择：

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

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

3.2 启动容器

bash 复制代码

./cdcup.sh up

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

4. 在 MySQL 造数（示例）

如果选了 MySQL 作为 Source：

bash 复制代码

./cdcup.sh mysql

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

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）

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

yaml 复制代码

# 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

提交：

bash 复制代码

./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）开放。

yaml 复制代码

# 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

提交：

bash 复制代码

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

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

6. 打开 Flink Web UI

bash 复制代码

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

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

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

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

sql 复制代码

-- 新增
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. 分表并表与路由（可选）

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

yaml 复制代码

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

按表改名/跨库迁移：

yaml 复制代码

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

9. 停止与清理

bash 复制代码

./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 模型。