快速开始（Quick start）

使用 Docker 运行 Debezium 的注意事项

本教程使用 Docker 和 Debezium 容器映像来运行 ZooKeeper、Kafka、Debezium 和 MySQL 服务。在单独的容器中运行每个服务简化了设置，因此您可以看到 Debezium 的实际运行情况。

在生产环境中，您将运行每个服务的多个实例，以提供性能、可靠性、复制和容错能力。通常，您要么将这些服务部署在 OpenShift 或 Kubernetes 等平台上，该平台管理运行在多个主机和机器上的多个 Docker 容器，要么将其安装在专用硬件上。

您应该了解使用 Docker 运行 Debezium 的以下注意事项：

  • ZooKeeper 和 Kafka 通常会将其数据本地存储在容器中，这需要您将目录作为卷挂载到主机上。这样，当容器停止时，持久化数据将保留。然而，本教程将跳过这个设置 —— 当容器停止时，所有持久化数据都会丢失。这样，当您完成教程后，清理就会变得简单。
  • 本教程要求您在不同的容器中运行每个服务。
  • 为了避免混淆，您将在单独的终端中运行前景中的每个容器。这样，容器的所有输出都将显示在用于运行它的终端中。

启动 Zookeeper

ZooKeeper 是你必须启动的第一个服务。

1、打开一个终端，并使用它在容器中启动 ZooKeeper

docker run -it --rm --name zookeeper -p 2181:2181 -p 2888:2888 -p 3888:3888 quay.io/debezium/zookeeper:3.2
- -it：容器是交互式的，这意味着终端的标准输入和输出都连接到容器上。
- --rm：当停止时，容器将被移除。
- --name zookeeper：容器的名称。
- -p 2181:2181 -p 2888:2888 -p 3888:3888：将容器的三个端口映射到 Docker 主机上的相同端口。这使得其他容器 (以及容器外的应用程序) 能够与 ZooKeeper 进行通信。

如果你使用的是 Podman, 请运行以下命令：

$ podman pod create --name=dbz -p 8083:8083
$ podman run -it --rm --name zookeeper --pod dbz quay.io/debezium/zookeeper:3.2

2、确认 ZooKeeper 已启动并正在 2181 端口上监听

您应该会看到类似以下的输出：

Starting up in standalone mode
ZooKeeper JMX enabled by default
Using config: /zookeeper/conf/zoo.cfg
2017-09-21 07:15:55,417 - INFO  [main:QuorumPeerConfig@134] - Reading configuration from: /zookeeper/conf/zoo.cfg
2017-09-21 07:15:55,419 - INFO  [main:DatadirCleanupManager@78] - autopurge.snapRetainCount set to 3
2017-09-21 07:15:55,419 - INFO  [main:DatadirCleanupManager@79] - autopurge.purgeInterval set to 1
...
port 0.0.0.0/0.0.0.0:2181

启动 Kafka

启动 ZooKeeper 后，您可以在新的容器中启动 Kafka。

Debezium 3.2.0.final 已经在多个 Kafka Connect 版本上进行了测试。请参考 Debezium 测试矩阵，以确定 Debezium 和 Kafka Connect 之间的兼容性。

1、打开一个新的终端，并使用它在容器中启动 Kafka

这个命令使用 quay.io/debezium/kafka 镜像的 3.2 版本运行一个新的容器：

$ docker run -it --rm --name kafka -p 9092:9092 --link zookeeper:zookeeper quay.io/debezium/kafka:3.2
  • -it：容器是交互式的，这意味着终端的标准输入和输出都连接到容器上。
  • –rm：当停止时，容器将被移除。
  • –name kafka：容器的名称。
  • -p 9092:9092：将容器中的端口 9092 映射到 Docker 主机上的相同端口，以便容器外的应用程序可以与 Kafka 通信。
  • –link zookeeper:zookeeper：告诉容器它可以在同一 Docker 主机上运行的 zookeeper 容器中找到 ZooKeeper。

如果使用 Podman, 请运行以下命令：

$ podman run -it --rm --name kafka --pod dbz -e HOST_NAME=127.0.0.1 quay.io/debezium/kafka:3.2

