跳到主要内容

配置映射概述

配置映射（ConfigMap）是一种用于存储和管理应用程序配置数据的功能。它允许您将配置信息与应用程序代码分离，使配置管理更加灵活和安全。

什么是配置映射​

配置映射是一个包含键值对配置数据的容器。每个配置映射可以包含多个配置变量，这些变量可以在您的任务、智能体、工具或其他应用程序组件中使用。通过配置映射，您可以实现配置的模块化管理，将不同服务或功能的配置进行逻辑分组。

主要特点​

  • 配置隔离: 为不同服务、组件或环境创建独立的配置映射，实现配置的模块化管理
  • 团队隔离: 每个团队只能访问和管理自己的配置映射
  • 安全管理: 支持敏感信息的安全存储和访问控制
  • 默认配置: 支持设置默认配置映射
  • 批量导入: 支持通过YAML文件批量导入配置
  • 智能搜索: 快速查找和过滤配置映射和变量
  • 全屏管理: 采用全屏模态窗口提供更好的操作体验

核心概念​

配置映射（ConfigMap）​

配置映射是配置数据的逻辑分组。您可以根据组件、服务功能或环境等不同维度来组织它们，从而实现配置的模块化管理。这种方式有助于降低配置的复杂性，提高可维护性。

常见的组织方式示例：

  • auth-service - 认证服务的相关配置
  • redis-config - Redis缓存的连接信息
  • feature-toggles - 功能开关集合
  • production-secrets - 生产环境的敏感信息
  • shared-settings - 多个服务共享的配置

配置变量（ConfigVariable）​

配置变量是存储在配置映射中的具体键值对：

  • 键（Key）: 配置项的名称，如 DATABASE_URL
  • 值（Value）: 配置项的值，如 postgresql://localhost:5432/mydb
  • 描述（Description）: 配置项的说明
  • 敏感标记: 标记是否为敏感信息（如密码、API密钥）

使用场景​

配置映射提供了灵活的配置管理方式，适用于多种场景。

1. 按服务或组件分离配置​

将不同微服务或应用程序组件的配置分别存储在各自的配置映射中。

认证服务配置 (auth-service):

  • JWT_SECRET_KEY: "your-very-secret-key"
  • TOKEN_EXPIRATION: "24h"

数据处理任务配置 (data-processor):

  • BATCH_SIZE: 100
  • SOURCE_QUEUE: "raw-data-queue"

2. 管理功能开关​

使用配置映射集中管理应用程序的功能开关，方便动态调整功能。

功能开关配置 (feature-toggles):

  • ENABLE_NEW_DASHBOARD: true
  • MAINTENANCE_MODE: false
  • MAX_UPLOAD_SIZE_MB: 100

3. 管理第三方服务凭证​

统一存放外部服务（如数据库、缓存、邮件服务）的连接信息和密钥。

外部服务配置 (external-services):

  • DATABASE_URL: "postgresql://user:pass@host:5432/db"
  • REDIS_URL: "redis://localhost:6379"
  • S3_BUCKET_NAME: "my-app-storage"

4. 按环境提供不同配置​

虽然不是唯一用途，但配置映射也常用于区分不同部署环境（如开发、测试、生产）的配置。

生产环境数据库 (production-db):

  • DATABASE_URL: postgresql://prod-db:5432/app

开发环境数据库 (development-db):

  • DATABASE_URL: postgresql://localhost:5432/app_dev

界面功能详解​

配置映射管理界面​

主要功能区域​

  • 搜索栏: 快速搜索配置映射名称和描述
  • 创建按钮: 创建新的配置映射
  • 配置映射列表: 显示所有配置映射的详细信息
  • 操作按钮: 管理变量、编辑、删除等操作

列表信息显示​

  • 名称: 配置映射名称，默认配置映射显示星标（⭐）
  • 描述: 配置映射的用途说明
  • 默认状态: 显示是否为默认配置映射
  • 变量数量: 显示包含的配置变量数量
  • 创建时间: 配置映射的创建日期
  • 操作按钮: 管理变量、编辑、删除

配置变量管理界面​

全屏模态窗口​

