MariaDB 运行手册（RUNBOOK）¶

服务：server 命名空间下的 MariaDB 单实例（mariadb-operator 托管）配套变更档案见 SOP.md；本文档面向日常运维与值班，无需了解本次变更历史即可照着操作。

目录¶

服务概览
接入与凭据
日常速查表
日常操作
配置管理
备份与恢复
监控与告警
故障处置
安全与权限
容量与性能
附录

1. 服务概览¶

项目	内容
用途	集群内共享 MariaDB 数据库，当前承载业务库 `slurm_acct_db`、`rain`
版本	MariaDB 12.3.3（12.3 LTS，社区维护至 2029-05）
形态	单实例（副本数 1），非高可用
托管方式	mariadb-operator 26.6.0 依据 `MariaDB` 自定义资源生成 StatefulSet、Service、PVC
数据落盘	PVC `storage-mariadb-0`（20Gi）→ StorageClass `nfs-csi` → NFS `192.168.31.249:/srv/nfs/k8s`
运行节点	由调度器决定，实测曾落 `k8s-node-02`、`k8s-node-03`
重要性等级	高。数据不可再生，服务中断影响所有依赖方（含 Slurm 记账）
异常时的业务影响	写入失败、记账中断、依赖应用的连接报错；数据本身因落在 NFS 上不会随 Pod 消失

组件构成：

组件	位置	说明
MariaDB 实例	`server/mariadb-0`（Pod）、`server/mariadb`（Service）	数据库本体
控制器	`mariadb-system/mariadb-operator`	依据 CR 生成并修复工作负载
准入 Webhook	`mariadb-system/mariadb-operator-webhook`	校验 CR 合法性；不可用时 CR 写入会被拒
证书控制器	`mariadb-system/mariadb-operator-cert-controller`	签发 Webhook 与实例 TLS 证书，替代 cert-manager
CRD	`mariadbs.k8s.mariadb.com` 等	由独立 release `mariadb-operator-crds` 管理

外部依赖：NFS 服务端 192.168.31.249（主机名 dell-R620，即常见运维入口机）。该主机不可达时，数据库容器会出现 IO 挂起（mount 选项为 hard），而非快速报错。

2. 接入与凭据¶

地址与端口¶

场景	地址	端口
集群内（推荐）	`mariadb.server.svc.cluster.local`	3306
集群内（短名，同命名空间）	`mariadb`	3306
通过 Traefik TCP 入口	`traefik.server.svc.cluster.local`	3306（已有 `IngressRouteTCP/mariadb` → `mariadb:3306`）
集群外	需先做端口转发，见下方示例	—

Traefik 的 Service 类型为 ClusterIP，集群外访问需沿用现有运维约定（与已有 openldap 的 TCP 暴露方式一致）。

账号清单¶

账号	来源	用途
`root@%`	部署时创建	管理账号，可远程登录
`root@localhost`	镜像初始化	容器内本地管理
`slurm@%`	业务方自行创建	业务账号（Slurm 记账）
`healthcheck@localhost/127.0.0.1/::1`	operator 自动创建	健康检查专用，勿动

凭据取用（凭据不写入本文档）¶

# 取出 root 密码到当前 shell 变量（推荐，避免进入命令历史）
export MDB_ROOT_PW="$(kubectl -n server get secret mariadb-root -o jsonpath='{.data.password}' | base64 -d)"
echo "长度=${#MDB_ROOT_PW}"        # 仅校验取到了值，不回显明文

客户端接入示例¶

# 方式一：容器内登录（最快捷，无需网络打通）
kubectl -n server exec -it mariadb-0 -- env MYSQL_PWD="$MDB_ROOT_PW" mariadb -uroot

# 方式二：集群内其他 Pod 连接
#   mariadb -h mariadb.server.svc.cluster.local -P 3306 -uroot -p

# 方式三：从本地机器经端口转发连接（保持该终端不关闭）
kubectl -n server port-forward svc/mariadb 13306:3306
#   另开终端：mariadb -h 127.0.0.1 -P 13306 -uroot -p

