Yii2文库系统源码部署：转码、Sphinx检索与支付回调全链路

简介知沃文库系统是一套基于 Yii2 框架开发的 PHP 文库建站程序面向希望自建文档分享与付费下载平台的站长及中小型技术团队。它借鉴百度文库、原创力等平台的产品思路解决文档存储、格式转换与管理问题并覆盖从内容发布到流量变现的运营链路。压缩包内为 1 个 PDF 文件体积约 7.54MB即系统部署与配置手册内容涵盖阿里云 ECS 安全组开放端口、PC 站与手机站和接口站的域名解析、对象存储与短信、微信支付、支付宝设置以及第三方登录、公众号对接、导航与栏目层级、用户等级、Banner 管理和文档发布、Sphinx 全文检索启用、定时转码任务等模块可视为一份从服务器初始化到运营功能上线的落地清单。已有 334 人浏览学习。资源正文侧重文档转换后以 H5 或图片形式保持文字放大无失真配合毫秒级检索与分销、商城、资讯等辅助工具帮助读者理清文库网站的搭建顺序减少重复排错。1. 文库系统源码拿到手第一件事不是上传刚拿到一套文库系统源码的时候多数人会先传上去点两下看到首页能开就觉得成了。真正运营过文档站的人知道文库站的重活全在后台一篇 30 页的 PPT 要在几秒内变成能翻页的 H5十几万份文档要能被一个字命中付费下载的回调丢一次就是一次客诉。这套基于 Yii2 的文库系统源码把文档管理系统该有的东西基本铺齐了——多格式转码预览、Sphinx 全文检索、付费下载、公众号与小程序入口、对象存储和短信配置。它适合的是想直接跑起一个文库网站系统、把精力放在内容和运营上的人而不是想从零写一遍转码引擎的人。下面按我实际部署的顺序拆先把三套域名的骨架搭稳再处理转码、检索、支付的链路最后把上线后最容易翻车的地方挨个说清。2. 三站同源部署www、m、api 的目录、伪静态与安全组这套文库网站系统最容易被误解的一点是「三个站」。控制台里要解析 www、m、api 三个子域很多人第一反应是装三份代码结果升级一次改三处数据还串不起来。实际结构是一份代码、三个入口三套域名都指向同一个项目根目录靠域名和路由规则决定加载哪套模板、返回 HTML 还是 JSON。2.1 为什么是三个子域而不是一个PC 站和手机站分开核心原因是模板体系不同。PC 端的文档详情页有侧边栏、相关推荐、目录树手机端是单列流式布局加悬浮下载条两套模板的 DOM 结构差得远用同一套响应式硬扛会让首屏体积翻倍移动端体验和 SEO 都吃亏。分开之后m 站可以单独做移动端适配的 meta 和结构化数据PC 站保持原有的收录权重互不干扰。api 站独立出来则是给小程序和公众号用的。小程序要求请求域名在后台白名单里备案且必须 HTTPS你把接口挂在 www 下面等于把整站域名都暴露给小程序配置后期换域名、加证书、做灰度都麻烦。单独一个 api 子域只吐 JSON关掉静态缓存日志单独切分排查接口问题的时候一眼就能定位。提示三个子域必须都做 HTTPS。支付回调、小程序请求、公众号网页授权都强制要求证书且证书链要完整缺中间证书在部分安卓机上会直接握手失败。2.2 建站三件套根目录、运行目录、伪静态我用的是常见的 LNMP 面板工具路径和命令跟其他面板大同小异。建站时有三处必须对齐错一处就是 404 或者 500。第一网站根目录填项目下的 public不是项目根目录。Yii2 的入口文件、静态资源、上传目录都在 public 里你把根目录指到项目外层等于把 config、runtime、vendor 全暴露在 Web 下这是安全事故。第二运行目录同样指到 public。有些面板建站时根目录和运行目录是两个独立字段只改一个不生效表现为首页能开但 CSS/JS 全 404。第三伪静态要写 Yii2 的单入口规则不能套用其他框架的模板。下面是 PC 站的完整配置m 站与 api 站只需改server_name其余保持一致server { listen 80; server_name www.example-doc.test; # 根目录必须落到 public不是项目根 root /www/wwwroot/wenku/public; index index.php; # Yii2 单入口路径不存在就交给 index.php 路由 location / { try_files $uri $uri/ /index.php?$args; } # 静态资源直接落盘别让 PHP 兜底否则文档页首屏会明显变慢 location ~* \.(css|js|jpg|png|gif|woff2|svg)$ { expires 7d; access_log off; } location ~ \.php$ { fastcgi_pass unix:/tmp/php-cgi-74.sock; fastcgi_index index.php; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; # 大文件下载和转码回调可能超过默认 60s这里放宽到 300s fastcgi_read_timeout 300; } # 上传目录禁止执行 PHP防止伪装图片的木马 location ~* ^/uploads/.*\.(php|php5)$ { deny all; } }try_files的三个参数顺序不能乱先找真实文件再找目录最后才回落给index.php?$args。把$args丢掉会导致分页参数、搜索关键词全部失效翻到第二页就回到首页。fastcgi_read_timeout设 300 秒是因为部分大体积 PDF 在上传完成后会同步触发一次封面生成默认 60 秒容易在弱网环境下断掉。uploads目录禁执行那条是血泪经验文库站允许用户上传这个口子不堵早晚出事。2.3 安全组只开该开的端口云服务器的安全组是第二道门禁。我见过有人图省事直接放行全部端口结果 MySQL 和 Redis 被扫数据被清。这套系统的端口清单很固定端口用途是否对公网说明80 / 443Web 入口是三个子域共用22SSH 运维谨慎建议限制来源 IP 段3306MySQL否只允许本机或内网6379Redis否队列、缓存、会话9312Sphinx 检索服务否只给本机 PHP 连9306SphinxQL 调试口否排障时临时开9312 这个端口最容易被忽略。Sphinx 的 searchd 默认监听 9312PHP 通过 extension 直连如果 searchd 起在本机而防火墙拦截了回环表现为「后台显示索引已建好前台搜索永远是空」。排障时先telnet 127.0.0.1 9312确认通不通再去看索引。2.4 安装收尾目录权限与初始化代码传完、站点建好接下来是权限和初始化。runtime 和上传目录必须可写但权限给到 777 是偷懒正确做法是属主给 Web 运行用户目录 755、文件 644只对 runtime 和 uploads 单独放行cd /www/wwwroot/wenku # 属主交给 Web 用户不同面板用户名不同先确认再改 chown -R www:www /www/wwwroot/wenku # 代码目录收紧防止被篡改 find . -type d -exec chmod 755 {} \; find . -type f -exec chmod 644 {} \; # 只给运行时和上传目录写权限 chmod -R 775 runtime public/uploads public/storage # 初始化数据库表结构Yii2 的迁移命令执行前先改好数据库配置 php yii migrate --interactive0migrate跑之前一定先改数据库连接配置包含库名、账号、密码、字符集。字符集必须是utf8mb4用utf8存文档标题里的生僻字和 emoji 会截断导入一批数据之后才发现乱码回滚代价很大。跑完迁移顺手清一次缓存php yii cache/flush-all否则后台可能还读着安装前的旧配置。3. 转码流水线十三种格式怎么落到 H5 与图片文库系统的核心竞争力就在这一层。用户上传一个 docx你不可能让他下载下来用 Word 打开——文库站的浏览体验是「点开就能看、能翻页、能选中文字」。这套系统支持 doc、docx、ppt、pptx、pdf、txt、zip、mp3、mp4、jpg、png、bmp、gif 十三类其中前六类走转码后七类基本是直出或抽帧。做得对不对直接决定用户第一眼的观感。3.1 转码为什么必须异步新手最容易犯的错是在上传接口里同步转码文件落盘立刻调转码命令转完再返回成功。一篇 40 页的 PPT 在普通 2 核机器上要 20 到 40 秒接口直接超时用户看到的是「上传失败」实际上文件已经传上去了重复点几次产生一堆脏数据。正确链路是上传只做三件事——校验格式和大小、落原始文件、写一条status待转码的记录立刻返回。转码由独立的 CLI 进程消费PC 端和手机站只负责按状态轮询或展示「转码中」。这样上传接口的响应时间能压到几百毫秒转码失败也不影响原始文件可以重试。3.2 两段式转码LibreOffice 转 PDF再拆页转图Office 系列格式没法直接变网页行业通用做法是先用 LibreOffice 的无头模式统一转成 PDF再用渲染工具把 PDF 拆成逐页图片前端用图片模式翻页。文字型 PDF 还能额外抽一层文本层做检索补充。下面是我实际在用的 CLI 命令核心段?php // 单篇文档转码源文件 - PDF - 逐页 PNG // $docId 由队列消费端传入一次只处理一篇失败可单独重试 $doc Doc::findOne($docId); $src Yii::getAlias(storage) . /origin/ . $doc-file_path; $tmp sys_get_temp_dir() . /conv_ . $doc-id; mkdir($tmp, 0775, true); // 第一段无头模式转 PDF // --headless 必须加否则在无桌面的服务器上直接报错 // --norestore 防止上次异常退出后卡在恢复流程 $cmd1 sprintf( soffice --headless --invisible --norestore --convert-to pdf --outdir %s %s 21, escapeshellarg($tmp), escapeshellarg($src) ); exec($cmd1, $out1, $code1); $pdf $tmp . / . pathinfo($src, PATHINFO_FILENAME) . .pdf; if ($code1 ! 0 || !file_exists($pdf)) { // 失败原因原样落库别只记一个 failed后面没法排查 $doc-status Doc::STATUS_FAILED; $doc-fail_reason pdf_convert: . implode(|, $out1); $doc-save(false); return false; } // 第二段拆页转图150dpi 是清晰度和体积的平衡点 // 低于 120 放大后文字发虚高于 200 单页体积翻倍CDN 成本压不住 $cmd2 sprintf( pdftoppm -r 150 -png %s %s/page, escapeshellarg($pdf), escapeshellarg($tmp) ); exec($cmd2, $out2, $code2); // 逐页上传对象存储本地只保留缩略图避免磁盘被撑爆 foreach (glob($tmp . /page-*.png) as $pageFile) { $key doc/ . $doc-id . / . basename($pageFile); Oss::upload($key, $pageFile); $pages[] $key; unlink($pageFile); } $doc-page_count count($pages); $doc-page_list json_encode($pages); $doc-status Doc::STATUS_DONE; $doc-save(false);几个参数值得单独说。--convert-to pdf后面不加参数时 LibreOffice 会用默认的 PDF 导出设置字体嵌入不全中文文档经常出现方框字解决办法是服务器上装齐常用中文字体并在转换前把字体目录写进~/.config/libreoffice的配置里。-r 150的分辨率不是随便定的A4 幅面在 150dpi 下单页 PNG 大约 200KB 到 400KB40 页的文档差不多 10MB用户翻页时按需加载完全扛得住。page_list存 JSON 而不是再建一张附表是为了详情页一次查询就能拿到全部页地址少一次联表。3.3 定时任务怎么挂转码进程不能常驻吃内存我一般用 crontab 定时拉起处理固定条数后自动退出# 每 2 分钟拉起一次转码 worker一次最多 20 篇处理完自动退出 # 这样即使某篇文档把进程搞崩也不会影响下一批 */2 * * * * cd /www/wwwroot/wenku php yii doc/convert --limit20 /var/log/wenku/convert.log 21 # 每天凌晨 3 点合并增量索引具体在下一章展开 0 3 * * * indexer --config /etc/sphinx/wenku.conf --merge main delta --rotate /var/log/wenku/sphinx.log 21 # 每小时清理超过 24 小时的临时转码目录 0 * * * * find /tmp -maxdepth 1 -name conv_* -mmin 1440 -exec rm -rf {} \;cd到项目根再执行是必须的Yii2 的 console 入口依赖相对路径找配置直接写绝对路径调yii会报找不到 bootstrap。日志一定要重定向不重定向的话 crontab 执行失败会发系统邮件有些机器没配邮件服务报错直接丢了你以为任务在跑其实早就挂了。3.4 各格式的处理策略不是所有格式都走同一条路按类型分流能省不少资源格式处理方式说明doc / docxLibreOffice 转 PDF 后拆图保留排版最稳ppt / pptx同上逐页对应幻灯片动画丢失静态图可接受pdf直接拆图不经过 LibreOffice少一道转换速度快一倍txt直接读文本按行分页不产生图片体积最小mp3 / mp4不转码只抽封面和时长播放交给前端标签jpg / png / bmp / gif原图直出压缩后入对象存储gif 保留动图zip不解压只列文件清单解压有安全风险zip 这条要特别强调。有团队为了「预览压缩包内容」在服务端自动解压结果被塞了软链接和超大文件磁盘瞬间打满。这套系统的做法是只读中央目录列清单不解压安全边界清楚得多。4. 检索与变现Sphinx 索引配置与付费链路的权限联动文档站到了一定量级数据库LIKE %关键词%就彻底失效了——十万篇文档翻一遍要好几秒还吃满 CPU。这套系统用 Sphinx 做全文检索配合条件组合筛选响应能压到毫秒级。检索做不好用户搜两次搜不到就走了支付链路做不好用户付了钱下不了文档是直接的口碑事故。这两块本质上都是「状态一致性」问题放在一起说。4.1 主索引与增量索引的分工Sphinx 的索引是静态文件重建一次要扫全表。文档站每天都在新增内容不可能每小时全量重建。标准解法是拆成主索引和增量索引主索引存历史数据增量索引只存上次重建之后的新记录定时把增量合并进主索引。# 主索引数据源只索引已审核通过、状态正常的文档 source main_src { type mysql sql_host 127.0.0.1 sql_user wenku_ro sql_pass 只读账号密码别用 root sql_db wenku sql_port 3306 sql_query_pre SET NAMES utf8mb4 sql_query SELECT id, title, description, tags, cate_id \ FROM doc WHERE status 1 AND id (SELECT max_doc_id FROM sphinx_meta) # 参与筛选的字段必须声明为属性否则 WHERE 里用不了 sql_attr_uint cate_id sql_field_string tags } index main { source main_src path /var/lib/sphinx/main min_word_len 1 # 中文必须开 ngram否则整句被当成一个词搜「文档管理」匹配不到「文档管理系统」 ngram_len 1 ngram_chars U4E00..U9FFF charset_table 0..9, A..Z-a..z, a..z, U4E00..U9FFF }sql_query_pre里的SET NAMES utf8mb4不能省Sphinx 连 MySQL 时默认字符集可能不是 utf8mb4中文标题进索引会变成问号。ngram_len 1配合ngram_chars覆盖 CJK 区间是把中文按单字切分建立倒排代价是索引体积变大但换来的是任意两字组合都能命中文库站这种搜索场景必须这么配。cate_id声明成sql_attr_uint是为了支持「按栏目筛选」不声明的话只能在全文里搜组合检索做不了。增量索引继承主索引的配置只改查询条件source delta_src : main_src { # 只捞主索引之后的新增记录max_doc_id 由合并脚本回写 sql_query SELECT id, title, description, tags, cate_id \ FROM doc WHERE status 1 AND id (SELECT max_doc_id FROM sphinx_meta) }4.2 建索引与常驻服务索引建好之后 searchd 要常驻PHP 侧才能连上。常用命令就三条# 全量重建主索引--rotate 保证 searchd 不停机切换 indexer --config /etc/sphinx/wenku.conf --all --rotate # 单独更新增量索引频率可以高一些比如每 5 分钟 indexer --config /etc/sphinx/wenku.conf delta --rotate # 确认 searchd 在跑输出里能看到监听的 9312 端口 searchd --config /etc/sphinx/wenku.conf --status--rotate的原理是新索引写到.new后缀的文件建完后给 searchd 发信号让它切换旧索引保留到下次重建。不加这个参数必须先停服务站内搜索会中断几十秒用户感知明显。还有一个坑合并主索引和增量索引时用的是--merge main delta --rotate顺序不能反反了会把主索引的数据覆盖掉只能全量重建几十万文档要跑很久。4.3 付费下载回调里必须做幂等文库站的变现路径是「文档付费下载」链路是下单、拉起支付、渠道回调、改单加权限。这条链路上唯一不能出错的是回调处理因为支付渠道会重复推送网络抖动、你返回慢了、服务重启都可能触发重推。// 支付回调入口验签、幂等、事务内改单三件事缺一不可 public function actionNotify() { $raw Yii::$app-request-getRawBody(); if (!$this-verifySign($raw)) { // 验签失败直接拒别往下走 return $this-asJson([code FAIL, message sign error]); } $data json_decode($raw, true); $order Order::find()-where([out_trade_no $data[out_trade_no]])-one(); // 幂等的关键已支付的单直接回成功不重复加下载次数 if (!$order || $order-status Order::STATUS_PAID) { return $this-asJson([code SUCCESS]); } $tx Yii::$app-db-beginTransaction(); try { $order-status Order::STATUS_PAID; $order-paid_at time(); $order-save(false); // 用户等级对应每日下载配额扣减要和订单在同一个事务里 UserLevel::consumeQuota($order-user_id, $order-doc_id); $tx-commit(); } catch (\Throwable $e) { $tx-rollBack(); Yii::error(pay_notify: . $e-getMessage(), pay); // 返回失败让渠道重推别吞异常 return $this-asJson([code FAIL]); } return $this-asJson([code SUCCESS]); }verifySign用的是渠道给的密钥密钥必须放在环境变量里不能写进代码仓库。幂等判断放在事务外面是因为重复推送的量可能很大先进事务会白白占用连接。consumeQuota里对用户等级那一行要加SELECT ... FOR UPDATE否则同一用户并发下两单配额会被扣成负数这种账对不上后面很难查。4.4 配置项的先后顺序后台配置项很多顺序错了会互相卡。我一般按这个次序来先配对象存储再配短信接着第三方登录然后支付最后公众号和小程序。理由是对象存储是所有上传下载的基础短信和第三方登录依赖回调域名已经能通支付依赖订单表和回调地址公众号和小程序的网页授权又依赖支付和用户体系。公众号这块还要注意网页授权的回调域名只能填一个且必须已经备案PC 站和 m 站如果都要授权得走同一个 api 子域统一中转别在两边各配一套。5. 常见问题排查上线后最常翻车的五个点这一节是我自己踩过、也帮别人定位过的现场记录。文库系统这类产品出问题的地方高度集中按「现象 → 原因 → 解决」记下来下次遇到能省半天。5.1 手机站打开白屏PC 站正常现象www 访问一切正常m 子域返回 200 但页面空白控制台报一堆静态资源 404。原因建 m 站时根目录填对了但运行目录没改或者伪静态漏配。面板里根目录和运行目录是两个字段只改一个PHP 能执行但静态资源路径拼错模板加载到一半就断了。还有一种情况是 m 站的server_name写成了带 www 的形式域名解析和配置对不上。解决对比三个站点的 nginx 配置文件root必须都指向publictry_files那一行必须存在且参数一致。改完nginx -t检查语法再 reload别直接重启语法错误会导致整台机器上所有站点全挂。5.2 转码任务一直排队状态永远停在「转码中」现象后台上传成功列表里状态一直是待转码日志里没有任何转码记录。原因九成是 PHP CLI 的exec被禁用。面板默认的disable_functions里常带exec、shell_exec、proc_openWeb 模式下的限制和 CLI 模式共用同一个 php.iniCLI 跑起来直接报函数不可用而错误被 cron 的日志重定向吞掉了。少数情况是 LibreOffice 没装或装了但找不到soffice命令。解决先php -i | grep disable_functions确认把exec从禁用列表里去掉只对 CLI 生效更稳妥。再which soffice确认路径找不到就建软链到/usr/bin/soffice。改完手动跑一次php yii doc/convert --limit1能出结果再交给 cron。5.3 搜索永远是空结果但数据库里明明有数据现象前台搜索任意关键词都返回 0 条后台索引管理页显示索引已建。原因三种可能。searchd 没起来或端口不通索引建的时候status条件把数据全过滤了中文分词配置缺失整句被当成一个词。最常见的是第二种文档审核状态字段的枚举值和索引 SQL 里写的不一致索引扫了一遍一条没进。解决先searchd --status看服务再telnet 127.0.0.1 9312看端口然后用 SphinxQL 直连查SELECT COUNT(*) FROM main;确认索引里到底有多少条。条数为 0 就回去改sql_query的过滤条件改完indexer --all --rotate重建。中文搜不到但英文能搜到就是ngram_chars没配。5.4 支付成功但没加下载次数现象用户反馈付款了订单显示已支付但下载按钮还是提示无权限。原因回调地址配错渠道推到了 api 站的某个路径上被伪静态拦掉或者证书链不完整导致渠道侧握手失败重推几次后放弃。也有一种是自己代码里回调返回了非预期格式渠道判定失败。解决看渠道后台的回调记录有没有成功响应。没有就手动curl一遍回调地址确认能通且返回格式正确。证书用在线工具查一下中间证书是否齐全。代码侧把回调的原始报文和返回值都打进独立日志文件别和业务日志混在一起出问题的时候能直接对时间戳。5.5 大文件上传到 90% 就失败现象几十兆的 PDF 上传进度条走到大半就报错小文件正常。原因三处限制叠加。PHP 的upload_max_filesize和post_max_size默认 2M/8Mnginx 的client_max_body_size默认 1M对象存储的分片阈值也要对上。任何一处超限都会中断。解决三处一起改。php.ini 里两个值调到业务上限nginx 在server块加client_max_body_size 200m对象存储侧开分片上传前端切成 5MB 一片。改完php -i | grep upload_max和nginx -T | grep client_max各确认一次别只改一处就以为好了。6. 上线前验收三个脚本把转码、检索、回调各跑一遍部署完不等于能上线。我的习惯是在切流量之前用最小成本把三条主链路各打一遍确认端到端通。这一步花二十分钟能省掉上线当天凌晨被电话叫起来的麻烦。验收项就三块用一张表说清判定标准链路验证方式通过标准转码传一篇 30 页以上的 docx5 分钟内状态变为已完成页数与原文一致随机翻 3 页图片能打开检索用文档标题里的连续四个字搜索结果第一条就是该文档响应时间低于 300ms支付回调沙箱下单后手动重放回调两次订单只加一次下载次数第二次回调返回成功但不重复处理下面这个冒烟脚本我每次部署都会跑改改域名和 token 就能用#!/bin/bash # 上线前冒烟依次检查站点可达、检索接口、转码队列堆积 BASEhttps://www.example-doc.test APIhttps://api.example-doc.test TOKEN后台生成的测试用 token echo 1. 三站可达性 for host in www m api; do code$(curl -s -o /dev/null -w %{http_code} https://$host.example-doc.test/) # 200 或 301/302 都算正常跳转多半是强制 HTTPS echo $host - $code done echo 2. 检索接口 # 关键词取一篇已入库文档标题里的连续四字 curl -s $API/v1/search?kw文档管理limit5 \ -H Authorization: Bearer $TOKEN | head -c 500 echo echo 3. 队列堆积 # 待转码记录超过 200 条说明 worker 没在跑别急着放流量 php yii doc/queue-stat脚本里第三项最关键。转码队列的堆积量是个先行指标worker 挂了不会报错只会静默堆积等用户投诉的时候已经积了几千条。我给自己定的红线是待转码超过 200 条就暂停放量先查 cron 和disable_functions。检索那一步用「连续四个字」而不是单个词是因为单字搜索在 ngram 配置下基本都能命中测不出分词问题四字组合能同时验证索引完整性和中文切分。有一次我在半夜做迁移图快只跑了第一项站点可达就切了流量结果 Sphinx 的索引文件权限没跟着迁searchd 起不来但进程显示 running搜索静默返回空第二天早上才发现白丢了一上午的搜索流量。从那以后我每次部署不管多晚三项冒烟加一次手动重放支付回调都强制走一遍脚本跑完才动负载均衡的权重。希望帮到你。本文还有配套的精品资源点击获取