Skip to content
bitzorcas
中EN

Concept

运维扩展

负责 Incident 记录、运维指标、告警/SLA 读模型,以及 Webhook/CAP 恢复、配置热刷新和 Host 服务重启的受控操作端口。

Last updated

负责 Incident 记录、运维指标、告警/SLA 读模型,以及 Webhook/CAP 恢复、配置热刷新和 Host 服务重启的受控操作端口。

一张图读懂主路径

操作员动作

权限 + 审批

事件或动作记录

窄运行时适配器

结果 + 审计

珊瑚色节点表示本模块的核心决策或状态边界。

能力边界

  • 没有受保护状态机的 Incident 严重度、状态记录与 JSON 备注快照
  • 通过 owner Port 提供租户 Webhook 死信视图与全局 CAP 故障操作
  • 当前进程指标,以及受控配置热刷新与服务重启契约

模块明确不包含:Incident、指标、告警与 SLA 持久化归模块本地。Webhook、CAP、配置提供器与服务编排仍归各自 owner 或 adapter;只有失败关闭 Port 不足以证明操作可达。

代码地图

项目主要职责
BitzOrcas.Platform.OpsExtension.Contracts公开契约、端口、DTO 与事件
BitzOrcas.Platform.OpsExtension.Application命令、查询、处理器与应用策略
BitzOrcas.Platform.OpsExtension.Infrastructure持久化、连接器与框架适配器

源码位置: src/Platform/OpsExtension

核心用例

  • CreateIncident
  • UpdateIncidentStatus
  • RetryDeadLetter
  • RetryCapFailedMessage
  • ReloadConfig
  • RestartServiceCommand
  • GetRuntimeMetrics
  • GetObservabilitySeriesQuery

阅读用例时,先看请求契约和权限声明,再跟进处理器调用的聚合或端口,最后检查提交后的事件、缓存和审计。

关键模型与契约

关键类型阅读重点
IncidentRecord运维事件状态
IOpsExtensionStore事件与读模型端口
ICapRetryPortCAP 重试适配器
IConfigReloadPort配置热刷新适配器
IHostServiceRestartPort服务编排适配器

用例边界示例

字段说明
代表性契约RetryDeadLetterCommand
返回结果Result
审查重点使用可信租户与 Webhooks owner 重试 Port;不要虚构当前源码并未持久化的 retry-attempt 聚合。

示例伪代码

RetryDeadLetterCommand 伪代码
var tenantId = currentUser.User.TenantId;
var actorKey = currentUser.User.ActorUserId;
var deliveryId = command.DeliveryId.Trim();
// ① 敏感操作先过审批门:ApprovalTicket 无效即拒绝(DeliveryFailureApprovalRequired)。
if (!await approvalGate.ValidateAsync(command.ApprovalTicket, cancellationToken))
return Result.Failure(OpsExtensionErrors.DeliveryFailureApprovalRequired);
// ② 动作前先落意图审计;意图审计写不进去则整体失败关闭(DeliveryFailureAuditUnavailable)。
var intentPersisted = await DeliveryFailureAudit.TryRecordAsync(activityAuditSink,
new ActivityRecord("DeliveryFailure.Webhook.Retry.Intent", actorKey, tenantId,
true, $"delivery={deliveryId}", command.ApprovalTicket, clock.UtcNow),
logger, cancellationToken);
if (!intentPersisted) return Result.Failure(OpsExtensionErrors.DeliveryFailureAuditUnavailable);
// ③ 意图落库后才执行真实重投:Adapter 重入 WebhookDeliveryService,保留 owner guard。
var retry = await webhookRetry.RetryAsync(tenantId, deliveryId, cancellationToken);
var outcome = retry.IsSuccess ? retry.GetValueOrThrow().Status : retry.Error.Code;
// ④ 完成审计使用 CancellationToken.None:即使请求中止也必须留下处置结果。
var completionPersisted = await DeliveryFailureAudit.TryRecordAsync(activityAuditSink,
new ActivityRecord("DeliveryFailure.Webhook.Retry.Completed", actorKey, tenantId,
retry.IsSuccess, $"delivery={deliveryId},outcome={outcome}",
command.ApprovalTicket, clock.UtcNow),
logger, CancellationToken.None);
// ⑤ 真实重投失败优先返回其错误;完成审计缺失则以 OutcomeUnknown 显式暴露未知态。
if (retry.IsFailure) return Result.Failure(retry.Error);
if (!completionPersisted) return Result.Failure(OpsExtensionErrors.DeliveryFailureOutcomeUnknown);
return Result.Success(retry.GetValueOrThrow());

