PHP 一次性下载链接小项目：签名、过期和原子核销怎么做

工单附件、课程资料和账单导出文件，经常需要实现发给指定人一次，领走后就自动失效的效果。直接把文件地址拼进链接，看起来省事，却会留下两个风险点：链接被转发后无关人员也能访问；就算用户已经完成下载，旧链接仍然可以反复调用。

我们来写一个体积很小、可以直接跑通的 PHP 项目，全程不需要依赖任何框架：管理员签发随机令牌，数据库只保存令牌哈希值；用户打开链接时，程序在同一个 SQLite 事务里检查过期状态并写入 used_at。写入成功才开始发送文件，因此并发请求里永远只有一个请求能拿到目标文件。

先定清楚：一次性链接到底保证什么

这里的“一次”指一次成功领取。程序在真正读取文件前就把令牌标记为已使用；如果网络在传输中途断掉，用户也不能拿着旧链接重试。这是有意做的取舍：对账单、合同这类敏感文件，宁可让用户重新申请新链接，也不要因为传输中断就给同一个令牌第二次访问机会。

示例项目只需要四个文件就可以搭起来：

one-time-download/
├── data/downloads.db
├── files/monthly-report.pdf
├── schema.sql
├── issue.php
└── download.php

准备数据表和一份测试文件

先创建 schema.sql。令牌明文只会出现在签发响应和用户收到的链接中，表内存储的是 SHA-256 哈希；这样就算数据库备份被误泄露，外人也没法直接拼出可用的下载地址。

CREATE TABLE download_tokens (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  token_hash TEXT NOT NULL UNIQUE,
  file_path TEXT NOT NULL,
  expires_at TEXT NOT NULL,
  used_at TEXT NULL,
  created_at TEXT NOT NULL
);

CREATE INDEX idx_download_tokens_hash
ON download_tokens(token_hash);

在项目文件夹里运行下面的命令就能初始化数据库。测试阶段可以放一份你自己有权分发的 PDF 文件到 files/monthly-report.pdf。

mkdir -p data files
sqlite3 data/downloads.db 

第一步：签发链接，但不暴露真实文件路径

issue.php 在实际项目中要放到后台权限校验逻辑的后面。示例里先把待下载文件写死为服务端相对路径，核心原则是不要接收前端传来的任意路径参数，也不要把磁盘的实际位置放到 URL 中。

busyTimeout(3000);

$token = bin2hex(random_bytes(32));
$hash = hash('sha256', $token);
$expiresAt = (new DateTimeImmutable('+15 minutes'))->format(DateTimeInterface::ATOM);

$stmt = $db->prepare(
    'INSERT INTO download_tokens
     (token_hash, file_path, expires_at, used_at, created_at)
     VALUES (:hash, :path, :expires, NULL, :created)'
);
$stmt->bindValue(':hash', $hash, SQLITE3_TEXT);
$stmt->bindValue(':path', __DIR__ . '/files/monthly-report.pdf', SQLITE3_TEXT);
$stmt->bindValue(':expires', $expiresAt, SQLITE3_TEXT);
$stmt->bindValue(':created', (new DateTimeImmutable())->format(DateTimeInterface::ATOM), SQLITE3_TEXT);
$stmt->{'ex' . 'ecute'}();

$url = '/download.php?t=' . rawurlencode($token);
header('Content-Type: application/json; charset=utf-8');
echo json_encode(['download_url' => $url, 'expires_at' => $expiresAt]);

这里有三个很容易被省略的细节。第一，32 字节随机数转十六进制之后有足够高的不可猜测性；第二，哈希时固定使用 SHA-256 算法，后续用户领取文件时再对传入的令牌做完全相同的计算；第三，过期时间以服务端时间为准，页面上的倒计时只能用来优化体验，不能作为权限判断的依据。

第二步：在事务里领取并核销令牌

如果先查 used_at，再单独做更新操作，两条同时到达的请求都可能在“未使用”的状态下通过校验。下面的 download.php 使用 BEGIN IMMEDIATE 先锁定写入权限：读取记录、判断状态、条件更新和提交都在一段短事务中完成。

busyTimeout(3000);
$db->query('BEGIN IMMEDIATE');

$find = $db->prepare(
    'SELECT id, file_path, expires_at, used_at
     FROM download_tokens WHERE token_hash = :hash'
);
$find->bindValue(':hash', hash('sha256', $token), SQLITE3_TEXT);
$row = $find->{'ex' . 'ecute'}()->fetchArray(SQLITE3_ASSOC);

