BBS 社区（plugin-bbs）

Halo 2.x 插件：讨论 + 问答 + 公告 + 两级分类，适合博客站旁的隔离社区。

在线演示：https://blog.timxs.com/bbs（星港社区）

功能特性

• 帖子类型：讨论（POST）、问答（QUESTION）、公告（ANNOUNCEMENT，仅管理端可发）。三类帖必须归属分类，与置顶正交
• 问答：作者与版主可标记「已解决」；改出问答类型时服务端清掉已解决残留
• 锁定：版主操作——禁评论、禁作者编辑 / 删除。锁定帖不渲染评论组件，历史评论走只读接口（只看不赞）
• 置顶：独立开关 + 权重。分类页第 1 页浮顶（只在本分类页浮顶，不向父分类传染）；所属一级分类开启「置顶帖上首页」时同时出现在首页第 1 页顶部。徽标看 pinnedInView（本视图是否真浮顶），不是 pinned
• 分类：两级。Iconify 图标（保存时存下选择器输出的离线 SVG，选色已烤进 fill，未选色随文字色）+ 独立分类色（新建按名称预填实色；清空不上色）+ slug + 封面。板块级配置（pinToHome、moderatorRoles）仅一级可设，调和器抹掉子分类上的值
• 分区版主：一级分类可指定角色；持有该角色者管辖本分类树。全站版主（直接绑定 bbs-moderate / bbs-manage / 超管）不受限。管辖判定不展开角色依赖链
• 状态：草稿 / 待审核 / 已发布 / 已驳回；软删除进回收站，彻底删除仅管理角色
• 审核（可选）：用户发帖须审核；可配置「编辑已发布是否重新审核」。驳回后重提永远重审。审核中保存只更新内容、不改审核状态（WordPress 式）；作者可显式「取消提交」退回草稿；已驳回的帖子既可由作者修改重提，也可由版主直接通过。无需重审时对齐官方文章：标题 / 分类等设置保存即生效，正文仍需显式发布。提交审核可附可选补充说明，审核人在「审核记录」查看（与驳回原因对称）
• 评论：接入 Halo 官方评论体系。详情页由「评论组件」插件渲染；锁定帖改只读渲染
• 全文搜索：接入 Halo 搜索，已发布帖子可被站点全局搜索
• RSS：经 plugin-feed 输出全站 /feed/bbs/posts.xml 与一级分类 /feed/bbs/categories/{slug}.xml（未安装则无 RSS，其余照常）
• 前台：Flarum 两栏——白顶栏 + 品牌色 Hero、左栏分类树、紧凑列表。圆标（公告 / 置顶 / 未解决问答）+ 线框（已解决 / 锁）。默认按最后活跃排序
• 作者入口：无独立 /bbs/u 作者页。作者名按「作者链接模板」跳转（默认 /authors/{name}）；可选接入 interaction-plus（装扮 + 用户卡链接优先）
• 面向主题：Finder（${bbs}）+ 公开 REST API；主题可覆盖 bbs.html / bbs_post.html
• 安全：正文 HTML 服务端白名单净化；SVG 图标零 URL / 零事件属性；锁帖写入在安全链前拦截

环境要求

• Halo >= 2.25.0
• 构建：JDK 21、Node 18+、pnpm
• 可选：interaction-plus >= 1.0.0（装扮与用户卡链接；未安装时 BBS 照常运行）
• 可选：PluginFeed >= 1.4.0（RSS；未安装时无订阅源，其余照常）

快速上手

从安装到可用的五步；各项的详细行为见 使用说明。

1. 安装插件

在应用市场搜索「BBS 社区」安装；或从 GitHub Releases 下载 jar，在 Console「插件」页上传安装（自行构建见 构建）。

2. 创建分类（必须先行）

帖子必须归属分类——一个分类都没建时，用户发不了帖。 由「BBS 社区 → 帖子列表」页的「分类」进入分类管理：

• 两级树，可拖拽排序；封面、Iconify 图标、分类色、slug 均可后续完善
• 板块级配置（「置顶帖上首页」与「版主角色」）仅一级分类可设

3. 分配角色

