开源网盘系统推荐 - 开源云盘 - 安装及开发教程_eyebluetank

开源网盘系统推荐 - 开源云盘 - 安装及开发教程

 

云盘界面

 

介绍

本开源云盘致力于打造成一个优雅，好用，高效，克制的开源云盘。

在线体验 (账号demo/123456)

 

软件架构

本开源云盘采用前后端分离的模式开发。后端使用Golang语言，前端采用Vue框架；前端打包后的静态文件夹放置于后端/html目录下，后端对前后端资源做统一路由。

eyebluecn/tank 

eyebluecn/tank-front

 

特色

• 支持Docker安装
• 安装包仅10M左右，跨平台支持。windows, linux, macOS均提供安装包
• 支持 文件上传，文件预览，文件下载，聚合下载，提取码分享
• 提供编程接口，可以当作网站的第三方文件存储器
• 支持图片缓存，可使用参数对图片进行处理
• 支持多用户，支持用户空间限制
• 支持简体中文和英文

 

Todo

本开源云盘仍然处于持续迭代中，以下特性还不支持，但是已经在开发计划中：

• 支持Sqlite
• 支持文件混合预览，增强对常见文件的预览能力

 

加入讨论区

加入钉钉群可以体验最新Beta版本，你的任何合理需求，我都会尽量满足

 

安装

Linux

基本步骤

1. 安装MySQL，并创建一个数据库(使用UTF-8编码，否则不能存储中文)
2. 下载最新版本的开源云盘，去下载
3. 解压，运行根目录下tank

./tank

     打开 http://127.0.0.1:6010 看到安装引导页面即表示软件安装成功。接着按照UI引导安装开源云盘即可。

更多的运行方法

1. 文件tank是可执行文件，可以直接运行，如步骤3所示。

2. 如果你只是简单地希望开源云盘常驻后台运行，请使用根目录service文件夹下的脚本文件。

# 启动系统
./startup.sh
# 停止系统
./shutdown.sh

[推荐] 如果你希望开机启动云盘，或者可以使用系统的systemctl或service来控制开源云盘。

• 在/etc/systemd/system/下创建tank.service文件

vim /etc/systemd/system/tank.service

• tank.service的内容如下所示，其中ExecStart根据实际情况指定tank可执行文件

[Unit]
Description=EyeblueTank
Documentation=https://tank-doc.eyeblue.cn
Wants=network.target
After=network.target
 
[Service]
Type=simple
DynamicUser=yes
ExecStart=/data/program/tank/tank
Restart=always
RestartSec=3
 
[Install]
WantedBy=multi-user.target

• 装载tank服务，并启动（停止）开源云盘

# 装载tank服务
systemctl daemon-reload
# 设置tank开机启动
systemctl enable tank.service
# 查看tank状态
systemctl status tank.service
# 启动tank
systemctl start tank.service
# 重启tank
systemctl restart tank.service
# 停止tank
systemctl stop tank.service

 

Windows

1. 安装MySQL，并创建一个数据库(使用UTF-8编码，否则不能存储中文)
2. 下载最新版本的开源云盘，去下载
3. 解压，双击根目录下的tank.exe运行
4. 打开 http://127.0.0.1:6010 看到安装引导页面即表示软件安装成功。接着按照UI引导安装开源云盘即可。

 

MacOS

基本步骤

1. 安装MySQL(使用UTF-8编码)
2. 下载最新版本的开源云盘，去下载
3. 解压，运行根目录下tank

./tank

     打开 http://127.0.0.1:6010 看到安装引导页面即表示软件安装成功。接着按照UI引导安装开源云盘即可。

更多的运行方法

1. 文件tank是可执行文件，可以直接运行，如步骤3所示。

2. 如果你只是简单地希望开源云盘常驻后台运行，请使用根目录service文件夹下的脚本文件。

# 启动开源云盘
./startup.sh
# 停止开源云盘
./shutdown.sh

 

Docker

1. Docker中启动mysql

docker run --name dockermysql -p 13306:3306 -e MYSQL_ROOT_PASSWORD=123456 -e MYSQL_DATABASE=tank -e MYSQL_USER=tank -e MYSQL_PASSWORD=tank123 -v ~/data/dockermysql:/var/lib/mysql -d mysql:5.7

提示

容器名称为dockermysql，占用宿主13306端口，root密码123456，创建了一个tank数据库，用户名tank，密码tank123 ，将文件挂载于宿主的~/data/dockermysql文件夹。

1. Docker中启动开源云盘，x.x.x使用最新版本，参考这里

docker run --name tank -p 6010:6010 --link dockermysql:mysql -v ~/data/dockermatter:/data/build/matter -d eyeblue/tank:x.x.x

提示

容器名称为tank，占用宿主6010端口，链接数据库为mysql，即通过mysql可以访问到步骤1中mysql的地址，将文件挂载于宿主的~/data/dockermatter文件夹。

1. 打开 http://127.0.0.1:6010 看到安装引导页面即表示软件安装成功。

提示

MySQL Host => mysql
 
MySQL 端口 => 3306
 
MySQL 库名 => tank
 
MySQL 用户名 => tank
 
MySQL 密码 => tank123

 

自行编译

 

前端项目打包

1. clone  eyebluecn/tank-front

2. 安装依赖项

npm install

执行打包命令

npm run build