配置变量管理采用全屏模态窗口设计，提供更好的操作体验：

  • 大屏幕显示: 最大宽度7xl，高度90vh，充分利用屏幕空间
  • 响应式设计: 适配不同屏幕尺寸
  • 固定头部: 显示当前配置映射信息和关闭按钮

功能工具栏​

  • 搜索框: 实时搜索配置变量的键、值、描述
  • 敏感信息切换: 显示/隐藏敏感信息内容
  • 导出YAML: 将配置导出为YAML格式文件
  • 导入YAML: 从YAML文件批量导入配置
  • 添加变量: 创建新的配置变量

变量列表表格​

  • 粘性表头: 滚动时表头保持可见
  • 悬停效果: 鼠标悬停时行高亮显示
  • 类型标识: 清晰区分普通变量和敏感变量
  • 操作按钮: 编辑、删除等快捷操作

如何使用配置映射​

1. 访问配置映射管理​

  1. 登录系统后，点击右上角的用户头像
  2. 选择"设置"进入设置页面
  3. 点击"配置映射"标签页

2. 创建配置映射​

  1. 点击"创建新配置映射"按钮
  2. 填写以下信息：
    • 名称: 配置映射的唯一标识符（只能包含字母、数字、连字符和下划线）
    • 描述: 配置映射的用途说明
    • 设为默认: 是否将此配置映射设为团队的默认配置
  3. 点击"创建配置映射"完成创建

3. 管理配置映射​

查看和搜索配置映射​

  • 列表视图: 表格形式显示所有配置映射的详细信息
  • 实时搜索: 在搜索框中输入关键词，系统会实时过滤匹配的配置映射
  • 搜索范围: 支持按名称和描述进行搜索
  • 默认标识: 默认配置映射会显示星标（⭐）和"默认"标签

编辑配置映射​

  1. 点击配置映射行的"编辑"按钮
  2. 修改名称、描述或默认状态
  3. 点击"保存更改"

删除配置映射​

  1. 点击配置映射行的"删除"按钮
  2. 在确认对话框中点击"确认删除"
  3. 注意: 默认配置映射不能被删除

4. 管理配置变量​

进入变量管理界面​

  1. 点击配置映射行的"管理变量"按钮
  2. 系统会打开全屏模态窗口，显示该配置映射的所有变量

搜索和过滤变量​

  • 实时搜索: 在搜索框中输入关键词，立即过滤匹配的变量
  • 搜索范围: 支持按变量名、变量值、描述进行搜索
  • 敏感信息控制: 使用"显示/隐藏敏感信息"按钮控制敏感数据的显示

添加配置变量​

  1. 点击"添加变量"按钮
  2. 填写变量信息：
    • 变量名: 配置项的键名（必填）
    • 变量值: 配置项的值（必填）
    • 描述: 配置项的说明（可选）
    • 敏感信息: 勾选此项将变量标记为敏感信息
  3. 点击"添加变量"完成创建

编辑配置变量​

  1. 点击变量行的"编辑"按钮
  2. 修改变量的任何信息
  3. 点击"保存更改"

删除配置变量​

  1. 点击变量行的"删除"按钮
  2. 系统会立即删除该变量（请谨慎操作）

5. YAML导入导出功能​

导出YAML​

  1. 在变量管理界面点击"导出YAML"按钮
  2. 选择导出格式：
    • 简化格式: 适合人工编辑的简洁格式
    • Kubernetes ConfigMap: 标准的K8s ConfigMap格式
  3. 系统会自动下载YAML文件

导入YAML​

  1. 点击"导入YAML"按钮打开导入对话框
  2. 选择YAML格式和导入选项：
    • YAML格式: 选择简化格式或Kubernetes ConfigMap格式
    • 导入选项: 决定是否覆盖已存在的变量
  3. 上传YAML文件：
    • 拖拽上传: 直接将.yaml或.yml文件拖拽到上传区域
    • 点击选择: 点击"选择文件"按钮浏览文件
    • 手动输入: 直接在大尺寸文本框中编辑YAML内容（24行高度）
  4. 系统会自动检测文件格式并预填充内容
  5. 点击"导入配置"完成导入

YAML格式示例​

简化格式:

