xsxiaosa/mfd-monitor-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(agent): 统一中文注释并补充部署文档

Browse Source 
将代码与测试注释改为中文以符合仓库规范；新增中文部署指南、
示例配置，并完善构建脚本对 VERSION 注入的说明。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
codex
2026-05-19 02:30:49 +00:00
parent 89d5e27874
commit 877e4cf41d
28 changed files with 608 additions and 226 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
internal/collector/collector_windows.go
View File

@@ -62,7 +62,7 @@ var (
windowsLookupAccountSidWProc = windowsAdvapi32.NewProc("LookupAccountSidW")
)
// windowsMemoryStatus mirrors the Windows MEMORYSTATUSEX structure used by GlobalMemoryStatusEx.
// windowsMemoryStatus 镜像 GlobalMemoryStatusEx 使用的 Windows MEMORYSTATUSEX 结构。
type windowsMemoryStatus struct {
Length uint32
MemoryLoad uint32
@@ -75,7 +75,7 @@ type windowsMemoryStatus struct {
AvailExtendedVirtual uint64
}
// windowsMIBTCPRowOwnerPID mirrors a MIB_TCPROW_OWNER_PID row returned by GetExtendedTcpTable.
// windowsMIBTCPRowOwnerPID 镜像 GetExtendedTcpTable 返回的 MIB_TCPROW_OWNER_PID 行。
type windowsMIBTCPRowOwnerPID struct {
State uint32
LocalAddr uint32
@@ -85,7 +85,7 @@ type windowsMIBTCPRowOwnerPID struct {
OwningPID uint32
}
// windowsMIBTCP6RowOwnerPID mirrors a MIB_TCP6ROW_OWNER_PID row returned by GetExtendedTcpTable.
// windowsMIBTCP6RowOwnerPID 镜像 GetExtendedTcpTable 返回的 MIB_TCP6ROW_OWNER_PID 行。
type windowsMIBTCP6RowOwnerPID struct {
State uint32
LocalAddr [16]byte
@@ -97,7 +97,7 @@ type windowsMIBTCP6RowOwnerPID struct {
OwningPID uint32
}
// windowsSystemInfo mirrors the subset of SYSTEM_INFO needed for CPU package sizing.
// windowsSystemInfo 镜像 CPU 封装规模计算所需的 SYSTEM_INFO 子集。
type windowsSystemInfo struct {
ProcessorArchitecture uint16
Reserved uint16
@@ -112,21 +112,21 @@ type windowsSystemInfo struct {
ProcessorRevision uint16
}
// windowsSystemTimes stores system CPU time counters as 100ns units.
// windowsSystemTimes 以 100 纳秒为单位存储系统 CPU 时间计数。
type windowsSystemTimes struct {
Idle uint64
Kernel uint64
User uint64
}
// windowsLogicalProcessorInformation mirrors SYSTEM_LOGICAL_PROCESSOR_INFORMATION for core counting.
// windowsLogicalProcessorInformation 镜像用于统计核心的 SYSTEM_LOGICAL_PROCESSOR_INFORMATION。
type windowsLogicalProcessorInformation struct {
ProcessorMask uintptr
Relationship uint32
Data [16]byte
}
// windowsProcessMemoryCounters mirrors PROCESS_MEMORY_COUNTERS.
// windowsProcessMemoryCounters 镜像 PROCESS_MEMORY_COUNTERS。
type windowsProcessMemoryCounters struct {
CB uint32
PageFaultCount uint32
@@ -140,7 +140,7 @@ type windowsProcessMemoryCounters struct {
PeakPagefileUsage uintptr
}
// windowsProcessDetails contains best-effort per-process fields requiring extra handles or commands.
// windowsProcessDetails 包含需额外句柄或命令才能获取的尽力进程字段。
type windowsProcessDetails struct {
Exe string
Cmdline string
@@ -152,7 +152,7 @@ type windowsProcessDetails struct {
MemoryVMS uint64
}
// collectSystem fills Windows host identity, OS, and architecture fields.
// collectSystem 填充 Windows 主机标识、操作系统与架构字段。
func collectSystem(_ context.Context, hostID string, out *status.HostStatus) error {
hostname, err := os.Hostname()
if err != nil {
@@ -170,7 +170,7 @@ func collectSystem(_ context.Context, hostID string, out *status.HostStatus) err
return nil
}
// collectNetwork fills Windows interface, address, and MAC data using the portable net package.
// collectNetwork 使用可移植 net 包填充 Windows 网卡、地址与 MAC 数据。
func collectNetwork(_ context.Context, out *status.HostStatus) error {
ifaces, err := net.Interfaces()
if err != nil {
@@ -195,7 +195,7 @@ func collectNetwork(_ context.Context, out *status.HostStatus) error {
return nil
}
// collectResource fills Windows CPU, memory, and disk resource data.
// collectResource 填充 Windows CPU、内存与磁盘资源数据。
func collectResource(ctx context.Context, out *status.HostStatus) error {
var errs []error
out.CPU.LogicalCores = runtime.NumCPU()
@@ -217,7 +217,7 @@ func collectResource(ctx context.Context, out *status.HostStatus) error {
return errors.Join(errs...)
}
// collectProcesses enumerates Windows processes with Toolhelp and returns best-effort names.
// collectProcesses 通过 Toolhelp 枚举 Windows 进程并返回尽力获取的名称等信息。
func collectProcesses(_ context.Context, out *status.HostStatus) error {
processes, err := windowsProcessList()
out.Processes.Items = processes
@@ -229,7 +229,7 @@ func collectProcesses(_ context.Context, out *status.HostStatus) error {
return nil
}
// collectSockets reads Windows TCP listener tables and maps listener PIDs to process names.
// collectSockets 读取 Windows TCP 监听表并将监听 PID 映射到进程名。
func collectSockets(_ context.Context, out *status.HostStatus) error {
processes, processErr := windowsProcessMap()
var errs []error
@@ -259,7 +259,7 @@ func collectSockets(_ context.Context, out *status.HostStatus) error {
return nil
}
// windowsReadMemory calls GlobalMemoryStatusEx and converts physical memory counters to API fields.
// windowsReadMemory 调用 GlobalMemoryStatusEx 并将物理内存计数转换为 API 字段。
func windowsReadMemory() (status.MemoryInfo, error) {
memory := windowsMemoryStatus{Length: uint32(unsafe.Sizeof(windowsMemoryStatus{}))}
ok, _, err := windowsGlobalMemoryStatusExProc.Call(uintptr(unsafe.Pointer(&memory)))
@@ -269,7 +269,7 @@ func windowsReadMemory() (status.MemoryInfo, error) {
return windowsMemoryInfoFromStatus(memory), nil
}
// windowsVersion returns the legacy Windows major.minor.build tuple exposed by GetVersion.
// windowsVersion 返回 GetVersion 暴露的传统 major.minor.build 版本元组。
func windowsVersion() string {
version, err := syscall.GetVersion()
if err != nil {
@@ -281,13 +281,13 @@ func windowsVersion() string {
return fmt.Sprintf("%d.%d.%d", major, minor, build)
}
// windowsUptimeSeconds returns host uptime in seconds from GetTickCount64.
// windowsUptimeSeconds 从 GetTickCount64 返回主机运行时长（秒）。
func windowsUptimeSeconds() uint64 {
millis, _, _ := windowsGetTickCount64Proc.Call()
return uint64(millis) / 1000
}
// windowsPhysicalCores returns physical CPU core count from Windows processor topology.
// windowsPhysicalCores 从 Windows 处理器拓扑返回物理 CPU 核心数。
func windowsPhysicalCores() int {
var size uint32
result, _, _ := windowsGetLogicalProcessorInfoProc.Call(0, uintptr(unsafe.Pointer(&size)))
@@ -319,7 +319,7 @@ func windowsPhysicalCores() int {
return runtime.NumCPU()
}
// windowsCPUModelName reads the first processor name from the registry.
// windowsCPUModelName 从注册表读取首个处理器名称。
func windowsCPUModelName() string {
keyPath, _ := syscall.UTF16PtrFromString(`HARDWARE\DESCRIPTION\System\CentralProcessor\0`)
var key syscall.Handle
@@ -344,7 +344,7 @@ func windowsCPUModelName() string {
return strings.TrimSpace(syscall.UTF16ToString(utf16s))
}
// windowsReadCPUUsagePercent samples GetSystemTimes and returns best-effort CPU usage.
// windowsReadCPUUsagePercent 采样 GetSystemTimes 并返回尽力估算的 CPU 使用率。
func windowsReadCPUUsagePercent(ctx context.Context) float64 {
prev, err := windowsReadSystemTimes()
if err != nil {
@@ -362,7 +362,7 @@ func windowsReadCPUUsagePercent(ctx context.Context) float64 {
return windowsCPUUsagePercent(prev, next)
}
// windowsReadSystemTimes returns idle, kernel, and user system counters from GetSystemTimes.
// windowsReadSystemTimes 从 GetSystemTimes 返回空闲、内核与用户系统计数。
func windowsReadSystemTimes() (windowsSystemTimes, error) {
var idle, kernel, user syscall.Filetime
ok, _, err := windowsGetSystemTimesProc.Call(
@@ -376,7 +376,7 @@ func windowsReadSystemTimes() (windowsSystemTimes, error) {
return windowsSystemTimes{Idle: windowsFiletimeUint64(idle), Kernel: windowsFiletimeUint64(kernel), User: windowsFiletimeUint64(user)}, nil
}
// windowsCPUUsagePercent calculates non-idle CPU percentage between two Windows CPU samples.
// windowsCPUUsagePercent 根据两次 Windows CPU 采样计算非空闲 CPU 百分比。
func windowsCPUUsagePercent(prev windowsSystemTimes, next windowsSystemTimes) float64 {
prevTotal := prev.Kernel + prev.User
nextTotal := next.Kernel + next.User
@@ -391,12 +391,12 @@ func windowsCPUUsagePercent(prev windowsSystemTimes, next windowsSystemTimes) fl
return float64(totalDelta-idleDelta) / float64(totalDelta) * 100
}
// windowsFiletimeUint64 converts a FILETIME to a monotonically comparable counter.
// windowsFiletimeUint64 将 FILETIME 转换为可单调比较的计数。
func windowsFiletimeUint64(value syscall.Filetime) uint64 {
return uint64(value.HighDateTime)<<32 | uint64(value.LowDateTime)
}
// windowsReadDisks enumerates fixed and remote Windows drives and returns capacity data.
// windowsReadDisks 枚举 Windows 本地固定盘与远程盘并返回容量数据。
func windowsReadDisks() ([]status.DiskInfo, error) {
mask, _, _ := windowsGetLogicalDrivesProc.Call()
if mask == 0 {
@@ -430,7 +430,7 @@ func windowsReadDisks() ([]status.DiskInfo, error) {
return disks, errors.Join(errs...)
}
// windowsDiskInfoFromSpace converts Windows disk capacity counters into API disk fields.
// windowsDiskInfoFromSpace 将 Windows 磁盘容量计数转换为 API 磁盘字段。
func windowsDiskInfoFromSpace(root string, driveType uint32, total uint64, free uint64) status.DiskInfo {
used := uint64(0)
if total >= free {
@@ -446,7 +446,7 @@ func windowsDiskInfoFromSpace(root string, driveType uint32, total uint64, free
}
}
// windowsDriveTypeName maps Windows drive type constants to stable API labels.
// windowsDriveTypeName 将 Windows 驱动器类型常量映射为稳定的 API 标签。
func windowsDriveTypeName(driveType uint32) string {
switch driveType {
case windowsDriveFixed:
@@ -458,7 +458,7 @@ func windowsDriveTypeName(driveType uint32) string {
}
}
// windowsMemoryInfoFromStatus converts Windows physical memory counters into HostStatus memory data.
// windowsMemoryInfoFromStatus 将 Windows 物理内存计数转换为 HostStatus 内存数据。
func windowsMemoryInfoFromStatus(memory windowsMemoryStatus) status.MemoryInfo {
used := uint64(0)
if memory.TotalPhys >= memory.AvailPhys {
@@ -474,7 +474,7 @@ func windowsMemoryInfoFromStatus(memory windowsMemoryStatus) status.MemoryInfo {
}
}
// windowsTCPListeners returns IPv4 or IPv6 TCP listeners from GetExtendedTcpTable.
// windowsTCPListeners 从 GetExtendedTcpTable 返回 IPv4 或 IPv6 TCP 监听项。
func windowsTCPListeners(family int, familyName string, processes map[int]status.ProcessInfo) ([]status.TCPListenerInfo, error) {
table, err := windowsExtendedTCPTable(family)
if err != nil {
@@ -490,7 +490,7 @@ func windowsTCPListeners(family int, familyName string, processes map[int]status
return windowsParseTCP6Rows(table[4:], count, processes), nil
}
// windowsExtendedTCPTable calls GetExtendedTcpTable and returns the raw table bytes.
// windowsExtendedTCPTable 调用 GetExtendedTcpTable 并返回原始表字节。
func windowsExtendedTCPTable(family int) ([]byte, error) {
var size uint32
result, _, _ := windowsGetExtendedTCPTableProc.Call(
@@ -522,7 +522,7 @@ func windowsExtendedTCPTable(family int) ([]byte, error) {
return table, nil
}
// windowsParseTCP4Rows converts raw MIB_TCPROW_OWNER_PID rows into listener records.
// windowsParseTCP4Rows 将原始 MIB_TCPROW_OWNER_PID 行转换为监听记录。
func windowsParseTCP4Rows(rows []byte, count uint32, processes map[int]status.ProcessInfo) []status.TCPListenerInfo {
rowSize := int(unsafe.Sizeof(windowsMIBTCPRowOwnerPID{}))
items := make([]status.TCPListenerInfo, 0, count)
@@ -546,7 +546,7 @@ func windowsParseTCP4Rows(rows []byte, count uint32, processes map[int]status.Pr
return items
}
// windowsParseTCP6Rows converts raw MIB_TCP6ROW_OWNER_PID rows into listener records.
// windowsParseTCP6Rows 将原始 MIB_TCP6ROW_OWNER_PID 行转换为监听记录。
func windowsParseTCP6Rows(rows []byte, count uint32, processes map[int]status.ProcessInfo) []status.TCPListenerInfo {
rowSize := int(unsafe.Sizeof(windowsMIBTCP6RowOwnerPID{}))
items := make([]status.TCPListenerInfo, 0, count)
@@ -568,13 +568,13 @@ func windowsParseTCP6Rows(rows []byte, count uint32, processes map[int]status.Pr
return items
}
// windowsTCPPortFromNetworkOrder decodes the low 16 bits Windows stores in network byte order.
// windowsTCPPortFromNetworkOrder 解码 Windows 以网络字节序存储的低 16 位端口。
func windowsTCPPortFromNetworkOrder(raw uint32) int {
port := uint16(raw)
return int(port>>8) | int(port&0xff)<<8
}
// windowsProcessList enumerates processes with the Windows Toolhelp snapshot API.
// windowsProcessList 使用 Windows Toolhelp 快照 API 枚举进程。
func windowsProcessList() ([]status.ProcessInfo, error) {
cmdlines := windowsProcessCommandLines()
snapshot, err := syscall.CreateToolhelp32Snapshot(syscall.TH32CS_SNAPPROCESS, 0)
@@ -604,7 +604,7 @@ func windowsProcessList() ([]status.ProcessInfo, error) {
}
}
// windowsProcessInfoFromEntry combines Toolhelp identity data with optional process details.
// windowsProcessInfoFromEntry 合并 Toolhelp 身份数据与可选进程详情。
func windowsProcessInfoFromEntry(entry syscall.ProcessEntry32, details windowsProcessDetails) status.ProcessInfo {
name := syscall.UTF16ToString(entry.ExeFile[:])
exe := details.Exe
@@ -619,7 +619,7 @@ func windowsProcessInfoFromEntry(entry syscall.ProcessEntry32, details windowsPr
}
}
// windowsReadProcessDetails opens a process and reads fields that may require elevated privileges.
// windowsReadProcessDetails 打开进程并读取可能需要提升权限的字段。
func windowsReadProcessDetails(pid uint32) windowsProcessDetails {
handle, err := syscall.OpenProcess(windowsProcessQueryLimitedInfo|windowsProcessQueryInformation|windowsProcessVMRead, false, pid)
if err != nil {
@@ -634,7 +634,7 @@ func windowsReadProcessDetails(pid uint32) windowsProcessDetails {
return details
}
// windowsQueryProcessImageName returns the full process image path when access allows it.
// windowsQueryProcessImageName 在访问允许时返回完整进程映像路径。
func windowsQueryProcessImageName(handle syscall.Handle) string {
buf := make([]uint16, windowsMaxPath)
size := uint32(len(buf))
@@ -650,7 +650,7 @@ func windowsQueryProcessImageName(handle syscall.Handle) string {
return syscall.UTF16ToString(buf[:size])
}
// windowsQueryProcessTimes returns start time and lifetime-average CPU percentage.
// windowsQueryProcessTimes 返回启动时间与生命周期平均 CPU 百分比。
func windowsQueryProcessTimes(handle syscall.Handle) (int64, float64) {
var creation, exit, kernel, user syscall.Filetime
if err := syscall.GetProcessTimes(handle, &creation, &exit, &kernel, &user); err != nil {
@@ -666,7 +666,7 @@ func windowsQueryProcessTimes(handle syscall.Handle) (int64, float64) {
return startNanos / int64(time.Second), percent
}
// windowsQueryProcessMemory returns working set and pagefile usage when access allows it.
// windowsQueryProcessMemory 在访问允许时返回工作集与页面文件占用。
func windowsQueryProcessMemory(handle syscall.Handle) (uint64, uint64) {
counters := windowsProcessMemoryCounters{CB: uint32(unsafe.Sizeof(windowsProcessMemoryCounters{}))}
ok, _, _ := windowsGetProcessMemoryInfoProc.Call(
@@ -680,7 +680,7 @@ func windowsQueryProcessMemory(handle syscall.Handle) (uint64, uint64) {
return uint64(counters.WorkingSetSize), uint64(counters.PagefileUsage)
}
// windowsQueryProcessUsername returns DOMAIN\user for a process token when access allows it.
// windowsQueryProcessUsername 在访问允许时返回进程令牌的 DOMAIN\user。
func windowsQueryProcessUsername(handle syscall.Handle) string {
var token syscall.Handle
ok, _, _ := windowsOpenProcessTokenProc.Call(uintptr(handle), uintptr(windowsTokenQuery), uintptr(unsafe.Pointer(&token)))
@@ -702,7 +702,7 @@ func windowsQueryProcessUsername(handle syscall.Handle) string {
return windowsLookupAccountName(sid)
}
// windowsLookupAccountName resolves a SID pointer to DOMAIN\name.
// windowsLookupAccountName 将 SID 指针解析为 DOMAIN\name。
func windowsLookupAccountName(sid uintptr) string {
var nameSize, domainSize uint32
var sidType uint32
@@ -732,7 +732,7 @@ func windowsLookupAccountName(sid uintptr) string {
return domainName + `\` + account
}
// windowsProcessCommandLines reads command lines in one best-effort WMIC call to avoid per-process shelling.
// windowsProcessCommandLines 通过一次尽力 WMIC 调用读取命令行，避免逐进程 shell。
func windowsProcessCommandLines() map[int]string {
out := map[int]string{}
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
@@ -760,7 +760,7 @@ func windowsProcessCommandLines() map[int]string {
return out
}
// windowsProcessMap returns process metadata keyed by PID for TCP owner mapping.
// windowsProcessMap 返回以 PID 为键的进程元数据，供 TCP 属主映射使用。
func windowsProcessMap() (map[int]status.ProcessInfo, error) {
processes, err := windowsProcessList()
out := make(map[int]status.ProcessInfo, len(processes))
@@ -770,7 +770,7 @@ func windowsProcessMap() (map[int]status.ProcessInfo, error) {
return out, err
}
// windowsSortedKeys returns deterministic sorted keys from a string set.
// windowsSortedKeys 从字符串集合返回确定顺序的排序键列表。
func windowsSortedKeys(values map[string]struct{}) []string {
keys := make([]string, 0, len(values))
for key := range values {