# 方式四：应用侧连接串（以 JDBC 为例）
#   jdbc:mariadb://mariadb.server.svc.cluster.local:3306/slurm_acct_db

3. 日常速查表¶

#	目的	命令
1	实例是否就绪	`kubectl -n server get mariadb mariadb`
2	Pod 状态与重启次数	`kubectl -n server get pod mariadb-0 -o wide`
3	查看数据库日志	`kubectl -n server logs mariadb-0 --tail=100`
4	登录数据库	`kubectl -n server exec -it mariadb-0 -- env MYSQL_PWD="$MDB_ROOT_PW" mariadb -uroot`
5	重启实例	`kubectl -n server delete pod mariadb-0`
6	逻辑备份	见第 6 章备份命令
7	存储与容量	`kubectl -n server get pvc storage-mariadb-0`；`df -h /srv/nfs/k8s`（NFS 服务端执行）
8	控制器是否正常	`kubectl -n mariadb-system get pods`
9	近期事件	`kubectl -n server get events --sort-by=.lastTimestamp \\| tail -20`
10	资源水位	`kubectl top pod -n server mariadb-0`

第 4 项需要先按第 2 章取出 MDB_ROOT_PW。

4. 日常操作¶

4.1 状态检查¶

kubectl -n server get mariadb mariadb

预期输出（READY=True、STATUS=Running 即正常）：

NAME      READY   STATUS    PRIMARY     UPDATES                    AGE
mariadb   True    Running   mariadb-0   ReplicasFirstPrimaryLast   36h

kubectl -n server get pod mariadb-0

预期 1/1 Running、RESTARTS 为 0 或较少。若 RESTARTS 持续增长 → 按 8.1 处置。

kubectl -n server get sts mariadb

预期 READY 1/1。

4.2 启动 / 停止 / 重启¶

重启（推荐做法，滚动式，最轻量）：

kubectl -n server delete pod mariadb-0              # StatefulSet 会自动重建同名 Pod
kubectl -n server wait --for=condition=Ready pod/mariadb-0 --timeout=280s

预期：Pod 在 1 分钟内重建并 Ready，数据保留（已验证：Pod 重建后原库表数据完好）。

停止实例（高危：服务中断）：

# 先备份！见第 6 章
kubectl -n server patch mariadb mariadb --type=merge -p '{"spec":{"suspend":true}}'   # 高危：停止数据库

该命令属应急手段，会让 CR 暂时偏离 helm 期望清单；恢复 suspend: false 后即回到一致状态。常规的参数变更仍应走 values.yaml（见第 5 章）。

恢复运行：

kubectl -n server patch mariadb mariadb --type=merge -p '{"spec":{"suspend":false}}'
kubectl -n server wait --for=condition=Ready pod/mariadb-0 --timeout=280s

4.3 日志查看¶

# 最近 100 行
kubectl -n server logs mariadb-0 --tail=100

# 持续跟踪
kubectl -n server logs -f mariadb-0

# 只看报错（按关键字过滤，注意日志量）
kubectl -n server logs mariadb-0 --since=1h | grep -iE "error|warning|denied|refused|timeout|stale"

# 控制器日志（排查 CR 不被处理、Pod 不被重建等问题）
kubectl -n mariadb-system logs deploy/mariadb-operator --since=1h --tail=200

日志上限排查技巧：容器日志受 kubelet 轮转限制，历史更早的日志只能落到节点 /var/log/pods/server_mariadb-0_*/ 下查找。

4.4 进入容器排障¶

kubectl -n server exec -it mariadb-0 -- bash

# 容器内常用检查
df -h /var/lib/mysql                    # 数据盘挂载与容量
mount | grep mysql                      # 确认挂的是 NFS 而非本地盘
ls -l /var/lib/mysql | head             # 数据文件是否可读
mariadb-admin status -uroot -p          # 服务端运行指标，按提示输入 root 密码

4.5 扩缩容¶

副本数当前为 1（单实例）。扩副本不等于高可用——本实例未配置复制拓扑，直接调大 replicas 只会得到多个独立实例。需要高可用请按独立变更引入主从或 Galera 拓扑。

