# Xenon 选举相关配置参数
{
  "raft-timeout": 3000,        # 心跳超时（毫秒）
  "raft-election-timeout": 6000, # 选举超时（毫秒）
  "raft-heartbeat-interval": 150, # 心跳间隔（毫秒）
  "leader-start-command": "mysql -e 'SET GLOBAL read_only=OFF;'",
  "leader-stop-command": "mysql -e 'SET GLOBAL read_only=ON;'"
}

apiVersion: mysql.radondb.com/v1beta1
kind: MysqlCluster
metadata:
  name: my-cluster
spec:
  mysqlVersion: "8.0.30"                    # MySQL 版本
  replicas: 3                                # 副本数（奇数，至少 1）
  image: radondb/mysql:8.0.30                # MySQL 镜像
  xenonImage: radondb/xenon:1.1.7            # Xenon 镜像
  backupImage: radondb/percona-xtrabackup:2.4 # 备份镜像
  
  mysqlOpts:                                # MySQL 配置参数
    innodb_buffer_pool_size: "2G"
    max_connections: 1000
    slow_query_log: "ON"
    character-set-server: "utf8mb4"
    
  xenonOpts:                                # Xenon 配置参数
    raft-timeout: 3000
    raft-election-timeout: 6000
    
  resources:                                # 资源配额
    requests:
      cpu: "2"
      memory: "4Gi"
    limits:
      cpu: "4"
      memory: "8Gi"
      
  persistence:                              # 持久化存储
    size: "100Gi"
    storageClassName: "local-storage"
    
  backup:                                   # 备份策略
    schedule: "0 2 * * *"                  # Cron 表达式，每天凌晨 2 点
    keepNum: 7                              # 保留最近 7 个备份
    type: "full"                            # full / incremental
    
  monitoring:                               # 监控配置
    exporterImage: radondb/mysqld-exporter:0.14.0
    serviceMonitorLabels:
      team: dba
    
  service:                                  # 服务暴露方式
    type: ClusterIP                         # ClusterIP / NodePort / LoadBalancer
    nodePort: 30306

status:
  conditions:
  - type: Ready
    status: "True"
    lastTransitionTime: "2025-03-15T10:00:00Z"
  leader: my-cluster-0                       # 当前主节点
  replicas: 3                                # 实际副本数
  readyReplicas: 3                           # Ready 状态副本数

# Headless Service - 为每个 Pod 提供稳定 DNS
apiVersion: v1
kind: Service
metadata:
  name: my-cluster-headless
spec:
  clusterIP: None
  selector:
    app: mysql
    cluster: my-cluster
  ports:
  - name: mysql
    port: 3306

# 读写 Service - 由 Operator 动态将 Label 指向 Leader
apiVersion: v1
kind: Service
metadata:
  name: my-cluster
spec:
  type: ClusterIP
  selector:
    app: mysql
    cluster: my-cluster
    role: leader          # Operator 动态管理此 Label
  ports:
  - name: mysql
    port: 3306

affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
    - labelSelector:
        matchLabels:
          app: mysql
          cluster: my-cluster
      topologyKey: kubernetes.io/hostname

# 全量备份 CronJob 示例
apiVersion: mysql.radondb.com/v1beta1
kind: MysqlBackup
metadata:
  name: my-cluster-backup-20250315
spec:
  clusterName: my-cluster
  type: full                        # full / incremental
  storage:
    type: s3
    s3:
      bucket: radondb-backups
      endpoint: s3.example.com
      region: us-east-1
      secretName: s3-credentials

Application
    ├── Write ──► Service(role:leader) ──► Leader Pod (read_only=OFF)
    │
    └── Read  ──► Service(role:follower) ──► Follower Pod-1 (read_only=ON)
                                          ──► Follower Pod-2 (read_only=ON)

# 只读 Service 示例
apiVersion: v1
kind: Service
metadata:
  name: my-cluster-readonly
spec:
  type: ClusterIP
  selector:
    app: mysql
    cluster: my-cluster
    role: follower
  ports:
  - name: mysql
    port: 3306

# ServiceMonitor CRD 示例
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: my-cluster-mysql
  labels:
    release: prometheus
spec:
  selector:
    matchLabels:
      app: mysql
      cluster: my-cluster
  endpoints:
  - port: metrics
    interval: 30s
    path: /metrics

# PDB 示例
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: my-cluster-pdb
spec:
  minAvailable: 2
  selector:
    matchLabels:
      app: mysql
      cluster: my-cluster

