> For the complete documentation index, see [llms.txt](https://academy.shade.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.shade.inc/guides/guides-zh/she-zhi-he-qian-yi/tong-guo-rclone-pi-liang-qian-yi-shu-ju-dao-shade.md).

# 通过 Rclone 批量迁移数据到 Shade

如何通过 Rclone 将数据迁移到 Shade

### 高效处理数据迁移与传输

本指南介绍如何使用 rclone 将大量数据迁入或迁出您的 Shade 云盘。rclone 是一款功能强大的开源工具，支持多种不同的数据源。

### 下载 rclone

Shade 后端现已原生集成到 Rclone 中。您可以从 [rclone 官方下载页面](https://rclone.org/downloads/).

### 关于 rclone

[rclone](https://rclone.org/) 是一款功能强大的命令行程序，可用于管理云存储中的文件。它常被称为“云存储版 rsync”，支持 70 多家云存储服务提供商。

rclone 的常见用途包括：

* **同步和备份** 本地系统与云存储之间的文件
* **迁移数据** 从一家云服务提供商迁移到另一家
* **自动化工作流程** 通过计划任务执行同步和备份
* **管理大型文件传输** 支持断点续传和带宽控制
* **批量操作** 跨云服务复制、移动或删除文件

借助 Shade 的 rclone 后端，您可以利用 rclone 的所有强大功能，直接通过命令行操作 Shade 云盘。

### 配置

以下示例演示如何创建 Shade 配置。

首先， [创建免费账户](https://app.shade.inc/) 并选择套餐。

您需要登录账户，并在账户设置中获取 `API Key` 以及在已创建的云盘中获取 `Drive ID` 。

现在打开命令提示符或终端，切换到下载该文件的目录，然后运行

`./rclone config`\
\
（如果您使用的是 Mac，需要告知电脑此文件可以执行，因此请运行

`chmod +x rclone` )

然后按照以下交互式流程操作：

```
e) 编辑现有远程连接
n) 新建远程连接
d) 删除远程连接
r) 重命名远程连接
c) 复制远程连接
s) 设置配置密码
q) 退出配置
e/n/d/r/c/s/q> n

输入新远程连接的名称。
name> Shade

存储选项。
要配置的存储类型。
从下方列表中选择一个编号，或输入自定义值。
（滚动浏览列表并找到 Shade 选项；截至 2025 年 11 月 5 日，编号为 52）
[其他选项]
xx / Shade FS
   \ (shade)
[其他选项]
存储 > xx

选项 drive_id。
你的云端硬盘 ID，可在云端硬盘设置中查看。每个云端硬盘都必须单独创建 rclone 配置。
请输入一个值。
drive_id> [YOUR_ID]

选项 api_key。
你账户的 API 密钥。
请输入一个值。
api_key> [YOUR_API_KEY]

编辑高级配置？
y) 是
n) 否（默认）
y/n> n

配置完成。
选项：
- type: shade
- drive_id: [YOUR_ID]
- api_key: [YOUR_API_KEY]
保留此“Shade”远程端吗？
y) 是，没问题（默认）
e) 编辑此远程端
d) 删除此远程端
y/e/d> y

```

### 工作流示例：将文件复制到 Shade

配置好 Shade 远程端后，你可以轻松地将文件从本地文件系统复制到 Shade。以下是一个常见的工作流：

#### 将本地文件夹复制到 Shade

若要将本地系统中的文件夹复制到 Shade 云端硬盘：

```bash
./rclone copy /path/to/local/folder Shade:/destination/folder
```

例如，要将“Projects”文件夹复制到 Shade：

```bash
./rclone copy ~/Projects Shade:/Projects
```

此命令将：

* 将本地 Projects 文件夹中的所有文件复制到 Shade
* 保留文件夹结构
* 跳过已存在且未更改的文件
* 在传输过程中显示进度

#### 其他实用命令

**同步文件夹** （使目标与源完全一致，包括删除文件）：

```bash
./rclone sync ~/Projects Shade:/Projects
```

**检查将要复制的内容** 但不实际执行复制：

```bash
./rclone copy ~/Projects Shade:/Projects --dry-run
```

**复制时显示进度和统计信息**:

```bash
./rclone copy ~/Projects Shade:/Projects --progress --stats 1s
```

**列出 Shade 云端硬盘中的文件**:

```bash
./rclone ls Shade:/
```

### 替代方案：使用 rclone 的 S3 后端

如果你在 Shade 中使用 rclone，我们建议使用 [原生 Shade 后端](https://rclone.org/shade/) 以获得最佳体验。如果你已有基于 S3 的脚本或工作流，也支持使用 rclone 的通用 S3 后端，但这并非 rclone 推荐的连接方式。

1. 有关如何生成 S3 密钥并获取其访问密钥 ID 和秘密访问密钥，请参阅 [使用 Shade 的 S3 API](https://academy.shade.inc/developers/using-shades-s3-api).
2. 在 rclone 配置文件中添加一个 remote（运行 `./rclone config file` 以查找该文件）：

```
[ShadeS3]
type = s3
provider = Other
access_key_id = YOUR_ACCESS_KEY_ID
secret_access_key = YOUR_SECRET_ACCESS_KEY
endpoint = https://s3.shade.inc
region = us-east-1
no_check_bucket = true
```

3. 将你的 drive ID 用作 bucket 名称：

```bash
./rclone copy ~/Projects ShadeS3:YOUR_DRIVE_ID/Projects --progress
```

每个 bucket 都是一个现有的 Shade drive，因此不要尝试创建或删除 bucket。

### 标准选项

以下是 shade（Shade FS）特有的标准选项。

**注意：** 对于大多数用户，只需配置 `drive_id` 和 `api_key`。以下高级选项适用于特定用例，可保留默认值。

#### --shade-drive-id

你的云端硬盘 ID，可在云端硬盘设置中查看。每个云端硬盘都必须单独创建 rclone 配置。

属性：

* 配置项：drive\_id
* 环境变量：RCLONE\_SHADE\_DRIVE\_ID
* 类型：字符串
* 必需：是

#### --shade-api-key

你账户的 API 密钥。可在“设置 > API 密钥”中找到。

属性：

* 配置项：api\_key
* 环境变量：RCLONE\_SHADE\_API\_KEY
* 类型：字符串
* 必需：是

### 高级选项

以下是 shade（Shade FS）特有的高级选项。

#### --shade-endpoint

服务的端点。

通常留空。

属性：

* 配置项：endpoint
* 环境变量：RCLONE\_SHADE\_ENDPOINT
* 类型：字符串
* 必需：否

#### --shade-chunk-size

上传时使用的分块大小。

大于此大小的文件会按此大小分块上传。

请注意，每次传输都会将其存储在内存中，因此增大该值会增加内存用量。

最小值为 5MB，最大值为 5GB。

属性：

* 配置项：chunk\_size
* 环境变量：RCLONE\_SHADE\_CHUNK\_SIZE
* 类型：SizeSuffix
* 默认值：64Mi

#### --shade-encoding

后端使用的编码。

更多信息，请参阅 [概述中的编码部分](https://github.com/shade-labs/docs/blob/main/overview/README.md#encoding) 。

属性：

* 配置项：encoding
* 环境变量：RCLONE\_SHADE\_ENCODING
* 类型：Encoding
* 默认值：Slash,BackSlash,Del,Ctl,InvalidUtf8,Dot

#### --shade-description

远程端的描述。

属性：

* 配置项：description
* 环境变量：RCLONE\_SHADE\_DESCRIPTION
* 类型：字符串
* 必需：否

### Rclone 集成使用的 API 路由

以下路由供 rclone 集成使用，可直接与 Shade 文件系统交互。如果你想在自己的应用程序中直接使用这些路由，首先需要调用文档中“使用 API”部分“用户”一节里的相应路由来获取用户令牌。获取用户令牌后，请在请求中将其作为持有者令牌传递，而不是使用 API 密钥。

**注意：** rclone 后端会使用你的 API 密钥自动处理身份验证；只有在 rclone 之外构建自定义集成时，才需要考虑用户令牌。

## GET /{drive-id}/fs/listdir

> List directory contents for a given drive path

```json
{"openapi":"3.1.1","info":{"title":"Shade Rclone Routes","version":"0.0.0"},"paths":{"/{drive-id}/fs/listdir":{"get":{"tags":["drives"],"parameters":[{"name":"drive","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"query","required":true,"schema":{"type":"string"}},{"name":"authorization","in":"header","required":true,"schema":{"type":"string"}}],"operationId":"getByDriveFsListdir","summary":"List directory contents for a given drive path"}}}}
```

## GET /{drive-id}/fs/attr

> Get file or directory attributes/metadata

```json
{"openapi":"3.1.1","info":{"title":"Shade Rclone Routes","version":"0.0.0"},"paths":{"/{drive-id}/fs/attr":{"get":{"tags":["drives"],"parameters":[{"name":"drive","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"query","required":true,"schema":{"type":"string"}},{"name":"authorization","in":"header","required":true,"schema":{"type":"string"}}],"operationId":"getByDriveFsAttr","summary":"Get file or directory attributes/metadata"}}}}
```

## GET /{drive-id}/fs/download

> Download a file with optional content disposition

```json
{"openapi":"3.1.1","info":{"title":"Shade Rclone Routes","version":"0.0.0"},"paths":{"/{drive-id}/fs/download":{"get":{"tags":["drives"],"parameters":[{"name":"drive","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"query","required":true,"schema":{"type":"string"}},{"name":"disposition_type","in":"query","required":true,"schema":{"default":"attachment","type":"string"}},{"name":"authorization","in":"header","required":true,"schema":{"type":"string"}}],"operationId":"getByDriveFsDownload","summary":"Download a file with optional content disposition"}}}}
```

## POST /{drive-id}/fs/mkdir

> Create a directory at the specified path

```json
{"openapi":"3.1.1","info":{"title":"Shade Rclone Routes","version":"0.0.0"},"paths":{"/{drive-id}/fs/mkdir":{"post":{"tags":["drives"],"parameters":[{"name":"drive","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"query","required":true,"schema":{"type":"string"}},{"name":"authorization","in":"header","required":true,"schema":{"type":"string"}}],"operationId":"postByDriveFsMkdir","summary":"Create a directory at the specified path"}}}}
```

## POST /{drive-id}/fs/mkdir/batch

> Create multiple directories in a single request

```json
{"openapi":"3.1.1","info":{"title":"Shade Rclone Routes","version":"0.0.0"},"paths":{"/{drive-id}/fs/mkdir/batch":{"post":{"tags":["drives"],"parameters":[{"name":"drive","in":"path","required":true,"schema":{"type":"string"}},{"name":"authorization","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{},"required":true},"operationId":"postByDriveFsMkdirBatch","summary":"Create multiple directories in a single request"}}}}
```

## POST /{drive-id}/fs/copy-file

> Copy a file from one path to another

```json
{"openapi":"3.1.1","info":{"title":"Shade Rclone Routes","version":"0.0.0"},"paths":{"/{drive-id}/fs/copy-file":{"post":{"tags":["drives"],"parameters":[{"name":"drive","in":"path","required":true,"schema":{"type":"string"}},{"name":"from","in":"query","required":true,"schema":{"type":"string"}},{"name":"to","in":"query","required":true,"schema":{"type":"string"}},{"name":"authorization","in":"header","required":true,"schema":{"type":"string"}}],"operationId":"postByDriveFsCopy-file","summary":"Copy a file from one path to another"}}}}
```

## POST /{drive-id}/fs/move

> Move or rename a file or directory

```json
{"openapi":"3.1.1","info":{"title":"Shade Rclone Routes","version":"0.0.0"},"paths":{"/{drive-id}/fs/move":{"post":{"tags":["drives"],"parameters":[{"name":"drive","in":"path","required":true,"schema":{"type":"string"}},{"name":"from","in":"query","required":true,"schema":{"type":"string"}},{"name":"to","in":"query","required":true,"schema":{"type":"string"}},{"name":"authorization","in":"header","required":true,"schema":{"type":"string"}}],"operationId":"postByDriveFsMove","summary":"Move or rename a file or directory"}}}}
```

## POST /{drive-id}/fs/delete

> Delete a file or directory at the specified path

```json
{"openapi":"3.1.1","info":{"title":"Shade Rclone Routes","version":"0.0.0"},"paths":{"/{drive-id}/fs/delete":{"post":{"tags":["drives"],"parameters":[{"name":"drive","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"query","required":true,"schema":{"type":"string"}},{"name":"authorization","in":"header","required":true,"schema":{"type":"string"}}],"operationId":"postByDriveFsDelete","summary":"Delete a file or directory at the specified path"}}}}
```

## GET /{drive-id}/info/storage

> Fetch overall storage usage and limits

```json
{"openapi":"3.1.1","info":{"title":"Shade Rclone Routes","version":"0.0.0"},"paths":{"/{drive-id}/info/storage":{"get":{"tags":["drives"],"parameters":[{"name":"drive","in":"path","required":true,"schema":{"type":"string"}},{"name":"authorization","in":"header","required":true,"schema":{"type":"string"}}],"operationId":"getByDriveInfoStorage","summary":"Fetch overall storage usage and limits"}}}}
```

## GET /{drive-id}/info/upload

> Fetch upload configuration and constraints

```json
{"openapi":"3.1.1","info":{"title":"Shade Rclone Routes","version":"0.0.0"},"paths":{"/{drive-id}/info/upload":{"get":{"tags":["drives"],"parameters":[{"name":"drive","in":"path","required":true,"schema":{"type":"string"}},{"name":"authorization","in":"header","required":true,"schema":{"type":"string"}}],"operationId":"getByDriveInfoUpload","summary":"Fetch upload configuration and constraints"}}}}
```

## POST /{drive-id}/upload/multipart/part/{partNumber}

> Upload a specific part of a multipart upload

```json
{"openapi":"3.1.1","info":{"title":"Shade Rclone Routes","version":"0.0.0"},"paths":{"/{drive-id}/upload/multipart/part/{partNumber}":{"post":{"tags":["drives"],"parameters":[{"name":"drive","in":"path","required":true,"schema":{"type":"string"}},{"name":"partNumber","in":"path","required":true,"schema":{"type":"number"}},{"name":"token","in":"query","required":true,"schema":{"type":"string"}},{"name":"signAllEndpoints","in":"query","required":false,"schema":{"type":"string"}}],"operationId":"postByDriveUploadMultipartPartByPartNumber","summary":"Upload a specific part of a multipart upload"}}}}
```

## POST /{drive-id}/upload/multipart

> Initiate a multipart upload session

```json
{"openapi":"3.1.1","info":{"title":"Shade Rclone Routes","version":"0.0.0"},"paths":{"/{drive-id}/upload/multipart":{"post":{"tags":["drives"],"parameters":[{"name":"drive","in":"path","required":true,"schema":{"type":"string"}},{"name":"authorization","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{},"required":true},"operationId":"postByDriveUploadMultipart","summary":"Initiate a multipart upload session"}}}}
```

## POST /{drive-id}/upload/multipart/complete

> Complete a multipart upload by finalizing parts

```json
{"openapi":"3.1.1","info":{"title":"Shade Rclone Routes","version":"0.0.0"},"paths":{"/{drive-id}/upload/multipart/complete":{"post":{"tags":["drives"],"parameters":[{"name":"drive","in":"path","required":true,"schema":{"type":"string"}},{"name":"token","in":"query","required":true,"schema":{"type":"string"}},{"name":"authorization","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{},"required":true},"operationId":"postByDriveUploadMultipartComplete","summary":"Complete a multipart upload by finalizing parts"}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://academy.shade.inc/guides/guides-zh/she-zhi-he-qian-yi/tong-guo-rclone-pi-liang-qian-yi-shu-ju-dao-shade.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
