Files

codex 89d5e27874 💥 feat(agent)!: 添加主机监控代理首版

* 实现周期采集、快照缓存、本地 HTTP API 和主动上报

* 补齐 Linux 和 Windows 主机、网络、资源、进程和 TCP 采集

* 添加服务生命周期管理、配置加载、构建脚本和测试覆盖

BREAKING CHANGE: network.ips 拆分为 network.ipv4s 和 network.ipv6s。

2026-05-18 15:25:51 +00:00

4.5 KiB

Raw Blame History

MFD Monitor Agent Completion Design

Objective

Bring the current Go single-binary host monitoring agent into alignment with AGENTS.md: complete missing host status behavior, preserve cached snapshots, support Linux and Windows service lifecycle, add reporter retry/backoff, improve partial-success handling, and raise comments/tests to the repository standard.

Current Gaps

Package-level Go types, functions, methods, and interfaces are mostly undocumented.
Linux collection misses CPU usage percent, process start time, and process CPU percent.
TCP listener mapping does not clearly report permission-related partial mappings.
Windows collector and service runtime are incomplete; current service install only shells out to sc.exe.
Linux service install does not explicitly require root and does not preserve -config in the systemd unit.
Reporter logs failures but has no retry or bounded backoff.
Tests do not cover enough collector parsing, partial/error statuses, service guards, reporter retry, or HTTP edge cases.

Architecture

Keep the existing single-process architecture and package boundaries:

cmd/agent: CLI and process lifecycle.
config: defaults, JSON file loading, environment overrides.
collector: platform collection into status.HostStatus.
snapshot: collector aggregation and in-memory cache.
httpapi: GET /health and GET /status, cache reads only.
reporter: periodic POST of the cached HostStatus.
service: Windows/Linux service install, uninstall, start, and stop.

No historical storage, pagination, auth, UDP collection, thread lists, process handles, or trend analysis are included.

Behavior Design

Collection remains immediate-on-start and periodic afterward. HTTP and reporter paths both read the same cached snapshot and never trigger a live scan.

Each collector writes only its own section. If one collector fails, snapshot.Cache records a StatusError, marks agent.snapshot_status as partial, and keeps successful sections.

Linux should be the first complete collection implementation:

CPU usage percent from /proc/stat with a bounded sample and context cancellation.
Process start time from /proc/<pid>/stat.
Process CPU percent best-effort; if exact calculation is unavailable, keep the field stable and do not fail the process collector.
TCP listeners from /proc/net/tcp, /proc/net/tcp6, and /proc/<pid>/fd; unreadable process fd data should degrade listener status to partial.

Windows should expose a real service runtime path without NSSM. If full Windows metric collection would require a larger dependency decision, platform files should keep unsupported subsections explicit with partial/error statuses and tests around those contracts.

Service Design

Linux install should require root before writing /etc/systemd/system, render a systemd unit for the configured service name, include agent run, preserve -config <path> when supplied, run daemon-reload, and enable the service. Errors should include the failed operation.

Windows install/start/stop/uninstall should remain behind Windows build tags and avoid NSSM. Administrator requirements should be checked where practical.

Reporter Design

Reporter POST payload remains exactly the HostStatus JSON used by /status. Failed reports are logged and retried once after a short delay or handled with a simple bounded backoff. Retry/backoff must respect context cancellation and never terminate the process or block the local HTTP server.

Comments And Tests

All Go package-level types, structs, interfaces, functions, and methods need concise comments. Comments should explain behavior, side effects, units, platform assumptions, and permission-sensitive degradation.

Tests should be written before behavior changes and cover:

Linux parser helpers for CPU, memory, process stat/status, and TCP listeners.
Snapshot partial aggregation and timeout behavior.
HTTP not-ready and method-not-allowed behavior.
Reporter HTTP errors, retry/backoff, payload structure, and cancellation.
Linux service unit rendering, root guard, and config path propagation.
Windows build-tagged service contracts where compile-testable.

Verification

Completion requires:

go test ./... passes.
Current Linux build passes.
GOOS=windows GOARCH=amd64 go test ./... is attempted and either passes or any blocker is documented with the exact failure.
A final audit maps each AGENTS.md requirement touched by this pass to code, tests, or a documented remaining platform limitation.

4.5 KiB Raw Blame History