通过前面三步可以在dist文件夹下得到打包后的静态文件，将dist目录下的所有文件拷贝到后端项目的build/html文件夹下。

 

后端项目打包

1. clone  eyebluecn/tank

2. 安装Golang，配置环境变量GOPATH （因为使用go module，所以对GOPATH路径没有要求）

3. 打包

• windows平台双击运行 tank/build/pack/build.bat，成功之后可在tank/dist下看到tank-x.x.x文件夹，该文件夹即为最终安装包。

• linux平台运行如下命令：

cd tank/build/pack/
./build.sh

成功之后可在tank/dist下看到tank-x.x.x.linux-xxx.tar.gz

利用得到的安装包即可参考安装一节进行安装。

 

提示

如果你在安装依赖时，发现速度太慢，那么可以尝试修改脚本中的GOPROXY，常用的GOPROXY值有：

https://athens.azurefd.net
https://goproxy.io
https://goproxy.cn

 

软件下载

3.0.6

3.0.5

3.0.4

3.0.3

3.0.2

3.0.0

 

命令行工具

开源云盘提供了很多实用的命令行工具，tank(或者tank.exe)文件本质上就是一个可执行文件，可以接受参数，当我们输入一定的参数时，就可以把它当成命令行工具使用。

 

准备条件

在使用命令行工具时，请首先启动开源云盘。因为命令行工具本质上去调用开源云盘的http接口

 

查看版本

查看当前开源云盘版本

./tank -mode=version

 

映射本地文件映射

将本地文件映射到开源云盘中

./tank -mode=mirror -username=YourUsername -password=YourPassword -src=SourcePath -dest=DestPath [-host=EyeblueTankHost]

提示

YourUsername => 超级管理员的用户名

YourPassword => 超级管理员的密码

SourcePath => 想要映射的本地文件夹，例如：/data/temp

DestPath => 开源云盘的文件夹，例如 /morning

-host => 可以指定开源云盘地址，默认使用 http://127.0.0.1:6010

 

拉取远程文件

将一个远程文件拉取到开源云盘中

./tank -mode=crawl -username=YourUsername -password=YourPassword -src=SourcePath -dest=DestPath

提示

YourUsername => 超级管理员的用户名
YourPassword => 超级管理员的密码
SourcePath => 远程的资源文件，一般是http://或者https://开头
DestPath => 开源云盘的文件夹，例如 /morning

 

版本迁移

 

2.0.x迁移到3.0.x版本

由于2.0.x文件目录的结构按照时间戳顺序进行组织，3.0.0按照和开源云盘中一致的物理目录组织，因此导致文件存放的结构不一致。为了让2.0.0的用户更优雅的使用3.0.x版本，作者特意写了一个迁移工具，按照以下步骤进行迁移。

 

准备条件：

1. 停止tank2.0.x
2. 安装好tank3.0.x，即至少已经有一个超级管理员了。
3. 2.0.x和3.0.x使用同一个数据库
4. 执行以下迁移命令，其中YourUsername和YourPassword是指开源云盘3.0.x的超级管理员账号密码。Tank2.0MatterPath是指2.0.x版本的MatterPath，可以在tank.conf文件中找到，如果这个字段为空，例如2.0.x的安装目录为/data/tank2.0，那么就使用/data/tank2.0/matter。

cd tank 3.0.x安装目录
./tank -mode=migrate20to30 -username=YourUsername -password=YourPassword -src=Tank2.0MatterPath

迁移时间长短会和你的文件多少有关，请耐心等待，如果要想查看迁移过程日志：

cd tank 3.0安装目录
tail -f ./log/tank.log

迁移完毕后，所有2.0.x的用户名后会加上_20.

 

Webdav

访问地址

https://tank.eyeblue.cn/api/dav

(以官方开源云盘为例)

 

使用单独的域名作为WebDAV地址

如果你想去掉 /api/dav 的后缀，并且使用其他域名作为WebDAV的访问地址，你可以参考以下的nginx配置：

#https://tank-dav.eyeblue.cn
server{
        listen 443 ssl;
        server_name tank-dav.eyeblue.cn;
 
        ssl on;
        ssl_certificate /data/security/letsencrypt/eyebluecn/full_chain.pem;
        #private key
        ssl_certificate_key /data/security/letsencrypt/eyebluecn/private.key;
 
        location / {
                rewrite /(.*) /api/dav/$1 break;
                proxy_pass http://127.0.0.1:6010;
                proxy_set_header host $host;
                proxy_set_header X-Forwarded-For $remote_addr;
                proxy_pass_request_headers      on;
                client_max_body_size  2048m;
        }
}
 
#http://tank-dav.eyeblue.cn
server {
        listen      80;
        server_name    tank-dav.eyeblue.cn;
        rewrite ^(.*)$ https://tank-dav.eyeblue.cn$1 permanent;
}
 

通过以上的配置，WebDAV的访问地址就变成了：https://tank-dav.eyeblue.cn

 

支持WebDAV的常用客户端

Windows平台

WinSCP

这是windows平台的一个免费软件，下载地址: https://winscp.net/eng/download.php

 

Potplayer

这是一个windows平台的免费播放器，可以通过WebDAV直接观看网盘中的视频，下载地址：http://potplayer.daum.net

 

NetDrive 3

NetDrive 3是一个收费软件，不过可以支持7天试用，而且跨平台，下载地址：http://www.netdrive.net/

 

