本页内容
- 前提条件
- 设置 UFW 防火墙
- 在 Ubuntu 22.04 上安装 SFTPGo
- 完成 SFTPGo 安装
- v2.3.0 中的新功能 组 外部共享 品牌定制 OpenID Connect ACME Geo-IP 过滤 基于 shell 模式限制文件和目录
- 组
- 外部共享
- 品牌定制
- OpenID Connect
- ACME
- Geo-IP 过滤
- 基于 shell 模式限制文件和目录
SFTPGo 是一款免费、开源、功能齐全且高度可配置的 SFTP 服务器,可选支持 HTTP/S、FTP/S 和 WebDAV。支持多种存储后端:本地文件系统、加密本地文件系统、S3(兼容)对象存储、Google Cloud Storage、Azure Blob Storage、其他 SFTP 服务器。
所有支持的功能在 GitHub 项目页面上有详细描述。
SFTPGo 可用于多种操作系统,包括 Linux、Windows、macOS、FreeBSD。在本教程中,你将学习如何在 Ubuntu Ubuntu 22.04 系统上安装 SFTPGo,我们将探讨 v2.3.0 中引入的主要新功能。
前提条件
- 一台 Ubuntu 22.04 服务器。
- 一个具有 sudo 权限的非 root 用户。
设置 UFW 防火墙
出于安全考虑,建议在你的系统中安装并配置 UFW 防火墙。首先,使用以下命令安装 UFW 防火墙:
sudo apt install ufw -y
SFTPGo 在默认配置下使用以下 TCP 端口:
- 2022 用于 SFTP 服务。
- 8080 用于 Web 管理用户界面。
我们还需要放行用于服务器管理的 OpenSSH 端口。
使用以下命令放行所有必需的端口:
sudo ufw allow OpenSSH
sudo ufw allow 2022/tcp
sudo ufw allow 8080/tcp
接下来,启用 UFW 防火墙使其在系统重启后启动:
sudo ufw enable
检查状态:
sudo ufw status
你将看到以下输出:
Status: active To Action From -- ------ ---- OpenSSH ALLOW Anywhere 2022/tcp ALLOW Anywhere 8080/tcp ALLOW Anywhere OpenSSH (v6) ALLOW Anywhere (v6) 2022/tcp (v6) ALLOW Anywhere (v6) 8080/tcp (v6) ALLOW Anywhere (v6)
在 Ubuntu 22.04 上安装 SFTPGo
你可以从其 PPA 安装 SFTPGo。
首先添加 PPA:
sudo add-apt-repository ppa:sftpgo/sftpgo
sudo apt update
接下来安装 SFTPGo:
sudo apt install sftpgo
安装完成后,SFTPGo 应该已经以默认配置运行并设置为开机自动启动,使用以下命令检查其状态:
systemctl status sftpgo
完成 SFTPGo 安装
现在,打开你的 Web 浏览器,使用以下 URL 访问 SFTPGo 安装向导:" http://

提供你的管理员用户名和密码,然后点击 " Create Admin " 按钮。新创建的管理员将自动登录,因此你可以创建 SFTPGo 用户。
有关创建用户的更多详细信息,你可以查看 Getting Started Guide。
v2.3.0 中的新功能
让我们在接下来的章节中探讨 v2.3.0 中引入的主要新功能。
组
使用组可以简化多个 SFTPGo 用户的管理:你可以将设置一次性分配给一个组,而不必为每个单独的用户多次分配。
SFTPGo 支持两种类型的组:
- 主组
- 辅助组
一个用户可以是某个主组和多个辅助组的成员。根据组类型的不同,设置的继承方式也不同。你可以通过查阅官方文档了解更多详细信息。
让我们在这里看一些使用示例。
假设你有以下需求:
- 每个用户必须被限制在以用户名作为路径最后一个元素的本地主目录中,例如 /srv/sftpgo/data/
- 对于每个用户,单个文件的最大上传大小必须限制为 1GB
- 每个用户必须在路径 /s3
中有一个可用的 S3 虚拟文件夹,且每个用户只能访问 S3 bucket 中指定的 "prefix"。它必须无法访问其他用户的文件 - 每个用户必须在路径 /shared 中有一个可用的 S3 虚拟文件夹。这是一个与其他用户共享的文件夹
- 一组用户只能在 /shared 路径中下载和列出内容,而另一组用户拥有完全访问权限
通过定义两个组,我们可以轻松满足这些需求。
在 SFTPGo WebAdmin UI 中,点击 "Folders",然后点击 "+" 图标。
创建一个名为 "S3private" 的文件夹。将存储设置为 "AWS S3 (Compatible)" 并填写必需的参数:
- bucket 名称
- region
- credentials:access key 和 access secret