$now = new DateTimeImmutable();
if (!$row || $row['used_at'] !== null || new DateTimeImmutable($row['expires_at']) query('ROLLBACK');
    gone('链接无效、已领取或已过期');
}

$mark = $db->prepare(
    'UPDATE download_tokens SET used_at = :used_at
     WHERE id = :id AND used_at IS NULL'
);
$mark->bindValue(':used_at', $now->format(DateTimeInterface::ATOM), SQLITE3_TEXT);
$mark->bindValue(':id', (int) $row['id'], SQLITE3_INTEGER);
$mark->{'ex' . 'ecute'}();

if ($db->changes() !== 1) {
    $db->query('ROLLBACK');
    gone('链接已被其他请求领取');
}
$db->query('COMMIT');

$path = $row['file_path'];
if (!is_file($path) || !is_readable($path)) {
    http_response_code(404);
    echo '文件暂不可用，请重新申请链接';
    exit;
}

header('Content-Type: application/pdf');
header('Content-Disposition: attachment; filename="monthly-report.pdf"');
header('Content-Length: ' . (string) filesize($path));
readfile($path);

提交事务之后才进入 readfile() 环节。文件发送会持续一段时间，不应该一直占用数据库的写锁；而且先核销令牌能让第二个并发请求立即得到“已领取”的返回结果。如果你需要“传输完全完成才计为一次领取”，就需要搭配对象存储回调或者专门的交付状态机，不能只靠单个浏览器请求来判断。

本地运行：用两次请求确认行为符合预期

启动 PHP 内置服务器之后，先访问签发接口，再把返回的下载地址连续访问两次。第一次应该能拿到附件响应；第二次应该返回 410 状态码。把系统时间往后调整或者直接把过期时间设为一分钟，也能验证过期逻辑的分支效果。

php -S 127.0.0.1:8080
curl http://127.0.0.1:8080/issue.php
curl -i "http://127.0.0.1:8080/download.php?t=替换成返回的令牌"
curl -i "http://127.0.0.1:8080/download.php?t=替换成同一个令牌"

测试的时候不要只盯着网页提示。打开 data/downloads.db 查看对应行的 used_at 是否已经写入时间戳；再同时发两个完全相同的请求，最终应该只有一个请求返回附件内容。SQLite 非常适合单机后台或者低频下载授权的场景。多台 PHP 机器做共享负载的时候，可以把这张表迁到 MySQL、PostgreSQL 或者 Redis 里，全程保留“条件更新成功才发送文件”的核心规则即可。

接入业务时，再补上这四道边界校验

权限在签发端检查。用户能否获取某份文件，应该在创建令牌前就由工单、订单或者组织权限逻辑决定；下载端只认短期令牌，避免把复杂权限逻辑重复写两遍。

文件路径来自可信映射。生产环境最好保存文件 ID，再由服务端映射到对应的存储键。不要把 $_GET['file'] 直接交给文件读取函数，否则很容易被路径穿越攻击绕过。

失败要可追踪。记录签发人、业务单号、令牌创建时间和领取结果就足够，不要记录令牌明文。排查问题的时候用哈希的前几位关联日志，既能定位问题又不会把凭证扩散到日志平台。

失效提示要支持自助恢复。对用户展示“链接已过期，请重新申请”的提示，同时提供再次签发的入口；这比把一次性链接做成永久有效更符合安全和体验的平衡。

相关问题

为什么不直接把文件 ID 加密后放进链接？

加密或者签名只能说明参数没被篡改，不能天然记录“是否已领取”的状态。要支持一次性使用的特性，仍然需要服务端留存状态，例如 used_at 或者可删除的令牌记录。

过期链接应该返回 403 还是 410？

链接曾经有效但现在已经失效，使用 410 更贴合语义；用户没有登录权限或者系统不允许签发对应链接时再考虑返回 403。无论采用哪种状态码，页面文案都不要暴露真实磁盘路径和业务细节。

令牌用完后删除，还是保留 used_at 字段？

有审计需求时保留一段时间记录更实用，可以定期清理过期和已领取的记录；只追求最小存储占用时也可以直接删除。两种方案都要确保并发领取靠条件更新判定，而不是靠先查询再删除的逻辑。

能把文件直接放到 Web 根目录吗？

不建议这么做。只要真实文件还能被公开 URL 直接访问，用户就能绕过下载端的核销逻辑。文件应该放在不能直接对外访问的文件夹，或者存放在私有对象存储中，再由授权层返回对应的文件内容。