debezium/connect-base

Debezium Connect Base 镜像文档

镜像概述

本仓库已迁移至 quay.io/debezium/connect-base。

Kafka Connect 是用于在Kafka中移入和移出数据的系统。所有Debezium连接器均遵循Kafka Connector API的源连接器规范，每个连接器监控特定类型的数据库管理系统的变更数据，并将这些变更转发到按服务器、数据库和表组织的Kafka主题中。本镜像定义了一个可运行的Kafka Connect服务，预配置了所有Debezium连接器。该服务提供RESTful API用于管理连接器实例——只需启动容器，为每个要监控的数据源配置连接器，Debezium就会监控这些源的变更并将其转发到相应的Kafka主题。

什么是Debezium？

Debezium是一个分布式平台，可将现有数据库转换为事件流，使应用程序能够快速响应数据库中的每个行级变更。Debezium构建在Kafka之上，提供与Kafka Connect兼容的连接器，用于监控特定的数据库管理系统。Debezium将数据变更历史记录在Kafka日志中，因此应用程序可以随时停止和重启，并轻松消费其未运行期间错过的所有事件，确保所有事件都能被正确且完整地处理。

运行Debezium需要Zookeeper、Kafka以及运行Debezium连接器的服务。对于简单的评估和实验，所有服务都可以在单台主机上运行，如下文所述。然而，生产环境需要正确运行和联网多个服务实例，以提供性能、可靠性、复制和容错能力。这可以通过OpenShift等平台实现，该平台管理在多台主机和机器上运行的多个Docker容器。但在Docker容器中运行Kafka存在局限性，因此对于需要极高吞吐量的场景，应按照Kafka文档的说明在专用硬件上运行Kafka。

如何使用此镜像

本镜像作为其他希望使用自定义Kafka Connect连接器的镜像的基础镜像。它提供了完整的Kafka及其Kafka Connect库安装，以及docker-entrypoint.sh脚本，该脚本将运行Kafka Connect分布式服务，并动态设置Java类路径以包含$KAFKA_CONNECT_PLUGINS_DIR（即/kafka/connect）下子目录中的连接器JAR文件。

要添加连接器，您的镜像应基于此镜像（例如，使用FROM debezium/connect-base），并将一个或多个连接器的JAR文件添加到$KAFKA_CONNECT_PLUGINS_DIR下的一个或多个子目录中。

一般建议为每个连接器创建一个单独的子目录（例如"debezium-connector-mysql"），并将该连接器的JAR文件和其他资源文件放在该子目录中。

但是，当连接器共享依赖项时，应使用单个目录。这将防止共享依赖项中的类出现在类路径上的多个JAR中，从而避免出现难以理解的NoSuchMethodError异常。

启动Kafka Connect服务实例

注意：有关运行Kafka Connect的一般信息以及各种选项和环境变量的更多详细信息，请参阅Apache Kafka 文档。

Kafka Connect需要已运行的Zookeeper服务，该服务要么通过名为zookeeper的容器在本地运行，要么通过OpenShift作为名为zookeeper的服务运行。还需要已运行的Kafka代理，该代理要么通过名为kafka的容器在本地运行，要么通过OpenShift作为名为kafka的服务运行。

当运行一个或多个Kafka Connect服务实例的集群时，必须使用环境变量定义几个重要参数。请参见下文了解这些必需环境变量的列表和可接受的值。

使用此镜像启动Kafka Connect实例非常简单：

bash
$ docker run -it --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 -e ADVERTISED_HOST_NAME=$(echo $DOCKER_HOST | cut -f3  -d'/' | cut -f1 -d':') --link zookeeper:zookeeper --link kafka:kafka debezium/connect

此命令使用此镜像并启动一个名为connect的新容器，该容器在前台运行并附加控制台，以显示服务的输出和错误消息。它在8083端口上公开其REST API，该端口映射到本地主机上的相同端口号。它使用名为zookeeper的容器（或服务）中的Zookeeper和名为kafka的容器（或服务）中的Kafka代理。此命令设置了三个必需的环境变量，但您应将其值替换为适合您环境的更有意义的值。

