YAML格式指南

本指南详细介绍配置映射支持的YAML格式和语法规则，帮助您高效地导入和导出配置数据。

支持的YAML格式

系统支持两种YAML格式，您可以根据使用场景选择合适的格式：

1. 简化格式（推荐）

简化格式专为配置映射设计，支持完整的功能特性，包括变量描述和敏感信息标记。

基本结构：

name: "配置映射名称"
description: "配置映射描述"
variables:
  变量名:
    value: "变量值"
    description: "变量描述"
    isSecret: false

完整示例：

name: "auth-service"
description: "认证服务配置"
variables:
  JWT_SECRET_KEY:
    value: "your-very-secret-jwt-key-here"
    description: "JWT签名密钥"
    isSecret: true
  TOKEN_EXPIRATION:
    value: "24h"
    description: "令牌过期时间"
    isSecret: false
  OAUTH_CLIENT_ID:
    value: "oauth-client-12345"
    description: "OAuth客户端ID"
  OAUTH_CLIENT_SECRET:
    value: "oauth-secret-67890"
    description: "OAuth客户端密钥"
    isSecret: true
  ENABLE_2FA:
    value: "true"
    description: "是否启用双因子认证"

2. Kubernetes ConfigMap格式

标准的Kubernetes ConfigMap格式，适合与K8s环境集成。

基本结构：

apiVersion: v1
kind: ConfigMap
metadata:
  name: "配置映射名称"
data:
  变量名: "变量值"

完整示例：

apiVersion: v1
kind: ConfigMap
metadata:
  name: "database-config"
  labels:
    app: "my-application"
    environment: "production"
data:
  DATABASE_HOST: "prod-db.example.com"
  DATABASE_PORT: "5432"
  DATABASE_NAME: "myapp_production"
  DATABASE_USER: "app_user"
  REDIS_URL: "redis://redis.example.com:6379"
  MAX_CONNECTIONS: "100"

格式对比

特性	简化格式	Kubernetes格式
变量描述	✅ 支持	❌ 不支持
敏感信息标记	✅ 支持	❌ 不支持
配置映射描述	✅ 支持	❌ 不支持
K8s兼容性	❌ 不兼容	✅ 完全兼容
文件大小	较大	较小
可读性	更好	一般

YAML语法规则

基本语法

1. 缩进：使用2个空格进行缩进，不要使用Tab键
2. 键值对：使用冒号和空格分隔 key: value
3. 字符串：建议使用双引号包围字符串值
4. 布尔值：使用 true 或 false
5. 注释：使用 # 开始注释行

字符串处理

普通字符串：

SIMPLE_VALUE: "hello world"

多行字符串：

MULTI_LINE_VALUE: |
  这是一个多行字符串
  第二行内容
  第三行内容

包含特殊字符的字符串：

SPECIAL_CHARS: "包含\"引号\"和\n换行符的字符串"
DATABASE_URL: "postgresql://user:pass@host:5432/db?sslmode=require"

JSON格式的字符串：

JSON_CONFIG: '{"timeout": 30, "retries": 3, "endpoints": ["api1", "api2"]}'

数据类型示例

name: "data-types-example"
description: "各种数据类型的示例"
variables:
  # 字符串类型
  STRING_VALUE:
    value: "这是一个字符串"
    description: "字符串示例"
  
  # 数字类型
  NUMBER_VALUE:
    value: "12345"
    description: "数字示例"
  
  # 布尔类型
  BOOLEAN_VALUE:
    value: "true"
    description: "布尔值示例"
  
  # URL类型
  URL_VALUE:
    value: "https://api.example.com/v1"
    description: "URL示例"
  
  # 密码类型
  PASSWORD_VALUE:
    value: "super-secret-password"
    description: "密码示例"
    isSecret: true
  
  # JSON配置
  JSON_VALUE:
    value: '{"host": "localhost", "port": 3000}'
    description: "JSON配置示例"

实用案例

案例1：微服务配置