4.6 调整资源与存储¶

均通过 mariadb-deploy/charts/mariadb/values.yaml 修改后重新部署，详见第 5 章。

5. 配置管理¶

5.1 配置项位置¶

配置	位置	说明
实例参数（版本、副本、资源、存储、my.cnf）	`mariadb-deploy/charts/mariadb/values.yaml`	唯一入口，改这里
root 密码	Secret `server/mariadb-root`	不随 chart 管理
服务端运行时参数	CR 的 `spec.myCnf`（当前为空）	需要调优时写入

5.2 修改流程¶

cd mariadb-deploy
vi charts/mariadb/values.yaml                 # 修改目标参数（如 resources.limits.memory）

helm upgrade --install mariadb ./charts/mariadb -n server    # 应用变更
kubectl -n server wait --for=condition=Ready pod/mariadb-0 --timeout=280s

生效方式：

改动 replicas / resources / myCnf / image → 控制器滚动重建 Pod，会有短暂中断（单实例）。
改动 storage.size → 存储类支持在线扩容，PVC 直接扩容，一般不中断。

5.3 易错点¶

不要直接 kubectl edit mariadb mariadb。手工改动会让集群状态与 helm 期望漂移，下次 helm upgrade 会覆盖它；排查时也容易误判。所有变更走 values.yaml。
不要手工编辑 mariadb-0 的 StatefulSet 与 PVC，它们由控制器托管，会被自动纠正。
改 image 会触发实例重建，升级大版本前务必先备份，并确认 MariaDB 的版本升级路径。
改 auth.existingSecret 前先确保新 Secret 存在：CR 中 generate: false，Secret 缺失时实例会拒绝启动而非自动生成密码。

6. 备份与恢复¶

6.1 当前备份策略¶

尚无自动备份。需要按下面的命令手工执行，建议至少每日一次，并在重大变更前必做。

备份内容：全库逻辑备份（含存储过程与事件）
建议落点：NFS 服务端本机目录 /srv/nfs/ 之外的独立路径，避免与数据库数据同盘同故障域；异地副本更佳
保留策略：至少保留 7 天，按日期命名

6.2 手工备份¶

# 全库逻辑备份，导出到 NFS 服务端（192.168.31.249）本机磁盘
kubectl -n server exec mariadb-0 -- env MYSQL_PWD="$MDB_ROOT_PW" \
  mariadb-dump -uroot --all-databases --single-transaction --routines --events --triggers \
  > /srv/backup/mariadb-full-$(date +%Y%m%d-%H%M%S).sql

# 校验：文件应非空，且结尾包含 "Dump completed"
ls -lh /srv/backup/mariadb-full-*.sql | tail -3
tail -1 /srv/backup/mariadb-full-*.sql

/srv/backup/ 若不存在需先创建（mkdir -p /srv/backup）；把备份留在数据库数据同一文件系统（/srv/nfs/k8s）会失去容灾意义。

仅备份业务库：

kubectl -n server exec mariadb-0 -- env MYSQL_PWD="$MDB_ROOT_PW" \
  mariadb-dump -uroot --single-transaction --routines --events slurm_acct_db \
  > /srv/backup/slurm_acct_db-$(date +%Y%m%d-%H%M%S).sql

已确认的能力缺口：当前 log_bin=0（二进制日志关闭），因此不具备时间点恢复（PITR）能力，最坏情况只能恢复到最近一次全量备份。

6.3 恢复¶

# 1) 恢复前先确认目标状态，并再备份一次现状（防误恢复）
kubectl -n server exec mariadb-0 -- env MYSQL_PWD="$MDB_ROOT_PW" \
  mariadb-dump -uroot --all-databases --single-transaction \
  > /srv/backup/before-restore-$(date +%Y%m%d-%H%M%S).sql

# 2) 导入全量备份（高危：会覆盖同名库表数据）
kubectl -n server exec -i mariadb-0 -- env MYSQL_PWD="$MDB_ROOT_PW" \
  mariadb -uroot < /srv/backup/mariadb-full-<时间戳>.sql

