私有镜像站缓存延迟的根本原因是默认采用“被动触发+定时轮询”机制：Harbor proxy cache默认24小时同步元数据，Nexus不主动拉取tags列表，Satis完全依赖手动构建；需通过API主动同步、开启索引预加载或绑定Git webhook实现近实时更新。
私有镜像站缓存为何总“慢半拍”
私有镜像站（如 Harbor、Nexus、Satis）的缓存模块出现版本延迟，根本不是配置写错了，而是它默认按“被动触发 + 定时轮询”机制工作。比如 Harbor 的 proxy cache 默认每 24 小时拉一次上游元数据，而 Nexus 的 proxy repository 甚至不主动刷新 manifest 列表——除非有人请求过该镜像。所以你 push 了 v1.2.3，但下游 docker pull 或 composer require 仍报错“not found”，大概率是缓存还没“看见”这个版本。
- Harbor 默认不自动同步新 tag，只缓存被首次拉取过的镜像
- Nexus 3 的 proxy repo 不解析 upstream 的 tags API，仅靠 HTTP HEAD 请求试探是否存在 blob，漏判率高
- Satis 完全依赖
php bin/satis build手动触发，无人执行就永远不更新
Harbor 启用主动同步并调低刷新间隔
Harbor v2.5+ 支持通过 API 主动触发代理仓库同步，也能修改后台定时任务周期。别只改 harbor.yml 里的 proxy 配置，那只是声明代理关系。
- 编辑
/config/core/env，追加HARBOR_PROXY_CACHE_SYNC_INTERVAL=300（单位秒，即 5 分钟） - 登录 Harbor UI → 项目 → “代理缓存” → 点击目标 registry → 右上角“同步”按钮手动触发一次
- 更彻底：用 curl 调用同步 API：
curl -X POST "<a href="https://www.php.cn/link/d31aa7390c86c6e3bf2c8ec6c07aff5c">https://www.php.cn/link/d31aa7390c86c6e3bf2c8ec6c07aff5c</a>" -H "authorization: Bearer $TOKEN" - 注意：同步频率太密（如设为 60 秒）可能触发上游限流，尤其对
quay.io或gcr.io
Nexus 3 开启 tags 列表预加载与健康检查
Nexus 默认把 proxy repo 当作“懒加载黑盒”，不主动获取 tags 列表。必须显式开启两项能力才能接近实时感知新版本：
- 在 repository 配置页勾选
Download remote indexes（关键！否则不拉/v2/_catalog和/v2/<name>/tags/list</name>） - 启用
Remote storage health check，设为每 300 秒探测一次 upstream 是否可连通 - 若上游是 Docker Hub，还需在 Nexus 系统设置里关闭
Strict Transport Security (HSTS)，否则某些 redirect 会失败
不这么做，Nexus 就永远不知道 myorg/app:v2.0.0 已发布——除非有人先 docker pull myorg/app:v2.0.0，且该 pull 恰好穿透到 upstream。
Satis 强制增量构建 + webhook 自动触发
Satis 本身无守护进程，靠 satis build 命令生成静态 JSON。延迟来自没人跑它。解决方案不是加 cron，而是绑定 Git tag 推送事件：
- 在 GitHub/GitLab 仓库设置 webhook，目标 URL 设为内网部署的轻量接收端（如 Flask 写个 10 行 endpoint）
- 接收端校验签名后，执行：
php /path/to/satis/bin/satis build /path/to/satis.json /path/to/webroot --no-interaction --skip-errors - 关键参数：
--skip-errors防止单个包失败中断整个构建；--no-interaction避免卡在 stdin - 若用 Composer，还需在项目中配
"repositories": [{"type": "composer", "url": "<a href="https://www.php.cn/link/cc0c7120d78fdcf57974574359fc2445">https://www.php.cn/link/cc0c7120d78fdcf57974574359fc2445</a>"}]，并确保composer clear-cache在 CI 中执行
最易忽略的一点：Satis 生成的 packages.json 默认不包含 dev 分支快照，除非你在 satis.json 显式写 "require-all": true 或列出 "minimum-stability": "dev"。
缓存延迟不是“修不好”，而是多数私有镜像站默认不把上游变更当优先事件处理。真正压低延迟的关键，是让缓存模块从“等请求”转向“盯发布”——这需要 API 调用、webhook 集成和配置项显式打开，而不是只调大超时或换更快硬盘。
