常见问题与排查顺序

重要提示：排查问题时要按照顺序从上到下检查，不要跳步骤。每个问题都列出了检查顺序，按照顺序排查可以更快定位问题。

---

现象：用户能看到目录但无法上传文件

可能原因：

• Linux 文件系统权限不足（服务器层面）
• Virtual Folder 未允许 upload 操作
• Group 权限覆盖了 Virtual Folder，限制了写权限

检查顺序（从上到下，不要跳步骤）：

1. 检查服务器目录是否可写

   • 联系服务器运维人员（System）检查 Linux 文件系统权限
   • 确认 /srv/sftpgo/data/departments/[部门]/[目录] 的权限
   • 确认 SFTPGo 运行用户对该目录有写权限
   • 如果权限不对，需要 System 用户修复
   • ✅ 如果这里有问题，后面都不用看了，先解决这个

2. 检查 Virtual Folder 是否允许 upload

   • 登录 Admin UI，找到对应的 Virtual Folder
   • 查看 Virtual Folder 的权限配置
   • 确认 upload 权限已勾选
   • 如果没勾选，勾选并保存

3. 检查 Group 是否限制了写权限

   • 找到用户所在的 Group
   • 查看 Group 中对这个 Virtual Folder 的权限设置
   • 确认 Group 没有覆盖 Virtual Folder 的写权限
   • 注意：Group 权限优先级高于 Virtual Folder，如果 Group 设置为只读，即使 Virtual Folder 允许上传也不行
   • 如果需要修改，调整 Group 的权限配置

---

现象：Virtual Folder 创建成功但用户看不到

可能原因：

• Virtual Folder 未绑定到 Group
• 用户未加入对应的 Group
• Virtual Path 配置错误
• 用户缓存问题

检查顺序（从上到下，不要跳步骤）：

1. 检查是否已绑定 Group

   • 登录 Admin UI，找到这个 Virtual Folder
   • 查看 Virtual Folder 是否已添加到某个 Group
   • 重要：Virtual Folder 必须绑定到 Group 才能被用户看到
   • 如果没有绑定，找到对应的 Group 并添加

2. 检查用户是否加入该 Group

   • 找到这个用户，查看用户的 Group 列表
   • 确认用户是否在能访问这个 Virtual Folder 的 Group 中
   • 如果用户不在 Group 中，将用户添加到 Group
   • 保存后可能需要用户重新登录

3. 检查 Virtual Path 是否填写正确

   • 查看 Virtual Folder 的 Virtual Path 配置
   • 确认路径格式正确（通常以 / 开头）
   • 如果路径错误，修正并保存

4. 让用户重新登录

   • 有时配置更新后，需要用户重新登录才能看到新目录
   • 建议用户退出并重新登录 SFTPGo

---

现象：权限配置正确但用户仍无法访问

可能原因：

• Linux 文件系统权限不足（最常见）
• Virtual Folder 的 Mapped Path 配置错误，指向了不存在的目录
• 用户未正确加入 Group
• 缓存或服务未重启

检查顺序（从上到下，不要跳步骤）：

1. 检查 Linux 文件系统权限（优先级最高）

   • 联系服务器运维人员（System）检查
   • 确认目标目录 /srv/sftpgo/data/... 是否存在
   • 确认 SFTPGo 运行用户对该目录有访问权限
   • 这是最常见的原因，很多人在 SFTPGo 后台配置了半天，最后发现是 Linux 权限的问题

2. 检查 Virtual Folder 的 Mapped Path

   • 登录 Admin UI，找到对应的 Virtual Folder
   • 查看 Mapped Path（服务器真实路径）是否填写正确
   • 确认这个路径在服务器上确实存在
   • 如果路径错误或不存在，需要：
     • 联系 System 用户创建目录（如果目录不存在）
     • 或修正 Mapped Path 配置（如果路径填错了）

3. 再次确认用户 Group 归属

   • 查看用户的 Group 列表
   • 确认用户确实在正确的 Group 中
   • 确认这个 Group 确实绑定了对应的 Virtual Folder
   • 如果发现有问题，修正配置

4. 重启 SFTPGo 服务（最后手段）

   • 如果所有配置都正确，但用户还是无法访问
   • 联系 System 用户重启 SFTPGo 服务
   • 让用户重新登录

---

现象：用户能看到目录但无法下载文件

可能原因：

• Virtual Folder 未允许 download 操作
• Group 限制了下载权限
• Linux 文件系统只读权限

检查顺序（从上到下，不要跳步骤）：