• 普通用户无需配置：发帖权（bbs-uc-post）已聚合给所有登录用户，前台浏览自动公开
• 版主：手动分配「BBS 社区版主」（bbs-moderate）
• 全功能：分配「BBS 社区管理」（bbs-manage）；超管天然拥有
• 分区版主：自建一个角色（依赖建议勾上 bbs-moderate，已连带后台查看），授予目标用户，再把它写进一级分类的「版主角色」——持有者即管辖该分类树
• ⚠️ 别把「后台查看」（bbs-view）授给普通用户，否则对方能进管理后台看到草稿 / 待审核 / 回收站

各角色能力见下方 权限模型。

4. 安装评论组件与可选插件

评论的登录 / 审核策略由「系统设置 → 评论」统一控制，评论管理复用 Halo 后台「评论」页。

5. 外观与审核设置

插件设置：

• 外观 → 品牌：社区标题、Logo、顶栏菜单、主题色；Hero 区与页脚声明也可在此开关
• 内容 → 审核：是否「用户发帖需审核」（默认提交即发布）；开启后再定「编辑已发布是否重新审核」

完成后访问前台 /bbs 验证。

使用说明

Console（后台）

「BBS 社区」菜单（内容分组）：

• 帖子列表：按状态 / 类型 / 分类 / 作者 / 关键词筛选；行内编辑、设置、置顶、锁定、回收，以及发布 / 通过 / 驳回 / 取消提交（纯草稿走「发布」，进过审核的走「通过」；已驳回帖可由作者修改重提，也可版主直接通过；待审核帖可撤回提交；设置弹窗可保存并直接「发布 / 通过」）。分区版主只看见自己管辖的分类
• 写帖子 / 公告：全屏富文本编辑器；设置里选类型、分类（必选）、置顶与权重、别名、摘要。预览先静默保存再弹窗（桌面 / 平板 / 手机三档视口切换），读工作副本（含未提交修改），未发布也能预览（对齐官方；仅作者本人可见）
• 分类管理：由帖子列表页「分类」进入。两级树、拖拽排序、封面、板块版主角色

用户中心（UC）

「我的帖子」：登录用户发讨论 / 问答、编辑、删除自己的帖子（发帖必须登录）。用户不能发公告、不能置顶、不能锁定。编辑器首次手动保存、自动保存或 Ctrl/Cmd+S 会创建服务端草稿与 Halo 核心 Snapshot；编辑已发布帖子时，静默保存写入独立 headSnapshot，前台仍读取 releaseSnapshot。只有显式提交才进入审核或发布；已发布修改需审核时，旧发布版本在审核期间继续公开。提交入口三处：编辑器顶部、列表行菜单与设置弹窗（草稿 / 已驳回直接「提交」；已发布帖有未提交修改时「提交修改」；缺分类先弹设置补齐后可就地提交）。待审核期间保存只更新内容、不退出审核队列；想撤回须显式「取消提交」（列表行菜单），退回草稿后可继续编辑重提。编辑器「历史」可查看完整版本、并排对照、恢复、删除及对应审核时间线；「预览」先静默保存再弹窗（三档视口切换），读工作副本，未发布也能看。默认提交即发布；开启「用户发帖需审核」后进入待审核。锁定帖作者不可再编辑或删除。

前台

分页：桌面显示页码窗口（首页 / 末页 + 当前页 ±2，空档省略号）；窄屏为 n / 总页数 计数，点一下展开同款页码窗口下拉跳页。页码链接完整携带分类 / 搜索 / 排序 / 类型参数。

顶栏可选挂站点菜单：插件设置「外观 → 品牌 → 顶栏菜单」选已有菜单组，留空则顶栏不显示导航。多级菜单一律点击展开（不做悬停展开）：桌面点箭头出下拉（子项缩进平铺），窄屏进汉堡、点箭头逐层展开；带链接的父项文字跳转、箭头开合，不带链接的父项整项即开关。兼容 Halo 2.25（menuItems + children）与 2.26（menuName + parent）两种菜单存法及两者混存。

作者名链接（无独立 BBS 作者页）：

1. 插件设置「作者链接模板」（默认 /authors/{name}，{name} = 用户名；留空 = 作者名不跳转）
2. 若开启「接入互动增强」，且 interaction-plus 的「用户卡跳转链接」非空 → 优先用对方的模板
3. 互动增强未安装 / 未就绪 / 模板为空 → 静默回退 BBS 模板，不报错

