# 磐盘：给代理用的 disk-cli

磐盘地址是 `https://pan.lixf.ink`。证书还没生效时，同一台机器也可以先用 `http://pan.lixf.ink`。

代理只用 `disk-cli` 管理文件和令牌。申请令牌、查看审批结果、把令牌存到本机，这三件事都只有对应的命令，不要自己发票据相关的 HTTP 请求。

## 安装

在拿到这份仓库后：

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
disk-cli --help
```

命令行程序和网盘在同一个项目里，安装后入口是 `disk-cli`。

## 先写上网盘地址

地址和令牌可以放在 `~/.config/disk-cli/config.json`。环境变量 `DISK_CLI_BASE_URL`、`DISK_CLI_TOKEN` 会盖过文件里的同名字段。配置文件路径可以用 `DISK_CLI_CONFIG` 改掉。

```bash
disk-cli config set-base-url https://pan.lixf.ink
disk-cli config show
```

`config show` 只显示令牌有没有保存，以及前后几位，不会把完整令牌打出来。

## 令牌：申请、查询、保存

管理员在网页上通过或拒绝。代理这边只走下面三条命令。

提交申请。`--duration` 可以是 `30m`、`12h`、`7d`，或秒数。需要永不过期时改用 `--permanent`。

```bash
disk-cli token apply --applicant "整理助手" --reason "把项目附件放进磐盘" --duration 7d
```

```bash
disk-cli token apply --applicant "整理助手" --reason "长期同步资料" --permanent
```

命令会打印票据编号。接着用这个编号查看审批结果：

```bash
disk-cli token status 票据编号
```

还在等待时，可以自己隔一段时间再查，也可以让命令多等一会儿：

```bash
disk-cli token status 票据编号 --wait 120 --interval 5
```

通过之后，输出里会有一行令牌。把它存到本机，之后的文件命令才会带上身份：

```bash
disk-cli token set 这里换成_status_打印出来的令牌
disk-cli token me
```

被拒绝时，`token status` 会打印原因，不会给出令牌。

查看当前身份：

```bash
disk-cli token me
```

不再使用时吊销，并从本机配置里删掉：

```bash
disk-cli token revoke
```

管理员在网页上管理已经发出的令牌：可以吊销、删除，也可以改到期时间。限时令牌可以改成永久，永久令牌也可以改回一段有效期。代理不在网页上做这些事，申请、查询和保存仍然只用上面的命令。`--permanent` 只出现在 `disk-cli token apply` 上，用来申请永不过期的令牌。

脚本如果只想要 JSON，在子命令前加上 `--json`，例如 `disk-cli --json token status 票据编号`。

## 上传时如何确认内容

`disk-cli upload` 会先计算本地文件的 MD5。

- 网盘里已经有一份相同内容时，直接出现这个文件，不会再传一遍。输出里会写明已秒传。
- 还没有这份内容时，命令会把字节传上去，再请服务端按收到的内容重新计算 MD5，并核对大小。
- 只有 MD5 和大小都与登记时一致，文件才会出现在网盘里。
- 对不上时命令失败，网盘里不会多出一个文件。
- 内容刚传完、暂时还读不到时，命令会自动再确认几次。

```bash
disk-cli upload ./合同.pdf
disk-cli upload ./a.png ./b.png --parent /项目/附件
```

`--parent` 可以是路径，也可以是文件夹 id。省略时传到根目录。

## 浏览和下载

列出根目录，或某个文件夹（路径或 id 都可以）：

```bash
disk-cli ls
disk-cli ls /项目
disk-cli stat /项目/合同.pdf
disk-cli info /项目/合同.pdf
```

`info` 和 `stat` 是一回事。根目录写作 `/`。

按名称搜索：

```bash
disk-cli search 合同
```

下载原文件。图片、音视频可以用预览地址；有缩略图时可以单独把缩略图存下来。

```bash
disk-cli download /项目/合同.pdf -o ./合同.pdf
disk-cli preview /项目/封面.png -o ./封面.png
disk-cli thumb /项目/封面.png -o ./封面.thumb.jpg
```

下载走磐盘自己的地址，适合直接保存。视频预览支持断点读取。

## 文件夹和整理

```bash
disk-cli mkdir /项目
disk-cli mkdir -p /项目/2026/附件
disk-cli rename /项目/合同.pdf 合同-已签.pdf
disk-cli mv /项目/合同-已签.pdf /归档
disk-cli cp /项目 /备份
```

`mkdir -p` 会把中间还没有的文件夹一并建出来。`mv` 和 `cp` 的目标是文件夹，写 `/` 表示根目录。复制文件夹时，里面的文件和子文件夹会一起复制。

## 删除、回收站

默认只是放进回收站：

```bash
disk-cli rm /项目/草稿.txt
```

彻底删除才用 `--permanent`。文件夹会连同里面的内容一起处理。

```bash
disk-cli rm --permanent /项目/草稿.txt
```

查看回收站、按条目 id 还原、清空：

```bash
disk-cli trash
disk-cli restore 条目id
disk-cli trash empty
```

还原不要写路径，先用 `disk-cli trash` 看 id。清空回收站不能撤销。

## 出错时

失败会在标准错误输出 `错误：…`，退出码为 1。加了 `--json` 时，错误也是 JSON，字段里有 `detail` 和 `code`。上传确认没通过时，文件不会出现在列表里，改好本地文件后重新执行 `disk-cli upload` 即可。