简介这份资源面向需要在 Kubernetes 上部署 Nacos 集群的运维与后端开发人员尤其适合刚接触 K8s 编排、希望跳过繁琐配置直接跑通集群的初学者。它把 Nacos 集群部署拆解为按执行顺序排列的极简脚本覆盖数据库配置、Headless Service、StatefulSet、Service 以及 Ingress 暴露等关键环节省去大量手工调试成本。压缩包共 6 个文件以 5 个 yaml 清单为主分别承担数据库连接、无头服务、有状态副本集、服务暴露与外部访问入口等职责另附 1 个 txt 说明文件整体仅约 3KB轻量易读。目前已有 761 人学习下载说明该方案在实际部署场景中具备一定参考价值。读者可据此快速搭建可用的 Nacos 集群环境理解各资源对象的先后依赖关系并在此基础上按需调整副本数、存储与域名配置减少从零编写清单的试错时间。1. 从一堆散装 YAML 到能扛住重启的 Nacos 集群这套脚本到底在解决什么很多人第一次在 k8s 上部署 Nacos都是先kubectl apply一个官方示例跑起来看到 Pod 是 Running 就以为完事了。结果服务一重启配置丢了节点一扩容集群选主乱了生产环境一压测注册中心直接脑裂。问题的根子不在 Nacos 本身而在于那堆散装的 YAML 没有把「集群」两个字当回事——StatefulSet 的稳定网络标识、持久化存储的挂载路径、MySQL 外置数据源的连接池参数、JVM 堆内存与容器 limit 的匹配关系任何一项没对齐集群就是纸糊的。这篇笔记要拆的就是一套能直接抄作业的 k8s Nacos 集群部署脚本与 YAML 组合。它解决的不是「能不能跑起来」而是「跑起来之后能不能扛住滚动更新、节点故障和配置热更新」。适合已经会用 kubectl、懂一点 StatefulSet 和 Service 概念但还没在生产环境把 Nacos 集群真正落地的后端或运维工程师。如果你正在搜 k8s 部署教程、nacos 集群部署脚本或者纠结 consul 和 nacos 的区别到底该选哪个下面的内容会从 YAML 的每一段参数讲起把踩过的坑和验证方法一并交代清楚。2. 为什么 Nacos 集群在 k8s 上必须用 StatefulSet 而不是 Deployment2.1 从 Nacos 的集群寻址机制倒推工作负载选型Nacos 集群节点之间需要互相感知靠的是cluster.conf里写死的节点列表或者环境变量nacos.member.list指定的地址。每个节点启动时要知道其他节点的 IP 或域名才能组成 Raft 集群完成选主和数据同步。Deployment 创建的 Pod 名字是随机哈希重启后 IP 变了、名字也变了cluster.conf根本没法维护一个稳定的成员列表。StatefulSet 给每个 Pod 分配固定的序号和稳定的 DNS 域名比如nacos-0.nacos-headless.default.svc.cluster.local这样cluster.conf里写域名就能长期有效节点重启后重新注册到同一个域名上集群成员关系不会乱。另一个关键点是存储。Nacos 默认用内嵌 Derby 数据库单机没问题集群模式下必须外置 MySQL。但即便如此每个 Nacos 节点本地还有data目录用于存储 Raft 日志和快照。如果用 Deployment 加 emptyDirPod 一漂移日志就没了节点重新加入集群时可能因为日志缺失导致数据不一致。StatefulSet 配合 volumeClaimTemplates 给每个 Pod 挂一块独立的 PVCRaft 日志和本地缓存才能持久化这是集群稳定性的底线。2.2 一个最小可用的 StatefulSet YAML 骨架与逐段拆解下面这份 YAML 是我在多个环境里收敛出来的骨架去掉了花哨的 sidecar只保留 Nacos 集群运行必需的部分。注意看serviceName、podManagementPolicy和volumeClaimTemplates这三处它们是 StatefulSet 区别于 Deployment 的核心。apiVersion: apps/v1 kind: StatefulSet metadata: name: nacos namespace: middleware spec: serviceName: nacos-headless # 必须指向 Headless Service否则 Pod 没有稳定 DNS replicas: 3 # 集群节点数生产建议 3 或 5 podManagementPolicy: Parallel # 并行启动加快集群组建速度 selector: matchLabels: app: nacos template: metadata: labels: app: nacos spec: affinity: podAntiAffinity: # 反亲和尽量把 Pod 打散到不同节点 preferredDuringSchedulingIgnoredDuringExecution: - weight: 100 podAffinityTerm: labelSelector: matchLabels: app: nacos topologyKey: kubernetes.io/hostname containers: - name: nacos image: nacos/nacos-server:v2.3.2 # 版本按需替换不要用 latest env: - name: MODE value: cluster # 必须显式声明集群模式 - name: NACOS_SERVERS value: nacos-0.nacos-headless.middleware.svc.cluster.local:8848 nacos-1.nacos-headless.middleware.svc.cluster.local:8848 nacos-2.nacos-headless.middleware.svc.cluster.local:8848 - name: SPRING_DATASOURCE_PLATFORM value: mysql # 使用外置 MySQL - name: MYSQL_SERVICE_HOST value: mysql.middleware.svc.cluster.local - name: MYSQL_SERVICE_PORT value: 3306 - name: MYSQL_SERVICE_DB_NAME value: nacos_config - name: MYSQL_SERVICE_USER value: nacos - name: MYSQL_SERVICE_PASSWORD value: nacos_password - name: JVM_XMS value: 2g # 堆初始值与 limit 保持比例 - name: JVM_XMX value: 2g # 堆最大值建议不超过 limit 的 70% - name: JVM_XMN value: 1g # 新生代约为 Xmx 的一半 ports: - containerPort: 8848 # 主服务端口 - containerPort: 9848 # gRPC 端口2.x 必须暴露 - containerPort: 9849 # gRPC 端口2.x 必须暴露 volumeMounts: - name: nacos-data mountPath: /home/nacos/data # Raft 日志和本地缓存 - name: nacos-logs mountPath: /home/nacos/logs # 日志持久化方便排查 readinessProbe: tcpSocket: port: 8848 initialDelaySeconds: 30 periodSeconds: 10 livenessProbe: tcpSocket: port: 8848 initialDelaySeconds: 60 periodSeconds: 20 volumeClaimTemplates: - metadata: name: nacos-data spec: accessModes: [ReadWriteOnce] storageClassName: standard # 按集群实际 StorageClass 替换 resources: requests: storage: 10Gi - metadata: name: nacos-logs spec: accessModes: [ReadWriteOnce] storageClassName: standard resources: requests: storage: 5Gi这份 YAML 里最容易被忽略的是NACOS_SERVERS环境变量。Nacos 2.x 官方镜像支持用这个变量直接生成cluster.conf省去手动挂 ConfigMap 的麻烦。但要注意变量里的域名必须和 Headless Service 的命名规则完全一致格式是pod-name.service-name.namespace.svc.cluster.local。如果 namespace 写错或者 serviceName 对不上节点之间就互相找不到日志里会一直刷failed to connect to server。podManagementPolicy: Parallel是为了让三个 Pod 同时启动而不是等前一个 Ready 再起下一个。Nacos 集群需要多数节点在线才能完成选主串行启动会导致第一个 Pod 一直卡在选主阶段直到第二个 Pod 起来才能继续白白拉长部署时间。并行启动配合就绪探针能让集群更快进入可用状态。资源限制方面JVM_XMS和JVM_XMX建议设成一样避免堆动态伸缩带来的性能抖动。JVM_XMN设为Xmx的一半左右这是 Nacos 官方推荐的配比。如果容器 limit 设了 4Gi堆最大给 2.5Gi 到 3Gi 比较稳妥留出堆外内存给 gRPC 和 Netty 的直接缓冲区。见过太多因为堆内存超过 limit 导致 Pod 被 OOMKilled 的案例重启后集群重新选主业务侧注册列表瞬间清空这就是典型的「翻车」现场。3. Headless Service 与 MySQL 外置数据源的 YAML 配置细节3.1 Headless Service 的 YAML 写法与 DNS 验证方法StatefulSet 的serviceName指向的 Headless Service 必须单独创建它的clusterIP: None是硬性要求。没有这行k8s 会给 Service 分配一个虚拟 IPPod 的 DNS 解析就变成负载均衡地址而不是具体的 Pod 域名StatefulSet 的稳定网络标识就失效了。apiVersion: v1 kind: Service metadata: name: nacos-headless namespace: middleware labels: app: nacos spec: clusterIP: None # Headless Service 的关键标志 selector: app: nacos ports: - name: server port: 8848 targetPort: 8848 - name: grpc-client port: 9848 targetPort: 9848 - name: grpc-server port: 9849 targetPort: 9849创建完 Service 后可以起一个临时 Pod 用nslookup验证 DNS 解析是否正常。命令如下kubectl run -it --rm debug --imagebusybox:1.36 --restartNever -n middleware -- nslookup nacos-0.nacos-headless.middleware.svc.cluster.local如果返回的 IP 是具体某个 Pod 的地址说明 Headless Service 生效了。如果返回的是 Service 的 ClusterIP 或者解析失败就要检查 Service 的clusterIP字段是否真的设成了None以及 Pod 的 label 是否和 Service 的 selector 匹配。这个验证步骤花不了一分钟但能省掉后面排查集群成员发现失败的好几个小时。3.2 外置 MySQL 的库表初始化与连接池参数调优Nacos 集群模式必须用外置数据库官方推荐 MySQL 5.7 或 8.0。初始化 SQL 在 Nacos 发行包的conf/mysql-schema.sql里直接导入即可。但导入之前数据库的字符集要设成utf8mb4排序规则用utf8mb4_general_ci否则配置内容里有中文或特殊字符时会报错。CREATE DATABASE nacos_config DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER nacos% IDENTIFIED BY nacos_password; GRANT ALL PRIVILEGES ON nacos_config.* TO nacos%; FLUSH PRIVILEGES;连接池参数在 Nacos 的application.properties里控制但用官方镜像时可以通过环境变量覆盖。关键参数有三个db.pool.config.maximumPoolSize、db.pool.config.minimumIdle和db.pool.config.connectionTimeout。默认最大连接数是 50对于三个 Nacos 节点、每个节点并发读写配置的场景建议调到 100 左右。最小空闲连接保持 10 到 20避免频繁创建连接的开销。连接超时设 3000 毫秒太短容易在数据库抖动时误判太长会拖慢故障转移。# 在 StatefulSet 的 env 里追加 - name: DB_POOL_CONFIG_MAXIMUM_POOL_SIZE value: 100 - name: DB_POOL_CONFIG_MINIMUM_IDLE value: 20 - name: DB_POOL_CONFIG_CONNECTION_TIMEOUT value: 3000这里有个血泪经验MySQL 的max_connections也要同步调大。三个 Nacos 节点各 100 个连接加上其他业务如果 MySQL 默认的 151 个连接数没改Nacos 启动到一半就会报Too many connections然后节点反复重启集群永远凑不齐多数派。改完 MySQL 参数记得重启数据库或者动态生效别只改配置文件忘了 reload。3.3 用初始化脚本自动导入 SQL 并校验表结构如果不想手动导入 SQL可以在部署 Nacos 之前跑一个 Job用 MySQL 客户端镜像自动执行初始化脚本。这样整个部署流程就能完全脚本化适合放进 CI/CD 流水线。apiVersion: batch/v1 kind: Job metadata: name: nacos-db-init namespace: middleware spec: template: spec: containers: - name: mysql-client image: mysql:8.0 command: - bash - -c - | mysql -h mysql.middleware.svc.cluster.local -u root -p$MYSQL_ROOT_PASSWORD -e CREATE DATABASE IF NOT EXISTS nacos_config DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; mysql -h mysql.middleware.svc.cluster.local -u root -p$MYSQL_ROOT_PASSWORD nacos_config /sql/nacos-schema.sql env: - name: MYSQL_ROOT_PASSWORD valueFrom: secretKeyRef: name: mysql-root-secret key: password volumeMounts: - name: sql-script mountPath: /sql volumes: - name: sql-script configMap: name: nacos-sql-configmap restartPolicy: OnFailure这个 Job 的关键是把nacos-schema.sql放进 ConfigMap然后挂载到容器里执行。执行完成后可以用kubectl logs job/nacos-db-init -n middleware查看输出确认没有报错。之后再部署 StatefulSetNacos 启动时就能直接连上已经建好表的数据库省去启动阶段的建表逻辑集群组建速度会快不少。4. 集群部署脚本的编排顺序与滚动更新策略4.1 用 Shell 脚本串联 Namespace、Secret、Service、StatefulSet 的创建顺序手动一个个kubectl apply容易漏文件也不方便重复执行。我一般会写一个deploy-nacos.sh按依赖顺序把 YAML 文件串起来。脚本里加上set -e任何一步失败就停住避免带着错误状态继续往下走。#!/bin/bash set -euo pipefail NAMESPACEmiddleware SCRIPT_DIR$(cd $(dirname ${BASH_SOURCE[0]}) pwd) echo 创建 Namespace kubectl apply -f ${SCRIPT_DIR}/00-namespace.yaml echo 创建 MySQL 连接 Secret kubectl apply -f ${SCRIPT_DIR}/01-mysql-secret.yaml echo 初始化 Nacos 数据库 kubectl apply -f ${SCRIPT_DIR}/02-db-init-job.yaml kubectl wait --forconditioncomplete job/nacos-db-init -n ${NAMESPACE} --timeout120s echo 创建 Headless Service kubectl apply -f ${SCRIPT_DIR}/03-headless-service.yaml echo 部署 Nacos StatefulSet kubectl apply -f ${SCRIPT_DIR}/04-nacos-statefulset.yaml echo 等待集群就绪 kubectl rollout status statefulset/nacos -n ${NAMESPACE} --timeout300s echo 部署完成检查 Pod 状态 kubectl get pods -n ${NAMESPACE} -l appnacos -o wide这个脚本里kubectl wait和kubectl rollout status是两个关键等待点。前者确保数据库初始化 Job 跑完再部署 Nacos后者确保 StatefulSet 的所有 Pod 都进入 Ready 状态再返回。没有这两个等待脚本执行完立刻去访问 Nacos很可能因为集群还没选主完成而返回 503。4.2 StatefulSet 的 RollingUpdate 策略与 Pod 中断预算Nacos 集群默认的滚动更新策略是RollingUpdate但 StatefulSet 的更新顺序是从序号最大的 Pod 开始逐个替换。对于三节点集群更新顺序是 nacos-2、nacos-1、nacos-0。这个过程中只要多数节点在线集群就能正常提供服务。但如果不加 PodDisruptionBudget节点维护时可能一次性驱逐多个 Pod导致集群失去多数派。apiVersion: policy/v1 kind: PodDisruptionBudget metadata: name: nacos-pdb namespace: middleware spec: minAvailable: 2 # 至少保持 2 个 Pod 可用 selector: matchLabels: app: nacosminAvailable: 2意味着任何自愿中断比如节点排水最多只能同时影响一个 Pod。对于三节点集群这保证了任意时刻至少有两个节点在线Raft 多数派不会丢。如果是五节点集群可以设成 3。这个 PDB 在集群日常运维中非常有用尤其是 k8s 节点需要升级或重启的时候没有它驱逐操作可能直接把 Nacos 集群打挂。4.3 验证集群选主状态与配置写入的完整命令部署完成后怎么确认集群真的组成了而不是三个孤立的单机最直接的方法是看 Nacos 的集群管理接口。先随便进一个 Pod用 curl 调/nacos/v1/ns/operator/servers接口。kubectl exec -it nacos-0 -n middleware -- curl -s http://localhost:8848/nacos/v1/ns/operator/servers返回的 JSON 里会列出所有节点的 IP、状态和扩展信息。如果三个节点都出现在列表里并且state是UP说明集群成员发现正常。如果只看到一个节点或者某个节点状态是DOWN就要去查那个节点的日志重点看cluster.conf生成的内容和NACOS_SERVERS环境变量是否一致。再进一步可以写一条配置然后从另一个节点读出来验证数据同步。# 在 nacos-0 上写配置 kubectl exec -it nacos-0 -n middleware -- curl -X POST http://localhost:8848/nacos/v1/cs/configs -d dataIdtest.yamlgroupDEFAULT_GROUPcontentkey: value # 在 nacos-1 上读配置 kubectl exec -it nacos-1 -n middleware -- curl -s http://localhost:8848/nacos/v1/cs/configs?dataIdtest.yamlgroupDEFAULT_GROUP如果 nacos-1 能读到key: value说明 Raft 日志复制和数据库持久化都正常。读不到的话先检查 MySQL 里config_info表有没有数据再检查节点之间的 9848 端口是否互通。Nacos 2.x 的 gRPC 通信依赖 9848 和 9849 端口如果 NetworkPolicy 或者防火墙没放行节点之间能 ping 通但数据同步不了这种问题最隐蔽。5. 部署 Nacos 集群时最容易翻车的五个地方5.1 现象Pod 一直 CrashLoopBackOff日志报No DataSource set原因环境变量SPRING_DATASOURCE_PLATFORM没设成mysql或者 MySQL 连接信息不完整。Nacos 启动时检测不到外置数据源又因为MODEcluster不允许回退到内嵌 Derby直接启动失败。解决检查 StatefulSet 里SPRING_DATASOURCE_PLATFORM、MYSQL_SERVICE_HOST、MYSQL_SERVICE_PORT、MYSQL_SERVICE_DB_NAME、MYSQL_SERVICE_USER、MYSQL_SERVICE_PASSWORD这六个变量是否全部设置且值正确。特别注意密码里如果有特殊字符要确认 Secret 的 base64 编码没有引入换行符。5.2 现象集群三个 Pod 都 Running但注册的服务列表为空原因Nacos 节点之间没有组成集群每个节点各自为政。常见原因是NACOS_SERVERS里的域名解析失败或者 Headless Service 的clusterIP没有设成None。解决进 Pod 执行nslookup nacos-1.nacos-headless.middleware.svc.cluster.local确认能解析到具体 IP。如果解析到的是 Service 的 ClusterIP回去检查 Headless Service 的 YAMLclusterIP: None必须存在。另外确认NACOS_SERVERS里的 namespace 和实际部署的 namespace 一致大小写敏感。5.3 现象滚动更新时业务侧出现大量服务下线告警原因StatefulSet 更新时Pod 被终止前没有足够的时间把注册的服务摘除或者 PDB 没设导致多个 Pod 同时被驱逐。解决给 Nacos 容器加preStop钩子在终止前先调用下线接口再 sleep 一段时间等流量摘除。lifecycle: preStop: exec: command: - bash - -c - | curl -X DELETE http://localhost:8848/nacos/v1/ns/instance?serviceName...ip${POD_IP}port... sleep 10同时确认 PDB 的minAvailable至少是replicas - 1三节点集群设 2五节点设 3。这样滚动更新时最多影响一个 Pod业务侧感知不到明显抖动。5.4 现象Nacos 节点频繁 OOMKilled重启后集群重新选主原因JVM 堆内存设置超过了容器 limit或者堆外内存gRPC 直接缓冲区占用过高。Nacos 2.x 的 gRPC 通信比 1.x 的 HTTP 长轮询更吃堆外内存。解决把JVM_XMX降到容器 limit 的 60% 到 70%。比如 limit 是 4GiJVM_XMX设 2.5Gi 到 3Gi。同时监控 Pod 的container_memory_working_set_bytes如果接近 limit要么调大 limit要么调小堆。另外JVM_XMN不要超过JVM_XMX的一半否则新生代过大导致老年代过小Full GC 频繁。5.5 现象配置热更新不生效客户端一直拿到旧值原因Nacos 2.x 的配置推送依赖 gRPC 长连接如果客户端和服务端之间的 9848 端口被 NetworkPolicy 阻断或者客户端版本和服务端版本不匹配推送通道建立不起来。解决确认客户端到 Nacos 的 9848 端口连通telnet nacos-headless.middleware.svc.cluster.local 9848能通。检查客户端 SDK 版本Nacos 2.3.x 服务端建议客户端用 2.2.x 及以上。如果用的是 Spring Cloud Alibaba确认spring.cloud.nacos.config.extension-configs的 refresh 属性没有设成 false。最后看服务端日志里有没有push fail关键字有的话就是连接层的问题。6. 用 initContainer 做配置预检与集群健康度自愈6.1 initContainer 在 Nacos 启动前校验 MySQL 连通性和表结构Nacos 主容器启动前可以加一个 initContainer 做前置检查。这样如果数据库没准备好Pod 会卡在 Init 阶段而不是反复重启主容器日志也更干净。initContainers: - name: check-mysql image: mysql:8.0 command: - bash - -c - | until mysql -h mysql.middleware.svc.cluster.local -u nacos -p$MYSQL_PASSWORD -e SELECT 1 FROM nacos_config.config_info LIMIT 1; do echo 等待 MySQL 和 nacos_config 表就绪... sleep 5 done env: - name: MYSQL_PASSWORD valueFrom: secretKeyRef: name: nacos-mysql-secret key: password这个 initContainer 会一直重试直到config_info表可查询。SELECT 1 FROM ... LIMIT 1比SELECT 1更严格它要求表必须存在且有权限访问。如果表还没建说明数据库初始化 Job 没跑完或者失败了这时候卡在 Init 阶段比主容器 CrashLoop 更容易定位问题。6.2 用 livenessProbe 的 exec 探针检测集群选主状态默认的 TCP 探针只能检测端口是否监听不能判断节点是否真的加入了集群。可以改用 exec 探针调 Nacos 的集群健康接口检查当前节点是否在集群成员列表里。livenessProbe: exec: command: - bash - -c - | curl -s http://localhost:8848/nacos/v1/ns/operator/servers | grep -q $(hostname -i) initialDelaySeconds: 60 periodSeconds: 20 failureThreshold: 3这个探针的逻辑是获取集群成员列表然后 grep 当前 Pod 的 IP。如果当前节点不在列表里说明它掉出了集群探针失败kubelet 会重启这个 Pod。重启后 Pod 会重新加入集群比一直僵死在那里强。注意hostname -i在容器里返回的是 Pod IP和 Nacos 注册的 IP 一致。如果网络插件有特殊配置导致 IP 不一致可以把hostname -i换成环境变量POD_IP通过 downward API 注入。6.3 一个自愈脚本检测到集群节点数不足时自动扩容Nacos 集群的节点数最好是奇数3 或 5。如果因为节点故障导致在线节点数少于多数派集群会进入只读状态。可以写一个 CronJob 定期检查集群节点数少于阈值时自动扩容 StatefulSet。#!/bin/bash # check-nacos-cluster.sh EXPECTED3 CURRENT$(kubectl exec -n middleware nacos-0 -- curl -s http://localhost:8848/nacos/v1/ns/operator/servers | grep -o ip | wc -l) if [ $CURRENT -lt $EXPECTED ]; then echo 集群节点数不足当前 $CURRENT期望 $EXPECTED触发扩容 kubectl scale statefulset nacos -n middleware --replicas$EXPECTED else echo 集群节点数正常$CURRENT fi这个脚本可以放进 CronJob 每五分钟跑一次。但要注意扩容 StatefulSet 会创建新的 Pod新 Pod 需要时间加入集群。如果是因为网络分区导致节点数不足盲目扩容可能加重问题。所以这个自愈策略更适合节点被误删或驱逐的场景网络层面的故障还是要靠监控告警人工介入。6.4 验证自愈效果手动删除一个 Pod 观察集群恢复部署完自愈逻辑后可以手动删一个 Pod 验证效果。kubectl delete pod nacos-1 -n middlewareStatefulSet 控制器会立刻重建nacos-1新 Pod 启动后通过NACOS_SERVERS环境变量重新加入集群。观察kubectl get pods -n middleware -w新 Pod 应该在 30 秒到 1 分钟内进入 Ready。同时用之前的集群成员接口确认三个节点都回来了。如果新 Pod 启动后一直不加入集群检查 PVC 是否被正确挂载以及nacos-1的域名解析是否正常。这套自愈机制的核心思路是把「集群健康」当成一个可观测、可干预的状态而不是部署完就不管了。Nacos 集群在 k8s 上跑最大的挑战不是初始部署而是长期运行中的节点故障、滚动更新和资源竞争。把 initContainer、exec 探针和自愈脚本组合起来能挡掉大部分常见的集群异常。我自己的习惯是每次调整 Nacos 的 YAML 之后先删一个 Pod 看看恢复速度再触发一次滚动更新看看业务侧有没有抖动。这两个动作花不了十分钟但能提前暴露大部分配置问题。希望帮到你。本文还有配套的精品资源点击获取
简介这份资源面向需要在 Kubernetes 上部署 Nacos 集群的运维与后端开发人员尤其适合刚接触 K8s 编排、希望跳过繁琐配置直接跑通集群的初学者。它把 Nacos 集群部署拆解为按执行顺序排列的极简脚本覆盖数据库配置、Headless Service、StatefulSet、Service 以及 Ingress 暴露等关键环节省去大量手工调试成本。压缩包共 6 个文件以 5 个 yaml 清单为主分别承担数据库连接、无头服务、有状态副本集、服务暴露与外部访问入口等职责另附 1 个 txt 说明文件整体仅约 3KB轻量易读。目前已有 761 人学习下载说明该方案在实际部署场景中具备一定参考价值。读者可据此快速搭建可用的 Nacos 集群环境理解各资源对象的先后依赖关系并在此基础上按需调整副本数、存储与域名配置减少从零编写清单的试错时间。1. 从一堆散装 YAML 到能扛住重启的 Nacos 集群这套脚本到底在解决什么很多人第一次在 k8s 上部署 Nacos都是先kubectl apply一个官方示例跑起来看到 Pod 是 Running 就以为完事了。结果服务一重启配置丢了节点一扩容集群选主乱了生产环境一压测注册中心直接脑裂。问题的根子不在 Nacos 本身而在于那堆散装的 YAML 没有把「集群」两个字当回事——StatefulSet 的稳定网络标识、持久化存储的挂载路径、MySQL 外置数据源的连接池参数、JVM 堆内存与容器 limit 的匹配关系任何一项没对齐集群就是纸糊的。这篇笔记要拆的就是一套能直接抄作业的 k8s Nacos 集群部署脚本与 YAML 组合。它解决的不是「能不能跑起来」而是「跑起来之后能不能扛住滚动更新、节点故障和配置热更新」。适合已经会用 kubectl、懂一点 StatefulSet 和 Service 概念但还没在生产环境把 Nacos 集群真正落地的后端或运维工程师。如果你正在搜 k8s 部署教程、nacos 集群部署脚本或者纠结 consul 和 nacos 的区别到底该选哪个下面的内容会从 YAML 的每一段参数讲起把踩过的坑和验证方法一并交代清楚。2. 为什么 Nacos 集群在 k8s 上必须用 StatefulSet 而不是 Deployment2.1 从 Nacos 的集群寻址机制倒推工作负载选型Nacos 集群节点之间需要互相感知靠的是cluster.conf里写死的节点列表或者环境变量nacos.member.list指定的地址。每个节点启动时要知道其他节点的 IP 或域名才能组成 Raft 集群完成选主和数据同步。Deployment 创建的 Pod 名字是随机哈希重启后 IP 变了、名字也变了cluster.conf根本没法维护一个稳定的成员列表。StatefulSet 给每个 Pod 分配固定的序号和稳定的 DNS 域名比如nacos-0.nacos-headless.default.svc.cluster.local这样cluster.conf里写域名就能长期有效节点重启后重新注册到同一个域名上集群成员关系不会乱。另一个关键点是存储。Nacos 默认用内嵌 Derby 数据库单机没问题集群模式下必须外置 MySQL。但即便如此每个 Nacos 节点本地还有data目录用于存储 Raft 日志和快照。如果用 Deployment 加 emptyDirPod 一漂移日志就没了节点重新加入集群时可能因为日志缺失导致数据不一致。StatefulSet 配合 volumeClaimTemplates 给每个 Pod 挂一块独立的 PVCRaft 日志和本地缓存才能持久化这是集群稳定性的底线。2.2 一个最小可用的 StatefulSet YAML 骨架与逐段拆解下面这份 YAML 是我在多个环境里收敛出来的骨架去掉了花哨的 sidecar只保留 Nacos 集群运行必需的部分。注意看serviceName、podManagementPolicy和volumeClaimTemplates这三处它们是 StatefulSet 区别于 Deployment 的核心。apiVersion: apps/v1 kind: StatefulSet metadata: name: nacos namespace: middleware spec: serviceName: nacos-headless # 必须指向 Headless Service否则 Pod 没有稳定 DNS replicas: 3 # 集群节点数生产建议 3 或 5 podManagementPolicy: Parallel # 并行启动加快集群组建速度 selector: matchLabels: app: nacos template: metadata: labels: app: nacos spec: affinity: podAntiAffinity: # 反亲和尽量把 Pod 打散到不同节点 preferredDuringSchedulingIgnoredDuringExecution: - weight: 100 podAffinityTerm: labelSelector: matchLabels: app: nacos topologyKey: kubernetes.io/hostname containers: - name: nacos image: nacos/nacos-server:v2.3.2 # 版本按需替换不要用 latest env: - name: MODE value: cluster # 必须显式声明集群模式 - name: NACOS_SERVERS value: nacos-0.nacos-headless.middleware.svc.cluster.local:8848 nacos-1.nacos-headless.middleware.svc.cluster.local:8848 nacos-2.nacos-headless.middleware.svc.cluster.local:8848 - name: SPRING_DATASOURCE_PLATFORM value: mysql # 使用外置 MySQL - name: MYSQL_SERVICE_HOST value: mysql.middleware.svc.cluster.local - name: MYSQL_SERVICE_PORT value: 3306 - name: MYSQL_SERVICE_DB_NAME value: nacos_config - name: MYSQL_SERVICE_USER value: nacos - name: MYSQL_SERVICE_PASSWORD value: nacos_password - name: JVM_XMS value: 2g # 堆初始值与 limit 保持比例 - name: JVM_XMX value: 2g # 堆最大值建议不超过 limit 的 70% - name: JVM_XMN value: 1g # 新生代约为 Xmx 的一半 ports: - containerPort: 8848 # 主服务端口 - containerPort: 9848 # gRPC 端口2.x 必须暴露 - containerPort: 9849 # gRPC 端口2.x 必须暴露 volumeMounts: - name: nacos-data mountPath: /home/nacos/data # Raft 日志和本地缓存 - name: nacos-logs mountPath: /home/nacos/logs # 日志持久化方便排查 readinessProbe: tcpSocket: port: 8848 initialDelaySeconds: 30 periodSeconds: 10 livenessProbe: tcpSocket: port: 8848 initialDelaySeconds: 60 periodSeconds: 20 volumeClaimTemplates: - metadata: name: nacos-data spec: accessModes: [ReadWriteOnce] storageClassName: standard # 按集群实际 StorageClass 替换 resources: requests: storage: 10Gi - metadata: name: nacos-logs spec: accessModes: [ReadWriteOnce] storageClassName: standard resources: requests: storage: 5Gi这份 YAML 里最容易被忽略的是NACOS_SERVERS环境变量。Nacos 2.x 官方镜像支持用这个变量直接生成cluster.conf省去手动挂 ConfigMap 的麻烦。但要注意变量里的域名必须和 Headless Service 的命名规则完全一致格式是pod-name.service-name.namespace.svc.cluster.local。如果 namespace 写错或者 serviceName 对不上节点之间就互相找不到日志里会一直刷failed to connect to server。podManagementPolicy: Parallel是为了让三个 Pod 同时启动而不是等前一个 Ready 再起下一个。Nacos 集群需要多数节点在线才能完成选主串行启动会导致第一个 Pod 一直卡在选主阶段直到第二个 Pod 起来才能继续白白拉长部署时间。并行启动配合就绪探针能让集群更快进入可用状态。资源限制方面JVM_XMS和JVM_XMX建议设成一样避免堆动态伸缩带来的性能抖动。JVM_XMN设为Xmx的一半左右这是 Nacos 官方推荐的配比。如果容器 limit 设了 4Gi堆最大给 2.5Gi 到 3Gi 比较稳妥留出堆外内存给 gRPC 和 Netty 的直接缓冲区。见过太多因为堆内存超过 limit 导致 Pod 被 OOMKilled 的案例重启后集群重新选主业务侧注册列表瞬间清空这就是典型的「翻车」现场。3. Headless Service 与 MySQL 外置数据源的 YAML 配置细节3.1 Headless Service 的 YAML 写法与 DNS 验证方法StatefulSet 的serviceName指向的 Headless Service 必须单独创建它的clusterIP: None是硬性要求。没有这行k8s 会给 Service 分配一个虚拟 IPPod 的 DNS 解析就变成负载均衡地址而不是具体的 Pod 域名StatefulSet 的稳定网络标识就失效了。apiVersion: v1 kind: Service metadata: name: nacos-headless namespace: middleware labels: app: nacos spec: clusterIP: None # Headless Service 的关键标志 selector: app: nacos ports: - name: server port: 8848 targetPort: 8848 - name: grpc-client port: 9848 targetPort: 9848 - name: grpc-server port: 9849 targetPort: 9849创建完 Service 后可以起一个临时 Pod 用nslookup验证 DNS 解析是否正常。命令如下kubectl run -it --rm debug --imagebusybox:1.36 --restartNever -n middleware -- nslookup nacos-0.nacos-headless.middleware.svc.cluster.local如果返回的 IP 是具体某个 Pod 的地址说明 Headless Service 生效了。如果返回的是 Service 的 ClusterIP 或者解析失败就要检查 Service 的clusterIP字段是否真的设成了None以及 Pod 的 label 是否和 Service 的 selector 匹配。这个验证步骤花不了一分钟但能省掉后面排查集群成员发现失败的好几个小时。3.2 外置 MySQL 的库表初始化与连接池参数调优Nacos 集群模式必须用外置数据库官方推荐 MySQL 5.7 或 8.0。初始化 SQL 在 Nacos 发行包的conf/mysql-schema.sql里直接导入即可。但导入之前数据库的字符集要设成utf8mb4排序规则用utf8mb4_general_ci否则配置内容里有中文或特殊字符时会报错。CREATE DATABASE nacos_config DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER nacos% IDENTIFIED BY nacos_password; GRANT ALL PRIVILEGES ON nacos_config.* TO nacos%; FLUSH PRIVILEGES;连接池参数在 Nacos 的application.properties里控制但用官方镜像时可以通过环境变量覆盖。关键参数有三个db.pool.config.maximumPoolSize、db.pool.config.minimumIdle和db.pool.config.connectionTimeout。默认最大连接数是 50对于三个 Nacos 节点、每个节点并发读写配置的场景建议调到 100 左右。最小空闲连接保持 10 到 20避免频繁创建连接的开销。连接超时设 3000 毫秒太短容易在数据库抖动时误判太长会拖慢故障转移。# 在 StatefulSet 的 env 里追加 - name: DB_POOL_CONFIG_MAXIMUM_POOL_SIZE value: 100 - name: DB_POOL_CONFIG_MINIMUM_IDLE value: 20 - name: DB_POOL_CONFIG_CONNECTION_TIMEOUT value: 3000这里有个血泪经验MySQL 的max_connections也要同步调大。三个 Nacos 节点各 100 个连接加上其他业务如果 MySQL 默认的 151 个连接数没改Nacos 启动到一半就会报Too many connections然后节点反复重启集群永远凑不齐多数派。改完 MySQL 参数记得重启数据库或者动态生效别只改配置文件忘了 reload。3.3 用初始化脚本自动导入 SQL 并校验表结构如果不想手动导入 SQL可以在部署 Nacos 之前跑一个 Job用 MySQL 客户端镜像自动执行初始化脚本。这样整个部署流程就能完全脚本化适合放进 CI/CD 流水线。apiVersion: batch/v1 kind: Job metadata: name: nacos-db-init namespace: middleware spec: template: spec: containers: - name: mysql-client image: mysql:8.0 command: - bash - -c - | mysql -h mysql.middleware.svc.cluster.local -u root -p$MYSQL_ROOT_PASSWORD -e CREATE DATABASE IF NOT EXISTS nacos_config DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; mysql -h mysql.middleware.svc.cluster.local -u root -p$MYSQL_ROOT_PASSWORD nacos_config /sql/nacos-schema.sql env: - name: MYSQL_ROOT_PASSWORD valueFrom: secretKeyRef: name: mysql-root-secret key: password volumeMounts: - name: sql-script mountPath: /sql volumes: - name: sql-script configMap: name: nacos-sql-configmap restartPolicy: OnFailure这个 Job 的关键是把nacos-schema.sql放进 ConfigMap然后挂载到容器里执行。执行完成后可以用kubectl logs job/nacos-db-init -n middleware查看输出确认没有报错。之后再部署 StatefulSetNacos 启动时就能直接连上已经建好表的数据库省去启动阶段的建表逻辑集群组建速度会快不少。4. 集群部署脚本的编排顺序与滚动更新策略4.1 用 Shell 脚本串联 Namespace、Secret、Service、StatefulSet 的创建顺序手动一个个kubectl apply容易漏文件也不方便重复执行。我一般会写一个deploy-nacos.sh按依赖顺序把 YAML 文件串起来。脚本里加上set -e任何一步失败就停住避免带着错误状态继续往下走。#!/bin/bash set -euo pipefail NAMESPACEmiddleware SCRIPT_DIR$(cd $(dirname ${BASH_SOURCE[0]}) pwd) echo 创建 Namespace kubectl apply -f ${SCRIPT_DIR}/00-namespace.yaml echo 创建 MySQL 连接 Secret kubectl apply -f ${SCRIPT_DIR}/01-mysql-secret.yaml echo 初始化 Nacos 数据库 kubectl apply -f ${SCRIPT_DIR}/02-db-init-job.yaml kubectl wait --forconditioncomplete job/nacos-db-init -n ${NAMESPACE} --timeout120s echo 创建 Headless Service kubectl apply -f ${SCRIPT_DIR}/03-headless-service.yaml echo 部署 Nacos StatefulSet kubectl apply -f ${SCRIPT_DIR}/04-nacos-statefulset.yaml echo 等待集群就绪 kubectl rollout status statefulset/nacos -n ${NAMESPACE} --timeout300s echo 部署完成检查 Pod 状态 kubectl get pods -n ${NAMESPACE} -l appnacos -o wide这个脚本里kubectl wait和kubectl rollout status是两个关键等待点。前者确保数据库初始化 Job 跑完再部署 Nacos后者确保 StatefulSet 的所有 Pod 都进入 Ready 状态再返回。没有这两个等待脚本执行完立刻去访问 Nacos很可能因为集群还没选主完成而返回 503。4.2 StatefulSet 的 RollingUpdate 策略与 Pod 中断预算Nacos 集群默认的滚动更新策略是RollingUpdate但 StatefulSet 的更新顺序是从序号最大的 Pod 开始逐个替换。对于三节点集群更新顺序是 nacos-2、nacos-1、nacos-0。这个过程中只要多数节点在线集群就能正常提供服务。但如果不加 PodDisruptionBudget节点维护时可能一次性驱逐多个 Pod导致集群失去多数派。apiVersion: policy/v1 kind: PodDisruptionBudget metadata: name: nacos-pdb namespace: middleware spec: minAvailable: 2 # 至少保持 2 个 Pod 可用 selector: matchLabels: app: nacosminAvailable: 2意味着任何自愿中断比如节点排水最多只能同时影响一个 Pod。对于三节点集群这保证了任意时刻至少有两个节点在线Raft 多数派不会丢。如果是五节点集群可以设成 3。这个 PDB 在集群日常运维中非常有用尤其是 k8s 节点需要升级或重启的时候没有它驱逐操作可能直接把 Nacos 集群打挂。4.3 验证集群选主状态与配置写入的完整命令部署完成后怎么确认集群真的组成了而不是三个孤立的单机最直接的方法是看 Nacos 的集群管理接口。先随便进一个 Pod用 curl 调/nacos/v1/ns/operator/servers接口。kubectl exec -it nacos-0 -n middleware -- curl -s http://localhost:8848/nacos/v1/ns/operator/servers返回的 JSON 里会列出所有节点的 IP、状态和扩展信息。如果三个节点都出现在列表里并且state是UP说明集群成员发现正常。如果只看到一个节点或者某个节点状态是DOWN就要去查那个节点的日志重点看cluster.conf生成的内容和NACOS_SERVERS环境变量是否一致。再进一步可以写一条配置然后从另一个节点读出来验证数据同步。# 在 nacos-0 上写配置 kubectl exec -it nacos-0 -n middleware -- curl -X POST http://localhost:8848/nacos/v1/cs/configs -d dataIdtest.yamlgroupDEFAULT_GROUPcontentkey: value # 在 nacos-1 上读配置 kubectl exec -it nacos-1 -n middleware -- curl -s http://localhost:8848/nacos/v1/cs/configs?dataIdtest.yamlgroupDEFAULT_GROUP如果 nacos-1 能读到key: value说明 Raft 日志复制和数据库持久化都正常。读不到的话先检查 MySQL 里config_info表有没有数据再检查节点之间的 9848 端口是否互通。Nacos 2.x 的 gRPC 通信依赖 9848 和 9849 端口如果 NetworkPolicy 或者防火墙没放行节点之间能 ping 通但数据同步不了这种问题最隐蔽。5. 部署 Nacos 集群时最容易翻车的五个地方5.1 现象Pod 一直 CrashLoopBackOff日志报No DataSource set原因环境变量SPRING_DATASOURCE_PLATFORM没设成mysql或者 MySQL 连接信息不完整。Nacos 启动时检测不到外置数据源又因为MODEcluster不允许回退到内嵌 Derby直接启动失败。解决检查 StatefulSet 里SPRING_DATASOURCE_PLATFORM、MYSQL_SERVICE_HOST、MYSQL_SERVICE_PORT、MYSQL_SERVICE_DB_NAME、MYSQL_SERVICE_USER、MYSQL_SERVICE_PASSWORD这六个变量是否全部设置且值正确。特别注意密码里如果有特殊字符要确认 Secret 的 base64 编码没有引入换行符。5.2 现象集群三个 Pod 都 Running但注册的服务列表为空原因Nacos 节点之间没有组成集群每个节点各自为政。常见原因是NACOS_SERVERS里的域名解析失败或者 Headless Service 的clusterIP没有设成None。解决进 Pod 执行nslookup nacos-1.nacos-headless.middleware.svc.cluster.local确认能解析到具体 IP。如果解析到的是 Service 的 ClusterIP回去检查 Headless Service 的 YAMLclusterIP: None必须存在。另外确认NACOS_SERVERS里的 namespace 和实际部署的 namespace 一致大小写敏感。5.3 现象滚动更新时业务侧出现大量服务下线告警原因StatefulSet 更新时Pod 被终止前没有足够的时间把注册的服务摘除或者 PDB 没设导致多个 Pod 同时被驱逐。解决给 Nacos 容器加preStop钩子在终止前先调用下线接口再 sleep 一段时间等流量摘除。lifecycle: preStop: exec: command: - bash - -c - | curl -X DELETE http://localhost:8848/nacos/v1/ns/instance?serviceName...ip${POD_IP}port... sleep 10同时确认 PDB 的minAvailable至少是replicas - 1三节点集群设 2五节点设 3。这样滚动更新时最多影响一个 Pod业务侧感知不到明显抖动。5.4 现象Nacos 节点频繁 OOMKilled重启后集群重新选主原因JVM 堆内存设置超过了容器 limit或者堆外内存gRPC 直接缓冲区占用过高。Nacos 2.x 的 gRPC 通信比 1.x 的 HTTP 长轮询更吃堆外内存。解决把JVM_XMX降到容器 limit 的 60% 到 70%。比如 limit 是 4GiJVM_XMX设 2.5Gi 到 3Gi。同时监控 Pod 的container_memory_working_set_bytes如果接近 limit要么调大 limit要么调小堆。另外JVM_XMN不要超过JVM_XMX的一半否则新生代过大导致老年代过小Full GC 频繁。5.5 现象配置热更新不生效客户端一直拿到旧值原因Nacos 2.x 的配置推送依赖 gRPC 长连接如果客户端和服务端之间的 9848 端口被 NetworkPolicy 阻断或者客户端版本和服务端版本不匹配推送通道建立不起来。解决确认客户端到 Nacos 的 9848 端口连通telnet nacos-headless.middleware.svc.cluster.local 9848能通。检查客户端 SDK 版本Nacos 2.3.x 服务端建议客户端用 2.2.x 及以上。如果用的是 Spring Cloud Alibaba确认spring.cloud.nacos.config.extension-configs的 refresh 属性没有设成 false。最后看服务端日志里有没有push fail关键字有的话就是连接层的问题。6. 用 initContainer 做配置预检与集群健康度自愈6.1 initContainer 在 Nacos 启动前校验 MySQL 连通性和表结构Nacos 主容器启动前可以加一个 initContainer 做前置检查。这样如果数据库没准备好Pod 会卡在 Init 阶段而不是反复重启主容器日志也更干净。initContainers: - name: check-mysql image: mysql:8.0 command: - bash - -c - | until mysql -h mysql.middleware.svc.cluster.local -u nacos -p$MYSQL_PASSWORD -e SELECT 1 FROM nacos_config.config_info LIMIT 1; do echo 等待 MySQL 和 nacos_config 表就绪... sleep 5 done env: - name: MYSQL_PASSWORD valueFrom: secretKeyRef: name: nacos-mysql-secret key: password这个 initContainer 会一直重试直到config_info表可查询。SELECT 1 FROM ... LIMIT 1比SELECT 1更严格它要求表必须存在且有权限访问。如果表还没建说明数据库初始化 Job 没跑完或者失败了这时候卡在 Init 阶段比主容器 CrashLoop 更容易定位问题。6.2 用 livenessProbe 的 exec 探针检测集群选主状态默认的 TCP 探针只能检测端口是否监听不能判断节点是否真的加入了集群。可以改用 exec 探针调 Nacos 的集群健康接口检查当前节点是否在集群成员列表里。livenessProbe: exec: command: - bash - -c - | curl -s http://localhost:8848/nacos/v1/ns/operator/servers | grep -q $(hostname -i) initialDelaySeconds: 60 periodSeconds: 20 failureThreshold: 3这个探针的逻辑是获取集群成员列表然后 grep 当前 Pod 的 IP。如果当前节点不在列表里说明它掉出了集群探针失败kubelet 会重启这个 Pod。重启后 Pod 会重新加入集群比一直僵死在那里强。注意hostname -i在容器里返回的是 Pod IP和 Nacos 注册的 IP 一致。如果网络插件有特殊配置导致 IP 不一致可以把hostname -i换成环境变量POD_IP通过 downward API 注入。6.3 一个自愈脚本检测到集群节点数不足时自动扩容Nacos 集群的节点数最好是奇数3 或 5。如果因为节点故障导致在线节点数少于多数派集群会进入只读状态。可以写一个 CronJob 定期检查集群节点数少于阈值时自动扩容 StatefulSet。#!/bin/bash # check-nacos-cluster.sh EXPECTED3 CURRENT$(kubectl exec -n middleware nacos-0 -- curl -s http://localhost:8848/nacos/v1/ns/operator/servers | grep -o ip | wc -l) if [ $CURRENT -lt $EXPECTED ]; then echo 集群节点数不足当前 $CURRENT期望 $EXPECTED触发扩容 kubectl scale statefulset nacos -n middleware --replicas$EXPECTED else echo 集群节点数正常$CURRENT fi这个脚本可以放进 CronJob 每五分钟跑一次。但要注意扩容 StatefulSet 会创建新的 Pod新 Pod 需要时间加入集群。如果是因为网络分区导致节点数不足盲目扩容可能加重问题。所以这个自愈策略更适合节点被误删或驱逐的场景网络层面的故障还是要靠监控告警人工介入。6.4 验证自愈效果手动删除一个 Pod 观察集群恢复部署完自愈逻辑后可以手动删一个 Pod 验证效果。kubectl delete pod nacos-1 -n middlewareStatefulSet 控制器会立刻重建nacos-1新 Pod 启动后通过NACOS_SERVERS环境变量重新加入集群。观察kubectl get pods -n middleware -w新 Pod 应该在 30 秒到 1 分钟内进入 Ready。同时用之前的集群成员接口确认三个节点都回来了。如果新 Pod 启动后一直不加入集群检查 PVC 是否被正确挂载以及nacos-1的域名解析是否正常。这套自愈机制的核心思路是把「集群健康」当成一个可观测、可干预的状态而不是部署完就不管了。Nacos 集群在 k8s 上跑最大的挑战不是初始部署而是长期运行中的节点故障、滚动更新和资源竞争。把 initContainer、exec 探针和自愈脚本组合起来能挡掉大部分常见的集群异常。我自己的习惯是每次调整 Nacos 的 YAML 之后先删一个 Pod 看看恢复速度再触发一次滚动更新看看业务侧有没有抖动。这两个动作花不了十分钟但能提前暴露大部分配置问题。希望帮到你。本文还有配套的精品资源点击获取
