mfd-monitor-agent/docs/ARCHITECTURE.md

MFD Monitor Agent 架构与工作流程

本文档汇总当前代码中的实际运行流程，供开发、排障和评审时快速理解 agent 如何从配置加载到采集、缓存、查询、上报和服务化运行。

进程职责

MFD Monitor Agent 采用单进程一体化架构。一个 agent 进程同时负责：

• 周期采集主机状态
• 保存最近一次 HostStatus 内存缓存
• 提供本地 HTTP API
• 可选地向中心端主动 POST 上报
• 执行 Linux/Windows 服务安装、启动、停止和卸载命令

HTTP 查询与主动上报读取同一份缓存，不在请求路径上触发实时系统扫描。

包职责

包	职责
cmd/agent	CLI 分发、配置加载、进程生命周期、HTTP server 启停
internal/config	默认配置、JSON 读取、首次配置生成、环境变量覆盖、配置校验
internal/status	/status 与主动上报共用的 HostStatus JSON 数据模型
internal/collector	平台相关主机、网络、资源、进程、TCP 监听采集
internal/snapshot	子采集器聚合、partial 错误记录、并发安全缓存
internal/httpapi	GET /health 与 GET /status，查询参数 token 鉴权
internal/reporter	周期性 POST 缓存快照，失败重试与日志记录
internal/service	Linux systemd 与 Windows SCM 服务生命周期封装

启动与生命周期

agent 无参数时等价于 agent run。

agent run [-config config.json] 流程：

1. 解析 -config，未指定时使用当前工作目录 config.json。
2. 调用 config.LoadOrCreate。配置不存在时创建默认 JSON 并生成随机 http.token。
3. 创建 snapshot.Cache，启动后台采集循环。
4. 若 report.enabled=true，启动主动上报循环。
5. 启动 HTTP server，默认监听 0.0.0.0:8080。
6. 收到 SIGINT 或 SIGTERM 后优雅关闭 HTTP server。

服务命令 install、uninstall、start、stop 使用 config.Load 读取已有配置，不会自动创建配置文件。

配置加载流程

配置来源按以下顺序生效：

1. config.Default() 提供默认值。
2. JSON 文件覆盖默认值。
3. MFD_AGENT_* 环境变量覆盖 JSON。
4. validate 校验安全和必填项。

关键规则：

• http.token 必填；agent run 首次生成配置时会自动写入随机 token。
• report.enabled=true 时 report.endpoint 必填。
• 自动生成的配置文件权限为 0600，因为其中包含 API token。
• 非法布尔或时长环境变量会被忽略，保留文件中的原值。

采集与缓存流程

snapshot.Cache.Run 启动后立即采集一次，随后按 collect.interval 周期刷新。

每轮采集流程：

1. 用 collect.timeout 创建整体超时 context。
2. 构造新的 HostStatus，默认 agent.snapshot_status=ok。
3. 依次执行 system、network、resource、process、socket 采集器。
4. 子采集器失败时记录到 errors[]，整份快照降级为 partial，其他字段继续保留。
5. 用锁一次性发布最新快照，供 HTTP 与 reporter 并发读取。

processes.status 与 tcp_listeners.status 支持 ok、partial、error。例如 Linux 读取 /proc/<pid>/fd 权限不足时，TCP 端口仍会返回，但进程映射可能不完整并标记为 partial。

HTTP 查询流程

所有 API 都要求查询参数 token：

GET /health?token=<http.token>
GET /status?token=<http.token>

处理流程：

1. withQueryTokenAuth 使用恒定时间比较校验 token。
2. token 缺失、错误或配置 token 为空时返回 401。
3. 非 GET 方法返回 405。
4. /health 读取缓存元数据。首次快照未就绪时返回 503 和 {"status":"starting"}。
5. /status 返回完整缓存 HostStatus。首次快照未就绪时返回 503。

HTTP 请求不会触发采集，避免高并发查询放大系统扫描成本。

主动上报流程

启用条件：

{
  "report": {
    "enabled": true,
    "endpoint": "http://center.example.internal/agent/status"
  }
}

运行流程：

1. reporter.Run 按 report.interval 定时执行。
2. 从 snapshot.Cache 读取最新 HostStatus。
3. 首次快照未就绪时跳过本轮。
4. 以 application/json POST 到 report.endpoint。
5. 非 2xx、网络错误或超时视为失败。
6. 失败后等待短暂退避并重试一次。
7. 最终失败只记录日志，不影响采集循环或本地 HTTP 服务。

上报载荷与 /status 响应结构完全一致。

服务生命周期流程

Linux systemd

agent install -config /path/config.json -exe /path/agent：

1. 检查当前用户必须为 root。
2. 生成 /etc/systemd/system/<service.name>.service。
3. ExecStart 写入 <exe> run -config <path>。
4. 执行 systemctl daemon-reload。
5. 执行 systemctl enable <service.name>。

start、stop 调用 systemctl start/stop。uninstall 尽力 disable --now，删除 unit 文件后再次 daemon-reload。

Windows SCM

Windows 通过 sc.exe 管理服务，不依赖 NSSM。

install 使用 sc.exe create 注册自动启动服务，binPath 为：

"<exe>" run -config "<config>"

start、stop、uninstall 分别调用 sc.exe start、sc.exe stop、sc.exe delete。安装、删除和启停通常需要管理员权限。

HostStatus 数据模型

HostStatus 是唯一对外状态模型，同时用于：

• GET /status 响应体
• 主动上报 POST body
• 测试中的快照断言

顶层字段包括：

• agent：版本、启动时间、快照时间、快照状态
• host：机器标识、主机名、平台、架构、运行时长
• network：网卡明细、IPv4/IPv6、MAC
• cpu：逻辑核心、物理核心、使用率、负载、型号
• memory：内存容量与使用率
• disks：文件系统容量与使用率
• processes：采集状态与完整进程列表
• tcp_listeners：采集状态与 TCP 监听端口到进程映射
• errors：子采集器失败原因

平台差异

Linux 采集主要读取 /proc、/etc/os-release、net.Interfaces 和 statfs。进程与 socket 映射受 /proc/<pid> 权限和进程生命周期竞争影响。

Windows 采集使用 Win32 API、Toolhelp、注册表、PSAPI、iphlpapi 和一次尽力 WMIC 命令。部分字段需要高权限读取进程句柄或令牌，失败时降级为空字段或 partial。

非 Linux/Windows 平台保留基础主机和网络采集，进程与 TCP 监听采集明确返回不支持并标记 partial。