高权限主机状态 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 服务安装与运行流程