xyOps 新手入门指南：从添加第一台服务器到可视化工作流编排

导读

xyOps 是一个开源自托管的作业调度、工作流自动化引擎与服务器监控平台，它把"在服务器上运行作业"、"用可视化图形编排作业流"、"采集指标"、"按计划或间隔触发"以及"用动作与限制做出反应"整合在同一个系统里。本文以仓库内的 docs/welcome.md（即新用户登录后仪表盘上显示的开篇指南）为骨架，系统讲解 xyOps 的核心概念，并带你完成两个实战演练：创建第一个事件（Event）与第一个工作流（Workflow）。读完后，你将掌握添加服务器、理解事件/工作流/触发器/插件/动作/限制/分类等基础模型，并具备独立搭建第一条自动化流水线的能力。

本文对应仓库gh_mirrors/xy/xyops。更详细的完整安装与进阶走读见 docs/start.md（涵盖首次安装、conductor 主机名、base_app_url、第一个事件、事件链、JSON over STDIO、限制、web hook 动作与基础工作流）。

xyOps 是什么：一份欢迎页背后的全景

welcome.md 是 xyOps 在新用户仪表盘上展示的引导页：它在你创建第一个事件之前出现，创建后自动消失；之后随时可通过侧边栏的 "Documentation" → "Welcome to xyOps" 找回。这段引导浓缩了 xyOps 的产品定位——它既是作业调度器（在服务器上运行作业）、又是工作流自动化引擎（可视化编排作业流）、还是服务器监控平台（采集指标、触发运行、用动作和限制做出反应），并且所有这些能力都同时暴露在 Web UI 与 REST API 中。

从仓库结构看，这一架构得到了完整印证：

• lib/main.js、lib/engine.js、lib/schedule.js 对应 conductor 侧的核心调度与运行引擎；
• lib/server.js、lib/multi.js 对应服务器管理与集群协调；
• lib/api 目录下按功能拆分的 API 模块（如 events.js、servers.js、plugins.js）与 htdocs 中的前端页面类（htdocs/js/pages）共同构成了"UI 与 API 双入口"的体验。

Step 1：添加第一台服务器

在运行任何作业之前，至少需要添加一台服务器。**服务器（Server）**运行轻量级代理xySat，负责接收 xyOps 下发的作业并在本机执行。支持的主机形态包括 Docker、Linux、macOS 与 Windows。

通过 UI 添加服务器的步骤：

1. 打开Servers页面，点击Add Server。
2. 可选设置 label（标签）、icon（图标）与 groups（分组），也可以全部保留默认值。
3. 复制对应操作系统的一行式安装命令，在目标主机上执行。
4. 服务器出现在 UI 中，开始流式上报指标，并立即可用于运行作业。

这里的一行式安装命令本质上是向 conductor 的安装端点发起请求并管道到 shell 执行。结合 docs/servers.md 可以看得更清楚：

• 安装器行为：安装脚本会完成认证、把 xySat 安装为启动服务（systemd / launchd / Windows Service）、写入配置文件并启动代理；
• 自动化引导（API Key 方式）：为弹性伸缩或临时主机，可在 UI 创建仅授予add_servers权限的 API Key，然后把安装命令 URL 中t参数（默认 24 小时过期的临时令牌）替换为永不过期的 API Key，形如curl -s "https://xyops01.mycompany.com/api/app/satellite/install?t=API_KEY_HERE" | sudo sh，放进 cloud-init、AMI、Packer 模板等 first-boot 流程；
• 自动化 Docker Worker：以XYOPS_setup环境变量指向http://YOUR_XYOPS_SERVER:5522/api/app/satellite/config?t=YOUR_API_KEY_HERE，即可无限扩容 Docker 工人节点，每个请求都会生成新的 Server ID 与永久 Auth Token；配置目录必须使用各自的命名卷。

注意网络连通性：xySat 与 conductor 之间通过持久 WebSocket 连接通信，因此新服务器的网络栈必须先就绪，且 conductor 主机名必须能被 worker 解析到。若 worker 长时间未上线，优先检查主机名与路由（见 docs/servers.md 与 docs/start.md 的"两个重要 URL"一节）。

核心概念：事件（Events）与工作流（Workflows）

