> ## 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.

# 环境要求

> 安装之前需要准备什么——从一台 GPU 机器到一个受集中治理的集群。

StarForge 的设计目标是在一台 GPU 服务器上和在受集中治理的多节点集群上都能工作，
而不是为两者各出一个产品。两者之间变的只是「下面这些东西你真正需要哪几样」。

## 无论如何都需要

| 东西               | 说明                                                 |
| ---------------- | -------------------------------------------------- |
| Python 3.12–3.13 | 控制平面和 CLI 都要                                       |
| 一个容器运行时          | Docker 或 Podman。裸进程模式是给开发用的，没有任何隔离                 |
| 存储               | 一个控制台和每个节点看到完全一致的路径——见[存储布局](/zh-Hans/ops/storage) |
| 至少一张 GPU         | 除了平台自己那套跑在仿真模式下的测试之外                               |

## 团队部署还需要

| 东西                             | 为什么                                             |
| ------------------------------ | ----------------------------------------------- |
| **Postgres**                   | SQLite 是单写。两个控制台副本争抢同一个文件不叫部署                   |
| **Redis**                      | 共享缓存、分布式锁、限流、token 即时吊销。没有它，后台任务会停掉，而不是跨副本不安全地跑 |
| **S3 兼容对象存储**                  | 作业包、产物、数据集、归档。没有它这些全部回落到共享盘路径                   |
| **固定的 `FORGE_WEB_JWT_SECRET`** | 否则每次重启都换一把密钥，全员掉线                               |
| **一个 https 域名**                | `FORGE_PUBLIC_URL`。没有它单点登录无法工作                  |

<Warning>
  控制台副本多于一个又没有 Redis 的部署，后台角色是被禁用的——存储记账、诊断、
  每日日报和看门狗根本不会运行。[定时任务页](/zh-Hans/console/admin-tasks)有横幅提示，
  但很容易被忽略。
</Warning>

## 按执行器分

<Tabs>
  <Tab title="local">
    一台机器。Docker 或 Podman，真正的 GPU 直通还需要 NVIDIA 容器运行时。别的都不需要。
    即使是团队，这也是正确的起点——之后换执行器是改一项设置，不是一次迁移。
  </Tab>

  <Tab title="agent">
    多台裸机，每台跑一个 `forgelet`。要求存储根以同一路径挂载到控制台和每个节点，
    并且两侧都持有同一个 Bearer token。缺 token 会拒绝启动，而不是无鉴权运行。
  </Tab>

  <Tab title="kuberay">
    一个装了 KubeRay operator 的 Kubernetes 集群、一个 GPU device plugin，
    以及一个承载存储根的 RWX PVC。RWO 的 claim 不会直接失败——
    它给每个 Pod 各自一个卷，于是 checkpoint 分片散落在不同节点上，这次 run 再也续不了。
  </Tab>

  <Tab title="slurm">
    能通过 REST 访问的 `slurmrestd`，带 JWT。控制平面绝不回退到 `sbatch` 或 SSH。
    容器镜像必须通过 `FORGE_RUNTIME_REGISTRY_FILE` 以 SIF 或 SQSH 提供，
    容器运行时 profile 必须显式选择。
  </Tab>
</Tabs>

## 网络

| 方向          | 用于                                                                      |
| ----------- | ----------------------------------------------------------------------- |
| 用户 → 控制台    | Web 控制台和 API                                                            |
| 集群 → 控制台    | Ingest。训练要回传日志和指标，所以 `FORGE_INGEST_URL` 必须**从集群内部**可达——绝不能是 `127.0.0.1` |
| 控制台 → 执行器   | Kubernetes API、slurmrestd，或 agent 节点                                    |
| 集群 → 镜像仓库   | 拉训练镜像                                                                   |
| 集群 → 模型 hub | 拉权重，或走内网镜像——见[离线内网](/zh-Hans/ops/airgapped)                             |

第二行是最容易被忽略的。用户能访问到的控制台，不等于 worker 节点也能访问到。

## 可选项，以及缺了各自会失去什么

| 缺什么                | 后果                                     |
| ------------------ | -------------------------------------- |
| 对象存储               | 没有 `sf dataset push`，没有训练后自动评测         |
| 一个 LLM 端点          | 没有 AI 诊断、没有 Ask Agent、没有 LLM 裁判、没有每日日报 |
| 沙箱镜像               | 需要运行模型生成代码的环境会被拒绝，而不是退化成在训练容器里跑        |
| Argilla            | 没有偏好标注闭环                               |
| Hugging Face OAuth | 读不了受限模型，推不了导出结果                        |