Kafka 系列 —（11）Kafka Connect 深入指南

包含三大部分：

如何运行 Connect（standalone / distributed、启动示例、常见参数）

两个示例连接器实例配置与创建命令

文件数据源 + 文件数据池（FileStreamSource / FileStreamSink）

MySQL → Elasticsearch（Debezium / JDBC Source + ES Sink）

深入理解 Connect 的内部概念、健壮性、运维与调优要点（offsets、tasks、SMT、错误处理、安全、监控等）

1.运行 Kafka Connect

Kafka Connect 有两种运行模式：

Standalone mode（单机/开发）：适合单实例、简单任务、开发/测试。配置和偏移存储在本地文件或内存，单点。
Distributed mode（分布式/生产）：适合生产、高可用。多个 Connect worker 组成一个集群，通过 Kafka 内部主题存储配置、offset、状态，实现容错与伸缩。

1.1 准备条件（通用）

已有 Kafka 集群（至少 3 个 broker 推荐）
（可选）Confluent Schema Registry（使用 Avro 时）
Connect 插件（connector jars）放到 plugin.path
设置 JVM 堆、GC、日志

1.2 启动 Standalone（示例）

假设 Kafka 安装目录 $KAFKA_HOME。

编辑 config/connect-standalone.properties（基础示例）：

bootstrap.servers=broker1:9092,broker2:9092
key.converter=org.apache.kafka.connect.json.JsonConverter
value.converter=org.apache.kafka.connect.json.JsonConverter
key.converter.schemas.enable=false
value.converter.schemas.enable=false

offset.storage.file.filename=/tmp/connect-offsets.properties
offset.flush.interval.ms=10000

# plugin path where connector jars are placed
plugin.path=/opt/kafka-connect/plugins

启动命令：

$KAFKA_HOME/bin/connect-standalone.sh config/connect-standalone.properties config/my-connector.properties

Standalone 模式下你把 connector 的配置文件作为命令行参数传入（一次性启动一个 worker + 指定要运行的 connector）。

1.3 启动 Distributed（示例）

编辑 config/connect-distributed.properties：

bootstrap.servers=broker1:9092,broker2:9092
key.converter=io.confluent.connect.avro.AvroConverter
value.converter=io.confluent.connect.avro.AvroConverter
key.converter.schema.registry.url=http://schema-registry:8081
value.converter.schema.registry.url=http://schema-registry:8081

# Internal topics - required; must create with replication >= 3 in prod
config.storage.topic=connect-configs
offset.storage.topic=connect-offsets
status.storage.topic=connect-status
offset.flush.interval.ms=10000

plugin.path=/opt/kafka-connect/plugins

# worker group id
group.id=connect-cluster
rest.advertised.host.name=connect-01.example.com
rest.port=8083

启动多个 worker（在不同主机/容器上）：

$KAFKA_HOME/bin/connect-distributed.sh config/connect-distributed.properties

当多个 worker 启动并指向相同的 Kafka brokers 与相同的 config.storage.topic/offset.storage.topic 时，它们会自动形成集群并分配 task。

1.4 必备的内部主题（生产环境注意）

在分布式模式下，必须确保下列内部主题存在并有适当的分区和 replication：

connect-configs（config.storage.topic）
connect-offsets（offset.storage.topic）
connect-status（status.storage.topic）

推荐在生产环境使用 replication.factor = 3 且 partitions = 3（或按负载定）。你可以预建这些 topic 并设置合适的 retention.ms。

2.连接器实例：示例与命令

下面给出两组可直接运行的示例：File 源/汇（适合测试），以及 MySQL → Elasticsearch（生产级典型管道）。

2.1 示例 A — 文件数据源（FileStreamSource）与文件数据池（FileStreamSink）

适用：开发演示、日志管道入 Kafka、或将 Kafka 写回文件（如调试）。

2.1.1 FileStreamSourceConnector（示例配置 JSON）

这是 Kafka 自带的示例 connector（文件 → topic）。

file-source.json：

{
  "name": "local-file-source",
  "config": {
    "connector.class": "org.apache.kafka.connect.file.FileStreamSourceConnector",
    "tasks.max": "1",
    "file": "/var/log/myapp/app.log",
    "topic": "app-logs",
    "key.converter": "org.apache.kafka.connect.storage.StringConverter",
    "value.converter": "org.apache.kafka.connect.storage.StringConverter"
  }
}

创建（Distributed 模式，假设 Connect REST 在 http://connect-host:8083）：

curl -X POST -H "Content-Type: application/json" --data '@file-source.json' http://connect-host:8083/connectors

2.1.2 FileStreamSinkConnector（写到本地文件）

file-sink.json：

{
  "name": "local-file-sink",
  "config": {
    "connector.class": "org.apache.kafka.connect.file.FileStreamSinkConnector",
    "tasks.max": "1",
    "topics": "app-logs",
    "file": "/tmp/out-app.log",
    "key.converter": "org.apache.kafka.connect.storage.StringConverter",
    "value.converter": "org.apache.kafka.connect.storage.StringConverter"
  }
}

创建方式同上。

2.1.3 注意点（File connectors）

FileStream 连接器是单任务、单文件的；生产环境不适合做高吞吐写入。主要用于演示/调试。
tasks.max 控制并行度；文件源通常限制为 1（文件并行读取复杂）。
如果文件在多个主机上，考虑使用 Filebeat/Fluentd 将日志发送到 Kafka （更适合生产）。

2.2 示例 B — MySQL → Elasticsearch（推荐方案：Debezium MySQL Source + Elasticsearch Sink）

有两种主流做法：

Debezium MySQL Source Connector（CDC） + Elasticsearch Sink Connector

优点：实时捕获数据库行级变更（insert/update/delete）

JDBC Source Connector（全表/增量） + Elasticsearch Sink

适用于无法使用 binlog 的场景或批量同步

下面以 Debezium + ES Sink 为例（更为常见、实时）。

2.2.1 Debezium MySQL Source（示例）

mysql-debezium-source.json（示例）：

{
  "name": "mysql-debezium-source",
  "config": {
    "connector.class": "io.debezium.connector.mysql.MySqlConnector",
    "tasks.max": "1",
    "database.hostname"