本章说明可观测性如何同时回答服务是否存活、业务是否可用、数据是否新鲜以及异常是否正在收敛。根平台、注册服务节点、发现服务节点、内容分发平台、链下信任索引器、数据库和官网后端分别产生运行与业务证据；网站可以用旧快照改善访问体验，但旧快照不能替代后台真实健康状态。指标必须带来源、时间、状态和延迟，未知值不得当作零。

本章的观测证据分为四层：服务接口或源码定义的原始事实、后台聚合得到的运行指标、官网页面使用的展示数据，以及运维流程产生的烟测和告警记录。记录指标时至少同时保留 source、observedAt、dataStatus 和 lag，使“接口没有数据”“数据为零”“展示了旧快照”能够被区分。官网页面的展示结果只能说明前端获得了某次响应，不能代替节点、数据库或链下信任索引器的独立核验。

19.1 服务健康与就绪模型

检查顺序应从“能否响应”逐步推进到“能否完成业务”：先核对进程和 /health，再核对就绪状态及数据库连接，随后检查根平台、注册服务节点、发现服务节点、内容分发平台和链下信任索引器之间的依赖。一个接口返回 200 只能作为该检查点的证据；只有依赖检查、数据状态和注册/发现业务烟测均通过，才可将服务标记为业务可用。summary 长期失败时，即使页面仍能显示旧快照，也应保持后台失败状态。

liveness 只证明进程能够响应，readiness 还应检查必要依赖和配置，业务烟测则验证注册、发布、发现等真实路径。健康检查应记录目标、响应码、耗时、依赖状态和时间；数据库可连接不等于索引器已追上游事件，摘要接口有响应也不等于统计完整。恢复确认至少需要连续成功的健康检查和对应业务烟测。

19.2 注册指标

注册指标应围绕一次资源登记建立可追踪链路。推荐将 requestId 绑定到注册请求，将 resourceDid、资源版本或内容摘要绑定到登记事实，再将发布序列、分发批次和索引版本绑定到后续阶段。客户端重复点击或网络重试可以产生多个请求记录，但不能因此把同一资源版本重复计入登记成功；VC 为空时应如实记录返回结果，不能把空值解释为有效凭证。周期统计只在聚合层按统一时区计算，前端不得根据页面刷新次数自行累加。

注册指标至少区分请求接收、校验拒绝、登记成功、VC 返回、根平台受理、发布完成和发现可见。去重应使用请求或资源版本关联标识，而不能按 IP 粗略去重；生产统计应排除明确标记的烟测。TODAY、THIS WEEK、THIS MONTH 使用统一时区和半开时间区间，周期值不能因缓存或降级与累计值混淆。

19.3 发布与传播指标

传播指标以资源 DID、版本、内容摘要和发布序列贯穿各阶段，分别记录事件发生、接收、验证、分发和索引时间。端到端延迟是最后可查时间减首次受理时间，不能用某一段耗时替代。重试和重复批次保持幂等计数；游标停滞、序列缺口和节点离线进入积压或失败指标。

传播链路至少应能回答“资源在哪一阶段停止”：注册服务节点已受理但根平台尚未发布，根平台已发布但内容分发未完成，分发完成但发现服务节点尚未索引，或索引已完成但查询条件未命中。可用如下关联关系核对，而不以某个页面上的资源数量代替链路事实：

resourceDid + version
  -> publicationSequence
  -> distributionBatch / contentDigest
  -> discoveryIndexVersion / indexedAt
  -> queryRequestId / visibleAt

同一资源版本的重试应复用幂等键或被标记为重试；如果只有某一阶段的记录，应在运维结果中明确“已受理”“传播中”或“尚未可查”，而不是简单报告为成功。

19.4 发现查询指标

发现指标区分 DID 精确查询、结构化条件查询和语义查询，记录请求耗时、结果数、空结果、拒绝、超时和服务端错误。相关性不等于可信度，结果仍须经过状态、凭证、发布证明和新鲜度检查；错误响应保留关联标识，便于从官网请求追到发现服务节点日志。

查询指标至少记录查询模式、标准化后的输入摘要、请求标识、服务节点、命中数量、耗时、响应状态和数据状态。语义查询的原始任务描述可以用于排障和质量分析，但日志与统计不应保存不必要的个人或敏感内容；可用摘要、长度和哈希替代全文。空结果需要结合请求是否合法、索引是否新鲜和资源是否在节点覆盖范围内判断，不能直接归为发现服务故障。DID 精确查询命中后仍须核对资源状态、发布证据和版本。