1. 检查 Virtual Folder 的 download 权限

   • 登录 Admin UI，找到对应的 Virtual Folder
   • 查看是否勾选了 download 权限
   • 如果没有，勾选并保存

2. 检查 Group 的权限设置

   • 找到用户所在的 Group
   • 查看 Group 中对这个 Virtual Folder 的权限
   • 确认 Group 没有限制下载权限
   • 如果 Group 设置为"禁止下载"，需要调整 Group 配置

3. 检查 Linux 文件系统权限

   • 虽然下载通常只需要读权限，但如果 Linux 层面完全禁止读取，也不行
   • 联系 System 用户确认目录的读权限正常

---

现象：新创建的目录用户看不到

可能原因：

• 服务器层面目录已创建，但未在 SFTPGo 中创建 Virtual Folder
• Virtual Folder 创建了但未绑定 Group
• 用户未加入对应的 Group

检查顺序（从上到下，不要跳步骤）：

1. 确认服务器目录已创建

   • 联系 System 用户确认服务器端目录已创建
   • 确认目录路径正确（如：/srv/sftpgo/data/departments/tech/shared）
   • 如果目录不存在，需要 System 用户先创建

2. 检查是否已创建 Virtual Folder

   • 登录 Admin UI，查看 Virtual Folder 列表
   • 确认是否有对应这个目录的 Virtual Folder
   • 如果没有，需要创建 Virtual Folder：
     • Virtual Path：用户看到的路径（如：/tech/shared）
     • Mapped Path：服务器真实路径（如：/srv/sftpgo/data/departments/tech/shared）

3. 检查 Virtual Folder 是否绑定 Group

   • 找到刚创建的 Virtual Folder
   • 确认已添加到对应的 Group 中
   • 如果没有，添加并保存

4. 检查用户是否在 Group 中

   • 确认用户是否加入了对应的 Group
   • 如果没有，将用户添加到 Group
   • 让用户重新登录

---

现象：System 用户无法访问某些目录

可能原因：

• Linux 文件系统权限问题
• System 用户的配置问题（不应该发生）

检查顺序（从上到下，不要跳步骤）：

1. 检查 Linux 文件系统权限

   • System 用户虽然权限最高，但仍受 Linux 文件系统限制
   • 确认目录是否存在
   • 确认 SFTPGo 运行用户有权限访问
   • 注意：System 用户仍然需要通过 SFTPGo 运行用户来访问文件，如果 Linux 层面不允许，System 用户也访问不了

2. 检查 System 用户配置（很少见）

   • 如果 Linux 权限正常，但 System 用户还是无法访问
   • 联系系统管理员检查 System 用户的配置
   • 确认 System 用户的权限设置正确

---

现象：修改权限后用户仍然看不到变化

可能原因：

• 用户未重新登录
• 缓存问题
• SFTPGo 服务需要重启

检查顺序（从上到下，不要跳步骤）：

1. 让用户重新登录

   • 告诉用户退出 SFTPGo 并重新登录
   • 大部分情况下，重新登录就能看到变化

2. 清除浏览器缓存（Web 客户端）

   • 如果用户使用的是 Web 客户端
   • 让用户清除浏览器缓存或使用无痕模式
   • 重新登录

3. 重启 SFTPGo 服务（最后手段）

   • 如果重新登录和清除缓存都不行
   • 联系 System 用户重启 SFTPGo 服务
   • 让用户重新登录

---

快速排查清单

如果遇到问题，可以快速对照这个清单：

• Linux 文件系统权限是否正确？
• 目录在服务器上是否真实存在？
• Virtual Folder 是否已创建？
• Virtual Folder 的 Mapped Path 是否正确？
• Virtual Folder 是否绑定了 Group？
• 用户是否加入了对应的 Group？
• Virtual Folder 的权限配置是否正确？
• Group 的权限是否覆盖了 Virtual Folder？
• 用户是否重新登录了？
• SFTPGo 服务是否正常？

---

如果还是解决不了

如果按照上述步骤排查后仍然无法解决问题：

1. 记录详细信息

   • 用户账号
   • 问题目录路径（Virtual Path 和 Mapped Path）
   • 用户的 Group 归属
   • 具体的错误信息

2. 联系相关人员

   • Linux 权限问题 → 联系 System 用户
   • SFTPGo 配置问题 → 联系 Admin
   • 其他问题 → 联系技术负责人

3. 查看日志

   • 检查 SFTPGo 的日志文件
   • 检查 Linux 系统日志
   • 查看是否有相关错误信息