deepx-storage

deepx-storage — 云端网盘操作

deepx storage 走 adapter 自己的网盘 HTTP API（matpool 是 fs-N.matpool.com）， 不需要任何运行中机器，也不走 SSH。文件落在云端网盘上，运行中的机器从 /mnt 直接读到。

何时用

场景	用什么
在本地把数据集 / ckpt 传到 matpool 网盘	✅ deepx storage cp
起新机器之前先把代码 / 模型放好	✅ 本 skill
一次性下载某个 run 的 best.pth	✅ deepx storage cp remote:... ./
已经有机器在跑，要从本地 rsync 增量同步代码	❌ 用 deepx compute cp（更快、断点续传）
在机器内 cd /mnt 拷贝文件	❌ 直接 SSH 跑 cp/mv 即可
服务端拉 GitHub / HuggingFace 仓库	❌ 当前 deepx 不支持，去 matpool 网页或装 matbox 客户端

4 个动作

deepx storage ls [path]                   # 列目录（默认根）
deepx storage quota                       # used GB / total GB / 百分比
deepx storage cp <src> <dst>              # 上传 / 下载
deepx storage rm <path>... [--yes]        # 删除（默认要 --yes）

storage 没有 mkdir / mv / rename 子命令——matpool 的 fs API 没有公开 对应端点。要建嵌套目录，先去 matpool 网页（matbox 标签页）建好；移动 / 重命名 目前只能下载再上传。

ls

deepx storage ls                          # 网盘根
deepx storage ls runs                     # 等价 /runs
deepx storage ls /datasets/s3dis
deepx storage ls --json                   # 给 agent

输出列：TYPE / SIZE / MODIFIED / NAME。TYPE 列 f/d，目录名带尾 /。

实现注意：matpool 要求目录路径必须末尾带 /——CLI 自动加。如果你直接 curl /fs?path=/foo（没尾斜杠）matpool 会返回文件本身的内容而不是目录列表。

quota

deepx storage quota
# used 98.4 GB / 105 GB (93.7%)

deepx storage quota --json
# {"usage_mb": ..., "quota_gb": 105}

数据从 /api/user 的 volume 字段取，每次调用都是实时数。

cp（上传 / 下载）

remote: 前缀指网盘端，没前缀指本地。两端必须一端是 remote: 一端是本地。

# 上传单个文件
deepx storage cp ./model.pth remote:checkpoints/v14/best.pth

# 下载单个文件
deepx storage cp remote:logs/train.log ./train.log

# 下载到目录（自动用 remote 文件名）
deepx storage cp remote:logs/train.log ./logs/

限制：

• 不支持上传整个目录——matpool fs 是 per-file POST，逐个上传或用 deepx compute cp 走 rsync（要求机器在跑）
• 不支持网盘内拷贝（remote:a remote:b）——matpool fs API 没有 rename 端点， 需要的话先下载再上传

rm

deepx storage rm remote:tmp/junk.txt --yes
deepx storage rm remote:runs/v8 --yes        # 目录递归删（matpool 服务端处理）
deepx storage rm remote:tmp/a remote:tmp/b --yes  # 多目标

不带 --yes 也不带 DEEPX_AUTO_YES=1 时只列出候选不动手。删除是不可逆的 （matpool 服务端没有回收站），所以默认双保险。

remote: 前缀可加可不加，CLI 都接（deepx storage rm runs/v8 --yes 也行）。

Token 过期会自动重登

deepx storage 的 HTTP 路径跟 deepx compute / deepx balance 共享同一套 relogin 机制：matpool 返 code=176（token 过期），CLI 用缓存的凭证 silent relogin 一次，重试当前请求。用户感知不到，除非凭证本身已经失效——那时会报 "token expired and re-login failed"，需要重新 deepx auth login。

之前的实现里 storage 走的是裸 HTTP，过期会硬报错；现在已经修复跟 requestJSON 对齐了。

网盘 vs /mnt —— 别混

你的 Mac          deepx storage cp                fs-3.matpool.com
   │ ─────────────────────────────────────────────► │  云端网盘
   │                                                │
   │ deepx compute cp (rsync over SSH)              │
   │ ─────────────────────────────────────────► matpool 实例
                                                    │
                                                    └── /mnt 是云端网盘的本地挂载
                                                        实例释放后 /mnt 数据保留

同一份网盘内容，两条路径都能到。storage cp 不要机器；compute cp 要 机器在跑但快得多（rsync 增量、大目录强、断点续传）。

通用建议：

• 一次性少量文件 / 跨会话准备：deepx storage cp
• 训练时同步代码 / 拉 ckpt：deepx compute cp

调试用

DEEPX_DEBUG=1 deepx storage ls /

DEEPX_DEBUG=1 时所有 matpool API 请求 / 响应 body 打到 stderr。看不懂 code 含义时配合 docs/ADAPTERS.md 排查。

边界

• 租机 / SSH / compute cp（rsync 同步要机器在跑）→ deepx-machine
• 自动停机 / sweep 误杀排查 → deepx-recycle
• 实验记录 / ROI 排序 → deepx-experiment
• 实例内 /mnt 操作 → 直接 SSH 跑 cp / mv / rsync，不需要 skill