V3 主题功能配置教程（宝塔面板）

一、媒体自动转码功能

功能说明

上传 mp4 视频自动生成 webm 格式，上传 mp3 音频自动生成 ogg 格式。webm/ogg 格式体积更小、兼容性更好，可实现浏览器自动选择最优格式播放，加速页面打开。

配置步骤

第一步：安装 FFmpeg

  1. 登录宝塔面板
  2. 点击左侧菜单「软件商店」
  3. 在搜索框输入「FFmpeg」
  4. 找到后点击「安装」

联想截图_20260723201839.jpg

手动安装方式（SSH）：

# CentOS 系统
yum install -y ffmpeg

# Ubuntu/Debian 系统
apt-get update
apt-get install -y ffmpeg

第二步：启用 PHP exec 函数

  1. 点击左侧菜单「软件商店」
  2. 找到已安装的 PHP 版本，点击「设置」
  3. 在弹出的窗口中选择「禁用函数」
  4. 在禁用函数列表中找到「exec」，点击删除按钮移除它
  5. 点击「保存」

联想截图_20260723201839.jpg

第三步：修改 PHP 运行模式（可选）

如果转码速度较慢，可以修改 PHP 运行模式：

  1. 点击左侧菜单「网站」
  2. 找到你的网站，点击「设置」
  3. 选择「PHP 版本」
  4. 将运行模式改为「FastCGI」或「PHP-FPM」
  5. 点击「保存」

第四步：后台开关控制

在 Typecho 后台「外观」→「设置外观」→「内容设置」中，可以找到「媒体自动转码」开关：

  • 开启：上传 mp4/mp3 时自动触发转码
  • 关闭：不进行转码，仅保留原始文件

测试转码功能

  1. 登录 Typecho 后台
  2. 新建或编辑一篇文章
  3. 上传一个 mp4 视频或 mp3 音频文件
  4. 发布文章后访问前台查看效果

测试方法：

  • 上传文件后，等待 1-2 分钟（视频较大时需要更长时间）
  • 打开文章页面，按 F12 打开开发者工具
  • 查看 Network 面板，应该能看到 webm/ogg 文件的请求

常见问题

Q1：上传文件后没有生成 webm/ogg 文件？

  • 确认 FFmpeg 已安装（ffmpeg -version）
  • 确认 exec 已从禁用函数列表中移除
  • 将 PHP 运行模式改为「FastCGI」或「PHP-FPM」

Q2：转码速度很慢？

  • 升级服务器配置（增加 CPU 核心数）
  • 限制上传文件大小

二、友情链接自动生成功能

功能说明

自动从评论中提取访客填写的网址，通过 Puppeteer 截图生成生动的友情链接卡片。完全自动化，无需人工干预。

工作流程：

  1. 从评论数据库中提取所有填写了网址的访客
  2. 验证网址有效性（HTTP 200 OK）
  3. 使用 Puppeteer 对有效网址进行截图
  4. 按评论数从高到低排序
  5. 生成友链缓存文件，供前台展示

配置步骤

第一步：安装 Node.js 和 Puppeteer

  1. 安装 Node.js：

    # 宝塔面板方式：软件商店搜索 Node.js 安装
# 或手动安装：
curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
apt-get install -y nodejs

  2. 安装 Puppeteer（推荐使用国内源）：

    方法一：使用 cnpm（推荐，国内服务器）

    # 安装 cnpm
sudo npm install -g cnpm --registry=https://registry.npmmirror.com

# 使用 cnpm 安装 puppeteer
cd /www/wwwroot/你的域名/usr/themes/V3/assets/scripts
npm init -y
cnpm install puppeteer --save

    方法二：使用 npm + 国内源

    cd /www/wwwroot/你的域名/usr/themes/V3/assets/scripts
npm init -y
npm install puppeteer --save --registry=https://registry.npmmirror.com

    方法三：使用环境变量指定国内源

    cd /www/wwwroot/你的域名/usr/themes/V3/assets/scripts
npm init -y
PUPPETEER_DOWNLOAD_HOST=https://registry.npmmirror.com npm install puppeteer --save

    注意： Puppeteer 会自动下载 Chromium，可能需要几分钟时间。使用国内源可以加速下载。

  3. 验证安装：

    node -v    # 应该显示 Node.js 版本号
node -e "const puppeteer = require('puppeteer'); console.log('Puppeteer 安装成功');"

第二步：创建友链页面

  1. 登录 Typecho 后台
  2. 点击「管理」→「独立页面」→「新建页面」
  3. 填写标题：友情链接
  4. 在右侧「自定义模板」中选择「links.php」
  5. 点击「发布」

第三步：手动运行构建脚本

方法一：SSH 命令行

cd /www/wwwroot/你的域名/usr/themes/V3/assets/scripts
php build_links.php

方法二：浏览器访问
在浏览器中访问：

https://你的域名/usr/themes/V3/assets/scripts/build_links.php

