xyOps Tags 标签系统完全指南:定义、动态标记、标签驱动的自动化与 API 管理
xyOps Tags 标签系统完全指南:定义、动态标记、标签驱动的自动化与 API 管理
导读
本文全面讲解 xyOps(下一代开源作业调度与可视化工作流平台)中的 Tags 标签系统。Tags 是用户自定义的轻量元数据标签,可挂载在事件(Events)、作业(Jobs)与工单(Tickets)上,用于组织与检索,并能通过"标签条件"触发条件性作业动作实现自动化。读完本文,你将掌握标签对象的完整结构、三种生效位置与动态标记机制、基于标签的动作触发规则,以及通过 UI 和 API 全生命周期管理标签的实战方法。
概述:Tags 是什么
Tags 是用户自定义的标签,可以附加到事件、作业和工单上。它们是轻量级元数据,用于组织与搜索,同时也能驱动自动化——通过触发带条件的作业动作。标签只需定义一次(包含标题、可选图标与可选备注),之后就可以在任何支持标签的地方通过 ID 引用。
在 xyOps 中,Tags 承担三类核心职责:
- 可视化:标签与事件、运行中的作业和工单一同展示,快速传达环境(如 Production/Dev)或优先级(如 Sev1)等状态信息;
- 搜索:作业和工单的搜索可以按标签过滤,是历史数据检索的一等公民(first-class filter);
- 自动化:作业可以在运行时动态添加标签,标签也可以作为条件触发动作。
标签定义(Tag Definitions)
一个标签定义由以下字段组成:
| 字段 | 说明 |
|---|---|
id |
字母数字组成的 ID,由 xyOps 自动生成(也可通过 API 自行提供) |
title |
在 UI 中显示的标题 |
icon |
可选的 Material Design Icons 图标 ID |
notes |
可选的自定义备注 |
你可以在 UI 中创建、编辑和删除标签定义,或使用 Tag APIs。定义完成后,标签会出现在各类选择菜单中(例如动作条件选择器),并可用于搜索。
重要:标签 ID 是全局引用键,所有地方(包括作业动作条件和插件运行时更新)都以它为准。拿不准时,请直接从 UI 中复制标签 ID。避免创建以下划线开头的标签 ID——这些 ID 被保留给 xyOps 添加的系统标签。
从数据模型看,完整的 Tag 对象(见 docs/data.md)还包含以下服务器端自动维护的字段:username(创建者用户名)、created 与 modified(Unix 时间戳)、revision(内部修订号,每次变更递增)。旧版内置标签在更新前可能不含 revision 字段。
底层实现:标签的增删改查
标签 CRUD 的 API 实现位于 lib/api/tags.js。从源码结构可以看到几个值得注意的细节:
- ID 校验:所有涉及 ID 的接口都用正则
/^<a href="https://link.gitcode.com/i/e33a1ebaa28ee07c09aadb420f71725c" target="_blank">a-z0-9_]+$/校验参数([lib/api/tags.js),即 ID 只能是小写字母、数字、下划线; - ID 自动生成:创建时若未传
id,会调用Tools.generateShortID('t')自动生成以t开头的短 ID(lib/api/tags.js); - 唯一性校验:创建前会检查 ID 是否已存在,冲突则返回
tag错误(lib/api/tags.js); - 持久化与缓存:标签存储在
global/tags列表键下(storage.listPush/listFindUpdate/listFindDelete),同时维护内存缓存self.tags,并通过doUserBroadcastAll('update', { tags: self.tags })向所有在线用户实时广播更新(lib/api/tags.js); - 审计:每次创建、更新、删除都会记录事务日志(
tag_create/tag_update/tag_delete),可查阅 docs/actions.md 中对应的事件日志格式。
标签生效的位置(Where Tags Apply)
标签出现在三个位置,并随作业运行而流动:
- 事件(Events):每个事件可以定义一组默认标签。作业启动时会带上这些标签,但手动运行作业时可以自定义覆盖;
- 作业(Jobs):运行中的作业会不断累积额外标签。来源包括插件(push 更新)、工作流节点以及资源限制;
- 工单(Tickets):工单可以有自己的标签;对于工单关联的每个事件,工单还可以覆盖或补充要应用到"从该工单启动的作业"上的标签(对应 Ticket 数据模型中的
tags字段:可选的 Tag.id 数组,用于覆盖事件默认值)。
这种"事件默认 → 运行期累积 → 工单覆盖"的链路,保证了标签既能统一预设,又能按运行场景动态演化。
插件动态标记(Dynamic Tagging from Plugins)
事件插件(Event Plugins)可以通过向 STDOUT 发送 push 更新,为运行中的作业添加标签。这是纯增量操作(不支持替换/删除),标签会自动去重。标签 ID 必须引用已存在的标签定义。插件进程发送的 push 消息示例:
{ "xy": 1, "push": { "tags": ["tmi9dxf3792", "tb359d6dde"] } }
要点:
- 运行时只支持 push 方式更新标签;直接修改
job.tags会被忽略; - 标签 ID 必须已存在,需先在 UI 或通过 API 定义;
- 重复标签会自动去除。
更详细的插件 I/O 说明见 Plugins → Job Tags(docs/plugins.md)。其原文明确:push 对象用于指示 xyOps 将标签追加到现有集合上(不能替换或删除),标签本身必须是合法的 Tag.id,重复项自动移除。
标签驱动的动作(Tag-Driven Actions)
动作(Action)可以被"作业完成时是否带有某标签"这一条件所约束。当作业完成且包含该标签时,动作才会执行。这实现了精准路由,例如:"如果是生产环境则呼叫值班人员;如果是开发环境则仅记录日志。"
关键行为约束:
- 触发时机:仅在作业完成时触发;
- 重试行为:完成类动作(包括基于标签的动作)只在作业未被重试时运行;
- 去重:类型/目标完全相同的动作会被去重,即使来自多个来源也只会执行一次(去重键为类型+目标的组合,例如邮件收件人、web hook ID、事件 ID、通道 ID、插件 ID、桶 ID,见 docs/actions.md)。
示例:仅当作业完成且带有生产环境标签 tmi9dxf3792 时发送邮件的动作:
{
"enabled": true,
"condition": "tag:tmi9dxf3792",
"type": "email",
"users": ["oncall"],
"email": "ops@example.com"
}
你可以在 UI 的完整标签列表中选择标签条件。
条件语法说明
从 docs/actions.md(docs/actions.md)可以看到,作业条件(Job conditions)分为 start、complete、success、error、user、warning、critical、abort 等基于作业结果的类型,而标签条件 tag:TAGID 则是一个独立类型:作业完成时,仅当该标签存在于作业上才触发。因此它天然适用于"作业结束后按结果所属类别分流"的场景,例如把带有 Production 标签的失败作业升级为告警工单,而把 Dev 环境的失败仅记日志。
标签的其他来源(Other Ways Tags Are Applied)
除事件默认标签和插件 push 之外,以下功能也会添加标签:
- 资源限制(Resource Limits):作业上的限制(如时间、日志大小、内存、CPU)被超出时可以应用标签。这在运行时发生,并显示在作业活动(Activity)中。配置详见 docs/actions.md 与 docs/data.md(Limit 对象)。从数据模型看,Limit 的
tag类型是 Max Tag Limit——限制作业上允许的标签数量,这是软限制(soft limit),不会中止作业,超出时标签会被裁剪;tags字段则是"超出限制时要应用到作业上的 Tag.id 集合"(docs/data.md); - 工作流(Workflows):工作流节点可以为子作业定义标签。子作业完成后,用户自定义标签(非下划线开头)会上浮(bubble up)到父级工作流作业上,用于可见性与搜索。实现位于 lib/workflow.js:节点创建时
new_job.tags = Tools.copyHash(node.data.tags, true)(lib/workflow.js);子作业完成后,sub_job.tags中非下划线开头的标签会被过滤并合并进顶层作业,同时自动去重(lib/workflow.js)。这里的过滤逻辑!tag.match(/^_/)正是"下划线 ID 保留给系统标签"这一约定的代码级体现; - 工单(Tickets):当通过作业动作创建工单时,工单会自动继承作业的所有标签(动作参数中
ticket_tags为 Tag.id 数组,见 docs/actions.md)。
搜索与过滤(Searching and Filtering)
标签在 xyOps 中是第一等的搜索过滤器,常见用法包括:
- 作业:按标签过滤历史作业(例如
Production+Sev1组合检索); - 工单:按分类标签过滤(例如
Sev2、Maintenance); - 事件:用标签对相关自动化进行分组与定位。
构造 API 查询或使用 UI 时,请使用标签 ID;标题(title)仅用于显示。
通过 API 管理标签(Managing Tags via API)
标签管理端点可用于自动化与 CI/CD 流水线,完整协议定义见 docs/api.md:
| 端点 | 说明 | 权限 |
|---|---|---|
| get_tags | 列出全部标签 | 有效会话或 API Key 即可 |
| get_tag | 按 ID 获取单个标签 | 有效会话或 API Key 即可 |
| create_tag | 创建新标签(title 必填;id 可选;icon/notes 可选) | 需 create_tags 权限 |
| update_tag | 按 ID 更新标签(如 title/icon/notes) | 需 edit_tags 权限 |
| delete_tag | 按 ID 删除标签 | 需 delete_tags 权限 |
响应遵循标准响应格式,并在适用处返回完整的 Tag 对象。
各端点细节
get_tags:GET /api/app/get_tags/v1,无需输入参数。响应除标准格式外,包含 rows 数组(全部标签)与 list 元数据对象。示例响应:
{
"code": 0,
"rows": [
{
"id": "important",
"title": "Important",
"icon": "alert-rhombus",
"username": "admin",
"modified": 1611173740,
"created": 1611173740
}
],
"list": { "length": 1 }
}
get_tag:GET /api/app/get_tag/v1,参数 id(必填)。GET(query string)与 POST(JSON)均可。示例请求 { "id": "important" },响应含 tag 对象。
create_tag:POST /api/app/create_tag/v1,参数 id(可选,省略则自动生成)、title(必填)、icon(可选)、notes(可选)。示例请求:
{
"title": "Important",
"icon": "alert-rhombus",
"notes": "Attention is needed!"
}
响应含完整 tag 对象,包括自动生成的 id、username、created、modified 与 revision 字段。
update_tag:POST /api/app/update_tag/v1,参数 id(必填),可传稀疏(sparse)的可编辑属性 title/icon/notes。服务器会自动更新 modified 并递增 revision。示例请求 { "id": "important", "title": "High Priority" },响应 { "code": 0 }。
delete_tag:POST /api/app/delete_tag/v1,参数 id(必填)。示例请求 { "id": "important" },响应 { "code": 0 }。删除是永久性的,无法撤销。
测试用例佐证
仓库中的 test/suites/test-tags.js 覆盖了上述端点的完整生命周期:列出标签(test_api_get_tags)、获取不存在的标签应报错(test_api_get_tag_missing)、缺少 title 创建应报错、非法 ID 创建应报错、创建后获取并校验 id 与 title、更新后校验 title/icon/notes(UTT v2 / star / unit test notes)、删除不存在标签报错、正常删除等,是验证标签 API 行为边界(参数必填、ID 格式、存在性检查)的可靠参考。
权限说明
标签相关权限定义于 docs/privileges.md:create_tags(创建系统标签以组织事件、作业及相关数据)、edit_tags(编辑现有标签)、delete_tags(从系统删除标签)。需要为自动化账号分配这些权限时,请按最小权限原则授予。
实用建议与推荐标签(Tips and Recommended Tags)
以下是一些通用且实用的标签建议,可直接参考创建:
- 环境:
Production、Staging、Dev、QA - 优先级/严重级:
Sev1、Sev2、Sev3;Priority:High、Priority:Low - 变更窗口:
Freeze、Maintenance - 归属/团队:
Team:Ops、Team:Payments - 数据敏感性:
PII、Finance - 发布标签:
Release:2025/11、Canary、Beta
实践准则:
- 保持标签标题对用户友好,尽量用简洁、能快速传达含义的短标签;
- 优先使用 UI 创建标签,确保 ID 由系统生成且风格一致;若通过 API 自定义 ID,只使用小写字母数字与下划线;
- 避免以下划线(
_)开头的 ID,防止与系统标签冲突(这也与 lib/workflow.js 中"仅上浮用户标签、过滤下划线系统标签"的实现相呼应); - 在事件、工单、动作或插件 push 中引用标签之前,先完成标签定义。
小结
xyOps 的 Tags 系统是一条贯穿"事件 → 作业 → 工单"的元数据主线:定义一次、按 ID 全局引用;运行时可由插件、工作流节点、资源限制动态累积;完成后可通过 tag:TAGID 条件精确触发动作;搜索与过滤以 ID 为准;管理则可通过 UI 或 Tag APIs 完成,权限由 create_tags、edit_tags、delete_tags 三枚权限控制。合理设计标签体系(环境、严重级、团队归属、变更窗口等维度),即可把作业调度平台变成一套可检索、可审计、可自动分流的运维编排中枢。