Aurora-自己写的一套wordpress博客主题

hlx

Aurora
产品说明书
功能清单 · 运行环境 · 安装部署 · 后台配置
Aurora 是一套原创的苹果风格 WordPress 内容与社区主题，
配 allin-pro-core 业务插件，把会员、支付、积分、商品与 AI 能力接进来。
────────────────────────────────────────
项目        版本 / 说明
主题        Aurora 2.5.15（aurora-theme-2.5.15.zip）
插件        allin-pro-core 0.4.0
运行环境        WordPress 7.1 · PHP 8.3 · MariaDB 10.11 · Nginx 1.24
文档日期        2026 年 10 月
适用对象        站长、运维、二次开发者

本文档中的界面截图均取自实际运行的站点。涉及密钥、商户号、证书的部分只说明填写位置，不展示具体值。


目录
1    产品概述
2    功能总览
3    前台功能详解
4    后台设置
5    业务插件 allin-pro-core
6    技术架构与数据模型
7    运行环境
8    安装教程
9    升级、备份与排错
10    质量与测试
11    常见问题
12    版本记录


1  产品概述
Aurora 是一个可以独立运营的建站系统：主题负责界面、响应式、深浅色、SEO 与页面交互，业务能力（短信/社交登录、支付、余额、商品订单、投稿、会员）由 allin-pro-core 插件提供。两者分开的好处是——换主题不会丢业务数据，改界面不必动支付逻辑。
1.1  定位
· 内容站：文章、分类、专题、图库、幻灯片、相关推荐，面向长文阅读排版。
· 轻社区：板块（board）+ 问答（QA）两套内容形态，支持置顶、精华、投票与采纳。
· 会员制：VIP 等级、单篇购买、卡密兑换、余额与充值，一套价格体系覆盖三种变现。
· 轻电商：商品（规格 / 库存 / 限购 / 优惠码）+ 购物车 + 六通道支付回调。
· AI 增强：文章摘要、站内问答、后台写作助手，全部走同一个 OpenAI 兼容接口。
1.2  设计语言
整体按苹果官网的语言做：系统字体（-apple-system / PingFang SC）、大圆角卡片、毛玻璃浮层、克制的阴影与系统级缓动曲线。所有浮层遵循同一条规则——同时具备填充、高斯模糊与发丝描边，缺一项在浅色背景上就会「糊成一片」。
配色提供四套模式：跟随系统、浅色、深色、Spotify（深底 + 绿色强调）。切换结果存在浏览器 localStorage（键名 aurora-theme），通过  生效，首屏不闪白。
1.3  技术架构

  请求链路：反向代理 → WordPress → 主题（UI）+ 插件（能力） → 数据库与外部服务
静态资源（CSS/JS/图片/字体）由反向代理直接输出并开启 gzip；动态请求交给 PHP-FPM。主题与插件都只通过 WordPress 提供的 API 读写数据，不直接连库，迁移时换域名、换服务器都不需要改代码。


2  功能总览
下表是全部功能模块与入口，后面章节按前台、后台、插件三块展开。
模块        能力        入口 / 位置
首页        幻灯片、区块排序、卡片列表、分页        首页
幻灯片        自动 / 编号 / 手写三种来源，最多 8 张        后台 → 首页幻灯片
板块        板块列表、板块帖、置顶与精华        /boards、/board/
问答        提问、回答、投票、采纳最佳答案        问答型板块
图库        独立素材池、瀑布网格、灯箱        /gallery
搜索        AJAX 即时搜索，热词只取本站标签        导航栏搜索
文章        目录、AI 摘要、评分、打赏、付费墙        文章页
用户中心        资料、文章、订单、积分、消息、下载        /user
会员        VIP 等级与价格、权益对照        /vip
积分        签到、评论奖励、消费返分、会员加成        用户中心
商品        规格 / 库存 / 限购 / 优惠码 / 结算        /product、/cart
支付        六通道：微信、支付宝、PayJS、迅虎、易支付、码支付        结算页 / 充值
投稿        前台投稿、等级门槛、审核状态        /submit
写作        前台编辑器、45 秒自动保存        /write
导航        网址导航、自动抓取站点图标        /nav
热点        热榜聚合、首页卡片、文章侧栏        /hot
AI        摘要、问本站、后台写作助手        文章页、/ai-ask、编辑器
通知        站内铃铛、事件订阅、邮件通知        导航栏 / 后台
PWA        清单、离线缓存、加到主屏        后台 → 离线与安装
桌宠        页脚看板娘（手机端隐藏）        页脚右侧
SEO        标题模板、描述、OG、结构化数据、站点地图        全站