MacOS平台

NetDrive 3

 

Android平台

ES文件浏览器

在各大应用商店搜索即可下载。添加的方式 网络 -> ftp -> WebDAV

 

IOS平台

FE文件管理器

AppStore中搜索“FE文件管理器”即可下载，按照引导添加即可。

 

图片处理

/api/alien/download/{uuid}/{filename}

/api/alien/preview/{uuid}/{filename}

功能：在浏览器中下载文件

这个两个接口既可以下载公有文件，又可以下载私有文件。同时对于图片文件还可以做裁剪缩放等操作。

区别是download接口会在http header中加上Content-Disposition，浏览器会自动当成下载处理。

区别是preview接口不会在http header中加上Content-Disposition，因此浏览器会直接以预览模式打开。

访问级别：注册用户,管理员

请求参数：

返回: 二进制的文件

该接口同时还可以对图片进行缩放预处理

图片缩放支持的格式有：".jpg", ".jpeg", ".png", ".tif", ".tiff", ".bmp", ".gif"

额外参数

格式为 ir=mode_width_height

示例

原图：

1. 将宽度指定为200，高度等比例缩放

http://tank.eyeblue.cn/api/alien/preview/3f4b3090-e688-4d63-7705-93a120690505/horse.jpg?ir=fit_200_0

1. 将高度指定为200，宽度等比例缩放

http://tank.eyeblue.cn/api/alien/preview/3f4b3090-e688-4d63-7705-93a120690505/horse.jpg?ir=fit_0_200

1. 图片自动填充在200*200的大小中 （这种情况用得最多）

http://tank.eyeblue.cn/api/alien/preview/3f4b3090-e688-4d63-7705-93a120690505/horse.jpg?ir=fill_200_200

1. 图片固定大小200*200 (一般会导致变形)

http://tank.eyeblue.cn/api/alien/preview/3f4b3090-e688-4d63-7705-93a120690505/horse.jpg?ir=fixed_200_200

 

第三方存储

AlienController

• 开源云盘提供了编程接口，实现了云存储（如：七牛云，阿里云OSS）的核心功能，可以使用编程接口上传文件，作为其他网站、系统、app的资源存储器。可以在下载图片时对图片做缩放裁剪处理，可以有效地节省客户端流量

• 开源系列开源软件之二的《开源博客》正是使用开源博客作为第三方资源存储器。开源博客中的所有图片，附件均是存储在开源云盘中

上传时序图

 

下载时序图

 

---

接口详情

/api/alien/fetch/upload/token

功能：一个开源云盘受信任的用户请求一个UploadToken，用于给另一个用户向开源云盘上传文件

一般的使用场景是应用服务器向开源云盘请求UploadToken，然后将此UploadToken交由浏览器去向开源云盘上传文件

访问级别：注册用户,管理员

请求参数

---

/api/alien/fetch/download/token

功能：一个开源云盘受信任的用户请求一个DownloadToken，用于给另一个用户下载开源云盘上的私有文件

一般的使用场景是应用服务器向开源云盘请求DownloadToken，然后将此DownloadToken交由浏览器去向开源云盘下载文件

访问级别：注册用户,管理员

请求参数

---

/api/alien/confirm

功能：应用服务器向开源云盘确认某个文件是否确实已经上传好了

访问级别：注册用户,管理员

请求参数

---

/api/alien/upload

功能：浏览器拿着UploadToken通过FormData向开源云盘上传文件

一般的使用场景是应用服务器向开源云盘请求UploadToken，然后将此UploadToken交由浏览器去向开源云盘上传文件。由于在请求UploadToken的时候已经传入了文件元信息，因此这里的文件信息必须要和/api/alien/fetch/upload/token传入的参数信息一致

访问级别：游客,注册用户,管理员

请求参数

---

/api/alien/crawl/token

功能：获取一个token，提供给第三方去调用的一个接口

访问级别：游客,注册用户,管理员

请求参数

---

/api/alien/crawl/direct

功能：让开源云盘去拉取一个url资源

访问级别：注册用户,管理员

请求参数

---

/api/alien/preview/{uuid}/{filename}

功能：这个接口实现预览功能

访问级别：游客,注册用户,管理员

请求参数： 均是放置在url中

返回: 二进制的文件

---

/api/alien/download/{uuid}/{filename}

功能：在浏览器中下载文件

这个接口既可以下载公有文件，又可以下载私有文件。同时对于图片文件还可以做裁剪缩放等操作

访问级别：注册用户,管理员

请求参数：

返回: 二进制的文件

该接口同时还可以对图片进行缩放预处理，请参考这里

 

开源云盘api接口

一、实体

在详细介绍各controller中的接口前，有必要先介绍开源云盘中的各实体，所有的实体基类均为Base

Base

Base定义如下，所有会在数据库中持久化的实体均会继承Base，Controller在返回实体给前端时，会将字段和值序列化成json字符串，其中键就和每个实体字段后面的json标签一致，下文也会有详细例子介绍

type Base struct {
    //唯一标识
	Uuid       string    `gorm:"primary_key" json:"uuid"`
	//排序用的字段，一般是时间戳来表示序号先后
	Sort       int64     `json:"sort"`
	//修改时间
	UpdateTime time.Time `json:"updateTime"`
	//创建时间
	CreateTime time.Time `json:"createTime"`
}

 

