Redis 客户端运维自检清单

运维自检 Checklist

✅ = 0/5，❌ = 5/5，🔍 = 0/5
（如暂不适用，可将条目状态改为 🔍）

Health checks

// 每 5s 主动探活一次，配合 Prometheus counter/statsd
ticker := time.NewTicker(5 * time.Second)
go func() {
	for range ticker.C {
		if err := rdb.Ping(ctx).Err(); err != nil {
			log.Printf("[REDIS] ping failed: %v", err)
			// TODO: 上报告警平台
		}
	}
}()

落地要点

1. 频率可按 SLA 调整；普通 API 服务 5–10 s 足够。
2. Ping 失败应立刻告警并打出 error 级日志。

Error handling

val, err := rdb.Get(ctx, "foo").Result()
if err != nil {
	// redis.Nil == key 不存在
	if err == redis.Nil {
		return "", nil
	}
	return "", fmt.Errorf("redis get foo: %w", err)
}
return val, nil

统一封装 mustGetString(key) / mustSet(key,val)，集中处理 redis.Nil 与网络错误，避免业务侧忘记判错。

Monitor performance and errors

import "github.com/redis/go-redis/extra/redisotel/v9"

if err := redisotel.InstrumentTracing(rdb); err != nil {
	log.Fatalf("otel trace: %v", err)
}
if err := redisotel.InstrumentMetrics(rdb); err != nil {
	log.Fatalf("otel metrics: %v", err)
}

配套指标

Retries

rdb := redis.NewClient(&redis.Options{
	// 根据链路预算 & RT 调整
	MaxRetries:      5,
	MinRetryBackoff: 20 * time.Millisecond,
	MaxRetryBackoff: 300 * time.Millisecond,
})

调参建议

1. MaxRetries ≤ 5，防止级联雪崩。
2. 配合 OTel 指标观察 redis_cmd_retries_total；如触顶须排查。
3. 幂等写入方可安全重试；非幂等场景优先用 Lua 脚本+CHECK/SET。

Timeouts

rdb := redis.NewClient(&redis.Options{
	DialTimeout:  10 * time.Second, // TCP 三次握手 + TLS
	ReadTimeout:  3 * time.Second,  // 单条命令
	WriteTimeout: 3 * time.Second,
})

优化思路

• 结合 p99 网络时延 + 业务 SLA 设定。
• 超时日志必须记录 命令名 / key / 耗时 / 重试次数。
• 过短 → 大量误杀；过长 → 请求线程长时间占阻塞。持续用 OTel 观察 redis_timeout_total 变化。

如何使用这份清单？

1. 把本节内容放入你的项目文档。
2. 每实施一项，将 Checklist 中对应状态从 ❌ 改为 ✅。
3. 若一项暂不适用，将其改为 🔍（待评估）。
4. 持续观测 OTel 指标，按需微调重试/超时配置。

落实完毕后，状态行会自动反映完成度，方便自检与审计。祝你部署顺利、运行稳定!