Skip to content

标签功能(适用于定时任务、工作流、重试任务)

snail-job 1.6.0 版本中引入了客户端标签功能,支持通过标签匹配机制实现精准调度、流量控制和灰度发布等高级场景。本文档分为配置指南标签路由规则两部分,详细说明标签功能的使用方法。

一、标签基础概念

1. 标签格式

  • 标签采用 键值对(K:V) 格式配置(如 env:dev
  • 支持配置多个标签,每个标签独立生效
  • 系统保留关键字state(禁止使用,用于内部状态管理)

二、配置指南

1. 客户端配置

客户端支持两种标签配置方式,推荐使用常规配置(稳定性更高):

常规配置方式(推荐)

通过客户端 YAML 配置文件静态配置:

yaml
snail-job:
	# 标签(支持多标签)
  labels:
    env: dev
    version: 1.0.0
    # 可以配置多个标签
    # tag:grey

通过配置文件指定

非常规配置方式(动态调整)

通过服务端管理界面动态配置(适用于紧急摘流或临时调整):

  1. 登录服务端控制台
  2. 进入 客户端管理 页面
  3. 选择目标客户端 → 编辑标签
  4. 保存后立即生效(无需重启客户端)
image-20240918162822145image-20240918162822145

2. 服务端配置

服务端通过任务配置标签,实现基于标签的任务调度路由:

image-20240918162822145image-20240918162822145

三、标签路由规则

1. 版本兼容性

客户端版本服务端版本标签路由行为
≥ 1.6.0≥ 1.6.0严格执行标签匹配规则
< 1.6.0≥ 1.6.0标签路由不生效,默认匹配所有任务

2. 匹配规则详解

标签路由基于客户端和任务标签的包含关系进行匹配:

规则 1:客户端未配置标签

  • 规则:无论任务是否配置标签,未配置标签的客户端均自动匹配。
  • 示例
    • ✅ 任务标签 [env:dev ] —— 客户端 [ ](匹配成功)
    • ✅ 任务标签 [ ] —— 客户端 [ ](匹配成功)

规则 2:客户端配置标签

  • 规则
    • 1、客户端标签必须完全包含任务标签的所有项。
    • 2、若客户端处于下线状态,则自动被排除,不会参与匹配。
  • 示例:
    • ✅ 任务标签 [env:dev ] —— 客户端 [env:dev; tag:grey ](匹配成功)
    • ✅ 任务标签 [env:dev ] —— 客户端 [env:dev;](匹配成功)
    • ✅ 任务标签 [ ] —— 客户端 [env:dev; tag:grey ](匹配成功)
    • ❌ 任务标签 [env:dev; tag:grey ] —— 客户端 [ env:dev;](匹配失败,缺少 tag:grey
    • ❌ 任务标签 [env:prod ] —— 客户端 [ env:dev;](匹配失败,缺少 tag:grey
    • ❌ 任务标签 [env:prod ] —— 客户端 [ Env:prod;](匹配失败,缺少标签 key 不一致,区分大小写)

3. 标签格式规范

  • 标签采用 key:value 格式(如 env:dev)。
  • 标签匹配区分大小写(如 Env:devenv:dev 视为不同标签)。

4. 特殊场景说明

  1. 客户端状态过滤:下线状态的客户端自动被排除,不参与标签匹配
  2. 性能影响:标签匹配操作时间复杂度为 O (n),建议单客户端标签数量不超过 20 个

5. 测试用例

任务标签客户端标签预期结果说明
[env:dev][]客户端未配置标签
[][]双方均未配置标签
[env:dev][env:dev; tag:grey]客户端包含任务标签
[env:dev][env:dev;]客户端标签完全匹配
[][env:dev; tag:grey]任务无标签,客户端任意
[env:dev; tag:grey][env:dev;]客户端缺少 tag:grey
[env:prod][env:dev;]标签值不一致

四、典型应用场景

1. 环境隔离

yaml
# 开发环境任务
labels:
  env: dev

# 生产环境任务
labels:
  env: prod

2. 灰度发布

yaml
# 灰度任务
labels:
  version: 2.0.0
  tag: grey

3. 资源隔离

yaml
# 高性能计算任务
labels:
  hardware: high-cpu
  memory: 16g

五、最佳实践

  1. 标签设计原则
    • 保持标签语义清晰(如 envversionapp
    • 避免使用复杂标签值(如包含特殊字符)
    • 控制标签数量(建议单客户端 ≤ 10 个)
  2. 动态调整建议
    • 通过服务端界面动态调整标签时,建议记录变更历史
    • 紧急摘流后及时同步到配置文件,保持配置一致性

六、常见问题解答

  1. :如何查看客户端当前配置的标签?
    • :通过服务端控制台查看
  2. :标签匹配是否区分大小写?
    • :是的,env:Devenv:dev 视为不同标签
  3. :如何临时排除某个客户端?
    • :通过服务端在线机器中下线对应客户端