工作流环境变量使用指南

GeniSpace 工作流引擎提供了强大的环境变量替换功能，允许您在不同环境中使用相同的配置模板，通过环境变量动态替换配置值。环境变量使您能够在不同的工作流执行中重用配置，避免在每个节点中重复设置相同的值。

概述

环境变量替换机制分为两个阶段：

• API 端替换：在任务准备阶段，对 Operator 的 URL 配置进行替换
• Worker 端替换：在任务执行阶段，对节点输入、配置等进行全面替换

环境变量可以集中管理，并在工作流的多个节点中使用，支持在不同环境（开发、测试、生产）中使用相同的配置模板。

环境变量的来源

环境变量可以通过以下三种方式配置，系统会按照优先级自动合并：

1. 任务级环境变量（最高优先级）

在任务配置中直接定义的环境变量，适用于特定任务的所有执行。这种方式适合任务特定的配置或临时覆盖。

{
  "envVars": [
    {
      "key": "DB_HOST",
      "value": "localhost",
      "isSecret": false,
      "description": "数据库主机地址"
    },
    {
      "key": "DB_PASSWORD",
      "value": "secret123",
      "isSecret": true,
      "description": "数据库密码"
    }
  ]
}

2. ConfigMap 绑定（中等优先级）

任务可以绑定一个或多个 ConfigMap，ConfigMap 中的变量会被加载到环境变量中。这种方式适合共享配置和按环境管理配置。

{
  "executionConfig": {
    "configMaps": [
      {
        "id": "config-map-id",
        "name": "production-config"
      }
    ]
  }
}

提示

要了解如何创建和管理 ConfigMap，请参阅 ConfigMap 使用指南。

3. 默认 ConfigMap（最低优先级）

团队级别的默认配置映射，所有任务都可以自动访问。系统会自动加载标记为默认的 ConfigMap。这种方式适合全局通用配置。

提示

要了解如何设置默认 ConfigMap，请参阅 ConfigMap 使用指南。

优先级规则

任务级环境变量 > ConfigMap 绑定 > 默认 ConfigMap

当同一个变量在多个来源中定义时，优先级高的会覆盖优先级低的。这允许您在不同层级灵活地管理配置：

• 全局配置：放在默认 ConfigMap 中
• 环境配置：放在任务绑定的 ConfigMap 中
• 任务特定配置：直接在任务中定义

📖 了解更多：关于配置访问规则的详细说明，请参阅 ConfigMap 配置访问规则。

环境变量替换的两个阶段

阶段一：API 端替换（任务准备阶段）

在任务执行前，API 端会进行环境变量替换，支持在 URL 和 headers 配置中使用环境变量。

替换范围

• ✅ Operator 节点的 URL 配置

  • serverUrl 和 endpoint 配置（构建完整 URL 时）
  • 支持在 URL 的任意位置使用环境变量

• ✅ Operator 节点的 Headers 配置

  • headers 数组中的每个 header 的 value 字段
  • 支持在 header 值中使用环境变量模板

• ❌ 暂不支持

  • 其他配置项（如 timeout、retryPolicy 等）
  • 这些配置项需要在 Worker 端通过模板语法使用

替换格式

使用 {{变量名}} 模板语法：

URL 配置示例：

// 在 Operator 配置中
{
  "serverUrl": "https://{{API_HOST}}",
  "endpoint": "/api/v1/{{RESOURCE}}"
}

// 如果环境变量为：
// API_HOST = "api.example.com"
// RESOURCE = "users"

// 最终构建的 URL 为：
// "https://api.example.com/api/v1/users"

Headers 配置示例：

// 在 Operator 配置中
{
  "headers": [
    {
      "key": "Authorization",
      "value": "Bearer {{API_TOKEN}}"
    },
    {
      "key": "X-API-Key",
      "value": "{{API_KEY}}"
    },
    {
      "key": "Content-Type",
      "value": "application/json"
    }
  ]
}

// 如果环境变量为：
// API_TOKEN = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
// API_KEY = "your-secret-api-key"

