K3s 中使用 Helm 部署 Nacos 教程（严格对齐官方文档）

本教程完全遵循 Nacos 官方 Kubernetes 快速启动文档：https://nacos.io/docs/latest/quickstart/quick-start-kubernetes/，适配 K3s 集群环境，整合 Longhorn 持久化与 MetalLB 固定 IP 配置。

概述

本指南基于 Nacos 官方标准流程，在 K3s 集群中通过 Helm 完成 Nacos 单机模式与集群模式的部署，核心流程与官方文档完全一致，同时补充 K3s 特有的 servicelb 适配、Longhorn 持久化配置，满足开发测试与生产环境需求。

Nacos 官方推荐 Kubernetes 环境使用 Helm 部署，优先采用本地 Chart 包方式，规避仓库访问问题，确保部署流程标准化、可复现。

目标

严格按照官方文档完成 K3s 环境下 Nacos 的 Helm 部署
实现官方标准的持久化配置（对接 Longhorn）与服务暴露（MetalLB/servicelb）
掌握官方定义的验证、运维与故障排查方法

前置条件

已部署 K3s 集群（单节点/多节点，Kubernetes 版本 ≥ 1.20，满足官方最低要求）
已安装 Helm 3.5.0+（官方推荐版本）
集群节点已配置 kubectl 并具备管理员权限
已部署 Longhorn 并确认 longhorn 存储类可用：
```
kubectl get sc | grep longhorn
```
可选：部署 MetalLB（生产环境用于固定 LoadBalancer IP，官方推荐）
节点资源：单机模式 ≥ 1GB 内存，集群模式每个节点 ≥ 2GB 内存
节点可访问 Docker Hub，能拉取官方镜像 nacos/nacos-server

核心流程：官方标准部署步骤

1. 获取官方 Helm Chart 包（官方第一步）

根据官方文档，优先通过 Git Clone 获取最新 Chart 源码（而非 helm repo add），确保与官方同步：

# 克隆官方仓库（获取最新 Chart）
git clone https://github.com/nacos-group/nacos-k8s.git
cd nacos-k8s/helm/nacos

# 查看官方 Chart 目录结构（与文档一致）
ls -l
# 标准结构：Chart.yaml  README.md  templates  values.yaml

官方说明：直接克隆仓库可获取最新的 Chart 配置，避免 Helm 仓库同步延迟问题。

2. 部署前准备（官方标准操作）

2.1 创建命名空间

官方推荐使用独立命名空间隔离 Nacos 资源：

kubectl create namespace nacos

2.2 配置持久化存储（对接 Longhorn）

官方 Chart 默认支持持久化配置，需指定 longhorn 存储类（替换官方默认的 default 存储类）。

2.3 确认 LoadBalancer 组件

生产环境：部署 MetalLB（官方推荐），用于分配固定 IP
测试环境：使用 K3s 内置 servicelb（无需额外部署，自动分配 NodePort）

3. 部署单机模式 Nacos（官方开发测试环境）

官方定义的单机模式为嵌入式数据库，无需外部依赖，适合快速验证。

3.1 创建官方标准配置文件 `values-standalone.yaml`

严格遵循官方 values.yaml 结构，仅修改存储类与服务暴露配置：

# values-standalone.yaml （基于官方默认配置修改）
global:
  mode: standalone  # 官方单机模式标识
  namespace: nacos

nacos:
  image:
    repository: nacos/nacos-server
    tag: latest  # 官方默认使用 latest，生产建议指定稳定版本（如 v2.4.0）
    pullPolicy: IfNotPresent

  # 服务暴露：官方推荐 LoadBalancer 模式
  service:
    type: LoadBalancer
    port: 8848
    # 可选：MetalLB 固定 IP（生产环境配置）
    loadBalancerIP: 10.2.10.103
    # K3s servicelb 适配：固定 NodePort 端口
    nodePorts:
      http: "30848"
    externalTrafficPolicy: Local

  # 持久化配置（官方默认关闭，此处开启并对接 Longhorn）
  persistence:
    enabled: true
    storageClass: "longhorn"  # 替换官方默认的 default 存储类
    accessMode: ReadWriteOnce
    data:
      size: 1Gi
    logs:
      enabled: true
      size: 512Mi

  # JVM 配置（官方默认参数）
  jvm:
    xms: 512m
    xmx: 512m
    xmn: 256m

