消息队列 / 系统课时
部署 Source Connector
部署 Source Connector
这一课完成一个可验证的 Source Connector 部署:先确认插件可用,再通过 Kafka Connect REST API 创建连接器,让外部数据进入 Kafka,并用 Task 状态、source offset 与错误日志判断采集链路是否真的健康。
学习目标
- 通过 REST API 创建 Source Connector 配置并验证数据落点
- 检查 Connector、Task 状态与 source offset
- 通过失败
trace和 Worker 错误日志定位异常记录
部署前先确认 Worker 与插件
Source Connector 运行在 Kafka Connect Worker 中。创建配置前先确认 REST 接口可访问,并检查目标插件已经安装;否则配置本身再正确,也会在创建阶段因找不到 Connector 类而失败。
curl -s http://localhost:8083/
curl -s http://localhost:8083/connector-plugins预期输出
{"version":"<VALUE>","commit":"<VALUE>","kafka_cluster_id":"<ID>"}
[{"class":"org.apache.kafka.connect.file.FileStreamSourceConnector","type":"source","version":"<VALUE>"}]版本、提交号和插件列表会随环境变化。下面使用 FileStream Source 做最小闭环实验;生产环境应替换为实际数据源插件。
创建 Source Connector
先准备一个输入文件,再提交连接器配置。tasks.max 表示允许的最大 Task 数;单文件源通常只能由一个 Task 读取,因此这里设为 1。示例同时开启错误日志,便于记录可容忍的处理异常。
printf 'order-1001\norder-1002\n' > /tmp/source-orders.txt
curl -s -X POST http://localhost:8083/connectors \
-H 'Content-Type: application/json' \
-d '{
"name": "orders-file-source",
"config": {
"connector.class": "org.apache.kafka.connect.file.FileStreamSourceConnector",
"tasks.max": "1",
"file": "/tmp/source-orders.txt",
"topic": "orders.raw",
"key.converter": "org.apache.kafka.connect.storage.StringConverter",
"value.converter": "org.apache.kafka.connect.storage.StringConverter",
"errors.tolerance": "all",
"errors.log.enable": "true",
"errors.log.include.messages": "true"
}
}'预期结果
{"name":"orders-file-source","config":{"connector.class":"org.apache.kafka.connect.file.FileStreamSourceConnector","tasks.max":"1","file":"/tmp/source-orders.txt","topic":"orders.raw","key.converter":"org.apache.kafka.connect.storage.StringConverter","value.converter":"org.apache.kafka.connect.storage.StringConverter","errors.tolerance":"all","errors.log.enable":"true","errors.log.include.messages":"true"},"tasks":[],"type":"source"}返回中的 tasks 可能暂时为空,因为 Worker 需要异步启动 Task。配置提交成功只说明控制面接受了请求,不代表数据已经开始流动。

检查 Task 状态与数据落点
创建后先看状态,再消费目标 Topic。真正健康的状态应同时满足 Connector 为 RUNNING,且所有 Task 都为 RUNNING。
curl -s http://localhost:8083/connectors/orders-file-source/status
kafka-console-consumer.sh \
--bootstrap-server localhost:9092 \
--topic orders.raw \
--from-beginning \
--max-messages 2预期输出
{"name":"orders-file-source","connector":{"state":"RUNNING","worker_id":"<IP>:<PORT>"},"tasks":[{"id":0,"state":"RUNNING","worker_id":"<IP>:<PORT>"}],"type":"source"}
order-1001
order-1002如果 Connector 是 RUNNING 而某个 Task 为 FAILED,优先查看该 Task 的 trace 字段。Connector 状态描述控制器本身,Task 状态才直接反映具体采集执行单元是否工作。
查看位移与错误记录
支持 Connector offset REST API 的 Kafka Connect 版本可以直接查询该连接器保存的 source offset。位移表示“外部数据读取到哪里”,不等同于 Kafka Topic 的 consumer group offset;失败 Task 的状态接口则会附带异常 trace。
curl -s http://localhost:8083/connectors/orders-file-source/offsets
curl -s http://localhost:8083/connectors/orders-file-source/tasks/0/status预期结果
{"offsets":[{"partition":{"filename":"/tmp/source-orders.txt"},"offset":{"position":<VALUE>}}]}
{"id":0,"state":"RUNNING","worker_id":"<IP>:<PORT>"}position 会随文件内容变化。Task 正常时通常没有 trace;进入 FAILED 后,状态响应会附带错误堆栈。由于示例启用了 errors.log.enable,可容忍的处理错误还会写入 Worker 日志,生产环境应将这些日志接入集中检索系统。
部署 Source Connector 的验收标准不是“POST 返回 201”,而是配置被接受、Task 持续 RUNNING、目标 Topic 有新数据、source offset 向前推进,并且错误日志与失败 trace 都处于可解释范围内。