Pager

在前端请求一个列表时，通常返回的都是一个Pager，Pager中就是装的各个实体的列表

type Pager struct {
    //当前页数，0基
	Page       int         `json:"page"`
	//每页的大小
	PageSize   int         `json:"pageSize"`
	//总的条目数
	TotalItems int         `json:"totalItems"`
	//总的页数
	TotalPages int         `json:"totalPages"`
	//实体的数组
	Data       interface{} `json:"data"`
}

 

Matter

Matter是代表文件（文件夹是一种特殊的文件），为了避免和系统的file重复，这里使用matter，这个实体是开源云盘最重要也是最基本的实体：

type Matter struct {
    //继承Base，也就是说Base中的Uuid,Sort,ModifyTime,CreateTime这里也会有
	Base
	//所在的文件夹的uuid，如果在根目录下，这个字段为 root
	Puuid    string  `json:"puuid"`
	//创建这个文件的用户uuid
	UserUuid string  `json:"userUuid"`
	//创建这个文件的用户名
    Username string  `json:"username"`
	//该文件是否是文件夹
	Dir      bool    `json:"dir"`
	//文件名，带后缀名。例如：avatar.jpg
	Name     string  `json:"name"`
    //文件的md5值，目前该功能尚未实现，作为保留字段
	Md5      string  `json:"md5"`
	//文件大小，单位 byte。比如某个文件1M大，那么这里就为： 1048576
	Size     int64   `json:"size"`
	//文件是否为私有，如果true则该文件只能作者或超级管理员可以下载，如果false所有人均可以通过下载链接下载
	Privacy  bool    `json:"privacy"`
	//文件在磁盘中的路径，前端无需关心这个字段。但是后端在寻找文件时这个字段非常关键
	Path     string  `json:"path"`
	//文件下载次数
    Times    int64   `json:"times"`
	//该文件的父级matter，该字段不会持久化到数据集，属于获取matter详情时临时组装出来的
	Parent   *Matter `gorm:"-" json:"parent"`
	//该文件的子级matter数组，该字段不会持久化到数据集，属于获取matter详情时临时组装出来的
    Children *Matter `gorm:"-" json:"-"`
}

 

User

User是代表用户：

type User struct {
    //继承Base，功能同上
	Base
	//角色，有以下枚举值：GUEST(游客，不会持久化到数据库),USER(普通用户),ADMINISTRATOR(超级管理员)
	Role      string    `json:"role"`
	//用户名，在Matter的path字段中很有用
	Username  string    `json:"username"`
	//密码，默认不会返回给前端
	Password  string    `json:"-"`
	//头像Url
	AvatarUrl string    `json:"avatarUrl"`
	//上次登录时的ip
	LastIp    string    `json:"lastIp"`
	//上次登录的时间
	LastTime  time.Time `json:"lastTime"`
	//该用户允许上传的单文件最大大小
	SizeLimit int64     `json:"sizeLimit"`
	//该用户允许上传的文件总量最大大小
    TotalSizeLimit int64     `json:"totalSizeLimit"`
    //该用户已上传的文件总量大小
    TotalSize int64     `json:"totalSize"`
	//状态，有以下枚举值：OK(正常),DISABLED(被禁用)
	Status    string    `json:"status"`
}

 

Preference

Preference是整个网站的偏好设置，网站的名称，logo，favicon，版权，备案号等信息均由这个实体负责。定义如下：

type Preference struct {
    //继承Base，功能同上
	Base
	//网站名称
	Name        string `json:"name"`
	//网站的logo url
	LogoUrl     string `json:"logoUrl"`
	//版权信息
	Copyright   string `json:"copyright"`
	Record      string `json:"record"`
    //大小限制
    DownloadDirMaxSize    int64 `json:"downloadDirMaxSize"`
    //文件数量
    DownloadDirMaxNum     int64 `json:"downloadDirMaxNum"` 
    //用户默认总大小限制
    DefaultTotalSizeLimit int64 `json:"defaultTotalSizeLimit"`
    //是否允许自主注册
    AllowRegister bool `json:"allowRegister"`  
	//当前运行的开源博客版本，这个字段不可修改，每次发版时硬编码
	Version     string `json:"version"`
}

 

UploadToken

用于给陌生人上传的token

type UploadToken struct {
    //继承Base，功能同上
	Base
	//颁发该token的用户，系统中任何用户都能颁发token
	UserUuid   string    `json:"userUuid"`
	//使用这个token上传文件就必须上传在这个文件夹下
	FolderUuid string    `json:"folderUuid"`
	//陌生人上传好了的文件uuid
	MatterUuid string    `json:"matterUuid"`
	//过期时间
	ExpireTime time.Time `json:"expireTime"`
	//使用这个token上传文件就必须是这个文件名
	Filename   string    `json:"filename"`
	//使用这个token上传文件就必须是这个公私有性
	Privacy    bool      `json:"privacy"`
	//使用这个token上传文件就必须这个大小
	Size       int64     `json:"size"`
	//使用这个token上传文件陌生人的ip
	Ip         string    `json:"ip"`
}

 

DownloadToken

用于给陌生人下载的token，一个matter如果Privacy=true，那么就意味着只有自己或者超级管理员可以下载，如果让某些自己信任的用户也能下载，那么就需要生成DownloadToken给这些用户来下载

