跳转到正文

配置镜像与模型拉取:来源规则、代理、同步组与凭据

本文目录

本文说明怎样配置模型和镜像的获取地址、出站代理、节点复制范围及访问凭据,并在目标节点确认配置生效。

适用场景:下载慢或失败、使用内网镜像站、经代理出网、访问私有模型,或限制跨机房复制。

前置条件:修改拉取设置需要管理员权限。配置来源规则或代理时,准备对应地址;按节点区分规则时,先给节点设置对应标签。验证节点侧效果需要目标节点在线,验证管理节点出站时还需该机器能访问相应地址。

打开设置 → 镜像与模型拉取,按目的选择入口:

要解决的问题配置入口
从镜像站、Harbor 或内网模型代理获取文件来源规则
节点或管理节点通过 HTTP 代理访问外部地址代理
允许哪些节点自动互相复制、限制复制速率同步组
私有镜像或 gated 模型需要身份验证凭据

部署启动、扩副本或重建时,优先使用本地及可读共享存储的完整副本,再尝试同组节点复制,最后按规则拉取或下载。模型页的下载到…则明确从模型登记来源下载;要手动使用已有副本,选择复制到…,见下载与同步模型。修改规则不会替换已经存在的文件。

不配置时会怎样

  • 镜像目录里的官方镜像同时发布在 Docker Hub、quay.io 与华为云 SWR。节点并行探测这几个仓库的 https://<host>/v2/(5 秒超时,结果缓存 30 分钟,走与拉取相同的代理),先试能连上且延迟最低的。
  • 模板声明的 image_sources 是同一镜像的其他副本,排在目录副本之前,同样由节点排序。
  • 镜像下载已报告字节进度且尚未完成时,连续 3 分钟没有进展视为卡住,换下一个候选。慢但还在下载的,只有持续很慢才会换:任意连续 5 分钟平均低于 64 KiB/s,且后面还有候选可试,就放弃当前候选改试下一个;最后一个候选不因速度放弃。只按粗步长显示字节进度的运行时(nerdctl 的大层)不做这项速度判定。
  • runveil(udocker)节点的原生拉取自己决定开多少条连接,并在连接层处理慢,细节见限制镜像拉取的连接数:每个仓库 host 一份连接预算,从 4 条起步,多开连接还能提高整体速率才加到最多 16 条;仓库回 429/503、拒绝连接时减半并等够 Retry-After。连接 2 分钟没有数据,或连续两个窗口明显落后于同一次拉取里的其他连接(绝对下限 30 秒内平均 16 KiB/s),就换一条新连接,并从已收到的字节处继续,不重下整层;各分段下载用各自的 TCP 连接(HTTP/1.1),一条连接变慢不会拖住其余分段。
  • 网络、传输失败或卡住的仓库在这台节点上冷却 30 分钟,在测速候选中排到最后但不剔除。镜像不存在、认证或权限被拒时也会切换候选,但不因此冷却整个仓库;运行时不可用会直接结束本次拉取。
  • 模型默认从登记的站点(Hugging Face 或 ModelScope)下载,节点直连,不设代理(节点自己的环境变量 HTTP_PROXY 等仍然有效)。目录 URL 来源的模型只从它自己的目录下载。
  • 预置一个不限节点的同步组 default-all-nodes:节点之间会自动复制镜像和模型。两台节点连不通(例如两台云容器各自在 NAT 后面)时,复制在约 10 秒内失败,这一对节点 3 小时内不再尝试,副本改为自己拉取。

