配置参考

StarForge 部署读取的每一项设置，含类型、默认值和用途。

export FORGE_DEFAULT_FLEET_KIND=kuberay
export FORGE_STORAGE_ROOT=/mnt/shared/starforge
export FORGE_WEB_JWT_SECRET=$(openssl rand -hex 32)

每一项设置都是以 FORGE_ 为前缀的环境变量。没有配置文件——一套部署完全由它的环境描述， 这也是同一个镜像能在 Docker Compose、Kubernetes 和 systemd 下工作而不需要中间转换层的原因。

本页由 scripts/gen_settings_docs.py 从 server.core.config.WebSettings 生成， 新增设置而没写说明会让 CI 失败。只要这个开关存在，它就在这一页上。

​

五个不能跳过的

其余都有可用的默认值，这五个没有。

FORGE_DEFAULT_FLEET_KIND · local | node | kuberay | slurm · 默认值: "local"

console 还没有任何 Fleet 时，用来种出默认 Fleet 的后端——只在首次启动时读一次。之后后端是 「作业落在哪个 Fleet」的属性，再注册一个 Fleet 就是给 console 添一个后端的办法。 后端之间不会静默回退，所以即使你要的就是 local 也要显式写出来。 见执行后端。

FORGE_STORAGE_ROOT · path

一套部署只配这一个路径。它必须是绝对路径，而且在控制台、每个节点、每个容器里解析结果必须完全相同。 留空表示单机开发。

FORGE_WEB_JWT_SECRET · string

不设置则每个进程随机生成，结果是重启即全员掉线，多副本部署直接不可用。 除了笔记本之外，都要设一个固定的强随机值。

FORGE_DB_URL · url

团队部署指向 Postgres。留空则使用本地 SQLite 文件——单机是对的，两台机器就不对了。

FORGE_PUBLIC_URL · url

用户访问这套部署的 https 地址。OIDC 的 redirect_uri 由它拼出，没有它单点登录无法工作。

​

怎么读下面的表

• 必填表示不配置就拒绝启动。
• 自动生成表示你不提供时会按进程派生一个值。
• 破折号表示默认值为空，而空通常意味着该功能关闭。

绝对路径在启动时校验：相对的 FORGE_STORAGE_ROOT 会被拒绝， 而不是拿进程恰好启动的那个目录去解析。

​

核心

环境变量	类型	默认值	说明
FORGE_CACHE_TTL	float	5.0	进程内缓存的保留时长，超过后重新读取。
FORGE_COOKIE_SECURE	bool	—	会话 Cookie 是否带 Secure 标志。不设置时跟随 public_url 是否为 https；本机用 http 调试时设为 false。
FORGE_DB_PATH	Path	.forge/web.db	SQLite 文件的位置，相对于控制台的工作目录。有意不放在存储根下：那个根通常是共享文件系统，而 SQLite 跑在 NFS 上有众所周知的锁问题。配了 db_url 指向 Postgres 后这一项不再使用。
FORGE_DB_URL	str	—	数据库地址。留空则回落到 db_path 指向的 SQLite。团队部署应指向 Postgres。
FORGE_HOST	str	127.0.0.1	控制台 HTTP 监听地址。CLI 的 —host 会覆盖它。
FORGE_INGEST_URL	str	—	训练进程回传日志和指标的地址。集群在远端时不要填 127.0.0.1——那是 worker 自己的回环。要填控制台在集群网络内可达的 URL。
FORGE_JWT_HOURS	int	8	access token 的有效期。
FORGE_NO_AUTH	bool	false	把所有请求都当成管理员，完全跳过认证。仅供开发；任何别人能访问到的部署都绝不能开。
FORGE_OIDC_CLIENT_ID	str	—	在身份提供方注册的 client id。
FORGE_OIDC_CLIENT_SECRET	str	—	在身份提供方注册的 client secret。
FORGE_OIDC_DEFAULT_ROLE	str	operator	SSO 新用户建号时给的角色。admin 不要填在这里——第一个管理员应当是有人明确授予的
FORGE_OIDC_DISCOVERY_URL	str	—	留空则按 issuer 拼 /.well-known/openid-configuration；Casdoor 的按应用分路径，需要显式填
FORGE_OIDC_GROUP_CLAIM	str	—	存放用户所属组的 claim，每次登录据此同步团队成员关系。留空（默认）表示平台完全不碰 团队成员——手工维护团队的部署必须留空，否则下次登录会把所有人从团队里清出去。目录里 有、平台上没有的组会被跳过，不会自动创建团队。
FORGE_OIDC_GROUP_PREFIX	str	—	每个组名在被当作团队 key 之前先去掉的前缀。目录常下发路径或 DN，而平台要的是一个 key。
FORGE_OIDC_INSECURE_SKIP_VERIFY	bool	false	跳过对身份提供方的 TLS 校验。仅用于调试内网自签证书；生产环境绝不能开。
FORGE_OIDC_ISSUER	str	—	OIDC issuer 地址，例如一个 Casdoor 应用。配置它即开启单点登录。
FORGE_OIDC_SCOPE	str	openid profile email	登录时请求的 scope。
FORGE_PORT	int	8080	控制台监听端口。CLI 的 —port 会覆盖它。
FORGE_PUBLIC_URL	str	—	用户和身份提供方访问这套部署的地址。OIDC 的 redirect_uri 由它拼出，所以团队部署必须填真实的 https 域名。
FORGE_REDIS_PREFIX	str	lab	key 命名空间，让多套环境能共用一个 Redis 而不互相干扰。
FORGE_REDIS_URL	str	—	Redis：共享缓存、分布式锁、限流、token 即时吊销。留空则四者全部关闭，控制台按单实例行为运行。
FORGE_REFRESH_DAYS	int	30	refresh token 的有效期。它只通过 httpOnly Cookie 下发，浏览器里的 JavaScript 读不到。
FORGE_REPO_ROOT	Path	自动生成	控制台读取实验定义与本地台账的项目根目录。默认取当前工作目录。
FORGE_SERVE	bool	false	绑定 0.0.0.0 而不是回环地址。团队部署或容器部署需要打开。
FORGE_STATIC_DIR	Path	—	控制台前端构建产物（web/dist）所在目录。服务端 wheel 里已经带了，通常不用改。
FORGE_WEB_JWT_SECRET	str	自动生成	access token 的签名密钥。不配置则每个进程随机生成——单机可以，多副本不行：两个副本用不同密钥签名，重启就是全员掉线。