kubectl patch mysqlcluster my-cluster --type='merge' \
  -p '{"spec":{"image":"radondb/mysql:8.0.35"}}'

# MySQLCluster 持久化配置
spec:
  persistence:
    size: "200Gi"
    storageClassName: "local-ssd"
    accessModes:
    - ReadWriteOnce
    resources:
      requests:
        storage: 200Gi

总需求 = (数据大小 + 索引大小) × 1.5(碎片/膨胀) + binlog 保留大小 + 临时表空间 + 快照/克隆预留

T+0s      Leader 故障（OOM/NodeFailure/XenonCrash）
T+0~3s    Follower 心跳超时（raft-timeout: 3000ms）
T+3s      Follower 转为 Candidate，发送 RequestVote
T+3~4s    获得多数票，新 Leader 选出
T+4s      新 Leader 执行 leader-start-command（read_only=OFF）
T+4~5s    新 Leader 广播心跳，Follower 感知新 Leader 身份
T+5~8s    Follower CHANGE MASTER TO 新 Leader
T+5~10s   Operator 更新 Service Label（role: leader 指向新 Pod）
T+10~30s  应用感知连接中断 → 重连 → 恢复写入

# 手动触发 Leader 切换
kubectl exec -it my-cluster-0 -c xenon -- xenoncli raft transfer

# 查看集群当前状态
kubectl exec -it my-cluster-0 -c xenon -- xenoncli cluster raft
kubectl exec -it my-cluster-0 -c xenon -- xenoncli mysql status

# MySQLCluster 日志相关配置
spec:
  mysqlOpts:
    # Error Log
    log_error_verbosity: "2"        # 1:errors 2:errors+warnings 3:errors+warnings+notes
    
    # Slow Query
    slow_query_log: "ON"
    long_query_time: "1.0"         # 超过 1 秒计入慢查询
    log_queries_not_using_indexes: "ON"
    log_slow_admin_statements: "ON"
    min_examined_row_limit: "1000" # 扫描行数超过 1000 才记录
    
    # Binlog
    log_bin: "ON"
    binlog_format: "ROW"           # ROW 格式利于复制一致性
    binlog_row_image: "FULL"
    sync_binlog: "1"               # 每次事务同步 binlog 到磁盘
    expire_logs_days: "7"          # binlog 保留 7 天
    max_binlog_size: "500M"
    binlog_cache_size: "32768"

MySQL Container stdout/stderr
     │
     ├──► kubectl logs (临时查看)
     │
     └──► Fluent Bit / Filebeat DaemonSet
              │
              ├──► Elasticsearch / Loki
              │
              └──► Grafana (日志查询)

spec:
  mysqlOpts:
    log_output: "FILE"                    # 输出到文件而非 stderr
    slow_query_log_file: "/var/lib/mysql/slow-query.log"
    general_log_file: "/var/lib/mysql/general.log"

扩容注意点：

| 约束 | 说明 |
|------|------|
| 副本数为奇数 | 满足 Raft 多数派投票要求（1 / 3 / 5 / 7） |
| PodAntiAffinity | 扩容需确保目标 Node 不被已有 Pod 占用 |
| 存储容量 | 新 Pod 需匹配存储类支持的容量 |
| 网络带宽 | XtraBackup 数据同步占用带宽，生产环境限制传输速率 |
| Binlog 同步压力 | 新 Follower 追赶数据期间的 IO 压力 |

apiVersion: mysql.radondb.com/v1beta1
kind: MysqlVersion
metadata:
  name: mysql-8.0.30
spec:
  version: "8.0.30"
  mysqlImage: "radondb/mysql:8.0.30"
  xenonImage: "radondb/xenon:1.1.7"
  mysqlExporterImage: "radondb/mysqld-exporter:0.14.0"
  backupImage: "radondb/percona-xtrabackup:8.0.30"
  initImage: "radondb/mysql:8.0.30"
  # 升级限制：仅允许从指定版本平滑升级
  upgradeConstraints:
    - from: "8.0.28"
    - from: "8.0.29"
    - from: "8.0.30"