探测可达和延迟不能保证实际下载速度,最终以目标节点下载进度为准。Docker 通常会报告逐层字节进度;没有字节进度、正在解包或字节已收齐后的镜像登记阶段,不触发上述 3 分钟判定。每个候选从开始拉取到解包完成,最多 60 分钟。

  • Docker 分配不到伪终端时没有字节进度,只受单个候选的总时限约束。
  • nerdctl(包括经 nerdctl 拉取的 Kubernetes 节点)会将重画的进度表换算成逐层字节进度;所有层下载完、只剩耗时变化时视为解包。超过 1 GiB 的层按 0.1 GiB 显示进度,卡住时限按 100 KiB/s 走完一步所需的时间放宽到约 17.5 分钟;更慢的下载只受单个候选的总时限约束。
  • udocker 不输出字节,agent 通过逐层文件大小取得进度。
  • 拉取消息出现 Progress output not understood, stall check off: … 时,表示运行时输出格式无法识别,本次不再判定卡住,只受总时限约束;agent 日志会保留原始行。

来源规则

  1. 打开设置 → 镜像与模型拉取 → 来源规则,添加规则。匹配不带协议时是镜像仓库或镜像前缀,带 http:// 或 https:// 时是模型站点;按下面对应字段表填写。
  2. 选择适用节点,按先后顺序填写替代地址;不允许连接原站点时关闭允许回源。模型规则还需决定是否用于管理节点获取模型元数据。
  3. 站点规则可先用测试连通检查草稿,再保存。保存后在目标节点发起所需的下载或拉取,检查实际来源和完成状态;测试通过只说明探测请求成功,不代表完整文件一定能下载。

镜像规则

每条规则:

字段含义
匹配仓库 host(docker.io、ghcr.io、registry.example:5000)覆盖该仓库的所有镜像;引用前缀(gpuworks/、quay.io/team/app)覆盖前缀下的镜像
替代地址有序列表。host 规则保留仓库路径:docker.io → harbor.corp.example/dockerhub-proxy 把 nginx:1 变成 harbor.corp.example/dockerhub-proxy/library/nginx:1;前缀规则替换前缀
允许回源替代地址都失败后,是否还试镜像原来的仓库。纯内网关掉
适用节点节点标签选择器,空为全部节点;租用的云主机自带 gpuworks.ai/provider、gpuworks.ai/region

适用于节点的所有匹配规则按列表顺序叠加:替代地址在前,镜像自己的副本在后(由节点探测排序)。没有替代地址又关闭回源表示禁止从该仓库拉取;所有候选都被禁止时,启动失败并说明原因。

平台从替代地址拉取后,会在节点上补回原镜像名,因此部署仍使用原引用。规则只对平台发起的拉取生效;手动执行 docker pull 不走这些规则。配置规则不会修改 daemon.json 或 containerd 的 hosts.toml。

常见写法

场景规则
内网节点只能走自建 Harbor 代理缓存docker.io → harbor.corp.example/dockerhub-proxy、quay.io → harbor.corp.example/quay-proxy,关闭回源,适用 site=idc-a;Harbor 需要登录时配凭据
公司内部也推了一份官方镜像gpuworks/ → registry.corp.example/gpuworks/,允许回源
某个模板的镜像只在 ghcrghcr.io → 可用的 ghcr 镜像站,允许回源;或者让模板作者写 image_sources
想用社区 Docker Hub 加速器docker.io → 加速器地址,允许回源。平台不内置加速器,使用前自行确认其访问限制和可用性

站点规则(模型)

匹配写站点根,不带路径,例如 https://huggingface.co、https://modelscope.cn。字段:

字段含义
匹配站点根 https://huggingface.co;协议和主机名必填,不能带路径
替代地址有序列表,http(s):// 地址,可以带路径,例如 https://hf-mirror.com、https://xget.example/hf、http://hf-proxy.corp:8090。节点把原来对该站点的请求改发到这个地址上
允许回源替代地址都失败后,是否还连站点本身。纯内网关掉
适用节点节点标签选择器,空为全部节点
用于管理节点获取模型元数据勾选后,管理节点(server 所在机器)读模型元数据时可以用这条规则的地址;只有站点规则有这个勾选

规则会叠加:一台节点下载某个站点的模型时,所有匹配的规则按列表顺序把各自的替代地址依次排进候选,去重,最后才是站点本身。任何一条匹配的规则关闭了回源,站点本身就不在候选里。什么都不剩时,下载被禁止(WEIGHTS_FETCH_FORBIDDEN)。