# 3) 恢复单库
kubectl -n server exec -i mariadb-0 -- env MYSQL_PWD="$MDB_ROOT_PW" \
  mariadb -uroot slurm_acct_db < /srv/backup/slurm_acct_db-<时间戳>.sql

恢复后验证：

kubectl -n server exec mariadb-0 -- env MYSQL_PWD="$MDB_ROOT_PW" \
  mariadb -uroot -e "SHOW DATABASES; SELECT COUNT(*) FROM slurm_acct_db.cluster_job_table;" 2>/dev/null

预期：库列表与导入前一致；关键表行数与备份时点相符。

6.4 演练记录¶

日期	内容	结果
—	尚未执行恢复演练	待办：建议在业务低峰期以单库为单位演练一次，验证备份可用

持久化实证（非演练，来自实际运行）：Pod 于 2026-09-19 13:38 重建过一次，重建前创建的 slurm_acct_db（09-18 05:43）、rain（09-18 14:53）在两个时间点之后依然存在，说明 NFS 持久化生效、Pod 重建不丢数据。

7. 监控与告警¶

7.1 当前状况¶

MariaDB 自身指标尚未接入监控。 现状如下：

能力	状态
Pod/STS 存活与重启	已有（kube-state-metrics 在 `monitoring` 命名空间，无需额外配置）
数据库内部指标（连接数、慢查询、InnoDB 状态）	未接入，CR 中未启用 `metrics`
告警规则	无数据库专属告警
日志	容器标准输出，见 4.3；未接入日志聚合

查看入口（如需在 Grafana 中确认集群整体状态）：

kubectl -n monitoring get svc | grep -E "grafana|prometheus|alertmanager"
# Grafana:    kube-prometheus-stack-grafana.monitoring.svc.cluster.local:80
# Prometheus: kube-prometheus-stack-prometheus.monitoring.svc.cluster.local:9090

7.2 建议补充的监控（属变更，需另行评估）¶

启用 operator 的 spec.metrics 以导出 mysqld-exporter 指标，并补充以下告警：实例 NotReady、Pod 重启次数增长、PVC 使用率 > 80%、NFS 服务端不可达、连接数接近 max_connections。

7.3 需要重点盯的信号¶

在监控补齐之前，靠下列命令人工巡检：

kubectl -n server get pod mariadb-0                # RESTARTS 是否增长
kubectl -n server exec mariadb-0 -- df -h /var/lib/mysql          # 数据盘使用率
kubectl -n server exec mariadb-0 -- env MYSQL_PWD="$MDB_ROOT_PW" \
  mariadb -uroot -e "SHOW STATUS LIKE 'Threads_connected'; SHOW STATUS LIKE 'Threads_running';"
kubectl -n server exec mariadb-0 -- env MYSQL_PWD="$MDB_ROOT_PW" \
  mariadb -uroot -e "SHOW STATUS LIKE 'Aborted_connects';"

阈值参考：Threads_connected 接近 max_connections（当前 151）即需关注；Aborted_connects 快速增长说明连接被拒或认证失败。

8. 故障处置¶

8.1 场景：Pod 反复重启或无法启动¶

症状：kubectl -n server get pod mariadb-0 显示 CrashLoopBackOff、Error 或长期 Pending；业务连接全失败。

诊断

# 1) 看 Pod 状态与最近一次重启原因
kubectl -n server describe pod mariadb-0 | sed -n '/State:/,/Events:/p'
#    预期：正常时无 Waiting/Last State 异常；异常时会显示 Reason（如 OOMKilled、Error）

# 2) 看容器日志尾部
kubectl -n server logs mariadb-0 --tail=50
#    预期：正常有 "ready for connections"；异常常见 "Can't open ... /var/lib/mysql"、"Permission denied"、"No space left"

# 3) 看事件
kubectl -n server get events --sort-by=.lastTimestamp | tail -20

# 4) 看存储是否正常绑定
kubectl -n server get pvc storage-mariadb-0
#    预期 Bound；若 Pending → NFS 侧问题，转向 8.3

