功能定位：私有缓存仓库到底解决什么
在 HelloWorld IDE 的 Cloud Suite 2026.05 里，私有缓存仓库被明确定义为「把远端依赖提前拉到本地或内网，减少每次构建时重复下载」的加速组件。它与官方公共缓存（registry.helloworld.run）的最大区别是：数据主权归用户，更新节奏自己定，且默认走局域网，省去外网带宽。经验性观察：同一教室 50 台学生机同时拉取 Python 3.12 镜像，开私有缓存后总耗时从约 6 分钟降至 40 秒左右，外网流量下降 90% 以上。
版本演进上，2025 年及以前只有「本地离线包」模式，需要教师提前把完整语言链装进 U 盘；2026 起正式引入「私有仓库」概念，支持 HTTP(S) 代理、镜像回源、并发限流、以及课堂级缓存共享。下文所有路径与开关均以 Cloud Suite 2026.05（内部版本 26.5.1842）为基准，若你仍在 2025 LTS，请先在 Settings → Update → Check Now 拉取最新 delta 包。
前置检查：哪些依赖能被缓存
并不是所有文件进缓存都有收益。HelloWorld 采用「分层哈希」机制，只有体积 ≥8 KB 且 MIME 属于 application/octet-stream、application/zip、application/x-tar 的依赖才会被私有仓库索引。换言之，单文件脚本、README、图片素材默认跳过，避免缓存爆炸。
验证方法：打开任一项目，按下 F1 → Cache Diagnostics，在「Eligible Artifacts」页签能看到可被缓存的组件列表；灰色项即为被规则过滤掉的小文件。若你强制想缓存小于 8 KB 的私有 SDK，可在仓库配置里把 min-size 阈值改成 1 KB，但官方提醒：过小的阈值会显著增加索引时间，经验性观察在 1 万文件场景下可能让冷启动延长 5–7 秒。
最短可达路径：三步完成私有仓库初始化
桌面端（Windows / macOS / Linux）
- 顶部菜单 Cloud → Cache Repository → Initialize Private Registry。
- 在弹出向导里填写本地监听端口（默认 9666）与缓存目录（默认
~/.helloworld/cache/repo）。若机房有多块盘，建议把路径改到 SSD 分区，可提升并发吞吐。 - 点击「Start & Test」，向导会自动下载
registry-cli约 38 MB，并回拉一个 11 MB 的测试包。看到「Success: 200 OK」即完成。
回退方案：若端口冲突，可改任意 1–65535 空闲端口；若误删缓存目录，只需重新执行第 1 步，HelloWorld 会检测到缺失并自动重建索引，不会重复下载已缓存文件。
Web 端（Chrome / Safari / Edge）
Web 版没有本地守护进程，需要借助「Remote Cache Bridge」插件。路径：Settings → Extensions → Cache Bridge → Install。插件会在你的局域网内广播一个 mDNS 服务（_hwcache._tcp.local），桌面端一旦识别，就能在 Web 端下拉菜单里选择「Use LAN Cache」。该模式适合机房管理员统一维护一台缓存机，学生打开浏览器即可受益，无需每人下载完整离线包。
镜像回源与缓存策略：命中率与新鲜度如何兼得
HelloWorld 默认采用「TTL + ETag」双因子校验：对大多数开源包设置 24 h 保鲜，对企业私有包设置 5 min。你也可以在 registry.conf 里写规则：
[[repo.rule]] prefix = "internal-sdk" ttl = 300 priority = 10
以上示例把前缀为 internal-sdk 的依赖刷新间隔缩短到 5 分钟，保证开发迭代时拿到的永远是最新快照；而官方 Python、Node 等公共包仍保持 24 h，减少回源流量。经验性观察：在 200 人同时上机场景，若全部设为 5 min，回源带宽会从 50 Mbps 飙升到 300 Mbps，反而拖慢首次拉取；因此官方建议「私有高频包短 TTL、公共包长 TTL」分层配置。
课堂级共享：一台主机如何服务 500 学生
HelloWorld 的缓存仓库内置「课堂模式」开关，位置：Settings → Cache → Classroom Mode 。打开后会自动把并发连接上限从 50 提到 500，同时启用「零拷贝」传输（sendfile），在千兆交换机环境下可跑满 940 Mbps。需要注意：硬盘最好选用 NVMe RAID1，经验性观察 SATA SSD 在 400 并发时 I/O 延迟会升至 60 ms，导致个别学生端出现「503 Cache Timeout」。
网络层面，建议为缓存机配置静态 IP，并在教室路由把 *.helloworld.run 的 DNS 重写至该 IP。这样即使外网中断，学生端依旧能解析到本地缓存，实现「离线构建」。验证方法：拔掉外网网线，重新打开项目，若底部状态栏显示「Cache: LAN HIT」即表示流量已切换到私有仓库。
与 CI 流程集成：GitHub Actions 里调用私有缓存
企业用户常把 HelloWorld 当「轻量验证节点」，再提交到后端重型 CI。此时可在 GitHub Actions 里加一步：
- name: Setup HelloWorld Cache
run: |
curl -s https://releases.helloworld.run/cli/hw-cache-cli-linux-x64.tgz | tar -C /usr/local/bin -xz
hw-cache config set endpoint http://10.0.0.8:9666
hw-cache auth login ${{ secrets.HW_CACHE_TOKEN }}
随后正常执行 hw build 即可。经验性观察：在 500 MB 依赖场景下，CI 总时长从平均 4 分 20 秒降至 1 分 50 秒，缓存命中率约 85%。若你的 CI 跑在公网云主机，需要把 10.0.0.8 换成公网可路由地址，并在防火墙放行 9666 端口；否则会出现「Connection refused」而自动回退到官方源，不会中断构建。
例外与副作用：何时不该用私有缓存
- 合规隔离场景：若企业要求「构建机绝对不能出内网」，但私有仓库又要回源拉取外网新包，就会违背规定。此时应改用「离线预同步」脚本，提前在能出网的机器把依赖同步到移动硬盘，再人工导入内网缓存机。
- 单项目巨型模型：如一次性下载 20 GB 的 AI 模型，由于默认分片 8 MB，索引项会暴涨到 2 500 条，导致缓存冷启动耗时数十秒。工作假设：把大文件单独托管到 NAS，并在项目里写「跳过缓存」规则更合适。
- 动态快照包：某些团队把每次构建产物当成依赖（版本号带时间戳），这会让缓存不断膨胀，命中率接近 0。官方建议：把「动态包」路径写进黑名单
exclude = ["**/*SNAPSHOT*"]，强制走原链路。
故障排查：从现象到根因的速查表
| 现象 | 可能原因 | 验证步骤 | 处置 |
|---|---|---|---|
| 学生端显示「Cache: MISS」占比高 | 私有仓库未启动或端口被防火墙拦截 | 在缓存机 telnet 127.0.0.1 9666 | 放行 9666/TCP，或更换端口 |
| 构建日志出现「503 Sandbox Quota」 | 匿名用户日限额 100 次已用完 | 登录账号后查看 Settings → Usage | 登录或加入课堂组 |
| 缓存机磁盘飙满 | TTL 过长或未及时 GC | 执行 hw-cache gc --dry-run | 调短 TTL 或手动 GC |
验证与观测：如何量化加速效果
HelloWorld 内置「Cache Analytics」面板，路径：Cloud → Cache Repository → Analytics。核心指标有三：（1）Hit Ratio 命中率；（2）Median Download Time 中位下载耗时；（3）Origin Bandwidth 回源流量。建议每节课结束后导出 CSV，对比「开缓存 / 关缓存」两项数据，用箱线图查看耗时分布。经验性观察：命中率高过 80% 时，学生等待时间明显缩短，课堂节奏更流畅；若低于 60%，则需要检查规则是否过于宽松导致频繁回源。
适用/不适用场景清单
适用
- K-12/高校机房：50–500 台学生机，语言包重复率高，外网带宽有限。
- 企业内网开发：代码不能出防火墙，需自建依赖源。
- 技术直播/比赛：对冷启动时间敏感，需要亚秒级拉包。
不适用
- 依赖体积超大且变动极少的场景（如 20 GB 模型），缓存索引反而拖慢启动。
- 完全离线、无更新需求的封闭系统，本地离线包即可，无需额外维护仓库。
- 高度合规环境禁止任何回源，哪怕是 HTTPS 加密，也建议用「预同步 + 人工导入」。
最佳实践 10 条速查表
- 缓存目录放 SSD，禁用机械盘。
- 课堂模式再开 500 并发，日常开发保持默认 50 即可。
- 公共包 TTL 24 h，私有包 TTL 5 min，分层配置。
- 大文件 >2 GB 写 exclude，避免索引爆炸。
- 每周跑一次
hw-cache gc，回收率低于 15% 可延长 TTL。 - DNS 重写
*.helloworld.run到缓存机，实现真·离线。 - 防火墙放行端口，同时限制来源 IP 仅教室网段。
- CI 里加超时 30 s，防止缓存失效时卡死构建。
- 定期导出 Analytics，命中率 <60% 即调优规则。
- 升级前先用
hw-cache backup快照，版本回退只需还原数据库。
FAQ（结构化数据）
Q1: 更新到 26.5.1842 后缓存服务无法启动？
A: 控制面板移除「旧版 .NET 3.5」后重启即可，详见官方论坛置顶。
Q2: Web 端提示「Bridge 未找到」？
A: 确认与缓存机在同一局域网，并允许浏览器访问 mDNS；Chrome 需开实验功能 chrome://flags/#enable-mdns。
Q3: 能否完全禁止回源？
A: 在 registry.conf 把 upstream-enabled = false 即可，但新包将无法自动同步，需手动导入。
收尾：下一步行动建议
私有缓存仓库不是「开了就忘」的魔法按钮，而是一张需要持续调优的管网。先按本文三步完成最小可用配置，再用 Analytics 量化命中率，结合课堂或 CI 的真实流量逐步调整 TTL、并发与硬件资源。记住两个底线：合规优先，性能数据说话。带着指标去优化，你就能把「构建加速」从口号变成可复现、可汇报、可扩展的工程实践。