name: my-config
description: "我的配置映射"
variables:
  DATABASE_URL:
    value: "postgresql://localhost:5432/mydb"
    description: "数据库连接URL"
  API_KEY:
    value: "your-api-key"
    description: "API密钥"
    isSecret: true

Kubernetes ConfigMap格式:

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-config
data:
  DATABASE_URL: "postgresql://localhost:5432/mydb"
  API_KEY: "your-api-key"

配置访问规则​

配置访问优先级​

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

  1. 任务/工具直接配置

    • 在Task中直接配置的环境变量
    • 在Operator中直接配置的配置信息
    • 这些配置具有最高优先级，会覆盖其他来源的配置

  2. 绑定的配置映射

    • 任务、工具或智能体可以绑定特定的配置映射
    • 例如：ConfigMap: some-operator-config
    • 绑定的配置映射中的变量可以通过环境变量形式访问
    • 配置映射的访问范围仅限于绑定的组件

  3. 默认配置映射

    • 系统默认配置映射对所有组件可见
    • 可以通过环境变量形式访问：{YOUR_KEY}
    • 作为基础配置，优先级最低

配置访问范围​

  1. 全局访问

    • 默认配置映射中的变量可以被所有组件访问
    • 使用环境变量形式：{YOUR_KEY}

  2. 组件级访问

    • 绑定的配置映射仅对绑定的组件可见
    • 类似于Kubernetes Deployment绑定的ConfigMap
    • 提供更好的隔离性和安全性

  3. 直接配置

    • 在Task或Operator中直接配置的变量
    • 仅对配置的组件可见
    • 提供最高的灵活性和优先级

使用示例​

# 场景: 一个任务在运行时，其配置的加载和覆盖过程

# 1. 默认配置映射: 'global-config' (最低优先级)
#    所有组件均可访问。
#    假设其中定义了:
#    LOG_LEVEL: "info"
#    API_URL: "https://api.service.com"

# 2. 工具绑定的配置映射: 'some-operator-config' (中等优先级)
#    一个工具(Operator)可以绑定一个特定的配置映射。
#    假设 'my-operator' 工具绑定了 'some-operator-config'，其中定义了:
#    LOG_LEVEL: "debug"            # 覆盖 'global-config' 的 LOG_LEVEL
#    DB_HOST: "db.operator.internal" # 新增工具专属配置

# 3. 任务中直接定义的环境变量 (最高优先级)
#    在任务(Task)定义中直接设置，将覆盖来自所有配置映射的同名变量。
#    假设一个使用 'my-operator' 的任务 'my-task' 定义了:
#    LOG_LEVEL: "warn"             # 覆盖 'some-operator-config' 的 LOG_LEVEL
#    MAX_RETRIES: "5"              # 任务独有的新配置

# ---
# 最终 'my-task' 运行时生效的环境变量如下:
#
# LOG_LEVEL: "warn"
#   - 来源: 任务直接定义，优先级最高。
#
# API_URL: "https://api.service.com"
#   - 来源: 默认配置映射 'global-config'，未被覆盖。
#
# DB_HOST: "db.operator.internal"
#   - 来源: 工具绑定的 'some-operator-config'。
#
# MAX_RETRIES: "5"
#   - 来源: 任务直接定义。

最佳实践​

1. 命名规范​

配置映射命名:

  • 使用描述性名称：auth-service、redis-config、feature-toggles
  • 避免使用特殊字符，只使用字母、数字、连字符和下划线
  • 保持名称简洁明了，体现配置的用途或所属组件

配置变量命名:

  • 使用大写字母和下划线：DATABASE_URL、API_KEY
  • 使用前缀区分不同类型：DB_HOST、REDIS_PORT、SMTP_USER

2. 配置分组策略​

根据实际需求选择合适的分组策略：

按服务分组:

- auth-service      # 认证服务配置
- payment-service   # 支付服务配置  
- notification-service # 通知服务配置

按功能分组:

- database-config   # 数据库相关配置
- cache-config      # 缓存相关配置
- feature-toggles   # 功能开关

按环境分组（可选）:

- production-secrets  # 生产环境敏感配置
- development-config  # 开发环境配置

