TpEnhance 插件功能清单

TpEnhance 是一款 Typecho 功能增强套件，整合六大实用模块。全部模块的开关、配置与日常管理均整合在插件设置页内，以选项卡形式分组展示，互不干扰。

模块	核心功能
系统加速	头像国内源加速、正文静态库国内 CDN 替换、图片 CDN 图库（8 类图床 + 撰写页面板）
搜索优化	百度收录推送（独立开关）、五合一站点地图（独立开关）、SEO 增强、结构化数据（JSON-LD）、GEO（AI 收录优化）、GEO 自检
邮件推送	SMTP 评论通知（新评论通知作者 / 回复通知被回复者）、测试邮件、发送日志、自定义模板
登录限制	半小时失败次数限制、失败日志记录与清理
评论过滤	昵称 / 邮箱 / 网址 / IP / 敏感词 / 日文 / 长度等多维反垃圾策略
页面缓存	Redis / Memcached 页面加速、一键清空

一、系统加速模块

三类加速能力各自拥有独立开关，可任意组合，互不影响。

1.1 头像加速（开关）

加速头像源：Cravatar（推荐）、WeAvatar、极族、Loli 镜像四个国内源，另支持自定义源（模板占位符 {md5} / {size} / {rating} / {default}）。
QQ 头像特判（开关）：纯数字 @qq.com 邮箱自动显示对应 QQ 头像。
关闭开关后自动回退系统默认 Gravatar 官方源，主题无需修改。
与 Simple 3.0 主题（v3.0.5+）无缝接入，主题评论头像自动走加速通道。

1.2 静态库加速（开关）

开启后自动识别正文中引用的 jsDelivr / cdnjs / unpkg / code.jquery.com 四类公共库地址，替换为所选国内 CDN。
目标 CDN 库：Staticfile（七牛云）、BootCDN（Bootstrap 中国）、奇舞团 360 帕米图、ZStatic，另支持自定义 CDN（模板占位符 {lib} / {ver} / {file}）。
内置 19 个常用库白名单（jQuery、jQuery UI、Bootstrap、Popper、Font Awesome、Vue、Axios、Moment、ECharts、Swiper、Chart.js、highlight.js、clipboard.js、animate.css、Lodash、dayjs、three.js、D3、Leaflet），库名自动归一化（如 cdnjs 的 twitter-bootstrap → bootstrap）。
白名单外的 URL 一律保持原样，不做任何替换，避免错误改写。
文件名严格校验（拒绝路径穿越与非法字符），关闭开关后正文原样输出。

1.3 图片 CDN 与 CDN 图库（开关）

开启后后台「撰写文章 / 撰写页面」侧栏出现 CDN 图库面板，上传图片直接写入所选图床并返回外链；关闭则使用系统自带的文件上传管理。
8 类图床服务商：
- 国内大厂：阿里云 OSS、腾讯云 COS、七牛云 Kodo、又拍云 USS
- 国外大厂：Cloudflare R2、AWS S3、GitHub 仓库（支持自定义 API 域名，兼容 GitHub Enterprise，可配 jsDelivr / raw 回退）
- 自定义接口：PUT 二进制 / POST multipart 两种上传方式，自定义请求头、附加字段、响应地址（点路径取值）、访问域名与删除接口
图库面板功能：上传（点击 / 拖拽 / 多选）、改名、删除、复制外链、连通测试（一键上传测试图并自动清理）。
友好提示机制：服务商不支持删除时仅提示「已移出图库（云端文件需手动清理）」，不报错；上传失败（网络 / 凭证 / 超限）时提示服务商返回的具体原因。
安全限制：仅允许 jpg / png / gif / webp / svg / bmp / ico / avif 八类图片（按文件内容探测真实类型）；单文件 10MB 上限；重名文件自动加随机后缀；按年月子目录归档。

二、搜索优化模块

2.1 百度收录推送（独立开关）

独立开关：在搜索优化模块内单独控制百度推送功能的启停，关闭后 SEO 增强、结构化数据、GEO、站点地图等其它功能不受任何影响。
填入百度站长平台（搜索资源平台）的接口调用地址后，发布文章 / 页面时自动推送新链接。
支持手动分组批量推送：按「分组 URL 数」自动分组，逐组发送并查看结果。
推送日志（成功 / 失败、响应详情）完整记录，支持分页浏览。

2.2 站点地图（五合一，独立开关）

