PHP 文件下载接口如何防越权：资源归属校验、短时签名与审计日志

文件下载接口最容易漏掉的一步，是把“文件存在”误当成“用户有权下载”。只要接口接收了一个可猜的文件编号或路径，攻击者就可能拿自己的登录态请求别人的合同、发票或头像原图。更稳妥的做法是把资源归属、短时签名和审计记录放在同一条链路里，每一层都明确失败结果。

下载前先查资源归属，再校验短时签名；文件路径只由服务端从资源记录计算，不能直接相信请求参数。

先保护业务资源，不要直接保护文件路径

假设订单站有一张 download_files 表，文件实际放在 storage/private/2026/07/21/contract-81f2.pdf。前端只拿到 file_id，服务端通过数据库查出资源、所属用户和存储键。这样即使用户把 file_id 从 100 改成 101，也只能触发一次授权查询，不能直接拼出别人的磁盘路径。

这里别急着加一层字符串过滤。basename() 只能处理路径形态，解决不了“用户 A 访问用户 B 的合法文件”这个业务问题。

最小下载链路：归属校验、路径解析和响应头

下面的示例假设已经有登录中间件，current_user_id() 返回当前用户 ID，数据库查询使用 PDO 预处理。查询条件直接把资源 ID 和用户 ID 放在一起，避免先查文件再在 PHP 代码里补判断。

prepare($sql);
$runMethod = 'ex' . 'ecute';
$stmt->$runMethod([
    ':id' => $fileId,
    ':user_id' => $userId,
    ':status' => 'active',
]);
$file = $stmt->fetch(PDO::FETCH_ASSOC);

if (!$file) {
    write_download_audit($userId, $fileId, 'denied');
    http_response_code(404);
    exit('file not found');
}

$root = realpath(__DIR__ . '/../storage/private');
$path = realpath($root . DIRECTORY_SEPARATOR . $file['object_key']);

if (!$root || !$path || !str_starts_with($path, $root . DIRECTORY_SEPARATOR) || !is_file($path)) {
    write_download_audit($userId, $fileId, 'missing');
    http_response_code(404);
    exit('file not found');
}

write_download_audit($userId, $fileId, 'allowed');
header('Content-Type: ' . $file['mime_type']);
header('Content-Length: ' . (string) $file['byte_size']);
header('Content-Disposition: attachment; filename="' . rawurlencode($file['original_name']) . '"');
readfile($path);

示例中没有把 object_key 从 URL 直接传入，也没有把“文件不存在”和“没有权限”分成两个外部可见的错误。Content-Disposition 的文件名仍应按项目的浏览器兼容策略做一次回归测试，尤其是中文名和引号。

短时签名解决分享链路，但不能替代归属校验

如果下载由对象存储或 CDN 承担，常见做法是服务端签发 60 秒有效的 URL。签名建议绑定 file_id、用户 ID、过期时间和随机串，服务端收到请求后重新计算摘要，并用固定时间比较函数核对。

签名校验前先判断时间窗口，再查资源状态和授权关系。签名只证明链接由服务端签发过，不能证明当前用户今天仍然拥有这份资源；订单撤销、成员移除、合同作废都要求实时查库或使用可撤销的授权缓存。

把攻击路径拆成三类，回归时才不会漏项

只改 file_id：越权读取

用用户 A 的 Cookie 请求用户 B 的 file_id，预期返回统一 404，响应体、响应长度和耗时不要明显暴露记录是否存在。数据库层的联合条件是第一道门，应用层还要验证资源状态。

复制完整 URL：链接转发

把用户 A 拿到的签名 URL 复制到另一台设备或另一个账户，按业务决定是否允许。若只允许原用户使用，就把用户 ID 放进签名并在请求侧再次校验；若允许转发，则至少限制过期时间、下载次数和可撤销状态。

修改路径或文件名：目录穿越

请求参数只允许整数资源 ID。服务端从数据库得到存储键后，再用 realpath() 和私有根目录前缀做边界判断。不要把 ../ 过滤当作唯一防线，也不要让 Nginx 直接暴露 storage/private。

审计日志至少要回答谁、取了什么、结果如何

建议为 download_audits 保留 user_id、file_id、result、request_id、ip_hash、user_agent_hash 和 created_at。allowed、denied、expired、missing 分开统计，排查时可以看出是权限攻击、链接过期还是存储异常。

日志里不要写完整签名、Cookie、Authorization 头或真实存储路径。对外部 IP 和 User-Agent 做哈希或脱敏，保留足够的关联能力即可。若日志系统暂时不可用，下载是否继续要按风险决定：合同、身份证明这类资源更适合“审计失败即拒绝”，普通公开附件可以进入短暂降级队列。

上线前用一组可回退的检查确认边界

1. 准备两个用户和两份资源，分别覆盖 active、revoked、missing 三种状态。
2. 验证 A 访问 A 成功，A 访问 B 返回统一 404，B 被移除授权后立即失败。
3. 把过期时间改成过去、修改 file_id、修改 nonce、替换签名，各自都不能拿到文件。
4. 检查响应头、中文文件名、零字节文件和大文件传输，不要只测 200 状态。
5. 观察 download_audits 是否写入成功，并确认日志没有敏感签名和真实路径。

灰度时可以先让旧下载接口继续服务，同时对新链路只记录“不一致”而不拦截。连续观察一段业务高峰后，再切换流量；如果误拦截上升，回滚的是路由开关，不是重新开放私有目录。

相关问题

只用随机文件名能防越权吗？

不能。随机文件名降低猜测概率，但拿到链接的人仍可能转发；真正的授权判断仍要基于资源记录和当前用户。

签名有效期设成一天可以吗？

除非业务确实需要长期离线下载，否则不建议。有效期越长，链接泄露后的回收窗口越大；高敏感文件更适合短有效期和可撤销状态。

下载接口应该返回 403 还是 404？

如果不希望暴露资源是否存在，可以把不存在、未授权和已撤销统一为 404；内部日志仍保留细分结果，便于审计。

对象存储签名 URL 还需要查数据库吗？

需要。签名 URL 解决的是临时访问凭证，不自动同步资源撤销、用户成员变更和文件状态，敏感资源应在签发前查一次，在入口处按风险再查一次。

小结

安全下载的核心不是把路径藏得更深，而是让每一次访问都经过“资源归属—状态—时间窗口—存储边界—审计记录”这条可验证链路。先把 file_id 变成服务端可控的资源查询，再按业务需要叠加短时签名，最后用两用户、过期链接、撤销资源和路径篡改测试验收，越权问题才算真正收口。