监控平台使用说明

Agent 与 Pipeline 使用说明

---

一、Agent 获取/注册机器配置信息

--server=<服务器ID> 可以通过以下几种方式获取：

需要先安装 sqlite3，或者用项目自带的 node 脚本

node -e "const db = require('better-sqlite3')('./data/monitor.db'); const rows = db.prepare('SELECT id, name, host FROM servers').all(); console.log(rows)"

方式一：在管理平台前端查看（最简单）

1. 打开监控平台的"服务器监控"页面
2. 表格第一列就是服务器 ID，直接复制即可

方式二：调用 API 查询

curl http://localhost:3001/api/agent/servers

返回所有已注册服务器列表，包含 id、name、host 字段，找到对应机器的 id 即可。

方式三：查数据库直接获取

# SQLite
sqlite3 server/data.db "SELECT id, name, host FROM servers;"

方式四：不指定，让 Agent 自动发现

如果不传 --server 参数，Agent 启动时会自动匹配：

1. 采集本机 hostname 和 IP 地址
2. 查询数据库中所有服务器的 host 字段
3. 如果本机标识符与某个 servers.host 精确匹配（不区分大小写），就自动关联

也就是说，只要注册服务器时 host 字段填写正确，Agent 就能自动发现，不需要手动传 --server。

---

自动发现的匹配逻辑

本机 hostname (如 DESKTOP-ABC)
本机 IP     (如 192.168.1.100)
         ↓  与
数据库 servers.host 字段  →  匹配成功 → 自动关联

例如：

• 注册服务器时 host 填 192.168.1.100
• Agent 所在机器 IP 正好是 192.168.1.100
• 启动时自动匹配成功，无需 --server 参数

手动指定 --server 主要用于以下场景：同一台机器注册了多个服务器记录时需要精确指定，或者自动发现匹配不到时手动覆盖。

1. 服务器三级自动发现机制

Agent 启动时（server/agent/engine.js），通过以下三级流程自动识别本机对应的服务器 ID：

优先级	方式	说明
1	--server=<ID> 命令行参数	手动指定，最直接
2	本地 SQLite 数据库查找	查询 servers 表，匹配 host 字段
3	API 自动发现	调用 GET /api/agent/servers 获取所有已注册服务器进行匹配

2. 本机标识符采集

Agent 采集以下信息用于与 servers.host 字段做匹配：

• hostname: os.hostname() 及其小写形式
• 网络 IP: 所有非内部接口的 IPv4/IPv6 地址
• Loopback: 127.0.0.1、localhost、::1

匹配逻辑为不区分大小写的精确匹配。

3. 如果找不到对应服务器？

需要通过以下方式将服务器注册到数据库：

• 交互式注册：python scripts/register_servers.py
• 批量导入：python scripts/register_servers.py --file servers.csv
• 命令行注册：python scripts/register_servers.py --name "Web-01" --host 192.168.1.100 --port 22 --os "CentOS 7" --tags "web,production"
• CSV 模板：scripts/servers_template.csv
• 或者在管理平台的"服务器管理"页面手动添加

关键：注册时 host 字段必须填写能匹配上 Agent 所在机器的 IP 或 hostname。

---

二、Agent 使用说明

项目中有多个版本的 Agent，各有不同用途：

1. Node.js Agent（流水线执行引擎）— 核心

文件：server/agent/engine.js

职责：监控文件目录 → 检测匹配文件 → 执行流水线步骤 → 上报结果

# 本地模式（Agent 和 API 在同一台机器）
node server/agent/engine.js --api=http://localhost:3001/api --token=monitor-agent-token-2024

# 远端模式（Agent 部署在远程服务器）
node server/agent/engine.js --api=http://192.168.1.100:3001/api --token=monitor-agent-token-2024 --server=<服务器ID>

参数	默认值	说明
--api	http://localhost:3001/api	API 服务地址
--token	monitor-agent-token-2024	Agent 认证 Token
--poll	5000 (ms)	流水线配置轮询间隔
--business	(空)	仅监控指定业务
--server	(空)	指定服务器 ID
--deploy-interval	10000 (ms)	部署文件拉取间隔

运行模式自动检测：Agent 检查 uploads/ 目录是否存在，如果存在则为本地模式（直读文件），否则为远端模式（通过 HTTP 下载文件）。

2. Python Agent（系统指标采集）

