轻量级 Agent 接入指南

零运维服务器监控 — 5MB 单二进制，无依赖，开箱即用

概述

轻量级 Agent 是灵王 OPS 为没有现有监控系统的服务器提供的推送式采集方案。Agent 以独立二进制文件运行，主动将指标、日志和心跳数据上报给平台，由平台完成阈值评估、告警去重与通知分发。

┌──────────────────────────────────────────────────────────────┐
│                         被监控服务器                          │
│                                                              │
│   lingwang-agent                                             │
│     ├─ 系统指标采集  (CPU / 内存 / 磁盘)                      │
│     ├─ 进程存活检测                                           │
│     ├─ HTTP 健康探测                                          │
│     ├─ TCP 端口检测                                           │
│     └─ 日志采集 (error / warn 自动触发告警)                   │
│              │                                               │
│              │  POST /api/v1/alerts/agent/{tenant_id}        │
│              ▼                                               │
└──────────────────────────────────────────────────────────────┘
                         │
                         ▼
              ┌─────────────────────┐
              │     灵王 OPS        │
              │  告警去重 / 路由    │
              │  通知 / 升级        │
              └─────────────────────┘

适用场景：

• 裸机 / 云主机，未部署 Prometheus / Zabbix
• 临时测试环境或边缘节点快速接入
• 补充现有监控体系的采集盲区

前置条件

• 目标服务器可访问灵王 OPS 的 :8080 端口
• 已登录平台并获取团队 ID（在 团队管理 → 团队设置 中查看）
• 已在平台 接入目标 页面创建类型为 agent 的监控目标，获得 target_id

安装 Agent

方式一：直接下载二进制

# Linux x86_64
curl -L https://ops.sengyueplay.com/agent/lingwang-agent-linux-amd64 \
  -o /usr/local/bin/lingwang-agent
chmod +x /usr/local/bin/lingwang-agent

# Linux ARM64 (树莓派 / ARM 服务器)
curl -L https://ops.sengyueplay.com/agent/lingwang-agent-linux-arm64 \
  -o /usr/local/bin/lingwang-agent
chmod +x /usr/local/bin/lingwang-agent

# macOS ARM (Apple Silicon)
curl -L https://ops.sengyueplay.com/agent/lingwang-agent-darwin-arm64 \
  -o /usr/local/bin/lingwang-agent
chmod +x /usr/local/bin/lingwang-agent

# macOS x86_64
curl -L https://ops.sengyueplay.com/agent/lingwang-agent-darwin-amd64 \
  -o /usr/local/bin/lingwang-agent
chmod +x /usr/local/bin/lingwang-agent

验证安装：

lingwang-agent --version

方式二：Docker 运行

docker run -d \
  --restart unless-stopped \
  --name lingwang-agent \
  --pid host \
  -e LINGWANG_SERVER=http://ops.sengyueplay.com:8080 \
  -e LINGWANG_TARGET_ID={target_id} \
  -e LINGWANG_TEAM_ID={team_id} \
  lingwang/agent:latest

注意：--pid host 允许 Agent 探测宿主机进程，如不需要进程监控可省略。

启动 Agent

最简启动（命令行参数）

lingwang-agent \
  --server http://ops.sengyueplay.com:8080 \
  --target-id {target_id} \
  --team-id {team_id}

使用配置文件

创建 /etc/lingwang-agent/config.yaml：

server: http://ops.sengyueplay.com:8080
target_id: "your-target-id-here"
team_id: "your-team-id-here"
agent_id: "web-server-01"        # 唯一标识，建议使用主机名
interval: 30                     # 采集间隔（秒），默认 30
log_level: info

# 指标采集
metrics:
  cpu: true
  memory: true
  disk: true
  disk_paths:
    - /
    - /data

# HTTP 健康探测
http_checks:
  - name: nginx
    url: http://localhost:80/health
    timeout: 5
    expected_status: 200
  - name: app-api
    url: http://localhost:8080/api/health
    timeout: 5
    expected_status: 200

