配置

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

配置文件

默认位置：

~/.config/gflow/gflow.toml

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

gflowd init

最小示例：

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

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

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

守护进程配置

主机和端口

[daemon]
host = "localhost"
port = 59000

• 默认：localhost:59000
• 仅在明确了解安全影响时使用 0.0.0.0。

GPU 选择

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

配置文件：

[daemon]
gpus = [0, 2]

GPU 分配策略

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

配置文件：

[daemon]
gpu_allocation_strategy = "sequential" # 默认
# gpu_allocation_strategy = "random"

• sequential：按索引顺序分配（优先低编号 GPU）。
• random：每次调度随机化可用 GPU 的选择顺序。

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

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

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

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

GPU 轮询间隔

控制 gflow 发现外部 GPU 占用变化的速度。

配置文件：

[daemon]
gpu_poll_interval_secs = 3 # 默认：10

• 值越小，发现非 gflow 任务占用 GPU 会更快，但 NVML 轮询也会更频繁。
• 该值必须至少为 1。

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

gflowd up --gpu-poll-interval-secs 3
gflowd reload --gpu-poll-interval-secs 1

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

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

GPU 轮询间隔优先级（从高到低）：

1. CLI 参数（gflowd up --gpu-poll-interval-secs ...）
2. 环境变量（GFLOW_DAEMON__GPU_POLL_INTERVAL_SECS=...）
3. 配置文件（daemon.gpu_poll_interval_secs = ...）
4. 默认：10

时区

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

配置文件：

timezone = "Asia/Shanghai"

命令级别覆盖：

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. 默认：本地系统时区

项目追踪

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

[projects]
known_projects = ["ml-research", "cv-team"]
require_project = false

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

相关命令示例：

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

通知

如果你需要任务或系统事件的 webhook / 邮件通知，请直接查看通知。

• notifications.emails 也是 gbatch --notify-email 这类单任务邮件通知所复用的 SMTP 通道。
• 如果通知内容包含敏感任务元数据，仍应优先让守护进程只监听 localhost。

日志

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

环境变量

daemon 下的嵌套字段使用双下划线（__）分层。

export GFLOW_DAEMON__HOST=localhost
export GFLOW_DAEMON__PORT=59000
export GFLOW_DAEMON__GPUS=0,2
export GFLOW_DAEMON__GPU_ALLOCATION_STRATEGY=random
export GFLOW_DAEMON__GPU_POLL_INTERVAL_SECS=3

文件与状态

gflow 遵循 XDG Base Directory 规范：

~/.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。

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

故障排除

找不到配置文件

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

端口被占用

更换端口：

[daemon]
port = 59001

另见

• 安装 - 初始设置
• 快速开始 - 基本用法
• 多用户使用 - 共享调度器使用方式
• GPU 管理 - GPU 分配