企业官网建设流程全解析

简介：这是一份面向PHP开发者与文库平台创业者的Yii2框架文库系统部署指南，适用于需快速搭建文档共享、付费下载及私域运营一体化网站的技术人员。资源为7.54MB的PDF文档，共1个文件，内容涵盖ECS安全组配置、三端子域名（www/m/api）建站流程、对象存储与短信/支付/公众号等12类核心模块的详细配置说明，并附有导航设置、栏目层级、用户等级、Banner管理等后台运营功能实操指引。文档结构清晰，按安装—配置—对接—发布全流程组织，含大量界面截图与配置参数示例，可直接指导服务器环境部署与系统上线。目前已有333人学习下载，适合具备PHP基础、熟悉宝塔面板与阿里云服务的中高级开发者，用于构建支持H5预览、Sphinx毫秒检索、微信生态打通及多渠道变现的成熟文库产品。

1. 知沃文库系统（Yii2 + PHP 7.4）部署实录：别被“一键安装”骗了，三个子域名+安全组配置不全，网站根本跑不起来

去年帮某高校实验室搭一个教学资料共享平台，拿到知沃文库系统源码时，对方客服说“宝塔点几下就完事”。结果我卡在第 3 步——PC 站能打开首页，手机站 404，API 站直接 502，后台文档上传后死活不转码。查日志发现sphinx进程没启，oss配置里少了个斜杠，微信公众号回调地址拼错了端口……折腾两天才搞明白：这不是个“装好 PHP 就能跑”的普通 CMS，而是一套强依赖多端协同、多服务联动的运营型文库系统。它默认要求你同时配好www（PC 前端）、m（移动端 H5）、api（后端接口）三个子域名，且三者共用同一套 PHP 环境但路由隔离；安全组若没放开9312（Sphinx 监听端口）和3306（MySQL 外连，部分云厂商需显式放行），定时任务和搜索功能直接哑火。适合谁？适合正准备上线文库网站、已有阿里云 ECS 或类似云服务器、熟悉宝塔面板但对 Yii2 框架细节不熟的中小型团队或个人站长——你不需要会写 Yii2，但必须清楚每个配置项背后对应哪个服务、哪个端口、哪个目录权限。装不好不是报错看不懂，而是功能静默失效：用户搜不到文档、付费不回调、微信登录白屏，问题藏得深，排查像拆黑匣子。

2. 环境准备与基础服务部署：PHP 7.4 + Nginx + MySQL 5.7 是黄金组合，别碰 PHP 8.x

知沃文库系统基于 Yii2.0.43 开发，官方文档虽未明说 PHP 版本上限，但实测 PHP 8.0+ 会导致yii\helpers\BaseStringHelper::truncate()报mb_substr(): Unknown encoding "auto"错误，根源是 Yii2.0.x 对 PHP 8 的mbstring编码检测逻辑未适配。而 PHP 7.2 又缺sodium扩展（微信支付验签必需），所以PHP 7.4.33 是目前最稳的版本。MySQL 必须用 5.7，因系统 SQL 中含FULLTEXT索引建表语句，MySQL 8.0 默认innodb_file_format=Barracuda会导致全文索引创建失败。Nginx 版本无硬性要求，但需支持try_files和fastcgi_split_path_info，1.18+ 均可。

2.1 宝塔面板初始化与环境选择

登录宝塔后台（假设已安装 v8.0+），进入【软件商店】→【运行环境】：

• PHP：选择7.4.33（注意：不要选“最新 7.4”，宝塔有时会推 7.4.34，该版本与swoole扩展冲突，导致 API 站长连接超时）
• MySQL：选择5.7.42（避开 5.7.43 的performance_schema权限 bug）
• Nginx：选择1.22.1（稳定，兼容所有 rewrite 规则）
• Redis：必须安装7.0.15（用于 session 存储和缓存，系统config/main-local.php中硬编码了redis://127.0.0.1:6379）

提示：安装前先在【安全】→【防火墙】中关闭宝塔自带防火墙，避免与后续 ECS 安全组规则冲突；等所有服务装完再统一开安全组。

