RunPod 日常操作手册¶

更新时间：2026-07-21。适用范围：EvoSpeech 的临时 GPU 评测、SOTA 复现和未来训练。

这份手册是项目的 RunPod 长期操作记忆。项目采用“持久 Network Volume + 随用随建的临时 GPU Pod”模式：数据和 checkpoint 留在独立卷中，GPU 机器每天可以换，不把存储绑死在一张可能被别人占用的显卡上。

最重要的关机规则

当前 Pod 挂载独立 Network Volume。RunPod 官方说明此类 Pod 不能正常 stop，只能 terminate/delete；删除 Pod 后，Network Volume 中的 /workspace 数据继续保留。因此本项目的“关机”是：验证结果已写入持久卷 → 删除精确 Pod ID → 确认 Pod 为 0、Volume 仍存在。

一、当前冻结资源¶

项目	当前值	含义
CLI	`runpodctl 2.7.2-309512b`	GPU Pod、Volume、账户与账单控制
私有凭据	`~/.runpod/config.toml`，mode `0600`	只保存在本机，不进 Git
持久卷	`evospeech-research` / `imdh4l9gud`	Pod 删除后仍保留
机房	`EU-RO-1`	Network Volume 只能挂到同一 datacenter 的 Pod
容量/挂载点	50 GB / `/workspace`	数据、cache、checkpoint、结果的持久区域
空闲目标	0 个 Pod	不工作时只支付持久卷存储费
项目预算策略	≤ $1/h、≤ 4 h、≤ $10/job、启动后至少留 $10	`cloud/runpod/policy.json` 的保护值

机器可读身份在 cloud/runpod/resources.json；预算与允许 GPU 在 cloud/runpod/policy.json。价格是项目记录的上限假设，不是实时行情；每次启动仍要检查库存、余额和当前 spend。

二、CLI 分工：用 `runpodctl`，不是 `flash`¶

runpodctl：管理 GPU Pods、Network Volumes、SSH、库存和账单；本项目使用它。
flash：构建/部署 RunPod Serverless 应用；不是当前 GPU 研究主机的开关。

官方入口：RunPod CLI overview、 Pod CLI reference、 Network Volume CLI reference、 Pod 生命周期说明。

三、首次安装、登录与密钥纪律¶

本机已经安装并登录。新机器上才需要执行：

brew install runpod/runpodctl/runpodctl
runpodctl doctor
runpodctl version
runpodctl completion

runpodctl doctor 会交互式配置 API key 和 SSH。不要把 key 写进 shell profile、仓库 .env、 Dockerfile、聊天、终端截图或实验 JSON。配置后检查：

stat -f '%Sp %N' "$HOME/.runpod/config.toml"
chmod 600 "$HOME/.runpod/config.toml"
runpodctl user | jq '{balance:.clientBalance, spend_per_hour:.currentSpendPerHr}'

如果 key 曾经出现在聊天、公开日志或截图中，应立即在 RunPod 控制台撤销并重新运行 runpodctl doctor，不要把新 key 再粘贴到聊天里。

四、每天开始：30 秒只读体检¶

在仓库根目录执行：

cd /path/to/EvoSpeech

python scripts/runpod_evospeech.py status
runpodctl pod list --all
runpodctl network-volume get imdh4l9gud
python scripts/runpod_evospeech.py plan --minimum-memory-gb 24

健康的空闲状态应满足：

pod_count = 0；
volume_count = 1；
current_spend_per_hour_usd 只有持久卷存储成本；
Volume 是 imdh4l9gud、EU-RO-1、50 GB；
plan.selected 位于 EU-RO-1，GPU 显存和项目预算都满足当前任务。

只想让 Codex 检查、不创建机器时，可以说：

读取 RunPod runbook，执行只读 status、pod list、volume get 和 plan；不要创建、停止或删除资源。

五、每天开机：先 dry-run，再明确执行¶

1. 选择显存门槛¶

24 GB 评测任务：

python scripts/runpod_evospeech.py plan --minimum-memory-gb 24

48 GB 大模型或训练任务：

python scripts/runpod_evospeech.py plan --minimum-memory-gb 48

候选排序优先同机房、预算内、库存可用的 GPU。因为持久卷在 EU-RO-1，其他机房的候选不能直接挂载这个卷；不要只因外地 GPU 便宜就执行跨机房候选。

2. 预演完整创建命令¶

资源文件已记录 Volume ID，因此通常不需要手抄 --volume-id：

python scripts/runpod_evospeech.py create-pod \
  --minimum-memory-gb 24 \
  --name evospeech-YYYYMMDD-task

输出中的 action 必须是 would_create。检查：

gpu.datacenter_id 是 EU-RO-1；
network_volume_id 是 imdh4l9gud；
estimated_max_gpu_usd 可接受；
terminate_after 已设置；
余额保护没有失败。

3. 真正创建¶

只有核对 dry-run 后才执行：

python scripts/runpod_evospeech.py create-pod \
  --minimum-memory-gb 24 \
  --name evospeech-YYYYMMDD-task \
  --execute > tmp/runpod-create.json