处置

Reason=OOMKilled → 提高 values.yaml 中 limits.memory，重新 helm upgrade；同时确认是否有异常大查询。
日志出现 No space left on device → 见 8.4。
日志出现 NFS 相关报错或 describe 卡住不返回 → 见 8.3。
以上都不明确 → 先执行一次重建（kubectl -n server delete pod mariadb-0）观察是否自愈；仍失败则保留现场并升级处理。

验证

kubectl -n server wait --for=condition=Ready pod/mariadb-0 --timeout=280s
kubectl -n server exec mariadb-0 -- env MYSQL_PWD="$MDB_ROOT_PW" mariadb -uroot -e "SELECT 1;"

预期：Pod Ready，SELECT 1 返回 1。

8.2 场景：客户端连不上 / 认证失败¶

症状：应用报 Can't connect to server、Access denied for user、连接超时。

诊断

# 1) 服务与端点是否正常
kubectl -n server get svc mariadb
kubectl -n server get endpoints mariadb
#    预期：ClusterIP 10.110.57.41，endpoints 中有 10.244.x.x:3306（为空说明 Pod 未 Ready）

# 2) 服务端是否在监听
kubectl -n server exec mariadb-0 -- ss -lntp | grep 3306
#    预期：LISTEN 0 ... :3306

# 3) 账号与来源主机是否匹配
kubectl -n server exec mariadb-0 -- env MYSQL_PWD="$MDB_ROOT_PW" \
  mariadb -uroot -e "SELECT user,host FROM mysql.user;"
#    预期：含 root@% 与业务账号@%；缺少 % 通配会导致远程登录被拒

# 4) 认证错误计数
kubectl -n server exec mariadb-0 -- env MYSQL_PWD="$MDB_ROOT_PW" \
  mariadb -uroot -e "SHOW STATUS LIKE 'Aborted_connects';"

处置

endpoints 为空 → 先修 Pod（8.1）。
Access denied → 核对密码来源（第 2 章取用命令）；确认连接来源 IP 能被账号 host 覆盖；必要时用 root 重建业务账号。
服务端口正常但客户端超时 → 检查调用方网络策略、Traefik TCP 路由是否存在（kubectl -n server get ingressroutetcp mariadb）。

验证：从调用方实际执行一次连接，预期登录成功并 SELECT 1 返回。

8.3 场景：NFS 异常（挂载失败、IO 挂起、Stale file handle）¶

症状：数据库卡死无响应；Pod 日志出现 Stale file handle、Transport endpoint、not responding；df/ls 在容器内长时间不返回。

诊断

# 1) NFS 服务端是否存活（在能访问 192.168.31.249 的主机上执行）
ping -c 3 192.168.31.249
#    预期：有回包。无回包 → 服务端宕机或网络中断，直接进处置

# 2) 服务端共享是否正常导出
showmount -e 192.168.31.249
#    预期：列出 /srv/nfs/k8s

# 3) 服务端磁盘是否写满
df -h /srv/nfs/k8s
#    预期：Use% 未接近 100%

# 4) 容器内挂载点状态（注意：NFS 已经卡住时该命令也会卡住，需 Ctrl-C 退出）
timeout 10 kubectl -n server exec mariadb-0 -- mount | grep mysql

处置

先恢复 NFS 服务端（服务端在 192.168.31.249）：确认 nfs-server 进程与共享导出、磁盘空间、网络链路。
服务端恢复后，若容器内挂载仍不可用，重建 Pod 以重新挂载：

kubectl -n server delete pod mariadb-0        # 高危：会中断连接，需先确认服务端已恢复
kubectl -n server wait --for=condition=Ready pod/mariadb-0 --timeout=280s

若因数据文件损坏导致启动失败（日志报 InnoDB 相关错误），停止自动重试，保留 PVC，走备份恢复流程（6.3），并升级处理。

验证

kubectl -n server exec mariadb-0 -- df -h /var/lib/mysql       # 预期立即返回，非卡住
kubectl -n server exec mariadb-0 -- env MYSQL_PWD="$MDB_ROOT_PW" mariadb -uroot -e "SELECT 1;"