独立开关：关闭后全部站点地图地址返回 404，不再对外暴露；重新开启立即恢复，不影响搜索优化模块其它功能。
自动生成并按内容类型拆分：
- sitemap.xml —— 站点地图索引
- post_sitemap.xml —— 文章
- page_sitemap.xml —— 独立页面
- cate_sitemap.xml —— 分类
- tag_sitemap.xml —— 标签

后台设置页可直接点击访问各地图地址；站点地图附带 XSL 样式，浏览器可读。未开启伪静态时地址形如 /index.php/sitemap.xml。

2.3 SEO 增强（开关）

输出规范化的 description / keywords meta：
- 文章页：优先取自定义字段 ai_description → ai_summary → 正文自动摘要；关键词优先 ai_keywords → 文章标签。
- 首页：使用「首页描述 / 首页关键词」配置，留空回退系统站点描述。
- 列表页（分类 / 标签 / 搜索 / 归档）：自动生成页面摘要。
输出 Open Graph 全套标签（og:site_name / og:title / og:description / og:type / og:url）与 Twitter Card。
分享图优先取正文第一张图片，可通过「默认分享图」配置兜底图。
启用后自动接管前台 head 输出，避免与系统默认 meta 重复。

2.4 结构化数据 JSON-LD（开关）

输出 Schema.org 结构化数据，帮助搜索引擎理解页面：
- WebSite（全站，含站点描述）
- BlogPosting（文章页：标题、发布 / 修改时间、作者、发布者、语言）
- BreadcrumbList（文章页面包屑：首页 → 分类 → 文章）

2.5 GEO 模块（AI 收录优化，开关）

面向 AI 搜索 / 大模型引擎优化，robots meta 放宽快照限制：
index,follow,max-snippet:-1,max-image-preview:large,max-video-preview:-1
配套一键 GEO 自检：在设置页点击按钮即可实抓首页逐项检测（模块开关、robots meta 放宽状态），输出结论（要求管理员登录）。
与主题的「文章页顶部摘要卡片」显示开关相互独立、互不影响。

三、邮件推送模块（SMTP）

3.1 通知机制

新评论 → 邮件通知文章作者（作者本人评论不重复通知）。
评论被回复 → 邮件通知被回复的评论者（自己回复自己不发送）。
两个场景均有独立开关，可分别启用 / 关闭。

3.2 SMTP 配置

支持服务器地址、端口、加密方式（SSL / TLS / 不加密）、认证开关、发件邮箱、授权码密码、发件人名称。
授权码密码留空保存时自动保留原值，无需重复填写。
发件人名称留空时使用站点标题。
内置 PHPMailer 6.9.1（独立命名空间），兼容 PHP 8.3+，连接超时 8 秒不阻塞评论流程。

3.3 测试邮件

设置页填入收件邮箱，一键发送测试邮件验证配置正确性；发送结果即时提示并记录日志。

3.4 邮件模板

内置两套青绿色系 HTML 模板（作者通知 / 回复通知）。
支持在设置页粘贴自定义 HTML 模板（多行文本框），可用变量：

模板	变量
作者通知	`{blogUrl}` `{blogName}` `{author}` `{permalink}` `{title}` `{text}` `{ip}`
回复通知	以上全部，另含 `{replyAuthor}` `{replyText}` `{commentUrl}`

3.5 发送日志

全部发送记录（收件人、主题、结果、错误信息、时间）独立分页展示，与搜索优化推送日志分表显示、互不混淆。

四、登录限制模块

半小时内同一账号登录失败达到设定次数后，暂时拒绝新的登录尝试，防暴力破解。
登录失败日志完整记录（用户名、密码、IP、时间），支持清空与勾选删除，独立分页。

五、评论过滤模块（智能反垃圾）

对提交中的评论执行多维检查，命中规则可配置「标记待审 / 直接拒绝」等处理方式：

检查维度	说明
游客评论指定页面	指定 slug 的独立页面禁止游客评论
内容含文章标题	常见于采集垃圾评论
IP / 邮箱 / 网址 / 昵称黑名单	换行分隔的屏蔽词列表
日文内容 / 日文昵称	拦截日文垃圾评论
昵称长度 / 昵称为网址	拦截机器特征昵称
非中文评论 / 内容长度	按需启用
禁止词汇 / 敏感词汇	命中后按配置处理

六、页面缓存模块

支持 Redis 与 Memcached 两种驱动（自动检测扩展）。
缓存页面 HTML，命中后直接返回，显著降低动态请求压力。
发布 / 编辑内容、评论变动等事件自动精准清缓存；设置页支持一键全站清空。

TpEnhance 插件使用说明

