lft.php实战：Linphone消息图片中转部署与改造方案

简介这是一份针对Linphone开源VoIP应用图片消息中转需求的服务端PHP代码文件名为lft.php。官方版本依赖互联网中转在局域网或私有化部署中极不方便此代码重写了中转逻辑让开发者可在自有服务器上构建安全可控的图片消息通道。压缩包共1个文件格式为PHP整体大小约2KB轻量、易部署。已有293人学习/下载。实现要点包括接收图片时进行格式与大小校验防止异常数据通过GD或Imagick对图片转码压缩优化传输效率内置文件类型、文件名及路径安全防护同时适配MSRP与SIP协议的消息收发并支持身份验证、状态日志与性能参数调整。整体设计兼顾轻量性与可维护性配置灵活。既可作为内网Linphone消息中继模块也可作为PHP网络编程、图片处理和即时通信协议学习的实例参考。1. lft.php 到底是什么消息图片中转的职责边界很多人第一次接触 lft.php是在配 Linphone 的 SIP 服务器时发现消息里的图片发不出去或者对方收到一串奇怪的链接而不是预览图。其实 lft.php 就是 Linphone 生态里那个容易被忽略、却负责把消息里附带的图片“接住并转交”的 PHP 中转脚本。它的工作模式很直白Linphone 客户端把图片以 HTTP 上传到这个脚本脚本存下文件、生成一个带 token 的 URL再把这个 URL 回传给 SIP 信令层对方点开链接或自动预览时再由这个脚本把文件吐出去。整个过程相当于在 SIP 消息通道旁边加了一条 HTTP 文件通道而 lft.php 就是这条通道的看门人。这份资源适合两类人一类是把 Linphone 部署在自己服务器上、发现消息图片总翻车的人另一类是打算在自家 VoIP 系统里加“图片/文件中转”功能、想找一份能直接改的 PHP 参考实现的人。它不是一个完整的产品更像一个可拆解的零件。接下来我按“跑起来 → 看透它 → 改好它”的顺序拆最后把常见的坑一次性说清楚。2. 把 lft.php 跑起来环境准备与最小配置2.1 依赖检查PHP 扩展与目录权限lft.php 虽然看起来只有一百多行但它对运行环境有硬性要求。我一般建议先跑一遍 PHP 环境自检免得部署到一半才发现缺扩展。最少需要 PHP 7.0 以上因为里面用了random_bytes()这类函数如果还在用 PHP 5.6得先替换成openssl_random_pseudo_bytes()否则直接白屏。还需要确认下面几个扩展已经启用curl用于向外部存储转发、fileinfo用于识别上传文件的 MIME 类型、json用于解析 Linphone 客户端发来的 JSON 负载。在命令行先探一下底php -m | grep -E curl|fileinfo|json如果输出里缺少curl或fileinfo在 Debian/Ubuntu 上执行sudo apt install php-curl php-fileinfo sudo systemctl restart php8.2-fpm参数说明php -m列出所有已编译/已加载的模块grep过滤出我们关心的三个名字。php-curl和php-fileinfo是 PHP 的扩展包名不同发行版可能写作php8.1-curl根据实际 PHP 版本调整。重启 FPM 是因为 PHP 扩展是在进程启动时加载的不重启不生效。目录权限是个容易被忽略的坑。lft.php 默认会把上传的图片写入一个files/目录这个目录必须允许 PHP 进程写。我通常把它放在 web 根目录之外然后通过软链接或单独的静态路由暴露访问避免直接让 PHP 脚本目录对外可写。mkdir -p /var/lib/linphone-file-transfer chown www-data:www-data /var/lib/linphone-file-transfer chmod 750 /var/lib/linphone-file-transfer这里把目录所有者设为 Web 服务器运行用户www-data权限 750 表示 owner 可读写执行group 可读执行其他人无权。如果用了别的用户跑 PHP-FPM需要改成对应的用户名。2.2 部署 lft.php 到 Nginx/Apache我这边常用 Nginx PHP-FPM建议用fastcgi方式跑。先放一份最小 Nginx 配置server { listen 80; server_name sip.example.com; root /var/www/lft; index index.php; location /lft.php { include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_pass unix:/run/php/php8.2-fpm.sock; } location ~ ^/files/ { alias /var/lib/linphone-file-transfer/; expires 7d; add_header Content-Type image/jpeg always; } }逻辑说明location /lft.php把所有指向该脚本的请求交给 PHP-FPM 处理SCRIPT_FILENAME告诉 FPM 实际执行的脚本路径。location ~ ^/files/用来处理之前提到的独立存储目录alias把 URL 路径映射到实际目录expires 7d给图片加缓存头减少重复请求。如果你是 Apache 环境改用mod_php或php-fpm的ProxyPassMatch也行核心是让.php能被执行同时files/目录不做 PHP 解析。部署完先别急着接入业务直接用手工方式测试脚本是否存活curl -X POST http://sip.example.com/lft.php -F filetest.jpg -F from1001预期返回一个 JSON里面带url字段。如果返回 500看 PHP 错误日志大部分原因是目录权限或扩展缺失。这条命令里-F表示以表单方式上传文件test.jpg是本地要上传的文件from参数模拟 SIP 中的用户标识。2.3 配置 Flexisip/Linphone 服务端指向 lft.phpLinphone 自带的 SIP 服务端 Flexisip 通过file_transfer_url参数告诉客户端往哪里发图片。打开flexisip.conf找到消息相关的段落[module::Chat] enabledtrue file_transfer_urlhttp://sip.example.com/lft.php file_transfer_dir/var/lib/linphone-file-transfer file_transfer_http_paramsmax_size10485760参数说明file_transfer_url是客户端上传图片的目标地址必须能公网访问file_transfer_dir是服务端保存文件的目录这里填的路径要和 lft.php 里实际写入的目录一致max_size限制单张图片最大 10MB超过会直接拒绝。改完配置后重启 Flexisipsudo systemctl restart flexisip到这一步消息图片中转的最小闭环就通了Linphone 客户端发图 → SIP 信令中携带上传凭证 → 客户端把文件 POST 到 lft.php → 返回 URL → 对方收到后通过 URL 取图。但如果只是这样跑通你并不知道中间到底发生了什么下一章拆开看代码逻辑和关键字段。3. 消息图片流转机制从 SIP 信令到 HTTP 上传3.1 信令路径分析图片在 Linphone 里不是直接塞进 SIP 消息体的。SIP 消息体里放的是 MIME 格式的file-transfer描述包含文件名、大小、以及一个临时的上传 URL。Linphone 客户端拿到这个 URL 后才会真正发起 HTTP PUT 或 POST 请求。这里有个反直觉的设计SIP 通道只负责“通知对方我要发图”真正的图片数据全走 HTTP。lft.php 在这种设计里扮演的角色是临时接收端。它需要处理两类请求一类是客户端上传图片通常 POST multipart 或 PUT另一类是对方取图GET 请求 token。区分方式很简单看请求方法和 URL 参数。我拆过的这份代码里入口流程大致是这样的?php $method $_SERVER[REQUEST_METHOD]; if ($method POST || $method PUT) { // 处理上传保存文件并生成URL handle_upload(); } elseif ($method GET) { // 校验token输出文件 handle_download(); } else { http_response_code(405); echo json_encode([error method not allowed]); }逻辑说明$_SERVER[REQUEST_METHOD]取出 HTTP 方法根据方法分流到上传和下载两个处理函数。405 是告诉请求方不支持的 HTTP 方法。这段代码虽然简单但它是整个中转服务的骨架。3.2 lft.php 与文件存储映射上传处理的核心是“把上传的临时文件挪到正式目录然后生成唯一的访问链接”。代码里通常分三步校验请求是否包含文件、生成随机文件名、保存并构造 URL。关键实现如下function handle_upload() { $dir /var/lib/linphone-file-transfer/; if (!file_exists($dir)) { mkdir($dir, 0750, true); } $token bin2hex(random_bytes(16)); $ext pathinfo($_FILES[file][name], PATHINFO_EXTENSION); $filename $token . . . $ext; $dest $dir . $filename; if (!move_uploaded_file($_FILES[file][tmp_name], $dest)) { http_response_code(500); echo json_encode([error move failed]); return; } $base http:// . $_SERVER[HTTP_HOST]; echo json_encode([ url $base . /files/ . $filename, token $token ]); }逻辑说明random_bytes(16)生成 128 位随机数的二进制串bin2hex转成 32 位十六进制字符串这样可以避免文件名猜测攻击。pathinfo取得上传文件名的扩展名但这里有个安全风险扩展名来自客户端不能完全信任后面避坑章节会单独说。move_uploaded_file是 PHP 处理上传文件的安全移动方式只有真正通过 HTTP POST 上传的临时文件才能成功移动这是为了防止把系统文件移到 web 目录。参数说明$_FILES[file]中的file是表单字段名如果 Linphone 那边用不同的字段名比如File-Transfer这里要对应改。HTTP_HOST取自请求的 Host 头如果你有反向代理这可能是内网地址所以生产环境更推荐直接在配置里写死一个外网基础 URL避免生成的链接打不开。3.3 参数调优超时、大小限制、并发中转服务最大的翻车点不是代码逻辑而是 Web 服务器的超时和上传大小限制。lft.php 本身不限制体积但 Nginx 默认只允许 1MB 请求体PHP 默认upload_max_filesize是 2MB往往图片超过这个数就收到 413 或 500。我一般会在 Nginx 的 server 块里单独放开client_max_body_size 20m;同时确保 PHP 配置对齐; php.ini upload_max_filesize 20M post_max_size 22M max_execution_time 30参数说明client_max_body_size控制 Nginx 允许的最大请求体20M 够日常图片使用post_max_size必须比upload_max_filesize大因为 POST 请求里除了文件还有表单字段和 multipart 边界留 2M 余量合理。max_execution_time设 30 秒防止大文件上传时 PHP 进程被卡死。并发方面如果同一个 Flexisip 实例下有多个用户同时传图lft.php 是单进程执行的瓶颈在 PHP-FPM 的pm.max_children。我建议至少设置成 CPU 核心数的 2 倍否则高峰期会排大队。在php-fpm.d/www.conf里改pm.max_children 8 pm.start_servers 4 pm.min_spare_servers 2 pm.max_spare_servers 6这个配置让 FPM 一开始有 4 个空闲进程最低保持 2 个最高 6 个同时最多 8 个进程处理请求。如果图片很多可以把max_children提到 16但要注意内存开销每个 PHP-FPM 进程大概会占 30-50MB。4. 避坑与常见问题排查5 条血泪经验4.1 上传成功但下载 404现象客户端显示图片已发送但对方点开链接提示 404。原因lft.php 生成的 URL 路径是/files/而 Nginx 配置里location ~ ^/files/的 alias 路径和 PHP 写入的目录不一致。最常见是我把文件写到了/var/www/lft/files/但 Nginx alias 指到了/var/lib/linphone-file-transfer/两边对不上。解决统一路径。最让我省心的做法是直接在 PHP 里用__DIR__ . /files作为存储目录然后 Nginx 配置alias指向同一物理路径并确认目录存在且有读权限ls -ld /var/www/lft/files4.2 图片能被下载但 Content-Type 不对现象浏览器打开图片直接变成下载而不是预览或者后缀是.jpg但服务器返回application/octet-stream。原因没有根据文件扩展名或 MIME 类型返回正确的响应头浏览器只能按二进制流处理。解决在下载分支里加上 MIME 判断不要信任扩展名用 PHP 的finfo扩展识别真实类型$finfo finfo_open(FILEINFO_MIME_TYPE); $type finfo_file($finfo, $path); header(Content-Type: . $type); header(Content-Length: . filesize($path)); readfile($path);finfo_file会读取文件的真实内容并返回 MIME 类型比如image/jpeg、image/png。注意Content-Length要放在输出文件之前否则分块传输时浏览器可能不知道文件大小。4.3 上传时收到 413 Request Entity Too Large现象小图片正常大一点的图片直接 413PHP 错误日志里看不到任何记录。原因请求还没到 PHP 就被 Nginx 拦下了因为没设置client_max_body_size默认只有 1MB。这个错不在 lft.php你甚至看不到 PHP 报错。解决在server块加client_max_body_size 20m;并确认 PHP 的upload_max_filesize和post_max_size都同步改大。改完记得nginx -t检查配置然后 reloadsudo nginx -t sudo systemctl reload nginx4.4 文件名扩展名伪造导致的安全告警现象有安全工具扫描时提示 lft.php 存在任意文件上传风险有人上传.php后缀的文件如果存储目录恰好能执行 PHP就成了 webshell。原因上传时直接用了客户端提供的原始文件名作为扩展名掉进了pathinfo($_FILES[file][name], PATHINFO_EXTENSION)的坑。攻击者可以传一个shell.php的文件名代码会把它存成token.php如果/files/被 Web 服务器当作 PHP 解析就直接 getshell。解决弃用客户端扩展名改为根据 MIME 类型映射白名单。常见做法是$allowed_types [ image/jpeg jpg, image/png png, image/gif gif, image/webp webp ]; $finfo finfo_open(FILEINFO_MIME_TYPE); $mime finfo_file($finfo, $_FILES[file][tmp_name]); if (!isset($allowed_types[$mime])) { http_response_code(415); exit(json_encode([error unsupported type])); } $ext $allowed_types[$mime]; $filename bin2hex(random_bytes(16)) . . . $ext;finfo读取的是临时文件的真实内容不看扩展名所以伪造后缀很容易被识破。同时确保/files/在 Nginx 里不解析 PHP前面给过的location ~ ^/files/里不要写fastcgi_pass这样即使传了个文件也只会被当静态资源返回。4.5 客户端上传超时导致图片发送失败现象Linphone 客户端显示“上传超时”但服务器日志里有 POST 记录文件也存下来了。原因SIP 消息里约定的临时 URL 有效期太短或者 HTTP 响应太慢客户端在拿到上传结果前就断开了。Flexisip 默认的临时 URL 有效期我遇到过 30 秒的大图片在弱网下根本传不完。解决在 Flexisip 配置里调大file_transfer_url对应的有效期参数同时 PHP 端把max_execution_time提高到 60 以上并在上传成功后立即输出结果不要在响应里做额外耗时的缩略图生成缩略图放到异步任务里。我常用的值是file_transfer_http_paramsmax_size10485760;timeout120注意timeout参数有些 Flexisip 版本写作url_timeout具体看版本。如果找不到对应配置退一步在 lft.php 里保证上传分支的前 30 行内就开始move_uploaded_file避免在外面绕圈子。5. 进阶把 lft.php 改造成自己的消息中转服务5.1 给上传接口加 token 鉴权默认 lft.php 谁都能调如果你只在可信内网用还无所谓一旦服务暴露到公网会被恶意刷流量。我习惯加一层简单的 token 校验客户端上传时在请求头里带X-Auth-Token服务端这边提前生成一个随机 token 放到配置里。改动很小$cfg_token d41d8cd98f00b204e9800998ecf8427e; if (!isset($_SERVER[HTTP_X_AUTH_TOKEN]) || $_SERVER[HTTP_X_AUTH_TOKEN] ! $cfg_token) { http_response_code(401); echo json_encode([error unauthorized]); exit; }逻辑说明HTTP_X_AUTH_TOKEN是 PHP 把请求头X-Auth-Token转成$_SERVER变量时的命名规则头里的横线变下划线、字母转大写。这个 token 只是个演示生产环境建议用 HMAC 签名或者临时一次性 token避免在客户端里藏一份静态密钥。5.2 生成缩略图减轻移动端流量压力Linphone 客户端拿到原始大图后如果还要自动下载流量开销不小。可以在上传完成后异步生成一个缩略图额外返回一个thumb_url。PHP 里用 GD 库就能做不用引入太重的东西function make_thumb($src, $dest, $max_w 320, $max_h 320) { list($w, $h, $type) getimagesize($src); if ($type ! IMAGETYPE_JPEG $type ! IMAGETYPE_PNG) { return false; } $scale min($max_w / $w, $max_h / $h, 1); $nw (int)($w * $scale); $nh (int)($h * $scale); $src_img ($type IMAGETYPE_JPEG) ? imagecreatefromjpeg($src) : imagecreatefrompng($src); $dst_img imagecreatetruecolor($nw, $nh); imagecopyresampled($dst_img, $src_img, 0, 0, 0, 0, $nw, $nh, $w, $h); if ($type IMAGETYPE_JPEG) { imagejpeg($dst_img, $dest, 85); } else { imagepng($dst_img, $dest, 6); } imagedestroy($src_img); imagedestroy($dst_img); return true; }参数说明getimagesize拿到原图宽高和类型$scale是缩放比例取目标尺寸和原尺寸比例的最小值再用min(..., 1)避免把小图放大。imagecopyresampled生成高质量缩放图imagejpeg的第三个参数 85 是 JPEG 质量0-100 越大质量越高但文件也越大PNG 的 0-9 越小压缩越快、文件越大这里用 6 平衡。生成完缩略图把缩略图路径也拼进 URL 返回$thumb_url $base . /files/ . $thumbname; echo json_encode([ url $base . /files/ . $filename, thumb_url $thumb_url ]);5.3 把文件记录写进 SQLite方便后续管理当你手里积累了几万张图片没有一个索引管理起来很麻烦。最轻量的方式是用 SQLite不需要单独起 MySQLPHP 内置的 PDO 就支持。在 lft.php 的上传分支里加几行$db new PDO(sqlite:/var/lib/linphone-file-transfer/transfer.db); $db-exec(CREATE TABLE IF NOT EXISTS transfers ( id INTEGER PRIMARY KEY AUTOINCREMENT, token TEXT NOT NULL UNIQUE, filename TEXT NOT NULL, from_sip TEXT, created_at INTEGER NOT NULL )); $stmt $db-prepare(INSERT INTO transfers (token, filename, from_sip, created_at) VALUES (?, ?, ?, ?)); $stmt-execute([$token, $filename, $_POST[from] ?? null, time()]);逻辑说明CREATE TABLE IF NOT EXISTS保证脚本第一次运行时自动建表不需要手动初始化。token字段唯一能防止随机数碰撞如果重复就抛异常。from_sip存的是上传者标识从 POST 字段里取但别直接信任最好由 SIP 服务器传给 lft.php 时放在请求头里避免伪造。有了这张表你可以随时统计上传记录、清理过期文件甚至写一个管理后台列出所有中转过的图片。注意 SQLite 数据库文件本身也要限制为 PHP 进程可写别放在 public 目录下。5.4 验证整个链路是否正常改动完别急着上线我一般会写一个小脚本模拟 Linphone 收图的全过程先调 Flexisip 拿临时上传 URL然后 PUT 图片到 lft.php最后 GET 取回来比对内容是否一致。这里提供一个简化版的端到端测试# 1. 模拟客户端上传 RESP$(curl -s -X POST http://sip.example.com/lft.php \ -H X-Auth-Token: d41d8cd98f00b204e9800998ecf8427e \ -F file/tmp/test-photo.jpg \ -F from1001) # 2. 用python/jq取出url URL$(echo $RESP | jq -r .url) # 3. 下载并比对md5 curl -s $URL -o /tmp/downloaded.jpg md5sum /tmp/test-photo.jpg /tmp/downloaded.jpg如果两个 md5 值一样说明上传、存储、下载整个链路没问题。如果缩略图也做了再用jq -r .thumb_url取缩略图地址单独看一眼大小和尺寸是否符合预期。从那以后我每次部署 lft.php 或者改完代码都会强制走一遍这个测试流程。尤其是改完鉴权逻辑最容易出现“上传接口被锁死但自己没察觉”的尴尬。很多事故其实就出在某个响应头、某个目录权限或者某个被遗忘的max_size参数上。把这 5 条避开lft.php 作为 Linphone 消息图片中转服务才算真正能扛事。希望这份拆解能帮你在自己的环境里少走一轮弯路。本文还有配套的精品资源点击获取