> 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/tong-guo-rclone-pi-liang-qian-yi-shu-ju-dao-shade.md).

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

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

这是一份指南，介绍如何使用 rclone 将大量数据迁入或迁出你的 Shade 驱动器。rclone 是一款功能强大的开源工具，支持多种不同来源。

### 下载 rclone

Shade 后端现已作为 Rclone 的原生功能提供。你可以从以下位置下载 rclone： [rclone 官方下载页面](https://rclone.org/downloads/).

### 关于 rclone

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

rclone 的常见用途包括：

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

借助 Shade 的 rclone 后端，你可以利用 rclone 的所有强大功能，直接从命令行与你的 Shade 驱动器交互。

### 配置

下面是一个创建 Shade 配置的示例。

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

你需要登录并获取 `API 密钥` 和 `驱动器 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 选项，截至 11/5/25 它是 52）
[其他选项]
xx / Shade FS
   \ (shade)
[其他选项]
Storage> 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:/
```

### 标准选项

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

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

#### --shade-drive-id

你的驱动器 ID，请在驱动器设置中查看。每个驱动器都必须单独创建 rclone 配置。

属性：

* 配置：drive\_id
* 环境变量：RCLONE\_SHADE\_DRIVE\_ID
* 类型：string
* 必需：true

#### --shade-api-key

你账户的 API 密钥。你可以在 Settings > API Keys 下找到它

属性：

* 配置：api\_key
* 环境变量：RCLONE\_SHADE\_API\_KEY
* 类型：string
* 必需：true

### 高级选项

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

#### --shade-endpoint

服务的端点。

通常留空。

属性：

* 配置：endpoint
* 环境变量：RCLONE\_SHADE\_ENDPOINT
* 类型：string
* 必需：false

#### --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
* 类型：string
* 必需：false

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

以下路由由 rclone 集成使用，以便直接与 Shade 文件系统交互。如果你想在自己的应用中直接使用这些路由，首先需要通过调用我们文档中“Using the API”部分的“Users”部分里的相应路由来获取用户令牌。拿到用户令牌后，请在请求中将其作为 bearer token 传递，而不是使用你的 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.