2、确认 Kafka 已启动

您应该会看到类似以下的输出：

2017-09-21 07:16:59,085 - INFO  [main-EventThread:ZkClient@713] - zookeeper state changed (SyncConnected)
2017-09-21 07:16:59,218 - INFO  [main:Logging$class@70] - Cluster ID = LPtcBFxzRvOzDSXhc6AamA
2017-09-21 07:16:59,649 - INFO  [main:Logging$class@70] - [Kafka Server 1], started

启动 MySQL 数据库

此时，你已经启动了 ZooKeeper 和 Kafka, 但仍然需要一个 Debezium 可以捕获变更的数据库服务器。在这个过程中，你将使用示例数据库启动 MySQL 服务器。

1、打开一个新的终端，并用它启动一个新的容器，该容器运行一个预配置了库存数据库的 MySQL 数据库服务器。

该命令使用 quay.io/debezium/example-mysql 镜像的 3.2 版本运行一个新容器，该映像基于 mysql:8.2 镜像。它还定义并填充了一个示例库存数据库：

$ docker run -it --rm --name mysql -p 3306:3306 -e MYSQL_ROOT_PASSWORD=debezium -e MYSQL_USER=mysqluser -e MYSQL_PASSWORD=mysqlpw quay.io/debezium/example-mysql:3.2
  • -it
    容器是交互式的，这意味着终端的标准输入和输出都连接到容器上。
  • –rm
    当停止时，容器将被移除。
  • –name mysql
    容器的名称。
  • -p 3306:3306
    将容器中的端口 3306 (默认 MySQL 端口) 映射到 Docker 主机上的相同端口，以便容器外的应用程序可以连接到数据库服务器。
  • -e MYSQL_ROOT_PASSWORD=debezium -e MYSQL_USER=mysqluser -e MYSQL_PASSWORD=mysqlpw
    创建具有 Debezium MySQL 连接器所需最低权限的用户和密码。

如果使用 Podman, 请运行以下命令：
$ podman run -it –rm –name mysql –pod dbz -e MYSQL_ROOT_PASSWORD=debezium -e MYSQL_USER=mysqluser -e MYSQL_PASSWORD=mysqlpw quay.io/debezium/example-mysql:3.2

2、验证 MySQL 服务器是否启动

随着配置的修改，MySQL 服务器会启动和停止几次。你应该会看到类似以下的输出：

...
[System] [MY-010931] [Server] /usr/sbin/mysqld: ready for connections. Version: '8.0.27'  socket: '/var/run/mysqld/mysqld.sock'  port: 3306  MySQL Community Server - GPL.
[System] [MY-011323] [Server] X Plugin ready for connections. Bind-address: '::' port: 33060, socket: /var/run/mysqld/mysqlx.sock

启动 MySQL 命令行客户端

启动 MySQL 后，启动 MySQL 命令行客户端，以访问样本库存数据库。

1、打开一个新的终端，并使用它在容器中启动 MySQL 命令行客户端。

这个命令使用 mysql:8.2 镜像运行一个新的容器，并定义一个 shell 命令以使用正确的选项运行 MySQL 命令行客户端：

$ docker run -it --rm --name mysqlterm --link mysql mysql:8.2 sh -c 'exec mysql -h"$MYSQL_PORT_3306_TCP_ADDR" -P"$MYSQL_PORT_3306_TCP_PORT" -uroot -p"$MYSQL_ENV_MYSQL_ROOT_PASSWORD"'
  • -it
    容器是交互式的，这意味着终端的标准输入和输出都连接到容器上。
  • –rm
    当停止时，容器将被移除。
  • –name mysqlterm
    容器的名称。
  • –link mysql
    将容器链接到 mysql 容器。

如果使用 Podman, 请运行以下命令：
$ podman run -it –rm –name mysqlterm –pod dbz mysql:8.2 sh -c ‘exec mysql -h 0.0.0.0 -uroot -pdebezium’

1、确认 MySQL 命令行客户端已启动。

您应该会看到类似以下的输出：

mysql: [Warning] Using a password on the command line interface can be insecure.
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 9
Server version: 8.0.27 MySQL Community Server - GPL

