RecordPlatform

中文

English

中文

English

Appearance

监控告警 ​

RecordPlatform 的监控、指标和健康检查。

健康端点 ​

端点说明
/actuator/health整体健康状态
/actuator/health/livenessKubernetes 存活探针
/actuator/health/readinessKubernetes 就绪探针
/actuator/prometheusPrometheus 指标
/actuator/circuitbreakers熔断器状态

健康检查组件 ​

/actuator/health 端点包含：

组件检查内容
dbMySQL 连通性
redisRedis 连通性
rabbitRabbitMQ 连通性
s3StorageS3 节点可用性
sagaSaga 事务健康
outboxOutbox 事件健康
encryption加密策略状态

响应示例 ​

json
{
  "status": "UP",
  "components": {
    "db": { "status": "UP" },
    "redis": { "status": "UP" },
    "s3Storage": {
      "status": "UP",
      "details": {
        "healthyNodes": 3,
        "totalNodes": 3
      }
    },
    "encryption": {
      "status": "UP",
      "details": {
        "algorithm": "ChaCha20-Poly1305",
        "likelyHasAesNi": true
      }
    }
  }
}

关键指标 ​

Saga 指标 ​

指标类型说明
saga_totalCounter按状态统计的 Saga 总数
saga_durationTimer执行/补偿耗时
saga_runningGauge正在运行的 Saga
saga_pending_compensationGauge待补偿的 Saga

Outbox 指标 ​

指标类型说明
outbox_events_totalCounter按状态统计的事件数
outbox_publish_latencyTimer事件发布延迟
outbox_pendingGauge待发送事件
outbox_exhaustedGauge超过最大重试的事件

存储指标 ​

指标类型说明
s3_node_online_statusGauge节点在线状态 (0/1)，由 backend actuator 基于存储容量快照桥接暴露
s3_node_usage_percentGauge节点磁盘使用率 (0-100)，由 backend actuator 基于存储容量快照桥接暴露

生产存证批次指标 ​

所有标签都是固定枚举；指标刻意不包含 tenant、file、candidate 或 batch ID，以限制时序基数。

指标类型标签 / 说明
app_attestation_candidate_totalCounterresult=admitted|batched|dead_letter
app_attestation_candidate_backlogGauge最近一次定时任务观察到的全局值，status=ready|dead_letter
app_attestation_batch_totalCounterstatus=completed|retry|manual_review
app_attestation_batch_sizeDistribution summary每个已创建 batch 的 manifest 证据叶子数
app_attestation_batch_latency_secondsTimercandidate 准入到本地 batch 创建的耗时
app_attestation_production_run_totalCounterresult=completed|disabled|failed

健康阈值 ​

配置告警阈值：

yaml
# Outbox 阈值
outbox:
  health:
    pending-threshold: 500    # >500 待发送 → DEGRADED
    failed-threshold: 20      # >20 失败 → DOWN

# Saga 阈值
saga:
  health:
    running-threshold: 100    # >100 运行中 → DEGRADED
    failed-threshold: 10      # >10 失败 → DOWN
    pending-compensation-threshold: 50  # >50 待补偿 → DEGRADED

Prometheus 配置 ​

抓取配置 ​

yaml
scrape_configs:
  - job_name: 'recordplatform-backend'
    metrics_path: '/record-platform/actuator/prometheus'
    static_configs:
      - targets: ['backend:8000']

  # storage 和 fisco 是 Dubbo Provider，没有内嵌 HTTP 服务器，
  # 不直接暴露 /actuator/prometheus。通过 OTel Collector 的 Prometheus 导出端点采集。
  - job_name: 'otel-collector'
    metrics_path: '/metrics'
    static_configs:
      - targets: ['otel-collector:8889']

告警规则 ​

yaml
groups:
  - name: recordplatform
    rules:
      - alert: SagaFailureHigh
        expr: saga_total{status="failed"} > 10
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Saga 失败率过高"

      - alert: OutboxBacklog
        expr: outbox_pending > 500
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Outbox 事件积压"

      - alert: S3NodeDown
        expr: s3_node_online_status == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "S3 存储节点离线"

Grafana 仪表盘 ​

推荐面板 ​

  1. 系统概览

    • 请求速率和延迟
    • 错误率
    • 活跃连接数

  2. Saga 状态

    • 运行中 vs 已完成 vs 失败
    • 补偿队列深度
    • 平均耗时

  3. 存储健康

    • 各域节点状态
    • 复制延迟
    • 磁盘使用率

  4. 区块链

    • 交易速率
    • 熔断器状态
    • 重试次数

