簡介fog-client是一款基于C#開發(fā)的跨平臺(tái)計(jì)算機(jī)管理客戶端面向系統(tǒng)管理員與IT運(yùn)維人員解決Windows、Linux、macOS環(huán)境下的遠(yuǎn)程集中管理問題。資源包為zip格式共304個(gè)文件壓縮包整體僅7.7MB文件類型以cs源碼、resx界面資源、config配置文件為主同時(shí)包含plist、sh等跨平臺(tái)配置與腳本便于二次開發(fā)與自定義部署。目前已有169人學(xué)習(xí)下載。包內(nèi)提供完整客戶端源碼及構(gòu)建相關(guān)配置覆蓋自動(dòng)登出、自動(dòng)更新、能源管理、設(shè)備改名、Active Directory/Samba/Open Directory目錄加入以及TCP/IP、CUPS等多樣打印機(jī)管理模塊。無論是希望研究跨平臺(tái)客戶端架構(gòu)的開發(fā)者還是需要對(duì)接FOG服務(wù)器的運(yùn)維人員都能從中獲得可直接參考的實(shí)現(xiàn)思路與可編譯的基礎(chǔ)工程。1. 快速判斷fog-client 憑什么值得你下內(nèi)網(wǎng)里幾十臺(tái) Windows 和 Linux 機(jī)器需要統(tǒng)一納管的時(shí)候大家的第一反應(yīng)通常是 Ansible 或者 SaltStack。但如果你要的是一套能嵌進(jìn)自己運(yùn)維平臺(tái)、采集項(xiàng)和上報(bào)協(xié)議都能定制、跑起來就一個(gè)進(jìn)程的輕量客戶端fog-client 這種 C# 實(shí)現(xiàn)的方案反而更順手。它本質(zhì)是一個(gè)跨平臺(tái)計(jì)算機(jī)管理客戶端定時(shí)采集 CPU、內(nèi)存、磁盤和系統(tǒng)標(biāo)識(shí)把數(shù)據(jù)以 JSON 上報(bào)到服務(wù)端同時(shí)輪詢遠(yuǎn)程任務(wù)執(zhí)行完回傳結(jié)果。適合在做資產(chǎn)盤點(diǎn)、運(yùn)維自動(dòng)化或邊緣設(shè)備管理、且團(tuán)隊(duì)有 C# 技術(shù)棧的開發(fā)者。最直接的價(jià)值是部署成本可控不依賴目標(biāo)機(jī)預(yù)裝運(yùn)行時(shí)一條發(fā)布命令就能壓出 Windows 和 Linux 兩個(gè)平臺(tái)的單文件程序。下面把它的模塊劃分、核心代碼、部署方式和坑一個(gè)個(gè)拆開。2. 客戶端底座C# 跨平臺(tái)的模塊劃分與選型取舍2.1 為什么選 C#管理客戶端技術(shù)路線的取舍管理客戶端這個(gè)場景候選語言通常就三門Python、Go、C#。我以前用 Python 寫過一版采集代理上線第一個(gè)月就遇到兩個(gè)問題一是打包出來的目錄結(jié)構(gòu)在無圖形環(huán)境里看著像黑匣子二是每次升級(jí)都要處理系統(tǒng)和 Python 版本錯(cuò)位。后來切到 Go 試過編譯產(chǎn)物確實(shí)干凈但團(tuán)隊(duì)里沒人愿意維護(hù)復(fù)雜的狀態(tài)機(jī)而且遇到 Windows 域環(huán)境、WMI 這類系統(tǒng) API總覺得隔了一層。C# 的路數(shù)不一樣它在 Windows 上原生能碰 WMI、注冊表和性能計(jì)數(shù)器在 Linux 上又能通過 /proc 和 /sys 拿系統(tǒng)信息兩邊都能用同一套 async/await 去組織采集流程。加上 .NET 5 以后的自包含發(fā)布目標(biāo)機(jī)不需要預(yù)裝運(yùn)行時(shí)單個(gè)可執(zhí)行文件帶著 runtime 跑跟 Go 的部署形態(tài)差不多。維度C#.NET 5PythonGo部署產(chǎn)物單文件 自帶運(yùn)行時(shí)目錄、虛擬環(huán)境單文件Windows 系統(tǒng) API原生WMI/注冊表需第三方庫封裝需 syscall 層封裝Linux 系統(tǒng)信息/proc、/sysfs 直接讀方便方便異步并發(fā)模型async/await 成熟相對(duì)弱強(qiáng)團(tuán)隊(duì)維護(hù)成本有 C# 底子的團(tuán)隊(duì)容易接腳本編輯自由需要 Go 經(jīng)驗(yàn)這個(gè)對(duì)比不是說 C# 一定比另外兩門強(qiáng)而是在管理客戶端這個(gè)場景里它兩邊都能占到便宜Windows 側(cè)不需要繞一層 agentLinux 側(cè)不需要自找麻煩。后面要拆的 fog-client大體上就按采集器、任務(wù)執(zhí)行器、上報(bào)通道、本地調(diào)度四個(gè)模塊組織職責(zé)邊界非常清楚。2.2 從采集到上報(bào)四個(gè)模塊的職責(zé)邊界管理客戶端最忌把所有邏輯混在 Main 方法里fog-client 的拆分方式值得參考。采集器只負(fù)責(zé)從系統(tǒng)層拿數(shù)據(jù)輸出統(tǒng)一的 DeviceInfo 對(duì)象不關(guān)心數(shù)據(jù)怎么發(fā)出去任務(wù)執(zhí)行器從隊(duì)列里取服務(wù)端下發(fā)的任務(wù)區(qū)分 shell 命令、文件同步、定時(shí)快照等類型執(zhí)行完寫 TaskResult上報(bào)通道把序列化后的 JSON POST 到服務(wù)端管超時(shí)、重試和失敗緩存本地調(diào)度用多個(gè)周期定時(shí)器驅(qū)動(dòng)上面的三塊心跳、全量上報(bào)、任務(wù)輪詢各自用獨(dú)立間隔。這個(gè)拆分帶來的直接好處是你改采集邏輯時(shí)不用動(dòng)上報(bào)代碼換服務(wù)端協(xié)議時(shí)也不用碰采集器。比如服務(wù)端從 HTTP 改成 HTTPS只需要?jiǎng)?Reporter 和配置文件采集器一行不用改。任務(wù)執(zhí)行器的本地隊(duì)列還有個(gè)隱藏作用哪怕服務(wù)端異常下發(fā)了一百個(gè)任務(wù)客戶端也會(huì)一條條消化而不是瞬時(shí)創(chuàng)建一百個(gè)進(jìn)程把 CPU 打滿相當(dāng)于一個(gè)天然的背壓閥。2.3 同一套源碼跑兩個(gè)平臺(tái)條件編譯與運(yùn)行時(shí)判斷跨平臺(tái)在 C# 里靠兩件事落地條件編譯符號(hào)和運(yùn)行時(shí)平臺(tái)判斷。條件編譯解決“某些包只有特定平臺(tái)有”的問題運(yùn)行時(shí)判斷解決“同一個(gè)代碼入口按平臺(tái)走不同實(shí)現(xiàn)”的問題。下面的代碼是 fog-client 里很典型的平臺(tái)分流寫法解決“讀 CPU 型號(hào)”這一個(gè)功能在 Windows 和 Linux 上各走一套實(shí)現(xiàn)// HardwareInfo.cs // 場景采集 CPU 型號(hào)Windows 走 WMILinux 走 /proc/cpuinfo using System.Runtime.InteropServices; public static class HardwareInfo { public static string GetCpuModel() { if (OperatingSystem.IsWindows()) { // Windows 平臺(tái)用 ManagementObjectSearcher 查 Win32_Processor // 注意 System.Management 是 Windows-only 的 API需要 NuGet 包 using var searcher new System.Management.ManagementObjectSearcher( SELECT Name FROM Win32_Processor); foreach (var obj in searcher.Get()) { return obj[Name]?.ToString() ?? Unknown CPU; } } else if (OperatingSystem.IsLinux()) { // Linux 平臺(tái)解析 /proc/cpuinfo取第一行 model name foreach (var line in File.ReadAllLines(/proc/cpuinfo)) { if (line.StartsWith(model name)) { return line.Split(:, 2)[1].Trim(); } } } return Unknown CPU; } }邏輯說明Windows 分支用 ManagementObjectSearcher 執(zhí)行 WQL 查詢返回第一個(gè) CPU 的 NameLinux 分支逐行讀 /proc/cpuinfo命中 model name 后按冒號(hào)切兩段再 Trim兩邊結(jié)果語義一致。冒號(hào)拆分用 Split(:, 2) 只拆第一個(gè)冒號(hào)防止 CPU 型號(hào)文本里再出現(xiàn)冒號(hào)時(shí)被截?cái)?。參?shù)說明OperatingSystem.IsWindows() 是 .NET 5 提供的方法舊項(xiàng)目可以用 RuntimeInformation.IsOSPlatform(OSPlatform.Windows) 等價(jià)替代。System.Management 本身是 Windows-only 的包在 Linux 上編譯能通過但一調(diào)就翻車所以平臺(tái)判斷必須先于 WMI 調(diào)用。條件編譯的典型用法則是隔離引用差異#if NETFRAMEWORK // .NET Framework 下 System.Management 直接可用 #else // .NET 5 需要先引入 System.Management NuGet 包 #endif實(shí)際工程里我一般建議條件編譯只包住引用層面的差異業(yè)務(wù)邏輯盡量走運(yùn)行時(shí)判斷。這樣 Linux 包在發(fā)布前就能完整編譯出來不會(huì)等到運(yùn)行時(shí)才發(fā)現(xiàn)平臺(tái)專屬調(diào)用。3. 核心模塊實(shí)戰(zhàn)采集器、任務(wù)執(zhí)行器與重試上報(bào)3.1 采集器機(jī)器標(biāo)識(shí)與內(nèi)存信息的兩套來源采集器是整個(gè)客戶端的入口第一優(yōu)先要采集的是 MachineId。Windows 上常見做法是讀注冊表 Cryptography 項(xiàng)下的 MachineGuidLinux 上則是 systemd 維護(hù)的 /etc/machine-id。兩者都是安裝系統(tǒng)時(shí)生成的持久化 ID適合做設(shè)備主鍵。關(guān)鍵是要做好回退鏈因?yàn)榫喯到y(tǒng)和容器里文件不一定存在。// SysInfoCollector.cs —— 機(jī)器標(biāo)識(shí)采集含回退鏈 public static string GetMachineId(string configuredSource auto) { if (configuredSource guid) return Guid.NewGuid().ToString(N); if (OperatingSystem.IsWindows()) { // Windows: 注冊表 MachineGuid一般不會(huì)變化 using var key Microsoft.Win32.Registry.LocalMachine.OpenSubKey( SOFTWARE\Microsoft\Cryptography); var value key?.GetValue(MachineGuid)?.ToString(); if (!string.IsNullOrEmpty(value)) return value; } else if (OperatingSystem.IsLinux()) { // Linux: 優(yōu)先 /etc/machine-id容器里往往不存在 var candidates new[] { /etc/machine-id, /var/lib/dbus/machine-id }; foreach (var path in candidates) { if (File.Exists(path)) return File.ReadAllText(path).Trim(); } } // 兜底用隨機(jī) GUID至少客戶端不會(huì)因?yàn)槿?ID 失敗而啟動(dòng)崩潰 return Guid.NewGuid().ToString(N); }邏輯說明configuredSource 參數(shù)允許配置中心強(qiáng)制指定 ID 來源auto 模式按平臺(tái)走默認(rèn)鏈路。Linux 分支給了兩個(gè)候選路徑因?yàn)槿萜麋R像或精簡系統(tǒng)里 /etc/machine-id 可能不存在但 /var/lib/dbus/machine-id 還在。最后兜底用隨機(jī) GUID保住采集流程不中斷。參數(shù)說明MachineIdSource 配置項(xiàng)推薦值有 auto、registry、file、guid。auto 最省事guid 模式適合不想暴露機(jī)器真實(shí)標(biāo)識(shí)的離線場景。注意回退到隨機(jī) GUID 后重啟會(huì)生成新 ID資產(chǎn)系統(tǒng)里這會(huì)造成設(shè)備重復(fù)。正確做法是把回退原因和最終 ID 一起上報(bào)由服務(wù)端判斷是否合并。內(nèi)存采集同樣分兩套來源注意 /proc/meminfo 單位是 kB需要轉(zhuǎn)成 MB// 內(nèi)存總量Windows 走 WMILinux 走 /proc/meminfo public static long GetTotalMemoryMb() { if (OperatingSystem.IsWindows()) { using var searcher new System.Management.ManagementObjectSearcher( SELECT TotalPhysicalMemory FROM Win32_ComputerSystem); foreach (var obj in searcher.Get()) { var value obj[TotalPhysicalMemory]?.ToString(); if (long.TryParse(value, out var bytes)) return bytes / 1024 / 1024; } } else if (OperatingSystem.IsLinux()) { foreach (var line in File.ReadAllLines(/proc/meminfo)) { if (line.StartsWith(MemTotal:)) { var parts line.Split(:, 2)[1].Trim() .Split( , StringSplitOptions.RemoveEmptyEntries); if (long.TryParse(parts[0], out var kb)) return kb / 1024; // meminfo 單位是 kB轉(zhuǎn)成 MB } } } return 0; }為什么 Windows 總內(nèi)存走 WMI 而不是 PerformanceCounterPerformanceCounter 按分類計(jì)數(shù)據(jù)部分精簡服務(wù)器沒有對(duì)應(yīng)計(jì)數(shù)器類別WMI 的 Win32_ComputerSystem.TotalPhysicalMemory 對(duì) Windows Server Core 同樣可用兼容面更廣。Split 用 RemoveEmptyEntries 是為了處理多空格間隔避免解析出空字符串。3.2 任務(wù)執(zhí)行器隊(duì)列、分發(fā)與超時(shí)控制服務(wù)端下發(fā)的任務(wù)到達(dá)客戶端后先進(jìn)入本地 ConcurrentQueue再由 Dispatcher 一條條消費(fèi)。這樣即使服務(wù)端短暫不可用已拉到的任務(wù)也不會(huì)丟同時(shí)限制并發(fā)度避免任務(wù)風(fēng)暴打爆客戶端。// TaskDispatcher.cs —— 任務(wù)隊(duì)列與并發(fā)安全的消費(fèi) public class TaskDispatcher { private readonly ConcurrentQueueRemoteTask _queue new(); public void Enqueue(RemoteTask task) _queue.Enqueue(task); public async Task RunLoopAsync(CancellationToken ct) { while (!ct.IsCancellationRequested) { if (_queue.TryDequeue(out var task)) { var result await ExecuteAsync(task, ct); // 結(jié)果回傳由 Reporter 完成Dispatcher 不關(guān)心 HTTP 細(xì)節(jié) await OnTaskCompleted(result, ct); } else { await Task.Delay(50, ct); } } } private async TaskTaskResult ExecuteAsync(RemoteTask task, CancellationToken ct) { var timeout TimeSpan.FromSeconds( task.TimeoutSeconds 0 ? task.TimeoutSeconds : 60); using var cts CancellationTokenSource.CreateLinkedTokenSource(ct); cts.CancelAfter(timeout); try { return task.Type switch { shell await RunShellAsync(task.Payload, cts.Token), file_sync await FileSyncAsync(task.Payload, cts.Token), _ new TaskResult { Success false, Message $未知任務(wù)類型: {task.Type} } }; } catch (OperationCanceledException) { return new TaskResult { Success false, Message $任務(wù)執(zhí)行超時(shí){timeout.TotalSeconds}s }; } catch (Exception ex) { // 任何異常都要落回 TaskResult不能讓 Dispatcher 崩潰 return new TaskResult { Success false, Message ex.Message }; } } }邏輯說明Enqueue 負(fù)責(zé)收任務(wù)RunLoopAsync 在沒有取消時(shí)不斷出隊(duì)空隊(duì)列時(shí)等 50ms 再輪詢。每個(gè)任務(wù)用獨(dú)立的 CancellationTokenSource 控制超時(shí)switch 表達(dá)式按 type 分發(fā)未知類型返回失敗結(jié)果而不是拋異常保證執(zhí)行器穩(wěn)定。參數(shù)說明TimeoutSeconds 是任務(wù) payload 里的字段默認(rèn) 60 秒。CreateLinkedTokenSource 同時(shí)關(guān)聯(lián)客戶端停機(jī)信號(hào)和任務(wù)超時(shí)避免停機(jī)時(shí)任務(wù)還在后臺(tái)跑。如果任務(wù)本身需要長時(shí)間執(zhí)行超時(shí)值要由服務(wù)端配置而不是寫死。跑 shell 命令時(shí)注意用 WaitForExitAsync 而不是阻塞式 WaitForExit否則 CancellationToken 沒法真正中斷命令// RunShellAsync 簡化實(shí)現(xiàn) private static async TaskTaskResult RunShellAsync(RemoteTaskPayload payload, CancellationToken ct) { var psi new ProcessStartInfo { FileName OperatingSystem.IsWindows() ? cmd.exe : /bin/bash, RedirectStandardOutput true, RedirectStandardError true, UseShellExecute false, CreateNoWindow true }; if (OperatingSystem.IsWindows()) psi.Arguments $/c \{payload.Command}\; else { psi.ArgumentList.Add(-c); psi.ArgumentList.Add(payload.Command); } using var process Process.Start(psi); var outputTask process.StandardOutput.ReadToEndAsync(); var errorTask process.StandardError.ReadToEndAsync(); await process.WaitForExitAsync(ct); await Task.WhenAll(outputTask, errorTask); return new TaskResult { Success process.ExitCode 0, Message outputTask.Result }; }關(guān)鍵點(diǎn)UseShellExecutefalse 是必須的它讓 stdout 和 stderr 可以被重定向CreateNoWindowtrue 保證客戶端在后臺(tái)運(yùn)行時(shí)不彈黑框。Linux 分支用 ArgumentList 而不是拼字符串減少命令注入和轉(zhuǎn)義問題。3.3 上報(bào)通道JSON over HTTP、指數(shù)退避與失敗落盤上報(bào)通道是客戶端和服務(wù)端之間的唯一數(shù)據(jù)通路最怕網(wǎng)絡(luò)抖動(dòng)導(dǎo)致丟數(shù)據(jù)。fog-client 的上報(bào)用 POST JSON 加指數(shù)退避重試第一次失敗等 1 秒第二次等 2 秒第三次等 4 秒最多三次就進(jìn)入失敗落盤而不是無限重試。這樣既不過度消耗服務(wù)端資源也能在瞬斷場景恢復(fù)。// Reporter.cs —— 帶指數(shù)退避的設(shè)備上報(bào) public class Reporter { private readonly HttpClient _httpClient; private readonly string _baseUrl; private readonly string _cacheDirectory; public async Taskbool ReportAsync(DeviceInfo payload, CancellationToken ct) { var maxAttempt 3; for (var attempt 1; attempt maxAttempt; attempt) { try { using var resp await _httpClient.PostAsJsonAsync( ${_baseUrl}/api/devices/report, payload, ct); if (resp.IsSuccessStatusCode) { return true; } // 非 2xx 也退避防止服務(wù)端被瞬時(shí)高負(fù)載壓垮 await Task.Delay(TimeSpan.FromSeconds(attempt * 2), ct); } catch (HttpRequestException) { if (attempt maxAttempt) break; // 網(wǎng)絡(luò)瞬斷按 1、2、4 秒退避 await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt)), ct); } } // 三次都失敗就落盤下個(gè)周期再補(bǔ)報(bào) var cacheFile Path.Combine(_cacheDirectory, ${payload.MachineId}.json); await File.WriteAllTextAsync(cacheFile, JsonSerializer.Serialize(payload), ct); return false; } }邏輯說明PostAsJsonAsync 會(huì)把 payload 按 System.Text.Json 配置序列化后 POST返回 2xx 直接結(jié)束網(wǎng)絡(luò)異常類型DNS 解析失敗、連接超時(shí)、連接被重置走指數(shù)退避。最后失敗會(huì)把 JSON 寫進(jìn)本地磁盤丟數(shù)據(jù)窗口從幾秒降到幾乎為零。參數(shù)說明兩組退避時(shí)間分別對(duì)應(yīng)服務(wù)端“能響應(yīng)但不成功”和“根本連不上”兩種場景。重試次數(shù)和間隔建議放配置中心比如 ReportRetryCount 和 ReportRetryBaseSeconds。如果內(nèi)網(wǎng)斷連超過 10 分鐘只重試三次不夠必須靠失敗落盤兜底。3.4 本地調(diào)度心跳、全量上報(bào)與任務(wù)輪詢的三個(gè)節(jié)奏fog-client 有三條獨(dú)立的節(jié)拍心跳每 5 分鐘一次數(shù)據(jù)量極小只上報(bào)機(jī)器在線的狀態(tài)和客戶端版本全量上報(bào)每 30 分鐘一次把采集到的完整信息發(fā)出去任務(wù)輪詢每 15 秒一次因?yàn)槿蝿?wù)執(zhí)行對(duì)實(shí)時(shí)性有要求這個(gè)間隔要短。三個(gè)周期用同一個(gè) CancellationToken停機(jī)時(shí)全部循環(huán)一起退出。用 PeriodicTimer 實(shí)現(xiàn)比 Task.Delay 好因?yàn)?PeriodicTimer 會(huì)在下一個(gè) tick 重新計(jì)時(shí)不會(huì)累計(jì)漂移// Scheduler.cs —— 三個(gè)獨(dú)立周期 public class Scheduler : IAsyncDisposable { private readonly PeriodicTimer _heartbeatTimer new(TimeSpan.FromMinutes(5)); private readonly PeriodicTimer _reportTimer new(TimeSpan.FromMinutes(30)); private readonly PeriodicTimer _taskTimer new(TimeSpan.FromSeconds(15)); public async Task RunAsync(CancellationToken ct) { var tasks new[] { RunHeartbeatLoopAsync(ct), RunReportLoopAsync(ct), RunTaskPollLoopAsync(ct) }; await Task.WhenAll(tasks); } private async Task RunHeartbeatLoopAsync(CancellationToken ct) { while (await _heartbeatTimer.WaitForNextTickAsync(ct)) { await _reporter.ReportHeartbeatAsync(ct); } } }要點(diǎn)PeriodicTimer 能感知執(zhí)行時(shí)長。某一次上報(bào)卡了 40 秒下一個(gè) tick 不會(huì)立刻觸發(fā)而是等滿 5 分鐘再說天然錯(cuò)峰。任務(wù)輪詢這 15 秒間隔要結(jié)合服務(wù)端并發(fā)量調(diào)輪詢百臺(tái)機(jī)器可以輪詢上萬臺(tái)就要考慮長連接或消息推送不然服務(wù)端容易被每秒幾百個(gè)空請求打滿。4. 部署與配置從發(fā)布命令到服務(wù)托管4.1 發(fā)布命令RID、自包含與單文件把 fog-client 推到目標(biāo)機(jī)最常見方式是 dotnet publish。兩個(gè)典型命令一組分別產(chǎn)出 Windows 和 Linux 的部署包# Windows 10/11、Windows Server 2019 的 x64 機(jī)器 dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFiletrue -o ./dist/win-x64 # 常見 Linux 發(fā)行版CentOS 7、Ubuntu 18.04的 x64 機(jī)器 dotnet publish -c Release -r linux-x64 --self-contained true -p:PublishSingleFiletrue -o ./dist/linux-x64參數(shù)說明-r 指定 RuntimeIdentifier管理客戶端建議直接用 win-x64 和 linux-x64不用 x86 兼容畸形架構(gòu)。如果目標(biāo)機(jī)是 ARM 盒子把 -r 換成 linux-arm64。--self-contained true 把 .NET 運(yùn)行時(shí)打進(jìn)發(fā)布目錄目標(biāo)機(jī)零依賴代價(jià)是體積多 30-50 MB。PublishSingleFiletrue 把所有托管 DLL 并進(jìn)單個(gè) exe方便腳本分發(fā)。我一般還會(huì)顯式關(guān)掉裁剪避免 WMI 和反射類操作被剪出問題dotnet publish -c Release -r linux-x64 --self-contained true \ -p:PublishSingleFiletrue -p:PublishTrimmedfalsePublishTrimmedfalse 是給使用 WMI 或反射代碼的客戶端留的一條后路。裁剪模式可能剪掉 Win32_Processor 查詢所需的內(nèi)部類型發(fā)布包多幾 MB換穩(wěn)定性值得。如果確實(shí)要裁剪先跑一遍第 6 章的 mock 三連測再發(fā)。4.2 配置文件服務(wù)端地址與采集參數(shù)fog-client 的配置集中在單個(gè) appsettings.json結(jié)構(gòu)設(shè)計(jì)得很直接{ Server: { BaseUrl: http://ops-cfg-server:8080, ReportIntervalMinutes: 30, HeartbeatIntervalMinutes: 5, TaskPollingIntervalSeconds: 15, ReportRetryCount: 3, UseSystemProxy: false }, Client: { MachineIdSource: auto, CacheDirectory: cache, LogLevel: Information, TaskTimeoutSeconds: 60 } }配置項(xiàng)默認(rèn)/推薦說明Server.BaseUrl必填服務(wù)端根地址不帶尾部斜杠ReportIntervalMinutes30全量上報(bào)周期HeartbeatIntervalMinutes5心跳周期TaskPollingIntervalSeconds15任務(wù)輪詢周期值越小任務(wù)越及時(shí)服務(wù)端壓力越大ReportRetryCount3上報(bào)失敗重試上限UseSystemProxyfalse內(nèi)網(wǎng)環(huán)境默認(rèn)關(guān)閉系統(tǒng)代理避免請求繞一圈注意 BaseUrl 末尾不要加斜杠否則拼接 /api/devices/report 時(shí)會(huì)出現(xiàn) //api不少網(wǎng)關(guān)會(huì)直接 404。代碼里用 ConfigurationBuilder 加載并綁定強(qiáng)類型// AppConfig.cs —— 配置加載與強(qiáng)類型綁定 var configuration new ConfigurationBuilder() .SetBasePath(AppContext.BaseDirectory) .AddJsonFile(appsettings.json, optional: false, reloadOnChange: true) .Build(); var serverConfig configuration.GetSection(Server).GetServerOptions();reloadOnChange 設(shè)為 true 后服務(wù)端參數(shù)調(diào)整客戶端不需要重啟進(jìn)程對(duì)資產(chǎn)管理場景很關(guān)鍵畢竟幾十臺(tái)客戶端不可能一臺(tái)臺(tái)手動(dòng)重啟。改完配置源新值會(huì)在下個(gè)輪詢周期生效。4.3 服務(wù)托管Windows 用 scLinux 用 systemd客戶端必須開機(jī)自啟不能靠用戶手動(dòng)雙擊。Windows 上最直接的服務(wù)注冊命令sc create fog-client binPath C:\Program Files\FogClient\fog-client.exe start auto這條命令有個(gè)經(jīng)典坑binPath 后面的空格是必須的sc 的語法要求在等號(hào)后有一個(gè)空格否則報(bào)語法錯(cuò)誤。binPath 必須指向完整可執(zhí)行文件路徑不能寫相對(duì)路徑路徑里有空格的整段用雙引號(hào)包住。啟動(dòng)和查詢sc start fog-client sc query fog-clientLinux 側(cè)就是 systemd service 文件# /etc/systemd/system/fog-client.service [Unit] DescriptionFog Client Afternetwork-online.target Wantsnetwork-online.target [Service] WorkingDirectory/opt/fog-client ExecStart/opt/fog-client/fog-client Restartalways RestartSec10 EnvironmentDOTNET_SYSTEM_GLOBALIZATION_INVARIANT1 [Install] WantedBymulti-user.targetDOTNET_SYSTEM_GLOBALIZATION_INVARIANT1 用于精簡系統(tǒng)沒有 ICU 庫的場景否則客戶端啟動(dòng)時(shí)會(huì)因?yàn)檎也坏轿幕畔伄惓！Ｈ绻蛻舳巳罩拘枰暾镜鼗敵鲞@個(gè)變量不要加讓 .NET 走默認(rèn)的全球化模式。隨后執(zhí)行sudo systemctl daemon-reload sudo systemctl enable --now fog-client systemctl status fog-clientAfternetwork-online.target 和 Wantsnetwork-online.target 的組合要保留防止客戶端在網(wǎng)卡還沒就緒時(shí)啟動(dòng)把 BaseUrl 的 DNS 解析失敗當(dāng)成不可恢復(fù)錯(cuò)誤。4.4 網(wǎng)絡(luò)前置條件先確認(rèn)四項(xiàng)再分發(fā)服務(wù)端地址配置完成后在目標(biāo)機(jī)上先做一次連通性驗(yàn)證不要部署幾十臺(tái)再回頭排查。curl -v http://ops-cfg-server:8080/api/devices/ping四項(xiàng)檢查按順序做一是目標(biāo)機(jī)能不能解析服務(wù)端域名用 getent hosts 或 nslookup二是防火墻是否放行出站ping 通不代表 TCP 層通用 telnet IP 8080 驗(yàn)證三是是否需要系統(tǒng)代理如果需要就打開 UseSystemProxy四是服務(wù)端是否允許該網(wǎng)段來源收到 403 或 401 就讓服務(wù)端查白名單。這四項(xiàng)過了再批量推包比事后救火省心得多。5. 避坑指南五個(gè)讓客戶端半夜掛掉的真實(shí)場景5.1 WMI 首次查詢慢采集器被誤判為卡死現(xiàn)象客戶端剛部署完日志顯示第一次采集 CPU 信息耗時(shí) 8-12 秒業(yè)務(wù)側(cè)誤判為客戶端卡死超時(shí)后重試導(dǎo)致采集隊(duì)列堆疊。原因WMI 服務(wù)Winmgmt是懶啟動(dòng)的首次 WQL 查詢會(huì)觸發(fā) WMI 倉庫初始化在 Windows Server Core 上更明顯耗時(shí)能到十幾秒。解決采集邏輯里給 ManagementObjectSearcher 設(shè)置檢索超時(shí)超過 15 秒就放棄這次采集并返回空值。更重要的是超時(shí)后不要立即重試讓下個(gè)周期自然補(bǔ)采。fog-client 的采集器按模塊各自獨(dú)立 try-catch單個(gè)采集點(diǎn)失敗不影響其他項(xiàng)。5.2 /etc/machine-id 不存在客戶端開機(jī)即崩現(xiàn)象容器化部署或精簡 Linux 系統(tǒng)上客戶端啟動(dòng)第一條日志就是 FileNotFoundException指向 /etc/machine-id。原因容器鏡像默認(rèn)不帶 machine-id部分精簡系統(tǒng)把 dbus 相關(guān)文件也裁掉了而代碼里直接 File.ReadAllText 讀固定路徑。解決采集 MachineId 時(shí)按候選路徑探測/etc/machine-id、/var/lib/dbus/machine-id 依次嘗試都沒有就回退到 hostname 加啟動(dòng)時(shí)間生成的穩(wěn)定鍵同時(shí)打 warning 日志?；赝藭r(shí)不要直接用隨機(jī) GUID否則每次重啟設(shè)備在服務(wù)端都會(huì)生成一個(gè)新資產(chǎn)。5.3 sc create 等號(hào)后沒有空格服務(wù)建不出來現(xiàn)象sc create 命令在 Windows 上報(bào)無效參數(shù)或者服務(wù)創(chuàng)建成功但 start auto 沒生效服務(wù)一啟動(dòng)就退出。原因sc 命令的語法是 name value等號(hào)后必須有一個(gè)空格。腳本里寫成 binPath 不帶空格時(shí)系統(tǒng)解析會(huì)把路徑參數(shù)吞掉服務(wù)永遠(yuǎn)起不來。解決腳本里固定寫成 binPath C:... start auto等號(hào)后保留空格。這是 Windows 服務(wù)命令里最容易踩的坑沒有之一。建議寫成一個(gè) .bat 模板讓所有部署人員直接復(fù)制不要靠手敲。5.4 System.Management 在 Linux 上能編譯運(yùn)行時(shí)才翻車現(xiàn)象把同一份源碼在 Linux 上 publish 成功但跑到采集步驟拋 System.PlatformNotSupportedException調(diào)用棧指向 ManagementObjectSearcher。原因System.Management 是 Windows-only APINuGet 包在非 Windows 平臺(tái)沒有實(shí)際實(shí)現(xiàn)。編譯期不報(bào)錯(cuò)是因?yàn)?TFM 聲明支持運(yùn)行時(shí)才暴露真實(shí)平臺(tái)限制。解決所有 WMI 調(diào)用必須用 OperatingSystem.IsWindows() 包起來Linux 分支永遠(yuǎn)走 /proc 和 /sys。發(fā)布流程里加一道雙平臺(tái) smoke test先 Linux 編譯跑一次采集再 Windows 編譯跑一次任何一邊崩都直接攔截。5.5 HttpClient 按請求創(chuàng)建內(nèi)網(wǎng) socket 被拖垮現(xiàn)象客戶端跑了一周任務(wù)執(zhí)行越來越慢netstat 看到大量 TIME_WAIT 連接日志出現(xiàn) SocketException: Too many open files。原因Reporter 里每次上報(bào)都 new HttpClient()HttpClient 底層的 socket 不會(huì)隨請求結(jié)束立刻釋放加上內(nèi)網(wǎng)代理連接積壓把端口耗盡。解決HttpClient 做成單例或者用 IHttpClientFactory 管理生命周期。注意單例后 DNS 變更不會(huì)自動(dòng)生效配合 PooledConnectionLifetime 設(shè)置一個(gè)連接復(fù)用時(shí)長比如 5 分鐘既能復(fù)用端口又能看到 DNS 更新。這屬于上線前就該定下來的底層設(shè)計(jì)真等到 socket 耗盡再改客戶端得全部重發(fā)一遍。6. 進(jìn)階驗(yàn)證用本地 Mock 服務(wù)端做三連測6.1 Mock 服務(wù)端起在本地把三測跑通部署任何管理客戶端我最怕的是代碼邏輯正確但服務(wù)端對(duì)不上。所以 fog-client 工程下來后先起一個(gè)本地 Mock 服務(wù)端把上報(bào)、心跳、任務(wù)回執(zhí)三件事驗(yàn)完再考慮真實(shí)環(huán)境。用 ASP.NET Core Minimal API 五十行內(nèi)就能完成// MockServer/Program.cs —— 臨時(shí)驗(yàn)證用不用于生產(chǎn) using System.Collections.Concurrent; var builder WebApplication.CreateBuilder(args); var app builder.Build(); var received new ConcurrentBagDeviceInfo(); app.MapPost(/api/devices/report, (DeviceInfo device) { received.Add(device); return Results.Ok(new { code 0 }); }); app.MapPost(/api/devices/heartbeat, (HeartbeatInfo hb) { return Results.Ok(new { code 0, serverTime DateTime.UtcNow }); }); app.MapPost(/api/tasks/poll, () { // 固定下發(fā)一條 shell 任務(wù)用于驗(yàn)證任務(wù)執(zhí)行鏈路 return Results.Ok(new { task new { id Guid.NewGuid().ToString(), type shell, payload new { command echo ok } } }); }); app.MapGet(/api/devices/received, () received.ToArray()); app.Run(); public record DeviceInfo(string MachineId, string CpuModel, long MemoryMb); public record HeartbeatInfo(string MachineId, string Version);運(yùn)行起來后把目標(biāo)機(jī)的 BaseUrl 指向本地地址dotnet run --project MockServer curl http://localhost:5225/api/devices/heartbeat然后啟動(dòng) fog-client。第一測是上報(bào)等服務(wù)端日志打到 report 請求驗(yàn)證 DeviceInfo 的 JSON 字段名大小寫和序列化配置一致第二測是心跳測試時(shí)把 HeartbeatIntervalMinutes 臨時(shí)改成 1 分鐘不用真等五分鐘第三測是任務(wù)回執(zhí)Mock 的 poll 接口返回一條 echo 命令客戶端執(zhí)行后應(yīng)回傳 TaskResult再補(bǔ)一個(gè) MapPost /api/tasks/result 就能驗(yàn)證結(jié)果。6.2 兩個(gè)高頻返工點(diǎn)字段命名與自簽證書校驗(yàn)三連測最容易暴露的是字段命名問題。客戶端序列化配置用了 camelCase 策略時(shí)上報(bào)字段是 machineId、cpuModel而服務(wù)端如果按 PascalCase 綁字典就匹配不上。Mock 服務(wù)端用 record 類接收時(shí) ASP.NET Core 默認(rèn)大小寫不敏感很容易掩蓋這個(gè)坑。正確的驗(yàn)證方式是把 Mock 收到的原始 JSON 原樣打印出來看一次而不是依賴模型綁定后的值。另一個(gè)高頻返工點(diǎn)是自簽證書。內(nèi)網(wǎng)服務(wù)端一般用 HTTPS 加自簽證書客戶端 HttpClient 默認(rèn)校驗(yàn)嚴(yán)格直接連會(huì)拋?zhàn)C書錯(cuò)誤。穩(wěn)妥做法是在 HttpClientHandler 的 ServerCertificateCustomValidationCallback 里只放行配置過的證書指紋不要全局忽略校驗(yàn)。測試階段可以臨時(shí)放開生產(chǎn)環(huán)境必須回到白名單校驗(yàn)否則等于把半條命交給中間人。從那以后我每次改采集邏輯或序列化配置都強(qiáng)制走一遍這套流程本地 Mock 起服務(wù)、改 BaseUrl、跑三連測、確認(rèn)原始 JSON全綠才執(zhí)行發(fā)布命令。這個(gè)習(xí)慣幫我擋住了至少三次字段對(duì)不上和 WMI 超時(shí)引發(fā)的線上問題。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取