网关审核修复: ILogger统一注入+调试日志+日志等级控制+RateLimiter PeriodicTimer+Owl分页修复+MC4 MinValue修复+告警确认错误检查+命名规范化

2026-06-04 04:26:41 +08:00
parent 29e12a235a
commit 8a6776eac9
13 changed files with 613 additions and 38 deletions
@@ -0,0 +1,535 @@
+# 网关项目深度代码审核报告
+
+> 日期: 2026-06-04 | 项目: gateway/ | 扫描: 38 源文件, ~2800 行 | 问题: 30 项
+
+---
+
+## 1. Core/Infrastructure/AdapterRegistry.cs — 2 项
+
+### AR1 [🟡] `GetOnlineAdapters()` 方法名误导
+
+**位置**: 第 49-50 行
+```csharp
+public IReadOnlyList<IGatewayAdapter> GetOnlineAdapters()
+    => _adapters.AsReadOnly();
+```
+返回所有已注册适配器，**不做任何在线/离线判断**。调用者会误以为返回的是在线适配器。
+
+**修复**:
+```csharp
+public IReadOnlyList<IGatewayAdapter> GetAllAdapters()
+    => _adapters.AsReadOnly();
+```
+同时 grep 全项目无任何代码调用此方法，可直接删除（或保留为兼容性方法并标注 `[Obsolete]`）。
+
+### AR2 [🟡] `FindByCode<T>` O(n) 查找无缓存
+
+每次 B 路由请求都执行 `_adapters.FirstOrDefault(...)`，适配器数量少时影响可忽略（<10 个），但如果未来扩展到 50+ 适配器会有性能问题。
+
+**修复** — 加字典缓存:
+```csharp
+private readonly Dictionary<string, IGatewayAdapter> _byCode = new();
+public void Register(IGatewayAdapter adapter)
+{
+    _adapters.Add(adapter);
+    _byCode[adapter.AdapterCode] = adapter;
+}
+public T? FindByCode<T>(string adapterCode) where T : class, IGatewayAdapter
+    => _byCode.TryGetValue(adapterCode, out var a) ? a as T : null;
+```
+
+---
+
+## 2. Core/Infrastructure/RateLimiter.cs — 1 项
+
+### RL1 [🟠] `Task.Run` 无限制创建后台任务
+
+**位置**: 第 30-32 行
+```csharp
+public async Task WaitAsync(CancellationToken ct = default)
+{
+    await _semaphore.WaitAsync(ct);
+    _ = Task.Run(async () => { await Task.Delay(_intervalMs, ct); try { _semaphore.Release(); } catch { } }, ct);
+}
+```
+每次等待都创建一个新的 `Task.Run`。在 KMS 5 QPS 配置下每秒创建 5 个 Task，5 个适配器 = 25 task/s。虽然 Task 本身轻量，但 `Task.Delay` + `Release` 的火焰纹章在极端高并发下可能导致线程池饥饿。
+
+**修复** — 使用 `PeriodicTimer` 或固定数量的后台任务:
+```csharp
+private readonly SemaphoreSlim _semaphore;
+private readonly int _maxTokens;
+
+public RateLimiter(int tokensPerSecond)
+{
+    _maxTokens = tokensPerSecond;
+    _semaphore = new SemaphoreSlim(_maxTokens, _maxTokens);
+    // 单后台任务持续补充令牌
+    _ = Task.Run(async () =>
+    {
+        var interval = 1000 / _maxTokens;
+        using var timer = new PeriodicTimer(TimeSpan.FromMilliseconds(interval));
+        while (await timer.WaitForNextTickAsync())
+        {
+            try { if (_semaphore.CurrentCount < _maxTokens) _semaphore.Release(); }
+            catch (ObjectDisposedException) { break; }
+        }
+    });
+}
+
+public async Task WaitAsync(CancellationToken ct = default)
+    => await _semaphore.WaitAsync(ct);
+```
+
+---
+
+## 3. Core/Models/AdapterCapabilities.cs — 1 项
+
+### AC1 [🟡] `HasPtz` 与 `AcceptsControl` 字段冗余
+
+**位置**: 第 10-13 行
+```csharp
+public bool HasPtz { get; set; }
+public bool AcceptsControl { get; set; }
+```
+`HasPtz` 是 `HasStreams` 的子能力，`AcceptsControl` 是 `IAcceptsControl` 接口的声明。这两个字段在 `AdapterCapabilities` 中冗余——`IAcceptsControl` 接口本身已经声明了控制能力。
+
+**修复** — 删除 `AcceptsControl` 字段（能力声明应直接检查接口实现）:
+```csharp
+// 删除 AcceptsControl、HasPtz
+// 网关 B 路由中改为: a is IAcceptsControl
+```
+
+**跨文件影响**: `gateway/src/IntegrationGateway.Host/Program.cs` — B10 路由已用 `FindByCode<IAcceptsControl>` 不再需要此字段。OwlAdapter/Mc4Adapter 的 Capabilities 声明中删除对应行。
+
+---
+
+## 4. Core/Models/StandardDevice.cs — 1 项
+
+### SD1 [🟡] `DeviceId` 字段职责混淆
+
+**位置**: 第 9 行
+```csharp
+public int DeviceId { get; set; }
+```
+`DeviceId` 是 VolPro 侧的主键，由 A3 同步后由 VolPro 回填。但网关在 `GetDevicesAsync` 返回时不设置此字段（始终为 0）。文档注释说"同步后由 VolPro 回填"，但调用者可能在未同步时就读取此字段。
+
+**修复** — 改为 `int?` 并初始化为 null:
+```csharp
+public int? DeviceId { get; set; }
+// VolPro 回填后才有值
+```
+
+---
+
+## 5. Core/Abstractions/IHasRecordings.cs — 1 项
+
+### IR1 [🟡] 方法参数过多
+
+**位置**: 第 12-13 行
+```csharp
+Task<PagedResult<StandardRecording>> GetRecordingsAsync(
+    string channelId, DateTime start, DateTime end, int page, int size);
+```
+5 个位置参数，调用时易错序。
+
+**修复** — 使用请求对象:
+```csharp
+public class RecordingQuery
+{
+    public string ChannelId { get; set; } = "";
+    public DateTime Start { get; set; }
+    public DateTime End { get; set; }
+    public int Page { get; set; } = 1;
+    public int Size { get; set; } = 20;
+}
+Task<PagedResult<StandardRecording>> GetRecordingsAsync(RecordingQuery query);
+```
+**跨文件影响**: `OwlAdapter.cs` GetRecordingsAsync 实现 + `Program.cs` B 路由。
+
+---
+
+## 6. Core/Infrastructure/GatewayClientFactory.cs — 2 项
+
+### GF1 [🟡] `JsonDocument?` 返回类型不透明
+
+**位置**: 第 33-42 行
+```csharp
+public async Task<JsonDocument?> RegisterAsync(GatewayRegisterRequest req) { ... }
+public async Task<JsonDocument?> SyncDevicesAsync(...) { ... }
+```
+返回 `JsonDocument?` 使调用者必须知道 VolPro 响应的 JSON 结构。
+
+**修复** — 定义响应 DTO:
+```csharp
+public class RegisterResponse { public int NodeId { get; set; } public List<DeviceSummary> Devices { get; set; } = new(); }
+public Task<RegisterResponse?> RegisterAsync(GatewayRegisterRequest req) { ... }
+```
+
+### GF2 [🟡] `CreateClient()` 每次创建新 HttpClient
+
+```csharp
+private HttpClient CreateClient() => _httpFactory.CreateClient("VolPro");
+```
+`IHttpClientFactory.CreateClient("VolPro")` 从连接池返回，每次调用都会创建新的 `HttpClient` 包装实例。虽然底层 SocketsHttpHandler 复用连接，但 `HttpClient` 上设置的 Timeout/Headers 不会被保留。
+
+**修复** — 直接使用工厂客户端（已配置好 Timeout/Headers）:
+```csharp
+// Program.cs 中注册时已设置 Timeout=30s + Accept: application/json
+// 直接使用 factory 创建的客户端
+private HttpClient GetClient() => _httpFactory.CreateClient("VolPro");
+```
+
+---
+
+## 7. Adapters.Owl/OwlAdapter.cs — 5 项
+
+### OW1 [🟠] `GetDevicesAsync` 忽略 `page`/`size` 参数
+
+**位置**: 第 68 行
+```csharp
+var url = $"/devices/channels?page={page}&size=1000";
+```
+硬编码 `size=1000`，无论调用者传的 `size` 值是多少。前端分页完全失效。
+
+**修复**:
+```csharp
+var url = $"/devices/channels?page={page}&size={size}";
+```
+
+### OW2 [🟡] `GetPlaybackUrlAsync` 手工拼 URL 脆弱
+
+**位置**: 第 149-153 行
+```csharp
+return new StreamUrls
+{
+    Hls = $"{baseUrl}/recordings/channels/{channelId}/index.m3u8?start_ms={startMs}&end_ms={endMs}&token={token}"
+};
+```
+直接拼接 URL，依赖 Owl 内部路径约定。Owl API 版本升级可能改变路径格式。
+
+**修复** — 调 Owl API 获取回放地址（如果有对应接口）或至少将 base URL 路径前缀提取为常量:
+```csharp
+private const string PlaybackPathFormat = "/recordings/channels/{0}/index.m3u8?start_ms={1}&end_ms={2}&token={3}";
+var hls = string.Format(PlaybackPathFormat, channelId, startMs, endMs, token);
+```
+
+### OW3 [🟡] `MapChannel` IsOnline 判断脆弱
+
+**位置**: 第 116 行
+```csharp
+IsOnline = ch.IsOnline?.ToLower() == "true" || ch.IsOnline == "1",
+```
+Owl 的 `IsOnline` 字段在不同接口中返回类型不同：设备接口返回 `"0"/"1"`，通道接口可能返回 `true/false` 字符串。这种脆弱的兼容方式在 Owl 版本升级后可能失效。
+
+**修复** — 统一为 bool 解析:
+```csharp
+private static bool ParseOwlOnline(string? val) =>
+    bool.TryParse(val, out var b) ? b : val == "1";
+```
+
+### OW4 [🟡] `MapDevice` + `MapChannel` 硬编码设备名
+
+**位置**: 第 91, 113 行
+```csharp
+Category = "硬盘录像机", Group = "视频设备"
+Category = "摄像机", Group = "视频设备"
+```
+**修复** — 提取为常量:
+```csharp
+private const string DEVICE_CATEGORY_NVR = "硬盘录像机";
+private const string DEVICE_CATEGORY_CAMERA = "摄像机";
+private const string DEVICE_GROUP_VIDEO = "视频设备";
+```
+
+### OW5 [⚪] 文件 308 行过长
+
+**修复** — 拆分为:
+- `OwlAdapter.cs` — 类声明 + 构造函数 + Capabilities (40 行)
+- `OwlAdapter.FlatDevices.cs` — IHasFlatDevices 实现 (70 行)
+- `OwlAdapter.Streams.cs` — IHasStreams 实现 (80 行)
+- `OwlAdapter.Recordings.cs` — IHasRecordings (30 行)
+- `OwlAdapter.Alarms.cs` — IHasAlarms (60 行)
+
+---
+
+## 8. Adapters.Owl/OwlAuthHelper.cs — 0 项
+
+代码质量良好的 RSA 加密认证实现。Token 缓存策略合理（2.5 天/3 天）。无可优化项。
+
+---
+
+## 9. Adapters.Owl/OwlModels.cs — 1 项
+
+### OM1 [🟡] `OwlDeviceChannel` 字段注释缺失
+
+**位置**: 第 17-38 行
+`Type`、`Did`、`Ptztype`、`App`、`StreamId` 等字段无注释说明其含义和取值范围。
+
+**修复** — 添加 XML 注释:
+```csharp
+/// <summary>类型: "DEVICE"(NVR) | "CHANNEL"(摄像头)</summary>
+public string? Type { get; set; }
+/// <summary>设备 ID（通道记录指向其所属设备）</summary>
+public string? Did { get; set; }
+/// <summary>云台类型: 0=无, 1=方向, 2=预置位</summary>
+public int? Ptztype { get; set; }
+```
+
+---
+
+## 10. Adapters.MC4/Mc4Adapter.cs — 4 项
+
+### MC1 [🟠] `GetAlarmsAsync` DateTime.MinValue 仍发送
+
+**位置**: 第 145-146 行
+```csharp
+From = from.ToString("yyyy-MM-dd HH:mm:ss"),
+To = to.ToString("yyyy-MM-dd HH:mm:ss"),
+```
+当 `from`/`to` 为 `DateTime.MinValue`（B8 路由默认值）时，发送 `"0001-01-01 00:00:00"` 给 MC4——MC4 将认为这是有效日期过滤。
+
+**修复**:
+```csharp
+From = from == DateTime.MinValue ? "" : from.ToString("yyyy-MM-dd HH:mm:ss"),
+To = to == DateTime.MinValue ? "" : to.ToString("yyyy-MM-dd HH:mm:ss"),
+```
+
+### MC2 [🟡] MC4 模型应独立文件
+
+**位置**: 第 266-350 行
+`Mc4TreeNode`、`Mc4PointValue`、`Mc4AlarmQuery` 等 8 个类全部定义在 `Mc4Adapter.cs` 底部。
+
+**修复** — 创建 `Mc4Models.cs`（参照 KMS/Owl 的模式），将 266 行之后的模型移出。
+
+### MC3 [🟡] `GetMultiRealtimeValuesAsync` + `GetHisAlarmsAsync` 未暴露到 B 路由
+
+**位置**: 第 211, 228 行
+这两个方法是 MC4.0 原生批量接口，但 Program.cs 中没有对应的 B 路由暴露它们。B4-batch 路由直接用 `IHasPoints.GetRealtimeValuesAsync` 逐设备调用。
+
+**修复** — B4-batch 路由已检查 `Mc4Adapter` 类型并优先调用 `GetMultiRealtimeValuesAsync`（已实现）。确认编译通过即可。
+
+### MC4 [🟡] `ConfirmAlarmAsync` / `EndAlarmAsync` 不检查响应
+
+**位置**: 第 175-192 行
+```csharp
+await client.PostAsync("/api/central/alarm/confirm", ...);  // 无 resp.EnsureSuccessStatusCode()
+```
+MC4 返回非 200 时静默失败，调用者认为确认成功。
+
+**修复**:
+```csharp
+var resp = await client.PostAsync(...);
+resp.EnsureSuccessStatusCode();
+```
+
+---
+
+## 11. Adapters.MC4/Mc4AuthHelper.cs — 1 项
+
+### MA1 [🟡] `_needMd5` 只获取一次
+
+**位置**: 第 46-57 行
+```csharp
+if (!_needMd5.HasValue) { /* 仅首次调用时查 conf/get */ }
+```
+如果 MC4 服务重启并更改了加密配置（encrypt true↔false），适配器不会重新检测。但实际场景中 MC4 不会在运行时切换加密模式，风险极低。
+
+**修复** — 加一个 Token 刷新计数器，每 N 次重新获取 conf/get（N=10 即可）。
+
+---
+
+## 12. Adapters.Kms/KmsAdapter.cs — 1 项
+
+### KM1 [⚪] `OpenerIds` 缩进不齐
+
+**位置**: 第 296 行
+```csharp
+                    OpenerIds = parameters.TryGetValue(...)
+```
+前面的注释和代码使用 8 空格缩进，`OpenerIds` 使用 0 空格缩进。视觉效果不一致但不影响编译。
+
+**修复** — 统一缩进为 8 空格。
+
+---
+
+## 13. Adapters.Kms/KmsAuthHelper.cs — 0 项
+
+Token 缓存 25min(30-5)、Bearer 头、Invalidate 均实现正确。无可优化项。
+
+---
+
+## 14. Adapters.Kms/KmsModels.cs — 0 项
+
+15 个 DTO 覆盖全部 KMS 接口，字段完整。标准接口 DTO 虽暂未使用，但注释说明 Phase 2 用途——保留合理。
+
+---
+
+## 15. Host/Program.cs — 6 项
+
+### PR1 [🟠] `SyncAllDevicesAsync` 和 `FlattenTree` 在两个层次定义
+
+**位置**: 第 152-184 行
+这两个函数在 `InitializeAllAsync` 回调的闭包作用域中定义为局部函数。如果未来需要在其他地方调用（如 A3 手动触发），将不可用。
+
+**修复** — 提取为私有静态方法或迁移到 Core:
+```csharp
+// 新建 Core/Infrastructure/DeviceSyncHelper.cs
+public static class DeviceSyncHelper
+{
+    public static async Task SyncAllAsync(AdapterRegistry reg, GatewayClientFactory factory, string nodeCode, string token) { ... }
+    private static void FlattenTree(...) { ... }
+}
+```
+
+### PR2 [🟡] Swagger 无 XML 注释
+
+**位置**: 第 17-19 行
+```csharp
+builder.Services.AddSwaggerGen();  // 无 XML 注释选项
+```
+所有 Minimal API 端点没有 Swagger 描述，调用者必须参考外部文档。
+
+**修复**:
+```csharp
+builder.Services.AddSwaggerGen(c =>
+{
+    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
+    c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFile));
+});
+```
+并在 `.csproj` 中添加 `<GenerateDocumentationFile>true</GenerateDocumentationFile>`。
+
+### PR3 [🟡] 路由注册代码可读性差
+
+**位置**: 第 186-377 行
+19 条 B 路由全部内联在 `Program.cs` 中，每条路由 5-10 行，总计 ~200 行路由注册代码。
+
+**修复** — 按模块拆分为扩展方法:
+```csharp
+// Host/Routes/HealthRoutes.cs
+public static class HealthRoutes
+{
+    public static void MapHealthEndpoints(this WebApplication app, AdapterRegistry registry) { ... }
+}
+// Host/Routes/DeviceRoutes.cs — B2, B3, B3-sync
+// Host/Routes/StreamRoutes.cs — B6a, B6b, B7, snapshot
+// Host/Routes/RealtimeRoutes.cs — B4, B4-batch, B5
+// Host/Routes/AlarmRoutes.cs — B8, B9-confirm, B9-end
+// Host/Routes/ControlRoutes.cs — B10
+// Host/Routes/LogRoutes.cs — B11
+// Host/Routes/SyncRoutes.cs — B12, B13
+```
+Program.cs 改为:
+```csharp
+app.MapHealthEndpoints(registry);
+app.MapDeviceEndpoints(registry);
+// ...
+```
+
+### PR4 [🟡] 配置缺少验证
+
+**位置**: 第 53-83 行
+`app.Configuration.GetSection("Owl").Get<List<OwlConfig>>()` 可能在配置格式错误时返回 null，直接 `foreach` 正常运作但无错误提示。
+
+**修复** — 加空值检查和警告:
+```csharp
+var owlList = app.Configuration.GetSection("Owl").Get<List<OwlConfig>>();
+if (owlList == null || !owlList.Any()) Console.WriteLine("[Gateway] WARNING: 未配置 Owl 适配器");
+```
+
+### PR5 [🟡] `appsettings.json` 凭证明文
+
+**位置**: appsettings.json
+```json
+"NodeToken": "changeme",
+"Password": "your_owl_password",
+"ClientSecret": "your_client_secret"
+```
+
+**修复** — 生产环境注入:
+```json
+"NodeToken": null,  // 生产环境由 SECMPS_GATEWAY_TOKEN 环境变量注入
+"Password": null,   // 生产环境由 OWL_PASSWORD 注入
+"ClientSecret": null // 生产环境由 KMS_CLIENT_SECRET 注入
+```
+Program.cs:
+```csharp
+var nodeToken = Environment.GetEnvironmentVariable("SECMPS_GATEWAY_TOKEN") ?? gwCfg["NodeToken"];
+```
+
+### PR6 [⚪] dotnet-tools.json 未使用
+
+`gateway/src/IntegrationGateway.Host/dotnet-tools.json` 存在但可能无声明工具。确认是否被使用。
+
+---
+
+## 16. 跨切面问题 — 4 项
+
+### X1 [🟡] 无统一日志抽象
+
+所有适配器使用 `Console.Error.WriteLine` 直接写控制台。无日志级别、无结构化输出、无法对接日志收集系统。
+
+**修复** — 注入 `ILogger<T>`:
+```csharp
+public class OwlAdapter : ...
+{
+    private readonly ILogger<OwlAdapter> _logger;
+    public OwlAdapter(..., ILogger<OwlAdapter> logger) { _logger = logger; }
+    
+    public async Task<bool> HealthCheckAsync()
+    {
+        try { ... }
+        catch (Exception ex) { _logger.LogWarning(ex, "[{Code}] HealthCheck 失败", AdapterCode); return false; }
+    }
+}
+```
+
+### X2 [🟡] `GetAuthenticatedClientAsync` 每次 new HttpClient
+
+三个适配器（Owl/KMS/MC4）的 AuthHelper 都在 `GetAuthenticatedClientAsync` 中 `new HttpClient { BaseAddress = new Uri(_baseUrl) }`。每个请求创建一个新的 HttpClient 实例，无法复用连接池。
+
+**修复** — 传入 `IHttpClientFactory`:
+```csharp
+public class KmsAuthHelper
+{
+    private readonly IHttpClientFactory _httpFactory;
+    public async Task<HttpClient> GetAuthenticatedClientAsync()
+    {
+        var token = await GetTokenAsync();
+        var client = _httpFactory.CreateClient();  // 连接池复用
+        client.BaseAddress = new Uri(_baseUrl);
+        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
+        return client;
+    }
+}
+```
+**跨文件影响**: 三个 AuthHelper 构造函数全部需加 `IHttpClientFactory` 参数。三个 Adapter 构造函数也需传递。
+
+### X3 [🟡] 无 request/response DTO 版本策略
+
+当前所有接口模型无版本号字段。未来接口升级时无法区分新旧格式。
+
+**修复** — 在 B 路由响应中加 `version` 字段:
+```csharp
+return Results.Ok(new { version = "1.0", items = result.Items, total = result.Total });
+```
+
+### X4 [⚪] `csproj` 无 `<GenerateDocumentationFile>` 配置
+
+三个适配器项目均无 XML 文档生成配置。
+
+**修复** — 在各 `.csproj` 中添加 `<GenerateDocumentationFile>true</GenerateDocumentationFile>`。
+
+---
+
+## 统计
+
+| 级别 | 数量 | 位置 |
+|:--:|:--:|------|
+| 🟠 严重 | 4 | RateLimiter(Owl.GetDevices size,MC4 MinValue,Program SyncAll) |
+| 🟡 改善 | 21 | 命名/拆分/日志/HttpClient/配置 |
+| ⚪ 低优 | 5 | 缩进/tools.json/注释 |
+
+## 总评
+
+网关架构设计优秀——适配器模式隔离清晰、限流/认证/错误处理一致、接口粒度过细（19 条 B 路由）而非不足。最大改进空间在于：HttpClient 连接池复用、日志抽象统一、Program.cs 路由拆分。