跳到主要内容

配置映射最佳实践

本文档提供GeniSpace任务调度系统中配置映射（ConfigMap）的最佳实践指南，帮助您高效管理任务、工具和工作流的配置。

系统架构概述​

GeniSpace采用分层配置管理架构：

┌─────────────────────────────────────────────────────────────┐
│                    任务执行层 (TaskWorker)                    │
├─────────────────────────────────────────────────────────────┤
│                  工作流引擎 (WorkflowEngine)                  │
├─────────────────────────────────────────────────────────────┤
│              节点执行层 (Operators/Agents)                   │
├─────────────────────────────────────────────────────────────┤
│                配置管理层 (ConfigMap Service)                │
└─────────────────────────────────────────────────────────────┘

配置流转机制​

  1. 任务级配置 → TaskWorker → WorkflowEngine
  2. 工作流配置 → 节点输入解析 → 环境变量注入
  3. 工具配置 → 运行时配置合并 → 执行上下文

核心配置场景​

1. 外部服务配置​

用途: 配置AI服务、数据库、消息队列等外部服务连接信息

name: "external-services-config"
description: "外部服务连接配置"
variables:
  DATABASE_URL:
    value: "postgresql://user:pass@db:5432/genitask"
    description: "数据库连接字符串"
    isSecret: true
  
  DASHSCOPE_API_KEY:
    value: "sk-xxx"
    description: "通义千问API密钥"
    isSecret: true
  
  OPENAI_API_KEY:
    value: "sk-xxx"
    description: "OpenAI API密钥"
    isSecret: true
  
  SENDGRID_API_KEY:
    value: "SG.xxx"
    description: "SendGrid邮件服务API密钥"
    isSecret: true
  
  REDIS_URL:
    value: "redis://localhost:6379"
    description: "Redis缓存连接地址"

2. 工具运行时配置​

用途: 为工具配置API服务、数据库连接等运行环境

name: "operator-runtime-config"
description: "工具运行时配置"
variables:
  API_SERVICE_URL:
    value: "http://api-service:3000"
    description: "API服务地址"
  
  DATABASE_URL:
    value: "postgresql://user:pass@db:5432/genitask"
    description: "数据库连接字符串"
    isSecret: true
  
  DASHSCOPE_API_KEY:
    value: "sk-xxx"
    description: "通义千问API密钥"
    isSecret: true

3. 工作流节点配置​

用途: 为工作流中的AI节点、数据处理节点配置参数

name: "workflow-nodes-config"
description: "工作流节点配置"
variables:
  DEFAULT_MODEL:
    value: "gpt-4"
    description: "默认AI模型"
  
  MAX_TOKENS:
    value: "4000"
    description: "最大token数"
  
  BATCH_SIZE:
    value: "100"
    description: "批处理大小"
  
  SMTP_HOST:
    value: "smtp.example.com"
    description: "邮件服务器地址"
  
  SMTP_PASSWORD:
    value: "email_password"
    description: "邮件账户密码"
    isSecret: true

4. 容器化节点配置​

用途: 为容器化工具配置运行环境

name: "container-runtime-config"
description: "容器化节点运行配置"
variables:
  # Docker配置
  DOCKER_SOCKET:
    value: "/var/run/docker.sock"
    description: "Docker Socket路径"
  
  # Kubernetes配置
  KUBE_CONFIG_PATH:
    value: "/etc/kubernetes/config"
    description: "Kubernetes配置文件路径"
  
  KUBE_NAMESPACE:
    value: "genitask"
    description: "Kubernetes命名空间"
  
  # Railway配置
  RAILWAY_API_KEY:
    value: "railway_key_xxx"
    description: "Railway API密钥"
    isSecret: true
  
  RAILWAY_PROJECT_ID:
    value: "project_123"
    description: "Railway项目ID"
  
  # 资源限制
  DEFAULT_CPU_LIMIT:
    value: "1000m"
    description: "默认CPU限制"
  
  DEFAULT_MEMORY_LIMIT:
    value: "512Mi"
    description: "默认内存限制"

5. 环境特定配置​

用途: 区分开发、测试、生产环境的配置

# 生产环境配置
name: "production-env-config"
description: "生产环境配置"
variables:
  NODE_ENV:
    value: "production"
    description: "运行环境"
  
  LOG_LEVEL:
    value: "error"
    description: "日志级别"
  
  HEALTH_CHECK_INTERVAL:
    value: "30000"
    description: "健康检查间隔(毫秒)"
  
  HEARTBEAT_INTERVAL:
    value: "30000"
    description: "心跳间隔(毫秒)"
  
  # 生产数据库
  PROD_DATABASE_URL:
    value: "postgresql://prod_user:prod_pass@prod-db:5432/genitask_prod"
    description: "生产数据库连接"
    isSecret: true
  
  # 生产Redis
  PROD_REDIS_URL:
    value: "redis://prod-redis:6379"
    description: "生产Redis连接"
    isSecret: true

---
# 开发环境配置
name: "development-env-config"
description: "开发环境配置"
variables:
  NODE_ENV:
    value: "development"
    description: "运行环境"
  
  LOG_LEVEL:
    value: "debug"
    description: "日志级别"
  
  LOG_TASK_TO_FILE:
    value: "true"
    description: "是否记录任务到文件"
  
  # 开发数据库
  DEV_DATABASE_URL:
    value: "postgresql://dev_user:dev_pass@localhost:5432/genitask_dev"
    description: "开发数据库连接"
  
  # 开发Redis
  DEV_REDIS_URL:
    value: "redis://localhost:6379"
    description: "开发Redis连接"

配置使用模式​

1. 在工作流节点中引用配置​

