PHP 私有文件安全访问

wen PHP项目 2026-08-10 2

本文目录导读：

PHP 私有文件安全访问

目录结构设计（物理隔离）
核心实现逻辑（脚本代劳）
关键安全点深度解析
高级安全策略（防御纵深）
反模式（不要这样做）
完整示例：签名 URL + 权限验证 + 防下载代理
服务器配置加固（可选）
保证私有文件安全的四大黄金法则

在 PHP 中实现私有文件安全访问（即用户需要登录或授权后才能获取文件内容，无法直接通过 URL 访问），通常需要以下几个核心步骤：

目录结构设计（物理隔离）

将需要保护的私有文件存放在 Web 根目录之外（/var/www/private/），这样用户无法通过任何 URL 直接访问到它们。

/project-root
    /public_html          (Web 根目录，通常是 Apache/Nginx 的 root)
        index.php
        download.php
    /private-data         (放在该目录下，Web 服务器禁止访问)
        secret-files/
            user1-report.pdf
            financial-data.xlsx

核心实现逻辑（脚本代劳）

通过一个 PHP 脚本（如 download.php）来接受请求，验证身份后，将文件内容流式输出，同时设置正确的 HTTP 头。

示例代码：简易安全的下载脚本

<?php
// download.php
session_start();
// 1. 身份验证（必须登录）
if (!isset($_SESSION['user_id'])) {
    http_response_code(403);
    die('Forbidden: You must log in first.');
}
// 2. 参数校验（防路径穿越）
if (empty($_GET['file']) || !is_string($_GET['file'])) {
    http_response_code(400);
    die('Invalid filename.');
}
// 3. 清理并构建完整的绝对路径
$baseDir = '/var/www/private-data/secret-files/'; // 确保尾部有斜杠
$fileName = basename($_GET['file']);            // 彻底移除路径，只取文件名
$fullPath = $baseDir . $fileName;
// 4. 检查文件是否存在且可读
if (!file_exists($fullPath) || !is_readable($fullPath)) {
    http_response_code(404);
    die('File not found.');
}
// 5. 可选：检查用户权限（该用户是否拥有此文件）
// 假设用户 ID=1 只能访问 user1-report.pdf
// if (strpos($fileName, 'user' . $_SESSION['user_id'] . '-') !== 0) {
//     http_response_code(403);
//     die('Access denied to this file.');
// }
// 6. 发送文件
$fileSize = filesize($fullPath);
header('Content-Description: File Transfer');
header('Content-Type: application/octet-stream');
header('Content-Disposition: attachment; filename="' . $fileName . '"');
header('Expires: 0');
header('Cache-Control: must-revalidate');
header('Pragma: public');
header('Content-Length: ' . $fileSize);
readfile($fullPath);
exit;
?>

前端调用方式：

<a href="/download.php?file=user1-report.pdf">下载报告</a>

关键安全点深度解析

A. 路径穿越防护（Path Traversal）

虽然使用了 basename()，对于更复杂的需求（如子目录结构），建议使用 白名单映射 或 严格正则校验：

// 更强的防护：将请求映射到服务器端已知的文件 ID
// $_GET['id'] = 123，服务器端查表得到 /private/user_uploads/123.pdf
$allowedFiles = [
    1 => 'contract-2023.pdf',
    2 => 'invoice-001.pdf'
];
$id = (int)$_GET['id'];
if (!array_key_exists($id, $allowedFiles)) {
    die('File not allowed');
}
$fullPath = $baseDir . $allowedFiles[$id];

B. 用户权限校验（ACL）

这是最容易被忽略的一点。仅仅登录是不够的，必须验证登录用户是否被授权访问该文件。

// 建议读取文件所有者信息或用数据库关联
$ownerId = getFileOwnerIdFromDb($fileName); // 自定义函数
if ($ownerId !== $_SESSION['user_id']) {
    http_response_code(403);
    die('You do not have permission to access this file.');
}

C. 防止文件内容被缓存（隐私泄露）

某些浏览器/代理可能会缓存响应，针对敏感文件：

header('Cache-Control: no-store, no-cache, must-revalidate, max-age=0');
header('Cache-Control: post-check=0, pre-check=0', false);
header('Pragma: no-cache');

D. 大文件的流式传输（内存优化）

