@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/skills/meritdata-nacos-importer/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: meritdata-nacos-importer
+description: 批量导入 Nacos 配置（YAML/Properties → Nacos 服务）。当用户说"导入 Nacos 配置 / 上线配置 / 批量同步 / 灰度发布"时使用。
+metadata:
+  version: "1.0.0"
+  risk: high
+  layer: L4
+  sub-layer: L4-T
+  stack: tool
+---
+
+# meritdata-nacos-importer
+
+## 触发
+
+- 用户说"导入 Nacos 配置 / 上线配置 / 批量同步"
+- 用户提供 YAML/Properties 文件 + Nacos server + namespace
+- 灰度发布：先把配置推到"灰度命名空间"
+
+## 不触发
+
+- 单个 key 修改（→ Nacos 控制台 / API）
+- 配置中心架构问题（→ `meritdata-platform-nacos-config` skill）
+- 配置变更通知应用（→ `meritdata-platform-nacos-config` §shared-config）
+
+## 前置约束
+
+- 必须有 Nacos 服务地址 + 命名空间 ID + 访问凭证
+- 配置 key 命名遵守 [`rules/nacos-rules.md`](../../rules/nacos-rules.md)
+- 生产导入**必须先灰度**（PROD 命名空间单独审）
+- 大文件（>1MB）禁止推 Nacos（应用 `application-<env>.yml` 拆分）
+
+## 路由
+
+- [guide.md](references/guide.md) — 导入命令 + 工作流
+- [yaml-spec.md](references/yaml-spec.md) — YAML/Properties 文件规范
+- [gray-publish.md](references/gray-publish.md) — 灰度发布流程

package/skills/meritdata-nacos-importer/references/gray-publish.md

