> ## Documentation Index
> Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置参考

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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 下工作而不需要中间转换层的原因。

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

## 五个不能跳过的

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

<ParamField path="FORGE_DEFAULT_FLEET_KIND" type="local | node | kuberay | slurm" default="local">
  console 还没有任何 Fleet 时，用来种出默认 Fleet 的后端——只在首次启动时读一次。之后后端是
  「作业落在哪个 Fleet」的属性，再注册一个 Fleet 就是给 console 添一个后端的办法。
  后端之间不会静默回退，所以即使你要的就是 `local` 也要显式写出来。
  见[执行后端](/zh-Hans/ops/overview)。
</ParamField>

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

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

<ParamField path="FORGE_DB_URL" type="url">
  团队部署指向 Postgres。留空则使用本地 SQLite 文件——单机是对的，两台机器就不对了。
</ParamField>

<ParamField path="FORGE_PUBLIC_URL" type="url">
  用户访问这套部署的 https 地址。OIDC 的 redirect\_uri 由它拼出，没有它单点登录无法工作。
</ParamField>

## 怎么读下面的表

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

绝对路径在启动时校验：相对的 `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_GITHUB_ALLOWED_ORGS`       | `str`   | —                      | 逗号分隔的组织 login，只有这些组织的成员可以登录。留空表示任意 GitHub 账号都能在此建号。填了它会额外请求 `read:org` 授权；成员身份设为私密且未授权共享的用户会被拒绝。                                      |
| `FORGE_GITHUB_CLIENT_ID`          | `str`   | —                      | GitHub OAuth App 的 Client ID。它和 Secret 都填好后，登录页立刻出现「使用 GitHub 登录」按钮，无需重启。回调地址填 `&lt;对外地址&gt;/api/auth/social/github/callback`。        |
| `FORGE_GITHUB_CLIENT_SECRET`      | `str`   | —                      | GitHub OAuth App 的 Client Secret。加密落库，接口永不回显。                                                                                         |
| `FORGE_GOOGLE_ALLOWED_DOMAINS`    | `str`   | —                      | 逗号分隔的邮箱域名，只有这些域名可以用 Google 登录。留空表示任意 Google 账号都能在此建号——如果控制台可从公网访问，那等同于开放注册。已验证的邮箱域名与 Workspace 的 `hd` 声明都算数。                          |
| `FORGE_GOOGLE_CLIENT_ID`          | `str`   | —                      | Google Cloud 控制台里的 OAuth Client ID。它和 Secret 都填好后，登录页立刻出现「使用 Google 登录」按钮，无需重启。重定向地址填 `&lt;对外地址&gt;/api/auth/social/google/callback`。 |
| `FORGE_GOOGLE_CLIENT_SECRET`      | `str`   | —                      | Google Cloud 控制台里的 OAuth Client Secret。加密落库，接口永不回显。                                                                                   |
| `FORGE_GOOGLE_ONE_TAP`            | `bool`  | `false`                | 在登录页展示 Google One Tap 提示，用浏览器里已登录的账号一键登录。默认关闭，因为这个提示是不请自来的。需要先填好 Google 的 Client ID 与 Secret。                                         |
| `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 &lt;name&gt;`）：调用 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`      | 0 = 用 nvidia-smi 探测。容器化 console 请显式给：探测依赖宿主 NVIDIA Container Toolkit 注入，注入失败时会当成 0 张卡           |
| `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`   | —               | 这套部署开放哪些后训练方法，写成 `&lt;framework&gt;/&lt;method&gt;`，逗号分隔。留空表示 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` 读取。离线部署能拉到权重全靠它——见[离线内网部署](/zh-Hans/ops/airgapped)。 |
| `FORGE_HF_LOGIN_ENABLED`       | `bool` | `false`                                       | 在登录页提供「使用 Hugging Face 登录」。与下面的 Hugging Face 账号绑定是两回事——绑定是让已登录用户拉取受限仓库，两者共用同一个 OAuth 应用。登录只申请身份类 scope。                 |
| `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 目标，用于站内消息镜像，并作为日报的兜底目标。                                     |