lft.php：单文件 PHP 实现 SIP 图片消息中转与游标队列-北京尧图网络

简介面向在局域网或私有服务器部署 Linphone 的开发者这份代码给出图片消息中转的本地化实现用于替代官方服务器中转降低外网依赖并提升内部通信的可控性。压缩包共 1 个 PHP 文件约 2KB核心脚本覆盖图片上传接收、格式与大小校验、转码优化、安全过滤、身份验证、状态日志和接口集成等环节便于按现有环境修改配置。已有 295 人学习适合需要理解 Linphone 图片消息链路或搭建轻量中转服务的中级开发者参考。拿到后可从请求解析与文件落盘逻辑入手结合安全检查与日志机制梳理排错路径并依据实际并发与存储条件调整转码、缓存和权限策略快速形成可运行的内网图片消息中转方案。1. 一个 lft.php 撑起消息图片中转先看清它解决的是哪类麻烦客户端用 SIP MESSAGE 发纯文本一直很稳第一次发图就翻车把图片 base64 塞进消息体几百 KB 的内容直接把 UDP 包撑爆接收端收到一堆拼不回去的分片换 MSRP 又要多开端口、多配一套防火墙规则。这套 lft.php 就是冲着这个场景来的它是一份单文件的 PHP 服务端代码丢到一台 1 核 2G 的小机器或者普通虚拟主机上就能跑专门给某开源 SIP 软电话客户端做消息与图片的中转站客户端只负责把图片上传上来、拿回一个短 ID再把 ID 拼进原本的文本消息里发出去对端收到 ID 后再走 HTTP 把图取回。它适合已经有一套 SIP 信令在跑、但被二进制消息折磨得没脾气的团队适合内网自建、对端数量在几十到几千之间的场景也适合想读懂“最小可用中转服务”长什么样的开发者。不适合的是要公网大规模并发、要端到端加密、要阅后即焚的那类产品单文件写法顶不住。2. 目录与请求链路lft.php 一个入口怎么分派上传、投递和拉取这套代码最反直觉的地方在于“没有路由框架”。所有动作都打在同一个 lft.php 上靠action参数分派靠 HTTP 头传签名靠文件系统当存储。看懂这一点后面所有代码都是它的自然延伸。2.1 部署目录与文件职责解压后落到站点根目录的结构大致是这样我按职责把它拆成三类代码、数据、日志。路径类型职责是否允许外网直读lft.php代码唯一入口分派 upload/send/fetch/ack/gc/get是config.php代码共享密钥、存储路径、体积上限否data/img/数据图片落盘按 ID 前两位做二级目录绝对禁止data/box/数据每个收件人一个消息文件逐行 JSON绝对禁止data/tmp/数据上传临时区、GC 中间态绝对禁止logs/lft.log日志错误与拒绝记录按天切否data/和logs/一定要放在 Web 根之外或者像我在第 4 章给的 Nginx 配置那样显式return 403。这一步没做后面所有鉴权都是摆设——图能上传却能被任何人直接遍历下载。2.2 一次图片消息从客户端到对端的完整链路把时序摊开看一条带图消息其实走了两条完全不同的通道信令走 SIP载荷走 HTTP。这个拆分是整个项目的设计核心。发送端点“发送图片”先做本地压缩把图压到 5MB 以内常见做法是长边 1600px、JPEG 质量 0.8。客户端向lft.php?actionupload发一个 multipart POST带上签名头。服务端嗅探真实图片类型、生成 32 位十六进制 ID、落到data/img/xx/下返回{id, w, h, bytes}。客户端把id拼进 SIP MESSAGE 的正文格式我一般定成[img:xxxxxxxx]或者自定义Content-Type: application/lftjson包体是{body:看图,img:xxxx}。对端收到 MESSAGE解析出id再走actiongetidxxxx或等下一次fetch批量取回。对端渲染成功、上报actionack服务端记下游标这条消息不再重复下发。注意第 4 步短信令通道只承担“信令”正文永远不超过 1KB。只要守住这条线UDP 分片的问题彻底消失图片再大也只影响 HTTP 那一侧。2.3 请求参数与返回结构约定接口只有 6 个参数极少这是单文件服务能维护下去的前提。约定如下action方法关键参数返回uploadPOSTfilemultipartid、w、h、bytessendPOSTfrom、to、body、imgmidfetchGETme、cursorcursor、msgs[]ackPOSTme、midokgetGETid图片二进制gcGET无内部调用removed所有 JSON 返回统一是{ok:true,...}或{ok:false,err:...}。错误码只用 400/401/413/415/500 五个客户端照着判断就行不必猜。{ ok: true, cursor: 1043, msgs: [ {mid:5f3a...,from:1001,to:1002,body:看图,img:9c1e...,ts:1730000000} ] }cursor是字节偏移不是消息序号。这个设计省掉了一张自增表代价是客户端必须原样回传上一次的cursor一旦传错就会重复收或漏收。第 5 章那条“接收端少消息”的坑根子就在这里。3. 核心代码拆解落盘命名、文件队列、游标拉取三段实现单文件不等于一团乱麻。这份 lft.php 的写法值得借鉴常量集中在顶部鉴权先于一切然后 switch 分派每个功能一个函数函数之间只通过文件系统通信没有全局状态。3.1 入口分派与签名校验开头这二十行决定了整套服务的安全边界。?php // lft.php —— 消息/图片中转唯一入口所有请求都从这里进 declare(strict_types1); const LFT_ROOT __DIR__ . /data; // 数据根目录 const LFT_MAX_BYTES 5 * 1024 * 1024; // 单张图片上限 5MB const LFT_TTL 7 * 24 * 3600; // 中转文件保留 7 天 header(Content-Type: application/json; charsetutf-8); $action $_GET[action] ?? $_POST[action] ?? ; $token $_SERVER[HTTP_X_LFT_TOKEN] ?? ; $ts (int)($_SERVER[HTTP_X_LFT_TS] ?? 0); // 1) 先鉴权再干活。鉴权放在 switch 之前避免任何分支漏掉 if (!lft_auth($token, $ts)) { lft_out(401, [ok false, err bad_token]); } // 2) 用 switch 做分派不引入路由表 switch ($action) { case upload: lft_upload(); break; case send: lft_send(); break; case fetch: lft_fetch(); break; case ack: lft_ack(); break; case get: lft_get(); break; case gc: lft_gc(); break; default: lft_out(404, [ok false, err unknown_action]); } // 统一出口设状态码、打 JSON、结束进程 function lft_out(int $code, array $data): void { http_response_code($code); echo json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES); exit; }lft_out()用exit而不是return是这类单文件脚本常见的写法任何一处调用都立刻截断不用层层判断返回值。代价是没法做统一的后置清理所以临时文件必须写在data/tmp/里靠 GC 兜底。签名函数本身只有三行重点是hash_equals和那个 300 秒窗口function lft_auth(string $token, int $ts): bool { $secret lft_config(secret); // config.php 里的共享密钥 if ($token || $ts 0) return false; if (abs(time() - $ts) 300) return false; // 超过 5 分钟的签名直接丢防重放 return hash_equals(md5($secret . $ts), $token); }md5($secret . $ts)这个算法不高级但客户端用任何语言都是三行代码SDK 接入成本极低。如果你的场景对安全性要求高把它换成hash_hmac(sha256, $ts, $secret)然后两边同步改一行即可接口形态完全不变。3.2 图片上传类型嗅探、二级目录与不可猜的 ID上传是整套代码里最容易出安全事故的一段三个校验一个都不能省。function lft_upload(): void { $f $_FILES[file] ?? null; if (!$f || $f[error] ! UPLOAD_ERR_OK) { lft_out(400, [ok false, err no_file]); } if ($f[size] 0 || $f[size] LFT_MAX_BYTES) { lft_out(413, [ok false, err too_large]); } // 关键不要信 $_FILES[type]它来自客户端能随便伪造 $info getimagesize($f[tmp_name]); $allow [IMAGETYPE_JPEG jpg, IMAGETYPE_PNG png, IMAGETYPE_GIF gif, IMAGETYPE_WEBP webp]; if (!$info || !isset($allow[$info[2]])) { lft_out(415, [ok false, err bad_image]); } $id bin2hex(random_bytes(16)); // 32 位十六进制不可枚举 $dir LFT_ROOT . /img/ . substr($id, 0, 2); // 二级目录避免单目录几十万文件 if (!is_dir($dir) !mkdir($dir, 0755, true)) { lft_out(500, [ok false, err mkdir_fail]); } $path $dir . / . $id . . . $allow[$info[2]]; if (!move_uploaded_file($f[tmp_name], $path)) { lft_out(500, [ok false, err save_fail]); } lft_out(200, [ ok true, id $id, w $info[0], h $info[1], bytes $f[size], ]); }逐个说参数$f[size]是服务端拿到的实际字节数比客户端声明的可信$info[2]是getimagesize返回的IMAGETYPE_*常量直接映射成扩展名杜绝.php.jpg这类双扩展名substr($id, 0, 2)把文件散到 256 个目录里10 万张图时单目录也就几百个文件readdir不会卡move_uploaded_file而不是rename是因为只有它才会校验源文件确实是本次上传的临时文件。这里补一个血泪经验is_uploaded_file和move_uploaded_file必须成对出现才能挡住伪造的$_FILES只用一个在某些老版本里是能被绕过的。我一般干脆两个都写上。3.3 消息入队与游标拉取拿文件当队列用消息这一侧没有 Redis、没有 MySQL就是“一人一个文件逐行追加 JSON”。function lft_send(): void { $from lft_clean($_POST[from] ?? ); // 发送方账号 $to lft_clean($_POST[to] ?? ); // 接收方账号 $body trim((string)($_POST[body] ?? )); $imgId preg_replace(/[^a-f0-9]/, , (string)($_POST[img] ?? )); if ($from || $to ) { lft_out(400, [ok false, err bad_peer]); } if ($body $imgId ) { lft_out(400, [ok false, err empty_msg]); } $msg [ mid bin2hex(random_bytes(8)), from $from, to $to, body mb_substr($body, 0, 2000), // 正文硬截断防止塞大段文本 img $imgId, ts time(), ]; // 收件人 ID 做 md5避免账号里出现斜杠路径穿越 $box LFT_ROOT . /box/ . md5($to); if (!is_dir(dirname($box))) { mkdir(dirname($box), 0755, true); } $fh fopen($box, ab); if (!$fh || !flock($fh, LOCK_EX)) { // 必须加排他锁否则并发写会交错 lft_out(500, [ok false, err queue_fail]); } fwrite($fh, json_encode($msg, JSON_UNESCAPED_UNICODE) . \n); fflush($fh); // 落盘再解锁防进程崩溃丢数据 flock($fh, LOCK_UN); fclose($fh); lft_out(200, [ok true, mid $msg[mid]]); }md5($to)这一步看着多余实际是防路径穿越的如果有人把to传成../../etc/passwd不加哈希就直接写到系统目录去了。mb_substr($body, 0, 2000)同理防止有人用一条消息把磁盘写满。拉取端靠字节游标推进代码比队列还短function lft_fetch(): void { $me lft_clean($_GET[me] ?? ); $cursor max(0, (int)($_GET[cursor] ?? 0)); // 上次读到的字节偏移 $box LFT_ROOT . /box/ . md5($me); if (!is_file($box)) { lft_out(200, [ok true, cursor 0, msgs []]); } $fh fopen($box, rb); fseek($fh, $cursor); // 直接跳到游标位置 $chunk (string)stream_get_contents($fh, 256 * 1024); // 单次最多 256KB $end ftell($fh); fclose($fh); // 只消费到最后一个换行剩下的半行留到下一次 $cut strrpos($chunk, \n); if ($cut false) { lft_out(200, [ok true, cursor $cursor, msgs []]); } $valid substr($chunk, 0, $cut 1); $msgs []; foreach (explode(\n, $valid) as $line) { $line trim($line); if ($line ) continue; $m json_decode($line, true); if (is_array($m)) $msgs[] $m; } lft_out(200, [ ok true, cursor $cursor strlen($valid), // 只推进真正消费掉的字节 msgs $msgs, ]); }strrpos($chunk, \n)这一行是整个拉取逻辑的灵魂。没有它256KB 会正好切在一条 JSON 中间客户端json_decode失败那条消息永久丢失而且下一次拉取从错位的地方开始后面全乱。有了它半行数据原样留在文件里游标不推进下次自然读全。3.4 过期回收别让图片把磁盘吃干净中转服务的图片不是永久资产7 天不取基本就是废数据。GC 挂在 crontab 里跑逻辑简单到只有十几行function lft_gc(): void { $deadline time() - LFT_TTL; $it new RecursiveIteratorIterator( new RecursiveDirectoryIterator( LFT_ROOT . /img, FilesystemIterator::SKIP_DOTS ) ); $removed 0; foreach ($it as $f) { if ($f-isFile() $f-getMTime() $deadline) { unlink($f-getPathname()); $removed; } } lft_out(200, [ok true, removed $removed]); }getMTime()取的是文件修改时间上传后没人再动过正好当“存活时长”。注意 GC 要在入口处加 IP 白名单或者干脆走命令行php lft.php gc别让外部随便触发——删除操作被刷一次就是灾难。4. 跑起来Nginx PHP-FPM 环境与 curl 全链路联调代码看懂之后落地只差三件事装扩展、配目录、验链路。这部分我把踩过的顺序原样写出来照着走基本不会卡。4.1 环境与扩展检查PHP 版本 7.4 以上都能跑8.x 更稳str_contains、random_bytes之类不用兼容。必装扩展只有三个fileinfo类型嗅探、gd或imagick可选要做缩略图才装、mbstring正文截断。# 确认版本与扩展 php -v php -m | grep -E fileinfo|mbstring|gd # 缺 mbstring 时按系统装 sudo apt install -y php8.1-mbstring php8.1-gd sudo systemctl restart php8.1-fpmfileinfo一般是内置的mbstring是最常见的缺失项。没有它mb_substr会直接抛致命错误表现为整站 500日志里写Call to undefined function。php.ini里这三个值必须和代码里的LFT_MAX_BYTES对齐否则会出现“客户端说超限、服务端却没收到文件”的诡异现象upload_max_filesize 6M post_max_size 8M max_file_uploads 4 max_execution_time 30post_max_size要比upload_max_filesize大因为它还包含 multipart 的边界和其他字段。这个差值我一般留 2MB太小了偶发失败太大了没意义。4.2 Nginx 虚拟主机与目录权限站点配置重点就两条给够请求体大小、把data/封死。server { listen 80; server_name relay.example.internal; root /var/www/lft; index lft.php; client_max_body_size 6m; # 与 php.ini 的 upload_max_filesize 对齐 location ~ \.php$ { include fastcgi_params; fastcgi_pass unix:/run/php/php8.1-fpm.sock; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_read_timeout 30s; } location /data/ { return 403; } # 数据目录绝不外露 location /logs/ { return 403; } location ~ /\. { deny all; } # 顺手挡掉 .git / .env }权限这块data/要给 PHP-FPM 的运行用户写权限但绝不能给 777sudo mkdir -p /var/www/lft/{data/img,data/box,data/tmp,logs} sudo chown -R www-data:www-data /var/www/lft/data /var/www/lft/logs sudo chmod -R 750 /var/www/lft/data /var/www/lft/logs750的意思是同组可读可执行、其他用户完全不可见。用777省事的项目最后基本都会在某个目录里发现别人上传的东西。4.3 用 curl 走一遍完整收发联调不要一上来就动客户端先用 curl 把四个接口串一遍确认服务端没问题再改 App。# 1. 生成签名secret 换成 config.php 里配置的值 TS$(date %s) TOKEN$(printf %s your-secret${TS} | md5sum | cut -d -f1) # 2. 上传一张图记下返回的 id curl -s -X POST http://127.0.0.1/lft.php?actionupload \ -H X-LFT-Token: $TOKEN -H X-LFT-TS: $TS \ -F file./demo.jpg # 3. 给 1002 发一条带图消息 curl -s -X POST http://127.0.0.1/lft.php?actionsend \ -H X-LFT-Token: $TOKEN -H X-LFT-TS: $TS \ -d from1001 -d to1002 -d body看图 -d img上一步的id # 4. 以 1002 的身份拉取 curl -s http://127.0.0.1/lft.php?actionfetchme1002cursor0 \ -H X-LFT-Token: $TOKEN -H X-LFT-TS: $TS第 3 步返回{ok:true,mid:...}第 4 步返回cursor和msgs数组说明主链路通了。再跑一次第 4 步、把上一步的cursor原样带上应该返回空数组——这一步是验证游标推进正确的最快办法很多人跳过它结果上线后对端一直收到重复消息。提示md5sum的输出带两个空格再跟文件名cut -d -f1是为了只取哈希值。用openssl md5或php -r生成也一样只要和服务端的md5($secret.$ts)拼接顺序一致。4.4 客户端侧要改的三处服务端跑通只是半程客户端不改照样发不出图。第一处是发送逻辑把图片压缩后上传拿到id再组消息别再把 base64 往 MESSAGE 里塞。第二处是消息体格式我一般定成{body:...,img:...}并带上自定义Content-Type对端先按文本解析失败再按 JSON 兜底兼容老版本。第三处是接收逻辑解析到img字段就去actiongetid拉图拉失败要重试两次再显示占位图。5. 避坑与排查上线后最容易翻车的五个点代码跑通和稳定运行是两件事。下面这几条都是我在这类中转服务上真实遇到过的按“现象 → 原因 → 解决”原样列出来遇到时能省半天。5.1 上传与文件系统现象一上传接口返回 200客户端拿到的 id 也在但打开图片是 403。原因几乎都是目录权限和 Nginx 规则打架。data/被location /data/ { return 403; }挡住了如果客户端直接访问物理路径而不是走actionget就必然 403。另一种是mkdir用了0755但父目录属主是 rootPHP-FPM 写不进去。解决图片统一从actionget出由 PHP 读文件后readfile输出物理目录永远不对外。权限上把data/整个 chown 给www-data再chmod -R 750用sudo -u www-data touch data/tmp/probe验一次能不能写。现象二小图正常超过 2MB 的图上传失败PHP 日志里没有记录。原因在 Nginx 的client_max_body_size默认只有 1MB请求在进 PHP 之前就被 413 掉了所以 PHP 侧一片安静日志里啥也看不到。解决Nginx 的client_max_body_size设成 6mpost_max_size设成 8Mupload_max_filesize设成 6M三个值从大到小留余量。排查时先看 Nginx 的access.log状态码413 就说明没到 PHP 这一层。现象三上传的图片扩展名是.jpg但浏览器显示成一段乱码或者直接下载。原因是落盘时用了客户端传来的$_FILES[type]或原始文件名。对方把.php改名成.jpg传上来服务端照单全收。解决只用getimagesize()返回的IMAGETYPE_*常量映射扩展名白名单之外的直接 415。文件名的生成完全抛开用户输入用bin2hex(random_bytes(16))。这两条同时做比任何 WAF 规则都可靠。5.2 消息与并发现象四对端偶尔解析失败一条消息之后就再也收不到新消息了。这是最阴的一条。stream_get_contents($fh, 256*1024)正好切在一条 JSON 的中间客户端json_decode返回 null如果代码里没判空、直接把cursor推到$end下一次就从半行之后开始读后面所有 JSON 全部错位。解决按第 3.3 节那样用strrpos($chunk, \n)找到最后一个完整行游标只推进到那里剩下的半行下次再读。同时客户端也要防御解析失败的那条跳过并打日志不要整体中断。现象五两个人同时给同一个人发消息接收端少了一两条。原因是没有加文件锁两个 PHP 进程同时fopen(..., ab)再fwrite虽然O_APPEND保证了单次写的原子性但json_encode输出较长时内核可能拆成多次写两条消息的字节就交错在一起了读出来谁都不是合法 JSON。解决fopen之后立刻flock($fh, LOCK_EX)fwritefflush之后再flock($fh, LOCK_UN)。别用file_put_contents($box, $line, FILE_APPEND)图省事它的锁粒度不受你控制。压测时用ab -c 20 -n 200打一下send然后逐行json_decode校验那个 box 文件能一次暴露这个问题。6. 二次开发把单文件拆成可维护服务并做一次可回滚的灰度单文件的好处是部署无脑坏处是所有改动都动同一个文件两个人同时改必冲突加功能只能往后追加 case。真要长期维护我建议按“存储 → 分层 → 灰度”三步走每一步都能单独回滚。第一步换存储但别一次换完。先把data/box/的文件队列换成 SQLite表结构就三列id INTEGER PRIMARY KEY、to_user、payload再加个(to_user, id)索引。改动只在lft_send和lft_fetch两个函数里cursor从字节偏移换成id :cursor接口形态一个字都不用变客户端完全无感。等 SQLite 稳了再考虑上 Redis 或 MySQL——到那一步说明你的量已经超过单机文件系统了值得投入。第二步拆文件顺序很讲究。先把lft_auth、lft_out、lft_clean这些纯函数抽到lib/common.php再把 upload/send/fetch 各自抽成lib/transfer.php、lib/queue.php最后lft.php只剩下一个require加 switch。每抽一次就php -l检查一遍、用第 4 章的 curl 脚本回归一遍别攒着一起改。阶段改动范围回归方式回滚成本换 SQLite2 个函数curl 四步重复拉取换回旧 lft.php10 秒拆公共库新增 lib/入口 requirephp -l 全链路删 require1 分钟加 HMAC 签名lft_auth一行客户端一行新旧客户端各测一次改回 md52 分钟换 Redis 队列lft_send/lft_fetch并发压测保留文件队列双写一周第三步灰度这是我踩过坑之后最坚持的一环。中转服务最怕的不是报错是“悄悄丢消息”——用户不会来投诉只会在某天说一句“我上次发的图没收到”。所以任何一次改动我都会让新旧两条链路双写一段时间send时既写文件队列也写新存储fetch只读新存储同时跑一个比对脚本每五分钟抽样一次看两边的消息条数和内容对不对得上。连续对一天没差异再切掉旧链路。验证脚本不需要多复杂一个 CLI 就够# 抽样比对文件队列 vs 新存储只看最近 10 分钟的消息 php tools/compare.php --since600 --sample200 # 输出示例 # file_queue183 new_store183 diff0 # 出现 diff 就打印具体 mid别只看总数压测也别用本机自环扛一下就算完。我一般用两台机器一台ab -c 50 -n 2000打send另一台起 20 个协程持续fetch并校验 JSON 合法性跑十分钟。只要出现一条解析失败就说明锁或者游标还有问题别急着上线。从那以后我每次动这类中转服务的存储层都强制走一遍“双写抽样比对切流”三步哪怕只是改个 SQL也先从 5% 流量开始放。慢是慢一点但省下来的半夜排查时间远不止这些。希望帮到你。本文还有配套的精品资源点击获取

lft.php：单文件 PHP 实现 SIP 图片消息中转与游标队列

相关推荐

用披萨店实战简单工厂模式：从设计到扩展的完整指南

ponytail插件使用指南：轻量级任务聚合工具的设计与实操

SpringBoot共享单车用户大数据分析：从订单数据到运营决策指标

更多资讯

Lua脚本在游戏动态道具系统中的设计与优化

高校心理咨询系统开发：SpringBoot+小程序技术解析

校园点餐管理系统源代码：从课设到高并发实战的避坑指南

Python文件读写与CSV操作在游戏测试中的高效应用

text-to-CAD技术解析：从工程语义理解到STEP/URDF/DXF多格式交付

impeccable用法深度解析：从词源到搭配，彻底告别与perfect、flawless的混用

今日更新

Agent-Reach：打通大模型触达外部系统的最后一公里

深度学习图像隐写分析实战：从CNN原理到毕设源码全解析

AI赋能知识产权供需匹配：专利评估、需求挖掘与多路召回工程实践

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？