19.5 索引新鲜度与同步指标

同步状态 = 上游最新序列 - 本地游标 + 最近成功时间 + 最近错误
不确定的新鲜度 -> 标记 unknown，不填充为 0

重建索引、增量同步、暂停同步和同步失败应使用不同状态值；运维人员据此判断是没有新事件、处理延迟还是同步链路中断。 同步观测包括当前事件游标、上游最新序列、落后距离、最近成功时间、最近失败原因、索引更新时间和待处理数量。latest_sequence 持续增长只说明上游存在可观测的新事件，不能单独证明本节点完成索引；落后距离未知时显示未知而不是零。重建索引与增量同步分开标记。

新鲜度判断应同时观察上游最新序列、本地已处理游标、最近成功同步时间和最近错误。链下信任索引器的 latest_sequence 继续增长，只能证明上游仍有可观察事件；还必须核对本地游标是否推进、是否存在序列或摘要缺口，以及发现服务节点是否完成对应索引。没有上游序列、接口失败或节点尚未产生数据时，状态应为 unknown 或 unavailable，不应伪装成落后距离为零。

19.6 治理与授权指标

治理指标记录事件来源、链上位置、事件类型、索引游标、节点状态变化和最后同步时间。授权资格、资源控制权与发布结果分别观测；治理事件被索引不等于所有资源状态已更新，节点正常也不等于每条授权材料都有效。验证失败保留证据和原因。治理观测还应保留原始事件摘要，并分别记录链下信任索引器的接收、解码、投影和对外提供时间；资源控制权由资源自身的签名和 DID 文档证明，节点授权由治理路径证明，二者应在指标和故障分析中分开。

19.7 网络级与节点级统计

Network 页面可同时呈现网络级聚合和节点级明细，但聚合来源、更新时间和缺失节点必须可追溯。所有周期统计采用同一时区、边界和去重规则；使用旧快照时携带快照时间和降级标识。聚合值不简单相加不同口径的累计值。

所有窗口使用同一时区和半开区间 [start, end)；数据缺失、请求失败和真实零值必须分别编码，不能用零填充缺失值。

19.7.1 网络级指标

网络级指标描述统计范围内的节点和资源，包括节点数量、注册、发布、发现、治理同步和网络状态。每项指标应说明纳入条件、去重方式、来源接口和更新时间；节点缺少数据时，聚合结果标明覆盖范围和缺失情况，不能把未上报节点按零计入。

19.7.2 节点级指标

节点级指标按节点 DID 或稳定节点标识记录健康状态、授权状态、资源处理量、同步游标、索引新鲜度和最近错误。节点离线、未授权、尚未同步以及统计接口失败使用不同状态，避免以零值或空字符串掩盖真实情况。

19.7.3 注册、发布和发现指标

注册、发布和发现指标分别表示注册服务节点受理、根平台可信发布和发现服务节点索引可见，不能合并为一个“成功数”。同一资源版本通过 DID、版本和发布序列关联，重试、重复索引和旧快照不应造成虚假增长。

19.7.4 指标时间窗口

时间窗口采用统一时区和明确边界；周期值使用固定起止时刻，累计值从定义的统计起点计算。接口、官网 Network 页面和后台报表必须采用同一口径，避免服务器时区、请求时间或缓存生成时间差异造成周期值异常。

19.7.5 数据缺失和降级展示

指标缺失、接口失败、尚未产生数据和旧快照展示分别标记。页面可以显示带时间的旧数据，但必须体现降级状态；后台仍记录真实失败，禁止把缺失转成零，或把快照当作实时健康结论。

19.8 链上治理事件可见性

治理事件展示应区分链上事件时间、信任索引器接收和索引时间、官网接口生成时间及页面显示时间。事件序列或链上位置用于排序和追溯，双语描述是展示层映射，不能替代原始事件。链上或索引服务暂不可用时，应显示不可用或延迟状态。

19.9 日志、追踪与关联标识符