目录 URL 来源的模型(登记时给的是 HTTP 目录地址)只从它自己的目录下载,规则不作用于它们。ModelScope 与 Hugging Face 互不回退:模型登记在哪个站点,就只在那个站点的规则和站点本身里找。

公网镜像站与内网代理示例

对匹配项 https://huggingface.co,按节点网络填写替代地址:

  • 使用公网镜像站:填 https://hf-mirror.com,打开允许回源。节点先走 hf-mirror,失败或同一地址卡住 2 次时回到 huggingface.co。
  • 使用内网 HF 代理:填 http://hf-proxy.corp:8090,还可把 https://hf-mirror.com 排在后面。只准走内网时关闭允许回源,huggingface.co 就不在候选里;替代地址仍按填写顺序尝试。

内网镜像仓库同理:在镜像规则中将 docker.io 指向 harbor.corp.example/dockerhub-proxy,关闭允许回源。

海外租机和大陆机房混用时,将上述模型规则的适用节点限定为 site=idc-sh 或 gpuworks.ai/region 等标签,让海外节点直连、大陆节点走镜像。租用的云主机自带 gpuworks.ai/provider、gpuworks.ai/region 标签。

节点怎样依次尝试

模型页显示当前下载站点,切换时附原因。固定到 commit 的模型可在换地址时续传;使用 main 等分支时换地址会从头开始。

服务器按节点算好候选,规则的替代地址在前、站点本身在后。获取文件列表时,地址不可达、HTTP 错误或列表无法解析会使当前地址冷却 30 分钟,并尝试下一候选;源站限流(429、503)则与下载文件一样在原地址等待重试。

下载具体文件时:

  • 可重试的传输错误与源站限流:连接被拒绝或重置、TLS 握手超时、EOF 等,以及 429、503,先在原地址尝试;限流时按 Retry-After 或 RateLimit 头的重置时间等待(至少按退避间隔,最多 5 分 1 秒)。每文件在该地址最多尝试 6 次,最后一个地址最多 16 次,均含首次;次数耗尽仍失败才冷却换址。
  • 不可重试的来源错误:其他 HTTP 错误状态(包括 404、401/403)或 TLS 证书验证失败等,直接冷却 30 分钟并换候选,没有下一候选时结束。
  • 连续卡住:连续 5 分钟没有响应头或新数据算一次卡住,切断后尝试续传;同一地址连续两次且还有候选时冷却换址。最后一个地址不再切换,仍受 16 次总尝试上限约束。

冷却中的地址下次排在最后,不会被剔除;冷却与镜像拉取共用。

管理节点怎样读元数据

管理节点与计算节点的网络不同时,为管理节点可用的站点规则勾选用于管理节点获取模型元数据;需要代理时,还要在代理上勾选用于管理节点出站访问。管理节点逐个探测这些站点规则的候选地址,每个候选最多 5 秒,再从选中的地址读取元数据;只有允许回源时才访问原站点。有多个 Hugging Face 风格候选时,仓库信息可读但文件返回 401/403 的地址会被跳过,继续尝试其他候选;若所有候选都拒绝文件访问,仍尝试读取首个能应答地址的元数据,不能据此判断权重下载已获授权。

目录 URL、镜像归档、测试登录等出站请求使用管理节点代理,不由站点规则改写。

管理节点访问普通私网模型站点、HTTP 目录、镜像仓库及本机回环时,默认无需白名单。若管理员开启严格模式,则须授权必要的主机或网段;此时仅配置代理或网络可达还不够。平台管理员可在设置 → 安全与访问 → 出站访问策略管理开关和白名单,也可由主机管理员直接编辑 server.yaml 的 outbound_restrict_private_hosts 和 outbound_allow_private_hosts。两个字段的修改均从保存后的下一次管理节点 HTTP 请求或重定向生效,无需重启 server;已开始读取的响应体不中断。页面保存会写回同一配置文件;其他页面或文件编辑发生变更时,先重新加载再保存,以免覆盖他人的修改。配置文件缺失、不可读、无效或超过 1 MiB 时,临时拒绝普通私网与本机回环,公网继续遵循原有策略;修复后,下次请求恢复有效策略。特殊元数据、链路本地与保留地址始终禁止,见出站 HTTP 代理策略。

