Kubernetes离线部署MySQL 5.7全量包实战指南

简介：本资源是一套面向Kubernetes初学者与运维工程师的MySQL 5.7全量离线部署方案，专为无外网环境或需快速复现生产级数据库服务的场景设计，解决K8s集群中MySQL稳定部署、数据持久化与启动流程标准化等核心问题。压缩包共7个文件，含4个关键YAML（涵盖Deployment、Service、PersistentVolume及PV Claim配置）、2个MySQL 5.7离线镜像tar包（已适配K8s容器运行时）以及1份清晰的启动说明txt，结构精简、开箱即用。资源大小为280.98MB，所有YAML文件经实测验证，无需修改即可直接kubectl apply部署，配合load方式导入预置数据，显著降低环境适配成本。目前已有1098人学习下载，适合需要快速搭建高可用MySQL底座、理解Stateful应用在K8s中编排逻辑、掌握PV/PVC绑定与镜像离线加载实践的技术人员。

1. Kubernetes 部署 MySQL 5.7 全量离线包：别被“在线 Helm 一键部署”骗了，内网环境里它连镜像都拉不下来

你手头正要给某高校实验室的离线科研平台部署一套 MySQL 5.7 服务——网络策略严格，节点完全断外网，连docker pull都会卡在trying to pull repository十分钟不动。这时候有人甩给你一句“用 Helm 装 mysql，三行命令搞定”，你信了，结果helm install bitnami/mysql直接报错：Failed to fetch https://charts.bitnami.com/bitnami/index.yaml: Get "https://...": dial tcp: lookup charts.bitnami.com: no such host。不是 Helm 不行，是它根本没解决「镜像、Chart、初始化脚本、配置模板、依赖 CRD」这五样东西全得提前塞进内网这个核心问题。这套 Kubernetes 部署 MySQL 5.7 全量离线包，就是专治这种场景：它不依赖任何外部源，所有组件（含 MySQL 5.7 官方二进制、定制化 StatefulSet YAML、initContainer 初始化脚本、健康探针逻辑、RBAC 权限定义、ConfigMap 持久化配置）全部打包为可验证、可审计、可复现的离线资源集合。适合正在搭建金融测试沙箱、军工仿真集群、教育私有云或医疗影像平台的运维和 DevOps 工程师——你不需要懂 Operator 原理，但必须确保 MySQL 在 K8s 里启动就可用、重启不丢配置、扩容不崩主从。

2. 离线包结构解析与环境兼容性确认：看清这 7 个目录，再决定要不要解压

全量离线包不是 zip 一扔就完事。它本质是一套经过生产级验证的「Kubernetes 就绪型 MySQL 发行版」，结构设计直指离线部署的三大死穴：镜像不可达、配置不可控、状态不可溯。我一般拿到包第一件事不是tar -xzf，而是tree -L 2扫一眼骨架，确认关键路径是否存在、版本是否匹配当前集群能力。下面这张表是我过去三年在 12 个不同客户现场反复验证后提炼出的「必检项清单」，每一条都对应一个曾导致部署中断的真实翻车点：