3  前台功能详解
3.1  首页与幻灯片

首页首屏：幻灯片、公告条与分类入口
首页由若干区块组成，顺序可以在「后台 → 首页区块」里调整。幻灯片支持三种内容来源：
· 自动：先取置顶文章，再补最新文章，只收有特色图的；  适合日常更新
· 按文章编号：填 10, 7, 12，顺序即播放顺序，自动去重，最多 8 篇；  适合人工精选
· 手写一组：一行一张，竖线分隔「图片 | 标题 | 链接 | 描述」；  适合专题活动
编号模式下，输入框下方会实时列出每一条编号解析到的文章标题与编辑链接，找不到的编号标红，未发布或没有图的会注明「会被跳过」——填错当场就能看见。选中的文章优先用特色图，没有特色图时自动取正文第一张图。

3.2  板块与问答

板块列表：封面、帖子数、简介
板块是基于分类法 aurora_board 的内容聚合。每个板块可以标记置顶（_aurora_pinned）与精华（_aurora_featured），板块页会优先展示；首页「最新内容」只放纯文章，不混入板块帖，避免社区内容冲掉文章流。
把板块类型设为问答（_board_type = qa）后，帖子变成问题：回答就是评论，可以点赞/点踩（一人一票，投票记在 _qa_up / _qa_down / _qa_vote_），提问者可以采纳一个最佳答案，采纳后置顶显示。
3.3  图库
  图库：独立素材池，瀑布网格 + 灯箱
图库与文章配图是两个池子：图库只展示在媒体库里勾选了「加入图库」的附件（_aurora_gallery = 1），文章里的插图不会混进来。这样图库的排版不会被长图、示意图打断，文章也不会因为图库的裁切规则变形。
3.4  搜索与站内问答  搜索结果页：命中标题高亮、分类筛选、分页
搜索框支持即时联想（AJAX），回车进入结果页。热门搜索词只取本站的标签，不引外部热词——站点越小，这越重要，否则会出现「热词全是别人的」。

3.6  用户中心
用户中心：等级、积分、统计与功能入口
用户中心聚合了个人资料、我的文章、订单、积分流水、下载记录、站内消息与投稿状态。前台注册可以直接开放，也可以关掉只留登录；登录支持账号密码、短信验证码与社交账号。
3.7  会员与付费
会员中心：等级价格与权益对照
会员等级支持按月定价、权益对照、会员免费读单篇付费内容。三种变现方式可以并存：
· 订阅：按月付费的 VIP 等级；
· 单篇：指定文章单独标价，购买后可读 N 天（天数可配）；
· 卡密：后台生成卡密，用户在前台兑换，兑换尝试有每小时的次数上限。
3.8  商品与结算
商品页：规格、库存、限购、优惠码与结算入口
商品支持多规格（尺寸 / 颜色等组合各自定价与库存）、库存扣减、限购（按已支付订单 + 购物车数量合计）、优惠码与运费说明。结算页价格一律以服务端计算为准，前端只做展示——任何价格、档位都不从浏览器取值。

3.9  投稿与写作

前台投稿：栏目、标题、正文与提交说明
投稿页可以设定最低等级与提交后的状态（待审 / 直接发布）。提交后进入后台审核队列，通过即发布，退回会带上理由。

前台写作：富文本工具栏、分类标签、45 秒自动保存
写作页是前台编辑器：标题、正文、分类、标签，支持加粗、引用、代码、列表、链接与图片，每 45 秒自动保存草稿，也能用快捷键保存或提交审核。
3.10  网址导航与热点

网址导航：分组卡片、自动抓取的站点图标
导航页按分组陈列外链，保存时自动抓取站点 favicon 并本地缓存，避免第三方图床挂掉后一片空白；每行列数可配，首页可以只放一个入口。

3.11  深色模式、响应式与 PWA

