标签功能(适用于定时任务、工作流、重试任务)
在 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
通过配置文件指定
非常规配置方式(动态调整)
通过服务端管理界面动态配置(适用于紧急摘流或临时调整):
- 登录服务端控制台
- 进入 客户端管理 页面
- 选择目标客户端 → 编辑标签
- 保存后立即生效(无需重启客户端)


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


三、标签路由规则
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:dev
与env:dev
视为不同标签)。
4. 特殊场景说明
- 客户端状态过滤:下线状态的客户端自动被排除,不参与标签匹配
- 性能影响:标签匹配操作时间复杂度为 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
五、最佳实践
- 标签设计原则:
- 保持标签语义清晰(如
env
、version
、app
) - 避免使用复杂标签值(如包含特殊字符)
- 控制标签数量(建议单客户端 ≤ 10 个)
- 保持标签语义清晰(如
- 动态调整建议:
- 通过服务端界面动态调整标签时,建议记录变更历史
- 紧急摘流后及时同步到配置文件,保持配置一致性
六、常见问题解答
- 问:如何查看客户端当前配置的标签?
- 答:通过服务端控制台查看
- 问:标签匹配是否区分大小写?
- 答:是的,
env:Dev
与env:dev
视为不同标签
- 答:是的,
- 问:如何临时排除某个客户端?
- 答:通过服务端在线机器中下线对应客户端