> ## 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 各部分怎么拼在一起

> CLI → 控制平面 → 执行器 → Job Capsule。一份 JobSpec 契约。

StarForge 是四层，中间一份契约（JobSpec + recipe catalog）。加一种方法、换一个集群后端，不应该逼着别的层一起改。

<img src="https://mintcdn.com/starforge/KiXW_1e-qWb7Hzzw/images/architecture.png?fit=max&auto=format&n=KiXW_1e-qWb7Hzzw&q=85&s=e83de821bd965982f939b83a432211d1" alt="StarForge —— 围绕一份 JobSpec 契约的四层：你的机器、控制平面、四选一的执行器，以及训练容器。指标、日志和产物回流到 ingest。" className="block dark:hidden w-full" noZoom width="1536" height="1024" data-path="images/architecture.png" />

<img src="https://mintcdn.com/starforge/KiXW_1e-qWb7Hzzw/images/architecture-dark.png?fit=max&auto=format&n=KiXW_1e-qWb7Hzzw&q=85&s=eb3c5590a85463d7dafe7e6b12f96aad" alt="StarForge —— 围绕一份 JobSpec 契约的四层：你的机器、控制平面、四选一的执行器，以及训练容器。指标、日志和产物回流到 ingest。" className="hidden dark:block w-full" noZoom width="1536" height="1024" data-path="images/architecture-dark.png" />

## 各层

| 层     | 位置                                       | 职责                                                                             |
| ----- | ---------------------------------------- | ------------------------------------------------------------------------------ |
| CLI   | `core/starforge/cli/`，包 `starforge-core` | 实验、本地校验、打包、JobSpec。不碰集群凭据。                                                     |
| 控制平面  | `server/`，包 `starforge-console`          | 鉴权、配额、catalog 握手、出队、执行器投放、ingest、UI                                            |
| 执行器   | `server/executors/`                      | 把 `LaunchRequest` 变成 `docker run` / agent HTTP / RayJob / slurmrestd。看状态、回收资源。 |
| 训练运行时 | 服务端注入的 Job Capsule                       | `bootstrap.sh` 校验 manifest，再用镜像自带的 Python 跑 `runner.pex`。训练镜像不预装平台包。           |

## 提交路径

<Steps>
  <Step title="客户端组 JobSpec">
    `sf submit` 读实验目录和 `recipe.lock.json`，按硬件注册表展开 `--profile`，校验超参，按清单打包工作区（含 git 溯源）。
  </Step>

  <Step title="服务端准入">
    catalog 握手（方法和框架版本必须已发布）、配额、镜像 allowlist、HuggingFace 预检。任一不过就拒绝提交。
  </Step>

  <Step title="排队和装配">
    作业停在 `QUEUED`，调度器出队。装配把 JobSpec + 服务端配置收成 `LaunchRequest`，注入 `capsule.json`、`bootstrap.sh` 和内容寻址的 `runner.pex`。
  </Step>

  <Step title="执行器投放">
    `local`：`docker run`，GPU 分配和起容器同一把锁。`agent`：HTTP 打到节点上的 `forgelet`。`kuberay`：RayJob CR。`slurm`：slurmrestd 申请 allocation，再 `srun` + Ray（多池走 hetjob）。
  </Step>

  <Step title="容器启动">
    入口是 `bash .starforge/capsule/bootstrap.sh` → `python runner.pex run`。runner 校验文件摘要和 Python/框架能力，按 recipe adapter 选入口，上报 lifecycle。
  </Step>

  <Step title="回传">
    stdout 进日志页。曲线走 `starforge.report`（目录方法已接好；custom 要自己调）。失败可以触发诊断。
  </Step>
</Steps>

## 日常会碰到的设计选择

<AccordionGroup>
  <Accordion title="密钥只在服务端" icon="key">
    集群地址、HF token、对象存储钥匙在控制平面。客户端只有个人 access token。训练容器拿到的是按 run 签发、收窄 scope 的 ingest token。
  </Accordion>

  <Accordion title="不静默回退" icon="file-check">
    平台不猜框架、不猜入口。方法必须在 catalog 里发布。custom 必须声明 `train.sh` 和镜像。锁文件和 catalog 对不上就拒提交——用 `sf recipe upgrade` 升级。
  </Accordion>

  <Accordion title="换执行器，不换作业语义" icon="server">
    装配产出与后端无关的 `LaunchRequest`。执行器实现 launch / observe / stop / cleanup。用哪一个，取决于作业被放到的 Fleet 的 kind。配错了不会偷偷落到另一个后端。
  </Accordion>

  <Accordion title="提交可追溯" icon="git-commit-horizontal">
    每次 run 记下 git commit、配置快照、recipe digest、runner/capsule digest、镜像 digest。脏工作区默认拒提交，除非 `--allow-dirty`。
  </Accordion>
</AccordionGroup>

## 作业状态

台账状态（不是 Docker / Ray / Slurm 的原生状态）：

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
stateDiagram-v2
    [*] --> QUEUED: 提交受理
    QUEUED --> SUBMITTED: 出队
    SUBMITTED --> PENDING: launch 返回
    PENDING --> RUNNING: 容器起来
    RUNNING --> SUCCEEDED
    RUNNING --> FAILED
    RUNNING --> STOPPED: 停止 / 时段关闭
    RUNNING --> PAUSED: 暂停 / 排空
    PAUSED --> QUEUED: 继续
    FAILED --> QUEUED: 自动重试（预算内）
    STOPPED --> QUEUED: 从 checkpoint 续训
```

`QUEUED` 还没上集群。`PAUSED` 已经还卡、留着 checkpoint。自动重试和维护排空走同一条暂停/恢复路径。

## 下一步

<CardGroup cols={2}>
  <Card title="Recipe" icon="book-marked" href="/zh-Hans/concepts/recipes">
    catalog、锁文件、框架版本矩阵
  </Card>

  <Card title="资源" icon="cpu" href="/zh-Hans/concepts/resources">
    profile、配额、时段、多池
  </Card>
</CardGroup>