输出示例：

友链数据构建完成
共找到 12 个有效友链
缓存文件已保存: /www/wwwroot/xxx/usr/themes/V3/assets/cache/links_cache.json
更新时间: 2026-07-23 10:30:00

第四步：设置定时任务（每天自动重建）

  1. 登录宝塔面板
  2. 点击左侧菜单「计划任务」
  3. 点击「添加任务」

  4. 填写任务信息：

    • 任务名称： 每日更新友情链接
    • 执行周期： 每天
    • 执行时间： 02:00（凌晨 2 点，服务器负载低时）
    • 任务类型： Shell 脚本

    • 脚本内容：

      cd /www/wwwroot/你的域名/usr/themes/V3/assets/scripts && php build_links.php >> /www/wwwroot/你的域名/logs/links_cron.log 2>&1
  5. 点击「保存」

友链页面效果

友链页面展示为三列卡片网格，每个卡片包含：

  • 网站截图（Puppeteer 生成）
  • 网站头像（Gravatar）或首字母占位符
  • 网站名称和 URL
  • 评论次数

响应式适配：

  • 桌面端：3 列布局
  • 平板端：2 列布局
  • 移动端：1 列布局

技术说明

文件结构

assets/
├── cache/
│   └── links_cache.json              # 友链缓存文件
├── screenshots/                      # 网站截图目录
│   ├── xxx_desktop.jpg               # 桌面端截图（1440×900）
│   └── xxx_mobile.jpg                # 移动端截图（390×844）
└── scripts/
    ├── build_links.php               # 友链构建主脚本
    ├── screenshot.js                 # Puppeteer 双模式截图脚本
    └── package.json                  # Node.js 依赖配置

脚本逻辑

build_links.php：

  1. 查询 Typecho 评论表，按 URL 分组统计评论数
  2. 验证每个 URL 的 HTTP 状态码（必须为 200）
  3. 验证 Content-Type 是否为 text/html（排除图片、文件等）
  4. 调用 Puppeteer 脚本生成桌面端和移动端双截图
  5. 按评论数从高到低排序
  6. 将结果保存为 JSON 缓存文件

screenshot.js：

  1. 使用 Puppeteer 启动无头 Chrome（配置防沙箱参数）
  2. 桌面端模式：设置视口 1440×900，访问 URL，等待 domcontentloaded
  3. 截取桌面端截图，保存为 JPEG 格式（质量 85）
  4. 移动端模式：设置视口 390×844，标记 isMobile: true，重新访问 URL
  5. 截取移动端截图，保存为 JPEG 格式（质量 85）
  6. 关闭浏览器

双截图适配机制

  • 使用 HTML <picture> 元素实现设备适配
  • 桌面端（>768px）加载 xxx_desktop.jpg
  • 移动端（≤768px）加载 xxx_mobile.jpg
  • 即使移动端截图失败，仍可回退显示桌面端截图

缓存机制

  • 截图文件以 URL 的 MD5 值 + _desktop/_mobile 后缀命名
  • 已存在的截图不会重新生成，只更新不存在的
  • JSON 缓存文件包含所有友链数据，前台直接读取
  • 定时任务每天重建，确保数据最新

常见问题

Q1：友链页面显示空白？

  • 确认已运行过 build_links.php 脚本
  • 检查缓存文件是否生成：assets/cache/links_cache.json
  • 确认 PHP 有权限写入 assets/cache/ 和 assets/screenshots/ 目录

Q2：Puppeteer 截图失败？

  • 确认 Node.js 和 Puppeteer 已正确安装
  • 检查服务器是否有足够内存（建议至少 1GB）

  • 尝试手动运行截图脚本测试：

    node screenshot.js https://example.com /tmp/test.png

Q3：截图很慢？

  • 正常现象，每个网站需要加载完整页面
  • 建议在凌晨定时执行，避免影响白天访问

Q4：如何添加手动友链？

  • 当前版本仅支持自动从评论提取
  • 如果需要手动添加，可以直接编辑 links_cache.json 文件

注意事项

  1. 服务器资源： Puppeteer 截图会消耗较多 CPU 和内存，建议在低峰期执行
  2. 存储空间： 每个截图约 50-200KB，大量友链会占用较多空间
  3. 隐私保护： 仅抓取公开网站，不抓取需要登录的页面
  4. 网络超时： 每个网站截图超时时间为 30 秒，超时会跳过

三、技术说明

转码参数说明

  • VP9 编码：Google 开发的开源视频编码，压缩率高，质量好
  • CRF 30：恒定质量模式，值越小质量越好，体积越大
  • libopus：WebM 音频编码，音质好，体积小
  • libvorbis：OGG 音频编码，开源免费

文件命名规则

  • video.mp4 → video.webm
  • audio.mp3 → audio.ogg
  • 截图文件：md5(url).png

版本：V3 主题 1.3.0
日期：2026年7月23日