预期：命令秒回，查询正常。

8.4 场景：数据盘写满 / 需要扩容¶

症状：写入报 Disk full / No space left on device；insert 失败。

诊断

# 1) 容器内数据盘水位
kubectl -n server exec mariadb-0 -- df -h /var/lib/mysql
#    预期：Use% < 80%

# 2) 数据库实际占用与最大的库
kubectl -n server exec mariadb-0 -- du -sh /var/lib/mysql
kubectl -n server exec mariadb-0 -- env MYSQL_PWD="$MDB_ROOT_PW" \
  mariadb -uroot -e "SELECT table_schema, ROUND(SUM(data_length+index_length)/1024/1024,1) AS mb FROM information_schema.tables GROUP BY table_schema ORDER BY mb DESC;"

# 3) NFS 服务端整体水位
df -h /srv/nfs/k8s

处置

先清理可安全释放的空间（过期日志表、临时表、已完成归档的历史数据），清理前务必确认可删。
需要扩容时，PVC 与存储类均支持在线扩容：

# 修改 values.yaml 中 storage.size（如 20Gi -> 40Gi）后
cd mariadb-deploy && helm upgrade --install mariadb ./charts/mariadb -n server
kubectl -n server get pvc storage-mariadb-0       # 预期 CAPACITY 变为新值，STATUS 仍 Bound
kubectl -n server exec mariadb-0 -- df -h /var/lib/mysql

若 NFS 服务端本身空间不足，需先在服务端扩容后重试。

验证：df 显示新容量且 Use% 回落；执行一次写入测试（CREATE TABLE + INSERT + DROP）成功。

8.5 场景：Pod 被重建后担心数据丢失¶

症状：Pod 名相同但 AGE 归零、节点发生变化，担心数据没了。

诊断

# 1) Pod 创建时间与 PVC 绑定关系
kubectl -n server get pod mariadb-0 -o jsonpath='{.metadata.creationTimestamp} node={.spec.nodeName}{"\n"}'
kubectl -n server get pvc storage-mariadb-0        # 预期仍为 Bound，AGE 未重置

# 2) 数据目录仍在
kubectl -n server exec mariadb-0 -- ls /var/lib/mysql
kubectl -n server exec mariadb-0 -- env MYSQL_PWD="$MDB_ROOT_PW" mariadb -uroot -e "SHOW DATABASES;"

处置：PVC 未重建则数据未丢，无需处置。只有当 PVC 被删除时才发生数据丢失（nfs-csi 的 PV 回收策略为 Delete）。

验证：SHOW DATABASES 与重建前一致；关键表行数正常。

9. 安全与权限¶

账号模型：root@% 可远程登录，权限最大；业务账号按库授权。当前无独立审计账号。
凭据存储：root 密码存放于 Secret server/mariadb-root（etcd 中为 base64，非加密），取用方式见第 2 章。密码不入文档、不入 Git。
传输加密：operator 默认启用实例 TLS（自签），Webhook 证书由 cert-controller 自动签发与轮换。
轮换 root 密码：

kubectl -n server patch secret mariadb-root --type=merge \
  -p "{\"data\":{\"password\":\"$(printf '<新密码>' | base64 -w0)\"}}"    # 高危：替换凭据，请从密码管理系统取值
kubectl -n server rollout restart sts/mariadb          # Secret 变更不会自动生效，必须重启
kubectl -n server wait --for=condition=Ready pod/mariadb-0 --timeout=280s

轮换后需同步更新所有调用方配置，并验证连接：

export MDB_ROOT_PW="$(kubectl -n server get secret mariadb-root -o jsonpath='{.data.password}' | base64 -d)"
kubectl -n server exec mariadb-0 -- env MYSQL_PWD="$MDB_ROOT_PW" mariadb -uroot -e "SELECT 1;"

访问控制：集群侧由 RBAC 控制谁可读取该 Secret；数据库侧建议为业务方分配最小权限账号，避免共用 root。
风险提示：root@% 允许任意来源以 root 登录，建议后续收紧为指定网段。