​

代理提交

环境变量	类型	默认值	说明
FORGE_CLUSTER_PROFILE	str	—	转发给作业的 CLUSTER_PROFILE 默认值。客户端指定的 profile 只作记录，不覆盖它。
FORGE_NEMO_RL_DIR	str	—	提交 nemo-rl 作业必需，转发为作业的 NEMO_RL_DIR。这是镜像里的路径，不是宿主机也不是 CLI 项目目录

​

存储

环境变量	类型	默认值	说明
FORGE_AUDIT_RETENTION_DAYS	int	0	0 表示永久保留。清理不会破坏防篡改哈希链：每次清理都会留下一条说明删了哪个区间的记录，校验接口据此认可这段缺口，而这类说明记录本身永不删除。保留期执法属企业版
FORGE_AUDIT_RETENTION_INTERVAL_S	float	86400.0	审计保留期清理任务的执行间隔。
FORGE_CLUSTER_SECRETS_FILE	str	—	容器内密钥文件的路径。配置后只转发路径，密钥内容不会进入 Ray dashboard。
FORGE_DATA_SCAN_ALLOW_TERMS	str	—	逗号分隔的误报白名单，命中这些词的结果会被忽略。
FORGE_DATA_SCAN_DENY_TERMS	str	—	本部署额外视为敏感的词，逗号分隔，叠加在内置规则之上。只能填词，不能填正则—— 在设置框里粘一段正则，就等于让一次配置改动把后台任务挂死。
FORGE_DATA_SCAN_POLICY	str	report	数据集里发现敏感值时平台怎么做。off 不扫描；report 扫描、记录、在数据集页展示， 但照常放行；block 拒绝引用了高置信命中数据的提交。拦截只看置信度，不看是否有命中 ——低置信规则会打中代码语料里的每一段 base64 和每个 git SHA。
FORGE_INGEST_TOKEN_DAYS	int	30	作业 ingest token 的有效期。它必须长于你预期的最长训练时长，否则长作业跑到一半就再也报不上来了。
FORGE_JOB_RUNNER_MODE	str	bundled	平台运行时如何进入作业。bundled 注入一个内容寻址的 PEX，训练镜像不需要预装任何东西。image-installed 要求镜像里已装 starforge，只作为迁移回滚保留——两者之间绝不会自动回退。
FORGE_JOB_RUNNER_PATH	str	—	bundled 模式下 runner PEX 的读取位置。留空表示 <repo_root>/dist/starforge-runner.pex。
FORGE_JOB_RUNNER_PYTHON	str	—	runner 使用的解释器的部署级覆盖。留空则使用运行时产物自己声明的。
FORGE_JOB_RUNNER_REQUIRES_PYTHON	str	>=3.10,<3.14	bundled runner 支持的 Python 版本范围。训练镜像不在范围内会被直接拒绝，而不是留到后面才失败。
FORGE_LICENSE_FILE	str	—	改用文件存放授权串。授权是几百字节，没人想把它写进 Helm values 或留在 shell 历史里， 而 Kubernetes 更习惯把密钥挂成文件。两者都配时 license_key 优先。
FORGE_LICENSE_KEY	str	—	商业授权串（厂商签发的签名文档）。留空即社区版——那是受支持的配置而不是降级形态， 其中的一切都可用且不会改变。离线校验，永不回连厂商。可在管理台直接粘贴， 下一个请求即生效、无需重启——因为授权是按请求校验而不是在挂载时校验的。
FORGE_MAX_UPLOAD_MB	int	1024	提交的作业包压缩后的大小上限。解压后的上限是它的 50 倍，用来挡压缩炸弹。
FORGE_PASSTHROUGH_ENV	dict	自动生成	透传进每个作业的非密钥环境变量，例如 HF 镜像地址。
FORGE_QUEUE_POLL_INTERVAL	float	5.0	出队循环检查队列的间隔。
FORGE_QUOTA_ENFORCE	bool	true	软配额是否真的拦截准入。关掉之后只记录用量，不拒绝任何提交。
FORGE_SERVER_SECRETS_FILE	str	—	服务端的 KEY=VALUE 密钥文件；没用 cluster_secrets_file 时由它注入作业。
FORGE_STORAGE_ROOT	str	—	一套部署只配这一个路径。平台写的一切都由它派生：缓存、run 目录、作业包和控制平面状态。前提约束是这个路径在控制台、每个节点、每个容器里都完全一致——共享文件系统或同路径 bind mount 都能满足。留空表示单机开发，回落到 ./.forge/storage。
FORGE_SUBMIT_DRY_RUN	bool	false	只装配 runtime environment，不真的向 Ray 提交。调试用。
FORGE_VOLUME_ROOT	str	—	受治理的 Volume 根目录——作业可读的资料，与训练数据不同。必须位于存储根之外，启动时校验：存储根是以可写方式挂进作业容器的， Volume 若在其下就会多出一条可写路径，只读挂载形同虚设。把 JuiceFS 挂在这里、并把 S3 配置指向它的网关，同一份内容就同时有对象接口和文件系统两张面。留空表示这套部署不支持 Volume。

​

失败自动重试

环境变量	类型	默认值	说明
FORGE_AUTO_RETRY_DELAY_S	float	60.0	失败后等多久再重投，给瞬时故障留出恢复时间。
FORGE_AUTO_RETRY_ENABLED	bool	false	FAILED 训练作业自动置回队列、同 run_id 重投（NeMo-RL 自动从最新 checkpoint 续训）
FORGE_AUTO_RETRY_MAX	int	1	每个作业的自动重试次数。作业可以用自己的 max_retries 覆盖。
FORGE_AUTO_RETRY_ON	str	started	重试哪一类失败。started 只重试跑到过 RUNNING 的作业——配置或环境类错误通常在那之前就挂了，重试也是白重试。all 则任何失败都重试。

