简介：面向计划搭建或运营文库网站的PHP开发者与站长，这份PDF文档给出知沃文库系统的安装配置与后台使用指引。该系统基于Yii2框架开发，融合百度文库、原创力、豆丁文库等平台思路，支持doc、pdf、ppt、图片、音视频等多格式转换预览，借助Sphinx实现毫秒级全文与组合检索，并提供微信支付宝支付、公众号小程序、商城资讯分销等运营模块。压缩包内共1个PDF文件，约7.54MB，内容按部署流程组织，涉及ECS安全组设置、PC/手机/接口站建立、对象存储、短信与支付配置、第三方登录、公众号对接、导航与栏目层级、用户等级、Banner管理、内容管理、文档发布流程、Sphinx启用及定时转码任务等。已有334人学习，适合希望快速完成环境搭建、理清系统模块关系并支撑后续文库平台运营的读者查阅。
1. 文库系统源码上线前的第一判断：三个子域跑一套程序
一套文库网站系统源码值不值得上手，我通常先看域名拓扑，再看功能列表。这份资源的部署形态很典型：www 跑 PC 站，m 跑手机站，api 跑接口，三个子域指向同一台服务器、同一个程序根目录。这个设计基本决定了后面所有配置动作——伪静态要按站点分开写、Cookie 必须跨子域、上传目录必须共享、转码任务只能有一个入口在跑。搞不清这一层，装完首页能打开，登录却一直掉，或者手机站传的文档 PC 站搜不到，排查能耗掉一整天。这套文库系统源码基于 Yii2 框架、PHP 技术栈，配套从服务器安全组、建站、对象存储、短信、支付、第三方登录，到公众号、栏目层级、用户等级、Banner、Sphinx 检索和定时转码的一整套运营配置说明，适合想自己搭文档管理系统或文库站点、又不想从零写转码和全文检索的人。
2. 三子域一套程序的建站骨架：目录、伪静态与存储参数
2.1 根目录怎么摆：三个站点共用一个 public
建站这一步最容易犯的错，是给 PC 站、手机站、接口站各传一份程序。表面上看三个站互不干扰，实际上上传文件、缓存、Session 全被打散，用户在手机站传的文档在 PC 站列表里查不到，后台改一次栏目要清三遍缓存。正确做法是只留一份代码，把三个站点的站点根目录都指向同一个绝对路径，运行目录统一指向public。
常见的目录结构我一般这样摆：
/data/www/wenku/ # 站点根目录（三个子域都指向这里） ├── public/ # 运行目录，Web 入口 │ ├── index.php # 前端入口 │ ├── api.php # 接口入口 │ ├── static/ # 静态资源 │ └── uploads/ # 上传落地，建议软链到数据盘 ├── console/ # 命令行入口，转码与索引都从这里跑 ├── common/ # 公共模型与配置 ├── backend/ # 后台模块 ├── runtime/ # 运行时缓存与日志，需要可写 └── vendor/ # composer 依赖几个参数要提前定死，不然后面改起来很烦：站点根目录填/data/www/wenku，运行目录填/public，PHP 版本按程序要求走（这套资源常见做法是 7.4 及以上），runtime和public/uploads要给 Web 用户可写权限，但不要把整个站点根目录设成 777——那等于把配置文件和数据库密码摆在公网上。上传目录如果单独挂数据盘，用ln -s软链过去，比直接改程序里的路径常量安全，将来迁移也只动一个链接。
public作为唯一入口还有一层好处：转码出来的 H5 页面和图片序列都落在uploads下，PC 站、手机站、接口站拿到的是同一个相对路径，前端不用为每个子域拼不同域名前缀，少一类跨域图片 403 的问题。
2.2 伪静态与跨子域 Cookie：登录态为什么老掉
Yii2 默认的 URL 形态是index.php?r=site/login，直接上线对 SEO 很不友好，文库站靠栏目页和文档页吃自然流量，路由必须美化。这份资源的做法是开urlManager，把文档详情、栏目列表、标签页都映射成静态化路径：
// common/config/main.php 片段 'urlManager' => [ 'enablePrettyUrl' => true, // 开启美化 URL 'showScriptName' => false, // 去掉 index.php 'suffix' => '.html',// 文档详情页带后缀，便于静态缓存 'rules' => [ 'doc/<id:\d+>.html' => 'doc/view', // 文档详情 'list/<cat:\d+>.html' => 'doc/list', // 栏目列表 'search/<kw>' => 'search/index', // 检索结果页 ], ],配套的 Nginx 伪静态要按子域分别写。PC 站和手机站规则一致，接口站要关掉页面缓存、放开跨域：
server { listen 80; server_name www.example.com m.example.com; root /data/www/wenku/public; index index.php; location / { try_files $uri $uri/ /index.php?$query_string; # 交给 Yii2 路由 } location ~ \.php$ { fastcgi_pass unix:/run/php/php-fpm.sock; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } location ~* \.(js|css|png|jpg|webp|woff2)$ { expires 7d; # 预览图与静态资源走长缓存 access_log off; } }登录态掉线十有八九是 Cookie 域没配对。三个子域共享登录，Session 的 Cookie 域必须写成.example.com这种带前导点的形式，而不是www.example.com。在 Yii2 里改session组件和request组件的cookieValidationKey要一致，否则手机站拿到的 Cookie 在 PC 站验不过，表现就是「登录成功，刷新又变游客」。这一步翻车过的人都懂，属于典型的玄学问题，实际就是配置里少了一个点。
提示：三个子域共用一份
cookieValidationKey，但不要把它提交进公开仓库；接口站的跨域头只放行你自己的三个域名，不要写*配credentials。
2.3 数据库、缓存与对象存储：先定容量再装
装之前先想清楚两件事：文档存本地还是对象存储，检索走数据库还是 Sphinx。这套文库系统源码的卖点是毫秒级检索和多格式预览，这两件事都吃资源，配置不当会在文档量上去之后集中爆发。
数据库连接我一般单独抽一个配置文件，字符集统一utf8mb4，表前缀保留程序默认值，方便后续升级不冲突：
// common/config/db.php return [ 'class' => 'yii\db\Connection', 'dsn' => 'mysql:host=127.0.0.1;dbname=wenku;charset=utf8mb4', 'username' => 'wenku', 'password' => '******', 'tablePrefix' => 'wk_', 'charset' => 'utf8mb4', 'enableSchemaCache' => true, // 表结构缓存，减少 describe 查询 'schemaCacheDuration' => 3600, ];缓存建议直接上 Redis，三个子域共用一套，但 key 前缀要区分开，避免后台清缓存把前台的登录 Session 一起冲掉。文件缓存只适合单机、文档量几千以内的小站，一旦上 CDN 或者扩到第二台机器就会互相看不见。
存储方案我整理成一张表，按规模选就行：
| 方案 | 适合文档量 | 优点 | 注意点 |
|---|---|---|---|
| 本地磁盘 | 千级以内 | 零成本、转码读写快 | 备份难、扩容要停机、源文件很快吃满盘 |
| 对象存储 | 万级以上 | 容量弹性、可私有读 | 要走临时签名 URL，别把 bucket 设成公共读 |
| 对象存储 + CDN | 预览图访问量大 | 首屏快、省源站带宽 | 回源鉴权要配好，缓存刷新策略要写进流程 |
对象存储的配置项无非四样：AccessKey、Secret、Bucket、访问域名。要提醒的是密钥权限最小化，只给这一个 bucket 的读写，不要用主账号密钥；预览图如果走 CDN，私有 bucket 的签名 URL 有效期别设太长，文库站的付费文档预览地址被人转出去，损失是直接的。
3. 文档转码与检索链路：从上传落地到 Sphinx 命中
3.1 转码状态机：三态流转与失败重试
文库站的核心体验在「上传完能不能马上看」。这套资源的做法是把 doc、docx、ppt、pptx、pdf、txt、zip 以及 mp3、mp4、jpg、png、bmp、gif 这些格式统一转成 H5 或图片序列，文字放大不失真，对搜索引擎也友好。转码不是请求里同步做的——一个 50 页的 PPT 同步转能把 PHP-FPM 进程占满，用户等到超时，所以必须走队列加定时任务。
我一般给文档表加三个字段：convert_status（0 待转、1 转换中、2 成功、-1 失败）、convert_times（重试次数）、preview_path（转码产物路径）。状态机只允许单向流转，转换中的记录超过阈值时间没回写就判定为僵死，重新入队。
命令行入口放在console下，用参数控制批量和超时：
# 每次取 20 条待转码文档，单篇超时 300 秒，最多重试 3 次 php /data/www/wenku/yii doc/convert --limit=20 --timeout=300 --retry=3--limit是限流阀，按 CPU 核数给，4 核机器一般 10 到 20 之间，给大了转码进程互相抢资源，反而更慢；--timeout要大于最大文档的实际转码耗时，否则大 PDF 会被反复判超时；--retry到上限后把记录标成 -1 并写日志，别再无限重试，不然一批坏文件能把队列堵死。
失败原因集中在几处：源文件权限不对、服务器缺字体导致 PDF 转图片全是方块、Office 文档里有宏或者加密、zip 包解压后路径穿越。日志里要看的是转码工具的实际 stderr，不是 PHP 层的异常信息，那层信息基本是黑匣子，只能告诉你失败了。
3.2 Sphinx 主索引与增量索引：新文档搜不到怎么办
检索这条链路是文库站和普通 CMS 最大的差别。数据库LIKE '%关键词%'在十万级文档上就是灾难，这套资源用 Sphinx 做全文检索加条件组合检索，响应能压到毫秒级。配置的关键是主索引加增量索引，主索引全量建，增量按自增 ID 追。
# /etc/sphinx/sphinx.conf 片段 source doc_src { type = mysql sql_host = 127.0.0.1 sql_user = wenku sql_pass = ****** sql_db = wenku sql_query_pre = SET NAMES utf8mb4 # 只索引转码成功的文档，且 ID 不超过上次增量水位 sql_query = SELECT id, title, description, cat_id, UNIX_TIMESTAMP(create_time) AS ctime \ FROM wk_doc WHERE convert_status = 2 AND id <= (SELECT max_id FROM wk_sphinx_meta) sql_attr_uint = cat_id # 栏目过滤用，必须做属性 sql_attr_timestamp = ctime # 按时间排序用 sql_field_string = title # 标题保留原文，便于高亮 } index doc_main { source = doc_src path = /data/sphinx/doc_main morphology = none min_word_len = 1 charset_table = 0..9, A..Z->a..z, a..z, U+4E00..U+9FA5 # 中文按单字切 }sql_attr_uint和sql_attr_timestamp这两行别省，栏目筛选、时间排序全靠属性字段，漏了就只能全量过滤，毫秒级立刻变秒级。中文分词这块，常见做法是单字切加关键词表，标题命中权重给高，正文摘要权重给低；如果追求更好的分词效果，也可以换带中文词典的分词方案，代价是多一個维护成本。
增量索引的合并命令固定两条：
# 1. 建增量索引并热加载 indexer --config /etc/sphinx/sphinx.conf doc_delta --rotate # 2. 把增量合并进主索引，合并后清空增量 indexer --config /etc/sphinx/sphinx.conf --merge doc_main doc_delta --rotate--rotate是平滑重建，不中断线上查询；合并完成要把wk_sphinx_meta的max_id更新成当前最大文档 ID，否则下一轮增量会重复索引同一批数据，索引文件越滚越大。这套流程跑顺了，新文档从上架到可检索的延迟就是增量任务的间隔，一般 1 到 5 分钟，够用。
3.3 定时任务怎么排：三条 cron 加一把锁
转码、增量索引、临时文件清理这三件事都靠 cron，排布上最大的坑是并发。转码任务如果上一轮还没跑完下一轮又起来，同一篇文档会被两个进程同时写，产物互相覆盖，预览页一半白一半花。解决办法是flock加非阻塞锁：
# 每分钟拉起一次转码，拿不到锁就跳过，避免并发 * * * * * flock -n /tmp/wenku_convert.lock php /data/www/wenku/yii doc/convert --limit=20 >/dev/null 2>&1 # 每 5 分钟跑一次增量索引并合并 */5 * * * * flock -n /tmp/wenku_index.lock /usr/bin/indexer --config /etc/sphinx/sphinx.conf doc_delta --rotate && /usr/bin/indexer --config /etc/sphinx/sphinx.conf --merge doc_main doc_delta --rotate # 凌晨清理三天前的转码临时文件，源文件保留 0 3 * * * php /data/www/wenku/yii doc/clean-tmp --days=3flock -n的-n是关键，拿不到锁直接退出而不是排队等，否则任务会越堆越多。转码频率给到每分钟是因为单轮只处理 20 条，处理完立刻退出，空跑的成本很低；索引任务给 5 分钟是平衡检索实时性和 CPU 占用。清理任务一定要和源文件分开目录，我见过把uploads整个当临时目录清的，源文件一起没了，那真是没有后悔药。
注意：
searchd进程要设开机自启，服务器重启后索引服务没起来，前台检索会直接报错而不是降级，用户看到的就是整站搜索不可用。
4. 运营配置：支付回调、三套凭证与栏目结构
4.1 支付通道：金额单位与回调幂等是两道坎
文库站的变现靠单篇付费下载和会员，支付接的是主流移动支付通道。流程本身不复杂：下单生成订单号 → 调起支付 → 异步回调 → 验签 → 校验金额 → 改订单状态 → 发下载权限。真正出事的地方在两处：金额单位和回调重复。
金额单位必须从下单到回调全程统一。有的通道按分传，有的按元传，程序里如果一处乘 100 一处不乘，表现就是「支付成功，订单还是待支付」，用户投诉、客服退款，血泪经验。回调处理的骨架大概是这样：
public function actionNotify() { $raw = file_get_contents('php://input'); // 1. 验签：失败直接返回失败，并记录原始报文，方便对账 if (!$this->verifySign($raw)) { Yii::error('pay sign fail: ' . $raw, 'pay'); return 'fail'; } $data = json_decode($raw, true); $order = Order::findOne(['order_no' => $data['out_trade_no']]); // 2. 幂等：已支付的订单直接返回成功，不重复发货 if ($order && $order->status == Order::STATUS_PAID) { return 'success'; } // 3. 金额校验：回调金额与订单金额按分比对，不一致直接拒绝 if (!$order || (int)$order->amount_fen !== (int)$data['total_fee']) { Yii::error('pay amount mismatch: ' . $raw, 'pay'); return 'fail'; } // 4. 事务内改状态并发下载权限 $this->grantDownload($order, $data['transaction_id']); return 'success'; }三个参数要盯死：out_trade_no必须唯一且能反查订单，total_fee按分存整数避免浮点误差，transaction_id落库做对账凭据。回调返回的字符串要和通道约定的一致，返回错了通道会一直重推，日志刷得飞快。
4.2 三套凭证别混用：公众号、开放平台与小程序
这套资源对接微信生态的部分最容易配串。公众号网页授权、公众号消息推送、小程序登录、开放平台第三方授权，用的是四组不同的凭证，配置位置也不在一处：
| 场景 | 需要的凭证 | 配置位置 | 常见错误 |
|---|---|---|---|
| 公众号网页授权 | AppID + AppSecret + 授权域名 | 后台第三方登录 | 授权域名带路径或端口，回调失败 |
| 公众号消息推送 | 服务器地址 + Token + EncodingAESKey | 后台公众号设置 | Token 与后台不一致，消息一直提示配置失败 |
| 小程序登录 | AppID + AppSecret + 业务域名 | 小程序配置 | 用了公众号的 Secret，换取 openid 报错 |
| 开放平台授权 | 第三方平台 AppID + 授权回调 | 开放平台设置 | 回调地址与平台上登记的不完全一致 |
授权域名这条要特别说：域名必须是纯域名，不能带协议后的路径、不能带端口，且要能被公网访问。配错的表现是页面跳转过去白屏或者提示 redirect_uri 参数错误，看不出是哪一步的问题，只能挨个字符比对。
公众号自定义菜单和自动回复的配置建议在后台改完先取关再重新关注测试，很多人配完发现没生效，其实是本地缓存了旧的菜单结构，不是程序问题。消息推送的服务器地址配好之后，后台会做一次校验请求，这时候如果站点开了强制 HTTPS 跳转而校验走的是 HTTP，也会失败。
4.3 栏目层级、导航与用户等级：先定结构再灌内容
栏目层级是运营侧最该在上线前定死的东西。文库站的栏目一般是三级：一级大类（行业、学科、文档类型）、二级分类、三级标签。层级超过三级，面包屑和导航做起来会非常难受，检索过滤条件也会爆炸。程序里通常用parent_id加path字段，path存1-5-23这种祖先链，查子孙栏目一条LIKE '1-5-%'就够了，比递归查询快得多。
导航和 Banner 属于展示层，和栏目是两套数据，但都吃缓存。操作顺序我一般卡死：先建栏目 → 再导内容 → 最后配导航和 Banner。反过来的话，导航里挂的栏目 ID 会在导入过程中变，前台出现死链，还得手动清一遍缓存。
用户等级直接和上传下载权限挂钩，是个容易被忽略但很影响运营的参数表：
| 等级 | 每日上传数 | 单文件上限 | 下载权限 | 备注 |
|---|---|---|---|---|
| 普通用户 | 3 | 20MB | 仅免费文档 | 上传后进入待审核 |
| 实名用户 | 20 | 100MB | 免费 + 积分兑换 | 需绑定手机号 |
| 上传者 | 50 | 200MB | 全部免费文档 | 上传通过率达标后升级 |
| 运营号 | 不限 | 500MB | 全部 | 后台手动授予 |
这几档数值不是拍脑袋的，要结合服务器磁盘和转码队列的吞吐反推：单文件上限给到 500MB，转码一篇就能把 CPU 占满几十秒，队列会被大文件堵住，普通用户的上传数就必须压下来。等级规则定完再开放注册，比上线后天天改规则省事得多。
5. 避坑与排查：这套文库系统最容易翻车的十个点
5.1 站点与转码链路上的故障
现象：手机站登录成功，切到 PC 站又变游客。原因基本是 Session 的 Cookie 域写成了具体子域，或者三个站点的cookieValidationKey不一致，手机站签发的 Cookie 在 PC 站验不过。解决是把 Cookie 域改成带前导点的主域，三份配置的校验密钥统一，改完清一遍runtime缓存再测。
现象：文档上传成功，预览页一直转圈，状态停在「转换中」。原因通常是转码进程中途被杀，状态没回写，记录僵死。解决是给转换中状态加超时判定，超过 10 分钟自动回到待转码并累加重试次数，同时在 cron 里用flock防并发，避免两个进程同时处理同一篇。
现象：PDF 转出来的图片全是方块或空白。服务器缺中文字体，转码工具找不到字体就渲染成占位符。解决是把常用中文字体装进系统字体目录并刷新字体缓存，转码容器或运行环境里也要装一份，别只在宿主机装。
现象：上传大文件直接 413 或 502。Nginx 的client_max_body_size和 PHP 的upload_max_filesize、post_max_size三处都要放开，只改一处没用；502 多半是转码同步执行把 FPM 进程拖死，要把转码改成异步队列。正确顺序是先改上传限制，再确认转码是异步的。
现象：磁盘几天就满了，一查全是源文件。源文件、转码中间产物、预览图混在一个目录，清理脚本一刀切。解决是按uploads/source、uploads/tmp、uploads/preview三个目录分开存，清理只动 tmp，源文件按保留策略单独处理。
5.2 支付、登录与检索上的故障
现象：支付成功但订单显示未支付。九成是金额单位不一致，回调按分传、订单按元存，校验直接不通过；剩下一成是回调地址被防火墙拦了，通道推不过来。排查先看回调日志有没有收到请求，收到了再比金额字段，两步就能定位。
现象：公众号网页授权回调报 redirect_uri 错误。后台填的授权域名带了路径或端口，或者和公众号后台登记的域名不完全一致。解决是两边都只填纯域名，改完等几分钟生效，别急着反复提交。
现象：新发布的文档搜索不到，老文档正常。增量索引跑了但没合并进主索引，或者sphinx_meta的水位没更新导致增量重复。解决是手动执行一次合并命令，确认max_id已推进，再看检索配置里查的是主索引还是主索引加增量。
现象：搜索关键词命中率很低，标题完全匹配也搜不出来。中文分词配置问题，单字切得太碎或者词典没加载。解决是先确认索引字段里包含了标题，再调分词配置，把标题字段权重调高，用几个固定关键词做回归测试，别凭感觉调。
现象：后台改了栏目名，前台还是旧的。栏目、导航、Banner 都做了缓存，改完没触发刷新。解决是后台操作完成后主动清对应缓存 key，而不是等过期；或者把这三类数据的缓存时间压到很短，用性能换一致性。
6. 上线前压一遍：用三个指标验收这套文库系统
装完能打开首页不算验收。我习惯在上线前跑一轮固定动作，用三个指标判断这套文库系统源码是不是真的可用：转码成功率、检索命中延迟、支付回调闭环。
| 验收项 | 目标值 | 验证方法 |
|---|---|---|
| 转码成功率 | 常见格式 ≥ 95% | 批量传 50 篇 doc/pdf/ppt，看状态为成功的比例 |
| 单篇转码耗时 | 20 页 PDF ≤ 30 秒 | 从convert_times和日志时间戳算差值 |
| 检索命中延迟 | 新文档上架后 ≤ 5 分钟可搜 | 发布后按分钟轮询检索接口 |
| 检索响应 | P95 ≤ 200ms | 用脚本压 100 次组合条件查询 |
| 支付闭环 | 100% 回调成功 | 用沙箱各下一单，验订单状态与下载权限 |
检索这块我会写个小脚本压一遍，别用浏览器手点，手点感受不到长尾：
# 连续 100 次组合条件检索，统计 P95 耗时 for i in $(seq 1 100); do curl -s -o /dev/null -w "%{time_total}\n" \ "https://www.example.com/search/test?cat=3&sort=time" done | sort -n | awk '{a[NR]=$1} END{print "P95:", a[int(NR*0.95)]}'-w "%{time_total}"拿的是端到端耗时，包含网络和 PHP 执行；如果这个数和 Sphinx 日志里的查询耗时差很多，说明瓶颈在 PHP 层或者数据库，不在索引。压的时候记得带真实条件组合，只测空关键词没有意义。
还有一个容易漏的验收点：把转码队列故意塞一篇坏文件（加密 PDF 或者改过扩展名的 zip），看它会不会把后面的正常文档堵住。队列的健壮性比峰值性能更重要，线上最怕的不是慢，是卡死。
从那以后我每次交付这类文库站，都强制走一遍「坏文件堵队列」的测试，再顺带把 cron 的锁文件清一遍——flock的锁文件如果被手工删掉而进程还在，后面所有任务都会静默跳过，这个坑我踩过一次，日志里什么都没有，排查了两个小时。希望帮到你。
本文还有配套的精品资源，点击获取
