Laravel SFTP驱动连接成功但无法查看文件问题排查

环境与配置 #

使用Laravel 10+、PHP 8.2，已配置filesystems.php中的SFTP磁盘：

'sftp_internal' => [
    'driver' => 'sftp',
    'host' => env('INTERNAL_SFTP_HOST'),
    'port' => (int) env('INTERNAL_SFTP_PORT', 22),
    'username' => env('INTERNAL_SFTP_USER'),
    'password' => env('INTERNAL_SFTP_PWD'),
    'root' => env('INTERNAL_SFTP_ROOT'),
    'visibility' => 'public',
    'permPublic' => 0775,
    'directoryPerm' => 0755,
    'timeout' => 30,
],

INTERNAL_SFTP_ROOT设置为/var/sftp。

SFTP服务器配置 #

• 目录权限：

ls -la /var/sftp:
drwxr-xr-x  3 root     root     4096 Jan 30 11:51 .
drwxr-xr-x 16 root     root     4096 Jan 29 14:33 ..
drwx------ 19 sftpuser sftpuser 4096 Jan 30 08:49 portal_uploads

• sshd_config配置：

# override default of no subsystems
# Subsystem     sftp    /usr/lib/openssh/sftp-server
Subsystem sftp internal-sftp

Match User sftpuser
    ForceCommand internal-sftp
    PasswordAuthentication yes
    ChrootDirectory /var/sftp
    PermitTunnel no
    AllowAgentForwarding no
    AllowTcpForwarding no
    X11Forwarding no

问题现象 #

• 通过FileZilla或sftp sftp@<IP_ADDRESS>命令可正常访问并查看/var/sftp/portal_uploads下的文件目录。
• Laravel Tinker中执行以下命令均返回空数组：

Storage::disk('sftp_internal')->allFiles(); // 返回 []
Storage::disk('sftp_internal')->allDirectories(); // 返回 []

• SFTP服务器日志显示连接成功，无错误信息。

解决方案 #

核心原因 #

sshd_config中设置了ChrootDirectory /var/sftp，这会将sftpuser的SFTP会话根目录映射为真实路径的/var/sftp。此时sftpuser视角下的/对应真实服务器的/var/sftp，而你在Laravel配置中设置的root为/var/sftp，相当于让Laravel去访问sftpuser视角下的/var/sftp（即真实路径的/var/sftp/var/sftp），该目录不存在，因此返回空。

修复步骤 #

1. 修改.env文件中的INTERNAL_SFTP_ROOT为/：

INTERNAL_SFTP_ROOT=/

2. 清除Laravel配置缓存（若开启了缓存）：

php artisan config:clear

3. 重新测试：

// 现在可以列出根目录下的portal_uploads目录
Storage::disk('sftp_internal')->allDirectories(); // 返回 ['portal_uploads']
// 访问portal_uploads下的文件
Storage::disk('sftp_internal')->allFiles('portal_uploads');

额外说明 #

• 当前/var/sftp的权限drwxr-xr-x已满足sftpuser的执行与读取需求，无需修改。
• portal_uploads的权限drwx------仅允许sftpuser访问，符合安全要求，无需调整。

内容的提问来源于stack exchange，提问作者Matt Larsuma