# 网盘与 OAuth (/zh/docs/channels/cloud-drives)

需要授权的网盘有哪些、两条授权路径怎么走、令牌如何续期与落库，国内网盘如何经自部署的聚合服务以 WebDAV 接入，以及网盘渠道的固有限制。

## 支持的网盘 [#支持的网盘]

「新建渠道」选类型时，「网盘」分组里除了通用 [WebDAV](./object-storage.mdx) 之外，还有 6 个需要 OAuth 授权的模板：

| 模板 | rclone 后端 | 专属字段 |
|---|---|---|
| OneDrive | `onedrive` | 区域 |
| Google Drive | `drive` | — |
| Dropbox | `dropbox` | — |
| pCloud | `pcloud` | 数据区域 |
| Box | `box` | — |
| Yandex Disk | `yandex` | — |

专属字段之后，6 个模板都依次是「应用 Client ID」「应用 Client Secret」「授权」「存储目录」：

- **区域**（OneDrive）：「国际版」「美国政府云」「德国云」「中国世纪互联」，决定授权与接口端点，要与账号所属区域一致。
- **数据区域**（pCloud）：「美国」或「欧洲」，要与注册账号时所选区域一致，否则换取令牌失败。
- **应用 Client ID / 应用 Client Secret**：在服务商开放平台自建的 OAuth 应用的标识与密钥。一键授权必须先填 Client ID；粘贴令牌时，令牌若是用自建应用取得的，也要填这两栏；用 rclone 内置应用取得的令牌两栏留空。令牌续期用的就是这两项，必须与签发令牌的应用一致。两者随渠道配置加密保存，编辑时显示为掩码。
- **授权**：令牌，由下面两条授权路径之一填入，未授权不能保存。
- **存储目录**：网盘里存放图片的目录，默认提示 `imgyoung`；留空存放在根目录。

授权所需的端点、权限范围与 rclone 内置的应用标识都取自 rclone 后端自身的注册信息，ImgYoung 不为各家单独编码。