​

LLM 裁判

环境变量	类型	默认值	说明
FORGE_JUDGE_CACHE_ENABLED	bool	true	缓存确定性打分（temperature ≤ 0）的结果，同一个 prompt 不用付两次钱。
FORGE_JUDGE_ENABLED	bool	false	训练作业自动注入 STARFORGE_JUDGE_ENDPOINT/TOKEN；训练侧 reward 经平台代理调裁判模型，凭据与审计都在平台侧
FORGE_JUDGE_LLM_API_KEY	str	—	裁判上游的 API key。留空则复用 agent_llm_api_key。
FORGE_JUDGE_LLM_BASE_URL	str	—	裁判调用的 OpenAI 兼容上游。留空则复用诊断 Agent 的 LLM 配置。
FORGE_JUDGE_LLM_MODEL	str	—	裁判用来打分的模型。留空则复用 agent_llm_model。
FORGE_JUDGE_LLM_TIMEOUT	float	60.0	单次裁判调用的请求超时。

​

Agent 沙箱

环境变量	类型	默认值	说明
FORGE_ENVIRONMENT_ALLOWED_HOSTS	str	—	作业为 openenv-remote 环境可以访问的主机，逗号分隔。留空表示一个都不允许，这是有意的：训练容器通常在内网里畅通无阻，如果 manifest 写什么主机就允许什么，环境引用就变成了别人写的出网通道。
FORGE_ENVIRONMENT_SELF_REGISTRATION	bool	false	环境能否通过「证明那个地址上确实有服务在应答」来给自己的主机授权。默认关闭，因为打开它意味着把出网判断从「管理员点名了这台主机」换成「封版时这个地址上有一个 OpenEnv 服务应答过，而且我们记下了是谁申请的」——对主机的保证更弱，对审计链的保证强得多。
FORGE_REFLOW_ENABLED	bool	true	Reflow 后台任务是否运行。默认开启，但在部署把采样率设成大于零之前它什么都不做——采集是按部署开启的，从不全局开启。
FORGE_REFLOW_FLUSH_INTERVAL_S	int	60	捕获的流量从内存刷入缓冲区的间隔。
FORGE_SANDBOX_CPUS	str	1	单个沙箱容器的 CPU 上限。
FORGE_SANDBOX_ENDPOINT	str	—	设置后训练作业注入 STARFORGE_SANDBOX_ENDPOINT，环境的代码执行工具改走外部沙箱；留空 = 容器内子进程
FORGE_SANDBOX_IMAGE	str	—	平台自带代码沙箱使用的镜像。不配置就不启用——运行模型生成的代码不该默认开启，而且也没有一个可以猜的镜像。
FORGE_SANDBOX_MAX_CONCURRENCY	int	8	同时可运行的沙箱数量上限。
FORGE_SANDBOX_MEMORY	str	512m	单个沙箱容器的内存上限。
FORGE_SANDBOX_TIMEOUT_S	float	30.0	单次沙箱执行的墙钟时间上限。
FORGE_SANDBOX_TOKEN	str	—	访问该外部沙箱服务的 Bearer token。
FORGE_SANDBOX_USER	str	65534:65534	沙箱进程运行时的用户。默认是非 root；只有镜像需要另一个非特权账号时才改。

​

Playground

环境变量	类型	默认值	说明
FORGE_PLAYGROUND_ENABLED	bool	false	训练产物一键起 vLLM OpenAI 兼容服务并在 web 对话试用；仅 local 后端
FORGE_PLAYGROUND_IMAGE	str	—	如 docker.io/vllm/vllm-openai:v0.11.0@sha256:…；不 pin 不放行
FORGE_PLAYGROUND_MAX_GPUS	int	4	单个 Playground 会话的 GPU 数量上限。
FORGE_PLAYGROUND_PORT_MAX	int	18099	与长期部署的端口范围不可重叠——重叠时一个临时会话能占掉稳定端点的端口
FORGE_PLAYGROUND_PORT_MIN	int	18000	Playground 会话占用的宿主机端口范围下界，每个会话占一个。
FORGE_PLAYGROUND_TTL_S	float	3600.0	空闲会话存活多久后自动停止并释放 GPU。

​

模型部署

