离线内网部署

在没有 Hugging Face、PyPI 和公共镜像仓库出口的网络里跑 StarForge。

FORGE_HF_ENDPOINT=https://mirrors.your-company.com/repository/huggingface

这一项设置就是权重下载能在镜像后面工作的原因。本页剩下的内容是另外三样会坏掉的东西，以及各自怎么办。

​

模型权重

huggingface_hub 读 HF_ENDPOINT，而平台会把 FORGE_HF_ENDPOINT 原样注入每个训练容器和 Playground 容器。把它指向一个反向代理即可——Nexus、Artifactory，或者任何能代理 Hub 的东西。

有两项调整会自动跟着一起生效，它们的存在都是因为某种极难诊断的失败：

超时被放宽

huggingface_hub 默认十秒超时。镜像第一次取一个它从未缓存过的文件时要一路回源， 这经常超过十秒。症状是冷文件下载失败、重试又成功，看起来像网络不稳定，而不像配置问题。

Xet 被关闭

Xet 需要短时效 token，而反向代理签不出来。不关的话，权重下载会卡在一个 400 上， 而那个响应体里除了一个 URL 什么都没有——没有消息、没有字段，连搜都没得搜。

如果你的镜像确实实现了 Xet，用 FORGE_PASSTHROUGH_ENV 显式覆盖。

拉不到权重的作业不会快速失败。它会启动、打印下载日志，然后一直卡到超时—— 整个过程都占着它的 GPU 分配。在向团队开放提交之前，先确认镜像是通的。

​

容器镜像

训练镜像来自 recipe catalog，而 catalog 里写的是 nvcr.io 这类公共仓库。内网里需要先转存再重定向：

设置	作用
FORGE_RUNTIME_REGISTRY_FILE	把 runtime_id 映射到你的仓库里实际存在的工件，覆盖 catalog 里的地址
FORGE_ALLOWED_IMAGE_REGISTRIES	用户用 --image 时允许的主机，设成你的内网仓库
FORGE_K8S_IMAGE_PULL_SECRET	KubeRay 下的拉取凭据

生产环境用 digest 而不是 tag。在你自己的镜像仓库里挪动的 tag，仍然是一个挪动过的 tag。

​

在镜像站后面构建镜像

Dockerfile 默认走公共上游，所以在哪都能构建。用 build 参数把它指向内网镜像站：

docker build \
  --build-arg APT_MIRROR=https://mirrors.your-company.com/repository \
  --build-arg PYPI_INDEX=https://mirrors.your-company.com/repository/pypi-group/simple/ \
  --build-arg NPM_REGISTRY=https://mirrors.your-company.com/repository/npm-group/ \
  --build-arg UV_IMAGE=mirror.your-company.com/astral-sh/uv:python3.13-trixie-slim \
  -t starforge-console:0.3.0 .

APT_MIRROR 留空就保持 Debian 自己的源——能正常访问互联网的机器上你要的就是这个。

​

平台运行时

作业侧需要 starforge 才能回传指标，而训练镜像里不会有它。

默认的 FORGE_JOB_RUNNER_MODE=bundled 不需要任何网络就解决了这件事： 服务端把一个内容寻址的 PEX 注入作业，训练镜像不需要预装任何东西。 这是少数几个「离线反而更简单」的地方——这项设置保持默认就好。

​

数据集

这里没有任何东西需要访问互联网。数据集用 sf dataset push 推进部署自己的对象存储， 作业启动时拉进共享缓存。见数据集。

​

确认成功

提交快速开始里那个作业，看日志。你要看到的顺序是：

resolving Qwen/Qwen2.5-1.5B via https://mirrors.your-company.com/repository/huggingface
downloading model-00001-of-00002.safetensors
...
Ray runtime started

卡在第一行和第二行之间是镜像的问题。响应体里只有一个裸 URL 的 400 是 Xet。 大文件在大约十秒后超时，说明放宽的超时没有生效——检查设置 HF_ENDPOINT 的是平台，而不是你自己的脚本。