第 24 章 监控、排错与升级
Walrus 应用的监控要覆盖写入、读取、链上状态和索引器。只监控 Web API 存活，会在真正出问题时没有定位信息。
指标清单
publisher：
- 上传请求数、成功率、失败率。
- P50/P95/P99 写入延迟。
- 单用户上传大小和频率。
- Sui 交易提交失败数。
- 不确定状态 job 数量。
aggregator：
- 读取请求数、成功率、失败率。
- P50/P95/P99 首字节和总耗时。
- 重构失败数。
- 出口带宽。
- cache hit ratio。
索引器：
- 当前处理 checkpoint。
- 落后 checkpoint 数。
- 事件处理失败数。
- DB 写入延迟。
- 重放和去重计数。
业务：
- 即将过期 Blob 数量。
- 校验失败 Blob 数量。
- 用户可见下载失败率。
- sponsor 钱包余额。
日志字段
每条关键日志至少带：
request_id
network
blob_id
blob_object_id
tx_digest
asset_id
user_id 或 tenant_id
state
error_code
duration_ms
敏感应用里，blob_id、文件名、用户 ID 要按内部安全规范脱敏或限制访问。不要为了排错把明文字段打进公开日志系统。
排错顺序
上传失败：
- 看本地文件是否可读、大小是否超过限制。
- 查 publisher 返回码和错误体。
- 查 Sui tx digest 是否存在。
- 查 Blob 对象是否创建。
- 查用户或 sponsor 余额。
- 查服务版本是否匹配目标网络。
读取失败：
- 确认
network正确。 - 确认
blob_id没有截断或编码错误。 - 换一个 aggregator。
- 查 Blob 是否过期。
- 查业务对象是否已替换引用。
- 做哈希校验，确认不是缓存旧内容。
索引异常：
- 查 checkpoint lag。
- 查失败事件和重试队列。
- 用
tx_digest直接查 Sui RPC。 - 比较对象版本，避免旧事件覆盖新状态。
- 必要时从某个 checkpoint 重放。
告警阈值
起步阈值可以这样设：
- 写入成功率 5 分钟低于 99% 告警。
- 读取成功率 5 分钟低于 99.5% 告警。
- 索引器落后超过 100 个 checkpoint 告警。
- sponsor 余额低于 3 天预算告警。
- 7 天内到期且未续期 Blob 数超过阈值告警。
- 校验失败出现任意非零值都告警。
阈值要按业务调，不要照搬。校验失败是高严重度，因为它可能表示数据错配、缓存污染或实现 bug。
升级流程
Walrus 版本要跟网络走：
- Mainnet：
mainnet-v1.47.1。 - Testnet：
testnet-v1.47.1。 - Devnet：
devnet-v1.48.0预发布。
升级步骤：
- 阅读官方 release note，确认是否有配置、合约或数据格式变化。
- 在 testnet 重放核心流程：上传、读取、续期、Move 引用、索引。
- 升级 SDK 和服务端依赖，锁定版本。
- 灰度 publisher/aggregator。
- 观察 24 小时关键指标。
- 再升级生产批量任务和后台索引器。
如果 SDK 升级但服务端仍旧，最容易出现“本地编译通过，协议请求失败”。集成测试必须连真实 testnet endpoint。
Runbook 模板
每个故障类型写一份 runbook：
故障：读取成功率下降
影响：用户下载失败、页面资源加载失败
先看：aggregator 5xx、超时、出口带宽、cache hit ratio
快速动作：切备用 aggregator、降低大文件并发、绕过异常 CDN 节点
确认恢复：读取成功率回到阈值，校验失败为 0
事后：补容量、调超时、更新告警
runbook 要能让值班人员执行，不要只写“检查网络”。