环境变量	类型	默认值	说明
FORGE_ALLOWED_IMAGE_REGISTRIES	str	—	用户用 sf submit --image 时允许的仓库主机，逗号分隔、精确匹配。留空时一等框架的镜像覆盖不受限，但自定义镜像完全关闭；生产部署应当显式配置。
FORGE_DEFAULT_FLEET_KIND	str	local	console 还没有任何 Fleet 时，用来种出默认 Fleet 的后端。local 是控制台主机上的一个容器，node 是远端跑着 forgelet daemon 的机器上的一个容器，kuberay 是每个作业一个临时 RayCluster，slurm 是通过 slurmrestd 拿到的独占分配。它只在首次启动时读一次——之后后端是「作业落在哪个 Fleet」的属性，注册第二个 Fleet 才是给 console 增加后端的办法，改这一项不会挪动任何已有作业。
FORGE_DEPLOYMENT_ALLOW_TRUST_REMOTE_CODE	bool	false	部署能否加载会执行其仓库内代码的模型。默认关闭，因为那等于运行模型作者写的代码。
FORGE_DEPLOYMENT_HEALTH_TIMEOUT_S	float	10.0	对服务中的 revision 做一次健康探测的超时。
FORGE_DEPLOYMENT_MAX_CONCURRENT_REQUESTS	int	0	一个部署最多允许多少个推理请求同时经控制台在途，0 表示不限。这是背压而不是配额——引擎打满之后再开更多连接也不会更快，而一个可重试的拒绝好过一个把在途请求一起拖慢的队列。
FORGE_DEPLOYMENT_MAX_GPUS	int	8	单个部署 revision 的 GPU 数量上限。
FORGE_DEPLOYMENT_PORT_MAX	int	18299	该端口范围的上界。
FORGE_DEPLOYMENT_PORT_MIN	int	18100	模型部署占用的宿主机端口范围下界。
FORGE_DEPLOYMENT_READINESS_TIMEOUT_S	float	900.0	新 revision 变为 ready 的时间上限，超时判定为失败。大模型冷加载需要这个余量。
FORGE_DEPLOYMENT_SGLANG_IMAGE	str	—	SGLang 部署使用的服务镜像。必须 digest 固定。
FORGE_DEPLOYMENT_SHARED_ROOTS	str	—	逗号分隔绝对路径；shared_path 模型只能位于这些目录或平台数据/产物根
FORGE_DEPLOYMENT_VLLM_IMAGE	str	—	如 docker.io/vllm/vllm-openai:v0.11.0@sha256:…；不 pin 不放行
FORGE_FORGELET_INDEX_URL	str	—	生成的 install.sh 从哪个包索引取 forgelet。留空表示 PyPI；内网部署应指向自己的镜像源——执行脚本的机器很可能没有公网出口。
FORGE_IMAGE_NEMO_RL	str	—	未传 —image 时所有 nemo-rl 作业用这张。基于官方镜像加工后写这里即可，不必带 digest
FORGE_IMAGE_OPENRLHF	str	—	未传 —image 时所有 openrlhf 作业用这张（平台自建镜像，见 deploy/docker/Dockerfile.openrlhf）
FORGE_IMAGE_TRL	str	—	未传 —image 时所有 trl 作业用这张
FORGE_IMAGE_VERL	str	—	未传 —image 时所有 verl 作业用这张
FORGE_INPROCESS_WORKERS	bool	true	后台角色（出队、诊断、看门狗、日报）是否在 web 进程内运行。关掉后改由独立进程承担（python -m server.worker --role <name>）：调用 LLM 的慢 tick 不再占着事件循环抬高 API 尾延迟，web 副本也变成纯无状态、可随意扩缩。默认开启，保证单容器部署行为不变。
FORGE_MODEL_DEPLOYMENTS_ENABLED	bool	false	与 Playground 临时会话分离；提供稳定内网端点、Revision、自愈与令牌
FORGE_NODE_ADDRESSES	str	—	逗号分隔的节点地址，例如 http://gpu-1:7070,http://gpu-2:7070。前提是存储根以同一路径挂载到控制台和每个节点上。
FORGE_NODE_LAUNCH_TIMEOUT_S	float	120.0	launch 请求的超时，覆盖镜像已在节点上时的起容器耗时。首次拉镜像是异步的，不占用这个超时。
FORGE_NODE_REQUEST_TIMEOUT_S	float	15.0	向 agent 发起普通请求的超时。
FORGE_NODE_STATE_DIR	str	~/.starforge-forgelet	节点保存加入 Fleet 时拿到的身份与凭证的位置。刻意不放在存储根下——看不到共享挂载的节点也必须能说明自己是谁。
FORGE_NODE_TOKEN	str	—	控制台与所有 agent 之间共享的 Bearer token。两侧都必须配置；缺失会拒绝启动，而不是无鉴权运行。
FORGE_RUNTIME_REGISTRY_FILE	str	—	部署级的 runtime_id → 执行工件映射。Slurm 下必填（需要 SIF 或 SQSH）。local 和 kuberay 下可选，登记后会覆盖 catalog 里的镜像地址——内网自建镜像就是这样接进来的。
FORGE_SLURM_RUNTIME_PROFILE	str	—	Slurm 使用哪种容器运行时。必须显式选择；不做自动探测，也不在 profile 之间回退。

​

Slurm 执行器

环境变量	类型	默认值	说明
FORGE_SLURM_ACCOUNT	str	—	作业计费所记的 account。
FORGE_SLURM_CLUSTER_WAIT_TIMEOUT_S	int	1800	等待分配内所有节点加入 Ray 集群的时间上限，超时即放弃。
FORGE_SLURM_CPUS_PER_NODE	int	1	每个节点申请的 CPU 数。
FORGE_SLURM_JWT_FILE	str	—	存放 slurmrestd 认证所用 JWT 的文件。
FORGE_SLURM_PARTITION	str	—	作业提交到哪个 partition。
FORGE_SLURM_QOS	str	—	作业申请的 QoS。
FORGE_SLURM_RAY_PORT	int	1200	分配内 Ray head 监听的端口。
FORGE_SLURM_REST_API_VERSION	str	v0.0.43	这套部署使用的 slurmrestd API 版本。
FORGE_SLURM_REST_URL	str	—	slurmrestd 的地址。控制平面固定走 REST，不提供 sbatch 或 SSH 回退。
FORGE_SLURM_REST_USER	str	—	控制平面向 slurmrestd 认证时使用的用户名。
FORGE_SLURM_STORAGE_ROOT	str	—	存储根在集群并行文件系统上的路径。留空表示与 storage_root 完全相同的绝对路径——这是常态。
FORGE_SLURM_TIMEOUT	float	30.0	单次 slurmrestd 请求的超时。
FORGE_SLURM_TIME_LIMIT	str	24:00:00	每次资源分配申请的墙钟时间上限。
FORGE_SLURM_TLS_VERIFY	bool	true	是否校验 slurmrestd 的 TLS 证书。调试之外都应保持开启。
FORGE_SLURM_WORKER_PORT_MAX	int	2999	该端口范围的上界。
FORGE_SLURM_WORKER_PORT_MIN	int	2000	Ray worker 使用的端口范围下界。

​

KubeRay 执行器