3. 敏感信息管理​

  • 将密码、API密钥等敏感信息标记为"敏感"
  • 敏感信息在界面上会显示为 ••••••••
  • 使用"显示敏感信息"功能时才会显示真实内容
  • 定期更新敏感信息
  • 不要在配置描述中包含敏感信息

4. 配置组织​

按功能或服务对配置进行分组：

认证服务配置映射 (auth-service):

- JWT_SECRET_KEY
- TOKEN_EXPIRATION
- OAUTH_CLIENT_ID
- OAUTH_CLIENT_SECRET

数据库配置映射 (database-config):

- DB_HOST
- DB_PORT  
- DB_NAME
- DB_USER
- DB_PASSWORD

外部服务配置映射 (external-services):

- SMTP_HOST
- SMTP_PORT
- REDIS_URL
- S3_BUCKET_NAME

5. 默认配置映射​

  • 每个团队只有一个默认配置映射
  • 默认配置映射通常包含全局通用的配置，如系统级设置
  • 默认配置映射中的变量可以被所有组件访问
  • 默认配置映射不能被删除，确保系统稳定性
  • 建议将常用的、非敏感的配置放在默认配置映射中

6. 搜索和过滤技巧​

  • 快速定位: 使用搜索功能快速找到特定的配置映射或变量
  • 模糊匹配: 搜索支持部分匹配，输入关键词即可找到相关配置
  • 多字段搜索: 搜索会同时匹配名称、描述等多个字段
  • 实时过滤: 搜索结果会实时更新，无需按回车键

7. 批量操作建议​

  • YAML导入: 适合批量创建或更新大量配置变量
  • 格式选择: 根据使用场景选择合适的YAML格式
  • 备份先行: 大批量操作前先导出现有配置作为备份
  • 分批导入: 对于大量配置，建议分批次导入以便于管理

安全注意事项​

1. 访问控制​

  • 只有团队成员可以访问团队的配置映射
  • 确保团队成员权限设置正确

2. 敏感信息保护​

  • 始终将密码、API密钥标记为敏感信息
  • 使用"隐藏敏感信息"功能保护敏感数据不被意外泄露
  • 不要在日志或错误信息中暴露敏感配置
  • 定期审查和更新敏感配置

3. 配置变更管理​

  • 重要配置变更前先通过导出功能备份
  • 在测试环境中验证配置变更的效果
  • 记录配置变更的原因和影响
  • 使用搜索功能验证变更是否正确应用

4. 文件上传安全​

  • 只上传可信来源的YAML文件
  • 导入前仔细检查YAML内容
  • 使用"覆盖已存在的变量"选项时要特别谨慎

常见问题​

Q: 如何在应用程序中使用配置映射？​

A: 配置映射中的变量可以通过API或SDK在您的智能体、任务中使用。具体使用方法请参考相关的开发文档。

Q: 可以创建多少个配置映射？​

A: 没有硬性限制，但建议根据实际需要合理创建，避免配置过于分散。

Q: 如何备份配置映射？​

A: 使用"导出YAML"功能可以将配置映射导出为文件进行备份，建议定期备份重要配置。

Q: 配置映射删除后可以恢复吗？​

A: 配置映射删除后无法直接恢复，请在删除前确认并使用导出功能做好备份。

Q: 为什么不能删除默认配置映射？​

A: 默认配置映射是系统的基础配置，删除可能影响依赖它的应用程序正常运行。

Q: YAML导入时出现错误怎么办？​

A: 请检查YAML文件格式是否正确，确保缩进和语法符合YAML规范。系统会显示具体的错误信息帮助您定位问题。

Q: 如何快速找到特定的配置变量？​

A: 使用变量管理界面的搜索功能，可以按变量名、值或描述进行搜索，支持实时过滤。

Q: 敏感信息如何安全管理？​

A: 将敏感配置标记为"敏感信息"，系统会自动隐藏显示。只有在需要时才使用"显示敏感信息"功能查看真实内容。

Q: 全屏模态窗口如何关闭？​

A: 可以点击右上角的"关闭"按钮，或者按ESC键快速关闭模态窗口。

Q: YAML文件上传有什么限制？​

A: 支持.yaml和.yml格式的文件，可以通过拖拽或点击选择的方式上传，系统会自动检测文件格式。

下一步​