跨服务记录至少关联请求标识、资源 DID、版本、发布序列、事件游标和节点标识，并记录时间、级别、结果和错误摘要。日志不得写入私钥或敏感请求内容；公开接口的错误信息应足够定位问题但不泄露内部配置。

接口层的关联字段应与协议类型保持对应：节点间请求使用 requestId、requestNonce、bodyHash 和 upstreamAuth；资源传播使用 publicationCursor、批次序列和资源包版本；发现查询使用请求标识、发现节点 DID、候选数量、检索后端和耗时；链下信任索引器还应记录最后处理 checkpoint、治理序列和同步时间。建议把这些字段组织成结构化日志，而不是只拼接在一条自由文本消息中。

{
  "requestId": "req-example",
  "resourceDid": "did:oan:SKDM:example-resource",
  "packageVersion": "1.0.0",
  "publicationCursor": 42,
  "nodeDid": "did:oan:INDS:example-node",
  "operation": "discovery_query",
  "result": "completed",
  "elapsedMs": 18
}

上例只展示可用于关联处理过程的公开或低敏字段；生产日志仍须按部署策略过滤资源描述、端点凭证、签名材料和内部错误堆栈。requestId 便于跨服务追踪，但不能作为授权凭证，也不能替代资源控制证明或治理事件序列。

19.10 快照、缓存与降级模式行为

快照覆盖必须满足“完整响应、结构校验、来源更新、时间更新”四项条件；部分响应不能覆盖完整旧数据。 旧快照是用户体验机制，不是健康证明。前端可先显示浏览器侧快照，再后台刷新；成功后以完整新数据替换并更新来源和时间；失败时保留快照但显示降级状态，长期失败仍触发后台告警。无缓存首次访问才显示加载状态，不能让加载占位永久遮住已有数据。

快照记录应至少包含数据来源、生成时间、结构版本和数据状态，例如：

{
  "source": "official-discovery-summary",
  "capturedAt": "2026-09-10T10:00:00Z",
  "dataStatus": "stale",
  "schemaVersion": 1,
  "coverage": "official-nodes",
  "payload": { "resourceCount": 12 }
}

其中 resourceCount: 12 只是某次快照中的业务值，不代表当前实时数量。前端可以在刷新失败时继续展示它，但后台仍需记录刷新失败及其持续时间；当接口恢复时，只有通过结构校验的完整响应才能覆盖该快照。

19.10.1 旧快照加载

页面打开时先读取浏览器侧可用快照，并标明生成时间和来源。快照解析失败、结构版本不兼容或内容完整性校验失败时，应丢弃该快照并进入首次加载流程，不得把损坏数据渲染为正常统计。

19.10.2 后台数据刷新

旧快照显示后，前端在后台请求最新接口，不阻塞用户查看已有内容。请求应有超时和失败处理，刷新过程不改变用户正在查看的资源详情或查询结果，除非新响应通过完整结构校验。

19.10.3 新数据覆盖

只有完整且结构有效的新响应才覆盖旧快照，并同步更新缓存时间、来源和数据状态。新响应部分缺失时保留可用旧数据并标记降级，不能用空响应或零值覆盖有效内容。

19.10.4 长期失败与告警

连续失败、长期无数据和同步游标长期不增长应进入后台告警，记录接口、首个失败时间、最近成功时间和错误证据。页面继续展示快照不得抑制告警；恢复须由连续成功和业务检查确认。

19.10.5 无缓存时的首次加载

没有快照时才显示首次加载状态，并在成功、失败或超时后明确结束。失败状态应说明数据暂不可用，不得无限显示加载文字，也不得伪造零值或空的健康结论。

19.11 备份、恢复与灾难恢复

备份覆盖节点身份和授权材料、数据库、资源包、发布队列、同步游标、配置版本及网站部署产物；私钥和凭据单独加密并限制访问。恢复后先校验完整性、序列连续性和密钥对应关系，再启动写入任务，并通过健康检查、注册/发现烟测和索引追赶确认恢复。 恢复顺序应先恢复配置和节点身份，再恢复数据库及其迁移、资源包和发布队列，随后校验同步游标、治理授权状态和网站构建产物，最后恢复对外写入。恢复过程要防止旧队列重复发布，也要防止游标倒退造成重复投影；可先以只读或暂停写入方式启动，核对 resourceDid、版本、发布序列和授权状态后再开放写入。/health 通过只说明进程恢复，不能单独证明历史索引、治理投影和未完成发布任务已经恢复。