环境变量	类型	默认值	说明
FORGE_K8S_API_SERVER	str	—	Kubernetes API server 地址。解析顺序是显式配置 → 集群内 ServiceAccount → 不可用。控制台通常就跑在集群里，所以一般留空。
FORGE_K8S_CA_PATH	str	—	校验 Kubernetes API server 所用的 CA 证书路径。
FORGE_K8S_CPU_LIMIT	str	—	训练 Pod 的 CPU 上限。留空表示不限，由节点容量决定。
FORGE_K8S_GPU_NODE_LABEL	str	starforge/gpu-series	标记 GPU 卡型的节点标签，Kubernetes 调度器据此原生地把作业放到正确的硬件上。
FORGE_K8S_GPU_PASSTHROUGH	bool	true	Pod 是否真的申请 nvidia.com/gpu。False 是仿真模式，给没有 GPU 的集群用（kind、OrbStack、CI）：Ray 的逻辑 num-gpus 照常工作，平台自己的闭环测试就能跑。
FORGE_K8S_IMAGE_PULL_POLICY	str	IfNotPresent	训练 Pod 的镜像拉取策略。
FORGE_K8S_IMAGE_PULL_SECRET	str	—	内网镜像仓库的拉取凭据。
FORGE_K8S_INSECURE_SKIP_VERIFY	bool	false	跳过对 Kubernetes API 的 TLS 校验。仅用于调试自签证书。
FORGE_K8S_MEMORY_LIMIT	str	—	训练 Pod 的内存上限。留空表示不限。
FORGE_K8S_NAMESPACE	str	—	创建训练资源的命名空间。留空则使用 ServiceAccount 所在的命名空间。
FORGE_K8S_NCCL_SOCKET_IFNAME	str	—	NCCL 走哪块网卡。多网卡机器上不指定的话 NCCL 会挑错网卡，表现为「训练能起来但慢得离谱」或者直接卡在 all-reduce，极难定位。常见值是 bond0、eth0、ib0。
FORGE_K8S_SERVICE_ACCOUNT	str	—	训练 Pod 使用的 ServiceAccount，用于它们自己需要访问集群资源的场景。
FORGE_K8S_SHM_SIZE	str	64Gi	训练 Pod 内 /dev/shm 的大小。Ray 的 object store 就在那里，而容器默认的 64MB 会让稍大一点的 batch 立刻 OOM。
FORGE_K8S_STORAGE_MOUNT	str	—	该 PVC 在 Pod 内的挂载路径。留空表示与 storage_root 相同的绝对路径，这样控制台和容器默认就一致。
FORGE_K8S_STORAGE_PVC	str	—	承载存储根的 PVC。没有它，每个作业都要重新下载几十 GB 的权重——在内网链路上这比训练本身还贵。
FORGE_K8S_STORAGE_SHARED	bool	true	该 PVC 是否能被同一作业的所有 Pod 同时读写。RWO 的 claim 不会让多节点作业直接失败——它给每个 Pod 各自一个卷，于是 checkpoint 分片散落在不同节点上，这次 run 再也续不了。这里声明的值会与实际 PVC 核对。
FORGE_K8S_TIMEOUT	float	30.0	单次 Kubernetes API 请求的超时。
FORGE_K8S_TOKEN	str	—	访问 Kubernetes API 的 Bearer token，不用集群内 ServiceAccount 时才需要。
FORGE_K8S_VOLUME_PVC	str	—	承载Volume根的第二个 PVC，只读挂载。留空表示这套部署在 KubeRay 上无法满足Volume引用，申请了Volume的作业会在准入时被拒。
FORGE_KUBERAY_ACTIVE_DEADLINE_S	int	0	运行中作业的墙钟上限，避免跑飞的作业无限占卡。0 表示不限。
FORGE_KUBERAY_HEAD_MODE	str	colocated	Ray head 是否同时充当第一个 GPU 计算节点。colocated 与 NeMo-RL 和 KubeRay 官方形态一致。专用的无 GPU head 会改变资源分配形状，不会被隐式切换。
FORGE_KUBERAY_PRERUNNING_DEADLINE_S	int	1800	作业迟迟跑不起来多久后判定失败。没有它的话，拉不到镜像或者没有满足 nodeSelector 的节点会让作业无限期 Pending，同时一直占着队列位置。0 表示不限。
FORGE_KUBERAY_RAY_VERSION	str	2.55.1	声明给 KubeRay 的 Ray 版本。它必须与训练镜像里的 Ray 一致。不一致的症状是「集群起来了但 worker 注册不上」，而唯一的线索是一行很容易被淹没的版本警告。
FORGE_KUBERAY_SUBMISSION_MODE	str	K8sJobMode	作业的提交模式。K8sJobMode 另起一个 submitter Pod；SidecarMode 把提交容器注进 head Pod，少一个 Pod、少一次调度，代价是不支持 submitterPodTemplate。
FORGE_KUBERAY_TTL_SECONDS	int	600	Kubernetes 垃圾回收的兜底。正常终态由平台在归档日志后立即清理；这个 TTL 只负责收拾控制平面没能删掉的残留。

​

本地执行器

