SFTP存储文件可上传但无法检索的问题排查求助

我正在配置SFTP存储用于上传图片和PDF文件，以下是filesystems.php的配置：

'default' => 'sftp-storage',
'disks' => [
     'sftp-storage' => [
        'driver' => 'sftp',
        'host' => env('GN_HOST'),
        'port' => env('GN_PORT'),
        'username' => env('GN_USERNAME'),
        'password' => env('GN_PASSWORD'),
        'root' => env('GN_DIR_PATH'),
        'visibility' => 'public',
    ],
] 

文件可通过系统正常上传，SFTP存储目录执行ls -l的输出如下：

-rwxrwxrwx. 1 usertwo usertwo  111718 Dec  5 10:46 ggve3PVyVwb1ZzwrzwKWQUzHlNPKDhdE9iJknM1I.png
-rwxrwxrwx. 1 usertwo usertwo 1246354 Dec  5 11:34 Qqr3hbf7Bc9tg2hcYjeZt4YyOAN1XdQsoU3Bh2dn.png

但系统检索文件时，会尝试从public文件夹读取（public文件夹内的文件可正常检索），检索代码如下：

public function show(int $reg_id, $document_name, int $id)
{
    $document_types = DocumentMaster::pluck('document_name')->toArray();

    /*Check if the document requested is a valid document from the list of DocumentMaster stored in database. If not display invalid document type error*/
    if (!in_array($document_name, $document_types)) {
         return response()->json("Document type invalid", 404);
    }
    $document_master_id = DocumentMaster::where('document_name', $document_name)->first()->id;
    $documents = Documents::where('document_master_id', $document_master_id)
                    ->where('reg_id', $reg_id)
                    ->where('id', $id)
                    ->get();

    if ($documents !=null  && count($documents)) {
        return response()->json(['data'=>$documents], 200);
    }
    else {
        $response = ['message' => 'The '.$document_name.' document does not exist for reg_id '.$reg_id];
        return response()->json($response, 404);
    }
    
}

上传至SFTP存储的文件会返回404未找到，响应内容为空，请问我哪里配置或代码出错了？

问题分析与解决 #

核心问题 #

1. 检索逻辑未关联SFTP磁盘：当前代码仅从数据库查询记录，未验证SFTP磁盘上的文件是否存在，也未返回SFTP文件的正确访问路径。前端或后续逻辑默认从public磁盘读取，导致找不到SFTP上的文件。
2. 数据库记录路径可能不匹配：如果数据库存储的是文件相对路径，需确保路径指向SFTP磁盘而非public磁盘。

具体修改步骤 #

1. 添加SFTP文件存在验证：在返回数据前，检查SFTP磁盘上是否存在对应文件，避免返回无效记录：

use Illuminate\Support\Facades\Storage;

// ... 原有代码 ...
if ($documents != null && count($documents)) {
    // 假设documents表中存储文件路径的字段为file_path
    foreach ($documents as $doc) {
        // 验证SFTP磁盘上的文件是否存在
        if (!Storage::disk('sftp-storage')->exists($doc->file_path)) {
            return response()->json(['message' => '文件不存在'], 404);
        }
        // 替换为SFTP文件的可访问URL
        $doc->file_url = Storage::disk('sftp-storage')->url($doc->file_path);
    }
    return response()->json(['data'=>$documents], 200);
}
// ... 原有代码 ...

2. 配置SFTP磁盘的外部访问URL：如果Storage::url()无法生成正确的外部链接，在sftp-storage配置中添加url项，指向SFTP存储的公网访问地址：

'sftp-storage' => [
    // ... 原有配置 ...
    'url' => env('GN_PUBLIC_URL'), // 示例：https://your-sftp-domain.com/storage
],

3. 确认上传时的路径存储逻辑：上传文件时，确保将SFTP磁盘的相对路径存入数据库，而非public磁盘路径：

// 上传示例代码
$path = Storage::disk('sftp-storage')->putFile('documents', $request->file('file'));
// 将$path存入documents表的file_path字段

内容的提问来源于stack exchange，提问作者Joyboy Sharma