深色模式：背景、卡片、文字与强调色整体切换
深浅色不是简单反色：卡片、描边、阴影、图表与代码块都有各自的深色取值，浮层在深色下会自动降低透明度并加深边框，保证「玻璃」仍然可读。
手机端首页：单列卡片、底部导航栏
手机端板块页：底部 Tab 导航
响应式按 1024 / 768 / 640 三个断点收敛：桌面三栏 → 平板两栏 → 手机单列，手机端启用底部导航栏，页脚桌宠在 640px 以下整块隐藏，图片懒加载，不再下载。
PWA 提供 manifest 与 Service Worker：加到主屏后独立窗口打开，已访问页面可离线查看。注意 Service Worker 只在 HTTPS（或 localhost）下生效，HTTP 访问时浏览器直接忽略，不影响正常浏览；后台、登录页与 AJAX 请求永远不走缓存。

4  后台设置
所有主题设置集中在「Aurora 主题 → 主题设置」，共 20 个标签页，保存后立即生效。每个标签页是一个表单，保存只作用于当前页，不会把别的页清空。

布局        首页列表样式、分页方式、文章页隐藏侧栏、文章目录、移动端底部导航
会员与付费        VIP 等级、付费墙、前台注册、频率限制、支付方式开关、价格与免费读规则
微信支付        商户号、AppID、证书序列号、APIv3 密钥、商户私钥、回调地址
首页幻灯片        启用、内容来源（编号/自动/手写）、图片列表、文章编号、张数、自动播放、间隔
首页区块        区块顺序（拖不动就填序号）
热点资讯        数据源、缓存时长、首页卡片、文章侧栏
网址导航        每行列数、自动抓图标、首页入口
巨型菜单        启用、子项达到几项时升级为巨型面板
打赏        开关、可选金额
评分与订阅        文章评分、邮件订阅
公告与页脚        顶部公告文字与链接、版权文字、ICP 备案号
卡密        每小时兑换尝试上限
下载        用户中心下载记录、下载区提示文字
站内通知        开关、铃铛位置、订阅事件、保留条数
邮件通知        SMTP 服务器、端口、加密方式、账号、密码、发件人
离线与安装        PWA 离线缓存


5  业务插件 allin-pro-core
插件承担「账号 + 钱」相关的部分，主题只负责展示。插件升级不会影响主题样式，反之亦然。
模块        能力        说明
短信登录        手机号 + 验证码登录/注册        未配置服务商时走沙箱适配器，验证码只写日志
社交登录        QQ、微博、微信、GitHub        OAuth 授权回调统一入口，缺密钥降级沙箱
支付适配器        微信、支付宝、PayJS、迅虎、易支付、码支付        六通道统一接口：下单、查询、验签、解析、退款
订单        创建、状态流转、回调验签、幂等        回调重复推送只处理一次
余额账户        余额、流水、扣款与退款        所有余额变动都有流水，可追溯到订单
充值        固定档位 + 自定义金额        价格与档位来自服务端配置，不从请求取
提现        申请、审核、打款记录        需要后台审核，留有操作日志
分销        推广码、佣金结算        按订单实付金额计算，退款会冲正
REST        对外接口命名空间与权限校验        非公开数据需要登录与能力校验



6  技术架构与数据模型
6.1  目录结构
路径        作用
style.css / functions.php        主题头信息与引导：加载 inc/ 下各模块、注册菜单与资源
inc/        20+ 个功能模块：slider、boards、gallery、search、members、points、reward、rating、notice、seo、pwa、ai-*、admin、permissions…
inc/admin.php        主题设置页：schema 定义、字段渲染、保存与清洗
page-templates/        前台功能页模板：user-center、vip、cart、write、submit、boards、gallery、hot、nav
template-parts/        可复用片段：卡片、作者栏、侧栏模块、分页等
assets/css/main.css        全站样式（约 212KB，gzip 后 ≈32KB）
assets/js/        交互脚本：main.js、slider、desk-pet、ai.js、ai-editor.js
assets/img/        图标、默认图、页脚桌宠（透明 WebP）
RELEASE-2.5.15.md        当前版本的改动说明

