Binlog同步Gin核心接口使用说明

说明：接口基于Gin框架开发，默认监听端口8080；所有接口返回格式统一为JSON，核心字段为 code（状态码，200为成功，400为参数/业务错误）、msg（描述信息）、data（返回数据，可选）。

基础请求地址：http://{服务IP}:8080（替换{服务IP}为实际部署服务器IP）

核心特性：支持多MySQL实例多任务并发同步，同一MySQL实例仅允许启动一个同步任务（避免重复解析），不同实例任务间完全隔离，支持优雅启停、状态独立查询。

一、健康检查接口（基础校验）

1. 接口信息

• 请求方式：GET

• 请求地址：/api/health

• 接口作用：校验Gin服务是否正常运行，无业务逻辑依赖，用于日常运维心跳检测

• 请求参数：无

2. 返回示例（成功）

{
  "code": 200,
  "msg": "Gin服务运行正常",
  "time": "2026-02-06 16:00:00"
}

二、启动Binlog同步接口（核心）

1. 接口信息

• 请求方式：POST

• 请求地址：/api/sync/start

• 接口作用：传入Binlog同步配置，启动对应MySQL实例的同步任务（支持指定Binlog位置/最新位置同步，支持黑白名单库过滤）

• 请求头：Content-Type: application/json

• 注意：同一MySQL实例（同一IP+端口）仅允许启动一个同步任务，禁止重复调用；不同MySQL实例可同时启动多个独立任务。

2. 请求参数（JSON格式）

参数名	类型	是否必填	说明	示例值
mysql_host	string	是	MySQL服务IP地址，需确保与Gin服务网络互通	127.0.0.1
mysql_port	int	是	MySQL服务端口，范围1-65535	3306
mysql_user	string	是	MySQL登录用户名，需具备Binlog同步权限（建议授予REPLICATION SLAVE等权限）	root
mysql_password	string	是	MySQL登录密码，确保密码正确且无特殊字符转义问题	123456
mysql_server_id	uint32	是	Binlog同步Slave ID，需全局唯一，不能与MySQL集群中其他节点（主库、从库）及其他同步任务重复	1001
binlog_file	string	否	指定Binlog文件名，留空或传空字符串则从MySQL最新Binlog位置开始同步	mysql-bin.000001
binlog_pos	uint32	否	指定Binlog偏移量，需与binlog_file配套使用；留空或传0则从指定文件的起始位置同步	1200
allow_databases	array[string]	否	白名单：仅同步该列表中指定的数据库，非空时优先生效（优先级高于黑名单）	["test_db", "prod_db"]
skip_databases	array[string]	否	黑名单：跳过该列表中指定的数据库，仅当白名单为空时生效（建议跳过系统库）	["mysql", "information_schema"]

3. 请求示例（常用场景）

场景1：从最新位置同步（带黑白名单，推荐）

{
  "mysql_host": "127.0.0.1",
  "mysql_port": 3306,
  "mysql_user": "root",
  "mysql_password": "123456",
  "mysql_server_id": 1001,
  "allow_databases": ["test_db"],
  "skip_databases": [
    "mysql",
    "information_schema",
    "performance_schema",
    "sys",
    "mysql_innodb_cluster_metadata"
  ]
}

场景2：从指定Binlog位置同步（仅黑名单）

{
  "mysql_host": "127.0.0.1",
  "mysql_port": 3306,
  "mysql_user": "root",
  "mysql_password": "123456",
  "mysql_server_id": 1001,
  "binlog_file": "mysql-bin.000001",
  "binlog_pos": 1200,
  "skip_databases": [
    "mysql",
    "information_schema"
  ]
}

场景3：极简配置（从最新位置同步，无过滤）

{
  "mysql_host": "127.0.0.1",
  "mysql_port": 3306,
  "mysql_user": "root",
  "mysql_password": "123456",
  "mysql_server_id": 1001
}

4. 返回示例

成功示例

{
  "code": 200,
  "msg": "Binlog同步任务已启动",
  "data": {
    "task_id": "mysql-127.0.0.1:3306",
    "config": {
      "flavor": "mysql",
      "mysql": {
        "mysql_host": "127.0.0.1",
        "mysql_port": 3306,
        "mysql_user": "root",
        "mysql_password": "123456",
        "mysql_server_id": 1001
      },
      "binlog": {
        "binlog_file": "",
        "binlog_pos": 0
      },
      "allow_databases": {
        "test_db": true
      },
      "skip_databases": {
        "information_schema": true,
        "mysql": true,
        "mysql_innodb_cluster_metadata": true,
        "performance_schema": true,
        "sys": true
      }
    }
  }
}

失败示例（重复启动）

