Initial release of bdrclone

2026-08-13 23:02:25 +08:00
commit d6d1956050
23 changed files with 3042 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,151 @@
+# bdrclone
+
+`bdrclone` 是面向百度网盘官方开放 API 的命令行和 FUSE 挂载客户端。它参考了
+rclone 的命令/VFS 语义和 OpenList 的百度驱动流程，但代码独立实现，只调用百度官方接口。
+
+已实现：
+
+- OAuth 授权码登录、过期自动刷新、token 原子持久化
+- `ls`、`stat`、`cat`、`mkdir`、`rm`、`mv`、`cp`、`quota`
+- 官方 dlink 下载、`User-Agent: pan.baidu.com`、HTTP Range 随机读取
+- MD5 秒传尝试、4/16/32 MiB 自动分片、多分片并发上传
+- Linux FUSE 挂载；macOS 使用 macFUSE/cgofuse 可选构建
+- 只读 HTTP 服务，支持单 Range 请求
+
+## 准备百度应用
+
+1. 在[百度网盘开放平台](https://pan.baidu.com/union/)完成开发者认证并创建“软件”应用。
+2. 在应用安全设置中加入回调地址：`http://127.0.0.1:53682/callback`。百度说明修改后最长约
+   1 小时生效。
+3. 记下应用的 AppKey (`client_id`) 和 SecretKey (`client_secret`)。
+
+不需要把应用提交上线审核即可授权自己的测试账号，但可用能力最终以百度控制台给应用开通的
+权限为准。
+
+## 构建
+
+需要 Go 1.24 或更高版本。
+
+```bash
+go build -o bdrclone ./cmd/bdrclone
+go test ./...
+```
+
+### macOS 挂载构建
+
+先安装 [macFUSE](https://osxfuse.github.io/)，再让 cgo 找到头文件和动态库：
+
+```bash
+brew install --cask macfuse
+CGO_CFLAGS="-I/usr/local/include/fuse" \
+CGO_LDFLAGS="-L/usr/local/lib -lfuse" \
+go build -tags cmount -o bdrclone ./cmd/bdrclone
+```
+
+Apple Silicon 上 macFUSE 的实际 include/lib 路径可能随版本变化；以安装包提供的路径为准。
+未加 `cmount` 标签的 macOS 构建仍包含全部 CLI/HTTP 功能，执行 `mount` 时会给出依赖提示。
+
+Linux 直接构建即可得到 FUSE 后端，运行时需要系统已安装 FUSE 设备和挂载工具。
+
+## 配置与授权
+
+```bash
+./bdrclone config \
+  --client-id '你的 AppKey' \
+  --client-secret '你的 SecretKey'
+
+./bdrclone auth
+```
+
+如果控制台尚未接受本机回调地址，可使用百度官方 OOB 模式。授权后，将百度页面显示的授权码
+粘贴回终端：
+
+```bash
+./bdrclone auth --oob
+```
+
+OOB 模式使用 `redirect_uri=oob`，无需在本机监听端口。
+
+默认配置文件：
+
+- macOS: `~/Library/Application Support/bdrclone/config.json`
+- Linux: `~/.config/bdrclone/config.json`
+
+配置文件以 `0600` 权限保存。可以用 `--config /path/config.json` 指定其他位置。
+
+只暴露网盘中的一个子目录：
+
+```bash
+./bdrclone config --root /我的资料
+```
+
+## 使用
+
+```bash
+./bdrclone ls /
+./bdrclone stat /文档/report.pdf
+./bdrclone download /文档/report.pdf ./report.pdf
+./bdrclone upload ./photo.jpg /备份/photo.jpg
+./bdrclone mkdir /备份/新目录
+./bdrclone mv /备份/a.txt /备份/b.txt
+./bdrclone cp /备份/b.txt /副本/b.txt
+./bdrclone rm /副本/b.txt
+# 目录删除必须显式确认递归语义；配置的根目录始终禁止删除
+./bdrclone rm --recursive /旧备份
+./bdrclone quota
+```
+
+挂载：
+
+```bash
+mkdir -p ~/BaiduNetdisk
+./bdrclone mount ~/BaiduNetdisk
+# 只读模式
+./bdrclone mount --read-only ~/BaiduNetdisk
+```
+
+挂载写入使用本地临时文件，文件关闭/flush 时整体分片上传。随机读取映射为官方 dlink 的 Range
+请求；随机写不是云端原地修改，而是“下载旧文件到缓存、修改、重新上传”。
+写回失败的临时内容会保留到用户缓存目录的 `bdrclone/failed-writes`，并在挂载进程的标准错误中
+打印恢复路径。
+
+HTTP 服务默认只监听本机：
+
+```bash
+./bdrclone serve --addr 127.0.0.1:8080
+curl http://127.0.0.1:8080/文档/report.pdf -o report.pdf
+```
+
+目录 URL 返回 JSON。不要在没有鉴权或反向代理保护的情况下监听公网地址。
+
+## 百度 API 限制
+
+- 百度网盘官方接口不允许创建空文件；挂载下的空文件在 flush 时会失败。
+- 大文件下载必须使用 `User-Agent: pan.baidu.com`，客户端已统一设置。
+- 分片大小由会员等级决定：普通用户 4 MiB、会员 16 MiB、超级会员 32 MiB；百度限制分片数，
+  因此不同等级的单文件上限不同。
+- `--upload-parts` 控制并发（默认 3）。低上行带宽遇到超时时建议设为 1。
+- dlink 是临时链接，每次打开文件会重新获取；不会把链接写入长期缓存。
+- 本程序只走官方接口，不实现 OpenList 文档中已经失效的 `crack`/`crack_video` 接口，也不会绕过
+  百度会员限速或开放平台权限。
+
+## 参考资料
+
+- [rclone](https://github.com/rclone/rclone)
+- [OpenList](https://github.com/OpenListTeam/openlist)
+- [OpenList 百度网盘驱动说明](https://doc.oplist.org/guide/drivers/baidu)
+- [百度授权码模式](https://pan.baidu.com/union/doc/%E4%BD%BF%E7%94%A8%E5%85%A5%E9%97%A8/%E6%8E%A5%E5%85%A5%E6%8E%88%E6%9D%83/%E6%8E%88%E6%9D%83%E7%A0%81%E6%A8%A1%E5%BC%8F/)
+- [百度文件列表](https://pan.baidu.com/union/doc/%E5%9F%BA%E7%A1%80%E7%BD%91%E7%9B%98%E6%9C%8D%E5%8A%A1/%E8%8E%B7%E5%8F%96%E6%96%87%E4%BB%B6%E4%BF%A1%E6%81%AF/%E8%8E%B7%E5%8F%96%E6%96%87%E4%BB%B6%E5%88%97%E8%A1%A8/)
+- [百度上传接口](https://pan.baidu.com/union/doc/%E5%9F%BA%E7%A1%80%E7%BD%91%E7%9B%98%E6%9C%8D%E5%8A%A1/%E4%B8%8A%E4%BC%A0/%E9%A2%84%E4%B8%8A%E4%BC%A0/)
+- [百度下载接口](https://pan.baidu.com/union/doc/%E5%9F%BA%E7%A1%80%E7%BD%91%E7%9B%98%E6%9C%8D%E5%8A%A1/%E4%B8%8B%E8%BD%BD/)
+
+## 开发验证
+
+测试使用本地模拟百度端点，不需要真实账号：
+
+```bash
+go test -race ./...
+go vet ./...
+```
+
+真实账号集成测试需要你自己的 AppKey/SecretKey 和授权 token，仓库不会保存这些凭据。