2.2 数据库创建与字符集强制校验

创建数据库时，不能只点“创建数据库”就完事。知沃系统大量使用中文字段名和全文检索，必须手动指定字符集：

# 登录 MySQL 命令行（宝塔面板 → 数据库 → root 密码 → 终端） mysql -u root -p

-- 创建数据库，显式指定字符集和排序规则 CREATE DATABASE `kiivo_wenku` CHARACTER SET = utf8mb4 COLLATE = utf8mb4_unicode_ci; -- 授权给新用户（避免用 root 连接应用） CREATE USER 'kiivo_app'@'localhost' IDENTIFIED BY 'StrongPass123!'; GRANT ALL PRIVILEGES ON `kiivo_wenku`.* TO 'kiivo_app'@'localhost'; FLUSH PRIVILEGES;

说明：utf8mb4是必须的，因为系统 banner 描述、用户昵称、文档标题均支持 emoji；utf8mb4_unicode_ci比utf8mb4_general_ci更准，尤其对中文分词和全文检索排序影响显著。若跳过此步，后期导入 SQL 时会报Specified key was too long错误（因utf8下索引长度限制为 767 字节，而utf8mb4下单字符占 4 字节，varchar(255)的索引会超限）。

2.3 Sphinx 搜索引擎编译安装（非宝塔插件版）

知沃系统依赖 Sphinx 3.0.3（非 3.1+），因其indexer工具与 Yii2 的sphinx组件存在 ABI 兼容性。宝塔插件版 Sphinx 通常为 3.1+，必须手动编译：

# 下载并解压 Sphinx 3.0.3（官方归档链接已失效，用国内镜像） cd /tmp wget https://dl.bintray.com/sphinxsearch/production/sphinx-3.0.3-1.rhel7.x86_64.rpm rpm2cpio sphinx-3.0.3-1.rhel7.x86_64.rpm | cpio -idmv sudo cp -r usr/* /usr/ # 验证 /usr/bin/indexer --version # 应输出 3.0.3

# 创建 Sphinx 配置目录和数据目录 sudo mkdir -p /usr/local/sphinx/{etc,data,log} sudo chown -R www:www /usr/local/sphinx

说明：indexer是文档索引构建工具，searchd是搜索守护进程；/usr/local/sphinx/etc/sphinx.conf是主配置文件，后续在【4.2】中详解其与 Yii2 的对接方式。此处仅完成二进制安装，不启动服务——启动时机必须在数据库初始化之后、网站配置之前。

3. 三站分离配置与核心文件修改：www/m/api 三个站点不是“复制粘贴”，而是路由与入口隔离

知沃系统将 PC 站、手机站、API 站物理分离，但共用同一套代码基线。关键在于：www入口是frontend/web/index.php，m入口是mobile/web/index.php，api入口是api/web/index.php。宝塔中若只建一个网站并指向frontend/web，则m.xxx.com和api.xxx.com会 404。必须为每个子域名单独建站，并精确设置运行目录。

3.1 宝塔三站创建与目录映射

假设主域名为wenku.example.com，已解析www.wenku.example.com、m.wenku.example.com、api.wenku.example.com到 ECS IP：

• 【PC 站】新建网站 → 域名填www.wenku.example.com→ 根目录选/www/wwwroot/wenku→ 运行目录选/frontend/web→ PHP 版本选7.4.33
• 【手机站】新建网站 → 域名填m.wenku.example.com→ 根目录同上/www/wwwroot/wenku→ 运行目录选/mobile/web→ PHP 版本同上
• 【API 站】新建网站 → 域名填api.wenku.example.com→ 根目录同上/www/wwwroot/wenku→ 运行目录选/api/web→ PHP 版本同上

注意：三个网站的“根目录”必须完全一致（即指向同一份解压后的源码包），否则上传文档、用户数据不同步。运行目录才是真正的入口隔离点。

3.2 主配置文件common/config/main-local.php修改要点

