Operations 运维控制面

Operations 是平台的运维应用编排层。它聚合模块注册表、租户 Store、后台作业目录、配置声明和一组 Framework 运维 Port，同时提供 Schema、备份、恢复与归档命令。它已经不再是早期知识库所描述的“只读控制台”。

1. 模块在架构中的位置

模块本地只有 Contracts 与 Application 两个项目。数据库迁移、备份和归档实现位于 Framework Infrastructure；审批后端来自 API Host 与 OpsExtension；后台执行器也由共享 Framework 和 Host 组合。

2. 当前能力面

3. 代码地图

Operations 没有自己的 Infrastructure 项目，不等于没有基础设施行为；它把这些行为委托给共享基础设施适配器。

4. HTTP 表面要分两类阅读

手写 OperationsEndpointGroup 映射作业管理、归档与缓存治理，共 9 条路由，并统一加认证、userPolicy 限流和精确权限。

Application 另有 16 个 [GenerateEndpoint] 声明，覆盖治理、租户、适配器、配置、外部连接器就绪度与 Schema/备份端点。当前生成器的 EnumerateAllTypes 不递归嵌套类型，因此不能把“有特性”直接等同于“已对外可达”。

# 对照手写映射和自动声明，审查真正的运行时端点来源。
rg -n "Map(Get|Post|Put)|GenerateEndpoint" \
  src/Hosts/BitzOrcas.Api/Endpoints/OperationsEndpointGroup.cs \
  src/Platform/Operations -g '*.cs'

# 当前生成器只遍历 namespace members，没有 GetTypeMembers 递归。
rg -n "EnumerateAllTypes|GetTypeMembers" \
  src/Framework/BitzOrcas.Endpoint.SourceGenerator/GenerateEndpointSourceGenerator.cs

5. 授权模型

OperationsPermissions 当前声明 19 个权限，其中包括缓存治理的两个权限（operations.cache.view / operations.cache.manage）。Website 分析死信的两个权限虽由 Operations 拥有，但路由位于 Website Host 端点组。

手写端点使用 RequirePermission；请求本身还实现 IAuthorizedRequest，通过资源与动作进入统一授权管道。新增路由时必须证明这两套表达不会漂移，而不是只看其中一层。

6. 审批模型

API Host 注册的 ProductionSensitiveOperationApprovalPort 在 Production 与 Staging 令 IsApprovalRequired=true。它把 OpsExtension Incident 的 Resolved 或 Closed 当作批准。

非强制环境的 ValidateAsync 直接成功。即使命令无条件调用 ValidateAsync，也不等于“所有环境强制审批”。没有 OpsExtension Store 时，强制环境只要工单号非空也会降级放行。

7. 当前保证与不可假设

8. 典型阅读路径

• 想建设运维首页：先读治理、适配器、配置与租户；
• 想执行数据库结构变更：读Schema 漂移与迁移安全；
• 想管理 Quartz/回退调度：读后台作业运行控制；
• 想做灾备或数据生命周期：读备份、恢复与归档；
• 想评估上线：读安全、测试、运维与商业 GA；
• 想做缓存失效或排查连接器装配：见本页缓存与连接器治理一节；
• Incident、CAP 失败、Webhook 死信和配置刷新属于 Ops Extension。

9. 缓存治理与外部连接器就绪度

这两组能力都围绕”只读投影 + 受控失效”展开，但来源与保证不同，不能混用。

9.1 缓存治理

缓存治理给平台运维一个狭窄、Host 专属入口：查询区域健康与指纹、按区域失效、对可预热区域执行补洞或全量重建。内部 Tag / Redis key 永不进入 HTTP 合同。横切规则与完整矩阵见缓存指南 · 区域目录。

能力端口 ICacheGovernancePort（Framework）声明 Provider：ProviderMode（LocalMemory / Distributed）、SupportsTagInvalidation、SupportsCrossInstanceInvalidation。FusionCacheStore 支持标签与跨实例失效；MemoryCacheStore 的 SupportsTagInvalidation 为 false。

运行时真相源 ICacheAreaCatalog（DefaultCacheAreaCatalog），Operations 侧 CacheGovernanceCatalog 同步公开区域键。当前 11 个区域：

三个 Host-only 操作（CallerType: Host、TenantId == "0"）：

rebuild 请求体关键字段：Area、Mode、TenantIds?、ApprovalTicket、Reason、Confirm、IdempotencyKey。lazy-only 区域返回 Operations.Cache.WarmupUnsupported。

守卫链（失效与重建共用）：Host 身份 → 区域目录 → Provider 能力（LocalMemory 失效/重建会 ProviderUnsupported）→ 审批工单 → 原因与确认令牌 → 幂等键 → 两阶段活动审计（审计写失败 fail-closed）。

启动侧可选 Cache:Warmup（默认 EnabledOnStartup=false），见生产配置与缓存指南。

9.2 外部连接器就绪度

GET /api/operations/connectors 返回 8 个外部连接器的配置与装配态，资源为 operations/adapters、动作 View。报告字段：Group、Connector、Provider、Status（Configured/NotConfigured/Unavailable）、AdapterRegistered、AdapterImplementation、ConfigurationSection、ChangesRequireRestart（固定为 true）、DependentCapabilities。

这份报告与 §6 讲的”适配器报告”不是一回事。适配器报告按实现类名前缀把约 35 个内部 Port 分成 Production/Default/Unknown 等类别，回答”容器能解析出什么”。连接器就绪度则按业务连接器维度，回答”这个外部系统的配置段是否存在、适配器是否注册”，且 Provider SDK 缺失时会以 fail-closed 的 Unavailable 代理呈现。两者应当分开呈现。

报告只读配置与装配态，不发起真实连通探针，ChangesRequireRestart 固定为 true 意味着改动连接器配置后必须重启进程才生效。

10. 最小调用示例

// ① 请求声明资源 operations/governance + View，统一授权管道据此决策。
var query = new GetGovernanceReport.Query();

// ② Handler 从 AppModuleRegistry 生成当前进程的治理快照。
Result<ModuleGovernanceReport> result =
    await mediator.Send(query, cancellationToken);

// ③ MermaidGraph 是展示数据；发布门禁仍应运行架构测试。
if (result.IsSuccess && result.Value!.HasCircularDependencies)
    release.Block("模块依赖存在环");

11. 源码核查

# 模块本地项目与全部用例。
find src/Platform/Operations -maxdepth 3 -type f -name '*.cs' \
  -not -path '*/bin/*' -not -path '*/obj/*' | sort

# 权限、资源动作与 HTTP 表面。
rg -n "PermissionDefinition|ResourceDescriptor|GenerateEndpoint|RequirePermission" \
  src/Platform/Operations src/Hosts/BitzOrcas.Api/Endpoints/OperationsEndpointGroup.cs \
  -g '*.cs' --glob '!**/bin/**' --glob '!**/obj/**'

# 缓存治理区域目录、重建与 Host 身份规则。
rg -n "CacheGovernanceCatalog|RebuildCacheArea|ConfirmToken|CacheGovernanceRules|ICacheAreaCatalog" \
  src/Platform/Operations src/Framework -g '*.cs'

# 外部连接器就绪度报告。
rg -n "GetExternalConnectorReadiness|ExternalConnectorReadinessEntry" \
  src/Platform/Operations -g '*.cs'

# 不应出现旧文档虚构的计划和锁实现。
rg -n "PlanId|PlanHash|DistributedLock|MigrationPlanStore" \
  src/Platform/Operations -g '*.cs'

返回平台模块目录 · Ops Extension