@alanwang-merit/meritdata-platform-skill-package 1.0.9 → 1.0.11

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

@@ -1,203 +0,0 @@
-# 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)

package/skills/meritdata-nacos-importer/references/yaml-spec.md

@@ -1,296 +0,0 @@
-# YAML/Properties 规范（nacos-importer）
-
-> 导入 Nacos 的配置文件规范。
-
----
-
-## 1. YAML 文件规范
-
-### 1.1 顶级结构
-
-```yaml
-# 一级 key 通常是 spring / server / meritdata / logging 等
-spring:
-  application:
-    name: my-2nd-service
-
-server:
-  port: 8080
-
-meritdata:
-  bpm:
-    enabled: true
-
-logging:
-  level:
-    com.example.order: DEBUG
-```
-
-### 1.2 缩进
-
-✅ **必须**：2 空格缩进
-❌ 禁止：Tab 缩进
-
-### 1.3 注释
-
-```yaml
-# 注释行
-spring:
-  # 嵌套注释
-  datasource:
-    url: jdbc:mysql://127.0.0.1:3306/order_dev  # 行尾注释
-```
-
-### 1.4 多行字符串
-
-```yaml
-# ✅ 用 | 保留换行
-description: |
-  这是多行
-  描述
-
-# ✅ 用 > 折叠换行
-summary: >-
-  这是长字符串
-  折叠为一行
-```
-
-## 2. 数据类型
-
-### 2.1 字符串
-
-```yaml
-# ✅ 显式引号
-name: "my-service"
-
-# ✅ 不带引号
-name: my-service
-
-# ✅ 含特殊字符必须引号
-pattern: "^[a-z]+$"
-```
-
-### 2.2 数字
-
-```yaml
-port: 8080
-max-pool-size: 20
-timeout: 30.5
-```
-
-### 2.3 布尔
-
-```yaml
-enabled: true
-disabled: false
-```
-
-### 2.4 列表
-
-```yaml
-# 短列表
-servers:
-  - 127.0.0.1:8848
-  - 127.0.0.1:8849
-
-# 嵌套列表
-endpoints:
-  - name: order
-    url: /api/v1/orders
-  - name: user
-    url: /api/v1/users
-```
-
-### 2.5 Map
-
-```yaml
-# 行内
-datasource: {url: jdbc:mysql://..., username: root}
-
-# 展开（推荐）
-datasource:
-  url: jdbc:mysql://...
-  username: root
-```
-
-### 2.6 空值
-
-```yaml
-# ✅ null / ~ / 不写
-password: null
-password: ~
-
-# ✅ 空字符串
-description: ""
-```
-
-## 3. ❌ 禁止使用
-
-### 3.1 ❌ YAML 锚点
-
-```yaml
-# ❌ 错：Nacos 不支持锚点
-defaults: &defaults
-  timeout: 30
-service-a:
-  <<: *defaults
-  url: /a
-```
-
-✅ 复制配置：
-
-```yaml
-service-a:
-  timeout: 30
-  url: /a
-```
-
-### 3.2 ❌ 文档分隔符
-
-```yaml
-# ❌ 错：Nacos 解析报错
-spring:
-  profiles: dev
----
-spring:
-  profiles: test
-```
-
-✅ 拆成多个文件。
-
-### 3.3 ❌ 复杂模板
-
-```yaml
-# ❌ 错：模板引擎语法
-url: ${DB_HOST:127.0.0.1}:${DB_PORT:3306}
-```
-
-✅ Nacos 用占位符在应用端替换：
-
-```yaml
-# Nacos 配置
-url: jdbc:mysql://${DB_HOST:127.0.0.1}:${DB_PORT:3306}/order_dev
-
-# 应用启动时传环境变量
-java -jar app.jar --DB_HOST=mysql.prod
-```
-
-## 4. Properties 文件规范
-
-### 4.1 基本格式
-
-```properties
-# 注释
-spring.datasource.url=jdbc:mysql://127.0.0.1:3306/order_dev
-spring.datasource.username=root
-spring.datasource.password=root
-```
-
-### 4.2 多行
-
-```properties
-# ✅ 用反斜杠续行
-description=这是一个很长的\
-              多行描述
-
-# ✅ 用 value 包含换行
-description=line1\nline2
-```
-
-### 4.3 特殊字符
-
-```properties
-# ✅ 用反斜杠转义
-url=jdbc:mysql://host\:port/db
-
-# ❌ 错：直接写特殊字符
-url=jdbc:mysql://host:port/db
-```
-
-## 5. 配置大小限制
-
-| 项 | 限制 |
-|----|------|
-| 单文件最大 | 100KB（Nacos 默认）|
-| 单 key 长度 | ≤ 1MB |
-| 嵌套层级 | ≤ 5 层 |
-
-超过需拆分：
-
-```yaml
-# ❌ 错：单文件超大
-my-2nd-service.yaml  # 5MB
-
-# ✅ 正确：按业务拆分
-my-2nd-service-db.yaml        # DB
-my-2nd-service-redis.yaml     # Redis
-my-2nd-service-mq.yaml        # MQ
-my-2nd-service-business.yaml  # 业务配置
-```
-
-## 6. 敏感信息
-
-### 6.1 ❌ 明文密码
-
-```yaml
-# ❌ 错
-spring:
-  datasource:
-    password: MyP@ssw0rd!
-```
-
-✅ 用 Nacos Config 加密：
-
-```yaml
-spring:
-  datasource:
-    password: ENC(xxx...)  # 加密值
-```
-
-或环境变量：
-
-```yaml
-spring:
-  datasource:
-    password: ${DB_PASSWORD}
-```
-
-### 6.2 ❌ 提交敏感信息到 git
-
-```bash
-# 检查
-git secrets --scan
-# 或
-grep -rE 'password.*=.*[a-zA-Z0-9]{8,}' configs/
-```
-
-## 7. 命名规范
-
-### 7.1 DataId
-
-```
-<spring.application.name>[-<suffix>].<format>
-```
-
-✅ `my-2nd-service.yaml` / `my-2nd-service-redis.yaml`
-❌ `MY-2ND-SERVICE.YAML`（大写）
-
-### 7.2 Group
-
-默认 `DEFAULT_GROUP`，灰度用 `GRAY_<日期>`。
-
-```
-DEFAULT_GROUP               # 默认
-GRAY_20260907               # 灰度
-```
-
-### 7.3 Key（Properties）
-
-✅ 全小写 + 点分隔：`spring.datasource.url`
-❌ 驼峰：`spring.datasource.jdbcUrl`
-
-## 8. 关联阅读
-
-- [guide.md](guide.md) — 导入指南
-- [gray-publish.md](gray-publish.md) — 灰度发布
-- [SKILL.md](../SKILL.md)