参数参考

MYSQL 角色刻意只公开 11 项参数。软件版本、端口、目录、字符集、TLS 路径与定时器表达式由角色统一固定，内存基线按节点规格推导；需要调整服务器行为时使用 mysql_parameters。

参数概览

旧版页面曾出现的 mysql_role、mysql_services、mysql_packages、mysql_data、mysql_port、mysql_replication_*、mysql_*_username 等变量已不属于公开接口，请勿使用。

身份参数

mysql_cluster

必填的集群身份，必须与清单分组名一致（预检要求成员位于同名分组）。字母、数字或下划线开头，可含 ._-，最长 63 字符：

mysql_cluster: my-test

用于生成实例名（my-test-1）、MGR Group UUID（由集群名确定性推导）、备份目录（<repo>/my-test/）与监控标签 cls。

mysql_seq

必填的实例序号。单机为 1；三节点必须是连续的 1、2、3，并直接作为 server_id：

10.10.10.11: { mysql_seq: 1 }

mysql_seq=1 仅表示首次引导时的协调者；运行时主库由 MGR 选举决定，重跑剧本不会迁回主库。

凭据参数

mysql_root_password

本地 root@'localhost' 密码，仅限本机使用（套接字或回环地址）。不能包含换行，不能保留 CHANGE_ME 前缀：

mysql_root_password: MySQL.Root

首次启动时设置；此后如果现场密码与声明不一致，任务会拒绝隐式重置并明确报错——修改 root 密码需要先手工 ALTER USER 再同步清单。

mysql_monitor_password

dbuser_monitor@'127.0.0.1' 密码，供 mysqld_exporter 使用，仅限本机回环地址、最多 3 连接、只读权限：

mysql_monitor_password: MySQL.Monitor

mysql_cluster_password

dbuser_cluster@'%'（要求 TLS）与 dbuser_backup@'localhost' 共用的平台密码，用于 AdminAPI 集群管理、Router 引导与 XtraBackup：

mysql_cluster_password: MySQL.Cluster

HA 集群中该密码写入集群 Metadata 与 Router 密钥环，不能通过普通重跑轮换：现场值与声明不一致时预检直接拒绝。单机实例无此绑定，改清单重跑即生效。

业务对象

mysql_databases

增量收敛的业务数据库列表，字段 name / encoding / collate / encrypt：

mysql_databases:
  - { name: app }
  - { name: app2, encoding: utf8mb4, collate: utf8mb4_general_ci, encrypt: false }

只创建与更新，不会因移除条目而删除数据库。写法与校验规则见集群配置。

mysql_users

增量收敛的业务用户列表，字段 name / host / password / connlimit / priv：

mysql_users:
  - name: app
    host: '%'
    password: DBUser.App
    connlimit: 20
    priv: { 'app.*': 'ALL PRIVILEGES' }

授权只增不减（移除映射不会 REVOKE）；平台身份（root、monitor、cluster、backup）不可声明。写法与校验规则见集群配置。

mysql_parameters

[mysqld] 段参数覆盖字典，渲染在托管配置末尾，同名参数后写生效：

mysql_parameters:
  max_connections: 500
  long_query_time: 2
  innodb_buffer_pool_size: 2G
  innodb_print_all_deadlocks: true    # true/false 渲染为 ON/OFF

约束与行为：

• 键名 [A-Za-z][A-Za-z0-9_.-]{0,63}，值为单行标量；渲染后仍经 mysqld --validate-config 校验，写错参数在部署阶段失败而不影响运行中的实例；
• 保留参数拒绝覆盖（-/_ 写法同判）：user、pid_file、server_id、datadir、socket、port、bind_address、mysqlx_bind_address、report_host、gtid_mode、enforce_gtid_consistency、log_bin、relay_log、plugin_load_add，以及 group_replication_* 与 TLS 相关（require_secure_transport、ssl_*）全族；
• 变更后重跑 mysql.yml 触发编排式滚动重启（从库先行、主库殿后），HA 集群预期仅主库切换瞬间有秒级写中断；
• 平台默认值中可覆盖的典型项：sql_require_primary_key（默认 ON）、long_query_time（默认 1）、binlog_expire_logs_seconds（默认 7 天）、内存类参数。

会话级动态参数（AdminAPI 通过 SET PERSIST 管理的少数复制参数）以运行时为准；角色会在每次收敛时把 group_replication_group_seeds 钉回声明成员表，避免持久化漂移。

备份参数

mysql_backup_enabled

是否启用每日备份定时器（mysql-backup.timer，每日触发、随机延迟 30 分钟内）：

mysql_backup_enabled: true

设为 false 停用定时器，但保留备份脚本与配置。注意：若备份目录从未创建过（备份从未启用），手工触发会因目录缺失直接退出。

mysql_backup_repo

本地备份仓库定义，当前只支持 local 一种方式：

mysql_backup_repo:
  local:
    path: /data/backups/mysql     # 绝对路径，不能与数据目录重叠
    retention: 7                  # 保留最近 N 份已提交全量（1-9999）

目录布局与恢复流程见日常管理。

监控参数

mysql_exporter_enabled

是否启用 mysqld_exporter 与 VictoriaMetrics Target 注册：

mysql_exporter_enabled: true

设为 false 时停用 Exporter 服务，并将 /infra/targets/mysql/<实例>.yml 收敛为空列表（不删除文件；文件只由 mysql-rm.yml 删除）。

固定平台约定

以下值由角色固定或推导，不是清单参数，列出供运维参考：