// 最终替换后的 headers 为：
// [
//   { "key": "Authorization", "value": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." },
//   { "key": "X-API-Key", "value": "your-secret-api-key" },
//   { "key": "Content-Type", "value": "application/json" }
// ]

替换逻辑

API 端使用 buildUrl 函数构建完整 URL，并在构建过程中替换环境变量：

// 支持的 URL 格式：
// 1. serverUrl + endpoint
"https://{{API_HOST}}" + "/api/{{VERSION}}/users"
// 结果: "https://api.example.com/api/v1/users"

// 2. 完整的 serverUrl（endpoint 为空）
"https://{{API_HOST}}/api/v1/users"
// 结果: "https://api.example.com/api/v1/users"

// 3. endpoint 包含完整 URL
"{{API_BASE_URL}}/users"
// 结果: "https://api.example.com/users"

未找到变量的处理

如果环境变量未找到，保持原模板格式（{{变量名}}），便于调试和问题排查。

阶段二：Worker 端替换（任务执行阶段）

在 Worker 执行工作流时，会对节点输入和配置进行环境变量替换。

替换范围

• ✅ 节点输入参数（defaultInputs）
• ✅ 节点配置值
• ✅ 数据路径引用
• ✅ JavaScript 代码中的 context.env 访问

替换格式

Worker 端支持三种方式使用环境变量：

1. 模板语法：{{变量名}}

在节点输入和配置中使用模板语法：

{
  "defaultInputs": {
    "host": "{{DB_HOST}}",
    "port": "{{DB_PORT}}",
    "connectionString": "mysql://{{DB_USER}}:{{DB_PASSWORD}}@{{DB_HOST}}:{{DB_PORT}}/mydb"
  }
}

2. 数据路径：env.变量名

在边的配置中使用数据路径引用环境变量：

{
  "source": "nodeA:output",
  "target": "nodeB:host",
  "dataPath": "env.DB_HOST"
}

3. JavaScript：context.env.变量名

在转换节点或其他使用 JavaScript 的节点中访问：

// 在转换节点或其他使用 JavaScript 的节点中
const apiUrl = context.env.API_BASE_URL;
const apiKey = context.env.API_KEY;

return {
  url: `${apiUrl}/endpoint`,
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
};

环境变量替换的递归处理

Worker 端的环境变量替换支持递归处理复杂数据结构：

• 字符串：替换其中的 {{变量名}} 模板
• 数组：递归处理数组中的每个元素
• 对象：递归处理对象中的所有属性值

示例

{
  "config": {
    "api": {
      "baseUrl": "https://{{API_HOST}}",
      "endpoints": [
        "{{API_HOST}}/users",
        "{{API_HOST}}/products"
      ],
      "headers": {
        "Authorization": "Bearer {{API_TOKEN}}",
        "X-API-Key": "{{API_KEY}}"
      },
      "timeout": "{{REQUEST_TIMEOUT}}"
    }
  }
}

所有嵌套的字符串值中的 {{变量名}} 都会被递归替换。

环境变量未找到的处理

API 端

如果环境变量未找到，保持原模板格式（{{变量名}}），便于调试。系统会记录警告日志，但不会阻止任务执行。

Worker 端

• 模板语法：保持原模板格式（{{变量名}}）
• 数据路径：返回 undefined
• JavaScript：返回 undefined

建议在使用前检查变量是否存在：

// 安全的访问方式
const apiUrl = context.env.API_BASE_URL || 'https://default-api.com';
const apiKey = context.env.API_KEY;
if (!apiKey) {
  throw new Error('API_KEY 环境变量未设置');
}

使用场景示例

场景一：数据库连接配置

{
  "envVars": [
    { "key": "DB_HOST", "value": "db.example.com" },
    { "key": "DB_PORT", "value": "5432" },
    { "key": "DB_NAME", "value": "mydb" },
    { "key": "DB_USER", "value": "admin" },
    { "key": "DB_PASSWORD", "value": "secret", "isSecret": true }
  ]
}

