3. 容量水位概念：存储容量、拉取/推送 QPS、并发连接数、镜像数量与标签数量阈值
在镜像供应链巡检中，容量水位是衡量仓库与分发系统健康度的核心指标集。水位过高不仅会导致拉取/推送失败、响应延迟飙升，还可能触发 Cosign 签名接口超时或签名验证失败。本章从五个关键维度定义容量水位，并给出巡检阈值参考。
3.1 五大水位指标定义
| 指标名称 | 定义 | 巡检单位 | 典型阈值（预警/告警） |
|---|---|---|---|
| 存储容量 | 仓库后端存储（对象存储或文件系统）已用空间占总配额的百分比 | % / GB | 70% / 85% |
| 拉取 QPS | 每秒从仓库拉取镜像清单或 Blob 的请求数 | 次/秒 | 集群额定 60% / 80% |
| 推送 QPS | 每秒向仓库推送镜像清单或 Blob 的请求数 | 次/秒 | 集群额定 50% / 75% |
| 并发连接数 | 同一时刻与仓库建立 TCP 连接的数量（含长连接与短连接） | 个 | 仓库最大连接数 60% / 80% |
| 镜像数量与标签数量 | 仓库中存储的镜像仓库总数与每个仓库下的标签总数 | 个 | 镜像数 10 万 / 20 万；单仓库标签 1000 / 3000 |
巡检要点： 存储容量与镜像/标签数量属于慢变水位，建议每小时巡检一次；拉取/推送 QPS 与并发连接数属于快变水位，建议每分钟巡检一次，并在 Cosign 签名调用前后各采集一次快照。
3.2 容量水位与 Cosign 签名的关联
Cosign 签名接口（cosign sign / cosign verify）在调用过程中会执行以下操作，每一步都可能受水位影响：
- 拉取镜像清单：需要从仓库读取 manifest，若拉取 QPS 过高或并发连接数打满，清单获取会超时。
- 推送签名对象：签名完成后将
.sig与.att对象推送到仓库，推送 QPS 过高或存储容量不足会导致推送失败。 - 标签写入：签名对象通过标签关联原镜像，若单仓库标签数量超过阈值，标签写入可能被仓库拒绝。
常见故障模式： 当存储容量超过 90% 时，部分对象存储（如 S3、MinIO）会进入只读模式，此时 Cosign 推送签名对象将直接返回 403 错误。巡检脚本必须将存储容量作为前置检查项。
3.3 容量水位巡检架构
下图展示了容量水位巡检与 Cosign 签名接口之间的数据流与依赖关系：
3.4 巡检阈值设定原则
- 存储容量：以仓库后端存储配额为基准，预留 15% 的 Buffer 用于签名对象与 attestation 的临时写入。
- 拉取/推送 QPS：以仓库集群额定 QPS 的 60% 作为预警线，80% 作为告警线；超过 80% 时 Cosign 签名接口应自动降级为异步模式。
- 并发连接数：监控仓库网关或负载均衡器的活跃连接数，超过 60% 时建议增加连接池或限流。
- 镜像数量与标签数量：单仓库标签超过 1000 个时，Cosign 的
cosign verify遍历标签的性能会显著下降；超过 3000 个时建议拆分仓库或启用标签回收策略。
3.5 巡检脚本示例（水位采集片段）
#!/bin/bash
# 容量水位巡检示例 - 采集存储容量与标签数量
REGISTRY="registry.example.com"
REPO="my-app"
THRESHOLD_STORAGE=85 # 存储容量告警阈值 (%)
THRESHOLD_TAGS=3000 # 单仓库标签告警阈值
# 1. 获取存储容量（假设通过 registry API 获取）
STORAGE_USED=$(curl -s "https://${REGISTRY}/v2/_catalog" | jq '.repositories | length')
echo "当前存储使用量: ${STORAGE_USED} 个仓库"
# 2. 获取指定仓库的标签数量
TAG_COUNT=$(curl -s "https://${REGISTRY}/v2/${REPO}/tags/list" | jq '.tags | length')
echo "仓库 ${REPO} 标签数量: ${TAG_COUNT}"
# 3. 水位判断
if [ "${TAG_COUNT}" -ge "${THRESHOLD_TAGS}" ]; then
echo "WARNING: 标签数量 ${TAG_COUNT} 超过阈值 ${THRESHOLD_TAGS}，建议清理或拆分仓库"
fi
# 4. 输出 Prometheus 格式指标供 Grafana 展示
echo "# HELP registry_storage_usage 仓库存储容量水位"
echo "# TYPE registry_storage_usage gauge"
echo "registry_storage_usage{repo=\"${REPO}\"} ${STORAGE_USED}"
echo "# HELP registry_tag_count 仓库标签数量"
echo "# TYPE registry_tag_count gauge"
echo "registry_tag_count{repo=\"${REPO}\"} ${TAG_COUNT}"
生产建议： 上述脚本应集成到 Prometheus Exporter 或定时任务中，采集结果写入时序数据库。当水位超过预警线时，通过 Webhook 通知 Cosign 签名流水线降低并发度或切换至备用仓库。
3.6 水位巡检与 Cosign 签名接口的联动策略
| 水位状态 | Cosign 签名行为 | 巡检响应动作 |
|---|---|---|
| 正常（所有指标 < 预警线） | 同步签名，正常推送 | 记录日志，持续监控 |
| 预警（任一指标 ≥ 预警线） | 同步签名，增加重试间隔 | 发送告警通知，准备限流 |
| 告警（任一指标 ≥ 告警线） | 切换为异步签名，暂存签名对象到本地队列 | 触发自动扩容或限流，暂停非关键推送 |
| 严重（存储容量 ≥ 95% 或 QPS 打满） | 停止签名，返回 503 给上游 CI | 紧急扩容存储或清理过期镜像 |
通过上述五个维度的容量水位定义与巡检策略，可以确保 Cosign 签名接口在镜像供应链中稳定运行，避免因仓库资源耗尽导致的签名失败或数据丢失。