• 事件（Event）：一份可复用的作业定义，声明了"运行什么"（一个插件加参数）、"在哪里运行"（服务器或分组）、"何时运行"（触发器）以及"如何控制与反应"（限制与动作）。事件每次被触发运行都会产生一个作业（Job）。完整模型见 docs/events.md。
• 工作流（Workflow）：一个可视化图形，用节点与连线把多个作业串成带控制流的编排。一次工作流运行会成为一个父作业，由其节点逐个启动子作业；支持扇出（fan-out）、汇聚（join）、重复（repeat）、跨服务器多路复用（multiplex），并且每个节点都可以挂载限制与动作。完整模型见 docs/workflows.md。

实践建议：大多数自动化用简单事件即可；当需要编排、分支或并行时才引入工作流。

触发器（Triggers）：决定作业何时运行

触发器控制事件与工作流"被允许运行"的时机。welcome.md 列出的常见类型：

在 UI 中，事件以表格形式列出触发器；工作流则以图形节点表示触发器，并连接到入口节点。触发器的组合有约束（如 interval 与 precision/delay 互斥，manual/catchup/range/precision/delay 每种每事件唯一），这些规则由 API 与 UI 强制校验，详见 docs/triggers.md。

调度器（conductor 上的 lib/schedule.js）默认每分钟评估一次事件触发器（可选秒级精度），命中后产生启动。

插件（Plugins）：决定作业运行什么

事件插件（Event Plugin）是真正"运行作业"的代码。内置插件包括：

• Shell 插件：运行任意 shell 脚本/命令；
• HTTP 请求插件：调用 HTTP(S) 端点，支持自定义请求头、POST 数据、成功/失败正则匹配、重定向、超时与 SSL 绕过等；
• Docker 插件：在容器内运行脚本（可指定任意镜像，支持 CPU/内存限额与 xyRun 资源封装）；
• 测试插件：产出样例数据/文件，便于测试流程分支。

插件协议极简：插件从 STDIN 读取一份 JSON 作业上下文，向 STDOUT 写 JSON 状态更新，任何语言只要支持 JSON over STDIO 即可编写插件。插件运行在目标服务器上、由 xySat 以子进程方式拉起，并拥有一个唯一临时目录作为工作目录（输入文件会被预下载到此目录，见 docs/plugins.md）。完整协议见 docs/xywp.md 与 docs/plugins.md。

动作（Actions）与限制（Limits）

• 限制（Limits）：自我施加的约束，如Max Time Limit（最大运行时长）、Max Output Limit（最大输出体积）、Max CPU/Memory（CPU/内存上限，带宽限期）、Max Jobs Limit（最大并发）、Max Queue（最大排队数）、Max Retries（最大重试次数）。超限时可以打标签、发通知、拍快照、并可选终止作业。限制可来自事件/工作流、分类（category）与全局默认（universal defaults），优先级依次为：事件定义 > 工作流限制节点 > 分类继承 > 全局继承（见 docs/limits.md）。
• 动作（Actions）：对作业结果（start、success、error、warning、critical、abort 或 tag 匹配）或告警状态变化的反应。类型包括邮件、web hook、运行作业（Run Event，用于事件链）、工单（ticket）、快照（snapshot）等。同一条件触发的动作并行执行，并按"类型+目标"去重，避免重复投递（见 docs/actions.md）。

一个典型的错误通知动作 JSON 形如：

{ "enabled": true, "condition": "error", "type": "email", "email": "admin@example.com" }

分类（Categories）：组织与默认值

分类用于组织事件并控制默认行为与可见性，其能力包括：

• 为分类内的事件施加默认动作与限制（事件可覆盖分类默认值）；
• 基于用户角色与权限控制访问；
• 为团队提供清晰的事件分组方式。

可以从默认分类起步，之后随时细化。分类继承机制详见 docs/categories.md；在运行时，分类定义的 actions/limits 会与事件自身的定义一起合并进作业（见 docs/events.md）。

实战一：创建你的第一个事件

按以下步骤走通第一条自动化：

1. 进入Events → New Event。
2. 填写标题，选择一个分类。
3. 选择Shell 插件，粘贴一段简单脚本，例如：

#!/bin/sh echo "Hello from xyOps" echo '{ "xy": 1, "code": 0 }'

最后一行 JSON 会向 xyOps 报告成功。Shell 插件的成功判定默认基于脚本退出码（0为成功，非零为失败），而完整 JSON 输出则走 xyOps Wire Protocol（XYWP）。补充说明（结合 docs/start.md 与 docs/plugins.md）：