环境变量	类型	默认值	说明
FORGE_DISK_WATERMARK_PCT	int	90	存储根使用率达到此值后暂停所有人出队，保护在跑作业的 checkpoint 写入。0 = 关闭。与存储配额管的不是一回事：配额是「谁占得太多」，水位线是「盘要满了」
FORGE_LOCAL_CHECK_EXTERNAL_GPUS	bool	true	是否检测平台之外占卡的进程——比如有人 ssh 上去开了个 notebook。在没有 device plugin 兜底的情况下这一步很值：否则平台会把已经被占用的卡再分出去。
FORGE_LOCAL_CHECK_GPU_HEALTH	bool	true	是否用 nvidia-smi 做 GPU 健康检查：ECC 待退页、未纠正错误、硬件降频。异常卡会停止分配，容量视图里会说明原因。这类故障不会报错，只会产出坏结果或者悄悄变慢。
FORGE_LOCAL_CLI_TIMEOUT	float	60.0	单次 docker / podman CLI 调用的超时。
FORGE_LOCAL_CONTAINER_TTL_S	int	600	孤儿容器的清理兜底。正常终态会先归档日志再立即删除；这个 TTL 只负责对账遗漏的残留。
FORGE_LOCAL_CPU_LIMIT	str	—	传给 --cpus。留空表示不限。
FORGE_LOCAL_GPU_COUNT	int	0	物理 GPU 数量。0 表示用 nvidia-smi 探测；控制台跑在探测不到的容器里时需要显式指定。
FORGE_LOCAL_GPU_PASSTHROUGH	bool	true	容器是否真的拿到 GPU。False 是仿真模式：分配、记账、标签一切照常，但容器不带 --gpus——平台的闭环测试就是这样在没有 NVIDIA 运行时的机器上跑的。生产必须保持开启。
FORGE_LOCAL_IMAGE_PULL_TIMEOUT_S	float	3600.0	首次用某个新镜像启动前，显式 pull 的超时。训练镜像动辄几十 GB，不能挤在 60 秒的 CLI 超时里——那会让「第一次用新镜像」必然失败。
FORGE_LOCAL_MEMORY_LIMIT	str	—	传给 --memory。留空表示不限。
FORGE_LOCAL_NETWORK	str	host	容器网络模式。host 网络最省事：作业要回连控制台上报状态和产物，而单机场景下也没有什么需要隔离的。
FORGE_LOCAL_RUNTIME	str	auto	容器运行时。auto 依次探测 docker、podman，最后回落到裸进程。裸进程模式没有任何隔离，还可能残留显存，只建议开发机使用——而隔离正是容器化要解决的问题。
FORGE_LOCAL_SHM_SIZE	str	—	训练容器内 /dev/shm 的大小。留空则沿用 k8s_shm_size。它由内存支撑，所以它加上内存上限不能超过物理内存。
FORGE_LOCAL_STOP_TIMEOUT	int	30	停止作业时，SIGTERM 之后留多少秒让它保存 checkpoint，超时才 SIGKILL。
FORGE_REGISTRY_RECONCILE_INTERVAL_S	float	300.0	多久从对象存储重建一次数据集和语料的投影。写路径已经直接 upsert，所以它是兜底；但它同时也是唯一能修复「绕过 API 改动过的条目」的机制。0 表示关闭。
FORGE_STORAGE_SCAN_INTERVAL_S	float	600.0	多久遍历一次存储根，统计每个用户的用量和平台总量。0 表示从不遍历，此时存储配额和看板卡片会显示「未统计」。大目录树上一次完整遍历要几分钟，所以它是后台角色而不是请求时现算。
FORGE_TERMINAL_CLEANUP_GRACE_S	float	2.0	收到 lifecycle 响应后再等多久才清理，让训练进程把最后的 stderr 写完。
FORGE_TERMINAL_LOG_TAIL_LINES	int	5000	训练侧来不及上报时，从容器、Pod 或 Slurm 归档里回捞的日志尾部行数。

​

对象存储

环境变量	类型	默认值	说明
FORGE_ALLOWED_RECIPES	str	—	这套部署开放哪些后训练方法，写成 <framework>/<method>，逗号分隔。留空表示 catalog 里的全部启用。catalog 说的是「平台支持哪些方法」，这里说的是「本部署对用户开放哪些」——显存不够跑蒸馏的集群在这里关掉它，而不是去改 catalog。
FORGE_HWCONFIG_REFRESH_INTERVAL	float	15.0	每个副本重新加载硬件 profile 配置的间隔。
FORGE_RECIPE_STRICT_PARAMS	bool	true	提交时是否拒绝 recipe 未声明的超参键。默认开启——一个被静默忽略的拼错的参数名，会让用户以为自己调了参。
FORGE_S3_ACCESS_KEY	str	—	该端点的 access key，只存在于服务端。
FORGE_S3_BUCKET	str	starforge	所有内容写入的 bucket。
FORGE_S3_ENDPOINT	str	—	作业包、产物、数据集和归档使用的 S3 兼容端点。凭据只留在服务端：客户端和作业侧一律只拿预签名 URL，限定单个方法、单个 key，并带过期时间。这样凭据不会进入 Ray dashboard、容器环境变量或作业日志，泄露一个 URL 的爆炸半径是「一个 key 加一段有效期」，而不是整个 bucket。不配置则对象存储关闭，全部回落到共享盘路径。
FORGE_S3_JOB_PRESIGN_TTL	int	259200	交给作业的预签名 URL 的有效期——代码包，或者 --init-from 的产物。它必须覆盖排队加拉取的全程：排几小时队是常态，而排队期间就过期的 URL 会让作业在第一步就失败。
FORGE_S3_PRESIGN_TTL	int	3600	普通预签名 URL 的有效期。
FORGE_S3_REGION	str	us-east-1	传给 S3 客户端的 region。
FORGE_S3_SECRET_KEY	str	—	该端点的 secret key，只存在于服务端。
FORGE_S3_SIGNATURE_VERSION	str	s3v4	签名版本。除非端点太老，否则保持 s3v4。
FORGE_TIMEZONE	str	Asia/Shanghai	整个服务使用的 IANA 时区名。时段窗口和每日 GPU-时的边界都按它计算。

​

时段窗口