使用 {{变量名}} 格式在节点配置中引用：

// 节点配置示例
{
  "type": "api-call",
  "config": {
    "url": "{{API_SERVICE_URL}}/users",
    "headers": {
      "Authorization": "Bearer {{API_TOKEN}}"
    },
    "timeout": "{{REQUEST_TIMEOUT}}"
  }
}

2. 在数据流中引用环境变量​

使用 env.变量名 格式引用：

// 边配置示例
{
  "source": "node1:output",
  "target": "node2:input", 
  "dataPath": "env.DATABASE_HOST"
}

3. 在工具代码中访问配置​

通过 context.env 访问配置变量：

// 工具代码示例
async execute(inputs, context) {
  const apiUrl = context.env.API_SERVICE_URL;
  const apiKey = context.env.API_KEY;
  
  // 使用配置执行业务逻辑
  const response = await axios.get(`${apiUrl}/data`, {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });
  
  return response.data;
}

配置优先级​

GeniSpace遵循以下配置优先级（从高到低）：

  1. 任务直接配置 - 在Task的envVars数组中直接定义的变量
  2. 工具绑定配置映射 - 工具绑定的特定配置映射
  3. 默认配置映射 - 标记为默认的全局配置映射

优先级示例​

# 默认配置映射 (最低优先级)
name: "global-config"
isDefault: true
variables:
  LOG_LEVEL: "info"
  API_URL: "https://api.service.com"

# 工具绑定配置映射 (中等优先级)  
name: "operator-config"
variables:
  LOG_LEVEL: "debug"  # 覆盖默认配置
  DB_HOST: "db.operator.internal"

# 任务直接配置 (最高优先级)
# 在任务定义中：
envVars: [
  {
    "key": "LOG_LEVEL", 
    "value": "warn"  # 覆盖所有其他配置
  }
]

组织策略​

按功能分组（推荐）​

├── infrastructure-config    # 基础设施配置
├── runtime-config          # 运行时配置  
├── service-config          # 服务配置
└── environment-config      # 环境配置

按业务域分组​

├── auth-service-config     # 认证服务配置
├── payment-service-config  # 支付服务配置
├── notification-config     # 通知服务配置
└── data-processing-config  # 数据处理配置

命名规范​

配置映射命名​

格式：{功能}-{用途}-config

示例：

  • task-scheduler-config - 任务调度配置
  • ai-service-config - AI服务配置
  • database-connection-config - 数据库连接配置

配置变量命名​

格式：{服务}_{类别}_{名称}

示例：

# 数据库相关
DB_HOST: "localhost"
DB_PORT: "5432" 
DB_PASSWORD: "secret"

# API相关
API_SERVICE_URL: "http://api:3000"
API_TIMEOUT: "30"
API_KEY: "secret123"

# 任务相关  
TASK_MAX_RETRIES: "3"
TASK_TIMEOUT: "1800"

安全最佳实践​

1. 敏感信息管理​

  • 将密码、API密钥等标记为敏感信息
  • 使用 isSecret: true 标记敏感变量
  • 不要在描述中包含敏感信息
variables:
  DATABASE_PASSWORD:
    value: "super_secret_password"
    description: "数据库连接密码"
    isSecret: true
  
  API_KEY:
    value: "sk-xxx"
    description: "API访问密钥"
    isSecret: true

2. 访问控制​

  • 每个团队只能访问自己的配置映射
  • 合理使用默认配置映射和绑定配置映射
  • 定期审查配置访问权限

常见使用模式​

1. 环境区分配置​

# 生产环境
name: "production-config"
variables:
  NODE_ENV: "production"
  LOG_LEVEL: "error"
  DATABASE_URL: "postgresql://prod-db:5432/app"

# 开发环境  
name: "development-config"
variables:
  NODE_ENV: "development"
  LOG_LEVEL: "debug"
  DATABASE_URL: "postgresql://localhost:5432/app_dev"

2. 服务特定配置​

# 认证服务配置
name: "auth-service-config"
variables:
  JWT_SECRET: "jwt_secret_key"
  TOKEN_EXPIRATION: "24h"
  OAUTH_CLIENT_ID: "oauth_client_id"

# 通知服务配置
name: "notification-config"  
variables:
  SMTP_HOST: "smtp.example.com"
  SMTP_PORT: "587"
  SMTP_USER: "noreply@example.com"

3. 功能开关配置​

name: "feature-toggles"
variables:
  ENABLE_NEW_DASHBOARD: "true"
  MAINTENANCE_MODE: "false"
  MAX_UPLOAD_SIZE_MB: "100"
  ENABLE_DEBUG_MODE: "false"

维护建议​

1. 定期备份​

  • 使用导出功能定期备份重要配置
  • 在重大变更前先备份现有配置
  • 建立配置变更记录

2. 配置验证​

  • 导入配置前仔细检查YAML格式
  • 验证敏感信息是否正确标记
  • 测试配置变更的影响范围

3. 文档维护​

  • 为每个配置映射添加清晰的描述
  • 为配置变量添加有意义的说明
  • 保持配置文档与实际使用同步

故障排查​

常见问题​

  1. 配置未生效

    • 检查配置优先级是否正确
    • 确认配置映射是否正确绑定
    • 验证变量名是否拼写正确

  2. 敏感信息泄露

    • 确保敏感变量标记为 isSecret: true
    • 检查日志中是否意外输出敏感信息
    • 定期更新敏感配置

  3. 配置冲突

    • 理解配置优先级规则
    • 检查是否有重复的变量名
    • 使用搜索功能快速定位配置

通过遵循这些最佳实践，您可以在GeniSpace系统中建立高效、安全的配置管理体系。