6.2  性能
· gzip 覆盖 CSS / JS / JSON / SVG / WOFF2：main.css 164KB → 31.6KB，main.js 67KB → 15.8KB。
· 图片全部 width/height 声明，配合 lazy loading，首屏不跳动。
· 列表查询关闭 no_found_rows、按需取字段；首页排除测试夹具与板块帖。
· 静态资源带版本号（?v=版本），升级后浏览器自动取新文件，不需要手动清缓存。
6.3  安全
· 全部表单带 nonce，后台操作校验 manage_options 能力。
· 匿名请求不暴露 /wp/v2/users，用户枚举接口整段移除。
· 验证码与频率限制可分别作用于登录、评论、投稿、支付回调。
· 密钥、商户证书、SMTP 密码只存服务端，页面只显示末四位。
· 支付回调验签 + 幂等；金额与档位一律服务端计算。
6.4  SEO
每页输出标题模板、描述、canonical、Open Graph 与结构化数据（Article / BreadcrumbList），自动生成站点地图与 favicon（内联 SVG，另带一份多尺寸 .ico）。
6.5  AI 接入
没写完

7  运行环境
7.1  服务器与软件
项目        最低        推荐（本文实测环境）
操作系统        Ubuntu 20.04 / CentOS 7        Ubuntu 24.04 LTS
CPU / 内存        1 核 / 1GB        2 核 / 2GB 以上
磁盘        10GB        20GB 以上（图片多的站建议配对象存储）
Web 服务器        Nginx 1.18+ 或 Apache 2.4+        Nginx 1.24
PHP        8.0        8.3（8.1/8.2 亦可）
数据库        MySQL 5.7 / MariaDB 10.3+        MariaDB 10.11
WordPress        6.4        7.1
HTTPS        上线必须        Let's Encrypt 或商业证书

7.2  PHP 扩展
以下扩展缺一不可，可用 php -m 自检：
bcmath  curl  dom  exif  fileinfo  gd  iconv  imagick  intl  json
mbstring  mysqli  openssl  pcre  PDO  pdo_mysql  sodium  xml
xmlreader  xmlwriter  xsl  zip  zlib  opcache

imagick 用于图片处理（缩略图、WebP）；gd 作为后备。opcache 开启后 PHP 执行时间通常下降 30% 以上。
7.3  可选服务
服务        用途        不配的后果
OpenAI 兼容接口        AI 摘要、问本站、写作助手        相关按钮置灰，页面其余功能正常
SMTP        注册验证、订单、评论通知邮件        站内通知照常，邮件不发送
短信服务商        手机号验证码登录        短信登录走沙箱，仅日志可见验证码
微信开放平台 / QQ / 微博 / GitHub        社交登录        仅保留账号密码登录
微信支付商户号 + 证书        微信支付        该通道自动降级沙箱

8.1  上传主题与插件
方式一（推荐，后台上传）：登录后台 → 外观 → 主题 → 上传主题 → 选 aurora-theme-2.5.15.zip → 启用；插件 → 安装插件 → 上传插件 → 选 allin-pro-core-0.4.0.zip → 启用。
方式二（命令行）：
sudo -u www-data wp theme install /path/aurora-theme-2.5.15.zip --activate
sudo -u www-data wp plugin install /path/allin-pro-core-0.4.0.zip --activate

8.2 伪静态、上传目录与权限
Nginx 站点配置示例（按域名与 PHP 版本调整）：
server {
    listen 80;
    server_name 你的域名;
    root /var/www/aurora;
    index index.php index.html;
    client_max_body_size 32m;

    gzip on;
    gzip_types text/css application/javascript application/json \
               image/svg+xml font/woff2;

    location / { try_files $uri $uri/ /index.php?$args; }
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }
    location ~ /\.(?!well-known) { deny all; }
}

保存后执行 sudo nginx -t && sudo systemctl reload nginx，再到后台「设置 → 固定链接」选「文章名」或自定义 /%post_id%.html 并保存，伪静态才会生效。
权限只需要两条：目录 755、文件 644，属主 www-data。不要把整站设成 777。
8.6  HTTPS（上线必做）
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d 你的域名