name: "microservice-config"
description: "微服务通用配置"
variables:
  # 服务配置
  SERVICE_NAME:
    value: "user-service"
    description: "服务名称"
  
  SERVICE_PORT:
    value: "8080"
    description: "服务端口"
  
  SERVICE_VERSION:
    value: "1.2.3"
    description: "服务版本"
  
  # 数据库配置
  DATABASE_URL:
    value: "postgresql://localhost:5432/userdb"
    description: "数据库连接URL"
    isSecret: true
  
  DATABASE_POOL_SIZE:
    value: "20"
    description: "数据库连接池大小"
  
  # 缓存配置
  REDIS_URL:
    value: "redis://localhost:6379"
    description: "Redis连接URL"
  
  CACHE_TTL:
    value: "3600"
    description: "缓存过期时间（秒）"
  
  # 日志配置
  LOG_LEVEL:
    value: "info"
    description: "日志级别"
  
  LOG_FORMAT:
    value: "json"
    description: "日志格式"

案例2：第三方服务集成

name: "external-services"
description: "第三方服务配置"
variables:
  # 邮件服务
  SMTP_HOST:
    value: "smtp.gmail.com"
    description: "SMTP服务器地址"
  
  SMTP_PORT:
    value: "587"
    description: "SMTP服务器端口"
  
  SMTP_USER:
    value: "noreply@example.com"
    description: "SMTP用户名"
  
  SMTP_PASSWORD:
    value: "smtp-app-password"
    description: "SMTP密码"
    isSecret: true
  
  # 对象存储
  S3_BUCKET_NAME:
    value: "my-app-storage"
    description: "S3存储桶名称"
  
  S3_ACCESS_KEY:
    value: "AKIAIOSFODNN7EXAMPLE"
    description: "S3访问密钥ID"
    isSecret: true
  
  S3_SECRET_KEY:
    value: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    description: "S3秘密访问密钥"
    isSecret: true
  
  S3_REGION:
    value: "us-west-2"
    description: "S3区域"
  
  # 支付服务
  STRIPE_PUBLIC_KEY:
    value: "pk_test_51234567890"
    description: "Stripe公钥"
  
  STRIPE_SECRET_KEY:
    value: "sk_test_51234567890"
    description: "Stripe私钥"
    isSecret: true
  
  STRIPE_WEBHOOK_SECRET:
    value: "whsec_1234567890"
    description: "Stripe Webhook密钥"
    isSecret: true

案例3：功能开关配置

name: "feature-toggles"
description: "功能开关配置"
variables:
  # 新功能开关
  ENABLE_NEW_DASHBOARD:
    value: "true"
    description: "启用新版仪表板"
  
  ENABLE_DARK_MODE:
    value: "true"
    description: "启用暗色主题"
  
  ENABLE_NOTIFICATIONS:
    value: "false"
    description: "启用推送通知"
  
  # 性能相关
  MAX_UPLOAD_SIZE_MB:
    value: "100"
    description: "最大上传文件大小（MB）"
  
  REQUEST_TIMEOUT_SECONDS:
    value: "30"
    description: "请求超时时间（秒）"
  
  MAX_CONCURRENT_REQUESTS:
    value: "1000"
    description: "最大并发请求数"
  
  # 维护模式
  MAINTENANCE_MODE:
    value: "false"
    description: "维护模式开关"
  
  MAINTENANCE_MESSAGE:
    value: "系统正在维护中，预计30分钟后恢复"
    description: "维护模式提示信息"
  
  # A/B测试
  AB_TEST_NEW_CHECKOUT:
    value: "50"
    description: "新结账流程A/B测试比例（%）"
  
  AB_TEST_RECOMMENDATION_ENGINE:
    value: "25"
    description: "推荐引擎A/B测试比例（%）"

导入导出操作

导出配置

1. 在配置变量管理界面点击"导出YAML"按钮
2. 选择导出格式：
   • 简化格式：包含完整的变量信息和描述
   • Kubernetes格式：标准K8s ConfigMap格式
3. 系统自动下载YAML文件

导入配置

1. 点击"导入YAML"按钮打开导入对话框
2. 选择YAML格式和导入选项
3. 上传文件的三种方式：
   • 拖拽上传：直接拖拽.yaml或.yml文件到上传区域
   • 点击选择：点击"选择文件"按钮浏览文件
   • 手动输入：直接在文本框中编辑YAML内容
4. 系统自动检测格式并预填充内容
5. 点击"导入配置"完成导入

导入选项说明

• 覆盖已存在的变量：
  • ✅ 勾选：导入时会覆盖同名的现有变量
  • ❌ 不勾选：跳过同名变量，只导入新变量