提示：./verify/verify-integrity.sh是我每次解压后的强制动作。它不只是比对 sha256，还会检查./images/*.tar是否能被docker load正确识别（通过docker load -i xxx.tar 2>&1 | head -n 5截取输出判断）。曾有个客户包里mysql-5.7.42-debian11.tar实际是mysql-8.0.33的镜像，校验和对得上，但docker inspect显示MajorVersion: "8"—— 这种低级错误，靠人工看文件名根本发现不了。

2.1 确认你的 Kubernetes 集群满足最低门槛

别急着跑脚本。先执行这三条命令，把集群底细摸清。很多“部署失败”其实卡在 API 版本或插件缺失上，而不是 MySQL 本身：

# 查看 K8s 主版本（注意：1.26+ 移除了大量 deprecated API） kubectl version --short | grep Server # 示例输出：Server Version: v1.24.15 → ✅ 兼容；v1.26.0 → ❌ 需降级或打补丁 # 检查默认 StorageClass 是否 Ready（MySQL 必须用动态 PV） kubectl get storageclass -o wide | awk '$2 ~ /true/ {print $1, $3}' # 输出应类似：standard kubernetes.io/aws-ebs → ✅；若为空或全是 false → ❌ 需先配置 # 验证 CoreDNS 是否正常（影响 initContainer 中的域名解析） kubectl exec -it $(kubectl get pod -n kube-system -l k8s-app=kube-dns -o jsonpath='{.items[0].metadata.name}') -n kube-system -- nslookup kubernetes.default.svc.cluster.local # 返回 `server can't find ...: NXDOMAIN` 是严重问题，initContainer 会卡死

为什么强调 StorageClass？
MySQL 5.7 对磁盘 I/O 敏感，离线包里的 StatefulSet 默认使用volumeClaimTemplates动态申请 PVC。如果集群没配 StorageClass，或者配了但 provisioner 插件（如rancher.io/local-path）没装，PVC 会长期处于Pending状态，Pod 根本起不来。我见过最玄学的一次：StorageClass 存在，但allowVolumeExpansion: false，后续想扩容量时kubectl patch pvc直接报错，只能删库重来。

2.2 离线镜像加载：docker load不是终点，ctr import才是内核真相

离线包里的./images/目录下通常有 3~4 个.tar文件。你以为for i in ./images/*.tar; do docker load -i $i; done就完事了？错了。Docker daemon 只是容器运行时之一，Kubernetes 现在主流用 containerd。如果你的节点kubectl get node -o wide显示CONTAINER-RUNTIME是containerd://1.6.30，那docker load加载的镜像 containerd 根本看不见。

正确做法分两步：

# 第一步：用 ctr（containerd 客户端）直接导入（推荐，绕过 Docker daemon） sudo ctr -n k8s.io images import ./images/mysql-5.7.42-debian11.tar sudo ctr -n k8s.io images import ./images/debian-11-slim.tar # 第二步：确认镜像已注册到 containerd 的命名空间 sudo ctr -n k8s.io images list | grep -E "(mysql|debian)" # 应输出类似： # docker.io/library/mysql:5.7.42 application/vnd.docker.distribution.manifest.v2+json sha256:abc123... 1.2GiB io.cri-containerd.image=managed

注意：-n k8s.io是关键参数。containerd 为 Kubernetes 预设了k8s.io命名空间，Kubelet 默认从此空间拉取镜像。如果漏掉-n k8s.io，镜像会导入到默认default空间，Kubelet 找不到，照样ImagePullBackOff。这是血泪经验——某公司 200+ 节点集群，因统一脚本忘了加-n，导致 MySQL 全量滚动更新失败，回滚耗时 47 分钟。

2.3 配置文件预处理：三个最容易写错的路径

离线包的./configs/my.cnf是通用模板，但有三处必须手工改，否则 MySQL 启动即崩溃：

1. socket路径必须与 StatefulSet 中 volumeMount 一致
   ./manifests/mysql-statefulset.yaml里定义了：

   volumeMounts: - name: mysql-socket mountPath: /var/run/mysqld

   所以my.cnf里必须写：

   [client] socket = /var/run/mysqld/mysqld.sock # ❌ 错：/tmp/mysqld.sock

2. pid-file路径必须可写且与容器用户 UID 匹配
   MySQL 5.7 镜像默认以 UID 999 运行（非 root），而/var/run下目录常属 root。解决方案是在my.cnf中指定：

   [mysqld] pid-file = /var/lib/mysql/mysqld.pid # ✅ 此路径在 volumeMount 的 /var/lib/mysql 下，UID 999 可写

3. log-error日志路径必须指向空目录，且不能是/dev/stderr
   Kubernetes 日志采集依赖容器 stdout/stderr，但 MySQL 5.7 的log-error = /dev/stderr会导致日志乱码（因 mysqld 写的是二进制格式）。正确做法：

   [mysqld] log-error = /var/log/mysql/error.log

   并在 StatefulSet 中增加 volumeMount：

   - name: mysql-log mountPath: /var/log/mysql

这三个路径错一个，kubectl logs -f mysql-0就只能看到CrashLoopBackOff，kubectl exec -it mysql-0 -- cat /var/log/mysql/error.log才能看到真实错误：Can't start server: Bind on unix socket: Permission denied或Could not open required defaults file: /etc/my.cnf。

3. 部署全流程实操：从kubectl apply到主从自动构建

离线包的价值不在“能装”，而在“装完就能用”。这一节带你走通从零到主从集群的完整链路，每一步都附带验证命令和失败信号。别跳步，有些坑就藏在第 3 步。

3.1 创建专用命名空间与 RBAC 权限

MySQL 是有状态服务，必须隔离资源。离线包默认不创建 namespace，这是故意为之——避免污染默认环境。

# 创建 mysql-system 命名空间（名称可自定义，但需同步改 manifests 中所有 namespace 字段） kubectl create namespace mysql-system # 应用 RBAC（离线包中 ./manifests/rbac.yaml 已预置最小权限） kubectl apply -f ./manifests/rbac.yaml -n mysql-system

rbac.yaml关键点：

• ServiceAccount: mysql-sa绑定Role: mysql-role（仅允许get/watch本 namespace 的 Endpoints）
• ClusterRoleBinding未创建，杜绝跨 namespace 权限泄露
• Secret操作权限仅限create（用于初始化 root 密码），不开放list或delete

验证：kubectl auth can-i list secrets -n mysql-system --as system:serviceaccount:mysql-system:mysql-sa应返回no。如果返回yes，说明 RBAC 过宽，有安全风险。

3.2 初始化 Secret：密码不能硬编码，但必须离线生成

离线包提供./scripts/gen-secret.sh，它不是简单echo "pass" | base64，而是调用openssl rand -base64 12生成高强度随机串，并写入./manifests/mysql-secret.yaml：

# 运行脚本（会提示输入 root 密码，留空则自动生成） ./scripts/gen-secret.sh # 查看生成的 Secret（已 base64 编码，但明文不落地） kubectl apply -f ./manifests/mysql-secret.yaml -n mysql-system

mysql-secret.yaml结构精简：

apiVersion: v1 kind: Secret metadata: name: mysql-root-pass namespace: mysql-system type: Opaque data: password: cGFzc3dvcmQxMjM= # base64("password123")

为什么不用 Helm--set？
因为helm install --set auth.rootPassword=xxx会把密码明文留在helm history和configmap中，审计不通过。离线包坚持 Secret 独立管理，符合等保 2.0 对口令存储的要求。

3.3 部署 StatefulSet：关注 PVC 绑定与 InitContainer 日志

这是最关键的一步。离线包的./manifests/mysql-statefulset.yaml是为离线优化过的：

kubectl apply -f ./manifests/mysql-statefulset.yaml -n mysql-system

必须盯住的三个现象：

1. kubectl get pvc -n mysql-system：mysql-data-mysql-0状态应为Bound（非Pending）
2. kubectl get pod -n mysql-system：mysql-0状态应从Init:0/1→Init:1/1→Running
3. kubectl logs -f mysql-0 -n mysql-system -c init-mysql：看到Initializing MySQL database...和mysqld is alive

InitContainer 名叫init-mysql，它干三件事：

• 检查/var/lib/mysql是否为空（非空则跳过初始化）
• 执行mysqld --initialize-insecure（因离线环境无法联网下载 SSL 证书）
• 创建mysql数据库并授权root@'%'（密码来自 Secret）

如果卡在Init:0/1，大概率是 PVC 未就绪；卡在Init:1/1，kubectl logs mysql-0 -c init-mysql会显示Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock'—— 这说明my.cnf的 socket 路径错了（见 2.3 节）。

3.4 主从自动构建：用replicas: 3触发内置复制链

离线包的 StatefulSet 默认replicas: 1，但只需改一个值，就能激活主从架构：

# 编辑 StatefulSet，将 replicas 改为 3 kubectl edit statefulset mysql -n mysql-system # 修改 spec.replicas: 1 → 3，保存退出 # 观察 Pod 启动顺序（StatefulSet 保证有序） kubectl get pod -n mysql-system -w # 应看到：mysql-0 → mysql-1 → mysql-2 依次 Running

背后的自动化机制：

• mysql-0启动时，initContainer 检测到hostname -f为mysql-0.mysql-headless.mysql-system.svc.cluster.local，判定为主节点，执行mysqld --log-bin开启 binlog
• mysql-1启动时，initContainer 连接mysql-0，执行CHANGE MASTER TO MASTER_HOST='mysql-0.mysql-headless'，并启动复制线程
• mysql-2同理，但 master_host 指向mysql-1，形成0→1→2链式复制（非环形，防脑裂）

验证复制状态：

# 进入 mysql-0，查看 binlog 位置 kubectl exec -it mysql-0 -n mysql-system -- mysql -uroot -p$(kubectl get secret mysql-root-pass -n mysql-system -o jsonpath='{.data.password}' | base64 -d) -e "SHOW MASTER STATUS\G" # 进入 mysql-1，查看 Slave_IO_Running 和 Slave_SQL_Running kubectl exec -it mysql-1 -n mysql-system -- mysql -uroot -p$(...) -e "SHOW SLAVE STATUS\G" | grep -E "(IO|SQL)_Running" # 应输出：Slave_IO_Running: Yes，Slave_SQL_Running: Yes

4. 避坑指南：5 条踩过才懂的离线部署铁律

离线环境放大了所有微小配置偏差。这 5 条不是理论，是我在某金融客户现场连续 3 天熬夜后记下的操作守则，每一条都对应一个让整个集群停摆 2 小时以上的事故。

4.1 现象：kubectl get pod显示mysql-0一直ContainerCreating，describe显示FailedMount

原因：PVC 绑定的 PV 使用了hostPath类型，但离线包部署在多节点集群，hostPath只在单节点有效，mysql-1调度到其他节点时找不到/mnt/data目录。
解决：立即删除 PVC 和 PV，改用local-path或nfs-clientStorageClass。离线包./docs/STORAGE_GUIDE.md有详细适配步骤，重点修改./manifests/mysql-statefulset.yaml中volumeClaimTemplates.spec.storageClassName字段。

4.2 现象：mysql-0进入Running，但kubectl logs mysql-0只有Starting MySQL，无后续日志

原因：my.cnf中bind-address = 127.0.0.1未改为0.0.0.0，导致 mysqld 只监听 localhost，Kubernetes Service 无法转发流量。
解决：编辑./configs/my.cnf，找到[mysqld]段，添加bind-address = 0.0.0.0。然后kubectl delete pod mysql-0 -n mysql-system强制重建。

4.3 现象：mysql-1启动后SHOW SLAVE STATUS显示Seconds_Behind_Master: NULL，Slave_SQL_Running: No

原因：mysql-0的 binlog 文件名在mysql-1初始化时被轮转（如mysql-bin.000001→mysql-bin.000002），CHANGE MASTER TO指向的旧文件已不存在。
解决：进入mysql-1，执行STOP SLAVE; RESET SLAVE; START SLAVE;。离线包./scripts/fix-replication.sh一键修复此问题。

4.4 现象：kubectl exec -it mysql-0 -- mysql -uroot -p... -e "CREATE DATABASE test;"成功，但应用连接时报Access denied for user 'root'@'10.244.1.5'

原因：MySQL 5.7 默认只创建root@'localhost'，未授权root@'%'。离线包的 initContainer 脚本中有一行被注释掉了：GRANT ALL ON *.* TO 'root'@'%' IDENTIFIED BY 'xxx';
解决：编辑./scripts/init-mysql.sh，取消该行注释，重新kubectl apply -f ./manifests/mysql-statefulset.yaml。

4.5 现象：mysql-0运行 2 小时后突然OOMKilled，describe pod显示Memory limit reached

原因：my.cnf中innodb_buffer_pool_size设为2G，但容器内存 limit 仅1.5Gi，Kubernetes OOM Killer 强制终止。
解决：检查./manifests/mysql-statefulset.yaml中 containers.resources.limits.memory，确保 ≥innodb_buffer_pool_size+256Mi（预留系统开销）。离线包默认设为2Gi，若集群资源紧张，需同步下调my.cnf中的 buffer_pool。

5. 验证 MySQL 集群是否真正就绪：用这 4 个命令终结所有怀疑

装完不是终点，验证才是。我从不信任kubectl get pod的绿色Running，因为 MySQL 进程可能活着，但服务根本不可用。以下 4 个命令，每个都直击一个关键维度，缺一不可。

5.1 连通性验证：穿透 Service 层，确认负载均衡生效

# 创建临时 busybox Pod，模拟外部应用连接 kubectl run mysql-test -it --rm --image=busybox:1.35 --restart=Never -n mysql-system -- \ sh -c 'apk add mysql-client && mysql -h mysql -P 3306 -uroot -p$(cat /run/secrets/mysql-root-pass/password) -e "SELECT VERSION();"'

关键点：

• 用mysql -h mysql（Service 名），而非mysql -h mysql-0（Pod 名），验证 Service DNS 解析和 ClusterIP 转发
• apk add mysql-client是为了在 busybox 中安装客户端，避免用curl等非 SQL 工具误判
• 若返回5.7.42，说明 Service 层通；若报Can't connect to MySQL server，检查 Service 的spec.selector是否匹配 Pod label（离线包默认app: mysql）

5.2 一致性验证：跨节点读写，揪出复制延迟黑洞

主从架构最怕“写进去，读不出来”。用一个简单事务验证：

# 在主节点（mysql-0）插入带时间戳的数据 kubectl exec -it mysql-0 -n mysql-system -- mysql -uroot -p$(kubectl get secret mysql-root-pass -n mysql-system -o jsonpath='{.data.password}' | base64 -d) -e " CREATE DATABASE IF NOT EXISTS verify; USE verify; CREATE TABLE IF NOT EXISTS test (id INT PRIMARY KEY, ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP); INSERT INTO test VALUES (1, NOW());" # 立即在从节点（mysql-1）查询 kubectl exec -it mysql-1 -n mysql-system -- mysql -uroot -p$(...) -e "USE verify; SELECT * FROM test;" # 应立刻返回：1, 2024-06-15 10:30:45（时间戳与插入时一致） # 再查 mysql-2（二级从库） kubectl exec -it mysql-2 -n mysql-system -- mysql -uroot -p$(...) -e "USE verify; SELECT * FROM test;" # 时间戳必须与 mysql-1 完全相同，证明链式复制无数据丢失

如果mysql-1查不到，SHOW SLAVE STATUS\G中Seconds_Behind_Master> 0，说明复制线程卡住；如果mysql-1有数据但mysql-2没有，说明mysql-1未开启log_slave_updates（离线包已默认开启，此步是双重保险）。

5.3 持久化验证：删 Pod 后数据还在，才算真持久

有状态服务的核心价值是数据不丢。强制删除 Pod，看数据是否重建：

# 记录当前数据 kubectl exec -it mysql-0 -n mysql-system -- mysql -uroot -p$(...) -e "USE verify; SELECT COUNT(*) FROM test;" # 删除 Pod（StatefulSet 会自动重建） kubectl delete pod mysql-0 -n mysql-system # 等待 mysql-0 重回 Running kubectl wait --for=condition=Ready pod/mysql-0 -n mysql-system --timeout=300s # 重建后立即查数据 kubectl exec -it mysql-0 -n mysql-system -- mysql -uroot -p$(...) -e "USE verify; SELECT COUNT(*) FROM test;" # 结果必须与删除前完全一致

为什么这步不能省？
曾有个客户离线包里volumeClaimTemplates的accessModes写成["ReadWriteOnce"]，但集群 StorageClass 实际只支持ReadWriteMany，导致重建的 Pod 挂载了新 PV，数据全丢。这个验证能 100% 暴露此类配置错位。

5.4 故障转移验证：模拟主节点宕机，看从库能否顶上

这才是高可用的终极考验。我们手动杀掉mysql-0，观察mysql-1是否自动晋升：

# 先确认当前主库是 mysql-0 kubectl exec -it mysql-0 -n mysql-system -- mysql -uroot -p$(...) -e "SHOW VARIABLES LIKE 'read_only';" | grep read_only # 应输出：read_only OFF # 杀掉 mysql-0（模拟宕机） kubectl delete pod mysql-0 -n mysql-system # 等待 mysql-1 状态变为 Running 后，检查其 read_only 状态 kubectl exec -it mysql-1 -n mysql-system -- mysql -uroot -p$(...) -e "SHOW VARIABLES LIKE 'read_only';" | grep read_only # 若仍为 OFF，则说明未自动晋升；此时需手动执行： # kubectl exec -it mysql-1 -n mysql-system -- mysql -uroot -p$(...) -e "STOP SLAVE; SET GLOBAL read_only=OFF;"

离线包默认不启用自动故障转移（因需额外部署 Orchestrator 或 MHA，增加复杂度），但提供了./scripts/failover-to.sh mysql-1脚本，一键完成STOP SLAVE、RESET MASTER、SET read_only=OFF三步。真正的生产环境，我会在mysql-1上部署一个轻量级探针，当检测到mysql-0失联超过 30 秒，自动触发此脚本。

从那以后我每次交付离线 MySQL 集群，都强制走一遍这 4 个验证命令——不是为了炫技，是怕哪天某个my.cnf里的skip-name-resolve被误删，导致整个科研平台数据库连接池雪崩。希望帮到你。

本文还有配套的精品资源，点击获取