# TCP 端口检测
tcp_checks:
  - name: mysql
    host: localhost
    port: 3306
    timeout: 3
  - name: redis
    host: localhost
    port: 6379
    timeout: 3

# 进程存活检测
process_checks:
  - name: nginx
    pattern: "nginx: master"
  - name: java-app
    pattern: "com.example.Application"

使用配置文件启动：

lingwang-agent --config /etc/lingwang-agent/config.yaml

环境变量方式（适合 CI/CD 或容器）

所有参数均可通过环境变量配置：

配置为系统服务（Linux systemd）

# 1. 创建配置目录和文件
mkdir -p /etc/lingwang-agent
cat > /etc/lingwang-agent/config.yaml <<EOF
server: http://ops.sengyueplay.com:8080
target_id: "your-target-id"
team_id: "your-team-id"
agent_id: "$(hostname)"
interval: 30
EOF

# 2. 创建 systemd service 文件
cat > /etc/systemd/system/lingwang-agent.service <<EOF
[Unit]
Description=Lingwang OPS Agent
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/lingwang-agent --config /etc/lingwang-agent/config.yaml
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

# 3. 启用并启动
systemctl daemon-reload
systemctl enable lingwang-agent
systemctl start lingwang-agent

# 4. 查看运行状态
systemctl status lingwang-agent
journalctl -u lingwang-agent -f

数据上报格式（API 参考）

Agent 通过 HTTP POST 将数据上报至灵王 OPS，适合自研 Agent 或脚本集成。

端点：

POST /api/v1/alerts/agent/{tenant_id}
Content-Type: application/json

请求体结构：

{
  "agent_id": "web-server-01",
  "heartbeat": {
    "status": "online",
    "version": "1.2.0",
    "hostname": "web-server-01",
    "metrics": {
      "cpu": 45.2,
      "memory": 72.8,
      "disk": 61.5
    }
  },
  "metrics": [
    {
      "name": "cpu_usage",
      "value": 45.2,
      "labels": {
        "host": "web-server-01",
        "core": "all"
      },
      "timestamp": "2026-04-12T17:41:00Z"
    },
    {
      "name": "memory_usage",
      "value": 72.8,
      "labels": {
        "host": "web-server-01"
      },
      "timestamp": "2026-04-12T17:41:00Z"
    },
    {
      "name": "disk_usage",
      "value": 61.5,
      "labels": {
        "host": "web-server-01",
        "mountpoint": "/"
      },
      "timestamp": "2026-04-12T17:41:00Z"
    }
  ],
  "logs": [
    {
      "level": "error",
      "message": "MySQL connection refused on port 3306",
      "labels": {
        "service": "mysql",
        "host": "web-server-01"
      },
      "timestamp": "2026-04-12T17:41:00Z"
    }
  ]
}

字段说明：

响应示例：

{"message": "ok"}

平台告警触发规则

平台对 Agent 上报数据的处理逻辑如下：

指标数据（metrics）目前存储供查询统计，阈值告警通过平台 告警规则 配置实现。

去重机制： 相同 agent_id + 相同 labels 组合产生的告警，平台会自动去重，不产生重复通知。

手动测试接入

无需安装 Agent，用 curl 即可验证接入是否正常：

# 替换为你的实际 tenant_id
TENANT_ID="your-tenant-id"
SERVER="http://ops.sengyueplay.com:8080"

# 发送心跳 + 指标 + 错误日志
curl -s -X POST "${SERVER}/api/v1/alerts/agent/${TENANT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "test-agent-001",
    "heartbeat": {
      "status": "online",
      "version": "test",
      "hostname": "test-server",
      "metrics": {
        "cpu": 88.5,
        "memory": 91.2,
        "disk": 75.0
      }
    },
    "metrics": [
      {
        "name": "cpu_usage",
        "value": 88.5,
        "labels": {"host": "test-server"},
        "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"
      }
    ],
    "logs": [
      {
        "level": "error",
        "message": "Test error log from curl",
        "labels": {"service": "test"},
        "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"
      }
    ]
  }'

预期响应：{"message":"ok"}