**OneDrive 的驱动器**：拿到新的授权后，保存或测试连接时，ImgYoung 按 rclone 自身的配置流程走完授权之后的步骤，每一问都取默认答案：选定账号的默认驱动器，写下 `drive_id` 与 `drive_type`，与 `rclone config` 逐题取默认值时的选择一致。向服务商查询失败时，保存返回 400，测试连接显示原因。编辑时沿用已存授权，不会重新选择。要用 SharePoint 文档库或其他驱动器，见[OneDrive 的其他驱动器](#onedrive-的其他驱动器)。

**pCloud 的令牌**：pCloud 的令牌永不过期（到期时刻为零值），不带刷新令牌，照常可以保存。

## 授权方式一：粘贴令牌 [#授权方式一粘贴令牌]

在任意一台有浏览器的电脑上用 rclone 取得令牌，再粘贴到表单。ImgYoung 所在的服务器不需要公网域名，这是没有域名的部署唯一可行的方式。

<Steps>
<Step>
在有浏览器的电脑上安装 rclone，执行表单里提示的命令（以 Google Drive 为例）：

```bash title="终端"
rclone authorize "drive"
```

浏览器会打开服务商的登录与授权页，完成授权。
</Step>
<Step>
终端输出形如：

```text
Paste the following into your remote machine --->
{"access_token":"…","token_type":"Bearer","refresh_token":"…","expiry":"…"}
<---End paste
```

把两行标记之间的内容整段复制。
</Step>
<Step>
在表单的「授权」一栏切到「粘贴令牌」，粘贴进去，填好其余字段，点「测试连接」后保存。
</Step>
</Steps>

- 令牌 JSON 与 rclone 编码后的配置串（`rclone authorize` 带配置串参数时的输出）都能识别，ImgYoung 从中取出令牌。
- 会过期的令牌必须带刷新令牌，否则访问令牌过期后无法续期，保存时返回 `渠道参数非法: 缺少刷新令牌,访问令牌过期后无法续期(字段 token)`；永不过期的令牌（如 pCloud）不需要。内容无法解析时返回 `渠道参数非法: 令牌格式非法(字段 token)`。
- `rclone authorize "<后端名>"` 取得的令牌由 rclone 内置应用签发，「应用 Client ID」「应用 Client Secret」留空，rclone 续期时同样用内置应用。
- 想用自建应用，执行 `rclone authorize "<后端名>" <Client ID> <Client Secret>`（自建应用要登记 rclone 的本机回调地址 `http://127.0.0.1:53682/`），再把同一个应用的 Client ID 与 Client Secret 填进表单。

## 授权方式二：后台一键授权 [#授权方式二后台一键授权]

在后台里直接走完 OAuth 授权码流程。它要求自建应用，因为 OAuth 的回调地址必须事先在服务商处登记，而 rclone 内置应用登记的只有本机回环地址，浏览器回调打不到远程服务器。

<Steps>
<Step>
在「设置 → 运行配置 → 访问与链接 → 对外站点地址」填好 ImgYoung 的对外地址，如 `https://img.example.com`。未填写时，发起授权返回 `一键授权需先在设置中填写对外站点地址;或改用粘贴令牌方式`。
</Step>
<Step>
到服务商的开放平台创建应用，把回调地址登记为对外站点地址加固定路径：

```text
https://img.example.com/api/admin/channel-oauth/callback
```

两边必须逐字符一致（协议、域名、端口、路径都算）。
</Step>
<Step>
在表单里「授权」一栏上方的「应用 Client ID」「应用 Client Secret」填好自建应用的凭证，再在「授权」一栏的「一键授权」里点「前往授权 …」。没填 Client ID 时这个按钮不可用。浏览器会新开一页进入服务商授权页。
</Step>
<Step>
授权完成后回调页显示「授权成功，请回到后台继续。」，表单的「授权」一栏变为「已授权」，保存即可。
</Step>
</Steps>

- 回调接口要求管理员登录态，授权要在**已登录后台的同一个浏览器**里完成。
- 一次授权会话 10 分钟内有效，表单最多等待约 11 分钟，超时提示「等待授权超时，请重新发起」。
- 令牌不写进回调页面，由表单凭一次性标识领取，只能领取一次。
- 换取令牌失败时表单显示 `换取令牌失败,请核对应用凭证与回调地址`；在服务商页面拒绝或取消时显示 `授权被拒绝或取消:` 加服务商返回的原因。
- 编辑已有渠道时重新授权，应用凭证两栏保持掩码即沿用已存的值。
- Client ID 与 Client Secret 随渠道保存，令牌到期后 rclone 用同一个应用续期。

## 令牌续期与落库 [#令牌续期与落库]

- 后端参数以映射直接交给 rclone，映射上挂了写回回调。访问令牌临近过期时，rclone 自己刷新，并通过回调写回新令牌；ImgYoung 立即用主密钥加密并存入渠道配置。rclone 在运行中写回的其他参数也走同一条路径。
- 落库失败只记日志（`后端写回参数无法落库`），内存里继续使用新令牌；进程重启后会退回元数据库里的旧令牌。
- 保存渠道时临时构造的后端如果刷新了令牌，新令牌随配置一起落库。
- 测试连接时令牌被刷新，分两种情况：
  - 沿用的已存令牌（编辑时「授权」一栏保持「已授权 · 沿用已存令牌」）被刷新，新令牌直接写回该渠道。
  - 本次表单里提交的令牌被刷新（测试失败时也可能发生），新令牌交还给表单：测试结论下方提示「服务商在测试时刷新了授权令牌，表单已换用新令牌，保存时提交的就是它；原令牌可能已失效。」，「授权」一栏显示「已授权」，之后保存提交的就是新令牌。自定义模式下新令牌写进后端参数的 `token` 一行。
- **只有一个刷新者**：ImgYoung 不另设刷新循环。有些服务商每次刷新都会作废旧的刷新令牌，两个刷新者会互相作废对方的令牌。周期轻探测（默认每 60 秒）发出的只读请求足以让 rclone 按时刷新。
- 编辑网盘渠道时，「授权」一栏显示「已授权 · 沿用已存令牌」，保持不动即沿用；点「重新授权」可以换一个令牌。
- [导出的 rclone 配置文件](./encryption.mdx)里也带着令牌。ImgYoung 仍在使用该渠道时不要拿这个文件去用：Box 这类服务商的刷新令牌只能用一次，两边会互相作废对方的令牌。ImgYoung 刷新令牌之后，文件里的令牌就过时了，需要重新导出。

<Callout type="warn" title="保存失败时刷新出的令牌会丢失">
创建或编辑渠道时，如果保存最终失败（参数非法、试构造失败、OneDrive 选定驱动器时查询失败、渠道名重复等），保存过程中服务商刷新出的新令牌既不落库，也不交还表单。对 Box 这类刷新令牌只能用一次的服务商，原令牌随之作废，只能重新授权。先点「测试连接」再保存能降低这种风险：测试时刷新出的令牌会交还表单，保存时用的已是新令牌。
</Callout>

## OneDrive 的其他驱动器 [#onedrive-的其他驱动器]

模板只会选定账号的默认驱动器。要用 SharePoint 文档库或其他驱动器，在「新建渠道 → 高级 → 自定义」里手填 `drive_id` 与 `drive_type`。

先在有浏览器的电脑上用 `rclone config` 交互地新建一个 OneDrive remote，在选择驱动器的步骤里选中目标驱动器，再查看它写下的参数：

```bash title="终端"
rclone config
rclone config show onedrive-tmp
```

把输出里的值填进自定义表单：

| 键 | 值 |
|---|---|
| rclone 驱动 | `onedrive` |
| `token` | `rclone config show` 输出的 `token` |
| `drive_id` | 同上 |
| `drive_type` | 同上（`personal`、`business` 或 `documentLibrary`）|
| `region` | 非国际版账号才需要：`us`、`de` 或 `cn` |
| `client_id`、`client_secret` | 只在 rclone 里用了自建应用时需要 |
| `path` | 存放图片的目录，如 `imgyoung` |

自定义模式里令牌原样保存，需要重新授权时替换 `token` 的值。保存后删除本机的临时 remote，避免两处同时刷新同一个令牌：

```bash title="终端"
rclone config delete onedrive-tmp
```

## 国内网盘：经自部署的聚合服务以 WebDAV 接入 [#国内网盘经自部署的聚合服务以-webdav-接入]

rclone 没有阿里云盘、百度网盘、115、夸克等国内网盘的后端。能对接它们的开源聚合服务（如 Alist 一类）采用 AGPL-3.0 许可证：把它们的代码移植进 ImgYoung，会让本项目整体被迫转为 AGPL，还要长期自行跟进这些网盘的接口与风控变化。

因此 ImgYoung 不移植，而是由你自行部署这类聚合服务、让它对外提供 WebDAV，ImgYoung 用通用 WebDAV 模板接入。两者是独立进程、只通过网络协议交互，许可证不会传染，网盘接口的维护也留在上游。

<Steps>
<Step>
按聚合服务自己的文档部署它，挂载要用的网盘，并开启 WebDAV。
</Step>
<Step>
为 ImgYoung 建一个专用账号，给它读、写、删除权限。深探测、每日对账与渠道清理都要删除对象，缺删除权限的渠道无法通过深探测。
</Step>
<Step>
在 ImgYoung 新建 WebDAV 渠道：「服务地址」填聚合服务的 WebDAV 地址（Alist 为 `https://域名/dav/`），「服务类型」选「其他（坚果云 / Alist / 群晖等）」，填账号密码；「存储目录」填该网盘在聚合服务里的挂载路径下的一个专用目录。
</Step>
<Step>
点「测试连接」确认写、读、删都通过，再设一个低于对象存储渠道的优先级，保存。
</Step>
</Steps>

## 网盘渠道的固有限制 [#网盘渠道的固有限制]

- **恒走代理**：网盘普遍不提供稳定的公开直链，网盘模板没有「公开访问地址」，表单也不显示「允许 302 直链」与「自动创建存储桶」。即使访问模式是 `redirect`，网盘上的图片也经 ImgYoung 代理输出。
- **频率与流量限制**：网盘对请求频率与流量的限制远严于对象存储，图片访问量大时容易被限流或触发风控。周期轻探测会对每个渠道每轮发一次只读请求。
- **全量镜像**：与其他渠道一样，网盘渠道最终要存下全站全部图片。

因此网盘更适合作**低优先级的备份渠道**：把它的优先级设得低于对象存储渠道，平时只承接异步补齐；主渠道异常时，访问才会切到它。这一取舍完全通过优先级表达，见[渠道与容灾](./index.mdx)。