@@ -0,0 +1,216 @@
+# 灰度发布流程（nacos-importer）
+
+> Nacos 配置灰度发布的标准流程。
+
+---
+
+## 1. 灰度发布 vs 全量发布
+
+| 维度 | 灰度发布 | 全量发布 |
+|------|---------|---------|
+| 范围 | 2-3 个实例 / 1 个 namespace | 全部实例 |
+| 风险 | 低（出问题只影响少量）| 高 |
+| 时间 | 长（分阶段）| 短（一次性）|
+| 适用 | 重要配置 / 不可逆操作 | 普通配置 / 可回滚 |
+
+## 2. 灰度命名空间
+
+### 2.1 创建
+
+在 Nacos 控制台：
+
+```
+命名空间名: gray-20260907-<变更主题>
+命名空间ID: 自动生成（复制用）
+描述: <变更原因>，操作人：张三
+```
+
+### 2.2 命名规范
+
+```
+gray-<YYYYMMDD>-<变更简述>
+```
+
+例：
+- `gray-20260907-bpm-timeout`
+- `gray-20260907-datasource-url`
+
+## 3. 灰度发布流程
+
+```
+1. 准备
+   ├─ 创建 PR / 评审
+   ├─ 创建 gray-xxx 命名空间
+   └─ 通知相关方
+
+2. 推送灰度
+   └─ nacos-import --namespace=gray-20260907-bpm-timeout
+
+3. 应用接入灰度
+   ├─ @NacosValue(group="gray-20260907-bpm-timeout")
+   └─ 或 spring.cloud.nacos.config.namespace=gray-20260907-bpm-timeout
+
+4. 验证（30 min）
+   ├─ 监控 / 日志 / 业务指标
+   ├─ 1-3 个实例跑灰度
+   └─ 通过 → 5 → 不通过 → 6.1
+
+5. 全量发布
+   ├─ nacos-import --namespace=prod
+   ├─ 监控所有实例
+   └─ 通过 → 6.2 / 不通过 → 6.1
+
+6. 收尾
+   ├─ 6.1 回滚：删除灰度 / 生产配置
+   └─ 6.2 清理：删除灰度命名空间
+```
+
+## 4. 配置示例
+
+### 4.1 应用端按 group 拉取
+
+```java
+@NacosValue(
+    value = "${order.timeout-seconds:30}",
+    group = "gray-20260907-bpm-timeout",  // 灰度
+    autoRefreshed = true
+)
+private int timeoutSeconds;
+```
+
+### 4.2 完整 namespace 切换
+
+```yaml
+# bootstrap.yml
+spring:
+  cloud:
+    nacos:
+      config:
+        namespace: gray-20260907-bpm-timeout  # 灰度
+```
+
+## 5. 监控指标
+
+| 指标 | 正常范围 | 异常处理 |
+|------|---------|---------|
+| 配置拉取成功率 | ≥ 99.9% | < 99% 立即回滚 |
+| 应用启动失败率 | < 0.1% | > 1% 回滚 |
+| 业务 RT (P95) | 持平 | 上升 > 50% 评估 |
+| 业务错误率 | 持平 | 上升 > 0.1% 回滚 |
+| 数据库连接 | 正常 | 异常立即回滚 |
+
+## 6. 回滚策略
+
+### 6.1 立即回滚
+
+```bash
+# 删除灰度命名空间配置（应用自动 fallback 到 prod）
+nacos-import --namespace=gray-20260907-bpm-timeout --skip-existing
+
+# 或手动删除
+curl -X DELETE "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=...&group=..."
+```
+
+### 6.2 全量回滚
+
+```bash
+# 备份当前 prod 配置
+nacos-export --namespace=prod --output=./backup-before-rollback
+
+# 恢复上一个版本
+nacos-import --namespace=prod --input-dir=./backup-before-rollback --skip-existing
+```
+
+## 7. CHANGELOG 模板
+
+```markdown
+## [YYYY-MM-DD] 配置变更
+
+**变更主题**：BPM 流程超时从 30s 改为 60s
+**变更人**：张三
+**灰度 ID**：gray-20260907-bpm-timeout
+**影响范围**：所有 BPM 流程
+
+**变更前**：
+```yaml
+meritdata:
+  bpm:
+    timeout-seconds: 30
+```
+
+**变更后**：
+```yaml
+meritdata:
+  bpm:
+    timeout-seconds: 60
+```
+
+**验证**：
+- 监控：✓ RT 持平
+- 业务：✓ 流程跑通
+- 错误率：✓ 无上升
+
+**回滚**：删除 gray-20260907-bpm-timeout 命名空间
+```
+
+## 8. ❌ 反模式
+
+### 8.1 ❌ 直接改生产命名空间
+
+```
+1. 改 prod/...
+2. 应用立即生效
+3. 出问题没回滚机会
+```
+
+✅ 用灰度命名空间。
+
+### 8.2 ❌ 灰度过长
+
+```
+灰度 3 天 → 没人验证 → 错过最佳窗口
+```
+
+✅ 灰度 ≤ 24h，及时收尾。
+
+### 8.3 ❌ 没有验证指标就全量
+
+```bash
+# ❌ 错
+nacos-import --namespace=prod  # 没验证
+```
+
+✅ 先灰度 → 验证 → 全量。
+
+### 8.4 ❌ 没备份
+
+```bash
+# ❌ 错：导入前没备份
+nacos-import --namespace=prod --input-dir=./new-config
+# 旧配置丢了
+```
+
+✅ 先 `nacos-export` 备份。
+
+## 9. 紧急回滚 SOP
+
+```
+发现生产异常
+  ↓
+1. 立即：删除新推的配置
+   curl -X DELETE "http://.../configs?dataId=..."
+
+2. 应用自动 fallback 到默认值 / 上次配置
+
+3. 通知：群 / 邮件 / 告警
+
+4. 记录事故：时间 / 影响 / 根因
+
+5. 修复 → 重新灰度
+```
+
+## 10. 关联阅读
+
+- [guide.md](guide.md) — 导入指南
+- [yaml-spec.md](yaml-spec.md) — YAML 规范
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-nacos-importer/references/guide.md

