Some miscellaneous changes (#419)

* some miscellaneous changes

* fix(offline-download): the case issue of docker volume mapping path of qBittorrent

* feat(ftp-server): local proxy tip

Author: KirCute

docs/guide/advanced/ftp.md

@@ -20,6 +20,14 @@ star: true
 
 # FTP / SFTP
 
+::: tip
+
+所有在网页端管理页面对 FTP 相关配置进行的调整必须重启 AList 才会生效。
+
+使用 FTP 下载时只会使用本地代理。
+
+:::
+
 ## **FTP 配置文件**
 
 | 字段     | 含义 | 示例值                       |
@@ -37,31 +45,33 @@ star: true
 
 ## **FTP 设置**
 
-在了解 FTP 的设置选项前需要先了解 FTP 协议的工作方式，FTP 协议传输文件有“主动传输”和“被动传输”两种方式：
+在了解 FTP 的设置选项前需要先了解 FTP 协议的工作方式，FTP 协议使用**两个 TCP 连接**进行交互，它们分别被称为“**控制流**”和“**数据流**”，21 号端口是 FTP 协议的默认控制流端口号，FTP 服务器会持续监听这一端口号等待客户端的连接并给出响应，**控制流只传输客户端的请求指令和服务端的错误信息，不传输文件内容和文件列表**。在 AList 中，控制流端口号由配置文件内的`listen`参数确定，默认为 5221，客户端必须能够访问服务端的这一端口，协议才可以正常工作。
+
+而数据流的建立主要有两种方式，被称为“主动模式”和“被动模式”：
+
+在主动模式下，客户端主动监听一个端口，并通过`PORT`指令将端口号发送给服务端，服务端主动连接客户端并传输文件或文件列表。在这种模式下，客户端需要能够被服务端直接访问，因此在当前 NAT 普及的情况下几乎只有服务端和客户端处在同一子网内时才能发挥作用。
 
 ```mermaid
 ---
 title: 主动模式
 ---
 sequenceDiagram
-    客户端->>服务端: 发送PORT指令，携带客户端的IP地址和传输数据流的端口
-    服务端->>客户端: 主动连接客户端
+    客户端->>服务端: 控制流发送PORT指令，携带客户端的IP地址和数据流端口号
+    服务端->>客户端: 主动连接客户端，在新建立的连接（数据流）中传输文件或文件列表
 ```
 
-在主动模式下，客户端需要能够被服务端直接访问，因此在当前 NAT 普及的情况下几乎只有服务端和客户端处在同一子网内时才能发挥作用。
+在被动模式下，客户端首先在控制流中发送`PASV`或`EPSV`命令，要求服务端新监听一个数据流端口，服务端在控制流中向客户端返回新监听的端口的端口号，待客户端与该端口建立连接以后再进行数据传输。在这种模式下，服务端不主动向客户端发起连接，因此只需要服务端处在 NAT 之外即可，但因为被动传输的传输端口不是预先确定，而是在连接发起前才确定的，因此在面对服务端和客户端之间存在端口映射，或服务端仅有一部分端口允许客户端连接的复杂网络环境时就需要额外配置。
 
 ```mermaid
 ---
 title: 被动模式
 ---
 sequenceDiagram
-    客户端->>服务端: 发送PASV或EPSV指令
+    客户端->>服务端: 控制流发送PASV或EPSV指令
     服务端-->>客户端: 服务端的公网IP（仅PASV）和用于传输数据的被动传输端口号
-    客户端->>服务端: 向服务端返回的IP和端口发起TCP连接
+    客户端->>服务端: 向服务端返回的IP和端口发起TCP连接，在新建立的连接（数据流）中传输文件或文件列表
 ```
 
-在被动模式下，服务端不主动向客户端发起连接，因此只需要服务端处在 NAT 之外即可，但因为被动传输的传输端口不是预先确定，而是在连接发起前才确定的，因此在服务端和客户端之间存在端口映射的复杂网络环境时就需要额外配置。
-
 - FTP 服务端公网地址
 
   在`PASV`命令中服务端向客户端发送的 IP 地址，如果服务端和客户端在同一子网内，用服务端的内网 IP 地址也可以，甚至如果服务端和客户端是同一台主机，也可以使用`127.0.0.1`。但如果服务端和客户端不在同一子网内，则需要填写能够让客户端访问到的服务端 IP 地址。
@@ -120,7 +130,21 @@ sequenceDiagram
       端口映射->>服务端: 转发到2000端口
   ```
 
-  
+  如果服务器与客户端之间存在多层端口映射，`:`之前只需要填写最靠近客户端的端口号，之后只需要填写最靠近服务端的端口号即可，比如以下场景填写`2000:5000`：
+
+  ```mermaid
+  sequenceDiagram
+      participant 客户端
+      participant 内网穿透服务
+      participant 软路由端口转发
+      participant Docker 容器端口映射
+      participant AList 进程
+      
+      客户端->>内网穿透服务: 2000
+      内网穿透服务->>软路由端口转发: 3000
+      软路由端口转发->>Docker 容器端口映射: 4000
+      Docker 容器端口映射->>AList 进程: 5000
+  ```
 
 - FTP 代理 User-Agent 请求头
 

docs/guide/advanced/offline-download.md

@@ -35,7 +35,7 @@ Then find the offline download button in the lower right corner, and choose to u
 If you use **docker**, please map the following two default paths by yourself. (mapped to the same directory on the host machine)
 
 - **/opt/alist/data/temp/aria2**
-- **/opt/alist/data/temp/qbittorrent**
+- **/opt/alist/data/temp/qBittorrent**
 
 :::
 

docs/guide/api/task.md

@@ -20,12 +20,14 @@ star: true
 
 alist中的任务管理可以分为：
 
-| 接口名                     | 说明             |
-| -------------------------- | ---------------- |
-| /upload                    | 上传任务         |
-| /copy                      | 复制任务         |
+| 接口名                      | 说明           |
+| -------------------------- | ------------- |
+| /upload                    | 上传任务        |
+| /copy                      | 复制任务        |
 | /offline_download          | 离线下载任务     |
 | /offline_download_transfer | 离线下载转存任务 |
+| /decompress                | 解压任务        |
+| /decompress_upload         | 解压转存任务    |
 
 每种任务都有以下接口：
 
@@ -65,7 +67,7 @@ POST /api/task/upload/info
   "message": "success",
   "data": [
     {
-      "id": "1",
+      "id": "WC7gsoTr5CHkExN9dmyxs",
       "name": "upload 1.png to [/s](/test)",
       "creator": "admin",
       "creator_role": 2,
@@ -97,7 +99,7 @@ POST /api/task/upload/info
 | » message       | string   | true  | none | 信息             | none                            |
 | » data          | [object] | true  | none |                  | none                            |
 | »» id           | string   | false | none | id               | none                            |
-| »» name         | string   | false | none | 任务名           | none                            |
+| »» name         | string   | false | none | 任务名          | 任务的命名方式见本文末尾           |
 | »» creator      | string   | false | none | 任务创建者用户名 | none                            |
 | »» creator_role | integer  | false | none | 任务创建者角色   | 0: 普通用户，1: 访客，2: 管理员 |
 | »» state        | string   | false | none | 任务完成状态     | none                            |
@@ -128,7 +130,7 @@ GET /api/task/upload/done
   "message": "success",
   "data": [
     {
-      "id": "1",
+      "id": "WC7gsoTr5CHkExN9dmyxs",
       "name": "upload 1.png to [/s](/test)",
       "creator": "example_user",
       "creator_role": 0,
@@ -160,7 +162,7 @@ GET /api/task/upload/done
 | » message       | string   | true  | none | 信息             | none                            |
 | » data          | [object] | true  | none |                  | none                            |
 | »» id           | string   | false | none | id               | none                            |
-| »» name         | string   | false | none | 任务名           | none                            |
+| »» name         | string   | false | none | 任务名           | 任务的命名方式见本文末尾             |
 | »» creator      | string   | false | none | 任务创建者用户名 | none                            |
 | »» creator_role | integer  | false | none | 任务创建者角色   | 0: 普通用户，1: 访客，2: 管理员 |
 | »» state        | string   | false | none | 任务完成状态     | none                            |
@@ -191,7 +193,7 @@ GET /api/task/upload/undone
   "message": "success",
   "data": [
     {
-      "id": "1",
+      "id": "WC7gsoTr5CHkExN9dmyxs",
       "name": "upload 1.png to [/s](/test)",
       "creator": "guest",
       "creator_role": 1,
@@ -223,7 +225,7 @@ GET /api/task/upload/undone
 | » message       | string   | true  | none | 信息             | none                            |
 | » data          | [object] | true  | none |                  | none                            |
 | »» id           | string   | false | none | id               | none                            |
-| »» name         | string   | false | none | 任务名           | none                            |
+| »» name         | string   | false | none | 任务名           | 任务的命名方式见本文末尾            |
 | »» creator      | string   | false | none | 任务创建者用户名 | none                            |
 | »» creator_role | integer  | false | none | 任务创建者角色   | 0: 普通用户，1: 访客，2: 管理员 |
 | »» state        | string   | false | none | 任务完成状态     | none                            |
@@ -608,3 +610,36 @@ POST /api/task/upload/retry_some
 | » message | string   | true  | none | 信息     | none                                       |
 | » data    | object | true  | none |          | 不在此对象中的任务表示重试成功且无错误信息 |
 | »» 任务id | string   | false | none | 错误信息 | none                                       |
+## 备注
+
+### 任务的命名方式
+
+- 上传：
+  ```text
+  upload 文件名 to [驱动挂载点](驱动内路径)
+  ```
+- 复制：
+  ```text
+  copy [源文件驱动挂载点](源文件驱动内路径) to [目标驱动挂载点](目标驱动内路径)
+  ```
+- 离线下载：
+  ```text
+  download 文件名 to (目标路径)
+  ```
+- 离线下载转存：
+  - 驱动离线下载：
+    ```text
+    transfer [源文件驱动挂载点](源文件挂载点) to [目标驱动挂载点](目标驱动内路径)
+    ```
+  - 本地离线下载：
+    ```text
+    transfer [](源文件本地路径) to [目标驱动挂载点](目标驱动内路径)
+    ```
+- 解压：
+  ```text
+  decompress [源文件驱动挂载点](源文件驱动内路径)[压缩文件内部路径] to [目标驱动挂载点](目标驱动内路径) with password <解压密码>
+  ```
+- 解压转存：
+  ```text
+  upload 文件名 to [驱动挂载点](驱动内路径)
+  ```

docs/guide/drivers/github.md

@@ -45,6 +45,36 @@ The name of the repository. For example, if the URL of the repository is `github
 
 A branch, a tag or a commit SHA. Only when a branch name is filled in is the driver writable. It defaults to the default branch if not filled.
 
+## **Gh Proxy**
+
+Used to speed up downloading
+
+- Download the content of `Raw` and `archive` and change it to **https://gh-proxy.com/raw.githubusercontent.com**
+
+```bash title="Copy"
+https://gh-proxy.com/raw.githubusercontent.com
+```
+
+```bash title="Copy"
+https://ghfast.top/raw.githubusercontent.com
+```
+
+```bash title="Copy"
+https://ghproxy.net/raw.githubusercontent.com
+```
+
+## **GPG private key**
+
+GPG private key, used to provide commit verifications. Verified commits will be marked with a green "Verified" label on the GitHub webpage. Use the following command to obtain it. Leave blank if verifications are not needed.
+
+```bash
+gpg --export-secret-key -a <Key Pair ID>
+```
+
+## **GPG key passphrase**
+
+Passphrase to the GPG private key. Leave blank if there is none.
+
 ## **Committer name**
 
 Custom committer name, defaulting to the owner's of the token when not filled.
@@ -76,32 +106,6 @@ Custom commit message, supporting the following template variables：
 - `TargetName`: (when renaming) new name. (when copying and moving) the target folder name.
 - `TargetPath`: (when renaming) new path. (when copying and moving) the target path.
 
-<br/>
-
-
-
-## **Gh Proxy**
-
-Used to speed up downloading
-
-- Download the content of `Raw` and `archive` and change it to **https://gh-proxy.com/raw.githubusercontent.com**
-
-```bash title="Copy"
-https://gh-proxy.com/raw.githubusercontent.com
-```
-
-```bash title="Copy"
-https://ghfast.top/raw.githubusercontent.com
-```
-
-```bash title="Copy"
-https://ghproxy.net/raw.githubusercontent.com
-```
-
-
-
-<br/>
-
 ### **The default download method used**
 
 ```mermaid

docs/guide/drivers/s3.md

@@ -21,52 +21,65 @@ star: true
 
 S3 object storage protocols, such as COS, OSS, B2, etc.
 
-### **BucKet**
+## **Bucket**
 
 bucket name
 
-### **Endpoint**
+## **Endpoint**
 
 Endpoint address (If you don’t know, you can read the official documents below)
 
-### **Region**
+## **Region**
 
 area (If you don’t know, you can read the official documents below)
 
-### **Access key id**
+## **Access key id**
 
 Access key id
 
-### **Secret access key**
+## **Secret access key**
 
 Secret access key
 
 ## **Session token**
 
 Session token，Normally, the three-segment token needs to be used, and the two-segment token does not need to fill in this option.
 
-### **Root folder path**
+## **Custom host**
 
-Root path, if not filled, it defaults to the root directory.
+Custom cdn acceleration domain name
 
-### **Custom Host**
+## **Enable custom host presign**
 
-Custom cdn acceleration domain name
+When "Custom host" is left blank, this option does not function.
+
+When disabled: The returned URL does not include signature, which is suitable for cases where the custom host is a CDN.
 
-### **Sign url expire**
+When enabled: The returned URL includes signature, which is suitable for cases where the host and OSS are from the same data center, the Endpoint is an internal access domain within the data center, and the custom host is an external access domain.
+
+## **Sign url expire**
 
 The validity period of the signed download address is 4 hours by default. If a custom accelerated domain name is used, this option is invalid.
 
-### **Placeholder**
+## **Placeholder**
+
 The name of placeholder file.
 
-### **Force path style**
+## **Force path style**
+
 If enable ForcePathStyle, usually needed for minio.
 
-### **List object version**
+## **List object version**
+
 Refer to s3 sdk documents.
 
+## **Remove bucket**
+
+Remove bucket name from path when using custom host.
+
+## **Add filename to disposition**
 
+Add filename to Content-Disposition header.
 
 ## **Add object storage examples and official documents**
 

docs/guide/webdav.md

@@ -29,6 +29,8 @@ star: true
 
 - If you want to add, delete or modify files, you need to open `Webdav manage` permissions and also need `Make dir or upload`, `Delete`, `Rename`, `Move`, `Copy` and other permissions. You can selectively open them according to your needs.
 
+Besides, since v3.42.0, writing to WebDAV not only requires the `Webdav Manage` permission but also basic permissions such as `rename`, `delete`, and `copy`.
+
 :::
 
 <br/>