SFTPGo API 接口详解与使用指南
2025-07-06 05:47:27作者：凌朦慧Richard
项目概述
SFTPGo 是一个功能强大的文件共享服务，支持通过多种协议（SFTP、HTTP/S、FTP/S 和 WebDAV）安全地共享文件。它提供了灵活的存储后端配置，支持本地目录、S3 存储桶等多种存储方案，并具有虚拟文件夹、用户组管理、双因素认证等高级功能。
API 基础信息
SFTPGo 的 API 遵循 OpenAPI 3.0.3 规范，当前版本为 v2.6.99-dev。API 采用 RESTful 设计风格，主要使用 JSON 作为数据交换格式。
认证方式
SFTPGo API 支持两种认证方式：
- Bearer Token 认证
- API Key 认证
核心 API 功能分类
1. 健康检查
端点：/healthz
这是一个简单的健康检查接口，无需认证，用于验证服务是否正常运行。
2. 令牌管理
管理员令牌
- 获取令牌：
/token(GET) - 注销令牌：
/logout(GET)
用户令牌
- 获取令牌：
/user/token(GET) - 注销令牌：
/user/logout(GET)
3. 管理员管理
密码修改
- 修改密码：
/admin/changepwd(PUT)
个人资料
- 获取资料：
/admin/profile(GET) - 更新资料：
/admin/profile(PUT)
双因素认证
- 获取恢复码：
/admin/2fa/recoverycodes(GET)
4. 公共分享功能
SFTPGo 提供了丰富的文件分享功能，允许用户通过 HTTP 链接共享文件和文件夹。
文件下载
- 下载共享内容：
/shares/{id}(GET) - 下载单个文件：
/shares/{id}/files(GET)
文件上传
- 上传多个文件：
/shares/{id}(POST) - 上传单个文件：
/shares/{id}/{fileName}(POST)
目录操作
- 查看目录内容：
/shares/{id}/dirs(GET)
API 使用示例
获取管理员令牌
GET /api/v2/token
Authorization: Basic [base64编码的用户名:密码]
成功响应示例：
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_at": "2023-05-01T12:00:00Z"
}
下载共享文件
GET /api/v2/shares/abc123/files?path=documents%2Freport.pdf
Authorization: Basic [base64编码的共享凭证]
上传文件到共享目录
POST /api/v2/shares/abc123/report.pdf
Authorization: Basic [base64编码的共享凭证]
Content-Type: application/pdf
[文件二进制数据]
最佳实践
-
令牌安全：获取的访问令牌应妥善保管，避免泄露。建议定期更换令牌。
-
错误处理：API 返回的标准错误码包括：
- 400：请求参数错误
- 401：未授权
- 403：禁止访问
- 500：服务器内部错误
-
文件路径编码：涉及文件路径的参数需要进行 URL 编码处理。
-
大文件处理：上传大文件时，注意设置合适的超时时间和缓冲区大小。
总结
SFTPGo 的 API 设计简洁而强大，涵盖了从基础的健康检查到复杂的文件共享管理等各个方面。通过合理利用这些 API，开发者可以轻松地将 SFTPGo 集成到自己的应用中，实现灵活的文件管理和共享功能。
对于需要更高级功能的用户，SFTPGo 还提供了用户管理、配额设置、IP 列表管理等更多 API 接口，可以根据实际需求进行探索和使用。