要以分离模式启动容器，只需将-it选项替换为-d。服务输出不会发送到您的控制台，但可以随时使用docker logs命令读取。例如，以下命令将显示输出并持续跟踪输出：

bash
$ docker logs --follow --name connect

在运行的容器中启动shell

如果您已经在运行带有Kafka Connect服务的容器，可以使用此镜像连接到该容器并获取命令行shell：

bash
$ docker exec -it connect bash

其中connect是现有容器的名称。shell将设置所有环境变量，与在容器中启动服务时完全相同。因此，可以指定到其他容器的链接和其他环境变量，这些都将反映在shell的导出变量中。

环境变量

Debezium Kafka镜像在使用此镜像运行Kafka代理时使用多个环境变量。

GROUP_ID

运行Kafka Connect服务时需要此环境变量。将其设置为唯一标识服务及其工作节点所属的Kafka Connect集群的ID。

CONFIG_STORAGE_TOPIC

运行Kafka Connect服务时需要此环境变量。将其设置为Kafka Connect服务在组中存储连接器配置的Kafka主题名称。该主题必须有单个分区，应高度复制（例如3倍或更多），并应配置为压缩。

OFFSET_STORAGE_TOPIC

运行Kafka Connect服务时需要此环境变量。将其设置为Kafka Connect服务在组中存储连接器偏移量的Kafka主题名称。该主题应具有多个分区，高度复制（例如3倍或更多），并应配置为压缩。

STATUS_STORAGE_TOPIC

运行Kafka Connect服务时应提供此环境变量。将其设置为Kafka Connect服务在组中存储连接器状态的Kafka主题名称。该主题可以有多个分区，应高度复制（例如3倍或更多），并应配置为压缩。

BOOTSTRAP_SERVERS

此环境变量是高级设置，仅在Kafka未在可链接的容器或服务中运行时使用。将其设置为用于建立与Kafka集群的初始连接的主机/端口对列表。一旦与这些代理之一建立连接，服务将发现并使用Kafka集群中的所有Kafka代理，无论此处为引导指定了哪些服务器。列表的格式应为host1:port1,host2:port2,...。建议在此列表中包含多个代理，以防其中一个不可用。

REST_HOST_NAME

此环境变量是高级设置。将其设置为REST API将绑定的主机名。默认为容器的主机名。指定值0.0.0.0可将REST API绑定到所有可用接口。

ADVERTISED_HOST_NAME

此环境变量是高级设置。将其设置为将提供给其他工作节点连接的主机名。默认为容器的主机名。

KEY_CONVERTER

此环境变量是高级设置。将其设置为实现Kafka Connect的Converter类的Java类的完全限定名称，用于将连接器的键转换为存储在Kafka中的形式。默认为org.apache.kafka.connect.json.JsonConverter。

VALUE_CONVERTER

此环境变量是高级设置。将其设置为实现Kafka Connect的Converter类的Java类的完全限定名称，用于将连接器的值转换为存储在Kafka中的形式。默认为org.apache.kafka.connect.json.JsonConverter。

INTERNAL_KEY_CONVERTER

此环境变量是高级设置。将其设置为实现Kafka Connect的Converter类的Java类的完全限定名称，用于将连接器偏移量和配置键转换为存储在Kafka中的形式。默认为org.apache.kafka.connect.json.JsonConverter。

INTERNAL_VALUE_CONVERTER

此环境变量是高级设置。将其设置为实现Kafka Connect的Converter类的Java类的完全限定名称，用于将连接器偏移量和配置值转换为存储在Kafka中的形式。默认为org.apache.kafka.connect.json.JsonConverter。

OFFSET_FLUSH_INTERVAL_MS

此环境变量是高级设置。将其设置为服务定期尝试提交任务偏移量的时间间隔（以毫秒为单位）。默认值为60000（即60秒）。

OFFSET_FLUSH_TIMEOUT_MS

此环境变量是高级设置。将其设置为等待记录刷新和分区偏移量数据提交到偏移量存储的最大时间（以毫秒为单位），超时后将取消该过程并在未来尝试中恢复要提交的偏移量数据。默认值为5000（即5秒）。

