项目集（Portfolio）

Halo CMS 插件 —— 统一管理和展示 GitHub、Gitee、产品、插件、工具等项目作品。
预览：https://blog.muyin.site/projects

交流群

点击链接加入群聊【halo博客-lywq插件】

功能特性

• 项目管理 — 在 Halo 控制台创建、编辑、删除项目，支持草稿 / 已发布 / 已归档三种状态
• 多平台支持 — 内置 GitHub、Gitee、独立站点、私有项目等平台选项，可在设置中自定义扩展
• 多类型分类 — 开源项目、产品、插件、网站、工具、类库，同样支持自定义
• 技术栈 & 标签 — 每个项目可关联多个技术栈和展示标签，方便筛选和检索
• 推荐项目 — 标记重点项目，在首页或侧边栏优先展示
• 默认页面 — 开箱即用的 /projects 列表页和 /projects/{slug} 详情页，支持主题覆盖
• Finder API — 注册 projectFinder，主题模板可直接调用，灵活控制渲染
• 编辑器卡片 — 在 Halo 富文本编辑器中插入项目卡片，在文章中嵌入项目展示
• Markdown 内容 — 项目详情支持 Markdown 编写，自动渲染为安全 HTML
• RBAC 权限 — 内置查看 / 管理两级角色模板，支持细粒度权限控制
• SEO 友好 — 自定义页面标题和描述，详情页自动生成 meta 信息

安装

方式一：从 Release 安装（推荐）

1. 前往 Releases 下载最新 .jar 文件
2. 在 Halo 控制台 → 插件管理 → 安装插件，上传 jar 文件
3. 启用插件

方式二：从源码构建

git clone https://github.com/liuyiwuqing/halo-plugin-portfolio.git
cd plugin-portfolio
./gradlew build

构建产物位于 build/libs/plugin-portfolio-*.jar，在 Halo 控制台上传安装。

配置

插件启用后，在 控制台 → 插件 → 项目集 → 设置 中可配置：

平台和类型选项支持自由增删改，value 建议使用小写英文、数字和下划线。

主题集成

Finder API

插件注册 projectFinder，在 Thymeleaf 模板中直接注入使用。Finder 只返回已发布项目。

方法列表

Thymeleaf 示例

展示推荐项目：

<th:block th:with="projects=${projectFinder.featured(1, 6)},
                   platformLabels=${projectFinder.platformLabels()},
                   typeLabels=${projectFinder.typeLabels()}">
  <div class="project-grid">
    <article th:each="project : ${projects.items}" class="project-card">
      <a th:href="@{/projects/{slug}(slug=${project.slug})}">
        <img th:if="${project.cover}" th:src="${project.cover}" th:alt="${project.title}" />
        <h3 th:text="${project.title}">项目标题</h3>
        <p th:text="${project.summary}">项目简介</p>
        <span th:text="${platformLabels[project.platform] ?: project.platform}">平台</span>
        <span th:text="${typeLabels[project.type] ?: project.type}">类型</span>
      </a>
    </article>
  </div>
</th:block>

渲染项目详情内容：

<div th:utext="${projectFinder.renderContent(project)}"></div>

按技术栈筛选：

<th:block th:with="projects=${projectFinder.listByTechStack('Vue', 1, 10)}">
  <div th:each="project : ${projects.items}">
    <a th:href="@{/projects/{slug}(slug=${project.slug})}" th:text="${project.title}">标题</a>
  </div>
</th:block>

默认页面

插件内置两个 Thymeleaf 模板：

主题可通过提供同名模板覆盖默认页面。关闭设置中的「启用默认展示页」后，插件不再注册路由，完全由主题自行渲染。

编辑器项目卡片

在 Halo 富文本编辑器中，可通过工具栏或斜杠命令 / 插入「项目卡片」节点。选择一个已发布项目后，文章中会嵌入一个可交互的卡片组件。

卡片在前端渲染为 <portfolio-project-card data-slug="xxx"> 标签，发布时由插件自动替换为带样式的 HTML 卡片，包含封面、标题、摘要和元数据标签。

项目数据模型

每个项目（Project）包含以下字段：

另有 sourceProvider、repoOwner、repoName 字段为后续仓库同步功能预留。

开发

环境要求

• Java 21+（Gradle toolchain 强制）
• Node.js 20+
• pnpm 10+

启动开发服务

# 终端 1：启动 Halo 开发服务器（含后端热重载）
./gradlew haloServer

# 终端 2：启动前端开发服务器（含 HMR）
cd ui
pnpm install
pnpm dev

Halo 开发服务器默认运行在 http://localhost:8090，前端开发服务器提供模块热替换。

项目结构

src/main/java/site/muyin/portfolio/
├── PortfolioPlugin.java          # 插件生命周期，注册 GVK 和索引
├── scheme/Project.java           # 核心数据模型
├── enums/                        # 枚举（项目状态）
├── model/                        # 数据传输对象
├── query/                        # 查询参数构建
├── setting/                      # 插件设置 POJO
├── service/                      # 业务逻辑接口
│   └── impl/                     # 业务逻辑实现
├── endpoint/                     # REST API（Console + Public）
│   └── routes/                   # 路由处理器
├── finders/                      # Finder API 接口
│   └── impl/                     # Finder API 实现
├── content/                      # 内容渲染（Markdown + 项目卡片）
└── router/                       # 默认页面路由

ui/src/
├── index.ts                      # 插件入口，注册路由和编辑器扩展
├── views/ProjectManagerView.vue  # 项目管理页面
├── api/portfolio.ts              # API 客户端和类型定义
├── editor/                       # TipTap 编辑器扩展
└── assets/                       # 静态资源

构建

# 完整构建（后端 + 前端）
./gradlew build

# 仅构建前端
cd ui && pnpm build

# 运行后端测试
./gradlew test

# 运行前端检查
cd ui && pnpm check

构建产物：build/libs/plugin-portfolio-*.jar

CI/CD

项目使用 GitHub Actions 自动化：

• CI（ci.yaml）— 推送或 PR 到 main 分支时触发，执行构建和测试
• CD（cd.yaml）— 发布 GitHub Release 时触发，构建并产出插件 jar

技术栈

许可证

GPL-3.0 © Lywq