集成关系

Webhook 与 CAP 有具体适配器;配置刷新取决于 AgileConfig,服务重启委托外部编排器而不是杀死 API 进程。操作 Port 不可用时统一失败关闭。

跨模块协作遵循以下方向:

  • 调用方依赖本模块公开 Contracts 或窄端口。
  • 状态变化通过版本化集成事件传播。
  • 具体数据库、消息、缓存、文件或厂商 SDK 留在 Infrastructure。
  • 组合根先注册失败关闭默认实现,再接入生产适配器。

安全、租户与隐私

权限目录已经按 Read/View/Manage 与授权动作对齐,并由 Governance Generator 收集。仍需注意:operations.extension 虽声明为默认关闭,当前用例没有运行时 Feature 门控;Incident 的 Resolved/Closed 也不足以单独充当敏感运维动作的审批证据。

模块保存租户数据时必须写入 TenantId,列表和详情使用同一授权规则。日志、事件和审计只保留诊断所需字段。

失败语义、幂等与可观测性

Webhook 重试重新进入 owner 投递逻辑,CAP 重试条件重置基础表;审计失败当前可能覆盖已经完成的动作结果。

情况处理原则
校验、未找到、冲突或禁止返回类型化 Result/Error,并由统一映射生成 Problem Details
适配器或关键状态不可用安全或高价值操作失败关闭;只读降级必须显式标记
重复请求或重复事件使用稳定幂等键,数据库唯一约束作为最后防线
外部超时传播取消,记录脱敏诊断,仅对安全操作执行有界重试

测试矩阵

#必须覆盖建议层级
1全部 32 条生成端点声明与精确权限码单元 + 集成
2跨租户 Incident/Webhook 访问集成/契约
3Webhook/CAP 重放与适配器失败集成/契约
4Incident 并发、审批绑定与审计双重失败集成/契约

测试还要固定一条通用红线:租户 A 的标识、缓存键、事件或查询条件不能让租户 B 读取或修改数据。

源码导航与变更检查

在 BitzOrcasVNext 仓库根目录运行:

Terminal window
# 列出公开类型,确认新增契约是否真的属于模块边界。
rg -n "^public (sealed |abstract |static |partial )*(record|class|interface|enum)" src/Platform/OpsExtension -g '*.cs'
# 检查跨层引用;调用方不应依赖另一个模块的 Infrastructure。
rg -n "ProjectReference|PackageReference" src/Platform/OpsExtension -g '*.csproj'
# 查找待补实现和省略式代码;预期没有命中。
rg -n "TODO|FIXME|// \.\.\.|省略" src/Platform/OpsExtension -g '*.cs'

扩展与发布检查

  1. 新能力是否由明确的 Contracts、权限和 Feature Key 表达?
  2. 持久化、连接器和 Provider 是否可以通过窄适配器替换?
  3. 生产组合是否仍命中 Null/Unavailable 默认实现?健康检查会不会误报绿色?
  4. 事务、事件、缓存失效、审计和后台任务是否有失败与重试证据?
  5. 中英文文档、图表、契约测试和运维手册是否随代码一起更新?

返回平台模块目录 · 查看模块依赖图 · 新增模块指南

100%

滚轮或按钮缩放 · 放大后拖动画面 · 双击切换 100% / 200%