19.12 部署烟测与功能验证

烟测最小闭环：

1. 记录部署提交、产物摘要和环境配置。
2. 检查各服务健康、数据库连接和索引游标。
3. 使用隔离身份完成注册及预期失败请求。
4. 检查根平台发布、分发和发现精确/语义查询。
5. 保存响应、日志、时间线和测试资源清理结果。 烟测使用隔离测试身份和测试资源，保存提交时间、关联标识、响应、日志和清理结果。注册成功不能替代发现验证；还须检查根平台发布、内容分发、索引收敛和数据库状态。任一关键步骤失败、响应不确定或产生未清理的生产数据，都不得宣告部署成功。 烟测结果应形成可复核的时间线，而不是只输出一个“通过”字符串。每一步记录目标地址或服务角色、提交号或产物摘要、请求标识、响应状态、耗时、关键响应字段和副作用清理结果；注册接口的受理成功、根平台发布成功和发现查询命中分别判定。对生产环境不适合写入真实资源时，应使用受控失败请求验证校验逻辑，并使用已有隔离测试资源验证发现路径。任何关键步骤结果不确定，都应保持部署状态为待核查。

19.12.1 注册功能烟测

使用隔离身份和受控资源验证请求校验、控制签名、注册服务节点受理、重复提交和错误响应。若接口返回注册 VC，检查其结构以及与资源 DID、版本或摘要的关联；测试结束后清理测试数据并保存证据。

19.12.2 发现功能烟测

使用已发布的隔离测试资源执行 DID 精确查询和语义查询，核对资源 DID、版本、状态、来源、发布证据和索引时间。结果为空、返回旧版本或接口失败时，结合发布记录和同步游标判断传播延迟还是功能故障。

19.12.3 节点健康检查

逐一检查根平台、注册服务节点、发现服务节点、内容分发平台、链下信任索引器和官网后端的存活、就绪及依赖状态，记录响应码、耗时、版本和检查时间，不能只检查进程是否存在。

19.12.4 数据库和索引器检查

检查数据库连接、迁移状态、关键记录和索引器游标，核对上游最新序列、本地游标和 latest_sequence 的关系及其连续变化，区分没有新事件与同步停止。

19.12.5 失败后的部署处理

关键烟测失败时停止发布确认，保留日志、提交号、产物哈希和测试资源信息，按修复或回滚流程处理。只有重试成功、数据副作用已清理且证据完整，才能重新出具验收结果。

19.13 数据保留、删除与隐私操作

公开指标只返回必要的聚合数据；访问统计、请求关联标识和运维日志应由后台权限控制。浏览器侧本地身份私钥、备份内容和用户提交的敏感材料不得写入访问统计。删除操作要说明在线数据、备份副本和不可变审计记录的不同保留规则。

19.14 运维告警与长期失败检测

告警记录应至少包括服务、接口、首次失败时间、最近成功时间、连续失败次数、错误摘要、影响范围和当前状态。

同一故障使用稳定指纹去重；恢复告警必须同时有连续健康检查和对应业务烟测，不能只依据进程重新启动。 长期失败检测覆盖 summary、治理同步、发布队列和索引游标停滞。告警记录服务、接口、连续失败次数、首个失败时间、最近成功时间、错误摘要和影响范围，并对同一故障去重；恢复需有连续成功和业务验证。网站继续显示旧快照时，后台告警不得被抑制。 summary 接口等周期性检查应保存“最近一次成功”和“最近一次失败”两条事实，而不是只保留当前状态。告警事件至少关联服务角色、接口、时间窗口、连续失败次数、最近成功序列或时间、错误摘要和影响范围；同一接口的短暂网络抖动可合并为一个故障指纹，持续失败则升级处理。恢复时应先确认接口连续成功，再确认数据时间或游标重新推进，最后执行受影响的注册/发现业务烟测。浏览器继续显示旧快照不能暂停或清除这条告警。

19.15 公共服务状态与维护通信

公共状态信息说明受影响服务、开始时间、当前状态、数据延迟和下一次更新，不暴露密钥、内部地址或用户数据。维护期间可以保留只读查询或旧快照，但应标明时间点和不可用功能；恢复公告以实际检查和业务烟测为依据。

参考来源