README
¶
Agent V2 文档
概述
Agent V2 是一个功能强大的服务运维代理，专注于提供全面的服务生命周期管理、健康监控、指标采集和自动恢复能力。Agent 通过 gRPC/HTTP 接口与 Controller 通信，实现集中化的服务管理。
核心功能
1. 指标采集系统
Agent V2 提供了强大的多层级指标采集能力，支持系统指标和应用指标的统一采集。
系统指标采集架构
Agent 采用三层采集架构，按优先级自动降级：
-
Telegraf Input 收集器（优先使用，推荐）
- 使用 Telegraf 的 input 插件进行系统指标采集
- 支持跨平台（Linux、macOS、Windows）
- 可配置的插件列表（cpu、mem、disk、diskio、net、system 等）
- 自动转换为 Prometheus 格式
-
增强型收集器（已废弃，仅 Linux）
- 基于 Prometheus Node Exporter 的 collectors
- 支持 70+ 种系统指标采集器
- 仅在 Telegraf Input 未启用时使用
-
基础收集器（降级方案）
- 基本的系统指标采集
- 作为最后的降级方案
应用指标采集
支持从应用服务主动拉取（Pull）和被动接收（Push）两种模式：
-
支持的协议：
- Prometheus（HTTP 端点）
- StatsD（UDP）
- OpenTelemetry（OTLP）
- JSON（HTTP 端点）
-
采集模式：
- 主动拉取：Agent 定期从配置的端点拉取指标
- 被动接收：应用主动推送指标到 Agent
指标策略管理
Agent 支持从 Controller 动态获取指标采集策略：
- 全局策略：适用于所有 Agent 实例的默认策略
- 实例策略：针对特定 Agent 实例的定制策略
- 策略特性：
- 指标优先级（critical、high、medium、low、disabled）
- 自定义采集间隔
- 指标过滤规则（支持通配符）
- 动态策略同步
2. 健康检查系统
Agent 提供多种健康检查方式，确保服务正常运行：
- HTTP 检查：检查 HTTP 端点的可用性和响应
- TCP 检查：检查 TCP 端口的连通性
- 进程检查：检查进程是否运行
- 脚本检查：执行自定义脚本进行健康检查
健康检查支持：
- 可配置的检查间隔和超时时间
- 重试机制
- 健康状态历史记录
- 自动触发恢复机制
3. 自动恢复系统
当服务健康检查失败时，Agent 自动触发恢复流程：
- 自动重启：失败时自动重启服务
- 指数退避：重启间隔逐渐增加，避免频繁重启
- 最大重启次数：防止无限重启循环
- 恢复状态跟踪：记录恢复历史
4. 服务生命周期管理
- 服务注册：自动发现并注册工作目录中的服务
- 服务启动/停止：支持 systemd 和直接启动两种方式
- 服务依赖管理：支持服务依赖关系，按拓扑顺序启动
- 进程用户切换：支持以指定用户身份运行服务
5. 日志管理
- 日志收集：自动收集服务日志
- 日志轮转：支持日志文件自动轮转
- 日志清理：自动清理过期日志
6. 配置管理
- 热重载：支持配置文件热重载，无需重启
- 多格式支持：支持 YAML 配置文件
- 配置验证：启动时验证配置有效性
架构设计
分层架构
┌─────────────────────────────────────┐
│ API Layer (gRPC/HTTP) │
│ - PackageService │
│ - CommandService │
│ - HealthService │
│ - MetricsService │
│ - FileService │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Service Layer │
│ - ServiceManager │
│ - ServiceRegistry │
│ - DependencyManager │
│ - HealthChecker │
│ - MetricsCollector │
│ - LogManager │
│ - AutoRecovery │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Domain Layer │
│ - Service (领域模型) │
│ - HealthStatus │
│ - Metrics │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Infrastructure Layer │
│ - SystemdAdapter │
│ - ProcessManager │
│ - Filesystem │
└─────────────────────────────────────┘
指标采集架构
┌─────────────────────────────────────────────┐
│ MetricsCollector │
│ ┌───────────────────────────────────────┐ │
│ │ TelegrafInputCollector (优先) │ │
│ │ - cpu, mem, disk, net, system │ │
│ └───────────────────────────────────────┘ │
│ ┌───────────────────────────────────────┐ │
│ │ EnhancedCollector (降级，仅Linux) │ │
│ │ - Node Exporter collectors │ │
│ └───────────────────────────────────────┘ │
│ ┌───────────────────────────────────────┐ │
│ │ BasicCollector (最后降级) │ │
│ └───────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ ApplicationMetricsCollector │
│ ┌───────────────────────────────────────┐ │
│ │ Pull Mode (主动拉取) │ │
│ │ - Prometheus Scraper │ │
│ │ - StatsD Collector │ │
│ │ - OTel Collector │ │
│ │ - JSON Collector │ │
│ └───────────────────────────────────────┘ │
│ ┌───────────────────────────────────────┐ │
│ │ Push Mode (被动接收) │ │
│ │ - Prometheus Endpoint │ │
│ │ - StatsD Receiver │ │
│ └───────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
快速开始
1. 配置文件
编辑 configs/agentv2.yaml：
# Agent 配置
agent:
code: "agent-001" # 必须唯一
# 服务注册配置
registry:
enabled: true
etcd_endpoints:
- "127.0.0.1:3379"
etcd_username: "root"
etcd_password: "Etcd@Passw0rd"
# 指标收集配置
metrics:
enabled: true
interval: 10s
collect_system: true
collect_service: true
# 推荐使用 Telegraf Input 收集器（跨平台）
telegraf_inputs_enabled: true
telegraf_inputs_list:
- "cpu"
- "mem"
- "disk"
- "diskio"
- "net"
- "system"
# 或使用增强型收集器（仅 Linux）
# enhanced_enabled: true
# enhanced_only_core: true
2. 启动 Agent
cd unicontroller/controller/agent/cmd/agent
go run main.go -config=../../configs/agentv2.yaml
3. 验证运行
- 健康检查端点：
http://localhost:58080/health - 指标端点：
http://localhost:58080/metrics - gRPC 服务：
localhost:10380
配置说明
指标采集配置
Telegraf Input 收集器（推荐）
metrics:
telegraf_inputs_enabled: true # 启用 Telegraf Input 收集器
telegraf_inputs_list: # 启用的插件列表
- "cpu"
- "mem"
- "disk"
- "diskio"
- "net"
- "system"
telegraf_inputs_interval: 10s # 采集间隔
增强型收集器（仅 Linux，已废弃）
metrics:
enhanced_enabled: true # 启用增强型收集器
enhanced_only_core: true # 只启用核心 collectors
# 或指定启用的 collectors
# enhanced_collectors:
# - "cpu"
# - "meminfo"
# - "loadavg"
应用指标配置
metrics:
application_enabled: true
application_endpoint: ":9091" # Prometheus 格式端点
指标策略配置
metrics:
strategy_enabled: true # 启用策略
strategy_source: "api" # 从 Controller API 获取
strategy_api_url: "" # 留空使用 controller_url
strategy_sync_interval: "30s" # 策略同步间隔
健康检查配置
health_check:
default_interval: 30s # 默认检查间隔
default_timeout: 5s # 默认超时时间
default_retries: 3 # 默认重试次数
自动恢复配置
auto_recovery:
enabled: true # 启用自动恢复
max_restarts: 5 # 最大重启次数
restart_delay: 5s # 重启延迟
backoff_factor: 2.0 # 退避因子
max_backoff: 60s # 最大退避时间
服务配置
服务通过 package.json 文件配置：
{
"id": "my-service",
"name": "My Service",
"version": "1.0.0",
"spec": {
"command": ["/usr/bin/my-service"],
"health_check": {
"type": "http",
"endpoint": "http://localhost:8080/health",
"interval": "30s",
"timeout": "5s",
"retries": 3
},
"metrics": {
"pull": {
"enabled": true,
"protocol": "prometheus",
"endpoint": "http://localhost:9090/metrics",
"interval": 10
}
}
}
}
API 接口
gRPC 服务
- PackageService：服务包管理（安装、卸载、列表、配置）
- CommandService：服务命令（启动、停止、重启、暂停、恢复）
- HealthService：健康检查查询
- MetricsService：指标查询和上报
- FileService：文件操作（上传、下载、列表）
HTTP 端点
GET /health：Agent 健康状态GET /metrics：Prometheus 格式指标GET /api/v1/services：服务列表GET /api/v1/services/{id}/health：服务健康状态GET /api/v1/services/{id}/metrics：服务指标
与 Controller 集成
Agent 通过 etcd 服务注册机制与 Controller 集成：
- 服务注册：Agent 启动后自动向 etcd 注册
- 状态同步：Agent 定期更新注册信息（心跳）
- 服务发现：Controller 自动发现并连接 Agent
- 策略同步：Agent 从 Controller 获取指标采集策略
最佳实践
1. 指标采集
- 推荐使用 Telegraf Input 收集器：跨平台、稳定可靠
- 配置策略管理：通过 Controller 统一管理指标采集策略
- 合理设置采集间隔：根据指标重要性设置不同的采集间隔
2. 健康检查
- 选择合适的检查类型：HTTP 检查适用于 Web 服务，TCP 检查适用于网络服务
- 设置合理的超时时间：避免因网络延迟导致误报
- 配置重试机制：提高检查的可靠性
3. 自动恢复
- 设置最大重启次数：防止无限重启循环
- 配置指数退避：避免频繁重启导致资源浪费
- 监控恢复历史：及时发现服务异常
4. 服务配置
- 使用依赖管理：确保服务按正确顺序启动
- 配置健康检查：及时发现服务异常
- 配置指标采集：监控服务运行状态
故障排查
指标采集问题
-
检查收集器状态：
- 查看日志确认使用的收集器类型
- 检查 Telegraf Input 插件是否正常初始化
-
检查策略配置：
- 确认策略是否从 Controller 成功加载
- 检查指标是否被策略规则过滤
-
检查网络连接：
- 确认应用指标端点是否可访问
- 检查防火墙规则
健康检查问题
-
检查配置：
- 确认健康检查类型和端点配置正确
- 检查超时时间和重试次数设置
-
检查服务状态：
- 确认服务是否正常运行
- 检查服务日志
服务注册问题
-
检查 etcd 连接：
- 确认 etcd 地址和认证信息正确
- 检查网络连通性
-
检查 Agent Code：
- 确认 Agent Code 唯一
- 检查是否与其他 Agent 冲突
开发指南
目录结构
agent/
├── cmd/
│ ├── agent/ # Agent 主程序
│ └── config-validator/ # 配置验证工具
├── internal/ # 内部实现
│ ├── api/ # gRPC/HTTP API 实现
│ ├── server/ # 服务器实现
│ └── wire.go # 依赖注入配置
├── pkg/ # 公共包
│ ├── config/ # 配置管理
│ ├── domain/ # 领域模型
│ ├── ops/ # 运维功能
│ │ ├── health/ # 健康检查
│ │ ├── metrics/ # 指标采集
│ │ ├── recovery/ # 自动恢复
│ │ └── logs/ # 日志管理
│ └── service/ # 服务管理
└── configs/ # 配置文件
添加新的指标采集器
- 实现
Scraper接口（pkg/ops/metrics/protocols/scraper.go） - 在
ScraperFactory中注册 - 在配置中添加支持
添加新的健康检查类型
- 实现
Checker接口（pkg/ops/health/health_checker.go） - 在
createChecker方法中添加创建逻辑 - 在服务配置中添加支持
版本历史
v2.0.0（当前版本）
- ✅ 重构指标采集架构，支持 Telegraf Input 收集器
- ✅ 支持应用指标主动拉取和被动接收
- ✅ 支持指标采集策略管理
- ✅ 完善健康检查和自动恢复机制
- ✅ 支持服务依赖管理
- ✅ 支持配置热重载
许可证
[许可证信息]
贡献
欢迎提交 Issue 和 Pull Request。
Directories
Click to show internal directories.
Click to hide internal directories.