一、环境要求

项目	要求
Typecho	1.3 及以上
PHP	8.3 及以上（需 `pdo_mysql` / `pdo_sqlite` 等常规扩展；邮件使用 SSL 时需 `openssl`；CDN 图库上传需 `curl` 扩展）
主题配合	Simple 3.0 主题（v3.0.5 及以上）已在 `<head>` 内置接入点并接入头像加速，安装即生效；其他主题需按「七、其他主题接入」手动接入

二、安装与启用

将 TpEnhance 文件夹上传（或解压）至站点目录 usr/plugins/，保持目录名大小写为 TpEnhance（加速模块的驱动类按原始大小写加载，切勿改成全小写）。
进入后台 → 控制台 → 插件，找到 TpEnhance，点击「启用」。
启用成功后点击「设置」，进入插件设置页。设置页顶部为模块选项卡：
```
系统加速 | 搜索优化 | 邮件推送 | 登录限制 | 评论过滤 | 页面缓存
```
点击选项卡切换模块；各模块的开关、配置项、状态卡片与日志均在对应页签内。修改任意开关后，请点击页面底部「保存设置」使配置生效。
每个模块都有独立的「启用 / 关闭」总开关，关闭后该模块所有功能停止工作，但不影响其他模块；模块内部还有细分开关（如百度推送、站点地图、头像、静态库、图片 CDN），可按需精调。
配置保护：禁用插件时自动备份全部配置，重新启用时自动恢复，无需重新填写；升级覆盖插件目录也不会丢失配置。

三、系统加速模块配置

打开「系统加速」选项卡。设置页顶部状态卡实时显示三类加速能力的开关状态与图库文件统计；「图床连通测试」卡可一键验证图床配置（上传一张测试图后自动删除）。

3.1 头像加速

打开「【头像加速】是否使用加速头像源」开关。
「头像源」选择：Cravatar（推荐） / WeAvatar / 极族 / Loli 镜像；也可选「自定义源」，并填写地址模板，可用占位符：
- {md5} —— 邮箱 MD5 值
- {size} —— 头像尺寸
- {rating} —— 分级
- {default} —— 默认头像
「QQ 号邮箱使用 QQ 头像」开关：开启后 数字@qq.com 形式的邮箱自动显示 QQ 头像。
关闭此开关后自动回退系统默认 Gravatar 官方源（国内访问可能较慢）。

3.2 静态库加速

打开「【静态库加速】是否调用国内公共 CDN 库」开关。
「公共 CDN 库」选择：Staticfile（七牛云） / BootCDN / 奇舞团 360 帕米图 / ZStatic；也可选「自定义 CDN」并填写模板，占位符：{lib}（库名）、{ver}（版本）、{file}（文件名）。
保存后，正文中引用的 jsDelivr / cdnjs / unpkg / code.jquery.com 公共库地址会自动替换为所选国内 CDN（仅限 jQuery、Bootstrap、Vue、ECharts 等 19 个内置白名单库；白名单外的链接一律不动）。

3.3 图片 CDN 与 CDN 图库

打开「【图片 CDN】是否启用图库」开关。
「图床服务商」选择并填写对应凭证：

服务商	需填写的关键参数
阿里云 OSS（国内）	Bucket 外网域名、AccessKeyId、AccessKeySecret；可选自定义访问域名（绑定 CDN 后使用）
腾讯云 COS（国内）	Bucket 访问域名、SecretId、SecretKey；可选自定义访问域名
七牛云 Kodo（国内）	Bucket 名、AK、SK、绑定域名；空间地区不同时可选上传加速地址
又拍云 USS（国内）	Bucket 名、操作员、操作员密码、绑定域名
Cloudflare R2（国外）	Endpoint、Bucket、AK、SK；区域固定 auto
AWS S3（国外）	Endpoint、Bucket、AK、SK、Region
GitHub 仓库（国外）	Token、仓库（owner/repo）、分支、存放目录；API 域名可自定义（兼容企业版）；可自动拼接 jsDelivr / raw 外链
自定义接口	上传 URL（`{key}` 占位）、请求方式（PUT / POST）、文件字段名、请求头、附加字段、响应取值路径、访问域名、删除 URL 与删除请求头

