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

# sf admin

> 管理员命令：用户、配额与维护模式

需要 admin 角色。控制台侧对应功能见[管理页](/zh-Hans/console/admin)。

## 用户管理

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin users                          # 全部用户
sf admin user-add <用户名>              # 新建本地账号（交互输入密码）
sf admin set-role <用户名> <角色>       # admin / operator
sf admin disable <用户名> --on          # 停用
sf admin disable <用户名> --off         # 启用
```

## 配额

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin set-quota <用户名> \
  --gpus 16 \                  # 并发 GPU 上限（默认 8）
  --jobs 6 \                   # 并发作业上限（默认 4）
  --daily-gpu-hours 200 \      # 每日 GPU-时（0=不限）
  --max-storage-gb 2000 \      # run 目录存储上限 GiB（0=不限）
  --profiles h200,h100 \       # 允许的 profile（逗号分隔，空=全部）
  --priority 10                # 排队优先级（默认 0）
```

<Note>
  存储配额与 GPU 配额的语义不同。GPU 是**预扣**：提交时就为这个作业留出卡数。
  存储只能**事后测量** —— 训练进程往盘上写不会通知平台，作业也说不出自己会写多少，
  所以没有可预扣的量。规则是「已经超了就不再放新作业出队」，在跑的作业不受影响。

  用量由后台周期扫描得出（`FORGE_STORAGE_SCAN_INTERVAL_S`，默认 600 秒），
  因此是最终一致的：两次扫描之间可能短暂超出。扫描卡住时配额闸自动让行 ——
  与其让所有人提交不了，不如在看板上把「数据陈旧」显示出来。
</Note>

## 维护模式

排空集群 → 升级 → 恢复，作业从 checkpoint 续训不丢进度：

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin maintenance status     # 当前状态与是否可安全重启集群
sf admin maintenance drain      # 进入维护模式并排空（幂等，没排干净再跑一次）
# …… 升级集群 / 平台 ……
sf admin maintenance resume     # 退出维护；被暂停作业自动续训
```

<Note>
  维护模式是总闸：drain 后新作业不出队、运行中作业被暂停（保留 checkpoint）。resume 后一切自动恢复，无需逐个操作。
</Note>

## `sf admin`

Manage users and quotas

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin <subcommand>
```

| 命令                     | 说明                                     |
| ---------------------- | -------------------------------------- |
| `sf admin disable`     | Disable or enable a user               |
| `sf admin maintenance` | Drain, upgrade and resume the cluster  |
| `sf admin set-quota`   | Set a user's compute and storage quota |
| `sf admin set-role`    | Change a user's role                   |
| `sf admin user-add`    | Create a local account                 |
| `sf admin users`       | List every user                        |

### `sf admin disable`

Disable or enable a user

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin disable <USERNAME> [options]
```

| 参数         | 说明     |
| ---------- | ------ |
| `USERNAME` | **必填** |

| 选项     | 说明                           |
| ------ | ---------------------------- |
| `--on` | --on disables, --off enables |

### `sf admin maintenance`

Drain, upgrade and resume the cluster

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin maintenance <subcommand>
```

| 命令                            | 说明                                |
| ----------------------------- | --------------------------------- |
| `sf admin maintenance drain`  | Enter maintenance mode and drain  |
| `sf admin maintenance resume` | Leave maintenance mode            |
| `sf admin maintenance status` | Show maintenance state and safety |

#### `sf admin maintenance drain`

Enter maintenance mode and drain

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin maintenance drain [options]
```

| 选项       | 说明                                                                  |
| -------- | ------------------------------------------------------------------- |
| `--note` | Maintenance note, echoed back to anyone whose submission is blocked |

#### `sf admin maintenance resume`

Leave maintenance mode

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin maintenance resume
```

除 `--help` 外没有其他选项。

#### `sf admin maintenance status`

Show maintenance state and safety

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin maintenance status
```

除 `--help` 外没有其他选项。

### `sf admin set-quota`

Set a user's compute and storage quota

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin set-quota <USERNAME> [options]
```

| 参数         | 说明     |
| ---------- | ------ |
| `USERNAME` | **必填** |

| 选项                          | 说明                                                                                                                                                     |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--gpus` `<int>`            | Concurrent GPU cap (默认 `8`)                                                                                                                            |
| `--jobs` `<int>`            | Concurrent job cap (默认 `4`)                                                                                                                            |
| `--daily-gpu-hours` `<int>` | GPU-hours per day (0 = unlimited) (默认 `0`)                                                                                                             |
| `--max-storage-gb` `<int>`  | Cap on the user's run directories in GiB (0 = unlimited). Enforced against a periodic scan: going over blocks new jobs, running ones continue (默认 `0`) |
| `--profiles`                | Allowed profiles (comma separated, empty = all)                                                                                                        |
| `--priority` `<int>`        | Queue priority (默认 `0`)                                                                                                                                |

### `sf admin set-role`

Change a user's role

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin set-role <USERNAME> <ROLE>
```

| 参数         | 说明     |
| ---------- | ------ |
| `USERNAME` | **必填** |
| `ROLE`     | **必填** |

除 `--help` 外没有其他选项。

### `sf admin user-add`

Create a local account

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin user-add <USERNAME> [options]
```

| 参数         | 说明     |
| ---------- | ------ |
| `USERNAME` | **必填** |

| 选项                 | 说明                                          |
| ------------------ | ------------------------------------------- |
| `--password`, `-p` | **必填**                                      |
| `--role`           | admin \| operator \| viewer (默认 `operator`) |
| `--email`          | —                                           |

### `sf admin users`

List every user

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin users
```

除 `--help` 外没有其他选项。