💥 feat(agent)!: 添加主机监控代理首版
* 实现周期采集、快照缓存、本地 HTTP API 和主动上报 * 补齐 Linux 和 Windows 主机、网络、资源、进程和 TCP 采集 * 添加服务生命周期管理、配置加载、构建脚本和测试覆盖 BREAKING CHANGE: network.ips 拆分为 network.ipv4s 和 network.ipv6s。
This commit is contained in:
codex
349
plan.md
Normal file
349
plan.md
Normal file
@@ -0,0 +1,349 @@
|
||||
高权限主机状态 Agent 设计方案
|
||||
|
||||
1. 项目简介
|
||||
|
||||
MFD Monitor Agent 是一个使用 Go 实现的单二进制主机状态监控 agent，用于在 Windows 和 Linux 主机上采集并暴露完整主机状态。
|
||||
|
||||
agent 提供本地 HTTP API，默认监听 127.0.0.1:8080。GET /health 用于返回进程存活状态和最近一次快照元数据；GET /status 用于返回缓存中的完整主机状态快照。
|
||||
|
||||
agent 通过后台周期采集刷新内存缓存，避免每次 HTTP 请求都实时扫描系统，从而提升响应速度并降低系统负载。
|
||||
|
||||
agent 支持可选的周期性 HTTP POST 主动上报，上报数据直接复用 HostStatus JSON 结构，避免维护两套数据模型。
|
||||
|
||||
agent 支持通过 CLI 管理服务生命周期，包括 run、install、uninstall、start、stop 和 version。Linux 侧面向 systemd service，Windows 侧面向 Windows Service。
|
||||
|
||||
2. 目标
|
||||
|
||||
开发一个独立的 Go 单二进制 agent，支持安装为 Windows Service 和 Linux systemd service。
|
||||
|
||||
安装阶段要求管理员/root；首版运行阶段也默认使用高权限账户，以稳定采集完整主机信息。
|
||||
|
||||
agent 对外提供 HTTP 接口，核心接口为 GET /status，单次返回完整主机状态快照，包含：
|
||||
- IP
|
||||
- MAC
|
||||
- 主机名
|
||||
- CPU
|
||||
- 内存
|
||||
- 磁盘
|
||||
- 完整进程列表
|
||||
- 监听中的 TCP 端口及其进程映射
|
||||
|
||||
同时 agent 支持按周期向中心端固定 HTTP 接口主动上报同一份状态 JSON。
|
||||
|
||||
|
||||
3. 服务权限说明
|
||||
|
||||
注册为服务这一步基本都需要管理员权限：
|
||||
|
||||
- Windows：创建、删除、启动、停止 Windows Service 需要管理员权限
|
||||
- Linux：写入 systemd unit、systemctl enable/start 通常需要 root
|
||||
|
||||
服务运行阶段：
|
||||
|
||||
- 如果只读取主机名、IP、MAC、内存、磁盘、CPU，通常不一定需要管理员权限
|
||||
- 但如果要稳定获取完整进程列表，以及监听 TCP 端口和进程映射，建议服务默认也以高权限运行
|
||||
|
||||
建议首版权限策略：
|
||||
|
||||
- 安装阶段：必须管理员/root
|
||||
- 运行阶段：默认高权限运行
|
||||
- 接口层：即使某些字段采集失败，也不要让整个 /status 失败，应返回 partial 或错误原因
|
||||
|
||||
|
||||
4. 架构方案
|
||||
|
||||
推荐使用“单进程一体化”架构。
|
||||
|
||||
一个 agent 进程中同时承担以下职责：
|
||||
|
||||
- 周期采集主机状态
|
||||
- 缓存最近一次状态
|
||||
- 对外提供 HTTP 查询接口
|
||||
- 定时向中心端主动上报状态
|
||||
- 负责 Windows/Linux 服务生命周期管理
|
||||
|
||||
虽然是单进程，但代码建议按模块拆分：
|
||||
|
||||
- collector/system：主机名、OS、架构、启动时间、采集时间
|
||||
- collector/network：网卡、IPv4/IPv6、MAC
|
||||
- collector/resource：CPU、内存、磁盘
|
||||
- collector/process：完整进程列表
|
||||
- collector/socket：TCP 监听端口及其进程映射
|
||||
- snapshot：聚合各采集器输出，形成统一 HostStatus
|
||||
- httpapi：提供 GET /health、GET /status
|
||||
- reporter：定时 POST HostStatus 到中心端
|
||||
- service：封装 Windows/Linux 服务生命周期和安装命令
|
||||
- config：统一加载监听地址、采集周期、上报周期、上报目标、机器标识等配置
|
||||
|
||||
|
||||
5. HTTP 接口设计
|
||||
|
||||
建议保留两个接口：
|
||||
|
||||
- GET /health
|
||||
用于返回进程存活、版本、最近快照时间、最近采集状态
|
||||
|
||||
- GET /status
|
||||
返回完整 HostStatus
|
||||
|
||||
根据当前确认的需求，/status 采用单接口全量返回，不拆分接口，不使用 include 参数。
|
||||
|
||||
默认监听地址建议为：
|
||||
|
||||
- 127.0.0.1
|
||||
|
||||
如果后续需要局域网访问，再通过配置改为指定内网地址。
|
||||
|
||||
原因：
|
||||
|
||||
- /status 会返回较多敏感主机信息
|
||||
- 服务以高权限运行时，应尽量缩小默认暴露面
|
||||
|
||||
|
||||
6. HostStatus 建议字段
|
||||
|
||||
建议返回统一 JSON 结构，主要包含以下字段：
|
||||
|
||||
- agent
|
||||
- version
|
||||
- started_at
|
||||
- snapshot_at
|
||||
- snapshot_status
|
||||
|
||||
- host
|
||||
- host_id
|
||||
- hostname
|
||||
- platform
|
||||
- platform_version
|
||||
- arch
|
||||
- uptime_seconds
|
||||
|
||||
- network
|
||||
- interfaces[]
|
||||
- name
|
||||
- mac
|
||||
- mtu
|
||||
- flags
|
||||
- addresses[]
|
||||
- ips[]
|
||||
- macs[]
|
||||
|
||||
- cpu
|
||||
- logical_cores
|
||||
- physical_cores
|
||||
- usage_percent
|
||||
- load_avg
|
||||
- model_name
|
||||
|
||||
- memory
|
||||
- total
|
||||
- used
|
||||
- free
|
||||
- available
|
||||
- used_percent
|
||||
|
||||
- disks[]
|
||||
- device
|
||||
- mount_point
|
||||
- fs_type
|
||||
- total
|
||||
- used
|
||||
- free
|
||||
- used_percent
|
||||
|
||||
- processes
|
||||
- status: ok | partial | error
|
||||
- items[]
|
||||
- pid
|
||||
- ppid
|
||||
- name
|
||||
- exe
|
||||
- cmdline
|
||||
- username
|
||||
- status
|
||||
- start_time
|
||||
- cpu_percent
|
||||
- memory_rss
|
||||
- memory_vms
|
||||
|
||||
- tcp_listeners
|
||||
- status: ok | partial | error
|
||||
- items[]
|
||||
- ip
|
||||
- port
|
||||
- pid
|
||||
- process_name
|
||||
- process_exe
|
||||
- family: ipv4 | ipv6
|
||||
|
||||
- errors[]
|
||||
用于记录子采集器失败原因，例如：
|
||||
- process.cmdline permission denied
|
||||
|
||||
|
||||
7. 采集策略
|
||||
|
||||
建议采用“周期采集 + 内存缓存”：
|
||||
|
||||
- 启动后立即采集一次
|
||||
- 后台定时刷新缓存
|
||||
- HTTP 接口直接读取缓存，不在每次请求时实时扫描系统
|
||||
- 主动上报也读取同一份缓存，避免重复采集
|
||||
|
||||
这样做的好处：
|
||||
|
||||
- 响应更快
|
||||
- 降低系统扫描频率
|
||||
- 避免进程列表和端口列表每次请求都重新采集
|
||||
|
||||
采集时建议设置：
|
||||
|
||||
- 整体采集超时
|
||||
- 单个子采集器失败不拖垮整次快照
|
||||
|
||||
例如：
|
||||
|
||||
- 进程采集失败，仍返回 CPU、内存、磁盘等其他信息
|
||||
- tcp_listeners 采集不完整时，将状态标记为 partial
|
||||
|
||||
|
||||
8. 主动上报设计
|
||||
|
||||
agent 除了支持外部系统通过 HTTP 拉取状态，还支持定时主动上报。
|
||||
|
||||
建议方式：
|
||||
|
||||
- 配置一个固定中心服务 URL
|
||||
- 周期性 POST HostStatus JSON
|
||||
- 上报载荷直接复用 /status 的 JSON 结构
|
||||
|
||||
这样可以避免维护两套数据模型。
|
||||
|
||||
建议配置项：
|
||||
|
||||
- report.enabled
|
||||
- report.endpoint
|
||||
- report.interval
|
||||
- report.timeout
|
||||
|
||||
上报失败策略：
|
||||
|
||||
- 超时和失败日志独立记录
|
||||
- 支持重试或简单退避
|
||||
- 上报失败不能影响本地 HTTP 服务
|
||||
- 上报失败不能导致进程退出
|
||||
|
||||
|
||||
9. CLI 设计
|
||||
|
||||
建议提供以下命令：
|
||||
|
||||
- agent run
|
||||
- agent install
|
||||
- agent uninstall
|
||||
- agent start
|
||||
- agent stop
|
||||
- agent version
|
||||
|
||||
Linux：
|
||||
|
||||
- agent 进程以前台模式运行
|
||||
- 额外提供 systemd unit 模板
|
||||
- 安装脚本负责写入 unit 并启停
|
||||
|
||||
Windows：
|
||||
|
||||
- 使用服务包装库实现 install/uninstall/start/stop/run
|
||||
- 不依赖外部 NSSM
|
||||
|
||||
|
||||
10. 技术建议
|
||||
|
||||
推荐使用 Go 实现，原因：
|
||||
|
||||
- 单二进制，部署简单
|
||||
- Windows 和 Linux 跨平台支持较好
|
||||
- 服务化实现相对成熟
|
||||
- 适合做常驻守护进程和 HTTP 服务
|
||||
|
||||
系统信息采集建议优先使用成熟跨平台库，例如：
|
||||
|
||||
- gopsutil
|
||||
|
||||
这样可以减少自己处理平台差异的工作量。
|
||||
|
||||
如库在“端口到进程映射”能力上不足，可以针对 Windows/Linux 做补充实现。
|
||||
|
||||
|
||||
11. 测试建议
|
||||
|
||||
单元测试：
|
||||
|
||||
- 各采集器输出能正确映射为 HostStatus
|
||||
- 进程列表和 TCP 监听项在空结果、部分字段缺失、权限错误时能输出 partial/error
|
||||
- snapshot 聚合逻辑在部分采集失败时仍返回可用快照
|
||||
|
||||
集成测试：
|
||||
|
||||
- 启动后 GET /health 返回正常
|
||||
- GET /status 返回完整 JSON，包含 cpu、processes、tcp_listeners
|
||||
- 模拟中心端，验证 POST 的载荷、超时、失败重试行为
|
||||
|
||||
平台验证：
|
||||
|
||||
- Windows：服务安装、启动、停止、卸载
|
||||
- Linux：systemd 安装、enable、start、restart
|
||||
|
||||
性能与稳定性：
|
||||
|
||||
- 大量进程场景下 /status 仍在可接受时间内返回
|
||||
- 采集周期与 HTTP 并发访问同时存在时无明显阻塞
|
||||
- /status 响应体较大时内存占用可控
|
||||
|
||||
|
||||
12. 首版边界
|
||||
|
||||
首版默认包括：
|
||||
|
||||
- IP
|
||||
- MAC
|
||||
- 主机名
|
||||
- CPU
|
||||
- 内存
|
||||
- 磁盘
|
||||
- 完整进程列表
|
||||
- TCP 监听端口及进程映射
|
||||
- 本地 HTTP 查询
|
||||
- 主动 HTTP 上报
|
||||
- Windows/Linux 服务化
|
||||
|
||||
首版默认不包括：
|
||||
|
||||
- 历史存储
|
||||
- 趋势分析
|
||||
- 分页查询
|
||||
- UDP 监听信息
|
||||
- 线程列表
|
||||
- 进程句柄
|
||||
- 连接状态详情
|
||||
- 强制 Token/mTLS
|
||||
|
||||
|
||||
13. 结论
|
||||
|
||||
最务实的首版实现方案是：
|
||||
|
||||
- 使用 Go
|
||||
- 单进程一体化架构
|
||||
- 安装时管理员/root 权限
|
||||
- 运行时默认高权限服务账户
|
||||
- GET /status 单接口全量返回
|
||||
- 默认监听 127.0.0.1
|
||||
- 同时支持被动查询和主动上报
|
||||
|
||||
如果进入实现阶段，下一步可以直接开始定义：
|
||||
|
||||
- 配置文件结构
|
||||
- HostStatus Go struct
|
||||
- collector 接口
|
||||
- Windows/Linux 服务安装与运行流程
|
||||
Reference in New Issue
Block a user