🎯 异常慢下载处置规范（2026-10-20）
📌 结论摘要
结论是：任何下载、包安装、镜像拉取或构建依赖获取，只要持续低于正常吞吐或长时间没有字节进展，就必须主动停止等待，立刻采集证据、检索记忆、测速可信替代源并切换到最快路径。依据是 2026-10-20 Docs 构建事件：102 上的 pip install --no-cache-dir mkdocs-material 在 9.8 MiB 的 Babel wheel 上运行超过 20 分钟，而同一时刻对同一制品做 8 MiB 限量测速，Tencent PyPI 为 21143309 B/s、Aliyun 为 12314963 B/s、官方 PyPI 为 4350763 B/s、Tsinghua 为 1329157 B/s。影响是“等它自己完成”不再被接受，构建和下载必须具备可观测进度、替代源、自动选择和可审计回退。
🗂️ 目录
🚨 触发条件
结论：慢不是单看总耗时，而是看进展速率。 依据是长时间等待通常来自单连接停滞、CDN 慢速、并发占满或构建缓存未命中，单纯延长超时只会扩大无响应时间。影响是以下任一条件出现时必须进入处置流程，不能继续静默等待。
| 条件 | 判定 | 立即动作 |
|---|---|---|
| 60 秒无字节增长 | size 或连接计数连续不变 |
采集进程、连接、文件大小和日志，停止当前等待 |
| 吞吐低于测速基线 20% 持续 60 秒 | 例如基线 5 MB/s，实际低于 1 MB/s | 测速替代源并准备切换 |
| 预计剩余时间超过 5 分钟 | 当前速率与剩余大小推算 | 优先使用镜像、缓存或跨节点路径 |
| 同一构建步骤超过历史基线 3 倍 | 例如 Docs pip 从约 5 分钟变为 20 分钟 |
取消该 Run，修复构建输入后重跑 |
连接长期处于 ESTAB 但无应用进展 |
进程 sleeping 且临时文件不变 | 视为慢链路，不视为正常计算 |
📊 记忆与现场证据
结论：记忆系统已经给出两条可复用路径，分别是镜像测速和节点分层传输。 依据是历史记忆记录了 Docs 构建无缓存时 pip install 占 319.7 秒、GitHub 直连约 80-90 KB/s 而代理可达 2-12 MB/s、101 到 102 实测约 82 MB/s、File-Hub PUT/GET 约 1.2/2.3 MB/s。影响是处置时必须先查已有经验，不重新猜测。
| 证据来源 | 数字或事实 | 用途 |
|---|---|---|
| 历史 CI 记忆 | Docs 构建的决定性耗时是 pip install --no-cache-dir mkdocs-material，无缓存约 319.7 秒 |
定位构建慢的单点 |
| 历史下载记忆 | GitHub 直连 80-90 KB/s，gh-proxy.com 约 2-12 MB/s |
说明可信代理与原始源需要实测比较 |
| 历史节点记忆 | 101→102 约 82 MB/s；101→MM/RR/DD/dog 明显更低 | 决定是否本地测速、跨节点或走 File-Hub |
| 当前现场 | Babel 9.8 MiB wheel 长时间停滞；复测时官方、Tencent、Aliyun、Tsinghua 均可达但速度差异大 | 证明官方源也可能瞬时慢，不能把“源正确”当成“路径正常” |
| 当前 CI | 构建进程、BuildKit 容器、临时 wheel 大小和网络连接均可观测 | 证明应取证后切换，不应盲目重启 |
🧭 标准处置流程
结论：固定按“证据、记忆、路径规划、测速、切换、校验、留档”执行。 依据是节点系统里可用的路径不止“本机直连一个源”，还包括局域网节点、5 台公网 VPS 和 File-Hub；只看源站速度会漏掉回传慢的路径。影响是任何 Agent 或运维人员都可以按同一个端到端标准选择路径，不需要临场发明方法。
- 记录异常：记录 Run ID、Job、Step、主机、进程、开始时间、当前字节数、连接状态和临时文件路径；不输出凭据。
- 检索记忆：按“下载慢、镜像、测速、缓存、跨节点、File-Hub”查询已有事实，优先复用已验证速度和失败模式。
- 生成候选路径：至少评估目标机直连、局域网节点、5 台公网 VPS、File-Hub 已有对象和 File-Hub 回传；PyPI、npm、apt、Docker/OCI、GitHub Release、模型权重和数据集都使用同一路径模型。
- 限量测速：对每个候选源使用固定 8 MiB 范围或固定 15 秒上限；远程节点还要测“下载到该节点、上传 File-Hub、目标机从 File-Hub 下载”的端到端时间。
- 选择路径：选目标机最终可用时间最短且校验通过的路径；若差距在 10% 内，优先本机或同 LAN，减少跨节点与中转步骤。
- 切换执行：停止旧等待或取消对应 Run，使用新的索引、缓存或来源重跑；保留原 Run 的失败或取消证据和上次失败日志。
- 校验留档：安装后校验版本、SHA-256或镜像摘要、健康检查和回滚入口；把所选源、速度、耗时、失败原因和残余风险写入项目记录与记忆系统。
🕸️ 节点路径规划
结论：节点优势用于扩展可选路径，不用于无条件增加中转。 依据是历史实测 101→102 约 82 MB/s，而公网节点和 File-Hub 的速度差异很大；只有在端到端结果更快时才值得跨节点。影响是同一套方法可以服务构建依赖、模型下载、安装包、镜像和数据同步，而不是只针对 PyPI。
| 路径 | 适用对象 | 计分方式 | 约束 |
|---|---|---|---|
| 目标机缓存或本地镜像 | 已成功构建过的依赖、固定版本包 | 直接命中时间 + 校验时间 | 保留镜像摘要、版本和缓存失效条件 |
| 目标机直连公开源 | 任意小中型对象 | 下载时间 + 校验时间 | 只接受可信 HTTPS 和可校验制品 |
| 局域网节点直连或回传 | 101/102 等同 LAN 资源 | 目标节点下载 + 必要回传 | 大于 1 MB 的非实时传输按项目边界处理 |
| 5 台公网 VPS 抓取 | 对中国源或境外源单边访问更快的对象 | VPS 下载 + File-Hub 上传 + 目标机下载 + 校验 |
必须逐台实测，不能只看 VPS 本地速度 |
| File-Hub 已有对象 | 版本化安装包、镜像归档、模型、数据 | 目标机下载 + 哈希回读 | 必须按命名、版本和 SHA-256 定位 |
| 跨节点实时直传 | 一次性、非归档、当前任务消耗的对象 | 对端下载 + 直传 + 目标机校验 | 遵守节点网络边界的大小、路径和并发上限 |
结论：外部 VPS 只是抓取端，不是天然的最快端。 依据是中国源走境外 VPS 可能绕远，境外源走 VPS 又可能受回传瓶颈；只有把 File-Hub 或直传纳入同一计分，才能判断是否真的更快。影响是跨节点方案必须有完整链路证据，不能把“某台 VPS 能访问 GitHub”写成“整体下载更快”。
结论：实时拓扑先做候选筛选，再做测速。 依据是 Console 拓扑里离线节点显示红色，逻辑入口 GW 不是物理主机，DERP/未知链路不能代表可达数据面；把这些对象当作下载节点会产生无效 SSH、长时间超时或错误结论。影响是候选集合必须从节点角色、在线状态和链路类型生成，不能从图上的位置猜测。
| 拓扑对象 | 在下载路径中的用途 | 边界 |
|---|---|---|
| 101 / 102 | 局域网测速端、构建端、可复用缓存端 | 102 是计算节点；101 是交付协调节点，不在其上长期放业务数据 |
| MM / d02 / dog-public | 外部源抓取端、Edge 路径 | 不承担文件存储；抓取后按归档规则走 File-Hub |
| DD | File-Hub/Cloudreve 存储端点 | 只通过公网 HTTPS 读写；不把 Cloudreve 本地目录当普通文件系统 |
| RR | 控制面与节点状态来源 | 不作为默认大流量抓取端；只有规则 14 的比速场景才作为候选并被记录 |
| Home / NAS | 管理与用户存储资源 | 不作为通用下载中转站或 Nomad Worker |
GW 逻辑入口 |
表示公网入口身份 | 不是可 SSH 的主机，不能参与测速 |
| 红色离线客户端 | 状态观测对象 | 直接排除，不重试到超时 |
| DERP / 未知路径 | 控制面兜底 | 大文件优先 File-Hub，不把仅中继路径当数据面 |
🔧 CI 与下载工具
结论：PyPI 本机源选择已经工具化，节点级路径规划写入统一手册。 依据是新增 scripts/ci/select-pypi-index.sh，它对官方 PyPI、Tencent、Aliyun 和 Tsinghua 的同一 wheel 做 8 MiB 限速测速，输出最快的 HTTPS 索引；Docs Dockerfile 通过 PIP_INDEX_URL 接收结果，并用固定 mkdocs-material==9.7.7、15 秒连接超时和 3 次重试降低不确定性。影响是 102 不再固定走慢源；当本地镜像仍不够快时，按节点路径表继续评估 5 台 VPS 和 File-Hub，而不是只换一个 URL 后继续等待。
结论：缓存后端也必须纳入慢下载判定。 依据是 2026-10-20 第二次构建已把 PyPI 安装缩短到约 1.5 分钟，但 buildx 随后在 GHA cache 导出阶段持续 futex 等待，BuildKit 日志在 02:14:16 后停止推进。影响是 Docs 工作流改用同仓库 GHCR registry cache，避免把构建成功后的缓存上传误当成“构建仍在计算”。
| 对象 | 命令或位置 | 作用 |
|---|---|---|
| PyPI 选择 | bash scripts/ci/select-pypi-index.sh |
并行测速并只输出最快索引 URL |
| 仅查看候选 | bash scripts/ci/select-pypi-index.sh --dry-run |
不联网，列出受控候选 |
| Docs 构建 | .github/workflows/docs-site-docker.yml |
在 Buildx 前选择源并传入 PIP_INDEX_URL |
| Docs 缓存 | GHCR agentmeshos-docs:buildcache |
缓存与镜像同仓库，替代停滞的 GHA cache 导出 |
| Docker 安装 | tools/docs-site/docker/Dockerfile |
固定版本、超时和重试 |
| 节点端到端评估 | 本文“节点路径规划” | 将远端抓取、File-Hub 回传和目标机下载合并计时 |
| 实时拓扑筛选 | Console“网络控制 / 网络态势实时分布图” | 先排除离线、逻辑入口和非数据面链路，再生成候选节点 |
| 大文件与跨节点 | docs/node-network-boundary.md |
继续执行 File-Hub、测速和 SHA-256 规则 |
🔁 回退与失败关闭
结论：源切换失败必须回到官方源或上次已验证镜像，不能静默继续。 依据是镜像源和 CDN 都可能短时故障，官方源仍应作为语义回退；构建缓存命中、镜像摘要和健康检查才是发布依据。影响是切换不会改变生产运行对象，除非新镜像通过完整发布门禁。
- 测速脚本无可用结果时，回退到
https://pypi.org/simple并在日志中明确记录。 - 构建仍失败时，保留上一次成功镜像和 release bundle，不推送半成品。
- 生产回退只使用已经验证过的同摘要镜像和部署脚本，不手工覆盖运行容器。
- 每次异常都要留下“为什么等待、为什么切换、切换前后速度、最终校验结果”，并在下一次遇到同类问题时优先从记忆检索。
⚠️ 风险与未决项
结论：自动选源提升可用性，但镜像信任和速度波动仍需持续约束。 依据是脚本只接受硬编码的 HTTPS 可信候选，仍不能证明镜像内容在所有时段与官方完全一致；版本固定和下载校验可以降低风险，但不能替代上游供应链审计。影响是需要把镜像选择、哈希校验和异常频率纳入后续运维观察。
| 事项 | 当前状态 | 下一步 |
|---|---|---|
| 镜像内容一致性 | HTTPS 来源受控，但未对每个 wheel 固定哈希 | 后续引入 requirements lock 与 --require-hashes |
| 自动测速开销 | 每次 Docs 构建增加最多约 15 秒并行探测 | 保持 8 MiB/15 秒上限，禁止无限下载探测 |
| 非 PyPI 下载 | 方法已泛化，但尚无一个跨生态自动编排器 | 将 PyPI、npm、apt、Docker、模型和数据集接入同一路径评分格式 |
| VPS 与 File-Hub 自动评分 | 当前已定义计分方法，Docs 事件因本地镜像足够快未触发跨节点 | 在真实慢源事件中执行 5 节点端到端测量并写入记录 |
| 网络抖动 | 单次测速可能受当时拥塞影响 | 低速率时允许重测一次，仍慢则切换并记录 |
| 规则生效范围 | 项目脚本已落地，系统级规则仍需同步 | 将六步流程写入全局规则和按需手册 |