# 资源限制（官方默认无限制，补充 K3s 适配配置）
resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: 1000m
    memory: 1Gi

3.2 执行官方部署命令

# 本地 Chart 部署（官方标准命令）
helm install nacos . -n nacos -f values-standalone.yaml

# 等待 Pod 启动（官方验证步骤）
kubectl get pods -n nacos -w

4. 部署集群模式 Nacos（官方生产环境）

官方明确生产环境必须使用 集群模式 + 外部 MySQL，禁止使用嵌入式数据库，以下为完整流程。

4.1 前置步骤：部署 MySQL 并初始化（官方要求）

部署 MySQL 服务（可通过 Helm 部署，参考官方文档）

下载官方初始化 SQL 脚本并执行：

# 下载官方 SQL 脚本
wget https://raw.githubusercontent.com/alibaba/nacos/master/distribution/conf/nacos-mysql.sql
# 登录 MySQL 执行脚本，创建 nacos_config 数据库
mysql -h <mysql-service-ip> -u root -p < nacos-mysql.sql

创建 MySQL 密码 Secret（官方推荐，禁止明文配置）：

kubectl create secret generic nacos-mysql-secret -n nacos \
  --from-literal=mysql-password="<你的 MySQL 密码>"

4.2 创建官方集群配置文件 `values-cluster.yaml`

严格遵循官方集群配置规范，配置 MySQL 连接、3 副本、Longhorn 持久化：

# values-cluster.yaml （官方标准集群配置）
global:
  mode: cluster  # 官方集群模式标识
  namespace: nacos
  replicaCount: 3  # 官方要求集群至少 3 副本

nacos:
  image:
    repository: nacos/nacos-server
    tag: v2.4.0  # 生产环境指定稳定版本
    pullPolicy: IfNotPresent

  service:
    type: LoadBalancer
    port: 8848
    loadBalancerIP: 10.2.10.103  # MetalLB 固定 VIP
    externalTrafficPolicy: Local
    # 官方集群通信端口（固定，不可修改）
    clusterPort: 9848
    raftPort: 9849

  # 持久化配置（官方生产环境强制开启）
  persistence:
    enabled: true
    storageClass: "longhorn"
    accessMode: ReadWriteOnce
    data:
      size: 5Gi
      annotations:
        longhorn.io/replica-count: "2"  # Longhorn 副本数，提高可靠性
    logs:
      size: 2Gi

  # 外部 MySQL 配置（官方集群模式必配，替代嵌入式数据库）
  mysql:
    host: "mysql.nacos.svc.cluster.local"  # MySQL Service 地址
    port: 3306
    db: "nacos_config"
    user: "root"
    # 引用 Secret，官方推荐方式
    passwordFromSecret:
      name: nacos-mysql-secret
      key: mysql-password
    param: "characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true"

  # JVM 配置（官方生产环境推荐参数）
  jvm:
    xms: 2g
    xmx: 2g
    xmn: 1g

# 资源限制（官方推荐生产配置）
resources:
  requests:
    cpu: 1000m
    memory: 2Gi
  limits:
    cpu: 2000m
    memory: 4Gi

4.3 执行官方集群部署命令

# 官方标准集群部署命令
helm install nacos . -n nacos -f values-cluster.yaml

# 等待所有 Pod 启动（3 个副本均为 Running 状态）
kubectl get pods -n nacos -w

5. 官方标准验证步骤（与文档完全一致）

5.1 检查 Pod 与 Service 状态

# 1. 检查 Pod 状态（单机 1 个，集群 3 个）
kubectl get pods -n nacos

# 2. 检查 Service 状态（确认 LoadBalancer IP/NodePort）
kubectl get svc -n nacos

5.2 访问 Nacos 控制台（官方默认地址）

根据 Service 暴露方式，选择访问路径：

MetalLB 固定 IP（生产环境）：
```
http://10.2.10.103:8848/nacos
```