```text

版本管理能力：

| 能力 | 说明 |
|------|------|
| 版本发现 | Operator 启动时加载所有 `MysqlVersion` CRD，构建版本映射表 |
| 升级校验 | 创建集群时指定 `spec.mysqlVersion`，Operator 查找匹配的 `MysqlVersion` CRD |
| 滚动升级 | 更新 `MysqlCluster.spec.mysqlVersion`，Operator 按升级约束执行滚动升级 |
| 多版本共存 | 不同集群可使用不同 MySQL 版本，同一集群所有 Pod 版本一致 |
| 镜像替换 | 通过修改 `MysqlVersion.spec.mysqlImage`，所有引用该版本的集群均可感知变更 |

升级路径约束：MySQL 版本升级存在限制——只能跨越一个 GA 版本（如 8.0.28 → 8.0.34 不等同于 8.0.28 → 8.0.30 → 8.0.34 两次升级），Operator 依据 `upgradeConstraints` 拒绝跨版本直升。

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-cluster-config
data:
  my.cnf: |
    [mysqld]
    server-id=100
    innodb_buffer_pool_size=2G
    max_connections=1000
    character-set-server=utf8mb4
    collation-server=utf8mb4_unicode_ci
    slow_query_log=ON
    long_query_time=1.0
    binlog_format=ROW
    sync_binlog=1
    gtid_mode=ON
    enforce-gtid-consistency=ON

  xenon.json: |
    {
      "raft-timeout": 3000,
      "raft-election-timeout": 6000,
      "admit-defeat-hearbeat-count": 5,
      "leader-start-command": "mysql -e 'SET GLOBAL read_only=OFF; SET GLOBAL super_read_only=OFF;'",
      "leader-stop-command": "mysql -e 'SET GLOBAL super_read_only=ON; SET GLOBAL read_only=ON;'"
    }
```text

可在线修改的动态参数：

- `max_connections`
- `innodb_buffer_pool_size`（MySQL 8.0+）
- `slow_query_log` / `long_query_time`
- `read_only`（由 Xenon 自动管理）
- `innodb_flush_log_at_trx_commit`
- `sync_binlog`
- `general_log`

配置变更最佳实践：

graph TD
    subgraph Leader["Leader (my-cluster-0)"]
        Data["db1 / db2 / db3 (全量数据)<br/>所有写入在此完成"]
    end

    Leader -->|"Binlog Replication"| Follower1["Follower<br/>(只读副本)<br/>全量数据"]
    Leader -->|"Binlog Replication"| Follower2["Follower<br/>(只读副本)<br/>全量数据"]

# ClusterIP（默认）
spec:
  service:
    type: ClusterIP

# NodePort
spec:
  service:
    type: NodePort
    nodePort: 30306

# LoadBalancer
spec:
  service:
    type: LoadBalancer
    loadBalancerIP: "10.0.0.100"
    annotations:
      service.beta.kubernetes.io/aws-load-balancer-internal: "true"
      service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
```text

Service Endpoint 动态切换：Operator 实时监控 Xenon Raft 状态，当 Leader 切换后立即更新 Service 的 Label Selector（`role: leader` 指向新 Leader），确保写流量自动切到新主节点。

只读 Service 配置：

Pod 端口映射：

| 端口 | 用途 | 说明 |
|------|------|------|
| 3306 | MySQL 服务端口 | 数据库连接 |
| 9104 | mysqld-exporter Metrics | Prometheus 采集 |
| 8080 | Xenon HTTP API | Xenon 状态查询与管理 |

spec:
  tls:
    enabled: true
    # 引用包含 TLS 证书的 Secret
    secretName: mysql-tls-secret
    # 可选：指定 SAN（Subject Alternative Name）
    issuerRef:
      name: mysql-ca-issuer
      kind: Issuer
```text

Secret 内容要求（`mysql-tls-secret`）：

| Key | 内容 | 说明 |
|------|------|------|
| `ca.crt` | CA 根证书 | 签发客户端和服务端证书 |
| `tls.crt` | 服务端证书 | MySQL 服务端使用的 X.509 证书 |
| `tls.key` | 服务端私钥 | 对应服务端证书的私钥 |

MySQL TLS 配置项（Xenon 自动设置）：

安全配置集成：

| 安全维度 | 配置 | 效果 |
|------|------|------|
| 传输加密 | `require_secure_transport=ON` | 所有客户端连接必须使用 TLS |
| 复制加密 | Slave 连接自动使用 `MASTER_SSL=1` | 主从复制链路加密 |
| 密码策略 | `validate_password` 插件 | 密码复杂度校验 |
| 连接限制 | `max_connect_errors` / `connect_timeout` | 防暴力破解 |
| 网络安全 | NetworkPolicy 仅允许白名单 CIDR | 最小化暴露面 |
| 审计 | General Log（关闭）+ 应用层审计 | 可审计 SQL 操作 |

