# 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 upload ~/ /备份/mac/
# 排除受保护目录和缓存；--exclude 可重复，支持 **
./bdrclone upload ~/ /备份/mac/ --exclude .Trash --exclude 'Library/Caches/**'
./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 时会失败。
- 目录上传会创建远端空目录，但会跳过无法读取的路径、符号链接、特殊文件及百度接口无法表示的空文件，并逐项提示。
- `upload --exclude` 使用相对于源目录的 glob；无 `/` 的规则匹配任意层级的文件名，`**` 可跨目录匹配。
- 大文件下载必须使用 `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，仓库不会保存这些凭据。