K3s servicelb NodePort（测试环境）：

# 获取 Node IP
NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[0].address}')
# 访问地址
echo "http://${NODE_IP}:30848/nacos"

官方默认账号密码：nacos / nacos

5.3 功能测试（官方 API）

执行官方文档中的测试命令，验证服务注册与配置管理功能：

# 1. 服务注册
curl -X PUT 'http://<NACOS-IP>:8848/nacos/v1/ns/instance?serviceName=nacos.naming.serviceName&ip=20.18.7.10&port=8080'

# 2. 服务发现
curl -X GET 'http://<NACOS-IP>:8848/nacos/v1/ns/instance/list?serviceName=nacos.naming.serviceName'

# 3. 发布配置
curl -X POST "http://<NACOS-IP>:8848/nacos/v1/cs/configs?dataId=nacos.cfg.dataId&group=test&content=helloWorld"

# 4. 获取配置
curl -X GET "http://<NACOS-IP>:8848/nacos/v1/cs/configs?dataId=nacos.cfg.dataId&group=test"

6. 官方标准运维操作

6.1 升级 Nacos（官方流程）

# 1. 拉取官方最新 Chart
git pull origin master

# 2. 修改 values 文件中的镜像版本（如 v2.4.0 → v2.4.1）
# 3. 执行升级命令
helm upgrade nacos . -n nacos -f values-cluster.yaml

6.2 扩缩容集群（官方命令）

# 集群扩缩容（修改副本数）
helm upgrade nacos . -n nacos --set global.replicaCount=5 -f values-cluster.yaml

6.3 卸载 Nacos（官方命令）

# 卸载 Helm 应用
helm uninstall nacos -n nacos

# 可选：删除持久化数据（谨慎操作）
kubectl delete pvc -n nacos --all

7. 官方故障排除（参考文档）

根据官方文档，常见问题排查步骤如下：

问题现象	官方排查方法
Pod 启动失败（`CrashLoopBackOff`）	查看 Pod 日志：`kubectl logs -f <pod-name> -n nacos`；检查 JVM 内存配置是否过小
PVC 状态 `Pending`	确认 Longhorn 存储类可用；检查 Longhorn 节点是否就绪：`kubectl get pods -n longhorn-system`
LoadBalancer IP 未分配	MetalLB 环境：检查 IP 池配置；K3s servicelb 环境：确认 Service 类型为 `LoadBalancer`，使用 NodePort 访问
集群节点无法通信	检查 9848/9849 端口是否开放；确认 MySQL 连接正常

附录：官方资源链接

Nacos 官方 Kubernetes 快速启动文档：https://nacos.io/docs/latest/quickstart/quick-start-kubernetes/
Nacos 官方 Helm Chart 仓库：https://github.com/nacos-group/nacos-k8s/tree/master/helm/nacos
Nacos 官方故障排查指南：https://nacos.io/docs/latest/faq/faq-k8s/

概述​

目标​

前置条件​

核心流程：官方标准部署步骤​

1. 获取官方 Helm Chart 包（官方第一步）​

2. 部署前准备（官方标准操作）​

2.1 创建命名空间​

2.2 配置持久化存储（对接 Longhorn）​

2.3 确认 LoadBalancer 组件​

3. 部署单机模式 Nacos（官方开发测试环境）​

3.1 创建官方标准配置文件 values-standalone.yaml​

3.2 执行官方部署命令​

4. 部署集群模式 Nacos（官方生产环境）​

4.1 前置步骤：部署 MySQL 并初始化（官方要求）​

4.2 创建官方集群配置文件 values-cluster.yaml​

4.3 执行官方集群部署命令​

5. 官方标准验证步骤（与文档完全一致）​

5.1 检查 Pod 与 Service 状态​

5.2 访问 Nacos 控制台（官方默认地址）​

5.3 功能测试（官方 API）​

6. 官方标准运维操作​

6.1 升级 Nacos（官方流程）​

6.2 扩缩容集群（官方命令）​

6.3 卸载 Nacos（官方命令）​

7. 官方故障排除（参考文档）​

附录：官方资源链接​

概述

目标