📚 课程目录第4章缓存命中率指标

4. 缓存命中率指标：Hit Ratio 与 Byte Hit Ratio 定义及 API 获取

在代理缓存（Proxy Repository）的效能评估中，命中率是最核心的观测指标。它直接反映了缓存对上游源站请求的卸载能力，也是误差预算（Error Budget）台账中“缓存效率”维度的关键输入。Nexus Repository 提供了两个维度的命中率指标：请求命中率（Hit Ratio）与字节命中率（Byte Hit Ratio）。

4.1 指标定义与业务含义

指标名称	计算公式	业务含义	典型场景
Hit Ratio （请求命中率）	`Hits / (Hits + Misses) × 100%`	衡量客户端发起的请求中有多大比例由缓存直接响应，未穿透到上游源站。	小文件频繁访问场景（如 npm 包元数据、Maven POM 文件）。
Byte Hit Ratio （字节命中率）	`Cache Bytes Served / Total Bytes Requested × 100%`	衡量从缓存中直接返回的数据量占总请求数据量的比例，反映带宽节省效果。	大文件分发场景（如 Docker 镜像层、PyPI 源码包）。

  关键区别： Hit Ratio 关注“次数”，Byte Hit Ratio 关注“流量”。一个仓库可能 Hit Ratio 很高（大量小文件命中），但 Byte Hit Ratio 很低（少数大文件未命中导致流量消耗巨大）。两者必须同时监控，才能全面评估缓存效率。

4.2 指标获取方式：Nexus API 实战

Nexus Repository 通过 REST API 暴露缓存统计信息，无需直接读取数据库。核心端点位于 /service/rest/v1/repositories/{repositoryName}/proxy/statistics。

4.2.1 API 端点与参数

方法	端点路径	说明
`GET`	`/service/rest/v1/repositories/{repositoryName}/proxy/statistics`	获取指定代理仓库的实时缓存统计摘要。
`GET`	`/service/rest/v1/repositories/{repositoryName}/proxy/statistics/interval?from=ISO8601&to=ISO8601`	获取指定时间范围内的历史统计切片，用于趋势分析。

4.2.2 使用 curl 获取实时指标

# 获取仓库 "npm-proxy" 的实时缓存统计
curl -u admin:admin123 \
  -X GET "http://nexus.example.com/service/rest/v1/repositories/npm-proxy/proxy/statistics" \
  -H "accept: application/json" | jq .

返回 JSON 示例（关键字段）：

{
  "repositoryName": "npm-proxy",
  "hitRatio": 78.5,
  "byteHitRatio": 62.3,
  "totalRequests": 15420,
  "hits": 12105,
  "misses": 3315,
  "totalBytesRequested": 8589934592,
  "cacheBytesServed": 5347737600,
  "lastUpdated": "2025-03-21T10:30:00Z"
}

字段映射：

hitRatio → 请求命中率（百分比）
byteHitRatio → 字节命中率（百分比）
hits / misses → 原始计数，可用于自行计算精确率
cacheBytesServed / totalBytesRequested → 字节级原始数据

4.2.3 获取历史趋势数据

# 获取过去 7 天的每小时统计切片
curl -u admin:admin123 \
  -X GET "http://nexus.example.com/service/rest/v1/repositories/npm-proxy/proxy/statistics/interval?from=2025-03-14T00:00:00Z&to=2025-03-21T00:00:00Z" \
  -H "accept: application/json" | jq .

返回结果为一个数组，每个元素包含该时间窗口内的聚合统计，可用于绘制命中率趋势图，识别缓存效率下降的时间点。

4.3 命中率计算与误差预算的关系

在误差预算台账中，缓存命中率直接影响上游请求配额消耗。假设上游源站（如 Docker Hub、Maven Central）对 API 调用次数或流量有速率限制，缓存命中率越低，消耗的配额越多，误差预算消耗越快。

缓存命中率	上游请求占比	误差预算消耗速度	建议动作
> 90%	< 10%	慢	维持现状，定期审查缓存策略
70% – 90%	10% – 30%	中等	检查缓存 TTL 设置，分析未命中原因
< 70%	> 30%	快	紧急优化：预热缓存、调整负缓存策略、扩容

4.4 缓存命中率数据流架构

下图展示了从客户端请求到命中率指标落地的完整数据流，以及 API 在其中的采集位置。

4.5 自动化采集脚本示例

以下 Python 脚本可用于定时采集命中率指标，并写入误差预算台账系统（如 Prometheus、InfluxDB 或 CSV 文件）。

import requests
import json
import time
from datetime import datetime

# 配置
NEXUS_URL = "http://nexus.example.com"
NEXUS_USER = "admin"
NEXUS_PASS = "admin123"
REPOSITORIES = ["npm-proxy", "pypi-proxy", "docker-proxy"]

def fetch_proxy_statistics(repo_name):
    url = f"{NEXUS_URL}/service/rest/v1/repositories/{repo_name}/proxy/statistics"
    response = requests.get(url, auth=(NEXUS_USER, NEXUS_PASS))
    response.raise_for_status()
    return response.json()

def main():
    timestamp = datetime.utcnow().isoformat()
    metrics = []
    for repo in REPOSITORIES:
        try:
            data = fetch_proxy_statistics(repo)
            metrics.append({
                "timestamp": timestamp,
                "repository": repo,
                "hit_ratio": data["hitRatio"],
                "byte_hit_ratio": data["byteHitRatio"],
                "hits": data["hits"],
                "misses": data["misses"],
                "cache_bytes_served": data["cacheBytesServed"],
                "total_bytes_requested": data["totalBytesRequested"]
            })
            print(f"[OK] {repo}: Hit={data['hitRatio']}%, ByteHit={data['byteHitRatio']}%")
        except Exception as e:
            print(f"[ERROR] {repo}: {e}")

    # 写入台账文件（示例：追加到 CSV）
    with open("cache_hit_ratio_budget.csv", "a") as f:
        for m in metrics:
            f.write(f"{m['timestamp']},{m['repository']},{m['hit_ratio']},"
                    f"{m['byte_hit_ratio']},{m['hits']},{m['misses']}\n")

if __name__ == "__main__":
    main()

注意： 如果代理仓库从未被访问过，API 可能返回 null 或 0 值。建议在采集脚本中加入空值校验，避免台账中出现异常数据导致误告警。

4.6 命中率指标的可观测性最佳实践

双指标联合监控： 同时设置 Hit Ratio 和 Byte Hit Ratio 的告警阈值，避免单一指标掩盖问题。
按仓库粒度采集： 不同制品类型（npm、Docker、Maven）的缓存行为差异巨大，应分别采集和评估。
时间窗口对齐： 在误差预算台账中，命中率的时间窗口应与上游配额重置周期对齐（如 Docker Hub 的 6 小时窗口）。
缓存预热影响： 新部署的代理仓库或清空缓存后，命中率会短暂下降，台账应区分“稳态”与“瞬态”数据。