环境变量	类型	默认值	说明
FORGE_ARGILLA_API_KEY	str	—	该 Argilla 实例的 API key。
FORGE_ARGILLA_URL	str	—	人工偏好标注使用的 Argilla 实例。它的地址是部署级设置，信任级别与数据库、对象存储相同——内网部署里它本来就在私网上，所以不做 webhook 那套私网拦截。
FORGE_ARGILLA_WORKSPACE	str	argilla	创建标注数据集所用的 Argilla workspace。
FORGE_FAIRSHARE_WINDOW_H	float	24.0	公平调度回溯多长时间。太短，刚跑完大作业的人立刻又排到前面；太长，几周前的用量还在压着今天的人。
FORGE_SCHEDULE_DISPATCH_MIN_REMAINING_S	float	1800.0	窗口剩余时间少于这个值时不再放行作业。
FORGE_SCHEDULE_ENFORCE	bool	false	时段窗口是否真的拦截作业。关闭时只按配置展示，不拒绝任何东西。
FORGE_SCHEDULE_STOP_GRACE_S	float	600.0	窗口关闭后，强制停止运行中作业前的宽限时间。
FORGE_SCHED_POLICY	str	priority-fifo	出队排序策略。priority-fifo 是优先级降序加先到先得。fair-share 在同优先级内，让近期用得少的人排前面。单个团队感觉不到差别；多个团队共用一个集群时会很明显，因为先到先得允许一个人在额度内连提二十个作业把队列占满——那会立刻变成人际问题，并且被归咎于平台。
FORGE_SCHED_PREEMPTION	bool	false	让团队配额从「上限」变成「保底」。集群有空时团队可超额运行，超出部分在别的团队 低于其保底额度并排队时被回收——暂停并自动从最近 checkpoint 续跑。默认关闭，此时 团队配额是硬上限，什么都不会被回收。借用与回收是同一个开关：只借不收会让一个团队 无限期占住集群。
FORGE_SCHED_PREEMPT_MIN_RUNTIME_S	float	600.0	作业启动后多久才可能被回收。没有这个下限，繁忙队列会回收一个、放行一个、再回收一个， 集群一天都在写 checkpoint。
FORGE_SCHED_RESERVE_AFTER_S	float	900.0	作业因容量不足被拒多久之后，调度器开始为它预留卡。没有预留，队列会饿死大作业，而制造这个饿死流的正是平台自己：lifecycle 作业和 Playground 会话各占一张卡，于是一个四卡作业被跳过，排在它后面的一卡作业抢走刚释放的容量——每一轮都如此，永远如此。控制台上显示成「等待容量」，无限期。预留的代价是在凑齐之前有卡闲置，所以它只对已经饿了这么久的作业生效。0 表示不预留。
FORGE_SWEEP_EARLY_STOP_ENABLED	bool	true	sweep 早停的部署级急停开关。早停本身由客户端按每次 sweep 配置，这个开关存在的唯一理由是：早停会主动杀作业，必须留一个不改任何 sweep 就能全局关掉它的地方。

​

维护模式

环境变量	类型	默认值	说明
FORGE_MAINTENANCE_MODE	bool	false	打开后，新提交一律入队但不下发，已排空的作业保持 PAUSED 并标记自动恢复。关闭即自动恢复：队列 worker 会按原 run id 重新提交每个暂停的作业，从 checkpoint 续训。
FORGE_MAINTENANCE_NOTE	str	—	回显给被拦下的提交者，例如「升级 Ray 镜像至 0.7.0-20260805，预计 30 分钟」

​

运行时看门狗

环境变量	类型	默认值	说明
FORGE_MCP_ENABLED	bool	true	是否挂载 MCP 服务，向 AI agent 暴露作业配置、指标和日志。
FORGE_MCP_TOKEN_DAYS	int	30	MCP OAuth access token 的有效期。
FORGE_ONBOARDING_CARD	bool	true	概览页是否显示新手引导卡，指引新用户安装 CLI、登录并提交第一个作业。有作业后会自动隐藏。
FORGE_PREMIUM_PUBLIC	bool	false	AI 诊断、Ask Agent 和 MCP 接入是否对所有登录用户开放，而不是仅限管理员。
FORGE_WATCHDOG_CLUSTER_RECONCILE	bool	true	是否做集群级的 Ray 用卡与台账对账。这项检查不依赖客户端上报的任何东西，是三者中最可靠的一项。
FORGE_WATCHDOG_CLUSTER_TOLERANCE	int	0	集群级对账的容差（张）。
FORGE_WATCHDOG_ENABLED	bool	true	运行时看门狗是否启用。裸金属 Ray 没有 cgroup 或 GPU 硬隔离，准入只是作业启动前的软闸；看门狗周期性地把集群实际用卡与台账记账对账，不符则告警并留审计，还可以停掉能可靠归因的超额作业。它是纵深防御的一层——硬配额需要 Kubernetes 或 Kueue 一类的基础设施。
FORGE_WATCHDOG_ENFORCE	bool	false	看门狗判定为可靠超额时，是否真的停止作业，还是只告警。
FORGE_WATCHDOG_FATAL_HANG_S	float	90.0	日志末尾已是 WorkerProc/Actor 崩溃且持续无新输出时，自动标 FAILED 并停止；0 关闭
FORGE_WATCHDOG_GPU_MIN_MEM_MIB	float	2048.0	一张卡上占用多少显存才算「本作业在用」。用它排除空闲卡——空闲卡也会报大约 0.6 GB 的残留上下文——避免把整机的空闲卡误算成超额。
FORGE_WATCHDOG_GPU_TOLERANCE	int	0	单个作业实际用卡超出记账多少张才算超额。
FORGE_WATCHDOG_INTERVAL	float	120.0	看门狗巡检的间隔。
FORGE_WATCHDOG_SILENCE_ALERT_S	float	1800.0	一个活跃且记账大于零的作业持续多久没有遥测就告警——通常意味着采集被关掉了，或者作业卡死了。
FORGE_WATCHDOG_STARTUP_GRACE_S	float	300.0	作业进入 RUNNING 后多久内不做判定，避开启动和预热期的抖动。
FORGE_WATCHDOG_TELEMETRY_WINDOW_S	float	300.0	遥测数据多新才算「当前」。

​

诊断 Agent

环境变量	类型	默认值	说明
FORGE_AGENT_COMPARE_MAX_TURNS	int	6	对比助手最多可以调用多少轮工具。
FORGE_AGENT_DIAGNOSE_ON_FAIL	bool	true	作业失败时是否立即触发一次诊断。
FORGE_AGENT_DIAGNOSE_RUNNING	bool	true	是否在作业运行期间就诊断，而不只是在它结束之后。
FORGE_AGENT_DIAGNOSIS_COOLDOWN	int	900	同一个作业两次诊断之间的最小间隔。
FORGE_AGENT_DIAGNOSIS_INTERVAL	float	300.0	多久考察一次运行中的作业是否需要诊断。
FORGE_AGENT_DIAGNOSIS_MAX_TURNS	int	8	诊断 Agent 在必须给出结论前，最多可以调用多少轮工具。
FORGE_AGENT_ENABLED	bool	true	诊断 Agent 是否启用。
FORGE_AGENT_LLM_API_KEY	str	—	该端点的 API key。
FORGE_AGENT_LLM_BASE_URL	str	https://api.openai.com/v1	诊断 Agent 调用的 OpenAI 兼容端点，例如 https://api.openai.com/v1。
FORGE_AGENT_LLM_MODEL	str	gpt-4o-mini	诊断 Agent 使用的模型。默认取轻量模型以降低成本，但多步诊断推理对模型能力很敏感，生产建议用更强的。
FORGE_AGENT_LLM_TEMPERATURE	float	0.3	设为负数则不下发 temperature；部分推理/新模型（o 系、gpt-5 类、部分 Azure）只接受默认温度，硬编码会报 400
FORGE_AGENT_LLM_TIMEOUT	float	60.0	单次 LLM 调用的超时。