用户权限最小化：

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: mysql-alerts
  labels:
    release: prometheus
spec:
  groups:
  - name: mysql-critical
    rules:
    # P0: MySQL 实例宕机
    - alert: MySQLDown
      expr: mysql_up == 0
      for: 1m
      labels:
        severity: critical
      annotations:
        summary: "MySQL instance {{ $labels.pod }} is down"
        description: "MySQL on pod {{ $labels.pod }} has been down for more than 1 minute."
        runbook_url: "https://wiki.example.com/mysql-down"

    # P0: 复制中断
    - alert: MySQLReplicationBroken
      expr: mysql_slave_status_slave_io_running == 0 or mysql_slave_status_slave_sql_running == 0
      for: 1m
      labels:
        severity: critical
      annotations:
        summary: "MySQL replication broken on {{ $labels.pod }}"

  - name: mysql-warning
    rules:
    # P1: 复制延迟
    - alert: MySQLReplicationLag
      expr: mysql_slave_status_seconds_behind_master > 30
      for: 5m
      labels:
        severity: warning
      annotations:
        summary: "MySQL replication lag {{ $value }}s on {{ $labels.pod }}"

    # P1: 连接数超过 80%
    - alert: MySQLHighConnectionUsage
      expr: (mysql_global_status_threads_connected / mysql_global_variables_max_connections) * 100 > 80
      for: 5m
      labels:
        severity: warning
      annotations:
        summary: "MySQL connection usage {{ $value | humanize }}% on {{ $labels.pod }}"

    # P1: 缓冲池命中率低于 95%
    - alert: MySQLLowBufferPoolHitRate
      expr: (rate(mysql_global_status_innodb_buffer_pool_read_requests[10m]) - rate(mysql_global_status_innodb_buffer_pool_reads[10m])) / rate(mysql_global_status_innodb_buffer_pool_read_requests[10m]) < 0.95
      for: 10m
      labels:
        severity: warning
      annotations:
        summary: "InnoDB buffer pool hit rate below 95% on {{ $labels.pod }}"

    # P1: 磁盘增长预测
    - alert: MySQLDiskSpacePrediction
      expr: predict_linear(mysql_global_variables_datadir_size_bytes[6h], 24*3600) > 200*1024*1024*1024
      for: 1h
      labels:
        severity: warning
      annotations:
        summary: "MySQL data directory predicted to exceed 200GB in 24h"

  - name: mysql-info
    rules:
    # P2: 慢查询增长
    - alert: MySQLSlowQueriesIncrease
      expr: rate(mysql_global_status_slow_queries[5m]) > 10
      for: 10m
      labels:
        severity: info
      annotations:
        summary: "Slow queries rate {{ $value }}/s on {{ $labels.pod }}"

    # P2: 磁盘使用超过 70%
    - alert: MySQLDiskSpaceUsage
      expr: (mysql_global_variables_datadir_size_bytes / 200*1024*1024*1024) * 100 > 70
      for: 1h
      labels:
        severity: info
      annotations:
        summary: "MySQL data directory usage {{ $value | humanize }}%"

// Xenon 脑裂防护配置
{
  "raft-timeout": 3000,
  "raft-election-timeout": 6000,
  "leader-start-command": "mysql -e 'SET GLOBAL read_only=OFF; SET GLOBAL super_read_only=OFF;'",
  "leader-stop-command": "mysql -e 'SET GLOBAL read_only=ON; SET GLOBAL super_read_only=ON;'",
  "admit-defeat-hearbeat-count": 5
}

graph TD
    subgraph AZ1["AZ-1 (us-east-1a)"]
        subgraph NodeA["Node-A"]
            Pod0["my-cluster-0<br/>MySQL<br/>Xenon<br/>PVC (SSD)"]
        end
    end
    subgraph AZ2["AZ-2 (us-east-1b)"]
        subgraph NodeB["Node-B"]
            Pod1["my-cluster-1<br/>MySQL<br/>Xenon<br/>PVC (SSD)"]
        end
    end
    subgraph AZ3["AZ-3 (us-east-1c)"]
        subgraph NodeC["Node-C"]
            Pod2["my-cluster-2<br/>MySQL<br/>Xenon<br/>PVC (SSD)"]
        end
    end

    Pod0 <-->|"Raft Heartbeat (跨 AZ)"| Pod1
    Pod1 <-->|"Raft Heartbeat (跨 AZ)"| Pod2
    Pod0 <-->|"Raft Heartbeat (跨 AZ)"| Pod2