type DownloadToken struct {
    //继承Base，功能同上
	Base
	//颁发该token的用户
	UserUuid   string    `json:"userUuid"`
	//该token只能下载这个文件
	MatterUuid string    `json:"matterUuid"`
	//有效期截止
	ExpireTime time.Time `json:"expireTime"`
	//下载者的ip
	Ip         string    `json:"ip"`
}
 

 

Dashboard

开源云盘的控制面板，显示云盘的统计数据：PV/UV、'活跃'文件、活跃IP

type Dashboard struct {
    //继承Base，功能同上
	Base
	//环比，表示连续2个单位周期（比如连续两周）内的量的变化比。
	InvokeNum      int64  `json:"invokeNum"`
	//总环比
	TotalInvokeNum int64  `json:"totalInvokeNum"`
	//当日UV
	Uv             int64  `json:"uv"`  
	//总UV           
	TotalUv        int64  `json:"totalUv"`    
	//当日文件总数
	MatterNum      int64  `json:"matterNum"`    
	//总文件总数
	TotalMatterNum int64  `json:"totalMatterNum"`
	//当日文件总大小
	FileSize       int64  `json:"fileSize"`    
	//文件总大小
	TotalFileSize  int64  `json:"totalFileSize"` 
	//平均耗时，反映了服务器整体的响应速度 
	AvgCost        int64  `json:"avgCost"`
	//日期
	Dt             string `json:"dt"`
}
 

 

Share

文件分享记录

type Share struct {
    //继承Base，功能同上
	Base
	//分享该记录的名称
	Name           string    `json:"name"`
	//分享类型，文件/文件夹/混合类型
	ShareType      string    `json:"shareType"`
	//分享该记录的用户
	Username       string    `json:"username"`
	//分享该记录的用户标识
	UserUuid       string    `json:"userUuid"`
	//下载次数
	DownloadTimes  int64     `json:"downloadTimes"`
	//提取码
	Code           string    `json:"code"`
	//是否过期失效
	ExpireInfinity bool      `json:"expireInfinity"`
	//过期时间
	ExpireTime     time.Time `json:"expireTime"`
	//文件夹文件
	DirMatter      *Matter   `json:"dirMatter"`
	//文件集合
	Matters        []*Matter `json:"matters"`
}
 

 

WebResult

WebResult并不是会持久化到数据库中实体，WebResult是在controller返回数据给前端时包装的一层，有了WebResult后每个接口返回的数据会更加统一，方便了前端的统一处理

type WebResult struct {
    //状态码，具体每个码的意义参考下文
	Code int       `json:"code"`
	//一句话描述请求结果，通常会是出错时指明出错原因，或者修改权限等小操作时提示的`操作成功`
	Msg  string      `json:"msg"`
	//内容可能是一个实体，也可能是一个 Pager.
	Data interface{} `json:"data"`
}
 

 

状态码对应关系如下：

const (
	//正常
	RESULT_CODE_OK = 200
	//未登录
	RESULT_CODE_LOGIN = -400
	//没有权限
	RESULT_CODE_UNAUTHORIZED = -401
	//请求错误
	RESULT_CODE_BAD_REQUEST = -402
	//没有找到
	RESULT_CODE_NOT_FOUND = -404
	//登录过期
	RESULT_CODE_LOGIN_EXPIRED = -405
	//该登录用户不是有效用户
	RESULT_CODE_LOGIN_INVALID = -406
	//提交的表单验证不通过
	RESULT_CODE_FORM_INVALID = -410
	//请求太频繁
	RESULT_CODE_FREQUENCY = -420
	//服务器出错
	RESULT_CODE_SERVER_ERROR = -500
	//远程服务不可用
	RESULT_CODE_NOT_AVAILABLE = -501
	//并发异常
	RESULT_CODE_CONCURRENCY = -511
	//远程微服务没有找到
	RESULT_CODE_SERVICE_NOT_FOUND = -600
	//远程微服务连接超时
	RESULT_CODE_SERVICE_TIME_OUT = -610
	//通用的异常
	RESULT_CODE_UTIL_EXCEPTION = -700
)

 

二、返回规范

开源云盘采用前后端分离的模式，前端调用后端接口时，url均以/api开头，返回均是json字符串

• 返回的json字符串的key均为小写开头的驼峰法，具体参考实体类中json标签

• 返回的时间格式均为 YYYY-MM-dd HH:mm:ss（例如：2018-01-06 17:57:00）

返回内容均是由WebResult进行包装，因此具有高度的统一性，在这里我们约定一些说法，后面介绍Controller时便不再赘述

1. 返回一个XX实体

   指的是WebResult的Code=200, Data=一个XX实体对象

   例：返回一个User，则前端会收到以下json字符串：

   {
     "code": 200,
     "msg": "",
     "data": {
       "uuid": "eed2c66d-1de6-47ff-645e-b67beaa10365",
       "sort": 1514803034507,
       "modifyTime": "2018-01-06 18:00:58",
       "createTime": "2018-01-01 18:37:15",
       "role": "USER",
       "username": "demo",
       "avatarUrl": "/api/alien/download/ea490cb6-368e-436d-71c0-fcfb08854c80/1180472.png",
       "lastIp": "124.78.220.82",
       "lastTime": "2018-01-06 18:00:58",
       "sizeLimit": 1048576,
       "totalSizeLimit": 104857600,
       "totalSize": 10485760,
       "status": "OK"
     }
   }
   

    