常见错误和解决方案

1. 缩进错误

错误示例：

variables:
WRONG_INDENT:  # 缺少缩进
  value: "错误"

正确示例：

variables:
  CORRECT_INDENT:  # 正确的2空格缩进
    value: "正确"

2. 引号使用错误

错误示例：

MIXED_QUOTES:
  value: "包含'单引号'的字符串"  # 可能导致解析错误

正确示例：

PROPER_QUOTES:
  value: "包含\"双引号\"的字符串"  # 正确转义

3. 特殊字符处理

错误示例：

DATABASE_URL:
  value: postgresql://user:p@ssw0rd@host:5432/db  # @符号未转义

正确示例：

DATABASE_URL:
  value: "postgresql://user:p@ssw0rd@host:5432/db"  # 使用引号包围

4. 布尔值格式

错误示例：

ENABLE_FEATURE:
  value: True  # 大写T

正确示例：

ENABLE_FEATURE:
  value: "true"  # 小写，建议用引号

最佳实践

1. 格式选择建议

• 使用简化格式：当您需要详细的变量描述和敏感信息标记时
• 使用K8s格式：当您需要与Kubernetes环境集成时
• 混合使用：可以根据不同配置映射的用途选择不同格式

2. 命名规范

# 推荐的变量命名
variables:
  DATABASE_URL:          # 全大写，下划线分隔
    value: "..."
  
  SMTP_HOST:             # 使用前缀区分服务
    value: "..."
  
  ENABLE_NEW_FEATURE:    # 布尔值使用ENABLE_前缀
    value: "true"
  
  MAX_UPLOAD_SIZE_MB:    # 包含单位信息
    value: "100"

3. 敏感信息处理

variables:
  # 明确标记敏感信息
  DATABASE_PASSWORD:
    value: "super-secret-password"
    description: "数据库密码"
    isSecret: true
  
  API_KEY:
    value: "sk-1234567890abcdef"
    description: "第三方API密钥"
    isSecret: true
  
  # 非敏感信息无需标记
  DATABASE_HOST:
    value: "localhost"
    description: "数据库主机地址"
    isSecret: false  # 可省略，默认为false

4. 文档化建议

name: "well-documented-config"
description: "良好文档化的配置映射示例"
variables:
  # 为每个变量提供清晰的描述
  JWT_SECRET_KEY:
    value: "your-secret-key"
    description: "用于JWT令牌签名的密钥，至少32字符"
    isSecret: true
  
  TOKEN_EXPIRATION:
    value: "24h"
    description: "JWT令牌过期时间，支持格式：1h, 30m, 24h, 7d"
  
  MAX_LOGIN_ATTEMPTS:
    value: "5"
    description: "用户最大登录尝试次数，超过后账户将被锁定"

5. 版本控制

• 导出配置前添加版本注释：

# 配置版本：v1.2.0
# 更新日期：2024-01-15
# 更新说明：添加新的缓存配置
name: "my-config"
description: "应用配置 v1.2.0"
variables:
  # ... 配置内容

验证和测试

1. 语法验证

导入前可以使用在线YAML验证器检查语法：

• YAML Lint
• Online YAML Parser

2. 测试导入

建议在测试环境中先测试YAML导入：

1. 创建测试配置映射
2. 导入YAML文件
3. 验证变量是否正确导入
4. 检查敏感信息标记是否正确

3. 备份策略

• 导入前先导出现有配置作为备份
• 重要配置变更前创建配置映射快照
• 定期备份关键配置映射

故障排除

常见导入错误

1. "YAML格式错误"

   • 检查缩进是否正确（使用2个空格）
   • 确认冒号后有空格
   • 检查引号是否匹配

2. "变量名不符合规范"

   • 变量名只能包含字母、数字和下划线
   • 必须以字母或下划线开头
   • 不能包含空格或特殊字符

3. "文件格式不支持"

   • 确保文件扩展名为.yaml或.yml
   • 检查文件编码是否为UTF-8

4. "导入部分失败"

   • 查看导入结果统计信息
   • 检查是否有重复的变量名
   • 确认"覆盖已存在变量"选项设置

通过遵循本指南的建议和最佳实践，您可以高效地使用YAML格式管理配置映射，确保配置数据的准确性和可维护性。