跳转到正文

从 HTTP 文件服务器导入模型与镜像

本文目录

将 HTTP 文件服务器上的模型目录或 docker save 镜像归档登记到平台,再获取到节点用于部署。模型目录需提供 Apache、nginx、Caddy 等可解析的目录列表页;镜像使用归档文件的直接地址。

开始前确认:

  • 使用有 managementAdmin 权限的账号。下载或导入到节点时,目标节点须在线;下载模型还要求 agent 支持 HTTP 目录来源(过旧时见下方错误处理)。
  • URL 为不含内嵌凭据的 http / https。模型指向权重所在的目录,镜像指向归档文件。
  • server 能读取来源,用于解析。普通私网及本机回环默认无需白名单;仅当开启严格模式时才需要白名单。平台管理员可在设置 → 安全与访问 → 出站访问策略保存授权,也可由主机管理员直接编辑 server.yaml 的 outbound_restrict_private_hosts 和 outbound_allow_private_hosts。保存后下一次请求生效,无需重启 server,见出站 HTTP 代理策略。
  • 模型由目标节点下载,节点也必须能访问目录。镜像归档可由节点直连,或由能读取归档的 server 中转。

重定向最多 5 次;模型目录的每次跳转还必须留在注册时的主机上。管理节点与 agent 各自使用对应的拉取代理;内网地址需要绕过代理时,将其加入相应代理条目的 no_proxy。

从 HTTP 目录注册模型

  1. 在模型页点注册模型,来源选HTTP 目录,填写模型自身目录的地址,例如 https://models.example.internal/Qwen/Qwen3-0.6B,点解析。
  2. 核对名称、文件数和模型元数据。「目录 ID」默认取 URL 末两段,必要时改为该模型的目录 ID;它影响推理目录/模板参数预设匹配。没有匹配项仍可注册,部署时手选参数。
  3. 确认注册后,在模型页检查来源为HTTP 目录。注册只创建记录,不代表权重已到达节点。
  4. 需要提前准备权重时,点该模型的下载到…,选择目标节点或存储并开始下载;等待该目标副本就绪。也可在部署时按本地已有、同步组内复制或下载的规则获取,详见下载、缓存和节点间同步模型。

目录 URL 来源只从自己的目录下载,拉取设置里的站点规则不作用于它们;节点下载仍使用该节点的拉取代理。目录源没有 revision 概念,要保留可复现的版本,应指向发布后不再覆盖的目录。

开启严格模式时,目录地址旁可勾选自动加入该主机的白名单。点击解析或确认注册时才追加当前主机;已有名单保留,更换主机后重新勾选。特殊保留地址不能授权。此授权同时作用于管理节点的其他来源访问,注册失败不会撤销已明确保存的主机授权。

已登记模型的刷新元数据、社区仓库卡片浏览和凭据列表的测试登录也支持在当前操作处授权。只有全局开启严格模式且目标需要允许时才提供授权;限制关闭或目标已允许时,原操作直接执行,不写白名单。Hugging Face 元数据若已由浏览器读取成功,不会为管理节点额外申请来源权限。

解析结果与目录限制

解析读的是服务端的目录列表页,规则如下:

  • 平台不要求目录布局:有 config.json 时据此读出架构、精度与上下文长度;没有(例如只有 GGUF 分片)也能登记,只是这些元数据为空,权重大小按目录里的 GGUF 文件计。目录一个文件都没有、或 config.json 解析失败时报 HTTP_DIRECTORY_NOT_A_MODEL。
  • 列表页里的「目录大小」是给人看的两位有效数字(1.4G),只作参考。磁盘准入、进度与完整性校验都用 下载响应实测的字节数,下载完成后节点写一份实测清单作为完成标记,二次对账不会重下。
  • 目录地址会去掉结尾斜杠、查询参数和片段,保留主机名大小写与显式端口。解析确认粘贴的是文件地址时,会尝试回到该文件所在目录。
  • 列举是有上限的:最多 3 层子目录、合计 5000 个条目、单个列表页 8 MiB、单个列表页 30 秒超时。超出上限报 HTTP_DIRECTORY_TOO_LARGE——截断的列举会静默注册出一个缺权重的模型,所以这里宁可报错。
  • 连不上或读不出列表页报 HTTP_DIRECTORY_UNREACHABLE。

目标节点下载时报 MODEL_SOURCE_REQUIRES_NEWER_AGENT,先升级该 agent,再重试下载。