2. 返回XX的Pager

   指的是WebResult的Code=200, Data=XX的Pager

   例：返回User的Pager，则前端会收到以下json字符串：

   {
     "code": 200,
     "msg": "",
     "data": {
       "page": 0,
       "pageSize": 10,
       "totalItems": 2,
       "totalPages": 1,
       "data": [
         {
           "uuid": "6a661938-8289-4957-4096-5a1b584bf371",
           "sort": 1515057859613,
           "modifyTime": "2018-01-04 17:26:01",
           "createTime": "2018-01-04 17:24:20",
           "role": "ADMINISTRATOR",
           "username": "simba",
           "avatarUrl": "/api/alien/download/d1e453cb-3170-4bdb-73f2-fa0372ee017b/1180480.png",
           "lastIp": "180.173.103.207",
           "lastTime": "2018-01-04 17:26:01",
           "sizeLimit": -1,
           "totalSizeLimit": 104857600,
           "totalSize": 10485760,
           "status": "OK"
         },
         {
           "uuid": "e59be6a3-f806-463e-553a-4c5892eedf78",
           "sort": 1514881002975,
           "modifyTime": "2018-01-02 16:16:43",
           "createTime": "2018-01-02 16:16:43",
           "role": "USER",
           "username": "blog_dev",
           "avatarUrl": "/api/alien/download/fdca6eee-d009-4eb3-5ad4-15ba3701cb2e/jump.jpg",
           "lastIp": "",
           "lastTime": "2018-01-02 16:16:43",
           "sizeLimit": 1048576,
           "totalSizeLimit": 104857600,
           "totalSize": 10485760,
           "status": "OK"
         }
       ]
     }
   }
   

    

3. 返回错误信息：yyy

   指的是WebResult的Code=-400, Msg=yyy(这里的Code具体值参考上文的code表)

   例：返回错误信息："【新建文件夹】已经存在了，请使用其他名称。"，则前端会收到以下json字符串：

   {
     "code": -700,
     "msg": "【新建文件夹】已经存在了，请使用其他名称。",
     "data": null
   }
   

    

4. 返回成功信息：zzz

   指的是WebResult的Code=200, Msg=zzz(这里的Code具体值参考上文的code表)

   例：返回成功信息："删除成功。"，则前端会收到以下json字符串：

   {
     "code": 200,
     "msg": "删除成功。",
     "data": null
   }
   

    

三、接口

开源云盘所有的接口均定义在controller中，总共定义了以下controller：

每个接口都有不同的访问级别，系统中定义了三种访问级别，分别是：

游客 < 注册用户 < 管理员

PreferenceController

该Controller负责网站中的偏好设置，主要操作Preference实体

---

/api/preference/fetch

功能：读取网站偏好设置，网站名称，logo，版权，备案信息，zip下载大小限制，zip下载数量限制，用户默认总大小限制，是否允许自主注册均从此接口读取

访问级别：游客,注册用户,管理员

请求参数：无

返回: 一个Preference实体

---

/api/preference/edit

功能：编辑网站偏好设置，修改网站名称，logo，版权，备案信息，zip下载大小限制，zip下载数量限制，用户默认总大小限制，是否允许自主注册

访问级别：管理员

请求参数：

返回: 一个Preference实体

---

/api/preference/system/cleanup

功能：重置系统，谨慎操作

访问级别：管理员

请求参数：

返回: 成功信息“重置成功”

---

MatterController

该Controller负责站内创建文件夹，上传文件，修改文件路径，删除文件，修改文件访问权限等，主要操作Matter实体

---

/api/matter/create/directory

功能：创建文件夹

访问级别：注册用户,管理员

请求参数：

返回: 新建的这个文件夹的Matter实体

---

/api/matter/upload

功能：上传文件

访问级别：注册用户,管理员

请求参数：

返回: 刚上传的这个文件的Matter实体

---

/api/matter/crawl（命令行工具）

功能：通过url获取文件

访问级别：注册用户,管理员

请求参数：

返回: 刚上传的这个文件的Matter实体

---

/api/matter/delete

功能：删除文件或者文件夹

访问级别：注册用户,管理员

请求参数：

返回: 成功信息“删除成功”

---

/api/matter/delete/batch

功能：批量删除文件或文件夹

访问级别：注册用户,管理员

请求参数：

返回: 成功信息“删除成功”

---

/api/matter/rename

功能：重命名文件或文件夹

访问级别：注册用户,管理员

请求参数：

返回: 刚重命名的这个文件的Matter实体

---

/api/matter/change/privacy

功能：改变文件的公私有属性

访问级别：注册用户,管理员

请求参数：

返回: 成功信息“设置成功”

---

/api/matter/move

功能：将一个文件夹或者文件移入到另一个文件夹下

访问级别：注册用户,管理员

请求参数：

返回: 成功信息“设置成功”

---

/api/matter/detail

功能：产看文件详情

访问级别：注册用户,管理员

请求参数：

返回: 这个文件的Matter实体

---

/api/matter/page

功能：按照分页的方式获取某个文件夹下文件和子文件夹的列表

访问级别：注册用户,管理员

请求参数：

返回: Matter的Pager

---

/api/matter/mirror

