部署与运维

两种部署拓扑

同机（推荐起步）：server + agent 都跑在 GPU 机器上，笔记本浏览器/CLI 经 LAN 访问（server.yaml 设 host: 0.0.0.0，token 认证）。

分体：server 跑在常开的轻量机器（NAS / Mac mini 均可），agent 跑在各 GPU 机器， agent.yaml 的 server_url 指向 ws://<server-ip>:8600。agent 单向出站长连接， GPU 机器无需任何入站端口，断线自动重连 + spool 重放。

常驻运行（systemd user service）

deploy/systemd/ 提供 server 与 agent 的 user unit 模板：

mkdir -p ~/.config/systemd/user
cp deploy/systemd/gpuctl-*.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now gpuctl-server gpuctl-agent
loginctl enable-linger "$USER"   # 关键：否则登出/重启后服务不会起来

升级

git pull && uv sync --frozen --no-dev
systemctl --user restart gpuctl-server gpuctl-agent

受限/离线网络安装

平台依赖只有约 50 个小 wheel（torch 不属于平台依赖，用训练机现有环境即可）。网络受限时在能上网的机器预下载，再拷到目标机离线安装：

# 能上网的机器（如 Mac），为 Linux x86_64 + py3.12 下载
uv export --format requirements-txt --locked --no-hashes --no-dev -o /tmp/reqs.txt
grep -v '^-e ' /tmp/reqs.txt > /tmp/reqs-clean.txt
uv run --python 3.12 --with pip python -m pip download -r /tmp/reqs-clean.txt hatchling editables \
  --python-version 312 --only-binary=:all: \
  --platform manylinux_2_28_x86_64 --platform manylinux_2_17_x86_64 \
  --platform manylinux2014_x86_64 -d ./wheels
rsync -az ./ ./wheels/ gpu-host:~/GPUPlane-wheels/   # 含仓库本体

# 目标机（离线）
cd ~/GPUPlane && uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python --no-index --find-links ~/GPUPlane-wheels \
  -r ~/GPUPlane-wheels/reqs-clean.txt hatchling editables
uv pip install --python .venv/bin/python --no-index --no-build-isolation \
  -e ./packages/common -e ./packages/tbreader -e ./packages/sdk \
  -e ./packages/server -e ./packages/agent -e ./packages/cli

Docker runner（可选）

Process runner 是默认；Docker runner 是可选能力，语义相同（日志/退出码/槽位），自动注入 --gpus、取消用 docker kill。使用前 agent 主机需安装 NVIDIA Container Toolkit：

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker       # 先确认没有运行中的容器
docker run --rm --gpus all <cuda-image> nvidia-smi

WSL2 上先确认宿主透传正常（nvidia-smi 可见 GPU）——Toolkit 只负责把已透传的 GPU 暴露给容器，不能替代 Windows/WSL 驱动。

常用运维命令

uv run gpuctl backup             # 在线备份 SQLite 到 <data_dir>/backups/
uv run gpuctl backup-agent       # 归档 agent 完整 job 日志/runtime/spool
uv run gpuctl job retry <id>     # 失败任务重新排队
uv run gpuctl job cancel <id>    # SIGTERM → 5s → SIGKILL（整进程组）
uv run gpuctl status             # 节点/队列总览

CLI 命令面速查：

gpuctl status                          # 总览: 节点/GPU/当前job/队列
gpuctl node list|show <id>
gpuctl job submit -n N -g 1 -d D [--watch DIR] -- <cmd...>
gpuctl job list|show|cancel|retry <id>
gpuctl logs <job-id> [-f] [--full] [--stream stderr]
gpuctl run list|show <id>              # show 打印 RunSummary
gpuctl metrics <run-id> --names train/loss --window 6h
gpuctl checkpoints <run-id>
gpuctl import-run <dir>                # TB events + logs + ckpt 导入
gpuctl backup / backup-agent
gpuctl event-hook ...                  # 事件触发本地命令