从 URL 导入镜像归档

  1. 在镜像页的社区镜像或自定义镜像标签,打开添加…镜像抽屉,找到从 URL 导入,填写 docker save 归档地址并点解析。
  2. 核对归档大小和真实镜像引用。引用与已有目录项相同时,URL 会追加到该项的获取地址并跳转过去;没有匹配项时,用解析出的第一个引用预填新镜像表单,核对后保存。
  3. 若提示无法在下载前解析(例如归档压缩过或文件服务器不支持 Range),按提示手动填写镜像引用与获取地址并保存。此时尚未核实归档内容,不能凭文件名判断 tag。
  4. 登记完成后,按下一节在目标节点导入;仅保存 URL 不会开始传输。

解析由 server 查询大小,并读取归档的部分内容取得实际引用,不下载整个归档。已知引用不匹配与无法预览是不同情况,节点导入时的处理见下节。

「获取地址」是镜像已有的字段,现在既放 registry 引用,也放归档 URL。归档 URL 只会被下载并 load, 永远不会被当成 registry 引用去 pull:节点下拉、拉取候选与拉取命令都按这条规则过滤。部署也不会自己选归档 URL 去下载:要用归档,先在镜像页的节点行导入,再部署。

节点获取方式:直连或管理节点中转

镜像详情页的节点表里,这一行的获取方式除了默认的按拉取设置拉取,还有两种 URL 相关的选择:从 URL 导入…(本次填写地址), 以及该镜像已经声明过的、按主机名命名的地址条目。两者点获取都会先打开弹窗,而不是直接开始下载。

开始前,按节点访问条件选择下载路径:

  • 直连:节点能访问归档时,由节点自己下载归档并 load。
  • 管理节点中转:节点访问不到镜像站、或只有管理节点能出网时用它。管理节点下载归档并流式推送给节点,服务端不落盘。该传输不可续传,中断后重试从头开始,进度显示已传字节数。
  1. 粘贴归档地址(选已声明的条目时会预填并自动解析一次);
  2. 点解析,服务端用 HEAD + Range 读出归档大小与归档里真实的镜像引用;
  3. 核对引用与当前镜像是否一致:已解析出引用但不包含当前镜像时,弹窗会拦截,应换成正确的归档地址;无法预览则显示警告,确认来源和内容后才继续;
  4. 使用中转时,勾选管理节点中转;
  5. 点弹窗里的拉取开始下载。

严格模式下,勾选当前主机的白名单后,点击解析或通过管理节点中转直接点击拉取,会先保存该主机授权再执行操作;中转拉取不要求先成功解析。预填地址的自动解析不会写白名单,节点直连拉取也不会因此授予管理节点权限。

弹窗里确认后,这个地址会被记录进该镜像的获取地址,于是其他节点的镜像页也能直接选它;这也是「拉取失败后 重试」仍然知道该去哪里下载的原因。

归档读不出引用(被压缩过、或镜像站不支持 Range)时不会拦截,只给一条警告:这种归档没法在下载前核对, 节点会在 load 之后把归档实际携带的 tag 记进这一行的消息里。

直连导入时,如果归档内带的 tag 与目录引用不一致,节点会把目录引用补打上去;真实 tag 记进这一行的消息里,便于事后核对。

导入完成后镜像在节点上是 present,部署时节点直接使用;实例始终以目录里的规范引用启动。

常见错误

错误码含义与处理
HTTP_DIRECTORY_UNREACHABLE目录列表页读不到:检查 server 到来源的网络、内网出站授权,并确认来源会返回目录列表
HTTP_DIRECTORY_NOT_A_MODEL目录里一个文件都没有,或 config.json 解析失败
HTTP_DIRECTORY_TOO_LARGE文件数或层级超出上限,请指向模型自身的目录
MODEL_SOURCE_REQUIRES_NEWER_AGENT目标节点 agent 过旧,先升级 agent
IMAGE_ARCHIVE_URL_INVALID归档地址不可用:必须是无内嵌凭据的 http/https
IMAGE_ARCHIVE_URL_POLICY_DENIED该主机还没被允许。普通私网默认无需允许,关闭「限制私网主机」时地址旁没有加入白名单的勾选。开启后,勾选「自动加入该主机的白名单」,点击解析或中转拉取时会把主机写入允许列表;未勾选则不写入。设置 → 安全与访问 → 出站访问策略仍可管理整份列表
IMAGE_ARCHIVE_URL_POLICY_BLOCKED该地址不能通过允许列表放行,例如保留地址、链路本地地址
IMAGE_ARCHIVE_URL_UPSTREAM_STATUS归档服务器返回了具体 HTTP 状态(如 404)。核对路径,这不是网络故障
IMAGE_ARCHIVE_URL_UNREACHABLEserver 没连上归档,检查地址、网络和 TLS;节点直连失败还需检查节点到来源的网络
IMAGE_ARCHIVE_URL_NOT_DECLARED该 URL 不在这个镜像的「获取地址」里,先把它加进去再同步

相关

这篇文档有帮助吗?