9.3.2 配置格式与灰度发布

在 Nacos 配置管理中，配置格式直接影响可读性、解析效率与变更风险控制。常见格式包括 Properties、YAML、JSON、XML 与文本模板。建议同一应用同一环境尽量使用单一格式，并建立校验、审计、回滚机制。灰度发布用于降低配置变更风险，可通过命名空间、分组、数据ID 或客户端标签实现“部分实例先行、观察稳定后全量”。

原理草图（配置格式校验与灰度流转）：

配置格式示例与命令（同一应用使用统一格式）：
- Properties 示例（适合简单键值）

# 文件：/opt/nacos/config/app.properties
app.name=order-service
app.timeout=2000
feature.gray=false

YAML 示例（分层清晰）

# 文件：/opt/nacos/config/app.yaml
app:
  name: order-service
  timeout: 2000
feature:
  gray: false

JSON 示例（结构化强）

// 文件：/opt/nacos/config/app.json
{
  "app": {
    "name": "order-service",
    "timeout": 2000
  },
  "feature": {
    "gray": false
  }
}

Nacos 发布配置（以 HTTP API 为例，需保证 Nacos 已运行并可访问）：

# 变量准备
NACOS_ADDR="http://127.0.0.1:8848"
NAMESPACE_ID="public"
GROUP="DEFAULT_GROUP"
DATA_ID="order-service.yaml"

# 发布 YAML 配置
curl -sS -X POST "${NACOS_ADDR}/nacos/v1/cs/configs" \
  -d "dataId=${DATA_ID}" \
  -d "group=${GROUP}" \
  -d "namespaceId=${NAMESPACE_ID}" \
  --data-urlencode "content=$(cat /opt/nacos/config/app.yaml)" \
  -d "type=yaml"

# 预期输出：true（表示发布成功）

灰度发布实操示例（命名空间隔离 + 客户端标签）：

# 1) 创建灰度命名空间（仅示例，生产建议使用 UI 创建并记录ID）
curl -sS -X POST "${NACOS_ADDR}/nacos/v1/console/namespaces" \
  -d "customNamespaceId=gray-ns" \
  -d "namespaceName=gray-namespace" \
  -d "namespaceDesc=for gray release"

# 2) 向灰度命名空间发布新配置（仅灰度实例订阅此命名空间）
curl -sS -X POST "${NACOS_ADDR}/nacos/v1/cs/configs" \
  -d "dataId=${DATA_ID}" \
  -d "group=${GROUP}" \
  -d "namespaceId=gray-ns" \
  --data-urlencode "content=$(cat /opt/nacos/config/app.yaml)" \
  -d "type=yaml"

# 3) 客户端使用灰度命名空间启动（示例为 Java 客户端启动参数）
# -Dnacos.namespace=gray-ns -Dnacos.server-addr=127.0.0.1:8848

配置格式校验示例（本地校验再发布，避免解析错误）：

# YAML 校验（需要安装 yq 或 python pyyaml）
python3 - <<'PY'
import yaml,sys
with open('/opt/nacos/config/app.yaml') as f:
    yaml.safe_load(f)
print("YAML OK")
PY

# JSON 校验
python3 -m json.tool /opt/nacos/config/app.json >/dev/null && echo "JSON OK"

客户端动态刷新示例（以 Spring Cloud Alibaba 为例，监听配置变更）：

# 文件：bootstrap.yaml
spring:
  application:
    name: order-service
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848
        namespace: public
        group: DEFAULT_GROUP
        file-extension: yaml

// 示例：动态刷新注解（需引入 spring-cloud-starter-alibaba-nacos-config）
@RefreshScope
@RestController
public class FeatureController {
    @Value("${feature.gray:false}")
    private boolean gray;

    @GetMapping("/feature")
    public String feature() {
        return "gray=" + gray;
    }
}

灰度策略要点与命令说明：
- 命名空间隔离：灰度环境独立命名空间，避免误影响生产。
- 分组隔离：同命名空间内通过 group 区分（如 GRAY_GROUP）。
- 数据ID拆分：关键开关独立数据ID，减少影响面。
- 客户端标签：结合服务注册实例标签选择性订阅。

排错清单（含命令与预期）：
1. 发布失败（返回 false 或 403）

# 检查 Nacos 是否可达
curl -sS "${NACOS_ADDR}/nacos" | head -n 1
# 若无响应，检查 Nacos 进程与端口
ss -lntp | grep 8848

配置不生效（客户端未刷新）

# 检查客户端是否订阅正确命名空间/分组
# 以 Java 启动参数为例
ps -ef | grep nacos | grep namespace
# 检查配置是否实际存在
curl -sS "${NACOS_ADDR}/nacos/v1/cs/configs?dataId=${DATA_ID}&group=${GROUP}&namespaceId=${NAMESPACE_ID}"

YAML 解析错误导致客户端启动失败

# 本地先校验 YAML，避免缩进错误
python3 - <<'PY'
import yaml,sys
with open('/opt/nacos/config/app.yaml') as f:
    yaml.safe_load(f)
print("YAML OK")
PY

练习：
1. 使用 YAML 格式发布配置，修改 feature.gray 为 true，验证接口 /feature 是否动态变化。
2. 创建灰度命名空间 gray-ns，只让一台实例订阅该命名空间，观察灰度实例与非灰度实例配置差异。
3. 将关键开关拆分为独立数据ID（如 feature-toggle.yaml），验证单独回滚不影响其他配置。