📚 课程目录第3章连接器基础配置

3. 连接器基础配置：六个必填参数

说实话，我见过不少新手上来就调各种高级参数，结果连最基本的连接都跑不通。Debezium 连接器的配置，说白了就是告诉它三件事：连哪个数据库、用什么身份登录、变更数据往哪放。这六个参数就是干这个的。

核心原则：这六个参数是连接器的「身份证」，任何一个填错，连接器都起不来。我建议你先把它们当成硬性约束来对待。

3.1 connector.class — 连接器类型

这个参数决定了 Debezium 用哪种数据库协议去抓取变更。你想想看，MySQL 和 PostgreSQL 的 binlog 格式能一样吗？当然不能。

常见的取值：

io.debezium.connector.mysql.MySqlConnector — MySQL / MariaDB
io.debezium.connector.postgresql.PostgresConnector — PostgreSQL
io.debezium.connector.mongodb.MongoDbConnector — MongoDB
io.debezium.connector.sqlserver.SqlServerConnector — SQL Server
io.debezium.connector.oracle.OracleConnector — Oracle

我的习惯：我会把 connector.class 写在配置的第一行。这样一眼就能看出这个连接器是给哪个数据库用的。曾经有个同事把 MySQL 的连接器类名写成了 PostgreSQL 的，结果排查了半天……嗯，从那以后我就养成了这个习惯。

3.2 database.hostname 与 database.port — 网络地址

这两个参数一起决定了连接器往哪台机器的哪个端口发请求。没什么技术含量，但坑不少。

参数	说明	常见值
`database.hostname`	数据库主机名或 IP 地址	`192.168.1.100` 或 `db-prod.internal`
`database.port`	数据库监听端口	MySQL: `3306`, PostgreSQL: `5432`

我曾经踩过的坑：有一次配置 PostgreSQL 连接器，database.hostname 写的是 localhost，结果连接器在容器里跑，localhost 指向的是容器自己，不是宿主机上的数据库。折腾了半小时才发现。所以，生产环境一定要用明确的 IP 或可解析的主机名，别偷懒用 localhost。

另外，端口号默认值虽然常见，但我建议你还是显式写出来。为什么？因为有些云数据库的端口不是标准端口，比如 RDS for MySQL 有时候会用 3307。显式写出来，配置自文档化，别人一看就懂。

3.3 database.user 与 database.password — 认证凭证

这两个参数是连接器用来登录数据库的。权限给少了，连接器读不到 binlog；权限给多了，又有安全风险。

我一般会创建一个专用用户，只给必要的权限：

-- MySQL 示例
CREATE USER 'debezium'@'%' IDENTIFIED BY 'your_strong_password';
GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'debezium'@'%';
FLUSH PRIVILEGES;

安全建议：密码不要硬编码在配置文件中。可以用环境变量或密钥管理服务（如 Vault）来注入。Kafka Connect 的 REST API 会暴露连接器配置，明文密码等于裸奔。

我记得有一次做安全审计，发现某个测试环境的 Debezium 配置里密码是 password123……嗯，那个同事后来被拉去做了半天安全培训。

3.4 database.server.name — 逻辑标识符

这个参数很多人不理解它的作用。它其实是一个逻辑名称，用来标识这条数据变更流是从哪个数据库实例来的。

它的值会直接影响 Kafka 的 topic 命名：

# 假设 database.server.name = "production_mysql"
# 那么变更事件会发到这些 topic：
#   production_mysql.db_name.table_name
#   production_mysql.orders
#   production_mysql.users

所以，这个命名一定要有业务含义。我见过有人用 server1、db1 这种名字，半年后自己都分不清哪个是哪个。

我的命名规范：{环境}_{数据库类型}_{业务域}，比如 prod_mysql_orders、staging_pg_users。这样看 topic 名就知道数据来源，排查问题快很多。

3.5 完整配置示例

把这六个参数拼起来，就是一个最简可用的连接器配置：

{
  "name": "mysql-orders-connector",
  "config": {
    "connector.class": "io.debezium.connector.mysql.MySqlConnector",
    "database.hostname": "192.168.1.100",
    "database.port": "3306",
    "database.user": "debezium",
    "database.password": "${env:DB_PASSWORD}",
    "database.server.name": "prod_mysql_orders",
    "database.include.list": "orders_db",
    "table.include.list": "orders_db.orders, orders_db.order_items",
    "offset.storage.file.filename": "/data/offsets.dat",
    "database.history.kafka.bootstrap.servers": "kafka-broker:9092",
    "database.history.kafka.topic": "schema-changes.orders"
  }
}

注意：上面配置里的 database.history.kafka.bootstrap.servers 和 database.history.kafka.topic 是 MySQL 连接器必需的，用于存储 schema 变更历史。PostgreSQL 不需要这两个参数，因为它有自己的逻辑解码插件来管理 schema。

3.6 知识体系总览

下面这张图把这六个参数的关系梳理清楚了。你一看就明白：连接器配置其实就三层——连接谁、怎么连、叫什么。

3.7 常见问题与避坑

最后，我把这些年遇到过的跟这六个参数相关的坑整理一下：

connector.class 写错包名：大小写敏感，mysql 不是 MySQL，postgresql 不是 postgres。我建议你直接从官方文档复制，别手敲。
database.hostname 用了 VIP 或负载均衡器：Debezium 需要直连主库（或主节点），经过负载均衡可能导致连接漂移，binlog 位置丢失。
database.port 没写：虽然大多数连接器有默认端口，但显式写出来更安全。特别是 Oracle 和 SQL Server，端口经常不是默认的。
database.password 包含特殊字符：JSON 配置里需要转义，或者用环境变量注入。我见过密码里带 $ 导致解析失败的案例。
database.server.name 重复：同一个 Kafka Connect 集群里，server.name 必须唯一。否则 topic 会冲突，数据混在一起，根本分不清来源。

快速验证方法：配置好后，用 curl -X GET http://localhost:8083/connectors/你的连接器名/status 查看状态。如果 state 是 RUNNING，说明基础配置没问题。如果是 FAILED，先检查这六个参数。

嗯，基础配置就这些。别觉得简单，我见过太多线上事故都是这几个参数搞出来的。把它们吃透，后面的调优才有根基。