开启后进入「撰写文章 / 撰写页面」，右侧栏出现 CDN 图库面板：
- 上传：点击按钮选择文件，或直接把图片拖入面板；支持多选队列上传，逐个显示进度与结果。
- 改名：仅修改图库中的显示名称，不影响云端文件与外链。
- 删除：同时删除云端文件与图库记录；若所选服务商不支持删除接口（如只读图床），会提示「已移出图库，云端文件需手动清理」，不会报错。
- 复制：一键复制图片外链，可直接粘贴到编辑器。
关闭此开关后，撰写页面板消失，上传图片走系统自带的文件上传管理功能；已上传的图库记录与云端文件均保留。
图床连通测试：在设置页「图床连通测试」卡点击按钮，自动上传一张 1×1 测试图并立即清理，成功即提示「连接成功」；失败时提示服务商返回的具体原因（401 凭证错误、413 超限、429 频率限制等均已汉化）。

四、搜索优化模块配置

打开「搜索优化」选项卡：

4.1 百度收录推送（独立开关）

「百度收录推送」开关：默认启用；关闭后发布文章不再推送百度，且手动批量推送入口隐藏并提示，搜索优化模块的其它功能（SEO 增强、结构化数据、GEO、站点地图）不受影响。
登录百度站长平台 - 搜索资源平台 → 普通收录 → API 推送，复制接口调用地址。
粘贴到「【百度收录】接口调用地址」并保存。此后发布文章 / 页面会自动推送。
批量推送：在「百度收录推送状态」卡片中查看全站可推送链接总数与分组数，选择组号点击「发送分组 URL」。

4.2 站点地图（独立开关）

「站点地图」开关：默认启用；关闭后全部 sitemap 地址返回 404，开启后立即恢复。
启用后无需配置，直接访问：
- https://你的域名/sitemap.xml（未开伪静态则前面加 /index.php）
- post_sitemap.xml / page_sitemap.xml / cate_sitemap.xml / tag_sitemap.xml
建议将 sitemap.xml 提交至百度、必应、Google 等站长平台。

4.3 SEO 增强（开关：启用 / 关闭）

「首页描述」「首页关键词」：留空时首页描述回退使用系统设置中的站点描述；关键词留空则不输出首页 keywords。
「默认分享图」：填写一张图片完整地址，页面无图时作为 Open Graph / Twitter Card 的兜底分享图；留空则不输出。

4.4 结构化数据（JSON-LD）（开关：启用 / 关闭）

启用后自动输出 WebSite / BlogPosting / BreadcrumbList 结构化数据，无需配置。可用 Google 富媒体测试工具验证。

4.5 GEO 模块（AI 收录优化）（开关：启用 / 关闭）

启用后首页与文章页 robots meta 输出：index,follow,max-snippet:-1,max-image-preview:large,max-video-preview:-1。
点击「运行 GEO 自检」按钮，系统实抓首页并逐项检测（模块开关、robots 放宽状态），输出结论（需管理员登录本站）。
主题侧的「文章页顶部摘要卡片」（Simple 主题外观设置中）显示开关与本模块独立，可自由组合。

兼容说明：Simple 3.0 主题 v3.0.4 起，原主题内的「SEO 增强 / 结构化数据 / GEO 模块」设置项已迁移至本插件；主题「外观设置」仅保留「文章页顶部摘要卡片」。由旧版升级时，请在本插件中重新确认各项开关。

五、邮件推送模块配置

打开「邮件推送」选项卡：

5.1 获取 SMTP 参数

以常用邮箱为例（需在邮箱服务商设置中开启 SMTP 并生成授权码，授权码即「SMTP 密码」）：

服务商	SMTP 服务器	端口	加密
QQ 邮箱	smtp.qq.com	465	SSL
163 邮箱	smtp.163.com	465	SSL
腾讯企业邮	smtp.exmail.qq.com	465	SSL
Gmail	smtp.gmail.com	465 / 587	SSL / TLS
阿里企业邮	smtp.qiye.aliyun.com	465	SSL

5.2 填写配置

「SMTP 服务器地址」「SMTP 端口」「加密方式」「SMTP 认证」按上表填写。
「发件邮箱」填写用于登录 SMTP 的邮箱账号；「SMTP 密码 / 授权码」填写服务商生成的授权码（已填写后留空保存不会丢失，保留原值）。
「发件人名称」留空则使用站点标题。
保存设置后，状态卡片会显示当前配置摘要（服务器、加密方式、发件人）。

5.3 通知开关

「新评论通知文章作者」：文章收到新评论时邮件通知作者；作者本人发表评论不重复通知。
「回复通知被回复者」：评论被回复时邮件通知被回复的评论者；自己回复自己不发送。

5.4 发送测试邮件