10. 容量与性能¶

10.1 当前水位基线（2026-09-19 采集）¶

指标	数值
CPU 使用	29m（requests 200m）
内存使用	124Mi（requests 512Mi / limits 2Gi）
数据目录占用	159M
PVC	20Gi，Bound
NFS 后端	118G 总量，已用 212M，可用 112G（1%）
`max_connections`	151（镜像默认）
`innodb_buffer_pool_size`	128M（镜像默认，对超过数 GB 的数据集偏小）
`max_allowed_packet`	16M
`log_bin`	关闭
字符集 / 排序规则	`utf8mb4` / `utf8mb4_uca1400_ai_ci`

10.2 扩容触发条件与操作¶

触发条件	操作
数据盘 Use% > 80%	扩容 PVC（见 8.4）
`Threads_connected` 长期 > 120（接近 151）	调大 `max_connections`（写入 `values.yaml` 的 `myCnf`）并评估内存上限
内存接近 limit（2Gi）或出现 OOMKilled	提高 `limits.memory`
慢查询增多、buffer pool 命中率下降	调大 `innodb_buffer_pool_size`（`myCnf`），建议为可用内存的 50%~70%

调整 myCnf 示例（写入 mariadb-deploy/charts/mariadb/values.yaml）：

myCnf: |
  [mysqld]
  max_connections=300
  innodb_buffer_pool_size=1G

改后 helm upgrade 会滚动重建 Pod，单实例场景有短暂中断。

10.3 已知瓶颈与优化方向¶

NFS 作为数据库后端：无本地块设备的 fsync 语义，高并发写入时延迟抖动明显。当前为中小负载可接受；若要跑重负载，建议迁至块存储或集群内的 local-ssd（需接受单节点绑定）。
单实例无冗余：无副本、无自动故障转移，节点或 NFS 故障期间服务中断。
buffer pool 偏小：128M 默认值在数据增长后会成为瓶颈，属可预期的性能拐点。
无 binlog：无法做 PITR，也无法搭建从库；如需高可用或精细恢复，需先开启 binlog。
磁盘同故障域：若把备份也放在 /srv/nfs/k8s 所在文件系统，会与服务端故障一起丢失，务必分离。

11. 附录¶

11.1 术语表¶

术语	含义
CR / CRD	自定义资源 / 自定义资源定义，本服务用 `MariaDB` CR 声明实例
operator	监听 CR 并自动生成、修复工作负载的控制器
PVC / PV	持久卷声明 / 持久卷；PVC 删除时 PV 回收策略为 `Delete`，数据随之丢失
StorageClass	存储类，本服务使用 `nfs-csi`（NFS CSI 驱动提供）
PITR	时间点恢复，依赖 binlog，当前不具备

11.2 相关文档与交付物¶

文件	用途
`mariadb-deploy/SOP.md`	本次部署的变更档案（背景、步骤、验证、回滚、风险）
`mariadb-deploy/charts/mariadb/values.yaml`	实例唯一配置入口
`mariadb-deploy/charts/mariadb/templates/mariadb.yaml`	实例 CR 模板

11.3 关键信息速记¶

项	值
实例 CR	`server/mariadb`
Pod	`server/mariadb-0`
Service	`server/mariadb`（ClusterIP 10.110.57.41:3306）、`server/mariadb-internal`（headless）
PVC	`server/storage-mariadb-0`（20Gi，nfs-csi）
root Secret	`server/mariadb-root`（键 `password`）
控制器命名空间	`mariadb-system`
NFS 后端	`192.168.31.249:/srv/nfs/k8s`
已存在业务库	`slurm_acct_db`、`rain`

11.4 修订记录¶

日期	修改人	变更内容
2026-09-19	运维	首次成文：覆盖服务概览、接入、速查、日常操作、配置、备份恢复、监控、故障处置、安全、容量

来源：/home/rain/Documents/k8s_ins/mariadb-deploy/RUNBOOK.md ｜最后更新：2026-09-19 16:46（由 build/sync.py 同步，请勿在站点侧修改）