• Shell 插件支持任意带 shebang 的语言（Node.js、Python、Perl、PHP、Ruby、PowerShell 等），只需改首行解释器；
• 脚本内可直接输出25%这样的百分比行来更新实时进度条（0–100）；
• 也可以输出完整的 XYWP JSON，如{ "xy": 1, "status": "...", "progress": 0.5 }；
• 任何不被识别为 XYWP 消息的 STDOUT 内容都会作为普通日志捕获，STDERR 则作为原始文本记录。

4. 选择一台服务器（或一个分组）作为目标，保留默认的选择算法（algo，默认 random）。
5. 添加一个Manual触发器并保存事件。
6. 点击Run，实时查看日志流，并查看作业的结果与指标。

作业运行的生命周期（从触发器命中到执行完成）在 docs/events.md 中有完整描述：调度器评估触发器 → 创建作业对象（复制事件 + 触发上下文 + 覆盖项，合并分类与全局的 actions/limits）→ 解析参数（含{{ macros }}宏展开）→ 目标选择（过滤到在线且启用的服务器，可选 Target Expression 进一步收敛，如info.arch == "arm64" && info.cpu.cores >= 4）→ 插件执行 → 限制/动作评估 → 完成并归档历史。

延伸练习：再给事件加一个Max Time Limit与一个错误时的 email 动作，重新运行，观察动作与限制的实际表现。

实战二：创建你的第一个工作流

1. 进入Workflows → New Workflow。
2. 添加一个Trigger 节点（Manual），连接到引用上面那个事件的Event 节点。
3. 可选：在触发器和事件之间插入一个Controller（例如 Repeat 或 Multiplex）体验并行。
4. 给事件节点的**底部极点（bottom pole）**挂上一个Limit 节点（例如 Max Jobs Limit）。
5. 点击Test Selection或Run，然后检查父工作流作业及其子作业。

关于工作流图编辑，docs/workflows.md 给出关键规则：

• 节点侧面有连接极点：左侧输入、右侧输出，事件/作业节点底部还有专属的限制极点；
• 触发器输出 → 事件/作业/控制器；事件与作业节点可互连并接动作/控制器；动作节点只从事件/作业节点接入；限制节点挂在底部极点；
• 从事件/作业节点引出的连线默认条件是success，点击连线可改为complete、error、warning、critical、abort、tag:NAME或continue；
• 动作节点与限制节点不传递流程——它们只是被合并进启动的子作业；
• Split、Join、Repeat、Multiplex 控制器要求恰好一条输出；Decision 与 Wait 可多路输出；
• 控制器支持 "continue percentage"（成功率阈值）：Repeat/Multiplex/Split 控制的事件/作业节点的On Continue连线在整个受控集合全部结束后只触发一次，适合"全部跑完再执行下一步"的场景；
• 事件节点之间自动传递data与files，另有全局共享的workflowData对象可供非直接相连的节点读写（{ "xy": 1, "workflowData": { "foo": "bar" } }，子作业完成时浅合并回父工作流）。

值得留意的是，工作流实际上是一种特殊的事件：它使用工作流伪插件启动节点图（docs/events.md），在数据模型上存储在事件内（{ start?, nodes: [], connections: [] }，见 docs/data.md）。工作流复用事件 API，没有独立 API（docs/workflows.md 的 API 一节列明了get_events、run_event等入口）。

下一步学习路径

welcome.md 末尾给出了清晰的进阶路线，这里统一转换为仓库根目录相对路径：

• 分步初学者教程：Getting Started with xyOps；
• 添加更多服务器并用分组管理：Servers、Groups；
• 为服务器指标创建监控与告警：Monitors、Alerts；
• 用频道复用通知：Channels；
• 用桶（Buckets）在作业之间共享数据与文件：Buckets；
• 深入高级调度、Catch-Up、范围与黑窗：Triggers；
• 打包与分享自己的插件：Plugins、Marketplace；
• 编写自定义插件的底层协议：xyOps Wire Protocol；
• 完整文档索引：点击应用侧边栏的 "Documentation" 链接即可查阅。

遇到问题或想反馈，可参考 Support Guide。

一句话总结：xyOps 的入门路径就是"一台服务器 → 一个事件 → 一个触发器 → 一组限制与动作 → 一张工作流图"，welcome.md 正是这条路径的路线图；当你把第一个事件稳定运行起来后，再逐步叠加触发器、动作、限制与工作流，即可从零搭建起属于你自己的调度与监控体系。