然后登录管理后台 → 告警 页面，应看到一条来自 agent 来源的新告警。

在平台注册监控目标

Agent 上报成功后，建议在平台创建对应的监控目标记录，以便追踪 last_seen 时间和管理多台服务器：

# 先获取 Bearer Token（登录接口）
TOKEN="your-jwt-token"

curl -X POST "http://ops.sengyueplay.com:8080/api/v1/monitor-targets" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "生产 Web 服务器 01",
    "type": "agent",
    "endpoint": "test-agent-001",
    "auth_type": "none",
    "labels": "{\"env\":\"production\",\"role\":\"web\"}",
    "is_enabled": true
  }'

endpoint 字段填写与 Agent 配置中 agent_id 完全一致的值，平台用此字段关联上报数据并更新 last_seen_at。

监控目标 API：

多台服务器批量部署

Ansible 一键部署

# deploy-agent.yml
- hosts: all
  become: true
  vars:
    lingwang_server: "http://ops.sengyueplay.com:8080"
    lingwang_team_id: "your-team-id"

  tasks:
    - name: 下载 Agent 二进制
      get_url:
        url: "https://ops.sengyueplay.com/agent/lingwang-agent-linux-amd64"
        dest: /usr/local/bin/lingwang-agent
        mode: '0755'

    - name: 创建配置目录
      file:
        path: /etc/lingwang-agent
        state: directory
        mode: '0755'

    - name: 生成 Agent 配置
      copy:
        dest: /etc/lingwang-agent/config.yaml
        content: |
          server: {{ lingwang_server }}
          team_id: "{{ lingwang_team_id }}"
          agent_id: "{{ ansible_hostname }}"
          interval: 30
          metrics:
            cpu: true
            memory: true
            disk: true

    - name: 部署 systemd service
      copy:
        dest: /etc/systemd/system/lingwang-agent.service
        content: |
          [Unit]
          Description=Lingwang OPS Agent
          After=network.target
          [Service]
          ExecStart=/usr/local/bin/lingwang-agent --config /etc/lingwang-agent/config.yaml
          Restart=always
          RestartSec=10
          [Install]
          WantedBy=multi-user.target

    - name: 启动 Agent 服务
      systemd:
        name: lingwang-agent
        enabled: true
        state: started
        daemon_reload: true

运行：

ansible-playbook -i inventory.ini deploy-agent.yml

故障排查

Agent 启动后平台无数据

1. 检查网络连通性：

curl -v http://ops.sengyueplay.com:8080/health

1. 确认 team_id / target_id 填写正确（区分大小写的 UUID）

2. 查看 Agent 本地日志：

# systemd 模式
journalctl -u lingwang-agent -f --since "5 minutes ago"

# 前台运行模式
lingwang-agent --config /etc/lingwang-agent/config.yaml --log-level debug

1. 手动发一条 curl 验证端点（见上方测试章节）

告警重复产生

• 日志类告警基于 agent_id + level + labels 生成 fingerprint，相同内容自动去重
• 如果同一条日志因格式变化（如含时间戳的 message）导致 fingerprint 不同，建议在 labels 中记录关键字段，message 内容只保留静态描述

Agent 离线告警误触发

Agent 离线告警在 heartbeat.status == "offline" 时产生，正常运行的 Agent 只发送 "online"。如果遇到网络抖动导致误告警，可以在平台 告警规则 中对 source=agent, type=heartbeat 设置延迟或静默窗口。

指标值异常（如 CPU 持续 100%）

Agent 本地调试模式下可查看原始采集值：

lingwang-agent --config /etc/lingwang-agent/config.yaml --dry-run

--dry-run 模式会打印即将上报的 payload 而不实际发送，方便验证采集逻辑。

安全建议

相关文档

• 快速开始 — 平台整体接入流程
• Prometheus Alertmanager 接入 — 已有 Prometheus 的团队
• HTTP Webhook 通用接入 — 自定义告警推送
• 告警规则配置 — 指标阈值告警配置
• 通知渠道配置 — 邮件 / 钉钉 / 飞书 / 企业微信