readfile() 对于大文件（>100MB）可能占满内存，改用 fopen() + fpassthru()：

// 推荐使用此方法代替 readfile()
$handle = fopen($fullPath, 'rb');
if ($handle) {
    while (!feof($handle)) {
        echo fread($handle, 8192); // 8KB 块传输
        ob_flush();
        flush();
    }
    fclose($handle);
}

高级安全策略（防御纵深）

策略	实现方式
临时授权令牌	生成带过期时间的签名 URL：`?token=hash(hmac_sha256, user_id\|file_id\|expiry, secret_key)`，服务端验证时间戳和签名。
防盗链	检查 `$_SERVER['HTTP_REFERER']` 是否来自本域（不可靠，仅做辅助）。
加密	文件在磁盘加密存储，PHP 读取后 `openssl_decrypt` 再输出；密钥存放在环境变量或 KMS 中。
审计日志	记录谁在什么时候下载了什么文件（`error_log` 或写入数据库）。
超时限制	限制单次下载进程执行时间，防止 DDoS 占用 PHP 进程：`set_time_limit(60)`。

反模式（不要这样做）

// ❌ 危险：将文件放在 Web 根目录，用 PHP 读取
// 用户如果是攻击者，可能猜出路径直接访问 /uploads/private/xxx.pdf
// ❌ 危险：只用 basename() 但不检查子目录
// basename('../secret.txt') 结果是 'secret.txt'，但如果有特殊需求可能导致逻辑绕过
// ❌ 危险：依赖用户提供的路径（即使有权限）
// 应该用数据库 ID 映射，而不是让用户直接传文件名。

完整示例：签名 URL + 权限验证 + 防下载代理

<?php
// secure_download.php
session_start();
const SECRET_KEY = 'your-very-long-random-secret-key-here';
const DOWNLOAD_TTL = 3600; // 1小时有效
function generate_download_link($user_id, $file_id, $expires) {
    $data = $user_id . '|' . $file_id . '|' . $expires;
    $sig = hash_hmac('sha256', $data, SECRET_KEY);
    return 'download.php?file_id=' . $file_id . '&expires=' . $expires . '&sig=' . $sig;
}
// 下载界面
if ($_SERVER['REQUEST_METHOD'] === 'GET' && isset($_GET['file_id'])) {
    $user_id = $_SESSION['user_id'];
    $file_id = (int)$_GET['file_id'];
    $expires = (int)$_GET['expires'];
    $sig = $_GET['sig'] ?? '';
    // 验证令牌
    $expected_sig = hash_hmac('sha256', "$user_id|$file_id|$expires", SECRET_KEY);
    if (!hash_equals($expected_sig, $sig)) {
        http_response_code(403);
        die('Invalid token');
    }
    // 验证过期
    if (time() > $expires) {
        http_response_code(410);
        die('Link expired');
    }
    // 授权检查（结合数据库）
    $allowed = checkUserFilePermission($user_id, $file_id);
    if (!$allowed) {
        http_response_code(403);
        die('Unauthorized');
    }
    // 获取真实路径（必须从服务器端映射，禁止用户指定路径）
    $fileInfo = getFileInfoFromDB($file_id);
    $fullPath = '/var/www/private/' . $fileInfo['stored_name'];
    // 流式输出
    header('Content-Type: ' . mime_content_type($fullPath));
    header('Content-Disposition: inline; filename="' . $fileInfo['original_name'] . '"');
    header('Content-Length: ' . filesize($fullPath));
    header('Cache-Control: private, no-store');
    $fp = fopen($fullPath, 'rb');
    fpassthru($fp);
    fclose($fp);
    exit;
}
?>

服务器配置加固（可选）

在 Apache 中如果必须将私有文件放在 Web 根目录内（实在无法避免），可以用 .htaccess 强制拦截：

# /uploads-private/.htaccess 
Require all denied

或在 Nginx 中：

location ~* ^/uploads-private/ {
    deny all;
    return 403;
}

保证私有文件安全的四大黄金法则

隔离：文件存放位置永远在 Web 根目录之外。
代理：所有访问必须通过 PHP 脚本（脚本内完成验证+授权）。
映射：用户请求传递 ID，不用真实文件名/路径。
验证：登录态 + 具体文件权限 + 失效签名（可选）。