主题作者页若要展示该用户的 BBS 帖子，使用 Finder：listPostsByOwner / getAuthor（见 主题开发指南）。

评论

• 前台需安装官方 评论组件（plugin-comment-widget）；未安装时评论区为空、不影响页面
• 登录 / 审核策略由「系统设置 → 评论」统一控制
• 评论管理复用 Halo 后台「评论」页
• 锁定帖：模板不渲染 <halo:comment>，历史评论由前台走 GET /posts/{name}/comments 只读渲染。写入被服务端拦截

互动增强（可选）

插件设置 → 集成：

列表页昵称不渲染完整身份行（密度），仅昵称样式 + 最高优先级身份标识；详情楼主仍可用完整身份行。发帖数可通过扩展点贡献到 interaction-plus 名片统计（插件在 classpath 时自动注册）。

插件设置

审核通过 / 驳回走 Halo 官方通知中心：作者在 UC 通知列表收到站内消息（可按偏好开邮件）。作者审核自己的帖子不发。事件类型「我的帖子通过审核 / 未通过审核」会出现在用户通知偏好里。

页脚：声明文案（可清空隐藏）+ © {年} {站点名}（站点名来自 Halo 系统设置，链到博客首页）+ Powered by bbs（GitHub）。

权限模型（角色模板）

前台浏览由 bbs-public-read 自动聚合，不必把 bbs-view 授给普通用户——否则对方能进管理后台看到草稿 / 待审核 / 回收站。

如不希望所有注册用户都能发帖，删除 roleTemplate.yaml 中 bbs-uc-post 的
rbac.authorization.halo.run/aggregate-to-authenticated 标签后重新构建，再手动分配该角色。

面向主题开发者

主题可覆盖 bbs.html / bbs_post.html，经 Finder（${bbs}）与匿名公开 REST API 聚合社区数据；约定「忽略未知字段、接口只增不改」。模板覆盖、Finder 方法全表、REST 端点与数据模型见 主题开发指南。

构建

./gradlew build

产物在 build/libs/plugin-bbs-*.jar，在 Console「插件」页上传安装即可。

前端单独调试：

cd ui
pnpm install
pnpm dev          # watch 构建
pnpm type-check   # vue-tsc 类型检查

发布自动发帖（可选）

面向在 GitHub 上托管项目、以 GitHub Releases 发版的维护者；不在此场景可忽略本节。

仓库自带工作流 .github/workflows/bbs-post.yaml：发布 release 时，自动把发布说明发到你自己的 BBS 社区（调 Console API 建帖，正文由 release notes 转 HTML），版本公告不用再手工发一遍。未配置时它不会做任何事；确定不需要可直接删除该文件，不影响插件本身。

配置

仓库 Settings → Secrets and variables → Actions：

metadata.name 是分类的资源主键，既不是中文名也不是 slug——中文名是 displayName，前台链接别名是 slug。分类查询接口匿名可读，浏览器直接打开即可：

https://你的站点/apis/api.bbs.timxs.com/v1alpha1/categories

返回为 JSON 数组（无 items 包裹），仅含启用中的分类，priority 升序；其中 name 即分类的 metadata.name，displayName / slug 为其中文名与链接别名。

发帖行为：

• 状态：正式 release → 直接发布；预发布（prerelease）→ 存草稿；手动运行（Actions → 同步 BBS 公告 → Run workflow）可覆盖
• 不重复发帖：帖子别名固定为 release-<tag>（如 v1.2.3 → release-v123）。删了 release 重发、手动重跑都只更新已有帖；回收站内的帖视为不存在，会新建
• 内容：标题默认 <tag> 发布说明（tag 来自 git tag，不是 GitHub Release 标题）；配了 BBS_PROJECT_NAME 则按原样作为前缀拼成 {前缀} {tag} 发布说明。正文前后自动拼 release 页面链接与附件下载列表（会等待 CD 上传完 jar，超时则降级为不带下载链接）

鸣谢

• 感谢 Jevon 提供的 token 支持

交流反馈

License

GPL-3.0