分布式追踪 (OpenTelemetry) ​

项目已集成 OpenTelemetry Java Agent v2.26.1，三个 Java 服务自动采集 traces 和 metrics。

基础设施 ​

组件端口说明
OTel Collector4317 (gRPC), 4318 (HTTP), 8889 (Prometheus)数据收集与转发
Jaeger16686追踪可视化 UI

启用方式 ​

Docker 部署：设置 OTEL_JAVAAGENT_ENABLED=true（默认启用）

本地开发：

bash
./scripts/start.sh start --otel all

--otel 与 --skywalking 互斥，不能同时启用。

配置 ​

环境变量默认值说明
OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4317Collector 地址
OTEL_TRACES_SAMPLERparentbased_traceidratio采样策略
OTEL_TRACES_SAMPLER_ARG0.1采样率 (10%)

W3C Trace Context 标准传播，支持跨服务链路追踪。

Jaeger UI ​

访问 http://localhost:16686 查看追踪数据。

存储完整性校验 ​

系统定期验证 active chunk manifest、S3 兼容对象 metadata、抽样分片内容和区块链记录。缺少 active manifest 的文件会被标记为迁移状态；巡检不会回退到把 file.fileHash 当作对象内容哈希。

工作原理 ​

  1. 每天凌晨 2 点自动执行，采样 1% 的成功文件。
  2. 按租户批量加载 active manifest 及其有序分片。
  3. 对本轮样本应用随机选择的巡检级别：
级别校验内容对象下载
LIGHTWEIGHTmanifest 身份/安全合同，以及所有分片的路径、tenant、大小、metadata hash 和已声明 ETag不下载
MEDIUM轻量校验，加分片顺序/数量/聚合大小和 canonical manifestHash不下载
HEAVY中量校验，加受字节上限约束的分片抽样 SHA-256 和链记录比对仅选中的分片

file.fileHash 和 manifest v1 的兼容字段 fileHash 是链记录 ID。对象内容证据来自分片 plainHash/cipherHash，有序 manifest 的证明是 manifestHash。

配置 ​

配置项默认值说明
integrity.check.enabledtrue是否启用
integrity.check.schedule.cron0 0 2 * * ?执行时间
integrity.check.sample-rate0.01采样率
integrity.check.batch-size50每批文件数；运行时限制在 1..1000
integrity.check.lock-timeout-seconds1800分布式锁租期
integrity.check.heavy.sample-chunks1每个文件在重型巡检中抽样的唯一分片数
integrity.check.heavy.max-download-bytes83886080单文件单轮允许下载的最大抽样字节数

管理接口 ​

端点说明
GET /api/v1/admin/integrity-alerts查询告警列表
POST /api/v1/admin/integrity-alerts/check手动触发校验
PUT /api/v1/admin/integrity-alerts/{id}/acknowledge确认告警
PUT /api/v1/admin/integrity-alerts/{id}/resolve解决告警

告警通知 ​

发现完整性异常时，系统通过 SSE 推送 INTEGRITY_ALERT 事件通知管理员。记录和事件包含 alertType、severity、有界 evidence，以及适用时的 actualHash、chainHash。

Manifest 驱动的新类型包括 MANIFEST_MISSING、MANIFEST_INVALID、OBJECT_NOT_FOUND、METADATA_MISMATCH、CONTENT_HASH_MISMATCH、CHAIN_MISMATCH，并继续支持 CHAIN_NOT_FOUND。历史 HASH_MISMATCH、FILE_NOT_FOUND 记录仍可读取以保持 API 兼容。同一 tenant、文件和类型存在未解决告警时，不重复写入或推送。分布式锁（Redisson）串行化定时和手工巡检。

生产 Merkle Batch 触发器 ​

生产准入默认关闭，必须由运维显式启用。关闭时不会创建定时任务；人工触发返回 disabled 结果，且不读取或写入 candidate、batch、leaf。

配置项默认值说明
attestation.production.enabledfalse启用 candidate 准入和 flush
attestation.production.poll-interval-ms30000调度间隔
attestation.production.initial-delay-ms30000调度首次延迟
attestation.production.min-batch-size50自动 flush 数量阈值
attestation.production.max-batch-size100单个 batch 最多领取的 candidate 数
attestation.production.max-wait-seconds600最老 READY candidate 的最大等待时间
attestation.production.seed-limit200每租户每轮最多发现的新 candidate 数
attestation.production.max-batches-per-run2每租户每轮恢复与新建 batch 的共享预算
attestation.production.claim-lease-seconds120candidate worker 租约
attestation.production.candidate-max-attempts3进入 dead letter 前的最大失败次数

