gofs使用教程-基于golang的开源跨平台文件同步工具
概述
gofs是基于golang开发的一款开箱即用的跨平台文件同步工具，支持在本地磁盘之间同步、从远程服务器同步变更到本地、将本地文件变更推送到远程服务器三种模式。开源地址如下：Github & Gitee，欢迎Star或者提交Issue和PR！
安装
首先需要确保已经安装了Go (版本必须是1.20+)，然后你就可以使用下面的命令来安装gofs了
如果你不需要自行从源码编译安装，也可以直接下载最新发布的二进制文件
go install github.com/no-src/gofs/...@latest
在Docker中运行
你可以使用build-docker.sh脚本来构建docker镜像，首先你需要克隆本仓库并且cd到本仓库的根目录
$ ./scripts/build-docker.sh
或者使用以下命令直接从DockerHub中拉取docker镜像
$ docker pull nosrc/gofs
更多关于发布与docker的脚本参见scripts目录
后台运行
在windows系统中，你可以使用下面的命令构建一个在后台运行的不带命令行界面的程序
go install -ldflags="-H windowsgui" github.com/no-src/gofs/...@latest
快速开始
先决条件
请确保文件同步的源目录和目标目录都已经存在，如果目录不存在，则用你实际的目录替换下面的路径进行提前创建
$ mkdir source dest
生成仅用于测试的证书和密钥文件，生产中请替换为正式的证书
TLS证书和密钥文件仅用于与Web文件服务器和远程磁盘服务端进行安全通讯
$ go run $GOROOT/src/crypto/tls/generate_cert.go --host 127.0.0.1
2021/12/30 17:21:54 wrote cert.pem
2021/12/30 17:21:54 wrote key.pem
查看你的工作目录
$ ls
cert.pem key.pem source dest
使用方法
在磁盘之间同步
使用本地磁盘在磁盘之间同步文件
从服务器端同步
同步到服务器端
从SFTP服务器上同步
使用SFTP拉取客户端从SFTP服务器上同步文件
同步到SFTP服务器
使用SFTP推送客户端同步文件到SFTP服务器
从MinIO服务器上同步
使用MinIO拉取客户端从MinIO服务器上同步文件
同步到MinIO服务器
使用MinIO推送客户端同步文件到MinIO服务器
核心功能
本地磁盘
监控本地源目录将变更同步到目标目录
你可以使用logically_delete命令行参数来启用逻辑删除，从而避免误删数据
设置checkpoint_count命令行参数来使用文件中的检查点来减少传输未修改的文件块，默认情况下checkpoint_count=10，这意味着它最多有10+2个检查点。在头部和尾部还有两个额外的检查点。第一个检查点等于chunk_size，它是可选的。最后一个检查点等于文件大小，这是必需的。由checkpoint_count设置的检查点偏移量总是大于chunk_size，除非文件大小小于或等于chunk_size，那么checkpoint_count将变为0，所以它是可选的
默认情况下，如果源文件的大小和修改时间与目标文件相同，则忽略当前文件的传输。你可以使用force_checksum命令行参数强制启用校验和来比较文件是否相等
默认的校验和哈希算法为md5，你可以使用checksum_algorithm命令行参数来更改默认的哈希算法，当前支持的算法如下：md5、sha1、sha256、sha512、crc32、crc64、adler32、fnv-1-32、fnv-1a-32、fnv-1-64、fnv-1a-64、fnv-1-128、fnv-1a-128
如果你想要降低同步的频率，你可以使用sync_delay命令行参数来启用同步延迟，当事件数量大于等于sync_delay_events或者距离上次同步已经等待超过sync_delay_time时开始同步
另外你可以使用progress命令行参数来打印文件同步的进度条
$ gofs -source=./source -dest=./dest
加密
你可以使用encrypt命令行参数来启用加密功能，并通过encrypt_path命令行参数指定一个目录作为加密工作区。所有在这个目录中的文件都会被加密之后再同步到目标路径中
$ gofs -source=./source -dest=./dest -encrypt -encrypt_path=./source/encrypt -encrypt_secret=mysecret
解密
你可以使用decrypt命令行参数来将加密文件解密到指定的路径中
$ gofs -decrypt -decrypt_path=./dest/encrypt -decrypt_secret=mysecret -decrypt_out=./decrypt_out
全量同步
执行一次全量同步，直接将整个源目录同步到目标目录
$ gofs -source=./source -dest=./dest -sync_once
定时同步
定时执行全量同步，将整个源目录同步到目标目录
# 每30秒钟将源目录全量同步到目标目录
$ gofs -source=./source -dest=./dest -sync_cron="*/30 * * * * *"
守护进程模式
启动守护进程来创建一个工作进程处理实际的任务，并将相关进程的pid信息记录到pid文件中
$ gofs -source=./source -dest=./dest -daemon -daemon_pid
Web文件服务器
启动一个Web文件服务器用于访问远程的源目录和目标目录
Web文件服务器默认使用HTTPS协议，使用tls_cert_file和tls_key_file命令行参数来指定相关的证书和密钥文件
如果你不需要使用TLS进行安全通讯，可以通过将tls命令行参数指定为false来禁用它
如果将tls设置为true，则服务器默认运行端口为443，反之默认端口为80，你可以使用server_addr命令行参数来自定义服务器运行端口，例如-server_addr=":443"
如果你在服务器端启用tls命令行参数，可以通过tls_insecure_skip_verify命令行参数来控制客户端是否跳过验证服务器的证书链和主机名，默认为true
如果你已经启用了tls命令行参数，那么你可以使用http3命令行参数在服务器端和客户端启用HTTP3协议
出于安全考虑，你应该设置rand_user_count命令行参数来随机生成指定数量的用户或者通过users命令行参数自定义用户信息来保证数据的访问安全，禁止用户匿名访问数据
如果rand_user_count命令行参数设置大于0，则随机生成的账户密码将会打印到日志信息中，请注意查看
如果你需要启用gzip压缩响应结果，则添加server_compress命令行参数，但是目前gzip压缩不是很快，在局域网中可能会影响传输效率
你可以使用session_connection命令行参数来切换Web文件服务器的会话存储模式，当前支持memory与redis，默认为memory。
如果你想使用redis作为会话存储，这里是一个redis会话连接字符串的示例：
redis://127.0.0.1:6379?password=redis_password&db=10&max_idle=10&secret=redis_secret
# 启动一个Web文件服务器并随机创建3个用户
# 在生产环境中请将`tls_cert_file`和`tls_key_file`命令行参数替换为正式的证书和密钥文件
$ gofs -source=./source -dest=./dest -server -tls_cert_file=cert.pem -tls_key_file=key.pem -rand_user_count=3
速率限制
使用max_tran_rate命令行参数来限制服务器端和客户端的最大传输速率，这是一个期望值，而不是绝对值
例如，限制最大传输速率为1048576字节，即1MB
$ gofs -source=./source -dest=./dest -max_tran_rate=1048576
远程磁盘服务端
启动一个远程磁盘服务端作为一个远程文件数据源
source命令行参数详见远程磁盘服务端数据源协议
注意远程磁盘服务端的用户至少要拥有读权限，例如：-users="gofs|password|r"
你可以使用checkpoint_count和sync_delay命令行参数就跟本地磁盘一样
# 启动一个远程磁盘服务端
# 在生产环境中请将`tls_cert_file`和`tls_key_file`命令行参数替换为正式的证书和密钥文件
# 为了安全起见，请使用复杂的账户密码来设置`users`命令行参数
$ gofs -source="rs://127.0.0.1:8105?mode=server&local_sync_disabled=true&path=./source&fs_server=https://127.0.0.1" -dest=./dest -users="gofs|password|r" -tls_cert_file=cert.pem -tls_key_file=key.pem
远程磁盘客户端
启动一个远程磁盘客户端将远程磁盘服务端的文件变更同步到本地目标目录
source命令行参数详见远程磁盘服务端数据源协议
使用sync_once命令行参数，可以直接将远程磁盘服务端的文件整个全量同步到本地目标目录，就跟全量同步一样
使用sync_cron命令行参数，可以定时将远程磁盘服务端的文件整个全量同步到本地目标目录，就跟定时同步一样
使用force_checksum命令行参数强制启用校验和来比较文件是否相等，就跟本地磁盘一样
你可以使用sync_delay命令行参数就跟本地磁盘一样
# 启动一个远程磁盘客户端
# 请将`users`命令行参数替换为上面设置的实际账户名密码
$ gofs -source="rs://127.0.0.1:8105" -dest=./dest -users="gofs|password"
远程推送服务端
启动一个远程磁盘服务端作为一个远程文件数据源，并使用push_server命令行参数启用远程推送服务端
注意远程推送服务端的用户至少要拥有读写权限，例如：-users="gofs|password|rw"
# 启动一个远程磁盘服务端并启用远程推送服务端
# 在生产环境中请将`tls_cert_file`和`tls_key_file`命令行参数替换为正式的证书和密钥文件
# 为了安全起见，请使用复杂的账户密码来设置`users`命令行参数
$ gofs -source="rs://127.0.0.1:8105?mode=server&local_sync_disabled=true&path=./source&fs_server=https://127.0.0.1" -dest=./dest -users="gofs|password|rw" -tls_cert_file=cert.pem -tls_key_file=key.pem -push_server
远程推送客户端
启动一个远程推送客户端将本地文件变更同步到远程推送服务端
使用chunk_size命令行参数来设置大文件上传时切分的区块大小，默认值为1048576，即1MB
你可以使用checkpoint_count和sync_delay命令行参数就跟本地磁盘一样
更多命令行参数用法请参见远程磁盘客户端
# 启动一个远程推送客户端并且启用本地磁盘同步，将source目录下的文件变更同步到本地dest目录和远程推送服务器上
# 请将`users`命令行参数替换为上面设置的实际账户名密码
$ gofs -source="./source" -dest="rs://127.0.0.1:8105?local_sync_disabled=false&path=./dest" -users="gofs|password"
SFTP客户端
启动一个SFTP客户端，将发生变更的文件同步到SFTP服务器
$ gofs -source="./source" -dest="sftp://127.0.0.1:22?local_sync_disabled=false&path=./dest&remote_path=/gofs_sftp_server" -users="sftp_user|sftp_pwd"
SFTP推送客户端
启动一个SFTP推送客户端，将发生变更的文件同步到SFTP服务器
$ gofs -source="./source" -dest="sftp://127.0.0.1:22?local_sync_disabled=false&path=./dest&remote_path=/gofs_sftp_server&ssh_user=sftp_user&ssh_pass=sftp_pwd"
SFTP拉取客户端
启动一个SFTP拉取客户端，将文件从SFTP服务器拉到本地目标路径
$ gofs -source="sftp://127.0.0.1:22?remote_path=/gofs_sftp_server&ssh_user=sftp_user&ssh_pass=sftp_pwd" -dest="./dest" -sync_once
MinIO推送客户端
启动一个MinIO推送客户端，将发生变更的文件同步到MinIO服务器
$ gofs -source="./source" -dest="minio://127.0.0.1:9000?secure=false&local_sync_disabled=false&path=./dest&remote_path=minio-bucket" -users="minio_user|minio_pwd"
MinIO拉取客户端
启动一个MinIO拉取客户端，将文件从MinIO服务器拉到本地目标路径
$ gofs -source="minio://127.0.0.1:9000?secure=false&remote_path=minio-bucket" -dest="./dest" -users="minio_user|minio_pwd" -sync_once
任务服务端
启动一个任务服务器，将任务分发给客户端
以远程磁盘服务端为例，
首先创建一个任务清单配置文件remote-disk-task.yaml，
这里定义了一个从服务器同步文件的任务
然后创建在上述清单配置文件中定义的任务内容配置文件run-gofs-remote-disk-client.yaml
，它将会被客户端执行
最后使用task_conf命令行参数启动远程磁盘服务端
这里使用conf命令行参数来简化命令并复用集成测试的配置文件
$ cd integration
$ mkdir -p rs/source rs/dest
$ gofs -conf=./testdata/conf/run-gofs-remote-disk-server.yaml
任务客户端
启动一个任务客户端来订阅任务服务器，然后获取任务并执行它
使用task_client命令行参数来启动任务客户端，task_client_max_worker命令行参数将限制任务客户端的最大并发工作线程数
你可以使用task_client_labels命令行参数来定义任务客户端的标签，这些标签用于在任务服务器端匹配任务
这里使用conf命令行参数来简化命令并复用集成测试的配置文件
$ cd integration
$ mkdir -p rc/source rc/dest
$ gofs -conf=./testdata/conf/run-gofs-task-client.yaml
中继
如果你需要在两个无法直接相连的设备之间同步文件，可以使用反向代理作为中继服务器来实现，详情参见中继模式
远程磁盘服务端数据源协议
远程磁盘服务端数据源协议基于URI基本语法,详见RFC 3986
方案
方案名称为rs
主机名
远程磁盘服务端数据源在远程磁盘服务端模式下使用0.0.0.0或者其他本地网卡IP地址作为主机名，在远程磁盘客户端
模式下使用远程磁盘服务端的IP地址或者域名作为主机名
端口号
远程磁盘服务端数据源端口号，默认为8105
参数
仅在远程磁盘服务端模式下设置以下参数
path远程磁盘服务端真实的本地源目录mode指定运行模式，只有在远程磁盘服务端模式下需要手动指定为server，默认为远程磁盘客户端模式fs_serverWeb文件服务器地址，例如https://127.0.0.1local_sync_disabled是否将远程磁盘服务端的文件变更同步到远程本地的目标目录,可选值为true或false，默认值为false
示例
远程磁盘服务端模式下的示例
注：若图表展示错位，请点击图表中的全屏按钮查看
rs://127.0.0.1:8105?mode=server&local_sync_disabled=true&path=./source&fs_server=https://127.0.0.1
\_/ \_______/ \__/ \____________________________________________________________________________/
| | | |
方案 主机名 端口号 参数
管理接口
基于Web文件服务器的应用管理接口
默认情况下，仅允许私有地址和回环地址访问管理接口的相关路由
你可以通过将manage_private命令行参数设置为false来禁用默认行为，允许公网IP访问管理接口的路由
$ gofs -source=./source -dest=./dest -server -tls_cert_file=cert.pem -tls_key_file=key.pem -rand_user_count=3 -manage
性能分析接口
pprof访问地址如下：
https://127.0.0.1/manage/pprof/
配置接口
读取应用程序配置，默认返回json格式，当前支持json和yaml格式
https://127.0.0.1/manage/config
或者使用format参数来指定返回的配置格式
https://127.0.0.1/manage/config?format=yaml
报告接口
使用report命令行参数来启用报告接口的路由并且开始收集报告数据，需要先启用manage命令行参数
报告接口详情参见Report API
https://127.0.0.1/manage/report
日志
默认情况下会启用文件日志与控制台日志，你可以将log_file命令行参数设置为false来禁用文件日志
使用log_level命令行参数设置日志的等级，默认级别是INFO，可选项为：DEBUG=0 INFO=1 WARN=2 ERROR=3
使用log_dir命令行参数来设置日志文件目录，默认为./logs/
使用log_flush命令行参数来设置自动刷新日志到文件中，默认启用
使用log_flush_interval命令行参数设置自动刷新日志到文件中的频率，默认为3s
使用log_event命令行参数启用事件日志，所有事件都会记录到文件中，默认为禁用
使用log_sample_rate命令行参数设置采样日志的采样率，取值范围为0到1，默认值为1
使用log_format命令行参数设置日志输出格式，当前支持text与json，默认为text
使用log_split_date命令行参数来根据日期拆分日志文件，默认为禁用
# 在"本地磁盘"模式下设置日志信息
$ gofs -source=./source -dest=./dest -log_file -log_level=0 -log_dir="./logs/" -log_flush -log_flush_interval=3s -log_event
使用配置文件
如果需要的话，你可以使用配置文件来代替所有的命令行参数，当前支持json和yaml格式
所有的配置字段名称跟命令行参数一样，你可以参考配置示例或者配置接口的响应结果
$ gofs -conf=./gofs.yaml
校验和
你可以使用checksum命令行参数来计算并打印文件的校验和
chunk_size、checkpoint_count和checkpoint_count命令行参数在这里同在本地磁盘中一样有效
$ gofs -source=./gofs -checksum
更多信息
帮助信息
$ gofs -h
版本信息
$ gofs -v
关于信息
$ gofs -about