```text

跨 AZ 关键配置：

存储层跨 AZ 方案：

| 方案 | 说明 | 优缺点 |
|------|------|------|
| 云厂商跨 AZ 云盘 | 每个 AZ 独立 PV | 性能最优，依赖云平台 |
| Rook Ceph 跨 AZ 集群 | OSD 分布在多个 AZ，副本数>=3 | 统一存储层，跨 AZ 延迟增加 |
| 每个 AZ 独立 Local PV | 无共享存储 | 性能最高，无跨 AZ 存储依赖 |

跨 AZ 复制延迟考量：

| 场景 | 机房间延迟 | 复制模式 | 对写入事务的影响 |
|------|------|------|------|
| 同 AZ | <0.5ms | 半同步 | 几乎无额外延迟 |
| 跨 AZ（同 Region） | 1-3ms | 半同步 | 每个事务增加 1-3ms（等一确认） |
| 跨 Region | 30-100ms | **异步** | 无延迟影响，但故障时可能丢失数据 |

Raft 选举跨 AZ 影响：跨 AZ 部署时 Raft 心跳延迟略有增加，将 `raft-timeout` 从默认3000ms 调整为5000ms 可避免因跨 AZ 网络抖动导致的误触发选举。

[mysqld]
# InnoDB 核心
innodb_buffer_pool_size = 16G
innodb_buffer_pool_instances = 8
innodb_log_file_size = 2G
innodb_log_buffer_size = 256M
innodb_flush_log_at_trx_commit = 1
innodb_flush_method = O_DIRECT
innodb_io_capacity = 4000
innodb_io_capacity_max = 8000
innodb_read_io_threads = 8
innodb_write_io_threads = 8
innodb_page_cleaners = 8

# 连接
max_connections = 1000
thread_cache_size = 200
table_open_cache = 4000

# Binlog
binlog_format = ROW
sync_binlog = 1
binlog_cache_size = 1M

# 复制
slave_parallel_workers = 8
slave_parallel_type = LOGICAL_CLOCK

排查步骤：
1. kubectl describe pod my-cluster-0 → 查看 Events
2. kubectl logs my-cluster-0 -c init → Init Container 日志
3. kubectl logs my-cluster-0 -c mysql → MySQL 启动日志
4. kubectl logs my-cluster-0 -c xenon → Xenon 启动日志

常见原因：
- Init Container 数据目录校验失败 → PVC 损坏或目录为空
- MySQL 挂载卷权限问题 → fsGroup / runAsUser 未正确设置
- Xenon 无法连接 MySQL → /var/run/mysqld/mysqld.sock 不存在
- 磁盘空间不足 → PV 配额耗尽
```text

**场景 2：主从复制中断**

**场景 3：Raft 集群分裂**

**场景 4：备份失败**

**场景 5：性能下降**

# 查看 Operator 版本
radondb-mysql-operator version

# 查看集群列表
kubectl get mysqlcluster

# 查看集群详细状态
kubectl describe mysqlcluster my-cluster

# 创建集群
kubectl apply -f mysql-cluster.yaml

# 手动触发备份
kubectl apply -f - <<EOF
apiVersion: mysql.radondb.com/v1beta1
kind: MysqlBackup
metadata:
  name: my-cluster-manual-backup-$(date +%Y%m%d%H%M%S)
spec:
  clusterName: my-cluster
  type: full
EOF

# 从备份恢复
kubectl apply -f mysql-restore.yaml

# 查看备份列表
kubectl get mysqlbackup

# 删除集群（保留 PVC）
kubectl delete mysqlcluster my-cluster
```text

Xenon CLI（`xenoncli`）：

MySQL 运维命令：

Operator 日志查看：

# 集群健康检查
kubectl get mysqlcluster                              # CRD 状态 Ready
kubectl get pods -l cluster=my-cluster                # 所有 Pod Running
kubectl exec -it my-cluster-0 -c xenon -- xenoncli cluster raft  # Raft 正常
kubectl exec -it my-cluster-1 -- mysql -e "SHOW SLAVE STATUS\G"   # 复制正常

# 备份检查
kubectl get mysqlbackup                               # 最近备份 Completed
# 验证备份文件存在于 S3/MinIO

# 资源检查
kubectl top pods                                      # CPU/Memory 未达上限
kubectl get pvc                                       # PV 空间充足
```text