在「发送测试邮件」卡片填入你常用的邮箱 → 点击按钮 → 出现「测试邮件已发送」提示即配置正确。请到收件箱（注意垃圾箱）确认。

5.5 自定义邮件模板（可选）

两套内置模板为青绿色系 HTML。需要自定义时，把完整 HTML 粘贴到对应多行文本框，可用变量见「TpEnhance-功能清单.md」第 3.4 节。留空即使用内置模板。

5.6 邮件推送日志

所有发送记录（含测试邮件）在「邮件推送日志」卡片分页展示；失败记录附带错误信息，便于排查授权码错误、连接超时等问题。

六、登录限制 / 评论过滤 / 页面缓存

登录限制：「半小时内允许尝试登录失败的次数」按需填写（默认 15）；日志卡片支持清空与勾选删除。
评论过滤：各检查维度默认关闭（none），按需选择处理动作并填写对应词表；保存即生效。
页面缓存：选择 Redis / Memcached 驱动并填写连接参数；「禁用时是否删除数据表」决定禁用插件时是否保留日志表。缓存异常时点击「清空页面缓存」。

七、其他主题接入（非 Simple 主题）

在主题的 header.php 的 <head> 内（系统 $this->header() 调用之后）加入：

<?php \Typecho\Plugin::factory('TpEnhanceHead')->call('render', $this); ?>

建议同时抑制系统默认的重复 meta（在 $this->header(...) 参数中追加 description=&keywords=&social=）：

<?php $this->header('description=&keywords=&generator=&template=&pingback=&wlw=&xmlrpc=&rss1=&atom=&social='); ?>

评论头像加速（可选接入）：在主题输出头像处使用：

$url = '';
if (class_exists('\TypechoPlugin\TpEnhance\Accel')) {
    $url = \TypechoPlugin\TpEnhance\Accel::avatarUrl($mail, $size, 'G', 'mp', false);
}
// $url 非空用加速地址，为空回退主题原有头像逻辑

未启用插件时，以上调用零输出、零开销。

八、常见问题

Q1：测试邮件提示认证失败（Could not authenticate）？
授权码错误或未开启 SMTP 服务。请到邮箱服务商设置中重新生成授权码，注意区分「登录密码」与「授权码」。

Q2：评论提交时页面变慢？
发信为同步发送（超时 8 秒），SMTP 服务商响应慢时会稍有等待；确认网络与服务器端口后即可恢复正常。

Q3：前台没有 SEO meta 输出？
依次检查：① 搜索优化模块总开关是否开启；② 「SEO 增强」子开关是否启用；③ 主题 <head> 中是否有 TpEnhanceHead 接入调用（Simple 3.0 v3.0.4+ 已内置）。

Q4：sitemap.xml 404？
① 检查「站点地图」独立开关是否开启；② 未开启伪静态时请访问 /index.php/sitemap.xml；③ 或在后台「设置 - 永久链接」开启伪静态后使用根路径。

Q5：禁用插件会丢数据吗？
禁用时可分别选择是否保留「推送 / 邮件日志表」与「登录日志表」，默认保留；插件配置（全部模块设置）在禁用前自动备份，重新启用时自动恢复，不会丢失。

Q6：图库上传失败提示「拒绝访问」？
检查图床凭证（AK/SK 或 Token）是否正确、Bucket 是否有写权限；GitHub 方式需 Token 具有 repo 写权限。上传失败时面板会显示服务商返回的具体原因。

Q7：图库删除时提示「云端文件需手动清理」？
当前图床服务商未提供删除接口（或自定义接口未填写删除 URL），系统仅移除图库记录，云端文件不会报错也不会被误删；可填写删除接口后恢复自动删除。

Q8：静态库替换后有些链接没变？
只有内置白名单内的 19 个公共库会被替换；白名单外的库（或非四类来源站点）保持原样，属于保护机制。

Q9：关闭图片 CDN 图库后图片去哪了？
面板消失后撰写页走系统自带上传管理；已上传到图床的文件与外链不受影响，可重新开启图库面板查看。

九、升级与卸载

升级：备份 usr/plugins/TpEnhance/ 目录 → 上传新版覆盖 → 配置自动保留（无需重新保存）。
卸载：后台禁用（配置自动备份，按需选择是否删除数据表）→ 删除插件目录；重新上传启用后配置自动恢复。

TpEnhance v1.2 · 与 Simple 3.0 主题配套使用，效果更佳！

文章目录

TpEnhance 插件功能清单
TpEnhance 插件使用说明

Typecho TpEnhance插件，一款 Typecho 功能增强套件