重要的部分是 "Key Prefix",将其设置为 users/%username%/。

"Key Prefix" 将访问限制在指定的 bucket 子文件夹中。占位符 " %username% " 将被替换为关联的用户名。
创建另一个名为 "S3shared" 的文件夹,设置与 "S3private" 相同,但这次将 "Key Prefix" 设置为 shared/。"Key Prefix" 没有占位符,因此该文件夹将在静态路径上操作,不会根据关联的用户而改变。
现在点击 "Groups",然后点击 "+" 图标并添加一个名为 "Primary" 的组。
将 "Home Dir" 设置为 /srv/sftpgo/data/%username%。

和之前一样,占位符 " %username% " 将被替换为关联的用户名。
将这两个虚拟文件夹添加到该组,并将 "Max file upload size" 设置为 1073741824 字节(1GB)。

添加一个新组并将其命名为 "SharedReadOnly",在 ACL 部分设置 /shared 路径的权限,以授予只读访问权限。

组设置现已完成。
现在我们可以创建用户并将主组设置为 "Primary"。对于需要对 /shared 路径拥有只读访问权限的用户,我们还必须将 "SharedReadOnly" 设置为辅助组。
点击 "Users",然后点击 "+" 图标并添加一个名为 "user1" 的用户。

该用户符合上述限制,并对 /shared 路径拥有完全访问权限。
现在创建 "user2",它符合上述限制,并对 /shared 路径拥有只读访问权限。

你还可以使用模板功能同时创建多个用户。

只需设置用户名、凭据和组成员关系。

现在你可以使用任何 SFTP 客户端(如 FileZilla、WinSCP 等)登录,并验证需求是否得到满足。
外部共享
与没有 SFTPGo 账户的外部用户共享文件是一个常见需求。在 v2.3.0 中,此功能得到了改进。支持以下共享模式:
- 只读
- 只写
- 读写
让我们看看它们是如何工作的。登录 WebClient UI 并创建一个名为 "external_share" 的新目录。

向新创建的目录中添加一些文件。
然后选择 "external_share" 文件夹并点击 "Share" 图标。

将出现 "Add a new share" 界面,选择 "Read" scope。可选地,你可以限制共享可使用的次数、使用密码保护共享、按来源 IP 地址限制访问、设置自动过期日期。

然后从共享列表中,选择你刚刚创建的共享并点击 "Link" 图标。将弹出一个窗口,其中包含有关如何使用该共享的说明。

你可以将共享内容作为单个 zip 文件下载,也可以浏览它们并逐个文件下载。你可以复制这些链接并将它们发送给你的外部客户。
可浏览共享的链接将如下面屏幕所示出现。

现在,编辑该共享并将 scope 更改为 "Write"。该共享的链接将显示以下屏幕。

因此你的外部用户可以上传文件,但他们无法浏览或下载共享内容。如果你想防止覆盖现有文件,可以使用标准的 SFTPGo 每目录权限。
再次编辑该共享并将 scope 更改为 "Read/Write"。该共享的链接将显示以下屏幕。

