NtpSecureSync

English Version: README.en.md

一个安全、高性能的NTP客户端库，支持NTPv3和NTPv4协议。

特性

• 支持NTPv3和NTPv4协议
• 支持多服务器故障转移
• 支持网络延迟补偿
• 支持全球时区
• 提供详细的时间同步信息
• 支持时间误差估算
• 支持NTS（计划中）

安装

dotnet add package NtpSecureSync

基本用法

// 使用默认配置（系统本地时区） var client = new NtpClient(); var networkTime = await client.GetNetworkTimeAsync(); // 使用特定服务器 var timeFromServer = await client.GetNetworkTimeAsync("pool.ntp.org"); // 使用多个服务器（故障转移） var servers = new[] { "time.windows.com", "time.nist.gov", "pool.ntp.org" }; var timeWithFailover = await client.GetNetworkTimeAsync(servers);

高级用法

时区支持

// 1. 使用特定时区 var options = new NtpClientOptions { Version = NtpVersion.Version4, EnableNetworkDelayCompensation = true, TargetTimeZoneId = "China Standard Time" // 中国标准时间 }; var client = new NtpClient(options); var timeInfo = await client.GetDetailedTimeAsync("pool.ntp.org"); Console.WriteLine($"北京时间: {timeInfo.ServerTime:yyyy-MM-dd HH:mm:ss.fff}"); Console.WriteLine($"时区: {timeInfo.TimeZone.DisplayName}"); // 2. 获取可用时区列表 foreach (var tz in TimeZoneInfo.GetSystemTimeZones()) { Console.WriteLine($"ID: {tz.Id}, 显示名称: {tz.DisplayName}"); } // 3. 常用时区ID // - "China Standard Time" (中国标准时间) // - "Eastern Standard Time" (美国东部时间) // - "UTC" (协调世界时) // - "Tokyo Standard Time" (东京标准时间) // - "Pacific Standard Time" (太平洋标准时间)

自定义配置

var options = new NtpClientOptions { Version = NtpVersion.Version4, EnableNetworkDelayCompensation = true, Timeout = 5000, RetryCount = 3, EnableNts = true, AutoDowngrade = true, DefaultServers = new[] { "time.windows.com", "time.nist.gov" } }; var client = new NtpClient(options);

获取详细时间信息

var timeInfo = await client.GetDetailedTimeAsync("pool.ntp.org"); Console.WriteLine($"服务器时间: {timeInfo.ServerTime}"); Console.WriteLine($"本地时间: {timeInfo.LocalTime}"); Console.WriteLine($"时间偏移: {timeInfo.TimeOffset.TotalMilliseconds:F2}ms"); Console.WriteLine($"往返延迟: {timeInfo.RoundTripDelay.TotalMilliseconds:F2}ms"); Console.WriteLine($"估计误差: {timeInfo.EstimatedError:F2}ms"); Console.WriteLine($"服务器层次: {timeInfo.Stratum}"); Console.WriteLine($"时区: {timeInfo.TimeZone.DisplayName}");

时间缓存最佳实践

基本缓存实现

public class TimeService { private readonly INtpClient _ntpClient; private NtpTimeInfo _lastTimeInfo; private readonly object _lock = new object(); private readonly double _maxErrorThreshold; // 最大可接受误差（毫秒） public TimeService(INtpClient ntpClient, double maxErrorThreshold = 10000) { _ntpClient = ntpClient; _maxErrorThreshold = maxErrorThreshold; } public async Task<DateTime> GetCurrentTimeAsync() { try { // 尝试从NTP服务器获取时间 var timeInfo = await _ntpClient.GetDetailedTimeAsync("pool.ntp.org"); lock (_lock) { _lastTimeInfo = timeInfo; } return timeInfo.ServerTime; } catch (Exception) { // 如果网络不可用，使用缓存的时间信息 lock (_lock) { if (_lastTimeInfo != null) { var elapsed = DateTime.UtcNow - _lastTimeInfo.LastSyncTime; var estimatedError = _lastTimeInfo.EstimatedError + elapsed.TotalMilliseconds; if (estimatedError > _maxErrorThreshold) { throw new NtpException("缓存时间误差超过阈值"); } // 使用缓存的时区信息 return TimeZoneInfo.ConvertTime( DateTime.UtcNow.Add(_lastTimeInfo.TimeOffset), TimeZoneInfo.Utc, _lastTimeInfo.TimeZone ); } } throw; } } }

高级缓存实现

public class AdvancedTimeService { private readonly INtpClient _ntpClient; private readonly string[] _servers; private NtpTimeInfo _lastTimeInfo; private readonly object _lock = new object(); private readonly Timer _syncTimer; private readonly ILogger _logger; private readonly TimeSpan _syncInterval; private readonly double _maxErrorThreshold; public AdvancedTimeService( INtpClient ntpClient, ILogger logger, TimeSpan? syncInterval = null, double maxErrorThreshold = 10000, params string[] servers) { _ntpClient = ntpClient; _logger = logger; _servers = servers.Length > 0 ? servers : new[] { "pool.ntp.org" }; _syncInterval = syncInterval ?? TimeSpan.FromHours(1); _maxErrorThreshold = maxErrorThreshold; // 创建定时同步任务 _syncTimer = new Timer(SyncTime, null, TimeSpan.Zero, _syncInterval); } private async void SyncTime(object? state) { try { foreach (var server in _servers) { try { var timeInfo = await _ntpClient.GetDetailedTimeAsync(server); lock (_lock) { _lastTimeInfo = timeInfo; } _logger.LogInformation( "时间同步成功。服务器：{Server}, 偏移：{Offset}ms, 误差：{Error}ms", server, timeInfo.TimeOffset.TotalMilliseconds, timeInfo.EstimatedError); return; } catch (Exception ex) { _logger.LogWarning(ex, "服务器{Server}同步失败", server); } } } catch (Exception ex) { _logger.LogError(ex, "时间同步失败"); } } public DateTime GetCurrentTime() { lock (_lock) { if (_lastTimeInfo == null) { throw new InvalidOperationException("尚未完成首次时间同步"); } var elapsed = DateTime.UtcNow - _lastTimeInfo.LastSyncTime; var estimatedError = _lastTimeInfo.EstimatedError + elapsed.TotalMilliseconds; if (estimatedError > _maxErrorThreshold) { _logger.LogWarning( "时间误差({Error}ms)超过阈值({Threshold}ms)", estimatedError, _maxErrorThreshold); } return DateTime.Now.Add(_lastTimeInfo.TimeOffset); } } public void Dispose() { _syncTimer?.Dispose(); } }

缓存策略建议

1. 同步频率

   • 高精度要求：每5-15分钟同步一次
   • 一般精度要求：每1-4小时同步一次
   • 低精度要求：每12-24小时同步一次

2. 误差控制

   • 关键系统：最大误差限制在100ms以内
   • 一般应用：最大误差限制在1-10秒
   • 非关键系统：可接受更大误差

3. 故障处理

   • 实现优雅降级
   • 使用多个NTP服务器
   • 记录同步失败的原因
   • 监控时间偏移趋势

4. 性能优化

   • 使用内存缓存
   • 实现异步预加载
   • 避免频繁同步
   • 使用后台任务同步

5. 安全考虑

   • 验证时间偏移的合理性
   • 防止时间回跳
   • 记录异常时间变化
   • 考虑使用NTS（如果可用）

许可证

MIT