xyOps Tags 标签系统完全指南:定义、动态标记、标签驱动的自动化与 API 管理

原创2026-10-09 14:55:211,990 阅读

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 三枚权限控制。合理设计标签体系(环境、严重级、团队归属、变更窗口等维度),即可把作业调度平台变成一套可检索、可审计、可自动分流的运维编排中枢。

登录后查看全文
xyops