简介面向Linphone局域网或私有服务器部署场景压缩包内提供重写后的图片消息中转服务端lft.php源码解决自定义部署中依赖官方服务器中转带来的外网依赖问题适合需要在隔离网络或自有服务器上搭建安全可控通信环境的开发与运维人员。压缩包为单文件zip仅含1个php文件大小约2KB代码精简便于直接部署或按需二次修改。服务端实现了从接收图片上传、格式与大小校验、调用GD库或Imagick转码优化到结合SIP/MSRP协议正确转发消息的完整链路同时加入防止恶意文件上传、路径遍历、安全文件命名及身份验证等防护机制并配有日志记录便于调试维护针对自定义部署还预留了API集成与性能优化思路。已有293人学习/下载适合具备一定PHP基础、希望在内网环境实现同类消息中转服务的开发者参考使用。1. 为什么 Linphone 发图片必须有一个 lft.php 中转服务要用 Linphone 给联系人发一张截图试过的朋友都知道直接把文件往对话里拖是不行的——对方收到的不是图片而是一串以 http 开头的地址点开才能看到图。这串地址就是消息图片中转服务端返回的。标题里的 lft.php就是承担这个中转职责的 PHP 服务端代码它接收 Linphone 客户端 POST 上来的图片把文件保存到磁盘再回给客户端一个可下载的 URL让客户端把这个 URL 塞进 SIP 消息里发给对方。对自建 SIP 环境、不想把图片放进第三方服务的团队这个文件就是整条链路最小也最关键的一环。下面从头到脚把这条链路拆开讲清楚从原理到部署再到踩坑。2. 从 SIP 信令到 HTTPlft.php 是如何成为图片中转的2.1 为什么 SIP MESSAGE 不能直接把图片发过去SIP 协议最初是为呼叫信令设计的MESSAGE 方法最擅长承载的是一段文本。一条几 KB 的即时消息走 SIP 信令没有问题但换成图片就完全不同。一张手机截图随便 1 MB 以上1080p 的合照动辄 3~4 MB很多代理和网关对 SIP 消息体有大小限制超过几百 KB 的消息要么被静默丢弃要么直接触发对端服务器报错。把图片塞进 SIP 信令里根本不是改一个配置能解决的这是协议层对「大内容」的天然不适。Linphone 的做法是把大内容从信令里拆出去交给 HTTP。发送方先把图片 POST 到一台中转服务器服务器返回一个可下载的 URL这个 URL 被写进 SIP 消息的 body 里发给接收方。接收方拿到消息后通过这个 URL 去下载真正的图片。SIP 信令里始终只有几 KB 的文本图片流量全走 HTTP两端协议边界清晰信令层也不需要为文件传输调大缓冲区。这个设计不是 Linphone 独有IMS 和 RCS 生态里也有类似思路只是实现细节不同。差别在于中转服务器是公共的还是自己的。公共中转开箱即用但文件放在第三方手里lft.php 这类脚本解决的就是「我自己有台服务器想自建中转」的需求。理解了这个链路后面所有配置都在回答一个核心问题怎么让 HTTP POST 和 HTTP GET 两条路都走得通。2.2 lft.php 的四个动作收文件、改名、落盘、回 URLlft.php 这类中转脚本核心流程可以压缩成四个动作。第一步接收客户端 POST 上来的文件字段字段名一般是 file第二步丢掉原始文件名自己生成随机名用白名单校验后缀第三步用 move_uploaded_file 把文件从 PHP 临时目录移到持久化目录第四步拼出完整可访问的 URL返回 JSON。发送方拿到 URL 后把它放进 SIP 消息。四个动作里第二步最容易被人偷懒省略。保留原始文件名会带来两类真实事故一类是路径穿越文件名里带../就可能把文件写到目录外面另一类是重名覆盖两个用户同时传 IMG_001.jpg后到的把先到的盖掉。把原始名丢掉换成随机字符串这两类问题直接从根上消失。很多线上 404 和文件丢失都不是代码逻辑错而是这一步偷懒造成的。回 URL 这一步也有讲究。脚本必须知道当前请求是 HTTP 还是 HTTPS以及 Host 是什么否则返回的可能是http://内网IP/xxx.jpg这种接收方根本打不开的地址。这就是为什么第 5 章会有一个专门的混合内容排查项。2.3 自建中转和公共中转怎么选Linphone 生态里有公共的文件传输服务客户端设置里填好「文件传输服务器」地址就能用不用管部署。但公共服务的短板也明显文件存在别人服务器上隐私和合规说不清楚上传体积有上限发大视频经常失败服务一旦波动你的图片消息集体打不开。自建 lft.php 就是把这三块控制权拿回来自己定体积、定保留时间、定日志。对比维度公共中转自建 lft.php文件隐私第三方服务器可读自己服务器可控体积上限通常不透明自己设受磁盘限制可用性依赖公共设施依赖自己运维部署成本零一个 PHP 文件加半页配置日志与排障基本拿不到全在自己手里如果用户只在内网互发消息自建几乎是唯一选择如果跑公网配上 HTTPS 就能让整条链路完整。自建的前提是有一台能跑 PHP 的服务器这正好引出下一个问题为什么这类中转脚本的社区常见实现偏偏是 PHP。2.4 为什么这类中转服务常见实现偏偏是 PHP做中转服务Node、Go、Python 都行但搜索框里查「Linphone 文件传输中转服务端代码」出现频率最高的还是 PHP 文件。原因很现实部署门槛最低。一台普通虚拟主机装上 php-fpmWeb 服务器不用大改把文件丢进目录就能跑。Go 要编译二进制Node 要保持进程常驻Python 要折腾虚拟环境和 WSGI而 PHP 天生就是「请求进来、跑完退出」的模型跟这种低频率的中转上传场景完全匹配。lft.php 这类脚本通常只有几十行不引入框架不依赖 Composer。PHP 的上传处理函数也是现成的$_FILES帮你解析 multipart/form-datamove_uploaded_file处理临时文件转移is_uploaded_file做上传来源校验底层脏活基本都被语言封装好了。代价是默认参数保守php.ini 里好几个限制要联动调Web 服务器层还有一个 body 大小限制两层叠加容易出诡异的 413。这些坑不怪 PHP怪没把参数对齐。第 4 章专门把这些参数单拎出来讲每一条都对应一个真实故障。3. 部署 lft.php从 PHP 环境到第一个可下载 URL 的最小命令3.1 环境准备PHP 版本、必需扩展与 php -v 核查先确认服务器上有 PHP 环境。lft.php 不需要重框架但建议 PHP 7.4 以上推荐 8.1 / 8.2。Debian 系用 apt 装Windows 上做测试可以用 phpstudy 这类集成环境注意 phpstudy 默认 PHP 版本通常偏低先升级 PHP 版本再跑避免旧版本对random_bytes等函数支持不到位。代码示例里的hash_equals在 PHP 5.6 起可用random_bytes在 PHP 7.0 起可用7.4 是合理下限。装好后逐项确认三件事php-fpm 在跑、扩展 fileinfo 可用、curl 扩展存在。直接执行php -v php -m | grep -E fileinfo|mbstring|curl输出里能看到 PHP 版本号以及扩展列表。逻辑说明php -m列出当前 CLI 编译进来的扩展grep 过滤出我们要的项如果 fileinfo 没出现Debian 系执行apt install php-fileinfoWindows 下在 php.ini 里去掉对应 extension 行的分号。这里有个隐蔽坑CLI 和 FPM 是两个 SAPI扩展配置不一定一致命令行能看到不代表网页端能用所以还要用systemctl status php8.2-fpm看一眼进程状态最好再通过网页请求确认。参数说明如果机器上同时有多套 PHPphp -v看到的只是默认 CLI 版本未必是 Nginx 里 fastcgi_pass 指向的那套。要确认当前生效版本直接看/run/php/目录下存在哪个版本的 sock 文件。真实排障里CLI 有 fileinfo 而 FPM 没有的情况非常普遍改完 php.ini 记得 reload别改错文件。3.2 lft.php 最小实现一段可以直接抄走的 PHP 源码下面这段是 lft.php 的基线实现不接数据库、不用框架逻辑全写在注释里。?php /** * lft.php - Linphone 消息图片中转最小实现 * 只接收 POST 上传返回带 URL 的 JSON下载走 Web 服务器静态文件 */ $token set-a-strong-token-here; $inToken $_GET[token] ?? ($_SERVER[HTTP_X_LFT_TOKEN] ?? ); if (!hash_equals($token, $inToken)) { http_response_code(403); exit(forbidden); } if ($_SERVER[REQUEST_METHOD] ! POST || empty($_FILES[file])) { http_response_code(400); exit(bad request); } if (!is_uploaded_file($_FILES[file][tmp_name])) { http_response_code(400); exit(invalid upload); } $uploadDir __DIR__ . /lft_files/; if (!is_dir($uploadDir)) { mkdir($uploadDir, 0755, true); } $ext strtolower(pathinfo((string)($_FILES[file][name] ?? ), PATHINFO_EXTENSION)); $allowedExt [jpg, jpeg, png, gif, bmp, webp, pdf, mp3, mp4, txt, bin]; $ext in_array($ext, $allowedExt, true) ? $ext : bin; $filename bin2hex(random_bytes(16)) . . . $ext; $dest $uploadDir . $filename; if (!move_uploaded_file($_FILES[file][tmp_name], $dest)) { http_response_code(500); exit(save failed); } $baseUrl https:// . ($_SERVER[HTTP_HOST] ?? localhost) . /lft/ . $filename; error_log(sprintf([lft] save%s size%d from%s, $filename, $_FILES[file][size], $_SERVER[REMOTE_ADDR] ?? )); header(Content-Type: application/json); echo json_encode([url $baseUrl, size $_FILES[file][size]]);代码逻辑分四段。第一段做 token 校验用hash_equals而不是避免时序比较攻击第二段确认是 POST 且带 file 字段再通过is_uploaded_file确认临时文件来自上传机制第三段生成随机文件名并落盘第四段拼 URL 并返回。URL 里的/lft/前缀要和后面 Nginx 配置里的 alias 对应改了一边忘了另一边就会出现 404。参数说明token默认值必须换掉allowedExt按业务收紧如果只做聊天图片建议只留jpg/jpeg/png/gif/webp五个后缀表面积越小越安全。random_bytes(16)生成 32 位十六进制文件名正常情况下不会碰撞。URL 里固定用https://如果你的服务还在 http 阶段先改成http://或者直接用第 5 章里给的动态判断版本。3.3 Nginx 配置上传走 PHP下载走静态别名代码落盘后要让 Web 服务器知道两件事lft.php要被 PHP 执行/lft/开头的 URL 要映射到磁盘上的图片目录。推荐的做法是上传走 PHP-FPM下载走 alias 静态文件。下载不经过 PHP省一次进程开销也少一个可执行的入口。server { listen 443 ssl; server_name sip.example.com; root /var/www/lft; index index.php; client_max_body_size 20m; location /lft/ { alias /var/www/lft/lft_files/; location ~ \.php$ { deny all; } } location ~ \.php$ { include fastcgi_params; fastcgi_pass unix:/run/php/php8.2-fpm.sock; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; } }参数说明client_max_body_size是 Nginx 层的请求体上限必须大于等于 php.ini 的post_max_size否则上传在最外层被切断。alias末尾的斜杠不能丢。fastcgi_pass的 sock 路径要和你机器实际的 PHP 版本对应php8.2-fpm.sock只是示例。嵌套的location ~ \.php$保证有人往 lft_files 目录塞 PHP 文件也无法通过/lft/路径执行。目录权限这步不能省执行sudo mkdir -p /var/www/lft/lft_files sudo chown -R www-data:www-data /var/www/lft sudo chmod 755 /var/www/lft注意有的环境 Web 用户是nginx或www不是www-data。用ps aux | grep php-fpm看 master 进程跑在哪个用户下把属主改成那个用户。权限给错上传时会遇到 500 和日志里的 Permission denied。3.4 curl 双命令验证上传和下载配置完重启 Nginx 和 PHP-FPM马上做一次端到端验证。准备一张测试图curl -i -F file/tmp/test.png https://sip.example.com/lft.php?tokenset-a-strong-token-here curl -i -o /tmp/get-test.png https://sip.example.com/lft/上一条返回的url文件名第一条命令把文件 POST 给 lft.php返回 JSON 带 url 字段把 url 字段里的文件名拼到第二条命令。第二条走静态路径返回 200 且文件一致说明两条链路都通了。-i让 curl 输出响应头-F表示以 multipart/form-data 提交文件-o把下载内容写到指定文件。如果第一条返回 403检查 token返回 400检查字段名是不是file返回 413先看 Nginx error.log 里的client intended to send too large body。再做一步更彻底的校验对比两边文件内容md5sum /tmp/test.png /tmp/get-test.png两个值一致说明落盘和下载没有被中间层篡改。我一般还会用ls -l /var/www/lft/lft_files看一眼文件属主是不是 www-data这个细节决定了后面清理脚本能不能稳定跑起来。4. lft.php 上线前要调好的 4 个参数与目录清理策略4.1 php.ini 的 upload_max_filesize 与 post_max_size代码能跑通只是第一步真正让中转服务稳定的是把 PHP 侧参数对齐。PHP 默认upload_max_filesize只有 2Mpost_max_size是 8M一张手机原图就能超。上传在 PHP 层被切断时页面表现为 500 或空响应日志里出现UPLOAD_ERR_INI_SIZE很多人第一反应是代码写错了其实底层参数没动。推荐这套基线值upload_max_filesize 20M post_max_size 21M max_file_uploads 10 memory_limit 128M逻辑说明post_max_size要比upload_max_filesize略大因为 POST 请求体除了文件本身还要容纳 multipart 边界字段和头部信息两者设成一样会在边界上出现「文件没超但请求体超了」的怪问题。memory_limit不用跟着文件大小走PHP 的 multipart 解析不会把整个文件加载进内存128M 足够常规聊天场景。改完 php.ini 执行systemctl reload php8.2-fpm。注意 php.ini 有 CLI 和 FPM 两份改的是 FPM 那份路径一般在/etc/php/8.x/fpm/php.ini用php --ini可以确认当前加载的是哪份。同时核对 Nginx 的client_max_body_size两者对齐才不会出现 Nginx 先挡一刀、PHP 配置根本轮不到生效的情况。4.2 文件名随机化为什么后缀白名单比黑名单可靠文件名字段的处理最容易翻车的地方是直接用原始文件名。除了路径穿越和重名覆盖还有一个隐蔽问题如果下载路径恰好允许执行 PHP别人传一个.php后缀的文件上来你的中转服务就变成了一个可执行文件上传点。所以后缀校验必须做成白名单而不是黑名单。黑名单的思路是「拦掉我知道的危险后缀」问题在于你永远不知道攻击者会用什么奇怪后缀绕过去白名单的思路是「没写出来的都不允许」比如只放行图片后缀其他一律落成bin。严格程度完全不同。上面代码里的allowedExt就是白名单建议聊天图片场景直接收紧成下面这样$allowedExt [jpg, jpeg, png, gif, webp];配合bin2hex(random_bytes(16))生成的 32 位随机十六进制文件名两个用户同时传 IMG_001.jpg磁盘上会出现两个互不相干的随机名文件谁也不会覆盖谁。文件名本身不可预测等于给下载 URL 加了一层免费的访问控制。4.3 定期清理find -mtime 与 systemd timer中转服务是只增不减的上线一周磁盘被图片塞满这种事我见过不止一次。常见做法是加一个清理任务保留最近 7 天的文件更早的删掉。一条 find 命令就能完成find /var/www/lft/lft_files -type f -mtime 7 -delete参数说明-type f只找普通文件-mtime 7表示修改时间超过 7 天的文件边界上 7 天整不算想「刚满 7 天就删」可以换成-mtime 6。如果按日期分子目录这条命令对嵌套目录不生效得换成以目录为单位处理。定时执行用 cron 最简单放到/etc/cron.d/lft-clean*/30 * * * * find /var/www/lft/lft_files -type f -mtime 7 -delete删除操作没有后悔药。我一般会先手动跑一遍不带-delete的 find把输出看几行再放开自动清理并观察一周确认没有用户需要取回超过 7 天的文件。公共中转保留时间可以短到 48 小时内网自建 7 天是合理默认按业务自己调。4.4 防滥用token 与请求来源限制lft.php 部署到公网后立刻会暴露在两件事上扫描器探测上传接口以及陌生人往服务器传文件。token 校验是第一道防线。token 传递有两种形式URL 查询参数或自定义 Header。Linphone 这类客户端一般只在「文件传输服务器 URL」设置项里填一个地址不方便带自定义 Header所以常见做法是把 token 拼在 URL 后面https://sip.example.com/lft.php?token你的随机串接收方看到的是 lft.php 返回的图片 URL这个 URL 不带 token因为它只在 SIP 消息里传递不需要再次鉴权。这也解释了为什么示例代码里 token 只保护上传、不保护下载——上传需要「谁可以写文件」的凭证下载依赖随机文件名本身不易猜。第二道防线是来源限制。如果上传和下载都来自固定的 SIP 服务器出口可以在 Nginx 里做location /lft.php { allow 203.0.113.10; deny all; include fastcgi_params; fastcgi_pass unix:/run/php/php8.2-fpm.sock; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; }203.0.113.10是示例出口 IP替换成你自己的。注意这个方案只适用于单一出口的封闭场景接收方在公网时deny all会把下载也挡掉所以更通用的做法是只限制 POSTGET 下载保持开放。第三道防线是叠加安全习惯如果同一台机器上还跑着别的 PHP 应用注意别把 php 伪协议、反序列化这类入口和 lft.php 放在同一个对外可达路径下避免被绕行利用。这条属于环境和代码隔离问题值得在每次上线前花十分钟理一遍。5. lft.php 避坑排查5 个会让人误以为代码写错的典型问题中转服务出问题时现象千奇百怪但大多数都发生在配置层不是 PHP 代码逻辑本身。下面这 5 个问题是我在实战里遇到频率最高的每个都按「现象 → 原因 → 解决」写清楚。5.1 图片发出去对方点开是 404现象Linphone 消息里能看到 URL但点击后 404浏览器直接打不开。原因代码里拼的 URL 前缀是/lft/Nginx alias 目录没对上或者文件压根没落在预期的磁盘路径下。alias 配置写错是重灾区alias /var/www/lft/lft_files/和alias /var/www/lft/lft_files差一个斜杠寻址可能完全错位。解决先用 curl 上传一次看返回 JSON 里的 url 字段再手动拼出地址访问。若 404查看 nginx error.log 里open()那行显示的实际文件路径对比代码里的$uploadDir是否一致。把 alias 路径改成与$uploadDir一致reload nginx。这个排查过程不需要动 PHP 代码十分钟内能定位。5.2 上传直接 413 Request Entity Too Large现象curl 传一个 1M 文件报 413换 500K 又能成功阈值卡得很明显。原因Nginx 的client_max_body_size默认只有 1m你只改了 php.ini没改 Nginx。同理如果在 Nginx 前面还有一层反向代理或 CDN那层的 body 限制也要同步调。解决在 server 块里加client_max_body_size 20m确认post_max_size不高于它reload nginx。注意 Nginx 的 413 和 PHP 的 413 在日志里长不一样Nginx 会直接返回 413 响应PHP 则会在业务日志里报UPLOAD_ERR_INI_SIZE先分清是哪一层拒绝的。5.3 PHP 返回 500日志提示 tmp 目录不可写现象上传小文件也报 500PHP 错误日志里出现Unable to move...或Permission denied。原因两个常见来源。一是upload_tmp_dir默认指向/tmp系统 /tmp 如果被 noexec 挂载或已满PHP 没法完成上传解析二是lft_files目录属主不是 PHP-FPM 运行用户move_uploaded_file写不进去。解决先ps aux | grep php-fpm确认运行用户然后chown -R把lft_files属主改对。如果是 noexec 或空间问题在 php.ini 里把upload_tmp_dir指到一个专用可写目录比如/var/www/lft/tmp提前创建并设好属主。检查顺序先看属主再看 tmp 目录这两个解决掉500 基本消失。5.4 收到的链接是 http在 https 页面里点不开现象对方收到 URL 显示http://...在浏览器里点开被安全策略拦截或被 HSTS 直接掐断。原因lft.php 里拼 URL 写死了http://而站点已经全站 https混合内容被浏览器拦。这个问题在 Web 客户端里表现尤其明显SIP 消息里看着没问题但浏览器层不允许。解决用请求上下文动态推导协议不要写死前缀。$scheme (!empty($_SERVER[HTTPS]) $_SERVER[HTTPS] ! off) ? https : http; $baseUrl $scheme . :// . ($_SERVER[HTTP_HOST] ?? localhost) . /lft/ . $filename;逻辑说明$_SERVER[HTTPS]在直连场景下能正确反映协议如果前面还有一层反向代理需要从X-Forwarded-Proto头取值同时注意清理该头里的逗号和空格防注入。这个改动很小但能根治大半「链接打不开」的反馈。5.5 上传接口裸奔在公网被脚本扫成上传点现象日志里出现大量陌生 IP 的 POST 请求磁盘上多出很多不是你用户传的文件上传接口被当成了免费网盘。原因token 没设或者 token 是弱口令allowedExt白名单没有收紧任何后缀都能落盘。公网扫描器会持续探测常见路径里的上传脚本lft.php 这种文件名很容易被字典扫到。解决第一把 3.2 里的 token 校验用起来强制查询参数或 Header 校验第二收紧后缀白名单到图片类型第三如果下载侧也要鉴权写一个独立的 download.php 做二次校验?php $dlToken 另一个不同的强随机串; $f $_GET[f] ?? ; if (!hash_equals($dlToken, ($_GET[t] ?? ))) { http_response_code(403); exit; } $p __DIR__ . /lft_files/ . basename($f); if (!is_file($p)) { http_response_code(404); exit; } header(Content-Type: . mime_content_type($p)); readfile($p);这个 download.php 的关键点是basename($f)它会把f参数里的目录部分剥掉防止../目录遍历。token 校验通过才 readfile杜绝未授权下载。代价是每次下载都会跑一次 PHP对聊天图片频率完全够用。配合 4.4 的来源限制公网上的恶意扫描基本能被挡在门外。6. 用两台真实 Linphone 客户端验证你的 lft.php 中转链路curl 通了不代表客户端链路真的通了因为 Linphone 发出的 SIP 消息、URL 携带方式、下载触发时机都有它自己的行为。最终验证要用两台真实客户端一台登录账号 A一台登录账号 BA 给 B 发一张图片然后去看服务端的日志链路。lft.php 里已经埋了一行error_log每次成功上传都会往 PHP 错误日志里写一条[lft] save... size... from...。下载走的是 Nginx 静态文件不进 PHP 日志所以要看 Nginx access log。两条日志串起来就是一次完整的中转过程tail -f /var/log/nginx/access.log tail -f /var/log/php8.2-fpm.log在 A 客户端发图后预期看到PHP 日志先出现一条 POST 保存记录接着 Nginx access log 出现一条对/lft/随机文件名的 GET 请求。两条记录成对出现并且时间间隔在几秒内说明发送端上传成功、接收端下载成功。如果只有 POST 没有 GET说明接收端没有触发下载可能是 SIP 消息里的 URL 字段识别问题如果 GET 有了但图片显示不出来回到第 5 章的 5.1 和 5.4 查路径和协议。我习惯在验证时额外做一件事用stat查看落盘文件的时间戳再和 Nginx access log 对比确认下载确实命中这个文件而不是走了某个缓存。曾经有一次我排查半天最后发现是客户端本地缓存了旧 URL跟服务端毫无关系。从那以后每次改完配置我都先 curl 跑通最小路径再用两台真机发图确认日志成对出现才放手。这个习惯帮我挡掉了好几次把 alias 路径写错的事故。希望帮到你。本文还有配套的精品资源点击获取