证书自动续期由 certbot 的定时任务负责，装完可以 certbot renew --dry-run 验证一次。
8.3  首次配置清单
装好后按这个顺序配置，十分钟能跑通：
顺序        位置        要做什么
1        设置 → 常规        站点标题、副标题、时区（Asia/Shanghai）、日期格式
2        Aurora 主题 → 公告与页脚        公告文字、版权、ICP 备案号
3        Aurora 主题 → 外观        背景渐变、默认配色、强调色、页脚桌宠开关
4        Aurora 主题 → 首页幻灯片        选来源：编号（填文章 ID）或自动
5        Aurora 主题 → 会员与付费        开 VIP、定价、付费墙、注册开关
6        Aurora 主题 → 微信支付 / 插件支付设置        商户号与证书（没有就先留空，走沙箱）
7        Aurora 主题 → 邮件通知        SMTP 账号与密码
8        Aurora 主题 → AI        接口地址、API Key、模型，点「保存并测试连接」
9        Aurora 主题 → 离线与安装        开 PWA（需 HTTPS）
10        插件 → 短信 / 社交登录        填服务商密钥，没有就先用沙箱

8.4 上线前检查
· 首页、文章页、板块页、图库、搜索、用户中心都能打开且没有 PHP 报错。
· 后台每个设置页保存后刷新，值仍在（表单只有一个 action）。
· HTTPS 下 PWA 能安装；HTTP 下 Service Worker 不注册属正常。
· 支付回调地址可从公网访问，沙箱下单能走完流程。
· 备份已配置：数据库每日备份 + uploads 目录每周备份。


9  升级、备份与排错
9.1  升级
覆盖升级：后台停用旧主题 → 上传新 zip → 启用；或在服务器上用 unzip 覆盖目录（保留 wp-content/uploads 与数据库）。主题设置存在 theme_mods_aurora 里，升级不丢；文章、订单、余额都在数据库，更不受影响。
9.2  备份
# 数据库
mysqldump -u aurora -p aurora | gzip > /backup/aurora-$(date +%F).sql.gz
# 上传目录
tar czf /backup/uploads-$(date +%F).tar.gz -C /var/www/aurora/wp-content uploads

9.3  常见故障
现象        排查方向
首页 500 / 白屏        看 /var/log/nginx/error.log 与 php8.3-fpm 日志；多为扩展缺失或目录权限不对
后台保存后值被重置        确认主题版本 ≥ 2.5.5；旧版 AI 页存在嵌套表单问题
幻灯片不显示        来源选了「按文章编号」但编号全无效时会回退自动；若文章都没特色图则不显示
图片 404        固定链接是否保存过；上传目录权限是否 www-data
支付回调收不到        回调地址必须公网可达；检查 HTTPS 证书链与防火墙
PWA 不生效        Service Worker 只在 HTTPS 或 localhost 下注册
AI 按钮灰掉        没填 API Key；填完点「保存并测试连接」看返回


11  常见问题
Q  能不能只用主题、不装插件？
可以。文章、板块、图库、幻灯片、会员等级、积分、AI 这些都在主题里；插件补的是短信/社交登录、支付通道、余额充值、提现与分销。不装插件时结算会提示未配置支付方式。
Q  主题会不会和别的插件冲突？
主题只用自己的命名空间（aurora_*）与独立设置表，不改 WordPress 核心文件，也不 hook 别人的后台页。已知冲突集中在缓存插件与图片压缩插件：它们会改写 CSS/JS 路径，遇到样式异常先关掉这两类插件试一次。
Q  幻灯片想同时放「指定文章 + 自动补位」怎么办？
目前三种来源互斥。要混排，用「按文章编号」把想要的几篇都填进去，不足的部分再补编号，顺序完全按你填的来。
Q  手机端为什么看不到桌宠？
640px 以下整块隐藏，同时图片懒加载不下载。这是有意的：手机上页脚本来就窄，人物会挤掉文字。
Q  AI 不填密钥能用吗？
能用。摘要卡不渲染、问本站与写作助手按钮置灰并提示去设置，其余功能不受影响；填了密钥后按文章缓存摘要，不会重复计费。
Q  会员和单篇购买能同时开吗？
能。会员免费读的规则可以指定「哪个等级以上免费」，未达等级的访客看到单篇购买入口，购买后可读天数单独配置。
Q  升级会不会丢设置？
不会。设置在 theme_mods_aurora，数据在数据库；覆盖主题文件不影响两者。唯一的例外是手动改过主题文件——那种改动会被覆盖，建议用子题。