功能：把本地文件映射到开源云盘中（命令行工具）

访问级别：注册用户,管理员

请求参数：

---

/api/matter/zip

功能：把文件批量打包下载

访问级别：注册用户,管理员

请求参数：

---

UserController

该Controller负责站内创建文件夹，上传文件，删除文件，修改权限等，主要操作Matter实体

---

/api/user/login

功能：登录

访问级别：游客,注册用户,管理员

请求参数：

返回: 当前登录的User实体

---

/api/user/authentication/login

功能：授权变身登录

访问级别：游客,注册用户,管理员

请求参数：

返回: 当前登录的User实体

---

/api/user/register

功能：自助注册

访问级别：游客,注册用户,管理员

请求参数：

返回: 当前登录的User实体

---

/api/user/edit

功能：编辑用户

访问级别：注册用户,管理员

请求参数：

返回: 编辑的User实体

---

/api/user/detail

功能：查看用户详情

访问级别：注册用户,管理员

请求参数：

返回: User实体

---

/api/user/logout

功能：退出登录

访问级别：游客,注册用户,管理员

请求参数：无

返回: 成功信息"退出成功！"

---

/api/user/page

功能：查看用户列表

访问级别：管理员

请求参数：

返回: User实体的Pager

---

/api/user/change/password

功能：开源云盘用户修改用户密码

访问级别：注册用户,管理员

请求参数：

返回: 修改密码的User实体

---

/api/user/reset/password

功能：管理员重置用户密码

访问级别：管理员

请求参数：

返回: 修改密码的User实体

---

/api/user/toggle/status

功能：管理员修改用户状态

访问级别：管理员

请求参数：

返回: 修改状态的User实体

---

/api/user/transfiguration

功能：管理员变身

访问级别：管理员

请求参数：

返回: 变身用户的uuid

---

DashboardController

该Controller为开源云盘的控制面板，帮助了解云盘的统计数据：PV/UV、'活跃'文件、活跃IP

---

/api/dashboard/page

功能：获取近一段时间统计数据

访问级别：管理员

请求参数：

返回: Dashboard实体的Pager

---

/api/dashboard/active/ip/top10

功能：获取Top10活跃IP

访问级别：管理员

请求参数：无

返回: 由ip和times组成的List

---

ShareController

该Controller为开源云盘的提供分享功能，可以用来分享一切你想要分享的东西（文件/文件夹）

---

/api/share/create

功能：创建文件分享

访问级别：注册用户,管理员

请求参数：

返回: 被分享的Share实体

---

/api/share/delete

功能：在我的分享里删除文件分享

访问级别：注册用户,管理员

请求参数：

返回: 成功信息“操作成功”

---

/api/share/delete/batch

功能：在我的分享里批量删除文件分享

访问级别：注册用户,管理员

请求参数：

返回: 成功信息“操作成功”

---

/api/share/page

功能：获取我的文件分享列表

访问级别：注册用户,管理员

请求参数：

返回: Share实体的Pager

---

/api/share/browse

功能：被分享者打开文件分享

访问级别：游客,注册用户,管理员

请求参数：

返回: 被分享的Share实体

---

/api/share/zip

功能：被分享者下载文件分享

访问级别：游客,注册用户,管理员

请求参数：

返回: 无

 

开源云盘前端

开源云盘前端采用vue2.0 + vue-router + vue-resource + es6 +less的技术栈，项目中引入了model层，其层级与数据库存储层级相对应，为视图层提供模型， 进而视图层能够完全面向对象思想进行开发，这是本项目的精髓所在，components文件夹下放了一些通用的组件，欢迎大家使用并提出意见!

 

项目部分结构