Copyright (c) 2000, 2021, Oracle and/or its affiliates.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql>

2、在 mysql > 命令提示符下，切换到库存数据库：

mysql> use inventory;

3、列出数据库中的表：

mysql> show tables;
+---------------------+
| Tables_in_inventory |
+---------------------+
| addresses           |
| customers           |
| geom                |
| orders              |
| products            |
| products_on_hand    |
+---------------------+
6 rows in set (0.00 sec)

4、使用 MySQL 命令行客户端探索数据库并查看数据库中预加载的数据。

例如：

mysql> SELECT * FROM customers;
+------+------------+-----------+-----------------------+
| id   | first_name | last_name | email                 |
+------+------------+-----------+-----------------------+
| 1001 | Sally      | Thomas    | sally.thomas@acme.com |
| 1002 | George     | Bailey    | gbailey@foobar.com    |
| 1003 | Edward     | Walker    | ed@walker.com         |
| 1004 | Anne       | Kretchmar | annek@noanswer.org    |
+------+------------+-----------+-----------------------+
4 rows in set (0.00 sec)

启动 Kafka Connect

启动 MySQL 并通过 MySQL 命令行客户端连接到库存数据库后，您启动 Kafka Connect 服务。该服务暴露了一个 REST API，用于管理 Debezium MySQL 连接器。

1、打开一个新的终端，使用它在容器中启动 Kafka Connect 服务。

该命令使用 quay.io/debezium/connect 镜像的 3.2 版本运行一个新容器：

$ docker run -it --rm --name connect -p 8083:8083 -e GROUP_ID=1 -e CONFIG_STORAGE_TOPIC=my_connect_configs -e OFFSET_STORAGE_TOPIC=my_connect_offsets -e STATUS_STORAGE_TOPIC=my_connect_statuses --link kafka:kafka --link mysql:mysql quay.io/debezium/connect:3.2
  • -it
    该容器具有交互性，这意味着终端的标准输入和输出均连接到该容器。
  • –rm
    容器停止时将被移除。
  • –name connect
    容器的名称。
  • -p 8083:8083
    将容器内的 8083 端口映射到 Docker 主机上的相同端口。这使得容器外部的应用程序能够利用 Kafka Connect 的 REST API 来设置和管理新的容器实例。
  • -e CONFIG_STORAGE_TOPIC=my_connect_configs -e OFFSET_STORAGE_TOPIC=my_connect_offsets -e STATUS_STORAGE_TOPIC=my_connect_statuses
    设置 Debezium 镜像所需的环境变量。
  • –link kafka:kafka –link mysql:mysql
    Links the container to the containers that are running Kafka and the MySQL server.
    将容器链接到运行 Kafka 和 MySQL 服务器的容器。

若使用 Podman，请执行以下命令：
podman run -it –rm –name connect –pod dbz -e GROUP_ID=1 -e CONFIG_STORAGE_TOPIC=my_connect_configs -e OFFSET_STORAGE_TOPIC=my_connect_offsets -e STATUS_STORAGE_TOPIC=my_connect_statuses quay.io/debezium/connect:3.2

如果提供了‘——hostname‘命令行选项，Kafka Connect REST API 将不会在本地主机接口上监听。这可能会在 REST 端口暴露时引发问题。
若此问题存在，请设置环境变量 REST_HOST_NAME=0.0.0.0，这将确保 REST API 可从所有接口访问。

1、确认 Kafka Connect 已启动并准备好接受连接。

您应该会看到类似于以下的输出：

...
2020-02-06 15:48:33,939 INFO   ||  Kafka version: 3.0.0   [org.apache.kafka.common.utils.AppInfoParser]
...
2020-02-06 15:48:34,485 INFO   ||  [Worker clientId=connect-1, groupId=1] Starting connectors and tasks using config offset -1   [org.apache.kafka.connect.runtime.distributed.DistributedHerder]
2020-02-06 15:48:34,485 INFO   ||  [Worker clientId=connect-1, groupId=1] Finished starting connectors and tasks   [org.apache.kafka.connect.runtime.distributed.DistributedHerder]