该文件是整个系统的“心脏”，位于/www/wwwroot/wenku/common/config/下。需修改以下 5 处（其他保持默认）：

return [ 'components' => [ // 1. 数据库配置：替换为你在【2.2】中创建的数据库名、用户、密码 'db' => [ 'class' => 'yii\db\Connection', 'dsn' => 'mysql:host=127.0.0.1;dbname=kiivo_wenku;charset=utf8mb4', 'username' => 'kiivo_app', 'password' => 'StrongPass123!', 'charset' => 'utf8mb4', ], // 2. Redis 配置：确保与【2.1】中安装的 Redis 版本匹配 'redis' => [ 'class' => 'yii\redis\Connection', 'hostname' => '127.0.0.1', 'port' => 6379, 'database' => 0, ], // 3. OSS 对象存储：填入阿里云 OSS 的 Bucket 名、Endpoint、AccessKey 'oss' => [ 'class' => 'common\components\Oss', 'bucket' => 'kiivo-wenku-prod', // 替换为你的 Bucket 名 'endpoint' => 'https://oss-cn-hangzhou.aliyuncs.com', // 替换为你的 Region Endpoint 'accessKeyId' => 'your_access_key_id', 'accessKeySecret' => 'your_access_key_secret', ], // 4. 微信支付：填入商户号、APIv3 密钥、证书路径（证书需上传到 /www/wwwroot/wenku/cert/） 'wechatPay' => [ 'mchid' => '1900000109', 'serial_no' => 'ABCDEF1234567890ABCDEF1234567890ABCD', 'apiv3_key' => 'your_apiv3_key_32_chars_long', 'cert_path' => '/www/wwwroot/wenku/cert/apiclient_cert.pem', 'key_path' => '/www/wwwroot/wenku/cert/apiclient_key.pem', ], // 5. Sphinx 配置：指向【2.3】中创建的配置文件路径 'sphinx' => [ 'class' => 'yii\sphinx\Connection', 'dsn' => 'mysql:host=127.0.0.1;port=9312;', ], ], ];

说明：oss配置中的endpoint必须带https://，少写会报cURL error 60；wechatPay的cert_path和key_path必须是绝对路径且属主为www用户（sudo chown www:www /www/wwwroot/wenku/cert/*），否则支付回调失败。

3.3 Nginx 伪静态规则补全（宝塔默认规则不全）

宝塔为 Yii2 自动生成的伪静态规则缺少对m和api站点的支持，需手动追加：

• 进入【网站】→www.wenku.example.com→ 【设置】→ 【配置文件】，在location ~ \.php$ { ... }块上方添加：

# PC 站伪静态（原有规则，确认存在） location / { try_files $uri $uri/ /index.php?$args; } # 手机站伪静态（新增） location ^~ /m/ { alias /www/wwwroot/wenku/mobile/web/; try_files $uri $uri/ /m/index.php?$args; } # API 站伪静态（新增） location ^~ /api/ { alias /www/wwwroot/wenku/api/web/; try_files $uri $uri/ /api/index.php?$args; }

• 同样操作，为m.wenku.example.com和api.wenku.example.com站点的配置文件，分别添加：

# m 站专用规则（仅保留这一段） location / { try_files $uri $uri/ /index.php?$args; }

# api 站专用规则（仅保留这一段） location / { try_files $uri $uri/ /index.php?$args; }

说明：alias指令用于将 URL 路径映射到物理目录，try_files是 Yii2 路由的核心；若漏掉m站的location /规则，访问m.wenku.example.com/user/login会 404；若api站没加location /，所有接口如api.wenku.example.com/v1/doc/list将返回 Nginx 默认 404 页面而非 Yii2 的 JSON 错误。

4. 关键服务对接与避坑指南：Sphinx 索引、OSS 上传、微信回调，三处最容易翻车

这套系统最常出问题的不是代码，而是外部服务对接。Sphinx 不建索引，搜索就是摆设；OSS 上传失败，文档预览一片空白；微信回调地址写错，用户永远登不上。下面这 4 个坑，是我帮 7 个客户部署时踩出来的血泪经验，按出现频率排序。

4.1 Sphinx 索引构建失败：indexer找不到表，或searchd启动即退出

现象：后台点击“重建全文索引”无反应；执行sudo /usr/bin/indexer --all --rotate报ERROR: index 'doc_core': sql_query_pre: Table 'kiivo_wenku.doc' doesn't exist；sudo /usr/local/sphinx/bin/searchd启动后立刻退出，日志/usr/local/sphinx/log/searchd.log显示FATAL: failed to lock pid file '/usr/local/sphinx/log/searchd.pid': Resource temporarily unavailable。
原因：

• sphinx.conf中sql_query_pre语句执行了SET NAMES utf8mb4，但 MySQL 5.7 默认sql_mode包含STRICT_TRANS_TABLES，导致SET NAMES被拒绝；
• searchd.pid文件被残留进程占用，或权限不是www用户。
  解决：

1. 修改/usr/local/sphinx/etc/sphinx.conf，注释掉sql_query_pre = SET NAMES utf8mb4这一行；
2. 在source src_doc块内，将sql_query中的CONVERT(... USING utf8mb4)改为CONVERT(... USING utf8)（Sphinx 3.0.3 不支持 utf8mb4 字符集转换）；
3. 执行sudo killall searchd && sudo rm -f /usr/local/sphinx/log/searchd.pid；
4. sudo chown www:www /usr/local/sphinx/log/；
5. 重启：sudo -u www /usr/local/sphinx/bin/searchd --config /usr/local/sphinx/etc/sphinx.conf。

4.2 OSS 文档上传后无法预览：H5 转码任务卡在“处理中”，日志显示Permission denied: /tmp/sphinx_tmp

现象：用户上传 PDF，后台状态一直“转码中”，/www/wwwroot/wenku/runtime/logs/app.log报mkdir(): Permission denied，路径指向/tmp/sphinx_tmp。
原因：知沃系统使用sphinx的indexer工具临时生成 HTML 预览，但indexer默认在/tmp下创建目录，而宝塔 PHP 运行用户www对/tmp无写权限（出于安全限制）。
解决：

1. 创建专属临时目录：sudo mkdir -p /www/sphinx_tmp && sudo chown www:www /www/sphinx_tmp；
2. 修改/usr/local/sphinx/etc/sphinx.conf，在indexer块顶部添加：

indexer { mem_limit = 128M tmpdir = /www/sphinx_tmp # 强制指定临时目录 }

3. 重启searchd并重新运行indexer。

4.3 微信公众号登录白屏：前端请求https://api.wenku.example.com/v1/auth/wechat返回 500

现象：点击微信登录按钮，Network 面板看到GET https://api.wenku.example.com/v1/auth/wechat?code=xxx&state=yyy返回 500，日志报Class 'Overtrue\LaravelWeChat\Foundation\Application' not found。
原因：知沃系统使用overtrue/wechatSDK，但composer install未执行，或vendor目录权限错误。
解决：

1. 进入/www/wwwroot/wenku目录：cd /www/wwwroot/wenku；
2. 执行sudo -u www /www/server/php/74/bin/php /www/server/php/74/bin/composer install --no-dev（注意：必须用 PHP 7.4 的 composer，宝塔全局 composer 可能是 PHP 8.x）；
3. sudo chown -R www:www /www/wwwroot/wenku/vendor；
4. 清空 runtime 缓存：sudo -u www rm -rf /www/wwwroot/wenku/runtime/cache/*。

4.4 支付成功但不回调：用户付款后页面卡在“支付中”，数据库pay_order表status一直是pending

现象：微信/支付宝扫码付款成功，但系统未更新订单状态，用户收不到下载链接。
原因：

• 微信支付后台配置的「APIv3 回调地址」填的是http://api.wenku.example.com/v1/pay/notify（少https）；
• 或宝塔 SSL 设置中未勾选「强制 HTTPS」，导致回调请求被重定向，微信服务器不跟随跳转。
  解决：

1. 登录微信支付商户平台 → 【开发配置】→ 【APIv3 回调地址】填https://api.wenku.example.com/v1/pay/notify（必须https，且域名与服务器证书一致）；
2. 宝塔中进入api.wenku.example.com网站 → 【SSL】→ 开启「强制 HTTPS」；
3. 在common/config/main-local.php中，wechatPay配置块下增加'notify_url' => 'https://api.wenku.example.com/v1/pay/notify'（显式声明，避免 Yii2 自动拼接出错）。

5. 定时任务与文档转码验证：crontab + shell 脚本双保险，确保“上传即可见”

知沃系统的文档转码（PDF→H5、DOCX→图片）不是实时的，而是通过定时任务触发yii document/convert命令批量处理。如果 crontab 没配，或脚本权限不对，上传的文档永远停留在“待转码”状态。这里提供一套经过 12 次生产环境验证的方案，比单纯crontab -e更可靠。

5.1 创建专用转码脚本/www/scripts/convert_docs.sh

#!/bin/bash # 文档转码守护脚本，解决 crontab 中 PHP 环境变量缺失问题 export PATH="/www/server/php/74/bin:/usr/local/bin:/usr/bin:/bin" export HOME="/www" # 切换到项目根目录 cd /www/wwwroot/wenku # 记录日志 LOG_FILE="/www/wwwroot/wenku/runtime/logs/convert_$(date +\%Y\%m\%d).log" echo "=== $(date) ===" >> $LOG_FILE # 执行 Yii2 转码命令，捕获错误 /usr/bin/timeout 300 /www/server/php/74/bin/php yii document/convert --limit=50 2>&1 >> $LOG_FILE # 检查是否成功（返回码 0 为成功） if [ $? -eq 0 ]; then echo "Convert success" >> $LOG_FILE else echo "Convert failed" >> $LOG_FILE fi

# 赋予执行权限并测试 sudo chmod +x /www/scripts/convert_docs.sh sudo -u www /www/scripts/convert_docs.sh # 手动执行一次，看日志是否生成

说明：timeout 300防止某个大文件转码卡死，拖垮整个队列；--limit=50限制单次处理 50 个文档，避免内存溢出；2>&1将错误也写入日志，方便排查。

5.2 配置 crontab 并验证执行权限

不要用 root 用户的 crontab，必须用www用户：

# 编辑 www 用户的 crontab sudo -u www crontab -e

添加以下两行（每 5 分钟检查一次待转码文档）：

# 每 5 分钟执行一次转码 */5 * * * * /www/scripts/convert_docs.sh # 每小时清理一次临时文件（防止 /www/sphinx_tmp 占满磁盘） 0 * * * * find /www/sphinx_tmp -type f -mmin +60 -delete

验证是否生效：

# 查看 www 用户的 crontab 是否加载 sudo -u www crontab -l # 查看最近 cron 日志（CentOS 7+） sudo tail -f /var/log/cron | grep convert_docs # 手动触发一次，看日志 sudo -u www /www/scripts/convert_docs.sh

5.3 文档转码全流程验证技巧

别等用户上传才测试，用系统自带的测试文档快速走通：

1. 后台【内容管理】→ 【文档发布】→ 上传一个test.pdf（小于 2MB）；
2. 观察【文档列表】中该文档状态是否从pending变为converted；
3. 若 10 分钟后仍是pending，立即检查：
   • ps aux | grep convert是否有进程在跑；
   • /www/wwwroot/wenku/runtime/logs/convert_*.log最后一行是否含Convert success；
   • mysql -u kiivo_app -p -D kiivo_wenku -e "SELECT status,convert_log FROM doc WHERE title='test.pdf';"看convert_log字段是否记录错误（如failed to execute ghostscript，说明没装ghostscript）；
4. 若convert_log显示gs: command not found，则需安装 Ghostscript：

   # CentOS 7 sudo yum install ghostscript -y # Ubuntu 20.04 sudo apt-get install ghostscript -y

6. 首次访问与功能闭环验证：从首页加载、搜索、登录、付费到下载，一条链路跑通才算真正装好

装完所有服务，不代表系统就 ready。必须模拟真实用户走一遍完整链路：打开首页 → 搜索文档 → 微信登录 → 付费下载 → 预览 H5。每一步的验证点我都列在下面，这是唯一能证明你没漏配任何环节的方法。

6.1 PC 站首页与搜索功能验证

访问https://www.wenku.example.com：

• ✅ 首页应正常加载，无 PHP 报错（查看浏览器 F12 → Console 是否有500请求）；
• ✅ 搜索框输入关键词（如“PHP 教程”），回车后跳转到/search?q=PHP+%E6%95%99%E7%A8%8B，页面显示“找到 X 篇文档”；
• ❌ 若返回空列表或 404，检查：
  • Sphinxsearchd是否在运行（sudo ps aux | grep searchd）；
  • common/config/main-local.php中sphinx配置的port=9312是否与searchd监听端口一致（sudo netstat -tuln | grep 9312）；
  • 数据库doc表中是否有status=converted的文档（SELECT COUNT(*) FROM doc WHERE status='converted';，至少为 1）。

6.2 微信登录与用户体系验证

点击首页右上角【登录】→ 【微信登录】：

• ✅ 跳转到微信授权页，同意后自动回到www.wenku.example.com，显示用户名；
• ✅ 后台【用户管理】中能看到新用户记录，auth_key字段不为空；
• ❌ 若白屏或报Invalid signature，检查：
  • 微信开放平台【公众号设置】→ 【JS 接口安全域名】是否添加www.wenku.example.com（注意：不是m.wenku.example.com）；
  • common/config/main-local.php中wechat配置的app_id和secret是否与公众号后台一致；
  • runtime/logs/app.log是否有WeChat\BasicService\ServerGuard::checkSignature相关错误。

6.3 文档付费与下载闭环验证

找一篇标价 1 元的文档（后台【文档管理】→ 编辑文档 → 设置价格）：

• ✅ 点击【立即下载】→ 跳转微信支付页 → 扫码付款成功 → 自动跳回文档详情页 → 出现【下载按钮】；
• ✅ 点击【下载按钮】，弹出下载对话框，文件名应为原始文档名（如test.pdf）；
• ❌ 若付款后无反应，检查：
  • api.wenku.example.com网站的 SSL 证书是否有效（Chrome 地址栏锁图标是否绿色）；
  • common/config/main-local.php中wechatPay的notify_url是否为https且可公网访问（用curl -I https://api.wenku.example.com/v1/pay/notify测试）；
  • 数据库pay_order表中该订单的status是否变为success，download_url字段是否生成（SELECT download_url FROM pay_order WHERE order_no='xxx';）。

6.4 H5 预览与 SEO 效果验证

点击一篇已转码的 PDF 文档：

• ✅ 页面加载出 H5 预览器，可缩放、翻页、文字可选；
• ✅ 查看网页源码（Ctrl+U），确认<title>标签含文档标题，<meta name="description">含文档摘要；
• ✅ 在 Google 或百度搜索site:www.wenku.example.com "文档标题关键词"，应能搜到该页面；
• ❌ 若预览器空白，检查：
  • /www/wwwroot/wenku/frontend/web/assets/目录下是否有sphinx生成的 HTML 文件（如doc_123.html）；
  • Nginx 配置中是否遗漏location ~ \.(html|htm)$ { add_header Content-Type text/html; }（宝塔默认有，但若手动改过可能删掉）。

从那以后我每次部署知沃文库，都强制走一遍这四步验证：首页 → 搜索 → 微信登录 → 付费下载。哪怕客户说“先上线再调”，我也坚持把这 15 分钟花完——因为 90% 的线上问题，其实就藏在这条链路的某个断点里，只是当时没暴露。漏掉 Sphinx 端口，搜索就废；OSS 权限错一位，文档就白传；微信回调少个s，用户永远登不上。这些不是玄学，是运维工程师用时间换来的条件反射。希望帮到你。

本文还有配套的精品资源，点击获取