​

密钥与集成

环境变量	类型	默认值	说明
FORGE_HF_ENDPOINT	str	—	训练容器和 Playground 容器使用的 Hub API 镜像，huggingface_hub 通过 HF_ENDPOINT 读取。离线部署能拉到权重全靠它——见离线内网部署。
FORGE_HF_OAUTH_BASE_URL	str	https://huggingface.co	Hugging Face 的基础地址。只有对接企业版 Hub 时才需要改。
FORGE_HF_OAUTH_CLIENT_ID	str	—	Hugging Face OAuth 应用的 client id。
FORGE_HF_OAUTH_CLIENT_SECRET	str	—	该应用的 client secret。
FORGE_HF_OAUTH_ENABLED	bool	false	用户能否关联 Hugging Face 账号——作业读取受限模型或推送导出结果都需要它。
FORGE_HF_OAUTH_SCOPES	str	openid profile email read-repos gated-repos	用户关联账号时请求的 scope。
FORGE_HF_OAUTH_WRITE_ENABLED	bool	false	关联账号时是否可以申请写权限。默认关闭，让「什么都不会被上传」成为安全的默认值。
FORGE_HF_PREFLIGHT_ENABLED	bool	true	提交时是否预先检查作业引用的 Hub 资源可达且已授权。仅在启用 Hugging Face 集成时生效。
FORGE_SECRET_ENC_KEY	str	—	加密静态存储密钥所用的 Fernet 密钥。启用 Hugging Face 集成后必填——没有隐式兜底，因为一个悄悄未加密的密钥库比拒绝启动糟糕得多。

​

Webhook 渠道

环境变量	类型	默认值	说明
FORGE_DAILY_REPORT_AGENT_MAX_TURNS	int	6	源码分析 Agent 最多可以调用多少轮工具。
FORGE_DAILY_REPORT_DEEP_ANALYSIS	bool	false	开启后 Agent 会读取作业工作目录源码识别新方法/新技术；需已配置诊断 Agent 的 LLM，成本较高
FORGE_DAILY_REPORT_DEEP_ANALYSIS_MAX	int	3	控成本：仅对最可能引入新方法/有调整的少数项目跑源码分析
FORGE_DAILY_REPORT_ENABLED	bool	false	是否生成并发送每日的后训练进展汇总。
FORGE_DAILY_REPORT_KEEP_DAYS	int	90	钉钉里只发摘要+链接，完整日报存在服务端；超过保留天数的旧链接会失效
FORGE_DAILY_REPORT_PROMPT	str	—	留空使用内置默认提示词；可自定义汇报口吻与关注点（面向领导的进展/提升/待改进）
FORGE_DAILY_REPORT_SECRET	str	—	该专用 Webhook 的加签密钥。留空则回落到钉钉的加签密钥。
FORGE_DAILY_REPORT_TIME	str	09:00	日报发送时刻，HH:MM，按服务时区。
FORGE_DAILY_REPORT_WEBHOOK_URL	str	—	日报专用的 Webhook。留空则回落到钉钉 Webhook。
FORGE_DAILY_REPORT_WEEKDAYS_ONLY	bool	true	开启则仅周一至周五发送（汇总前一自然日）
FORGE_DINGTALK_AT_ALL	bool	false	推送时是否 @所有人。
FORGE_DINGTALK_AT_MOBILES	str	—	推送时 @ 指定成员（需其手机号）；多个用逗号分隔
FORGE_DINGTALK_ENABLED	bool	false	钉钉推送是否启用。关闭后站内消息镜像和日报都不推送。
FORGE_DINGTALK_NOTIFY_SITE_MESSAGES	bool	false	系统站内通知产生时，按下方级别镜像推送到钉钉群
FORGE_DINGTALK_SECRET	str	—	机器人安全设置选「加签」时填写；选「自定义关键词」则留空
FORGE_DINGTALK_SITE_MESSAGE_KINDS	str	error,warning	逗号分隔：error|warning|success|info；避免刷屏建议只推 error,warning
FORGE_DINGTALK_WEBHOOK_URL	str	—	钉钉群「智能群助手」添加自定义机器人后的 Webhook 地址（含 access_token）
FORGE_WEBHOOK_ALLOWED_HOSTS	str	—	出站主机白名单，逗号分隔。留空表示禁止一切 webhook，这是有意的：控制台通常能访问内网，允许任意出站目标等于把它变成一台内网扫描器。
FORGE_WEBHOOK_DAILY_REPORT_URL	str	—	日报的独立目标。留空则回落到主目标。
FORGE_WEBHOOK_ENABLED	bool	false	通用 webhook 渠道是否启用。控制台只按模板发一个 HTTP 请求——本来要进控制台进程的扩展改走进程边界，而不是做成插件。
FORGE_WEBHOOK_NOTIFY_SITE_MESSAGES	bool	false	站内通知是否镜像推送到 webhook。
FORGE_WEBHOOK_SITE_MESSAGE_KINDS	str	—	镜像推送哪些级别的通知，逗号分隔。留空表示全部。
FORGE_WEBHOOK_TEMPLATE	str	—	请求体的 JSON 模板，占位符是 {{title}} 和 {{text}}。留空则使用通用形状。
FORGE_WEBHOOK_URL	str	—	主 webhook 目标，用于站内消息镜像，并作为日报的兜底目标。