在节点中使用：

{
  "defaultInputs": {
    "connectionString": "postgresql://{{DB_USER}}:{{DB_PASSWORD}}@{{DB_HOST}}:{{DB_PORT}}/{{DB_NAME}}"
  }
}

场景二：API 服务配置

在 Operator 配置中使用（API 端替换）

{
  "envVars": [
    { "key": "API_HOST", "value": "api.example.com" },
    { "key": "API_TOKEN", "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "isSecret": true },
    { "key": "API_KEY", "value": "your-api-key", "isSecret": true }
  ]
}

在 Operator 配置中使用：

{
  "configuration": {
    "values": {
      "serverUrl": "https://{{API_HOST}}",
      "headers": [
        {
          "key": "Authorization",
          "value": "Bearer {{API_TOKEN}}"
        },
        {
          "key": "X-API-Key",
          "value": "{{API_KEY}}"
        }
      ]
    }
  }
}

在 JavaScript 代码中使用（Worker 端替换）

{
  "envVars": [
    { "key": "API_BASE_URL", "value": "https://api.example.com" },
    { "key": "API_VERSION", "value": "v1" },
    { "key": "API_KEY", "value": "your-api-key", "isSecret": true }
  ]
}

async function callAPI(endpoint) {
  const baseUrl = context.env.API_BASE_URL;
  const version = context.env.API_VERSION;
  const apiKey = context.env.API_KEY;
  
  const url = `${baseUrl}/${version}/${endpoint}`;
  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  
  return response.json();
}

场景三：多环境配置

使用 ConfigMap 管理不同环境的配置：

开发环境 ConfigMap：

name: dev-config
variables:
  API_HOST: "dev-api.example.com"
  DB_HOST: "dev-db.example.com"
  LOG_LEVEL: "debug"

生产环境 ConfigMap：

name: prod-config
variables:
  API_HOST: "api.example.com"
  DB_HOST: "prod-db.example.com"
  LOG_LEVEL: "info"

任务绑定对应的 ConfigMap 即可在不同环境中使用相同的配置模板。

最佳实践

1. 使用 ConfigMap 管理环境配置

• 公共配置：放在默认 ConfigMap 中，供所有任务使用
• 特定环境配置：放在任务绑定的 ConfigMap 中
• 任务特定配置：直接在任务中定义环境变量

📖 了解更多：关于 ConfigMap 的创建、管理和最佳实践，请参阅 ConfigMap 使用指南。

2. 命名规范

• 使用大写字母和下划线：DB_HOST、API_KEY
• 使用有意义的名称和前缀：
  • DB_ 前缀：数据库相关配置
  • API_ 前缀：API 服务相关配置
  • REDIS_ 前缀：Redis 相关配置
  • LOG_ 前缀：日志相关配置

3. 敏感信息处理

• 将敏感信息标记为 isSecret: true
• 敏感信息在日志中会被自动隐藏
• 定期轮换敏感凭据
• 考虑使用专门的密钥管理服务

4. 环境变量优先级

• 任务级环境变量：用于覆盖特定场景或临时调试
• ConfigMap：用于管理共享配置和不同环境的配置

5. 当前限制和注意事项

• API 端支持：支持 URL 和 headers 中的环境变量替换
• 其他配置项：如 timeout、retryPolicy 等需要在 Worker 端通过模板语法使用
• 变量未找到：建议在使用前检查变量是否存在，避免运行时错误
• 类型转换：环境变量值始终是字符串，需要时进行类型转换
• Headers 格式：headers 必须是数组格式，每个元素包含 key 和 value 字段

6. 调试技巧

• 使用有意义的变量名和描述
• 在开发环境中使用非敏感值进行测试
• 检查日志中的环境变量替换记录
• 使用默认值处理未定义的变量

相关文档

• ConfigMap 使用指南 - 了解如何创建和管理 ConfigMap
• 工作流概述 - 工作流引擎概述
• 工作流构建器 - 工作流设计器使用指南