2、使用 Kafka Connect REST API 来检查 Kafka Connect 服务的状态。

Kafka Connect 提供了一个 REST API 来管理 Debezium 连接器。要与 Kafka Connect 服务进行通信，您可以使用 curl 命令向 Docker 主机的 8083 端口发送 API 请求（该端口在启动 Kafka Connect 时已映射到 connect 容器的 8083 端口）。

  • a、打开一个新终端并检查 Kafka Connect 服务的状态：
    $ curl -H "Accept:application/json" localhost:8083/
{"version":"4.0.0","commit":"cb8625948210849f"}
  • b、检查已注册到 Kafka Connect 的连接器列表：
    $ curl -H "Accept:application/json" localhost:8083/connectors/
[]

部署 MySQL 连接器

在启动 Debezium 和 MySQL 服务后，您已准备就绪，可以部署 Debezium MySQL 连接器，使其开始监控示例 MySQL 数据库（inventory）。

此时，您正在运行 Debezium 服务、一个包含示例库存数据库的 MySQL 数据库服务器，以及连接到该数据库的 MySQL 命令行客户端。要部署 MySQL 连接器，您必须：

  • 连接器注册后，将开始监控数据库服务器的二进制日志，并为每行发生变更的数据生成变更事件。
  • 审查 Kafka Connect 启动时的日志输出有助于您更好地理解它在开始监控 binlog 之前必须完成的每一项任务。
注册一个连接器以监控库存数据库

通过注册 Debezium MySQL 连接器，该连接器将开始监控 MySQL 数据库服务器的二进制日志（binlog）。binlog 记录了数据库的所有事务（例如对单行数据的更改以及对模式的更改）。当数据库中的某一行发生变更时，Debezium 会生成一个变更事件。

在生产环境中，您通常会使用 Kafka 工具手动创建所需的主题，包括指定副本数量， 或者您会利用 Kafka Connect 机制来自定义 自动创建 主题的设置。 然而，在本教程中，Kafka 被配置为仅使用一个副本来自动创建主题。

步骤：

1、检查您将要注册的 Debezium MySQL 连接器的配置。

在注册连接器之前，您应熟悉其配置。下一步，您将注册以下连接器：

{
  "name": "inventory-connector",  
  "config": {  
    "connector.class": "io.debezium.connector.mysql.MySqlConnector",
    "tasks.max": "1",  
    "database.hostname": "mysql",  
    "database.port": "3306",
    "database.user": "debezium",
    "database.password": "dbz",
    "database.server.id": "184054",  
    "topic.prefix": "dbserver1",  
    "database.include.list": "inventory",  
    "schema.history.internal.kafka.bootstrap.servers": "kafka:9092",  
    "schema.history.internal.kafka.topic": "schema-changes.inventory"  
  }
}
  • 1、连接器的名称。
  • 2、连接器的配置。
  • 3、在任何时刻，只应有一个任务处于运行状态。由于 MySQL 连接器读取的是 MySQL 服务器的二进制日志，采用单一连接器任务能确保事件处理的顺序性和正确性。Kafka Connect 服务利用连接器启动一个或多个执行实际工作的任务，并自动将这些运行中的任务分布到 Kafka Connect 服务集群中。若有服务停止或崩溃，这些任务将被重新分配给仍在运行的服务。
  • 4、数据库主机，即运行 MySQL 服务器的 Docker 容器名称（mysql）。Docker 会在容器内部操控网络栈，使得每个通过链接的容器都能利用容器名称作为主机名，通过‘/etc/hosts‘进行解析。若 MySQL 运行于常规网络环境下，此处则应指定其 IP 地址或可解析的主机名作为该值。
  • 5、一个独特的主题前缀。此名称将用作所有 Kafka 主题的前缀。
  • 6、仅库存数据库中的更改会被检测到。
  • 7、连接器将使用此代理（您发送事件的同一代理）和主题名称，在 Kafka 中存储数据库模式的历史记录。重新启动时，连接器将恢复在 binlog 中指定开始读取时间点的数据库模式。
作者：Jeebiz  创建时间：2025-08-12 15:41
最后编辑：Jeebiz  更新时间：2025-08-12 17:10