├── doc                                            // vue-cli创建后配置文档
├── node_modules                                   // 依赖包存放目录
├── public                                         // 入口目录
├── src                                            // 源码目录
│   ├── assets                                     // 静态资源
│   ├── common                                     // 通用
│   │   ├── directive                              // 自定义指令
│   │   │   ├── directive.js                       // 验证规则指令
│   │   ├── filter                                 // 格式化
│   │   ├── fork                                   // 引用外部插件
│   │   ├── i18n                                   // 国际化通用
│   │   ├── util                                   // 工具包
│   ├── components                                 // 公用组件
│   │   ├── copy                                   // 复制工具
│   │   ├── filter                                 // 筛选工具
│   │   ├── photoswipe                             // 图片预览
│   │   ├── previewer                              // 预览通用
│   │   ├── CreateSaveButton.vue                   // 保存创建按钮组件
│   │   ├── LoadingFrame.vue                       // 框架加载组件
│   │   ├── NbBtnDropdown.vue                      // 按钮下拉组件
│   │   ├── NbCheckbox.vue                         // 复选框组件
│   │   ├── NbExpanding.vue                        // 收缩展开组件
│   │   ├── NbPager.vue                            // 分页组件
│   │   ├── NbRadio.vue                            // 单选框组件
│   │   ├── NbSlidePanel.vue                       // 动画组件
│   │   ├── NbSwitcher.vue                         // 开关按钮组件
│   ├── model                                      // 前端模型层
│   │   ├── base                                   // 基
│   │   │   ├── Base.js                            // 基类
│   │   │   ├── BaseEntity.js                      // 实体基类
│   │   │   ├── Filter.js                          // 过滤器类
│   │   │   ├── Pager.js                           // 分页类
│   │   ├── dashboard                              // 控制面板类
│   │   ├── download                               // 下载token类
│   │   ├── image                                  // 图片缓存类
│   │   ├── install                                // 配置类
│   │   ├── matter                                 // 文件类
│   │   ├── preference                             // 个性类
│   │   ├── share                                  // 分享
│   │   │   ├── Share.js                           // 分享类
│   │   │   ├── ShareExpireOption.js               // 分享时限类
│   │   │   ├── ShareType.js                       // 分享文件类型类
│   │   ├── user                                   // 用户
│   │   │   ├── User.js                            // 用户类
│   │   │   ├── UserRole.js                        // 用户角色类
│   │   │   ├── UserStatus.js                      // 用户状态类
│   ├── router                                     // 路由层
│   ├── views                                      // 视图层
│   │   ├── dashboard                              // 控制面板视图
│   │   │   ├── theme.json                         // echarts配置文件
│   │   ├── install                                // 云盘配置视图
│   │   ├── layout                                 // 布局视图  
│   │   │   ├── BottomNavigation.vue               // 尾部布局
│   │   │   ├── SideMenu.vue                       // 侧边栏菜单
│   │   │   ├── SideNavigation.vue                 // 侧边栏布局
│   │   │   ├── TopNavigation.vue                  // 头部布局
│   │   ├── matter                                 // 文件视图
│   │   │   ├── widget 
│   │   │   │   ├── imageCache                     // 图片缓存插件                                                     
│   │   │   │   ├── Director.js                    // 单个文件的导演类      
│   │   │   │   ├── FolderTree.vue                 // 文件夹递归树组件      
│   │   │   │   ├── MatterImage.vue                // 图片类型文件上传组件      
│   │   │   │   ├── MatterPanel.vue                // 单文件或文件夹个体     
│   │   │   │   ├── MoveBatchPanel.vue             // 批量文件移动组件      
│   │   │   │   ├── UploadMatterPanel.vue          // 文件上传组件 
│   │   ├── preference                             // 个性化视图
│   │   ├── share                                  // 分享视图
│   │   ├── user                                   // 用户视图
│   │   │   ├── feature                            // 权限枚举
│   │   ├── Frame.vue                              // 大架子
│   ├── vuex                                       // store
├

 

 

常见问题

 

为什么不能上传中文文件？

请首先检查数据库的编码，采用utf-8编码就可以上传中文。

以下提供常用数据库指令，以下数据库名为tank，表为tank30_user

# 查看数据库编码
USE tank;
SHOW VARIABLES LIKE 'character_set_database';
 
# 修改数据库编码
ALTER SCHEMA `tank`  DEFAULT CHARACTER SET utf8 ;
 
# 查看表以及字段编码
show create table tank.tank30_user;
 
# 修改表编码
ALTER TABLE `tank`.`tank30_user` 
CHARACTER SET = utf8 ;
 
# 修改字段编码
ALTER TABLE `tank`.`tank30_user` 
CHANGE COLUMN `username` `username` VARCHAR(45) CHARACTER SET 'utf8' NOT NULL ;

 

如何配置nginx反向代理？

通常我们不希望把6010端口暴露到公网，这时需要nginx进行反向代理，让用户使用域名及80端口（或443端口）就能访问开源云盘。以下是tank.eyeblue.cn的nginx配置

#https://tank.eyeblue.cn
server{
        listen 443 ssl;
        server_name tank.eyeblue.cn;
 
        ssl on;
        ssl_certificate /letsencrypt/full_chain.pem;
        #private key
        ssl_certificate_key /letsencrypt/private.key;
 
        gzip on; #开启或关闭gzip on off
        gzip_disable "msie6"; #不使用gzip IE6
        gzip_min_length 100k; #gzip压缩最小文件大小，超出进行压缩（自行调节）
        gzip_buffers 4 16k; #buffer 不用修改
        gzip_comp_level 3; #压缩级别:1-10，数字越大压缩的越好，时间也越长
        gzip_types application/javascript text/css text/javascript; #  压缩文件类型
        gzip_vary off;  #跟Squid等缓存服务有关，on的话会在Header里增加 "Vary: Accept-Encoding"
 
        location / {
                proxy_pass http://127.0.0.1:6010;
                proxy_set_header host $host;
                proxy_set_header X-Forwarded-For $remote_addr;
                proxy_pass_request_headers      on;
                client_max_body_size  2048m;
        }
 
}
 
#http://tank.eyeblue.cn 转发所有80的请求到443
server {
        listen      80;
        server_name    tank.eyeblue.cn;
        rewrite ^(.*)$ https://tank.eyeblue.cn$1 permanent;
}

提示

由于前端资源文件chunk-vendors.js 约2M，因此在nginx的配置中使用gzip压缩可以显著提升访问速度。

 

为什么太大的文件就不能上传了？

可能是反向代理的软件对post大小限制了，比如上方nginx配置的client_max_body_size 2048m;就使得最大只能上传2G的文件

 

为什么我的doc,ppt,xls等office文件不能预览？

由于预览office文件是借助了微软的接口，因此预览有这几个限制。

• 你部署的开源云盘必须是公网ip或者外网可以访问的域名。(也就是或127.0.0.1或者localhost都不行)
• 文件不能太大，超过10M微软的预览接口便不支持了。