SHUTDOWN_TIMEOUT

此环境变量是高级设置。将其设置为等待任务优雅关闭的时间（以毫秒为单位），同时连接器完成所有处理、记录任何最终数据并清理资源。这是总时间，不是每个任务的时间。所有任务都会触发关闭，然后按顺序等待它们。默认值为10000（即10秒）。

HEAP_OPTS

此环境变量是推荐的。使用此设置Kafka代理的JVM选项。默认值为-Xmx1G -Xms1G，意味着每个Kafka代理使用1GB内存。内存过少可能导致性能问题，过多可能导致代理无法在机器可用内存下正常启动。显然，容器必须能够使用此环境变量定义的内存量。

CONNECT_LOG4J_LOGGERS

此环境变量是可选的。使用此覆盖log4j.properties中用于log4j.rootLogger属性的日志记录器。可以提供带有CONNECT_LOG4J前缀的其他环境变量，如下面“其他”部分所述映射到log4j.properties文件中的属性。

LOG_LEVEL

此环境变量是可选的。使用此设置Kafka应用程序日志写入STDOUT和STDERR的详细级别。有效值为INFO（默认）、WARN、ERROR、DEBUG或TRACE。

ENABLE_APICURIO_CONVERTERS

此环境变量是可选的。通过将ENABLE_APICURIO_CONVERTERS=true设置为容器环境变量，可使用Apicurio Schema Registry启用Apicur.io转换器。有效值为false（禁用，默认）或true（启用Apicurio转换器）。

ENABLE_DEBEZIUM_SCRIPTING

此环境变量是可选的。通过将ENABLE_DEBEZIUM_SCRIPTING=true设置为容器环境变量，可启用使用脚本语言的Debezium功能，如消息过滤或基于内容的路由SMT。有效值为false（禁用，默认）或true（启用脚本）。注意：为防止执行任意脚本表达式，仅当您已适当保护对Kafka Connect配置界面的访问时，才应启用此选项。

ENABLE_JFR

此环境变量是可选的。设置后，将为此运行启动Flight Recorder记录会话。此功能对于在出现性能或功能问题时收集诊断信息非常有用。当变量转换为小写并将下划线替换为连字符时，可以通过JFR_RECORDING_前缀的环境变量配置Flight Recorder启动选项，例如JFR_RECORDING_PATH_TO_GC_ROOTS=true变为path-to-gc-roots=true。可以通过JFR_OPT_前缀的环境变量配置Flight Recorder控制选项。

其他

以CONNECT_开头的环境变量将用于更新Kafka Connect工作节点配置文件。每个环境变量名称将通过以下方式映射到配置属性名称：

1. 移除CONNECT_前缀；
2. 将所有字符转换为小写；
3. 将所有'_'字符转换为'.'字符

例如，环境变量CONNECT_HEARTBEAT_INTERVAL_MS转换为heartbeat.interval.ms属性。容器随后将更新Kafka Connect工作节点配置文件以包含该属性的名称和值。

环境变量的值不能包含'@'字符。

端口

使用此镜像创建的容器将公开8083端口，这是Kafka Connect服务绑定的标准端口。您可以使用标准Docker选项将其映射到运行容器的主机上的不同端口。

存储数据

此镜像运行的Kafka Connect服务不在容器中存储数据，但会生成日志。保留这些文件的唯一方法是使用卷将容器内的特定目录映射到本地文件系统（或OpenShift持久卷）。

日志文件

尽管此镜像会将Kafka Connect服务日志输出发送到标准输出，以便作为Docker日志可见，但此镜像还将Kafka Connect服务配置为将更多日志写入/kafka/logs的数据卷。所有日志每天轮换。

配置

此镜像在/kafka/config定义了一个数据卷，其中存储代理的配置文件。请注意，这些配置文件始终基于环境变量和链接的容器进行修改。此数据卷的最佳用途是能够查看Kafka使用的配置文件，尽管通过一些注意事项，也可以提供在启动时将被调整和使用的自定义配置文件。