因此现在外部用户可以浏览、下载并向共享目录添加新文件。
品牌定制
可以自定义 SFTPGo Web UI 以匹配你的品牌。以下是 /etc/sftpgo/sftogo.json 中的相关配置部分:
"branding": {
"web_admin": {
"name": "",
"short_name": "",
"favicon_path": "",
"logo_path": "",
"login_image_path": "",
"disclaimer_name": "",
"disclaimer_path": "",
"default_css": "",
"extra_css": []
},
"web_client": {
"name": "",
"short_name": "",
"favicon_path": "",
"logo_path": "",
"login_image_path": "",
"disclaimer_name": "",
"disclaimer_path": "",
"default_css": "",
"extra_css": []
}
}
看一下 WebAdmin 登录屏幕。

默认的 "name" 是 "SFTPGo WebAdmin",因此页面标题是 "SFTPGo WebAdmin - Login"。默认的 "short name" 是 "WebAdmin",因此登录页面显示 "WebAdmin -
你可以通过设置 "logo_path" 和 "short_name" 来自定义已登录用户页面左上角的 logo 和标签。

SFTPGo 使用了优秀的 SB Admin2 主题。如果你想对主题做一些小改动,可以设置 "extra_css" 指向你的自定义 CSS 文件的路径。另一方面,如果你重新构建了 SB Admin 2 CSS,可以将 "default_css" 设置为你的自定义 CSS 的路径。这样我们就避免了先加载默认主题再用你的改动覆盖它。
所有配置的路径(favicon_path、logo_path 等)都必须相对于 "static_files_path"。在 Linux 上,默认的 "static_files_path" 是 /usr/share/sftpgo/static ,例如你可以创建一个 "branding" 目录并将你的自定义资源放在那里。例如,你可以将 favicon 复制到 /usr/share/sftpgo/static/branding/favicon.ico 并将 "favicon_path" 设置为 /branding/favicon.ico。
你可以使用环境变量覆盖任何配置选项,例如可以使用 SFTPGO_HTTPD__BINDINGS__0__BRANDING__WEB_ADMIN__FAVICON_PATH 环境变量设置 Web 管理界面的 favicon 路径。有关使用环境变量配置 SFTPGo 的更多详细信息可以在此处找到。
更改配置文件后,你需要重启 SFTPGo 服务以应用更改。
sudo systemctl restart sftpgo.service
OpenID Connect
如果你已有身份提供商,它很可能支持 OpenID Connect 标准。
现在你可以将身份提供商的用户映射到 SFTPGo 管理员/用户,因此你可以使用身份提供商登录 SFTPGo WebClient 和 WebAdmin UI。
通过定义 pre-login hook,在 OpenID connect 登录成功后也可以自动创建 SFTPGo 用户。你可以配置提供给 pre-login hook 的 token claims 字段,然后在 hook 中创建/更新 SFTPGo 用户时实现你自己的自定义逻辑。
SFTPGo 官方文档说明了将 SFTPGo 与 Keycloak 集成的步骤。其他身份提供商,如 Google Identity、Azure Active Directory、Auth0、OneLogin,已由 SFTPGo 社区测试并确认可用。
一般来说,任何实现了 OpenID Connect Discovery 规范的 OpenID Connect 身份提供商都应该可用。
ACME
SFTPGo 内置了 ACME(Automatic Certificate Management Environment),因此你可以轻松地为 SFTPGo Web UI 和 REST API、WebDAV 服务以及 FTP 服务获取并续期免费的 Let's encrypt TLS 证书。
获取 Let's Encrypt 证书需要完成由 ACME(Automatic Certificate Management Environment)服务器发出的域名验证质询。该质询验证你对要获取证书的域名的所有权。存在不同的质询类型,SFTPGo 支持 "HTTP-01" 和 "TLS-ALPN-01" 质询类型。
要使用 ACME 协议,你需要一个指向你的服务器 IP 的有效域名。
让我们看一个示例配置,我们做以下假设:
- 我们需要为 "sftpgo.com" 域名获取一个 TLS 证书
- 我们已经有一个为 "sftpgo.com" 域名运行在端口 "80" 上的 Web 服务器,Web 根路径是 /var/www/sftpgo.com
打开 SFTPGo 配置文件 /etc/sftpgo/sftpgo.json ,找到 "acme" 部分并按如下方式修改:
"acme": {
"domains": ["sftpgo.com"],
"email": "<you email address here>",
"key_type": "4096",
"certs_path": "/var/lib/sftpgo/certs",
"ca_endpoint": "https://acme-v02.api.letsencrypt.org/directory",
"renew_days": 30,
"http01_challenge": {
"port": 80,
"proxy_header": "",
"webroot": "/var/www/sftpgo.com"
},
"tls_alpn01_challenge": {
"port": 0
}
}
确保 "sftpgo" 用户可以写入 /var/www/sftpgo.com 目录,或者预先创建具有适当权限的 /var/www/sftpgo.com/.well-known/acme-challenge 目录。
通过运行以下命令注册你的账户并获取证书:
sudo -E su - sftpgo -m -s /bin/bash -c 'sftpgo acme run -c /etc/sftpgo'
完成!从现在起,SFTPGo 服务将负责为配置的域名自动续期证书。证书默认存储在 /var/lib/sftpgo/certs 目录中。你现在可以配置 SFTPGo 服务使用这些证书。例如对于 Web UI,按如下方式修改 SFTPGo 配置文件 /etc/sftpgo/sftpgo.json:
"httpd": {
"bindings": [
{
"port": 9443,
"address": "",
"enable_web_admin": true,
"enable_web_client": true,
"enable_https": true,
"certificate_file": "/var/lib/sftpgo/certs/sftpgo.com.crt",
"certificate_key_file": "/var/lib/sftpgo/certs/sftpgo.com.key",
.....
重启 SFTPGo 服务以应用更改:
sudo systemctl restart sftpgo.service
你可以用类似的方式为其他服务启用 TLS。
Geo-IP 过滤
SFTPGO Geo-IP filtering 插件允许根据客户端 IP 地址的地理位置来接受/拒绝连接。
该插件可以读取 MaxMind GeoLite2 和 GeoIP2 数据库。你需要下载 MMDB 格式的国家数据库。
让我们看一个示例配置。我们做以下假设:
- Geo-IP filtering 插件位于 /usr/local/bin/sftpgo-plugin-geoipfilter-linux-amd64 路径
- 国家数据库位于 /var/lib/sftpgo/GeoLite2-Country.mmdb 路径
- 我们只想允许来自意大利的连接
打开 SFTPGo 配置文件 /etc/sftpgo/sftpgo.json ,找到 "plugins" 部分并按如下方式修改:
"plugins": [
{
"type": "ipfilter",
"cmd": "/usr/local/bin/sftpgo-plugin-geoipfilter-linux-amd64",
"args": ["serve", "--db-file", "/var/lib/sftpgo/GeoLite2-Country.mmdb", "--allowed-countries", "IT"],
"sha256sum": "",
"auto_mtls": true
}
]
重启 SFTPGo 服务以应用更改:
sudo systemctl restart sftpgo.service
完成!
当来自被拒绝国家的连接被拒绝时,你将在 SFTPGo 日志中看到类似这样的内容:
{"level":"debug","time":"2022-06-02T14:05:48.616","sender":"plugins.ipfilter.sftpgo-plugin-geoipfilter-linux-amd64","message":"[DEBUG] country not allowed: ip=XXX.XX.XXX.XXX country=NL"}
其他 SFTPGo 插件可在此处获得。
基于 shell 模式限制文件和目录
SFTPGo 支持基于用户和基于目录的类 shell 模式过滤器:可以根据类 shell 模式允许、拒绝文件,并可选择隐藏文件。
让我们看一些示例。假设你想拒绝某个特定目录中所有 jpg 和 png 扩展名的文件。选择要修改的用户,展开 "ACLs" 部分并添加一个类 shell 模式限制。

这样一来,png 和 jpg 扩展名的文件无法被下载或上传,但如果已存在,仍会在目录列表中可见。你可以通过将策略设置为 "Hidden" 来隐藏它们。

"Hidden" 策略是在 v2.3.0 中引入的。