3. Kafka Connect 单机模式：配置、启动与日志排查
单机模式，说白了就是在一台机器上跑 Connect 进程。很多初学者觉得这模式太简单，不值得花时间。但我得说句实话——单机模式是你理解 Connect 内部机制的最佳入口。我在项目中见过不少团队，分布式模式出了问题，最后定位到根因时，发现其实在单机模式下就能复现和排查。
这一章，咱们就踏踏实实把单机模式吃透。
3.1 单机模式配置文件详解
启动单机模式，核心就两个配置文件：connect-standalone.properties 和你的连接器配置文件（比如 file-source.properties）。前者管 Connect 进程本身，后者管具体的数据搬运任务。
先看 connect-standalone.properties 里最关键的几项：
# 核心配置
bootstrap.servers=localhost:9092
key.converter=org.apache.kafka.connect.json.JsonConverter
value.converter=org.apache.kafka.connect.json.JsonConverter
key.converter.schemas.enable=true
value.converter.schemas.enable=true
# 偏移量存储
offset.storage.file.filename=/tmp/connect.offsets
offset.flush.interval.ms=10000
# 插件路径
plugin.path=/usr/share/java,/opt/connectors这里我重点说几个坑：
bootstrap.servers：别只写一个 broker 地址。我习惯写至少两个，比如localhost:9092,localhost:9093。万一那个 broker 挂了，Connect 还能连上集群。key.converter.schemas.enable：这个开关很多人搞混。开了以后，每条消息都会带 schema 信息，数据量会变大。如果你下游是简单的日志收集，关掉它性能更好。offset.storage.file.filename：单机模式下偏移量存在本地文件。我曾经遇到磁盘写满，偏移量文件损坏，结果重启后重复消费了十几万条数据。嗯，建议把这个文件放到单独的磁盘分区。
3.2 启动与停止：别只会 Ctrl+C
启动命令很简单：
bin/connect-standalone.sh config/connect-standalone.properties config/file-source.properties但这里有个细节——启动顺序。我建议先确保 Kafka 集群和主题都就绪了，再启动 Connect。否则 Connect 启动时会一直重试连接，日志里刷满 WARN 信息，干扰你判断真正的问题。
kafka-topics.sh --bootstrap-server localhost:9092 --list，确认集群通了再启动 Connect。这步花不了 5 秒，但能省下你半小时的排查时间。
停止呢？直接 Ctrl+C 确实能停，但不优雅。正确的做法是：
# 先找到进程 ID
ps aux | grep connect-standalone
# 发送 SIGTERM 信号
kill -15 <PID>为什么要用 SIGTERM？因为 Connect 收到这个信号后，会先 flush 当前偏移量，确保已消费的数据不会重复。如果你直接 kill -9，偏移量可能没来得及写盘，重启后就会重复消费。
Ctrl+C 其实也会触发 SIGTERM。但如果你用脚本管理进程，或者通过容器运行，一定要确保发送的是 SIGTERM 而不是 SIGKILL。
3.3 日志查看：从海量信息中捞干货
Connect 的日志默认输出到控制台，但生产环境我建议重定向到文件：
bin/connect-standalone.sh config/connect-standalone.properties config/file-source.properties > connect.log 2>&1 &日志级别默认是 INFO。我个人习惯在 connect-log4j.properties 里把 org.apache.kafka.connect 的日志调到 DEBUG，但只保留最近两个文件：
log4j.logger.org.apache.kafka.connect=DEBUG, connectAppender
log4j.appender.connectAppender.MaxFileSize=100MB
log4j.appender.connectAppender.MaxBackupIndex=2为什么只保留两个？因为 DEBUG 日志量太大了，保留太多会撑爆磁盘。我见过有人没配这个，三天后磁盘满了，整个进程挂掉。
排查问题时，我通常按这个顺序看日志：
- 先搜
ERROR：直接定位致命问题。 - 再搜
WARN：很多潜在问题会在这里暴露。 - 最后看启动阶段的
INFO：确认连接器是否成功加载。
举个例子，启动时看到这条日志就说明连接器加载成功了：
[INFO] Finished starting connectors and tasks如果没看到，那你的连接器配置可能有问题。
3.4 常见问题排查：我踩过的坑
做单机模式这些年，我遇到过不少问题。挑几个典型的说说：
| 问题现象 | 根因 | 解决方案 |
|---|---|---|
启动后连接器状态一直是 UNASSIGNED |
偏移量文件损坏或权限不对 | 删除 offset.storage.file.filename 指定的文件，重启 |
| 数据写入 Kafka 但格式乱码 | Converter 配置不一致 | 检查 key.converter 和 value.converter 是否匹配 |
连接器报 ClassNotFoundException |
插件路径没配对 | 检查 plugin.path 是否包含连接器 jar 包所在目录 |
任务频繁重启，日志里出现 Offset commit failed |
偏移量刷盘太频繁或磁盘 I/O 瓶颈 | 调大 offset.flush.interval.ms，比如改成 30000 |
这里我特别想说说 插件路径 的问题。我曾经花了一整个下午排查一个连接器加载失败的问题，最后发现是 plugin.path 里写了个不存在的目录。Connect 不会报错，它只是默默跳过。你想想看，这种问题多隐蔽。
排查插件路径的黄金命令：
# 启动时加上 --verbose 参数
bin/connect-standalone.sh config/connect-standalone.properties --verbose 2>&1 | grep -i plugin这样你能看到 Connect 到底扫描了哪些目录，加载了哪些插件。
3.5 单机模式知识体系总览
下面这张图把单机模式的核心知识点串起来了。你可以把它当作一个快速索引，遇到问题时先看这张图，定位到具体环节再深入排查。
3.6 写在最后
单机模式虽然简单，但它是你理解 Connect 内部机制的基础。配置文件怎么配、启动顺序怎么排、日志怎么看、问题怎么查——这些基本功打扎实了，后面学分布式模式会轻松很多。
我个人建议，你可以在测试环境里故意制造一些故障，比如删掉偏移量文件、改错插件路径、模拟磁盘写满。亲手踩一遍坑，比看十遍文档都管用。嗯，我就是这么过来的。