Halo 项目展厅

面向 Halo 2.25+ 的项目展示插件。它把项目的在线体验、源码、下载、版本、状态、已知限制和关联文章集中管理，并将可验证的项目入口展示给博客读者。

效果预览

前台项目展厅

![项目展厅前台页面]
projects-page

Console 项目管理

![Console 项目管理列表]
console-project-list

查看项目编辑界面

![项目编辑基本信息]
project-editor-basic

![项目编辑访问入口与关联内容]
project-editor-details

功能

在 Halo Console 中创建、编辑、删除和排序项目
从已发布文章中选择项目的关联文章
独立的 /projects 项目展示页
在关联文章正文顶部自动插入项目体验卡
项目封面和最多 12 张项目截图均支持剪贴板粘贴、上传及附件库选择，截图还支持拖拽排序和放大浏览
支持 Bilibili BV/AV 视频链接，点击后按需加载播放器
公开项目只读 API
手动或每 30 分钟检测演示地址
地址检测阻止私网、回环、特殊用途 IP 和非 HTTP(S) 协议
区分在线体验、源码和下载，不把可访问项目误标为开源项目

安装

从 GitHub Releases 下载最新的 plugin-project-showcase-*.jar。
在 Halo Console 的插件管理中上传 JAR。
启用插件后，在 Console 左侧进入“项目展厅”。
创建项目并打开“公开展示”，前台即可访问 /projects。

插件要求 Halo >= 2.25.0。

也可以使用 JDK 21 从源码构建：

.\gradlew.bat build

构建产物位于 build/libs/。

配置与使用

在“项目展厅”中点击“新建项目”，填写项目名称、简介和状态。
设置封面、项目截图、版本、技术标签及需要公开的访问地址。
根据需要关联已发布文章，并填写体验说明或已知限制。
打开“公开展示”并保存；公开项目会出现在 /projects，也可以在关联文章顶部显示体验卡。
使用列表页的检测按钮检查体验地址，或等待插件每 30 分钟自动检测。

项目不会因为填写了体验地址而自动标记为开源。只有单独填写源码地址时，前台才会显示源码入口。

升级与卸载

升级前建议先备份 Halo 数据，再在插件管理中上传新版本 JAR 完成升级。现有项目数据和设置会继续使用。
卸载前先禁用插件；禁用后定时地址检测和插件路由将停止运行。
如需永久删除项目数据，请在卸载前从“项目展厅”中删除对应项目。插件不提供外部账户、订阅或云端数据，无需额外解绑。

项目字段

项目名称、简介、封面、项目截图、版本和生命周期
在线体验、源码和下载地址
Bilibili 项目演示视频
技术标签与已知限制
体验说明
关联的 Halo 文章
公开状态与排序

体验说明是公开内容，不应填写密码、密钥或其他敏感信息。需要测试账号时，建议填写账号申请方式，或使用权限受限且可定期重置的公开测试账号。

封面和截图都使用 Halo 附件库。在项目编辑窗口中点击对应的“剪贴板封面”或“剪贴板截图”区域，再按 Ctrl+V 即可上传剪贴板图片；也可以继续使用文件上传或附件库选择。截图最多保存 12 张，并可在后台拖拽调整顺序。没有单独设置封面时，第一张有效截图会作为项目封面。

Bilibili 视频请填写标准页面地址，例如 https://www.bilibili.com/video/BV1xx411c7mD。插件不接受短链接或任意 iframe HTML，只会为通过域名和视频编号校验的链接生成播放器。

地址检测

插件只将 HTTP 2xx 响应视为可访问。检测结果是一次网络可达性观察，不代表项目的安全性、正确性或生产可用性。

为防止 SSRF，检测客户端会拒绝私网、回环、链路本地、组播和特殊用途地址，并对每次重定向重新执行安全校验。

公开展示的数据只保留 HTTP(S) 链接和站内附件路径；Bilibili 播放器固定使用 player.bilibili.com，不会执行用户填写的嵌入代码。

数据与外部请求

项目资料存储在 Halo 的扩展资源中，插件不会将项目资料、用户信息或站点内容同步到开发者服务器。
只有手动检测或定时检测公开项目时，Halo 服务器才会请求对应的在线体验地址；请求设有超时，并会拒绝私网、回环和特殊用途地址。
用户点击 Bilibili 演示视频后，浏览器会按需加载 player.bilibili.com 播放器。未点击时不会加载播放器。
公开项目会通过 /projects 和只读公开 API 对访客可见。请勿在项目名称、简介、体验说明或链接中填写敏感信息。

公开 API

GET /apis/api.projectshowcase.xsstar.cn/v1alpha1/projects
GET /apis/api.projectshowcase.xsstar.cn/v1alpha1/posts/{postName}/projects

接口只返回已公开项目，并且不会暴露 Halo 扩展资源的完整内部字段。

故障排查

Console 中没有“项目展厅”：确认插件已启用，并刷新浏览器页面。
前台 /projects 没有内容：确认至少有一个项目打开了“公开展示”。
地址显示不可访问：确认目标使用 HTTP(S)、能够从 Halo 服务器访问，并返回 2xx 状态码。
图片无法显示：确认附件仍然存在，并检查附件访问权限和站点地址配置。
Bilibili 视频无法播放：使用标准 BV/AV 视频页面地址，不要填写短链接或 iframe 代码。

问题反馈请提交到 GitHub Issues。报告问题时请附上 Halo 版本、插件版本、复现步骤和相关日志，并删除其中的敏感信息。

开发

环境要求：JDK 21、Node.js 20+、pnpm 10。

.\gradlew.bat test
.\gradlew.bat :ui:buildFrontend
.\gradlew.bat build

Docker 可用时，可以运行 ./gradlew haloServer 启动本地 Halo 开发环境。

菜单

项目展厅