export EVOSPEECH_POD_ID="$(jq -r '.pod.id' tmp/runpod-create.json)"
runpodctl pod get "$EVOSPEECH_POD_ID"
runpodctl ssh info "$EVOSPEECH_POD_ID" --verbose

terminate-after 是最终保险，不替代主动回收。创建成功后应立即保存精确 Pod ID，不用名称猜测删除目标。若 adapter 报余额、库存或 datacenter 失败，先停下来重新 plan，不绕过预算保护。

六、连接与工作目录¶

获取 SSH 命令：

runpodctl ssh info "$EVOSPEECH_POD_ID" --verbose

进入远端后先检查：

nvidia-smi
df -h /workspace
ls -la /workspace

建议持久卷布局：

/workspace/evospeech/
├── cache/          Hugging Face、torch 与 metric cache
├── datasets/       固定 manifest 对应的公共数据
├── checkpoints/    下载权重和原创训练 checkpoint
├── jobs/           每次任务的 capsule、日志与临时状态
└── results/        完成后等待回传的 hash-bound 结果

容器系统盘和 /tmp 都视为可丢弃。需要跨天保留的内容必须位于 /workspace；关键 checkpoint 还应回传本地或对象存储，不能让 Network Volume 成为唯一副本。

七、运行中监控¶

runpodctl pod list
runpodctl pod get "$EVOSPEECH_POD_ID"
runpodctl user | jq '{balance:.clientBalance, spend_per_hour:.currentSpendPerHr}'
runpodctl billing pods --pod-id "$EVOSPEECH_POD_ID" --bucket-size hour

研究任务还必须监控自己的日志、checkpoint 与结果 manifest。GPU 还活着不代表实验健康；如果任务异常退出或不再前进，先保存诊断和可恢复状态，然后删除 Pod，不能让空闲 GPU 持续计费。

八、每天关机：保存、核对、删除精确 Pod¶

1. 关机前验收¶

结果、日志、capsule 和 checkpoint 已写到 /workspace；
关键结果已经回传本地；
本地能打开文件并核对 SHA-256/JSON schema；
记录实验退出码、完成度、GPU、时长和已知失败；
精确 Pod ID 已用 runpodctl pod get 再确认。

2. 删除临时 Pod¶

runpodctl pod get "$EVOSPEECH_POD_ID"
runpodctl pod delete "$EVOSPEECH_POD_ID"

这是有意删除临时计算实例；没有写入 Network Volume 的容器盘数据会消失。不要使用批量循环、名称模糊匹配或旧的 Pod ID。

3. 删除后必须验证¶

runpodctl pod list --all
runpodctl network-volume get imdh4l9gud
python scripts/runpod_evospeech.py status

预期是 0 个 Pod、1 个 Volume，账户每小时 spend 回落到持久卷成本。不要执行 runpodctl network-volume delete imdh4l9gud；那会永久删除项目的持久数据。

只想让 Codex安全关机时，可以说：

读取 RunPod runbook，先核对指定 Pod 的结果和持久卷，再删除这个精确 Pod；删除后验证 0 Pod、Volume 仍存在。不要删除 Network Volume。

九、第二天重新开机¶

被 delete 的 Pod 不会“恢复”。第二天重新运行 plan → create-pod dry-run → --execute，创建一台新的同机房 GPU Pod并重新挂载 imdh4l9gud。旧数据从 /workspace 继续使用。

如果 EU-RO-1 没有原 GPU：

先选同机房另一种、满足显存与预算的 GPU；
若同机房完全无货，等待通常比临时搬卷更简单；
真要跨机房，必须先制定数据复制与新 Volume 方案，不能把机房参数直接改掉后期待旧卷出现。

十、常用只读与诊断命令¶

runpodctl version
runpodctl doctor
runpodctl user
runpodctl gpu list
runpodctl datacenter list
runpodctl pod list --all
runpodctl network-volume list
runpodctl billing pods --bucket-size day
runpodctl billing network-volume --bucket-size day
runpodctl ssh list-keys

CLI 行为有变化时，以 runpodctl COMMAND --help 和官方文档为准，再更新本手册和 cloud/runpod/resources.json；不要凭旧记忆猜 flags。

十一、危险命令分级¶

操作	风险	项目规则
`pod get/list`、`user`、`billing`、`plan`	只读	可直接执行
`create-pod` 无 `--execute`	dry-run	每次开机必做
`pod create` / adapter `--execute`	开始计费	核对预算、卷、机房和自动终止后执行
`pod delete POD_ID`	删除临时机及容器盘	结果回传并核对精确 ID 后执行
`pod reset` / `pod update`	可能清空非持久数据	默认不用，先制定恢复方案
`network-volume update`	费用/容量变化	明确评估后执行；容量只能增大
`network-volume delete`	永久丢失持久数据	禁止自动执行；需要用户显式授权和备份

十二、每日最短清单¶

开机前：status → pod list → volume get → plan
开机时：create dry-run → 核对预算/机房/卷/terminate-after → --execute
工作中：结果写 /workspace → 监控日志/checkpoint/balance
关机前：回传并验 hash → pod get 精确 ID
关机时：pod delete 精确 ID
关机后：0 Pod → Volume 仍在 → spend 只剩存储