登记来源读取失败时
Hugging Face / ModelScope仍可登记,但元数据可能缺失。页面提示 MODEL_METADATA_UNREACHABLE 或 MODEL_METADATA_FORBIDDEN 时,检查管理节点规则和出站访问;不能把登记成功当作模型已就绪
HTTP 目录 URL管理节点必须先读取并解析目录,失败会阻止登记。目录地址不受站点规则改写,出站访问受管理节点代理控制,见从 HTTP 目录导入

Hugging Face 元数据也可由浏览器从同一套管理节点候选地址读取;只有实际取到内容才标为浏览器读取,未取到时由管理节点尝试。公共站点元数据暂不可达本身不会使部署准入失败,模型文件和其他部署条件仍须满足。

常见网络配置示例

下面是各种网络环境下的填法。所有地址都要自己填,平台不内置任何镜像站、加速器或预设。

网络场景从哪里配置
A. 海外或节点能直连公网不配置,按默认行为获取
B. 大陆,用公网镜像站在来源规则中填写模型镜像站
C. 机房有内网 HF 代理在来源规则中填写内网模型代理和镜像仓库,按需禁止回源
D. 海外租机加大陆机房用来源规则的适用节点区分机房
E. 完全离线预置模型,或配置内网模型站点并关闭回源;镜像另行准备,见下方说明
F. gated 或私有模型添加对应站点的凭据
G. 管理节点与计算节点网络不同分别配置管理节点元数据访问与管理节点代理
H. 节点要经代理出网按标签配置代理,Docker 节点还需核对生效状态
I. 离线导入按下方离线导入模型登记;整个集群离线时再配两条禁止规则

hf-mirror.com 的说明

hf-mirror.com 是个人运营的公共镜像站,没有 SLA,可能限速、改版或下线,所以平台不把它写成默认值。上面的 B 场景需要你手动填。生产环境建议自建代理(如 xget)或 Harbor、Nexus 一类的内网缓存,把它放在替代地址的第一位,hf-mirror 与站点本身当后备。

完全离线:两条「禁止」规则

没有出口的集群可添加下面两条规则,禁止从 Hugging Face 和 ModelScope 下载,避免等待公网连接超时。这不是全平台的断网开关。

匹配替代地址允许回源适用节点用于管理节点获取模型元数据
https://huggingface.co空关空(全部)勾选
https://modelscope.cn空关空(全部)勾选

这两个站点的模型随后需使用节点已有目录、共享存储或同组节点副本;缺少可用来源时,部署页直接说明。内网有对应模型镜像站时,将其填入替代地址即可。

HTTP 目录模型仍从登记的目录地址下载,可使用内网文件服务器;镜像仓库须另配镜像规则、内网副本或离线归档。完整准备流程见离线环境部署。

离线导入模型

  1. 把模型目录拷到某台节点(或共享存储)。
  2. 两种登记方式任选:登记成本地路径(来源 local);或先登记 Hugging Face / ModelScope 模型(让部署模板按来源找到它),再在模型页对那台节点「登记路径」。
  3. 在模型详情确认所选节点和路径已可用。其他同组节点需要此模型时,可从该副本复制;手动操作见节点间同步。

