agent-skills/skills/g3fo-docs/references/middleware/mysql/fault-analysis.md

# MySQL 8.4 复制冲突解决指南

> **AI 响应规范 (MySQL 执行策略)**:
> 1. **强制参数**: 所有 `docker exec` 命令必须包含 `-h127.0.0.1` 参数。
> 2. **双重输出**: 涉及 SQL 操作时，必须同时输出 `Docker 执行命令` 和 `纯 SQL 脚本`。
> 3. **默认连接**: 默认使用 `-uroot -pafe123456 -h127.0.0.1`。
> 4. **排障连贯性**: 诊断复制冲突时，在提供 **A. 查看复制状态概要** 后，**必须紧跟** 提供 **B. 自动提取错误详情** 脚本，以便用户直接获取修复建议。

## 1. 复制冲突解决（主键/唯一键重复或记录缺失）

### 1.1 快速定位冲突信息

当复制中断时，**必须按顺序执行以下两步**：首先查看概要，然后提取详细错误以获取修复脚本。

**A. 查看复制状态概要:**
```bash
# 方式 1: 传统状态查看 (重点关注 Last_SQL_Error)
docker exec -it mysql mysql -uroot -pafe123456 -h127.0.0.1 -e "SHOW REPLICA STATUS\G" | grep -E "Replica_.*_Running|Last_SQL_Error|Retrieved_Gtid_Set|Executed_Gtid_Set"

# 方式 2: 多线程环境下查看详情 (若启用并行复制，SHOW REPLICA STATUS 只能看到协调线程错误)
docker exec -it mysql mysql -uroot -pafe123456 -h127.0.0.1 -e "SELECT * FROM performance_schema.replication_applier_status_by_worker WHERE LAST_ERROR_NUMBER > 0\G"
```

**B. 自动提取错误详情（支持 1062 重复键 / 1032 记录未找到）:**
直接在宿主机执行以下脚本，它会自动解析错误日志并生成对应的修复方案：

```bash
# 提取冲突 GTID、表、冲突值及修复建议
grep -aE "Duplicate entry|Error_code: 1032" /data/mysql/logs/mysql_error.log | perl -nle '
if (/^(\S+).*?transaction\s+[\x27"]([^\x27"]+)[\x27"].*?table\s+([^\s;]+);/) {
  my ($time, $gtid, $table) = ($1, $2, $3);
  print "\n" . "="x60;
  print "时间: $time";
  print "GTID: $gtid";
  print "表名: $table";

  if (/Duplicate entry\s+[\x27"]([^\x27"]+)[\x27"]\s+for\s+key\s+[\x27"]([^\x27"]+)[\x27"]/) {
    print "类型: 1062 (主键/唯一键重复)";
    print "冲突值: $1 (索引: $2)";
    print "\n方案 A (手动修复 - 删除从库冲突行):";
    print "DELETE FROM $table WHERE [主键列] = \x27$1\x27;";
    print "\n方案 B (跳过事务 - 保持从库现状):";
    print "STOP REPLICA; SET GTID_NEXT=\x27$gtid\x27; BEGIN; COMMIT; SET GTID_NEXT=\x27AUTOMATIC\x27; START REPLICA;";
  } elsif (/Error_code: 1032|HA_ERR_KEY_NOT_FOUND/) {
    print "类型: 1032 (记录未找到 - 通常是 Delete/Update 目标不存在)";
    print "说明: 目标行在从库已不存在，Delete 操作已实质生效。";
    print "\n方案 A (直接跳过 - 安全):";
    print "STOP REPLICA; SET GTID_NEXT=\x27$gtid\x27; BEGIN; COMMIT; SET GTID_NEXT=\x27AUTOMATIC\x27; START REPLICA;";
  }
}
'
```

### 1.2 安全修复冲突（推荐删除冲突数据）
停止复制，临时关闭 binlog（避免删除操作同步到对端）：

**A. Docker 执行模式 (包含 -h127.0.0.1):**
```bash
# 以实际冲突表和主键为例（示例：test_sync.t1 的 id=12）
docker exec -it mysql mysql -uroot -pafe123456 -h127.0.0.1 -e "
STOP REPLICA;
SET sql_log_bin = OFF;
DELETE FROM `test_sync`.`t1` WHERE `id` = 12;
SET sql_log_bin = ON;
START REPLICA;
SHOW REPLICA STATUS\G;
"
```

**B. 纯 SQL 模式:**
```sql
STOP REPLICA;
SET sql_log_bin = OFF;
DELETE FROM `test_sync`.`t1` WHERE `id` = 12;
SET sql_log_bin = ON;
START REPLICA;
SHOW REPLICA STATUS\G;
```

### 1.3 应急跳过冲突事务（仅紧急场景）
精准跳过指定 GTID 事务（MySQL 8.0+ 推荐）：

**A. Docker 执行模式 (包含 -h127.0.0.1):**
```bash
docker exec -it mysql mysql -uroot -pafe123456 -h127.0.0.1 -e "
STOP REPLICA;
SET GTID_NEXT = '760f0600-f896-11ef-b265-0242ac130002:6';  # 替换为实际冲突 GTID
BEGIN; COMMIT;
SET GTID_NEXT = 'AUTOMATIC';
START REPLICA;
"
```

**B. 纯 SQL 模式:**
```sql
STOP REPLICA;
SET GTID_NEXT = '760f0600-f896-11ef-b265-0242ac130002:6';
BEGIN; COMMIT;
SET GTID_NEXT = 'AUTOMATIC';
START REPLICA;
```