@@ -0,0 +1,203 @@
+# Nacos 导入指南（nacos-importer）
+
+> YAML/Properties 文件批量导入 Nacos 服务。
+
+---
+
+## 1. 命令
+
+### 1.1 CLI 工具
+
+```bash
+nacos-import \
+  --server-addr=127.0.0.1:8848 \
+  --namespace=b8a8-xxx-dev \
+  --username=nacos \
+  --password=nacos \
+  --input-dir=./configs/dev \
+  --format=yaml
+```
+
+### 1.2 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--server-addr` | ✅ | Nacos 地址 |
+| `--namespace` | ✅ | 命名空间 ID（不是名称）|
+| `--username` | ✅ | 用户名 |
+| `--password` | ✅ | 密码 |
+| `--input-dir` | ✅ | 输入目录 |
+| `--format` | ✅ | `yaml` / `properties` |
+| `--dry-run` | - | 仅预览，不推送 |
+| `--skip-existing` | - | 跳过已存在 key |
+
+### 1.3 一键命令
+
+```bash
+# 推送到 dev
+./scripts/nacos-import.sh dev
+
+# 推送到生产（必须二次确认）
+./scripts/nacos-import.sh prod --confirm
+```
+
+## 2. 工作流
+
+```
+1. 本地 YAML/Properties 文件
+       ↓
+2. nacos-import CLI
+       ↓
+3. Nacos Open API
+       ↓
+4. Nacos 服务（命名空间隔离）
+       ↓
+5. 应用 @NacosValue / @ConfigurationProperties 拉取
+```
+
+## 3. 输入目录结构
+
+```
+configs/
+├── dev/
+│   ├── my-2nd-service.yaml        ← DataId: my-2nd-service.yaml
+│   ├── my-2nd-service-redis.yaml  ← DataId: my-2nd-service-redis.yaml
+│   └── common-shared.yaml         ← DataId: common-shared.yaml
+├── test/
+└── prod/
+```
+
+**DataId 命名**：`<spring.application.name>[-<suffix>].<format>`
+
+例：`my-2nd-service.yaml`、`my-2nd-service-redis.yaml`
+
+## 4. YAML 文件格式
+
+```yaml
+# configs/dev/my-2nd-service.yaml
+spring:
+  datasource:
+    url: jdbc:mysql://127.0.0.1:3306/order_dev
+    username: order
+    password: order123
+    hikari:
+      maximum-pool-size: 20
+
+server:
+  port: 8080
+
+meritdata:
+  bpm:
+    enabled: true
+```
+
+**注意**：
+
+- ✅ YAML 用 `:` 后空格
+- ✅ 嵌套用缩进
+- ❌ 不要包含 `---` 分隔符
+- ❌ 不要使用 YAML 锚点 `&` `*`（Nacos 不支持）
+
+## 5. 应用端拉取
+
+```yaml
+# bootstrap.yml
+spring:
+  application:
+    name: my-2nd-service
+  cloud:
+    nacos:
+      config:
+        server-addr: 127.0.0.1:8848
+        file-extension: yaml
+        namespace: b8a8-xxx-dev
+```
+
+```java
+@RestController
+public class OrderController {
+
+    @NacosValue(value = "${order.max-amount:10000}", autoRefreshed = true)
+    private BigDecimal maxAmount;
+
+    // ...
+}
+```
+
+## 6. 灰度发布
+
+详见 [gray-publish.md](gray-publish.md)。
+
+简版流程：
+
+```
+1. 准备灰度命名空间（如 gray-20260907）
+2. 把要发布的配置推到灰度命名空间
+3. 通知应用：@NacosValue(group="gray-20260907") 拉灰度
+4. 验证：监控 / 日志 / 业务指标
+5. 通过 → 推到生产命名空间
+6. 回滚 → 直接删除生产 / 灰度配置
+```
+
+## 7. ❌ 常见错误
+
+### 7.1 ❌ 命名空间 ID 错
+
+```
+ERROR: namespace 'dev' not found
+```
+
+✅ 用命名空间 ID（UUID 格式），不是名称。
+
+### 7.2 ❌ DataId 含非法字符
+
+```
+ERROR: dataId 'MY-SERVICE.YAML' invalid
+```
+
+✅ DataId 只允许小写字母、数字、`-`、`.`。
+
+### 7.3 ❌ 配置被覆盖未察觉
+
+```bash
+# ❌ 错：导入后没备份
+nacos-import ...  # 覆盖生产配置
+```
+
+✅ 用 `--skip-existing` 防止覆盖，或先备份：
+
+```bash
+nacos-export --namespace=prod --output=./backup-$(date +%Y%m%d)
+nacos-import --namespace=prod ...
+```
+
+### 7.4 ❌ 大文件超过限制
+
+```
+ERROR: content size 2097152 exceeds limit 102400
+```
+
+✅ 拆分配置：拆成 `my-2nd-service-db.yaml` + `my-2nd-service-redis.yaml` + ...
+
+## 8. 安全规范
+
+### 8.1 ✅ 通过 Nacos Open API
+
+```bash
+curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs" \
+  -d "dataId=my-2nd-service.yaml&group=DEFAULT_GROUP&content=..."
+```
+
+### 8.2 ❌ 不在 Nacos 控制台手动改生产
+
+| ❌ 反模式 | ✅ 正确 |
+|----------|--------|
+| 手动改 Nacos Web | Git 仓库管理 → nacos-importer |
+| 无变更记录 | 有 PR / commit / 操作日志 |
+| 多人手改冲突 | 自动化、单一来源 |
+
+## 9. 关联阅读
+
+- [yaml-spec.md](yaml-spec.md) — YAML 规范
+- [gray-publish.md](gray-publish.md) — 灰度发布
+- [SKILL.md](../SKILL.md)