文件：scripts/agent.py

pip install psutil requests
python scripts/agent.py --server-id <SERVER_ID> --interval 60
python scripts/agent.py --auto-register --name "MyServer" --host 192.168.1.100

采集指标：CPU、内存、磁盘、网络流量、运行时间、Top 5 进程。

3. PowerShell Agent（Windows 指标采集）

文件：scripts/agent.ps1

powershell -File agent.ps1 -ServerId <SERVER_ID> -ApiBase http://localhost:3001/api -Interval 60

4. Shell Agent（Linux 指标采集）

文件：scripts/agent.sh

bash agent.sh <SERVER_ID> [API_BASE] [INTERVAL]

---

三、流水线使用说明

1. 创建流水线

方式一：使用创建工具

# 列出可用模板
node scripts/create_pipeline.js list-templates

# 从模板生成 JSON
node scripts/create_pipeline.js template <name>

# 通过 API 创建
node scripts/create_pipeline.js create my-pipeline.json

# 预览（不实际创建）
node scripts/create_pipeline.js dry-run my-pipeline.json

方式二：在管理平台前端直接创建（"流水线编排"页面）。

2. 流水线 JSON 结构

{
  "code": "pipeline_code",
  "name": "流水线名称",
  "description": "描述",
  "trigger_type": "file_watch",
  "trigger_config": {
    "watch_dir": "监控目录",
    "file_pattern": "*.zip",
    "output_dir": "输出目录",
    "done_dir": "完成归档目录"
  },
  "result_config": {
    "enabled": true,
    "collect_dirs": ["{output_dir}"],
    "include_patterns": ["*.log", "*.pptx"],
    "exclude_patterns": [".task.meta", "*.tmp", "*.temp"],
    "max_file_size_mb": 100,
    "recursive": true
  },
  "steps": [
    {
      "name": "步骤名",
      "step_type": "tool_call",
      "step_order": 0,
      "stop_on_fail": true,
      "config": { "tool": "python", "args": ["script.py", "{input_file}"] }
    }
  ]
}

3. 支持的可配置变量

变量	说明
{input_file}	Agent 监控到的输入文件绝对路径
{filename}	输入文件名（含扩展名）
{filename_noext}	输入文件名（不含扩展名）
{work_dir}	本次执行工作目录（自动创建）
{watch_dir}	监控目录
{output_dir}	输出目录
{now}	当前时间戳（yyyyMMdd_HHmmss）

4. 支持的步骤类型（7 种）

类型	说明	关键配置
file_check	阻塞等待匹配文件出现	wait_dir, file_pattern, timeout_seconds
tool_call	执行命令行工具（支持后台）	tool, args, cwd, timeout_seconds, background
log_check	检测日志内容	file_path, match_pattern, match_type
file_move	移动文件/目录	source, dest
wait	纯延迟等待	seconds
condition	条件判断	expression（支持 previous.xxx, file_exists(), env()）
result_upload	采集并上传结果文件	collect_dirs, include_patterns, exclude_patterns

5. 参考示例

文件	说明
scripts/pipelines/simulation-monitor.json	仿真监控实际生产配置
scripts/pipelines/_example-all-types.json	完整参考模板（Linux 路径）
scripts/pipelines/_example-all-types-si_simulation.json	完整参考模板（Windows 路径）

---

四、Agent API 端点

Agent 与服务端交互的核心 API（server/routes/agent.js）：

方法	路径	用途
GET	/api/agent/pipelines	拉取激活的流水线配置
GET	/api/agent/servers	获取服务器列表（自动发现用）
GET	/api/agent/health	健康检查
POST	/api/agent/executions	创建执行记录
PUT	/api/agent/executions/:id	更新执行状态
POST	/api/agent/executions/:id/steps	上报步骤状态
POST	/api/agent/executions/:id/result-files	上传结果文件
GET	/api/agent/deployments/:serverId	拉取待部署文件

---

典型部署流程

1. 注册服务器 → 在平台添加服务器信息（host 需与 Agent 所在机器匹配）
2. 部署 Agent → 将 server/agent/engine.js 部署到目标服务器
3. 启动 Agent → node server/agent/engine.js --api=<API地址> --server=<服务器ID>
4. 创建流水线 → 在平台创建流水线配置，关联到对应服务器
5. 触发执行 → 向监控目录放入匹配的文件，Agent 自动检测并执行流水线