登记路径会补齐缺失的元数据(config、README、大小),已有内容不覆盖。若目录由 huggingface-cli download --local-dir 下载,.cache/huggingface/download/*.metadata 全部指向同一个 commit,且这是模型唯一副本,模型会固定到该 commit。

测试连通

  1. 在站点规则抽屉中点击测试连通,选择 1 到 5 台目标节点和仓库,默认 Qwen/Qwen3-0.6B。验证 gated 模型时改成实际仓库,避免只测公共仓库。
  2. 查看逐节点、逐地址结果:可用、需要凭据、HTTP 状态码或不可达。401/403 表示需检查对应站点凭据,不能当作完全可用。
  3. 修正失败项后重新测试并保存,再通过目标节点的实际下载确认配置。此测试使用节点的代理、no_proxy 和凭据,不验证管理节点自身的连通性。

测试按节点和地址分别显示结果:需要凭据表示地址已连通但文件下载被 401/403 拒绝;不可达表示探测未成功,并附延迟或原因。每个地址最多等待 10 秒。Hugging Face 的公共仓库信息可读不代表 gated 文件能下载,因此还会尝试读配置文件;GGUF 等仓库没有 config.json 本身不影响可达结论。

探测请求与 API

每个地址超时 10 秒,探测方式如下:

  • Hugging Face 风格地址:GET <地址>/api/models/<仓库>/revision/main,应答后再取 <地址>/<仓库>/resolve/main/config.json 的第一个字节。门禁仓库的仓库信息对所有人公开、只拒绝下载文件,所以要测门禁模型时把仓库改成它,文件被拒(401/403)就显示「需要凭据」;仓库里没有 config.json(如 GGUF 仓库)不影响结论;
  • modelscope.cn:GET <地址>/api/v1/models/<仓库>。

接口为 POST /api/v1/pull/source-rules/test。

同步组

同步组名称去除首尾空白后须唯一,区分大小写,最多 64 个 UTF-8 字节;创建和改名使用同一规则。列表和删除确认显示 #ID。升级时,存量重名按 ID 确定性加后缀,保留全部组 ID、节点条件和限速。

在设置 → 镜像与模型拉取 → 同步组添加或编辑组,按节点标签限定范围、设置复制限速并保存。随后在部署获取预估或实际复制进度中检查源节点是否符合预期。节点只自动从同组节点复制镜像和模型:

  • 一个节点属于多个组时,可以从任何一个同组节点复制;两节点共享多个组时取最严的限速。
  • 不属于任何组的节点不自动复制,只能在模型页或镜像页手动发起。
  • 同步组表达「连得上但不该走」:两个机房之间是慢专线、两台带公网 IP 的机器在不同大洲。连不通的情况不需要分组,复制会快速失败并回退。
  • 它是普通的组,可以改名、收窄或删除。多机房集群可以删掉它,按机房标签各建一个组;租用的云主机可以用 gpuworks.ai/provider 或 gpuworks.ai/region 分组。要恢复全部节点互相复制,新建一个不填节点条件的组即可。
  • 同一标签选多个值时满足其一即可,不同标签需同时满足。要单独选中某几台节点(例如没有云厂商标签的自有机器),先在计算节点页给它们加一个标签。
  • 每个组可以设复制限速,默认不限。

复制用的网络仍按存储同步网络选择:同一存储同步网络上的节点优先作为源。

凭据

在设置 → 镜像与模型拉取 → 凭据按下表添加条目,每个 host 一条。保存后可用测试登录检查,再以目标节点的实际拉取结果确认。密码和令牌加密存储,接口与页面都不回显。

种类填写怎么用
镜像仓库仓库 host、用户名、密码或令牌随节点期望状态下发,agent 只放在内存里。拉取时写一个临时 DOCKER_CONFIG 目录,拉完删除,不执行 docker login,不碰节点上的 ~/.docker/config.json
模型站点站点 host(如 huggingface.co)、token,用户名留空以 Authorization: Bearer 发送,只在 https 且 host 完全一致时带上:镜像站和其他域名永远拿不到。遇到重定向时,同域名及其子域名(例如站点的 CDN)会带,其他域名不带
  • udocker 的原生拉取直接带认证;udocker 命令行回退路径不支持认证,按匿名拉取。
  • 测试登录从管理节点发起,经用于管理节点出站访问的代理,访问私网地址还须满足管理节点的授权条件。镜像仓库请求 /v2/,token 请求 Hugging Face 的 GET /api/whoami-v2;节点能到而管理节点到不了的站点会测试失败,以实际拉取为准。
  • 目前只确认了 Hugging Face 的私有与 gated 仓库,ModelScope 私有仓库尚未验证。
  • 接口 /api/v1/pull/credentials;旧的 /api/v1/pull/registry-credentials* 返回 410。

代理

在设置 → 镜像与模型拉取 → 代理添加条目,填写下列字段并保存。用预览节点所使用代理确认匹配范围,再到目标节点详情查看拉取代理是否生效;Docker 还需按下方 dockerd 的状态处理。

字段含义
http_proxy、https_proxy代理地址
no_proxy不走代理的目标,语义同 Go 的 NO_PROXY:* 表示全部;可写 IP、CIDR;域名匹配自身及其子域名;以 . 或 *. 开头只匹配子域名;可带端口;loopback 与 localhost 永远不走代理
用户名、密码密码加密存储,不回显
适用节点节点标签选择器,空为全部节点
备注自由文字
用于管理节点出站访问勾选后,管理节点的出站访问使用这条

例如,机房节点需经代理出网时,可将适用节点限定为 site=idc-sh,填写 http_proxy、https_proxy 和 no_proxy。匹配的节点拉镜像、下载模型和探测都走该代理;管理节点也需要走时,勾选用于管理节点出站访问。

一台节点用第一条满足适用条件的条目,条目之间不叠加;没有匹配时用 agent 自己的环境变量。管理节点的出站代理(读元数据、取 logo、登记目录 URL、预览与探测镜像归档 URL、凭据测试登录)是第一条勾选了「用于管理节点出站访问」的条目。

agent 自己的请求再加上 loopback 与 server 所在地址进 no_proxy;同一份列表用于 agent 自己的请求、nerdctl 与 udocker 的命令行拉取(它们以前会丢掉 NO_PROXY)以及 dockerd 的 drop-in。目录 URL 的模型现在也经节点代理下载;内网文件服务器要写进 no_proxy。

节点详情里有只读的「拉取代理」卡片,显示这台节点用的是哪一条以及 dockerd 状态。代理页有「预览节点所使用代理」,按已保存的配置列出每台节点会用哪一条。接口:/api/v1/pull/proxies、/api/v1/nodes/{uuid}/pull-proxy。

dockerd

nerdctl、udocker 节点每次拉取按节点代理设置,立即生效。

Docker 节点的拉取由 dockerd 执行,代理只能配在 dockerd 上。agent 把代理写进 systemd 覆盖文件并执行 systemctl daemon-reload,不重启 dockerd。保存平台代理后,按以下顺序确认:

  1. 在节点详情的拉取代理卡片查看 dockerd 实际使用的代理。与设置不一致时,页面提示未生效。

    清空平台代理后,agent 删除自己生成的代理覆盖文件;dockerd 重启前仍使用旧代理,页面继续提示未生效。节点没有配置平台代理时,平台不修改你自己配置的 dockerd 代理,只显示当前值。

  2. 需要重启时,先确认中断影响:dockerd 开了 live-restore 时容器不中断,否则节点上所有容器都会停,平台会重新拉起推理实例。确认可以接受后,点击卡片旁的重启 dockerd并确认。

  3. 回到拉取代理卡片核对是否已生效。页面比较当前加载的配置与 dockerd 实际报告,不以设置保存成功为准。

dockerd 覆盖文件与配置比对

覆盖文件是 /etc/systemd/system/docker.service.d/zz-gpuworks-proxy.conf:

[Service]
Environment="HTTP_PROXY=http://192.0.2.8:3128" "HTTPS_PROXY=http://192.0.2.8:3128" "NO_PROXY=localhost,127.0.0.1,::1,<server 地址>,<你填的 no_proxy>"

文件名以 zz- 开头,使其排在常见的手工覆盖文件(如 proxy.conf、http-proxy.conf)之后;systemd 按文件名顺序应用同名环境变量。daemon.json 中的代理仍可能优先,见下表。具体比对读取 systemd 当前加载的配置(systemctl show docker -p Environment)与 docker info。

排障:

现象原因与处理
一直提示未生效,没有重启按钮,说 daemon.json 优先/etc/docker/daemon.json 里配了 proxies,dockerd 优先用它。删掉那里的代理(或把它改成你要的值)再重启 dockerd
提示需要 rootagent 不是 root,也没有免密 sudo(sudo -n true 失败)。按页面给出的文件内容和两条命令(sudo systemctl daemon-reload、sudo systemctl restart docker)手动执行;页面比对的是 docker info,执行后自动显示已生效
不是 systemd 管理的 dockerd、rootless docker、Mac 上的 Docker Desktop平台只展示 dockerd 的代理,不修改
代理里有用户名和密码dockerd 在 docker info 里把两者都显示为 xxxxx,比对时按同样方式处理

限制镜像拉取的连接数(runveil 节点)

runveil(udocker)节点自己下载镜像层,同时打开多少条到仓库的 TCP 连接由节点自动决定,不再固定为「层数 × 分段数」(最多 24 条)。私有仓库(Harbor、华为云 SWR、阿里云 ACR、registry.zstack.ai)或公司代理常按来源地址限制连接数或请求频率,开太多会收到 429 或被直接断开;链路本身慢时,多开连接也不会更快。docker、nerdctl 的拉取由它们自己的进程负责,不受这里影响。

  • 按仓库 host 一份预算。 同一节点上同时拉取的多个镜像共用同一个仓库的预算;经代理访问时,预算属于代理,代理后面的所有仓库共用。
  • 从 4 条起步,只在有收益时增加。 每 3 秒量一次整次拉取的速率:把连接数加倍后,新连接还在建立(TCP、TLS、重定向)的第一个窗口不参与判断,下一个窗口速率提高不到 15% 就退回原来的数量,并再试一次,仍不到才停在这个数量;大于 256 MiB 的层至少切成 4 段,更大的按约 64 MiB 一段切分(最多 64 段),连接数增加时同一层可以同时读更多段。上限默认 16 条。
  • 仓库让慢下来就慢下来。 收到 429 或 503、连接被拒绝时,连接数减半;同一个窗口内连接被重置达到 3 次或打开连接数的一半时同样减半(最长保持一分钟再回升),最低 1 条。同时到来的一批拒绝算一次,只按一次的等待时间等。连接被拒绝也会等待后重试,而不是直接失败。仓库给了 Retry-After 就等够这段时间(最长 2 分钟)再发下一个请求,没给就从 2 秒起每次翻倍、最长 30 秒,不会立即重连。同一仓库的其他拉取同样等待。每个请求最多连续等 5 次,仍被拒绝则这次拉取失败,由候选切换去试下一个来源。
  • 仓库不支持 Range 时,这一层只用 1 条连接。 它把某一层的分段请求答成整个文件时,这一层改为一条连接整块读取;其他层不受影响。
  • 慢连接按相对标准更换。 一条连接连续两个 30 秒窗口平均低于 16 KiB/s(绝对下限),或低于同一次拉取里其他连接速率中位数的十分之一,或比自己此前最高速率下降到十分之一而其他连接没有下降,就换一条新连接并从已收到的字节处继续;换上来的连接还没收到任何字节就再次被换,连续 5 次后放弃这一层。整条链路都慢时,各连接速度相当,不会被判为慢;每个窗口最多更换一半连接,不会一次全部断开。
  • 不记忆。 每次拉取从 4 条重新开始,节点不保存学到的上限。

如果仓库或代理明确只允许很少的连接,用 agent 参数 --image-pull-max-connections N(或环境变量 GPUWORKS_IMAGE_PULL_MAX_CONNECTIONS)给每个仓库 host 的连接数封顶;1 表示只用一条连接,0 或不设为自动(最多 16),最大可设 32,超出范围的参数会让 agent 拒绝启动。这是应对特殊网络的开关,日常不需要设置,见 agent 命令行。排查见镜像拉取失败。

部署页看到的预估

指定了节点(单节点手动放置或多机),或自动调度已经选出节点时,逐节点显示预估:已有、从哪个节点复制、从哪些来源拉取、模型从哪里来。拉取一栏列出全部候选,例如「将从 quay.io / swr.cn-southwest-2.myhuaweicloud.com / docker.io 拉取,按节点探测速度决定最终来源」;有来源规则的替代地址时写成「先从 harbor.corp.example 拉取,不通再从 … 中按探测速度选择」。这是按当前状态算出的预估,副本启动时会重新判断。

下载过程中各处显示当前来源:镜像页的节点行显示正在从 X 拉取或从节点 Y 同步;副本启动时的状态写作 pulling <实际拉取的地址>;模型页与部署详情的模型准备显示 从 <host> 下载(切换后附原因)或从节点 Y 复制。

同一部署的副本可能从不同来源拉到同一 tag 的不同内容(tag 被更新过,或镜像站缓存旧内容)。部署详情逐副本显示镜像 ID,与其他副本不同的标橙色提示。

权重一栏写成「将依次从 hf-mirror.com → huggingface.co 下载」(按规则算出的候选顺序)。所有候选都被规则禁止时写「无法下载:…」,原因文字建议在有该模型的节点上登记路径,或把模型放到共享存储。这样的部署调度原因是 weights_fetch_forbidden(节点只能靠下载拿到模型、又被禁止);模型页的下载接口返回 409 WEIGHTS_FETCH_FORBIDDEN。修改规则后会重新评估已有部署。

从旧版本升级

升级时自动迁移,不需要手工操作:

旧配置迁移结果
全局 URL 改写(network 设置)站点规则,对所有节点生效、允许回源、勾选「用于管理节点获取模型元数据」
节点网络覆盖里的改写站点规则,「适用节点」限定为 gpuworks.ai/node=<节点 uuid>,排在最前。旧版本里节点覆盖会整体替换全局;现在规则叠加,所以这台节点先试自己的地址,再试全局的,最后是站点本身。例如全局 hf-mirror 加某节点覆盖为内网代理,该节点的候选是 [内网代理, hf-mirror, huggingface.co]
image_registry_rewrites 里自己加的规则,以及节点网络设置里非 URL 的改写镜像规则(节点覆盖以 gpuworks.ai/node 限定);原设置含内部仓库 registry.zstack.ai 的安装会多一条 gpuworks/ → registry.zstack.ai/gpuworks/,可以改或删
全局代理一条对全部节点生效、勾选「用于管理节点出站访问」的代理条目
节点代理覆盖一条限定该节点、合并了全局值的代理条目,排在最前(这台节点仍然使用与以前完全相同的代理)
代理 URL 里内嵌的 user:pass@拆成用户名和加密保存的密码
每次下载手选的端点、代理列不再存在
「仓库凭据」改名「凭据」,原有条目归入镜像仓库一类

代理在 server 开始提供服务前结转;成功后删除旧网络设置,失败则保留并在下次启动时重试。

行为变化:

  • 设置页的「网络」卡片、节点详情的「网络覆盖」、/settings/network、network:<id>、/nodes/{uuid}/network(现返回 410)、网络预设(hf-mirror、xget 预设和 DNS 建议)都已删除,不再有任何预设。
  • 目录 URL 来源的模型以前不经代理直连,现在经节点代理下载。内网文件服务器要加入 no_proxy,否则会被送到代理上。
  • 模型下载以前对同一地址最多重试 16 次;现在有候选时按上文换地址,只有最后一个地址保留 16 次。

这篇文档有帮助吗?