mysql 8.0 官方推荐的实例级逻辑备份方式是 util.dumpinstance()，它支持并行、自动捕获 gtid 和 binlog 位置，需在 mysql shell 的 javascript/python 模式下通过 x protocol 连接执行，依赖 select、backup_admin、reload 等权限，目标路径须为空且 mysql 进程有写权限，并默认启用 consistent 快照与 zstd 压缩。
util.dumpInstance() 是 MySQL 8.0 官方推荐的实例级逻辑备份方式，比 mysqldump 更快、支持并行、能自动捕获 GTID 和 binlog 位置，适合中大型实例。但直接调用容易失败或产生意外结果，关键在于权限、路径、参数三者必须同时满足。
备份前必须确认的权限和连接方式
util.dumpInstance() 不是普通 SQL 命令，它依赖 AdminAPI，在 MySQL Shell 的 JavaScript 或 Python 模式下运行，且要求用户具备特定权限：
- 必须有 SELECT、BACKUP_ADMIN、RELOAD、PROCESS、REPLICATION CLIENT 权限
- SUPER 在 8.0.21+ 已非必需，但部分旧部署仍需（尤其含 mysql.sys 视图时）
- 连接必须使用 X Protocol（即 mysqlx:// 或 --mx），不能只用传统 TCP 连接（--sql 模式下会报错 “Operation not supported”）
常见错误现象：RuntimeError: Util.dumpInstance: Operation not supported 或 Access denied; you need (at least one of) the BACKUP_ADMIN privilege(s)
实操建议：
- 用
mysqlsh --uri mysqlx://root@localhost:33060启动（端口默认 33060，不是 3306） - 执行
\connect后再运行util.dumpInstance()，避免在未认证状态下误操作 - 权限授予语句必须显式包含
BACKUP_ADMIN：GRANT SELECT, BACKUP_ADMIN, RELOAD, PROCESS, REPLICATION CLIENT ON *.* TO 'backup_user'@'localhost';
util.dumpInstance() 的路径和目录约束
util.dumpInstance() 要求目标目录必须为空，且 MySQL 进程（不是当前 shell 用户）要有写权限。它不会创建父目录，也不会清空已有内容 —— 遇到非空目录直接报错退出。
常见错误现象：OSError: [Errno 39] Directory not empty 或 PermissionError: [Errno 13] Permission denied
实操建议：
- 备份路径用绝对路径，如
/backup/mysql/full_20260811，不要用相对路径或 Windows 驱动器盘符（如F:/backup在 Linux 下无效） - 提前手动创建目录并赋权：
mkdir -p /backup/mysql/full_20260811 && chown mysql:mysql /backup/mysql/full_20260811 - 如果用 root 启动 MySQL，确保该目录对
mysql用户可写；若用 systemd 管理，检查mysql.service中的User=设置
压缩、过滤与一致性控制参数怎么选
util.dumpInstance() 默认开启 compression: "zstd"，但线上调试时建议先关压缩（compression: "none"），方便快速验证文件结构。真正上线必须开压缩，否则备份体积暴涨且恢复慢。
关键参数差异：
-
excludeSchemas: ["mysql", "sys", "information_schema"]：这三个库默认不备份，但mysql里含账号信息（@.users.sql），如需迁移账号，别 exclude -
includeSchemas: ["app_db"]：只备份指定库，适合多租户环境隔离备份 -
consistent: true（默认）：启用全局读锁 + GTID 快照，保证一致性；设为false仅适用于只读实例，否则数据可能不一致 -
threads: 4：默认值，大实例可调高（如 8），但超过 CPU 核数收益递减，还可能压垮 I/O
示例命令（带注释）：
util.dumpInstance("/backup/mysql/full_20260811", {
compression: "zstd",
excludeSchemas: ["performance_schema"],
consistent: true,
threads: 6
})
备份后如何验证是否可用
util.dumpInstance() 成功后只输出日志，不校验文件完整性。真正风险点在恢复环节 —— 如果备份中途断电或磁盘满，@.done.json 可能没写入，但部分 .tsv 文件已生成，导致 util.loadDump() 报错或静默跳过表。
实操建议：
- 检查
@.done.json是否存在且非空：jq '.duration' /backup/mysql/full_20260811/@.done.json - 确认
sbtest@sbtest1.json类元数据文件数量与实际表数一致（可用find /backup/mysql/full_20260811 -name "*.json" | wc -l粗略估算） - 抽样查看一个
.tsv文件头几行：head -n 3 /backup/mysql/full_20260811/sbtest@sbtest1.tsv，确认是制表符分隔、无乱码 - 不要跳过小规模恢复测试 —— 直接在测试实例上跑一次
util.loadDump()，比任何检查都可靠
真正容易被忽略的是：备份目录权限归属、BACKUP_ADMIN 权限是否实际生效、以及 @.done.json 的存在性 —— 这三项任一缺失，都会让备份在恢复时“看起来成功，实际丢数据”。
