构建自定义镜像

Dockerfile、不要打进镜像的东西、仓库白名单、tag 和 digest

FROM nvidia/cuda:12.4.1-devel-ubuntu22.04
RUN pip install torch transformers trl accelerate
COPY . /workspace

训练镜像里装 CUDA、Python，以及你的 train.sh 会 import 的东西。仅此而已。

不要把 StarForge CLI 装进镜像，也不要从旧的教程仓库里抄可观测性代码。 平台运行时会在启动时以内容寻址 PEX 的形式注入——镜像里不需要任何东西，回传就能工作。

​

镜像里装什么

装进去	不要装
和集群驱动匹配的 CUDA / cuDNN	sf CLI、forge-console
Python 3.10 到 3.13（runner 的 requires_python 是 >=3.10,<3.14）	.forge/ token、当成一层的 HF_TOKEN
你的训练栈（transformers、deepspeed、vLLM 等）	数据集（运行时拉取或用平台数据集）
若走 catalog 的 custom recipe（external 观测）并要 import starforge：装 starforge-core	写死的控制台 URL

日志：print、logging、框架打到 stdout/stderr 的内容进控制台日志页。不要 POST /api/ingest/logs。

曲线：不会从 stdout 里猜。训练代码里调 starforge.report。

​

一份能改的 Dockerfile

风格对齐平台 TRL 镜像：CUDA devel 基底、venv 在 PATH 最前。catalog custom/custom 建议在后面的 RUN 里装 starforge-core。

# syntax=docker/dockerfile:1
ARG BASE_IMAGE=nvidia/cuda:12.8.0-devel-ubuntu24.04
FROM ${BASE_IMAGE}

ARG PYTHON_VERSION=3.12
ENV DEBIAN_FRONTEND=noninteractive \
    HF_HUB_ENABLE_HF_TRANSFER=1

RUN apt-get update && apt-get install -y --no-install-recommends \
        git curl ca-certificates \
    && rm -rf /var/lib/apt/lists/*

COPY --from=ghcr.io/astral-sh/uv:0.8 /uv /usr/local/bin/uv

RUN uv python install ${PYTHON_VERSION} \
 && uv venv --python ${PYTHON_VERSION} /opt/train-venv
ENV VIRTUAL_ENV=/opt/train-venv PATH=/opt/train-venv/bin:$PATH

# 生产请钉版本，不要留未 pin 的 extra。
RUN uv pip install --no-cache \
        "torch" \
        "transformers" \
        "accelerate" \
        "trl" \
        "hf-transfer" \
        "starforge-core"

# Job Capsule 用镜像里的 Python。保持这个 venv 在 PATH 最前。
CMD ["python", "-c", "import torch; print(torch.__version__)"]

包名按 train.py 实际 import 来改。DeepSpeed 要运行期 JIT 的话，通常需要带 nvcc 的 devel 镜像，和 Dockerfile.trl 一样。

local 执行器会用 bash 跑入口。PATH 仍须指向那个 venv，否则 train.sh 里的 python 可能是没有 torch 的 /usr/bin/python。

​

构建和推送

docker build -t myregistry.io/my-train:v1 .
docker push myregistry.io/my-train:v1

# 记下 digest 再提交：
docker buildx imagetools inspect myregistry.io/my-train:v1

tag 或 digest 都能提交：

sf submit my-custom --profile h200:8 \
  --image myregistry.io/my-train:v1 \
  --observability-url https://wandb.example/my-proj

sf submit my-custom --profile h200:8 \
  --image myregistry.io/my-train@sha256:abcd… \
  --observability-url https://wandb.example/my-proj

​

白名单

--image 会解析出仓库主机（ghcr.io、localhost:5000、没有主机名时是 docker.io）。这个主机必须出现在服务端 FORGE_ALLOWED_IMAGE_REGISTRIES（.env 里逗号分隔的主机名）。

服务端设置	自定义 --image	一等框架的 --image 覆盖
名单为空	拒绝（「空：禁止用户镜像」）	允许（空名单不限制一等框架覆盖）
有名单，主机不在里面	拒绝，并打出当前允许的主机	同样拒绝
主机在名单里	允许	允许

运维可以写成 FORGE_ALLOWED_IMAGE_REGISTRIES=registry.example.com,ghcr.io。节点还要能拉到镜像（KubeRay 的 imagePullSecret、agent 上的 Docker login、Slurm 侧已经转好的 SIF）。

​

各执行器

执行器	镜像形态
local / agent	OCI。agent 节点需要同样的拉取凭据。第一期 agent 是一作业一节点。
kuberay	OCI + RayJob 上的 pull secret。拉得慢会停在 PENDING。
slurm	runtime 注册表通常指向 SIF/SQSH。笔记本上的 Docker tag 往往不够，运维要转换并登记 runtime_id。

拉镜像慢时作业停在 PENDING，直到 preRunning 超时变成 FAILED。这不是训练代码的问题。

​

不要做的事

• 把 StarForge 源码 COPY 进 /opt，指望它和服务器 runner 对得上。capsule 是内容寻址、启动时注入的。
• 把 HF_TOKEN 烤进镜像层。服务端会注入 HF_TOKEN / HUGGING_FACE_HUB_TOKEN，或给一个密钥文件路径（CLUSTER_SECRETS_FILE）。
• 把 FORGE_INGEST_URL 设成控制台机器上的 127.0.0.1。训练节点用不了你笔记本的 loopback。这个变量在服务端，提交的人不用设；stdout 正常但图表空，多半是运维配错了。