thufs 是一个面向清华云盘终端用户的 CLI 工具,基于 Seafile API 实现,强调“上传、下载、列目录、分享”这类高频、可脚本化的文件操作。
它不试图成为一个重量级同步客户端,而是希望在 shell、远程服务器、集群作业、自动化脚本这些场景里,提供足够直接、稳定、可预期的命令行体验。
- 面向清华云盘日常用户,尤其是依赖终端和脚本的人群
- 聚焦单文件上传、下载、列目录、分享链接等核心能力
- 保持 Unix 风格的扁平命令接口,便于组合和自动化
- 默认提供人类可读输出,同时支持
--json供脚本消费
info查看当前 token 对应的账号信息repos或libraries查看当前可见的仓库或资料库ls查看远程目录内容,支持 repo 根目录upload上传本地文件到清华云盘download从清华云盘下载文件到本地share生成分享链接,可选密码和过期时间mkrepo或mklib主动创建 librarymkdir主动创建远程目录,并自动创建父目录push和pull作为兼容别名保留- 上传和下载在 TTY 下显示进度条
- 上传和下载支持
--progress jsonl,向 stderr 输出机器可读的流式进度事件 - 上传和下载尽力支持断点续传
- 冲突策略统一为
--conflict - 默认冲突策略为
uniquify,避免静默覆盖 - JSON 输出中返回最终落点路径,便于脚本追踪自动重命名结果
upload在目标 library 或目录不存在时会自动创建ls支持展示更新时间
清华云盘的官方使用方式更偏向 Web 或桌面同步,而很多终端用户真正需要的是:
- 在服务器上把实验结果直接上传到云盘
- 在脚本里拉取某个共享文件作为输入
- 在 cron、集群作业、自动化脚本里稳定地保存产物
- 快速查看某个库里的内容,而不是启动图形界面
thufs 针对的就是这类需求。它更像 scp、rsync、curl 这种“拿来即用”的命令工具,而不是一个常驻同步守护进程。
直接通过 Cargo 安装:
cargo install thufs --locked
thufs --help当前最低支持 Rust 版本为 1.85。如果直接 cargo install thufs 遇到依赖解析到更高 Rust 版本的问题,请使用 --locked。
也可以从源码构建:
git clone git@github.com:class-undefined/thufs.git
cd thufs
cargo build --release
./target/release/thufs --helpmacOS 用户也可以直接下载 GitHub Release 中对应架构的预编译二进制包。
如果你的网络环境访问 Rust 官方源较慢,可使用国内镜像:
export RUSTUP_DIST_SERVER="https://rsproxy.cn"
export RUSTUP_UPDATE_ROOT="https://rsproxy.cn/rustup"如果仅需本地开发调试:
cargo run -- --helpthufs 当前采用 token 驱动,不实现用户名密码登录,也不处理浏览器 OAuth 流程。你需要先从外部获取可用的 Seafile API token。
获取 token 的推荐方式:
- 使用清华账号登录清华云盘页面:
https://cloud.tsinghua.edu.cn/profile/#get-auth-token
- 在页面中的
Web API Auth Token区域点击“生成链接” - 获取页面展示的 token 信息,并将其用于
thufs auth set-token
设置 token:
thufs auth set-token <seafile-api-token>查看当前配置:
thufs config show
thufs --json config show默认配置文件路径:
~/.config/thufs/config.json
支持的环境变量覆盖:
THUFS_TOKENTHUFS_DEFAULT_REPOTHUFS_OUTPUTTHUFS_CONFIG_DIR
设计原则是“配置文件优先,环境变量覆盖”,这样既适合日常使用,也适合临时脚本注入。
显式远程路径的标准形式为:
repo:<library>/<path>
这里的 library 就是你在 Seafile 或清华云盘中可见的仓库名、资料库名。
例如:
repo:course-lib/slides/week1.pdf
表示:
仓库 course-lib 中的 /slides/week1.pdf
thufs ls repo:course-lib/slides
thufs download repo:course-lib/slides/week1.pdf
thufs upload ./report.pdf repo:course-lib/submissions/report.pdf
thufs upload ./report.pdf repo:course-lib如果配置了 THUFS_DEFAULT_REPO 或本地配置中的 default_repo,则可以使用简写路径:
thufs ls slides
thufs download slides/week1.pdf
thufs upload ./report.pdf submissions/此时这些路径会被解释为当前默认仓库下的路径。
repo:<library>/<path> 是有意义的,因为 Seafile 的文件定位天然依赖“仓库 + 仓库内路径”两段信息。
repo:<library> 在 upload 场景下也被支持,用来表示“上传到这个仓库根目录,并沿用本地文件名”。
而单独的 repo:<path> 在没有仓库名时是不完整的,因此不作为标准语法。
thufs info
thufs --json infothufs repos
thufs libraries
thufs --json reposthufs ls repo:course-lib/slides
thufs ls course-lib
thufs --json ls repo:course-lib/slidesls 的文件体积会自适应显示为 B、KB、MB、GB 等单位。
如果需要更新时间信息,可加 --time 或 -t。
thufs ls -t repo:course-lib/slides
thufs ls --time course-libthufs upload ./report.pdf repo:course-lib/submissions/report.pdf
thufs upload ./report.pdf repo:course-lib
thufs upload ./report.pdf submissions/说明:
- 如果目标写成
repo:course-lib,默认上传到仓库根目录,并使用本地文件名 - 如果目标以
/结尾且已配置默认仓库,如submissions/,也会默认使用本地文件名 - 如果目标 library 不存在,
upload会自动创建 library - 如果目标父目录不存在,
upload会自动创建远程目录 push是upload的兼容别名
thufs mkrepo course-lib
thufs mklib course-lib
thufs mkdir repo:course-lib/slides/week1
thufs mkdir submissions/week1thufs download repo:course-lib/slides/week1.pdf
thufs download repo:course-lib/slides/week1.pdf ./week1.pdf
thufs download repo:course-lib/slides/week1.pdf ./downloads/
thufs download https://cloud.tsinghua.edu.cn/f/abc123XYZ_/
thufs download "https://cloud.tsinghua.edu.cn/f/abc123XYZ_/?dl=1"
thufs download --share abc123XYZ_
thufs download --mode sequential repo:course-lib/slides/week1.pdf
thufs download --mode parallel --workers 8 repo:course-lib/slides/week1.pdf说明:
- 如果不写本地路径,默认保存到当前目录,并使用远程文件名
- 如果本地路径是已存在目录,则下载到该目录下并沿用远程文件名
- 也支持分享文件下载:可直接传完整分享链接,
?dl=1这类查询参数会被忽略,只提取其中的 token;或使用--share <hashcode> - 分享下载会根据当前登录状态决定身份:已配置 token 时会携带登录身份,未登录时按匿名下载处理,便于访问需要身份授权的分享链接
pull是download的兼容别名
thufs share repo:course-lib/slides/week1.pdf
thufs share --password secret --expire-days 7 repo:course-lib/slides/week1.pdf
thufs --json share repo:course-lib/slides/week1.pdf
thufs shares repo:course-lib/slides/week1.pdf
thufs shares --page 1 --per-page 50
thufs shares --all
thufs unshare <share-token>upload 和 download 统一支持:
--conflict <policy>可选策略:
uniquify自动生成不冲突的新文件名,如report-(1).pdfoverwrite覆盖已存在目标fail遇到冲突立即失败prompt显式进入交互式确认模式
默认策略:
uniquify
这意味着在未指定策略时,thufs 会尽量避免覆盖已有文件,并返回实际使用的最终路径。
示例:
thufs upload --conflict overwrite ./report.pdf repo:course-lib/submissions/report.pdf
thufs upload --conflict uniquify ./report.pdf repo:course-lib/submissions/report.pdf
thufs download --conflict fail repo:course-lib/slides/week1.pdf ./week1.pdf默认输出偏向人类阅读;传入 --json 后会输出结构化 JSON,更适合脚本处理。
例如:
thufs --json upload ./report.pdf repo:course-lib/submissions/report.pdf上传或下载结果中会包含类似这些字段:
requested_remote_pathfinal_remote_pathrequested_local_pathfinal_local_pathremote_namelocal_nameoverwrittenuniquified
因此脚本可以可靠判断:
- 最终是否发生自动重命名
- 最终保存到哪里
- 最终文件名是什么
示例:
FINAL_PATH="$(thufs --json download repo:course-lib/slides/week1.pdf | jq -r '.final_local_path')"
echo "saved to: $FINAL_PATH"- 在 stderr 为 TTY 时显示进度条
--progress jsonl会向 stderr 持续输出 JSON Lines 进度事件,适合 GUI、任务队列和脚本精确追踪百分比--progress none可关闭传输进度输出download会使用.thufs-part临时文件,并在服务器支持时尝试断点续传download默认使用单线程下载,避免在服务端 Range 支持不稳定时触发不必要的分片请求- 显式使用
--mode auto时会优先尝试并发分片下载;若自动模式下的 Range 分片请求失败,会清理临时文件并回退到单线程下载 - 自动回退会按进度模式报告为 warning:TTY 模式显示警告,
--progress jsonl输出warning事件,--progress none保持静默;显式--mode parallel仍会严格失败 upload会基于 Seafile 的 uploaded-bytes 机制进行尽力续传
机器可读进度示例:
thufs upload ./report.pdf repo:course-lib/submissions/report.pdf --progress jsonl
thufs download repo:course-lib/slides/week1.pdf ./week1.pdf --progress jsonl每行都是一个独立 JSON 事件,包含:
eventoperationpathtransferred_bytestotal_bytespercent
下载模式可通过以下参数显式控制:
--mode sequential默认行为,始终使用单线程下载--mode auto优先并发,不满足条件时自动退回单线程--mode parallel强制要求并发下载;若服务端不支持则报错--workers N指定并发下载的 worker 数,仅对并发下载生效
这类续传能力属于“best effort”,行为仍受服务端支持程度影响。
- 正常结果输出到 stdout
- 错误输出到 stderr
--json仅影响正常结果的格式,不改变错误流向
这保证了 thufs 更容易被 shell 管道、重定向、jq、xargs 等工具组合。
| 命令 | 作用 |
|---|---|
thufs info |
查看当前 token 对应账号信息 |
thufs repos |
列出当前可见仓库 |
thufs ls <remote> |
列出远程目录内容 |
thufs mkrepo <name> |
创建 library |
thufs mkdir <remote> |
创建远程目录 |
thufs upload <local> <remote> |
上传本地文件 |
thufs download <remote> [local] |
下载远程文件 |
thufs share <remote> |
创建分享链接 |
thufs shares [remote] |
分页查看分享链接,未指定 remote 时查看全部 |
thufs unshare <token> |
删除分享链接 |
thufs auth set-token <token> |
存储 token |
thufs config show |
查看当前生效配置 |
- 在 SSH 登录的服务器上直接备份实验结果
- 在集群作业结束后上传输出文件
- 在脚本中获取云盘上的输入数据
- 将云盘分享链接的创建纳入自动流程
- 快速浏览某个仓库下的资料而不打开网页
thufs 当前刻意不覆盖以下方向:
- 完整双向同步
- 递归目录上传或下载
- 多账号配置管理
- 任意 Seafile 实例的通用化接入
- GUI 或桌面常驻同步体验
如果你需要的是“稳定的命令工具”,这些边界是有意保留的;如果你需要“完整同步客户端”,那是另一类产品。
运行测试:
cargo test格式化代码:
cargo fmt查看帮助:
cargo run -- --help
cargo run -- upload --help
cargo run -- download --help- 当前实现基于 Seafile API 形态
- 某些服务端细节可能会因实际部署差异而存在边界行为
本项目采用 MIT License。
English documentation is available at README.en.md.