{
  "code": 400,
  "msg": "该MySQL实例的同步任务已在运行，请勿重复启动：mysql-127.0.0.1:3306",
  "data": null
}

失败示例（参数缺失）

{
  "code": 400,
  "msg": "参数解析失败：Key: 'SyncRequest.mysql_host' Error:Field validation for 'mysql_host' failed on the 'required' tag",
  "data": null
}

三、查看同步状态接口

1. 接口信息

• 请求方式：GET

• 请求地址：/api/sync/status

• 接口作用：查询指定Binlog同步任务的运行状态、完整配置信息，用于运维监控

• 请求参数：task_id（必填，字符串，任务唯一标识，格式为mysql-IP:端口）

2. 返回示例

示例1：正在同步

{
  "code": 200,
  "data": {
    "is_syncing": true,
    "config": {
      "flavor": "mysql",
      "mysql": {
        "mysql_host": "127.0.0.1",
        "mysql_port": 3306,
        "mysql_user": "root",
        "mysql_password": "123456",
        "mysql_server_id": 1001
      },
      "binlog": {
        "binlog_file": "",
        "binlog_pos": 0
      },
      "allow_databases": {
        "test_db": true
      },
      "skip_databases": {
        "information_schema": true,
        "mysql": true,
        "mysql_innodb_cluster_metadata": true,
        "performance_schema": true,
        "sys": true
      }
    },
    "msg": "正在同步Binlog"
  }
}

示例2：未在同步

{
  "code": 200,
  "data": {
    "is_syncing": false,
    "config": null,
    "msg": "未在同步"
  }
}

示例3：任务不存在

{
  "code": 404,
  "msg": "任务不存在：mysql-127.0.0.1:3306",
  "data": null
}

四、停止Binlog同步接口

1. 接口信息

• 请求方式：POST

• 请求地址：/api/sync/stop

• 接口作用：手动触发指定Binlog同步任务停止，执行优雅退出，停止后会在服务控制台打印本次同步统计信息

• 请求头：Content-Type: application/json

2. 请求参数（JSON格式）

参数名	类型	是否必填	说明	示例值
task_id	string	是	同步任务唯一标识，启动任务时返回的task_id	mysql-127.0.0.1:3306

3. 返回示例

成功示例

{
  "code": 200,
  "msg": "已触发任务停止：mysql-127.0.0.1:3306",
  "data": null
}

失败示例（无运行任务）

{
  "code": 400,
  "msg": "无运行中的任务：mysql-127.0.0.1:3306",
  "data": null
}

五、查询所有同步任务接口

1. 接口信息

• 请求方式：GET

• 请求地址：/api/sync/tasks

• 接口作用：查询当前所有同步任务的简要状态，便于批量运维监控

• 请求参数：无

2. 返回示例

{
  "code": 200,
  "data": {
    "task_count": 2,
    "tasks": [
      {
        "task_id": "mysql-127.0.0.1:3306",
        "is_syncing": true,
        "mysql_host": "127.0.0.1",
        "mysql_port": 3306,
        "binlog_file": "mysql-bin.000001",
        "binlog_pos": 1200
      },
      {
        "task_id": "mysql-172.18.20.66:3306",
        "is_syncing": false,
        "mysql_host": "172.18.20.66",
        "mysql_port": 3306,
        "binlog_file": "",
        "binlog_pos": 0
      }
    ]
  }
}

六、关键注意事项

1. 启动同步时，mysql_server_id 必须全局唯一，若与MySQL集群中其他节点（主库、从库）或其他同步任务重复，会导致Binlog同步启动失败；建议按“1000+实例编号”规则分配（如1001、1002）。

2. 黑白名单规则：白名单（allow_databases）非空时，仅同步白名单中的库；白名单为空时，同步所有不在黑名单（skip_databases）中的库，两者均为空则同步所有库。

3. 黑白名单需传入数组格式，若无需过滤，可直接省略该参数（无需传空数组）；系统库（如mysql、information_schema）建议加入黑名单，避免无效同步。

4. 同步任务停止后，会自动在Gin服务控制台打印本次同步的 RunInfo 统计信息（含总事件数、总行数、成功/失败数等核心指标），便于排查问题。

5. Gin服务重启后，所有正在运行的同步任务会自动终止，需重新调用启动接口启动同步；若需实现断点续传，需额外将任务位置信息持久化（如存数据库/本地文件）。

6. 若MySQL为MGR集群，启动同步前需确保集群状态正常（无NO_QUORUM错误），且同步连接指向集群主节点，否则会导致Binlog同步启动失败或同步异常。

7. 停止同步任务时，建议等待2秒后再重启该实例的同步任务，确保原有协程完全退出、资源释放，避免端口/连接冲突。