diff --git a/doc/design/file_manager/README.md b/doc/design/file_manager/README.md index 8d9c7487c52a270f88f661dda4a17b27c31cf6a3..2fe8fc28187986d724cddff52d81846eb8acffb6 100644 --- a/doc/design/file_manager/README.md +++ b/doc/design/file_manager/README.md @@ -1,47 +1,34 @@ # FileManager设计文档 ## 目标 -在本文档中,我们设计说明了名为FileManager系统,方便用户管理存放到PaddlePaddle Cloud上的文件。 +在本文档中,我们设计说明了名为FileManager系统,方便让用户上传自己的训练数据以进行分布式训练 主要功能包括: - 提供常用的命令行管理命令管理文件和目录 - - 支持的命令在[Here](./pfs/pfs.md) - 支持大文件的断点上传、下载 ## 名词解释 -- PFS:是Paddlepaddle cloud File System的简称,是对用户文件存储空间的抽象,与之相对的是local filesystem。目前我们用CephFS来搭建。 +- PFS:是`Paddlepaddle cloud File System`的缩写,是对用户文件存储空间的抽象,与之相对的是local filesystem。目前我们用CephFS来搭建。 - [CephFS](http://docs.ceph.com/docs/master/cephfs/):一个POSIX兼容的文件系统。 - Chunk:逻辑划上文件分块的单位。 -- [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/):提供七层协议的反向代理、基于粘性会话的负载均衡。 ## 模块 - ### 架构图 ### PFSClient -- 功能: 详细的内容看 +- 功能: 详细设计[link](./pfs/pfsclient.md) - 提供用户管理文件的命令 - - 用Go写,可以跨平台执行 + - 需要可以跨平台执行 - 双向验证 PFSClient需要和Ingress之间做双向验证[tls](#tls),所以用户需要首先在`cloud.paddlepaddle.org`上注册一下,申请用户空间,并且把系统生成的CA(certificate authority)、Key、CRT(CA signed certificate)下载到本地,然后才能使用PFSClient。 - -- 命令格式 - -``` -paddle [options] pfs [parameters] - -options: - -``` - -### Ingress + +### [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) - 功能: 提供七层协议的反向代理、基于粘性会话的负载均衡功能。 - 透传用户身份的办法 - Ingress需要把PFSClient的身份信息传给FileServer,配置的方法参考[Here](http://www.integralist.co.uk/posts/clientcertauth.html#3) - + Ingress需要把PFSClient的身份信息传给PFSServer,配置的方法参考[link](http://www.integralist.co.uk/posts/clientcertauth.html#3) ### PFSServer PFSServer提供RESTful API接口,接收处理PFSClient端的文件管理请求,并且把结果返回PFSClient端。 @@ -65,7 +52,7 @@ RESTful API ## 文件传输优化 ### 分块文件传输 -用户文件可能是比较大的,上传到Cloud或者下载到本地的时间可能比较长,而且在传输的过程中也可能出现网络不稳定的情况。为了应对以上的问题,我们提出了Chunk的概念,一个Chunk由所在的文件偏移、数据、数据长度及校验值组成。文件数据内容的上传和下载都是都过Chunk的操作来实现的。由于Chunk比较小(默认256K),完成一个传输动作完成的时间也比较短,不容易出错。PFSClient在传输完毕最后一个Chunk的时候检查destination文件的MD5值是否和source文件一致。 +用户文件可能是比较大的,上传到Cloud或者下载到本地的时间可能比较长,而且在传输的过程中也可能出现网络不稳定的情况。为了应对以上的问题,我们提出了Chunk的概念,一个Chunk由所在的文件偏移、数据、数据长度及校验值组成。文件数据内容的上传和下载都是都过Chunk的操作来实现的。由于Chunk比较小(默认256K),完成一个传输动作完成的时间也比较短,不容易出错。PFSClient需要在传输完毕最后一个Chunk的时候检查destination文件的MD5值是否和source文件一致。 一个典型的Chunk如下所示: @@ -84,8 +71,11 @@ type Chunk struct { ### 覆盖不一致的部分 文件传输的的关键在于需要PFSClient端对比source和destination的文件Chunks的checksum是否保持一致,不一致的由PFSClient下载或者传输Chunk完成。这样已经传输成功的部分就不用重新传输了。 +## 用户使用流程 +参考[link](https://github.com/PaddlePaddle/Paddle/blob/develop/doc/design/cluster_train/data_dispatch.md) + ## 框架生成 -用[swagger-api](https://github.com/swagger-api/swagger-codegen)生成Client和FileServer的框架部分,以便我们可以把更多的精力放到逻辑本身上。 +用[swagger](https://github.com/swagger-api/swagger-codegen)生成PFSClient和PFSServer的框架部分,以便我们可以把更多的精力放到逻辑本身上。 ## 参考文档 - [TLS complete guide](https://github.com/k8sp/tls/blob/master/tls.md) diff --git a/doc/design/file_manager/pfs/pfsclient.md b/doc/design/file_manager/pfs/pfsclient.md index dd4578e3696305109228d402a8ac4617dd157115..307d6b448f0d834cead9d9b4319db94d29db8f5a 100644 --- a/doc/design/file_manager/pfs/pfsclient.md +++ b/doc/design/file_manager/pfs/pfsclient.md @@ -1,4 +1,4 @@ -# PFS Client +# PFSClient ## Description The `pfs` command is a Command Line Interface to manage your files on PaddlePaddle Cloud @@ -28,8 +28,11 @@ paddle [options] pfs [parameters] ## Path Arguments When using a command, we need to specify path arguments. There are two path argument type: `localpath` and `pfspath`. + A `pfspath` begin with `/pfs`, eg: `/pfs/$DATACENTER/home/$USER/folder`. +[Here](https://github.com/PaddlePaddle/Paddle/blob/develop/doc/design/cluster_train/data_dispatch.md#上传训练文件) is how to config DataCenter + ## order of Path Arguments Commonly, if there are two path arguments, the first is the source, and the second is the destination. @@ -42,7 +45,7 @@ Synopsis: Options: -r - remove directories and their contents recursively + Remove directories and their contents recursively -v Cause rm to be verbose, showing files after they are removed. @@ -86,7 +89,7 @@ Synopsis: Options: -r Copy directories recursively - -f + -f Do not prompt for confirmation before overwriting the destination path. (The -f option overrides previous -n options.) -n Do not overwrite an existing file. (The -n option overrides previous -f options.) @@ -94,6 +97,10 @@ Options: Cause cp to be verbose, showing files after they are copied. --preserve--links Reserve links when copy links + +Examples: + paddle pfs cp ./file /pfs/$DATACENTER/home/$USER/file + paddle pfs cp /pfs/$DATACENTER/home/$USER/file ./file ``` - ls- list files