gflow

简体中文

English

简体中文

English

主题

配置 ​

大多数情况下 gflow 无需配置即可使用。只有在你需要调整守护进程监听地址/端口，或限制可用 GPU 时才需要配置文件（TOML）或环境变量。

配置文件 ​

默认位置：

~/.config/gflow/gflow.toml

也可以用向导生成一个配置文件：

bash
gflowd init

最小示例：

toml
[daemon]
host = "localhost"
port = 59000
# gpus = [0, 2]
# gpu_allocation_strategy = "sequential" # 或 "random"

所有命令都支持 --config <path> 指定配置文件：

bash
gflowd --config <path> up
ginfo --config <path>
gbatch --config <path> --gpus 1 python train.py

守护进程配置 ​

主机和端口 ​

toml
[daemon]
host = "localhost"
port = 59000
  • 默认：localhost:59000
  • 仅在明确了解安全影响时使用 0.0.0.0。

GPU 选择 ​

限制调度器允许分配的物理 GPU。

配置文件：

toml
[daemon]
gpus = [0, 2]

GPU 分配策略 ​

控制当有多张可用 GPU 时，gflow 如何选择具体索引。

配置文件：

toml
[daemon]
gpu_allocation_strategy = "sequential" # 默认
# gpu_allocation_strategy = "random"
  • sequential：按索引顺序分配（优先低编号 GPU）。
  • random：每次调度随机化可用 GPU 的选择顺序。

守护进程 CLI 参数（覆盖配置文件）：

bash
gflowd up --gpu-allocation-strategy random
gflowd restart --gpu-allocation-strategy sequential

守护进程 CLI 参数（覆盖配置文件）：

bash
gflowd up --gpus 0,2
gflowd restart --gpus 0-3

运行时控制（只影响新的分配）：

bash
gctl set-gpus 0,2
gctl set-gpus all
gctl show-gpus

支持写法：0、0,2,4、0-3、0-1,3,5-6。

优先级（从高到低）：

  1. CLI 参数（gflowd up --gpus ...）
  2. 环境变量（GFLOW_DAEMON_GPUS=...）
  3. 配置文件（daemon.gpus = [...]）
  4. 默认：所有检测到的 GPU

分配策略优先级（从高到低）：

  1. CLI 参数（gflowd up --gpu-allocation-strategy ...）
  2. 环境变量（GFLOW_DAEMON_GPU_ALLOCATION_STRATEGY=...）
  3. 配置文件（daemon.gpu_allocation_strategy = "..."）
  4. 默认：sequential

时区 ​

配置预约时间的显示和解析时区。

配置文件：

toml
timezone = "Asia/Shanghai"

命令级别覆盖：

bash
gctl reserve create --user alice --gpus 2 --start "2026-02-01 14:00" --duration "2h" --timezone "UTC"

支持格式：

  • IANA 时区名称："Asia/Shanghai"、"America/Los_Angeles"、"UTC"
  • 时间输入：ISO8601（"2026-02-01T14:00:00Z"）或简单格式（"2026-02-01 14:00"）

优先级（从高到低）：

  1. CLI 参数（--timezone）
  2. 配置文件（timezone = "..."）
  3. 默认：本地系统时区

项目追踪 ​

使用项目配置可以为多团队统一任务归属元数据。

toml
[projects]
known_projects = ["ml-research", "cv-team"]
require_project = false
  • known_projects：允许的项目编码列表。为空时表示允许任意非空编码。
  • require_project：为 true 时，所有任务提交都必须包含非空项目。
  • 项目值会做标准化（去除首尾空白）。仅空白的值会被视为未设置。
  • 项目编码长度上限：64 个字符。
  • 同时启用两项配置时，项目必须提供且必须在 known_projects 中。

相关命令示例：

bash
gbatch --project ml-research python train.py
gqueue --project ml-research
gqueue --format JOBID,NAME,PROJECT,ST,TIME

通知（Webhook） ​

gflowd 支持在任务/系统事件发生时发送 HTTP POST webhook（尽力而为）。

启用并配置：

toml
[notifications]
enabled = true
max_concurrent_deliveries = 16

[[notifications.webhooks]]
url = "https://api.example.com/gflow/events"
events = ["job_completed", "job_failed", "job_timeout"] # 或 ["*"]
filter_users = ["alice", "bob"] # 可选
headers = { Authorization = "Bearer token123" } # 可选
timeout_secs = 10
max_retries = 3

支持的事件名：

  • job_submitted
  • job_started
  • job_completed
  • job_failed
  • job_cancelled
  • job_timeout
  • job_held
  • job_released
  • gpu_available（仅在 GPU 变为可用时）
  • reservation_created
  • reservation_cancelled

Payload 结构（不同事件可能省略部分字段）：

json
{
  "event": "job_completed",
  "timestamp": "2026-02-04T12:30:45Z",
  "job": { "id": 42, "user": "alice", "state": "Finished" },
  "scheduler": { "host": "gpu-server-01", "version": "0.4.11" }
}

备注：

  • events = ["*"] 表示订阅所有支持的事件。
  • filter_users 用于按任务提交者 / 预约创建者过滤通知。
  • max_retries 使用指数退避（尽力而为）；系统过载时可能丢弃通知。
  • 注意敏感信息：webhook 可能包含任务元数据与用户名。

日志 ​

  • gflowd：使用 -v/--verbose（见 gflowd --help）。
  • 客户端命令（gbatch、gqueue、ginfo、gjob、gctl）：使用 RUST_LOG（例如 RUST_LOG=info）。

环境变量 ​

bash
export GFLOW_DAEMON_HOST=localhost
export GFLOW_DAEMON_PORT=59000
export GFLOW_DAEMON_GPUS=0,2
export GFLOW_DAEMON_GPU_ALLOCATION_STRATEGY=random

文件与状态 ​

gflow 遵循 XDG Base Directory 规范：

text
~/.config/gflow/gflow.toml
~/.local/share/gflow/state.msgpack  (或 state.json 用于旧版本)
~/.local/share/gflow/logs/<job_id>.log

状态持久化格式 ​

从 0.4.11 版本开始，gflowd 使用 MessagePack 二进制格式进行状态持久化：

  • 新安装：状态保存到 state.msgpack（二进制格式）
  • 自动迁移：现有的 state.json 文件会在首次加载时自动迁移到 state.msgpack
  • 向后兼容：gflowd 仍然可以读取旧的 state.json 文件

恢复模式（状态文件异常） ​

如果状态文件无法反序列化或迁移（例如升级/降级版本后），gflowd 会进入恢复模式：

  • gflowd 继续运行，但不会覆盖写入状态文件。
  • 状态变更会写入一个"单快照"日志文件：~/.local/share/gflow/state.journal.jsonl（每次保存都会覆盖写入）。
  • /health 返回 200，并包含 status: "recovery" 与 mode: "journal"。
  • 会在同目录创建一份备份（例如 state.msgpack.backup.<timestamp> 或 state.msgpack.corrupt.<timestamp>）。

当状态文件再次可读取后，gflowd 会加载最新的日志快照，重写状态文件，并清空日志文件。

如果日志文件不可写，gflowd 会退化为只读模式，此时所有会修改状态的 API 返回 503。

恢复方式：升级/降级到能够读取/迁移该状态文件的版本，或从备份文件恢复。

故障排除 ​

找不到配置文件 ​

bash
ls -la ~/.config/gflow/gflow.toml

端口被占用 ​

更换端口：

toml
[daemon]
port = 59001

另见 ​

Released under the MIT License.

Copyright © 2025-present PuQing