两个接口都要求管理员角色，并从认证请求上下文取得租户；调用方不能提交跨租户 ID。

端点说明
POST /api/v1/admin/attestation-batches/production/trigger为当前租户强制执行一轮有界处理
GET /api/v1/admin/attestation-batches/production/status查询 feature 状态、有效上限、candidate backlog 和 due batch

灰度顺序：先应用 Flyway migration，以 enabled=false 部署，检查状态和指标，再逐环境启用。回滚应用行为时设置 enabled=false；必须保留 candidate 表和 leaf 证据列，删除它们会丢失审计状态或破坏已创建 batch。

SkyWalking 集成 ​

配置 ​

部署脚本自动配置 SkyWalking Agent：

bash
SKYWALKING_OPTS="-javaagent:/path/to/skywalking-agent.jar \
  -Dskywalking.agent.service_name=platform-backend \
  -Dskywalking.collector.backend_service=skywalking-oap:11800"

分布式追踪 ​

SkyWalking 提供：

  • 跨服务请求追踪
  • 慢查询检测
  • 服务依赖映射
  • 错误追踪

日志聚合 ​

ELK Stack 配置 ​

yaml
# Logstash 管道
input {
  beats {
    port => 5044
  }
}

filter {
  if [fields][service] == "recordplatform" {
    grok {
      match => { "message" => "%{TIMESTAMP_ISO8601:timestamp} %{LOGLEVEL:level} %{GREEDYDATA:msg}" }
    }
  }
}

output {
  elasticsearch {
    hosts => ["elasticsearch:9200"]
    index => "recordplatform-%{+YYYY.MM.dd}"
  }
}

SLO/SLI 可观测性 ​

服务级别指标（SLI） ​

SLI指标来源计算方式
上传成功率saga_total_total{status}completed / (completed + failed + compensated)
存证 P99 延迟otel_blockchain_operation_duration_seconds{quantile="0.99"}基于 Collector 导出的 P99 样本做 max_over_time(...[window]) 窗口汇总
存储可用性s3_node_online_status对按 (node, fault_domain) 去重后的瞬时在线节点占比做 30 天滚动平均
API 错误率http_server_requests_seconds_count{status}5xx 数量 / 总请求数

服务级别目标（SLO） ​

SLO目标窗口错误预算（30 天）
上传成功率>= 99.5%30 天滚动0.5%（约 216 分钟）
存证 P99 延迟<= 5s30 天滚动—
存储可用性>= 99.9%30 天滚动0.1%（约 43 分钟）
API 错误率<= 0.5%30 天滚动0.5%（约 216 分钟）

燃尽率告警 ​

采用 Google SRE 多窗口燃尽率模型。短窗口和长窗口必须同时触发，以减少误报。

严重性短窗口长窗口燃尽率响应
Critical5 分钟1 小时14.4x立即处理
Warning30 分钟6 小时6x当日处理
Info1 小时1 天3x下周处理

配置文件 ​

文件用途
config/prometheus/recording-rules.ymlSLI 预计算规则（多时间窗口）
config/prometheus/alerting-rules.yml燃尽率告警 + 错误预算耗尽告警
config/grafana/slo-dashboard.jsonGrafana v10+ SLO 概览仪表盘

在 Prometheus 中加载：

yaml
rule_files:
  - "config/prometheus/recording-rules.yml"
  - "config/prometheus/alerting-rules.yml"

Grafana 仪表盘 ​

将 config/grafana/slo-dashboard.json 导入 Grafana。仪表盘包含：

面板行内容
SLO 总览4 个 Stat 面板，显示当前 SLI 值与目标对比
错误预算上传和 API 错误预算剩余仪表
上传成功率时序图，含 99.5% SLO 阈值线
存证延迟P50/P95/P99 时序图，含 5s 阈值线
存储可用性30 天滚动可用性比率 + 节点状态表格
API 错误率错误率时序图 + Top-5 错误端点
Resilience4j断路器状态 + 重试次数

注意：存证延迟通过 OTel Collector 的 Prometheus exporter 暴露，因此指标名带有 otel_ 前缀。它仍然使用 Micrometer 预计算的客户端分位数（.publishPercentiles()），因此当前 SLO 规则用 max_over_time(...) 对导出的 P99 样本做窗口汇总，而不是 histogram_quantile(...)。这些分位数不可跨多实例聚合。如需多实例部署，请在 FiscoMetrics.java 的 Timer builder 中添加 .publishPercentileHistogram(true)。

Released under the Apache 2.0 License.

Copyright © 2025-2026 RecordPlatform