--- url: https://docs.halo.run/guide/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 使用指南 ## 写在前面 ### [写在前面](/guide/prepare.md) - [Halo 是什么?](/guide/prepare.md#halo-是什么) - [发行版本](/guide/prepare.md#发行版本) - [应用生态](/guide/prepare.md#应用生态) - [环境要求](/guide/prepare.md#环境要求) - [浏览器支持](/guide/prepare.md#浏览器支持) - [名词解释](/guide/prepare.md#名词解释) - [许可证](/guide/prepare.md#许可证) - [贡献者](/guide/prepare.md#贡献者) - [项目状态](/guide/prepare.md#项目状态) ## 在线体验 ### [在线体验](/guide/demo.md) ## 快速安装 ### [使用 Docker Compose 部署](/guide/install/docker-compose.md) - [环境搭建](/guide/install/docker-compose.md#环境搭建) - [部署 Halo](/guide/install/docker-compose.md#部署-halo) - [升级 Halo](/guide/install/docker-compose.md#升级-halo) - [反向代理](/guide/install/docker-compose.md#反向代理) ### [使用 Docker 部署](/guide/install/docker.md) - [环境搭建](/guide/install/docker.md#环境搭建) - [部署 Halo](/guide/install/docker.md#部署-halo) - [升级 Halo](/guide/install/docker.md#升级-halo) ### [使用 1Panel 部署](/guide/install/1panel.md) - [1Panel 简介](/guide/install/1panel.md#1panel-简介) - [安装 Halo 应用](/guide/install/1panel.md#安装-halo-应用) - [创建网站](/guide/install/1panel.md#创建网站) - [升级 Halo](/guide/install/1panel.md#升级-halo) - [激活许可证](/guide/install/1panel.md#激活许可证) ### [使用宝塔面板部署](/guide/install/bt-panel.md) - [宝塔面板简介](/guide/install/bt-panel.md#宝塔面板简介) - [安装 Halo 应用](/guide/install/bt-panel.md#安装-halo-应用) - [配置网站和 SSL](/guide/install/bt-panel.md#配置网站和-ssl) - [升级 Halo](/guide/install/bt-panel.md#升级-halo) - [激活许可证](/guide/install/bt-panel.md#激活许可证) ### [使用 Helm 部署](/guide/install/helm.md) - [先决条件](/guide/install/helm.md#先决条件) - [快速部署](/guide/install/helm.md#快速部署) - [卸载](/guide/install/helm.md#卸载) - [使用 MySQL 数据库](/guide/install/helm.md#使用-mysql-数据库) - [使用已有的数据库](/guide/install/helm.md#使用已有的数据库) - [创建 Ingress](/guide/install/helm.md#创建-ingress) - [其他参数](/guide/install/helm.md#其他参数) ### [使用 Podman 部署](/guide/install/podman.md) - [前言](/guide/install/podman.md#前言) - [环境搭建](/guide/install/podman.md#环境搭建) - [部署 Halo](/guide/install/podman.md#部署-halo) - [升级 Halo](/guide/install/podman.md#升级-halo) - [使用 Podman Quadlet](/guide/install/podman.md#使用-podman-quadlet) ### [使用 JAR 文件部署](/guide/install/jar-file.md) - [依赖检查](/guide/install/jar-file.md#依赖检查) - [安装](/guide/install/jar-file.md#安装) - [作为服务运行](/guide/install/jar-file.md#作为服务运行) - [版本升级](/guide/install/jar-file.md#版本升级) - [反向代理](/guide/install/jar-file.md#反向代理) ### [使用离线包部署](/guide/install/offline.md) - [下载安装包](/guide/install/offline.md#下载安装包) - [安装部署](/guide/install/offline.md#安装部署) ### [配置说明](/guide/install/config.md) - [配置方式](/guide/install/config.md#配置方式) - [配置列表](/guide/install/config.md#配置列表) - [Redis 集成](/guide/install/config.md#redis-集成) ### [云平台](/guide/install/cloud/index.md) ### [其他指南](/guide/install/other/index.md) ## 初始化 ### [初始化](/guide/setup.md) ## 第一篇文章 ### [第一篇文章](/guide/first-post.md) - [登录管理端](/guide/first-post.md#登录管理端) - [新建文章](/guide/first-post.md#新建文章) - [查看文章](/guide/first-post.md#查看文章) ## 常用模块 ### [概念说明](/guide/use/common.md) - [登录](/guide/use/common.md#登录) - [注册](/guide/use/common.md#注册) - [控制台](/guide/use/common.md#控制台) - [个人中心](/guide/use/common.md#个人中心) - [文章](/guide/use/common.md#文章) - [页面](/guide/use/common.md#页面) - [分类](/guide/use/common.md#分类) - [标签](/guide/use/common.md#标签) - [附件](/guide/use/common.md#附件) - [主题](/guide/use/common.md#主题) - [插件](/guide/use/common.md#插件) ### [仪表盘](/guide/use/dashboard.md) - [调整仪表盘](/guide/use/dashboard.md#调整仪表盘) - [配置不同设备的布局](/guide/use/dashboard.md#配置不同设备的布局) ### [许可证激活](/guide/use/activate.md) - [购买许可证](/guide/use/activate.md#购买许可证) - [部署 Halo 付费版](/guide/use/activate.md#部署-halo-付费版) - [查看产品版本信息](/guide/use/activate.md#查看产品版本信息) - [查看已购产品许可证](/guide/use/activate.md#查看已购产品许可证) - [下载许可证](/guide/use/activate.md#下载许可证) - [激活许可证](/guide/use/activate.md#激活许可证) - [取消激活许可证](/guide/use/activate.md#取消激活许可证) - [使用增值权益](/guide/use/activate.md#使用增值权益) ### [个人中心](/guide/use/user-center.md) - [进入个人中心](/guide/use/user-center.md#进入个人中心) - [个人资料](/guide/use/user-center.md#个人资料) - [通知配置](/guide/use/user-center.md#通知配置) - [个人令牌](/guide/use/user-center.md#个人令牌) - [认证方式](/guide/use/user-center.md#认证方式) - [两步验证](/guide/use/user-center.md#两步验证) - [登录设备](/guide/use/user-center.md#登录设备) - [消息](/guide/use/user-center.md#消息) - [我的文章](/guide/use/user-center.md#我的文章) - [商城](/guide/use/user-center.md#商城) ### [文章](/guide/use/posts.md) - [新建文章](/guide/use/posts.md#新建文章) - [文章设置](/guide/use/posts.md#文章设置) - [发布及取消发布](/guide/use/posts.md#发布及取消发布) - [删除文章](/guide/use/posts.md#删除文章) - [文章分类管理](/guide/use/posts.md#文章分类管理) - [文章标签管理](/guide/use/posts.md#文章标签管理) ### [页面](/guide/use/pages.md) - [页面设置](/guide/use/pages.md#页面设置) - [页面操作](/guide/use/pages.md#页面操作) ### [评论](/guide/use/comments.md) - [查找评论](/guide/use/comments.md#查找评论) - [审核评论](/guide/use/comments.md#审核评论) - [回复评论](/guide/use/comments.md#回复评论) - [删除评论](/guide/use/comments.md#删除评论) ### [附件](/guide/use/attachments.md) - [存储策略](/guide/use/attachments.md#存储策略) - [附件分组](/guide/use/attachments.md#附件分组) - [上传附件](/guide/use/attachments.md#上传附件) - [查看附件](/guide/use/attachments.md#查看附件) - [删除附件](/guide/use/attachments.md#删除附件) - [移动附件](/guide/use/attachments.md#移动附件) ### [菜单](/guide/use/menus.md) - [创建菜单](/guide/use/menus.md#创建菜单) - [创建菜单项](/guide/use/menus.md#创建菜单项) - [排序](/guide/use/menus.md#排序) ### [主题](/guide/use/themes.md) - [安装主题](/guide/use/themes.md#安装主题) - [切换主题](/guide/use/themes.md#切换主题) - [修改主题设置](/guide/use/themes.md#修改主题设置) - [预览主题](/guide/use/themes.md#预览主题) - [升级主题](/guide/use/themes.md#升级主题) - [重载主题配置](/guide/use/themes.md#重载主题配置) - [重置](/guide/use/themes.md#重置) - [卸载主题](/guide/use/themes.md#卸载主题) ### [插件](/guide/use/plugins.md) - [安装插件](/guide/use/plugins.md#安装插件) - [插件设置](/guide/use/plugins.md#插件设置) - [启用/禁用插件](/guide/use/plugins.md#启用禁用插件) - [升级插件](/guide/use/plugins.md#升级插件) - [重载插件](/guide/use/plugins.md#重载插件) - [重置](/guide/use/plugins.md#重置) - [卸载插件](/guide/use/plugins.md#卸载插件) - [扩展配置](/guide/use/plugins.md#扩展配置) ### [应用市场](/guide/use/app-store.md) - [应用市场页面](/guide/use/app-store.md#应用市场页面) - [绑定 Halo 官网账号](/guide/use/app-store.md#绑定-halo-官网账号) - [安装/更新插件](/guide/use/app-store.md#安装更新插件) - [安装/更新主题](/guide/use/app-store.md#安装更新主题) - [付费应用激活](/guide/use/app-store.md#付费应用激活) ### [用户与权限](/guide/use/users.md) - [概览](/guide/use/users.md#概览) - [用户](/guide/use/users.md#用户) - [角色](/guide/use/users.md#角色) - [身份认证](/guide/use/users.md#身份认证) ### [站点设置](/guide/use/settings.md) - [基本设置](/guide/use/settings.md#基本设置) - [文章设置](/guide/use/settings.md#文章设置) - [SEO 设置](/guide/use/settings.md#seo-设置) - [用户设置](/guide/use/settings.md#用户设置) - [附件设置](/guide/use/settings.md#附件设置) - [评论设置](/guide/use/settings.md#评论设置) - [主题路由设置](/guide/use/settings.md#主题路由设置) - [代码注入](/guide/use/settings.md#代码注入) - [品牌信息](/guide/use/settings.md#品牌信息) - [通知设置](/guide/use/settings.md#通知设置) ### [备份与恢复](/guide/use/backup.md) - [备份](/guide/use/backup.md#备份) - [自动备份与同步](/guide/use/backup.md#自动备份与同步) - [恢复](/guide/use/backup.md#恢复) ### [移动端 App](/guide/use/mobile-app.md) - [绑定设备](/guide/use/mobile-app.md#绑定设备) - [删除绑定](/guide/use/mobile-app.md#删除绑定) ## 商城模块 ### [写在前面](/guide/shop/prepare.md) - [前提条件](/guide/shop/prepare.md#前提条件) - [前台路由](/guide/shop/prepare.md#前台路由) ### [控制台首页](/guide/shop/console-home.md) ### [商店设置](/guide/shop/settings.md) - [店铺](/guide/shop/settings.md#店铺) - [小程序](/guide/shop/settings.md#小程序) - [订单号](/guide/shop/settings.md#订单号) ### [支付方式](/guide/shop/payments.md) - [支付宝](/guide/shop/payments.md#支付宝) - [微信支付](/guide/shop/payments.md#微信支付) - [易支付](/guide/shop/payments.md#易支付) - [Stripe](/guide/shop/payments.md#stripe) - [银行转账](/guide/shop/payments.md#银行转账) - [收款码支付](/guide/shop/payments.md#收款码支付) ### [销售渠道](/guide/shop/sales-channels.md) - [创建销售渠道](/guide/shop/sales-channels.md#创建销售渠道) ### [产品管理](/guide/shop/products.md) - [查找和管理产品](/guide/shop/products.md#查找和管理产品) - [创建产品](/guide/shop/products.md#创建产品) - [管理分类](/guide/shop/products.md#管理分类) - [管理属性模板](/guide/shop/products.md#管理属性模板) - [发布产品](/guide/shop/products.md#发布产品) ### [订阅管理](/guide/shop/subscriptions.md) - [创建订阅产品](/guide/shop/subscriptions.md#创建订阅产品) - [订阅档次](/guide/shop/subscriptions.md#订阅档次) - [订阅计划](/guide/shop/subscriptions.md#订阅计划) - [变更规则](/guide/shop/subscriptions.md#变更规则) - [订阅策略](/guide/shop/subscriptions.md#订阅策略) - [管理订阅](/guide/shop/subscriptions.md#管理订阅) - [客户自助管理](/guide/shop/subscriptions.md#客户自助管理) - [续费提醒邮件](/guide/shop/subscriptions.md#续费提醒邮件) - [相关设置](/guide/shop/subscriptions.md#相关设置) - [限制](/guide/shop/subscriptions.md#限制) - [相关文档](/guide/shop/subscriptions.md#相关文档) ### [营销](/guide/shop/marketing.md) - [折扣](/guide/shop/marketing.md#折扣) - [优惠券](/guide/shop/marketing.md#优惠券) ### [订单管理](/guide/shop/orders.md) - [查找订单](/guide/shop/orders.md#查找订单) - [手动创建订单](/guide/shop/orders.md#手动创建订单) - [查看订单详情](/guide/shop/orders.md#查看订单详情) - [发货](/guide/shop/orders.md#发货) ### [虚拟交付](/guide/shop/virtual-delivery.md) - [创建产品](/guide/shop/virtual-delivery.md#创建产品) - [设置文件资源下载](/guide/shop/virtual-delivery.md#设置文件资源下载) - [设置卡密发货](/guide/shop/virtual-delivery.md#设置卡密发货) - [订单相关](/guide/shop/virtual-delivery.md#订单相关) - [API 规范](/guide/shop/virtual-delivery.md#api-规范) ### [商城客户中心](/guide/shop/customer-center.md) - [收货地址](/guide/shop/customer-center.md#收货地址) - [优惠券](/guide/shop/customer-center.md#优惠券) - [订单](/guide/shop/customer-center.md#订单) - [订阅](/guide/shop/customer-center.md#订阅) ### [Webhook](/guide/shop/webhooks.md) - [创建 Webhook](/guide/shop/webhooks.md#创建-webhook) - [请求格式](/guide/shop/webhooks.md#请求格式) - [验证签名](/guide/shop/webhooks.md#验证签名) - [返回状态与重试](/guide/shop/webhooks.md#返回状态与重试) - [防止重复处理](/guide/shop/webhooks.md#防止重复处理) - [查看投递记录](/guide/shop/webhooks.md#查看投递记录) ### [小程序](/guide/shop/mp.md) - [获取方式](/guide/shop/mp.md#获取方式) - [使用流程](/guide/shop/mp.md#使用流程) - [在 Halo 中配置](/guide/shop/mp.md#在-halo-中配置) - [配置支付渠道](/guide/shop/mp.md#配置支付渠道) ### [商城主题开发](/guide/shop/theme-dev.md) ## 常见问题 ### [常见问题](/guide/faq.md) ## 问题反馈 ### [问题反馈](/guide/contribution/issue.md) - [GitHub](/guide/contribution/issue.md#github) - [Halo 官方社区](/guide/contribution/issue.md#halo-官方社区) ## 贡献政策 ### [贡献政策](/guide/contribution/pr.md) - [主仓库贡献政策](/guide/contribution/pr.md#主仓库贡献政策) - [反馈与讨论](/guide/contribution/pr.md#反馈与讨论) - [维护者开发流程](/guide/contribution/pr.md#维护者开发流程) - [其他仓库](/guide/contribution/pr.md#其他仓库) ## 从 Halo 1.x 迁移 ### [从 Halo 1.x 迁移](/guide/migrate-from-1.x.md) - [备份数据](/guide/migrate-from-1.x.md#备份数据) - [导出数据文件](/guide/migrate-from-1.x.md#导出数据文件) - [部署 Halo 2.0](/guide/migrate-from-1.x.md#部署-halo-20) - [移动附件](/guide/migrate-from-1.x.md#移动附件) - [安装插件](/guide/migrate-from-1.x.md#安装插件) - [配置存储策略](/guide/migrate-from-1.x.md#配置存储策略) - [迁移](/guide/migrate-from-1.x.md#迁移) --- url: https://docs.halo.run/guide/prepare.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 写在前面

Halo logo

Halo [ˈheɪloʊ],强大易用的开源建站工具。

GitHub release Docker pulls GitHub last commit GitHub Workflow Status Codecov percentage

## Halo 是什么? Halo 是一款强大易用的开源建站工具,从个人博客、知识库,到企业官网、在线商城,Halo 都能助您轻松实现,一站式满足您的多样化建站需求。 Halo 管理后台界面 ## 发行版本 Halo 的发行版本主要分为两个大类别,即**Halo 社区版**和 **Halo 付费版**。 Halo 付费版包含专业版和商城版,是[**凌霞软件**](https://www.lxware.cn/)旗下的商业产品,致力于为企业、团体或有进阶需求的个人用户提供定制化和特定场景的功能支持。 关于三个版本的详细区别,请查阅[**版本对比**](https://www.lxware.cn/halo)。 在后续的文档中,除非特别说明,将使用付费版统称 Halo 专业版和 Halo 商城版。 ### Halo 社区版 Halo 社区版开源免费,遵循 GPL-3.0 协议,适合个人开发者、技术爱好者和开源项目。 - 零成本搭建博客、作品集、技术文档站 - 提供超过 100 款免费主题和插件 ### Halo 专业版 Halo 专业版在社区版基础上,集成多项适用于专业场景的功能: - 移动端 App:随时随地管理内容 - AI 智能建站:快速生成专业站点 - 手机号验证登录:提升安全性与用户体验 - 全站私有化部署:保障数据主权 - 付费主题与插件市场:提供精品主题,以及 SEO 优化、付费阅读、AI 助手等付费插件 ### Halo 商城版 Halo 商城版在专业版基础上,提供在线商城功能: - 一体化在线商城:覆盖商品管理、订单处理和支付对接流程 - 面向中国商家:集成微信支付、支付宝等本土支付方式 - 支持品牌官网、内容管理和线上店铺一站式建设 ## 应用生态 - **应用市场**:提供丰富的站点主题与功能插件,前往 [Halo 应用市场](https://www.halo.run/store/apps)了解详情。 - **成为开发者**:支持自主发布并管理应用,参阅[应用市场开发者入驻及应用创建指南](https://www.halo.run/archives/halo-app-store-developer-onboarding-app-creation)。 - **社区资源**:访问 [Awesome Halo](https://github.com/halo-sigs/awesome-halo),了解 Halo 相关的精选资源。 ## 环境要求 这里将讲述运行 Halo 所要求的一些软硬件的配置,我们建议你在运行或者部署之前先浏览一遍此页面。 ### 硬件配置 :::tip 云服务器要求 如果你要使用服务器进行部署 Halo,需要注意的是,Halo 目前不支持市面上的云虚拟主机,请使用云服务器或者 VPS。 ::: #### CPU 无特别要求。目前我们的 [Docker 镜像](https://hub.docker.com/r/halohub/halo) 也已经支持多平台。 #### 内存 为了获得更好的体验,我们建议至少配置 1G 的 RAM。 #### 磁盘 无特别要求,理论上如果不大量在服务器上传附件,Halo 对磁盘的容量要求并不是很高。但我们推荐最好使用 SSD 硬盘的服务器,能更快的运行 Halo。 #### 网络 无特别要求,Halo 目前可以在无公网环境下使用,但部分主题由于使用了第三方资源,可能需要公网环境。 ### 软件环境 Halo 理论上可以运行在任何支持 Docker 及 Java 的平台。 #### Docker(可选) 我们主要推荐使用 Docker 运行 Halo,这可以避免一些环境配置相关的问题,文档可参考: - [使用 Docker Compose 部署](https://docs.halo.run/guide/install/docker-compose.md) - [使用 Docker 部署](https://docs.halo.run/guide/install/docker.md) #### JRE(可选) 如果使用 Docker 镜像部署,那么无需在服务器上安装 JRE。但目前我们也提供了 jar 文件部署的方式,文档可参考: - [使用 JAR 文件部署](https://docs.halo.run/guide/install/jar-file.md) :::info Java 版本要求 版本要求: - 2.21 以上版本:**JRE 21** - 2.20 及以下版本:**JRE 17** ::: #### 数据库 Halo 目前支持以下数据库: - PostgreSQL - MySQL - MariaDB - H2 其中,H2 不需要单独运行,其他数据库需要单独安装并配置。一般情况下,推荐按照 [使用 Docker Compose 部署](https://docs.halo.run/guide/install/docker-compose.md) 文档将 Halo 和数据库容器编排在一起。 :::warning 不建议在生产环境使用 H2 不推荐在生产环境使用默认的 H2 数据库,这可能因为操作不当导致数据文件损坏。如果因为某些原因(如内存不足以运行独立数据库)必须要使用,建议按时[备份数据](https://docs.halo.run/guide/use/backup.md)。 ::: #### Web 服务器(可选) 如果你部署在生产环境,那么你很可能需要进行域名绑定,这时候我们推荐使用诸如 [Nginx](http://nginx.org/)、[Caddy](https://caddyserver.com/) 之类的 Web 服务器进行反向代理。但需要注意的是,目前 Halo 不支持代理到子目录(如:halo.run/blog)。 #### Wget(可选) 后续的文档中,我们会使用 wget 为例,用于下载所需要的文件,所以请确保服务器已经安装好了这个软件包。当然,下载文件不限制工具,如果你对其他工具熟悉,可以忽略。 #### Vim(可选) 后续的文档中,我们会使用 Vim 为例,用于修改一些必要的配置文件,所以同样请确保服务器已经安装了这个软件包。当然,修改文档也不限制工具,如果你对其他编辑软件熟悉,也可以忽略。 ## 浏览器支持 1. 用户前台:视主题所支持的情况而定。 2. 管理后台(Console 和个人中心):支持目前常见的现代浏览器,具体视 [Vue](https://vuejs.org/about/faq#what-browsers-does-vue-support) 框架的支持情况而定。 ## 名词解释 这里将列出后续文档中一些和 Halo 相关的名词含义。 ### \~(符号) 代表当前系统下的 [用户目录](https://zh.wikipedia.org/wiki/%E5%AE%B6%E7%9B%AE%E5%BD%95)。 ### 镜像 指 Halo 构建所产生的 [Docker 镜像](https://docs.docker.com/engine/reference/commandline/images/)。用户通过该镜像启动 Halo 应用。 ### 工作目录 指 Halo 所依赖的工作目录,在 Halo 运行的时候会在系统当前用户目录下产生一个 `.halo2` 的文件夹,绝对路径为 `~/.halo2`。里面通常包含下列目录或文件: 1. `db`:存放 H2 Database 的物理文件,如果你使用其他数据库,那么不会存在这个目录。 2. `themes`:里面包含用户所安装的主题。 3. `plugins`:里面包含用户所安装的插件。 4. `attachments`:附件目录。 5. `logs`:运行日志目录。 6. `application.yaml`:配置文件(可选),具体配置方式可查阅 [配置说明](https://docs.halo.run/guide/install/config.md)。 7. `backups`:备份文件目录。 8. `static`:虚拟的根文件目录,需要手动创建。 > 如果你使用的 Docker 部署,请不要忽略 `~/.halo2` 的目录映射。 ### 主题 包含了各种站点页面模板的资源包。用户访问 Halo 站点浏览到的内容及样式,由 Halo 管理端所配置使用的主题所决定。 相关使用文档:[主题管理相关功能说明](https://docs.halo.run/guide/use/themes.md) ### 插件 用于扩展 Halo 功能的软件包。插件独立于 Halo 核心应用,可以单独安装、升级、卸载。 相关使用文档:[插件管理相关功能说明](https://docs.halo.run/guide/use/plugins.md) ## 许可证 Halo 使用 [GPL-3.0](https://github.com/halo-dev/halo/blob/main/LICENSE) 协议开源,使用和分发时请遵守开源协议。 ## 贡献者 欢迎通过 Bug 反馈、功能建议和社区讨论参与 Halo 项目建设,具体方式请参阅[问题反馈](https://docs.halo.run/guide/contribution/issue.md)与[贡献政策](https://docs.halo.run/guide/contribution/pr.md)。 Halo 项目贡献者 ## 项目状态 ![Halo 项目活跃度](https://repobeats.axiom.co/api/embed/ad008b2151c22e7cf734d2688befaa795d593b95.svg "Halo 项目活跃度") --- url: https://docs.halo.run/guide/demo.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 在线体验 无需安装或部署,即可访问以下演示环境体验 Halo: - 站点地址:[https://demo.halocms.site](https://demo.halocms.site) - 管理后台:[https://demo.halocms.site/console](https://demo.halocms.site/console) - 用户名:`demo` - 密码:`P@ssw0rd123..` :::warning 注意 演示环境仅供功能体验,请勿上传或填写敏感信息。 ::: 如需在本地搭建体验环境,请参考[《如何在本地快速体验 Halo》](https://www.halo.run/archives/halo-local-quickstart)。 --- url: https://docs.halo.run/guide/install/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 安装 Halo ## 使用 Docker Compose 部署 ### [使用 Docker Compose 部署](/guide/install/docker-compose.md) - [环境搭建](/guide/install/docker-compose.md#环境搭建) - [部署 Halo](/guide/install/docker-compose.md#部署-halo) - [升级 Halo](/guide/install/docker-compose.md#升级-halo) - [反向代理](/guide/install/docker-compose.md#反向代理) ## 使用 Docker 部署 ### [使用 Docker 部署](/guide/install/docker.md) - [环境搭建](/guide/install/docker.md#环境搭建) - [部署 Halo](/guide/install/docker.md#部署-halo) - [升级 Halo](/guide/install/docker.md#升级-halo) ## 使用 1Panel 部署 ### [使用 1Panel 部署](/guide/install/1panel.md) - [1Panel 简介](/guide/install/1panel.md#1panel-简介) - [安装 Halo 应用](/guide/install/1panel.md#安装-halo-应用) - [创建网站](/guide/install/1panel.md#创建网站) - [升级 Halo](/guide/install/1panel.md#升级-halo) - [激活许可证](/guide/install/1panel.md#激活许可证) ## 使用宝塔面板部署 ### [使用宝塔面板部署](/guide/install/bt-panel.md) - [宝塔面板简介](/guide/install/bt-panel.md#宝塔面板简介) - [安装 Halo 应用](/guide/install/bt-panel.md#安装-halo-应用) - [配置网站和 SSL](/guide/install/bt-panel.md#配置网站和-ssl) - [升级 Halo](/guide/install/bt-panel.md#升级-halo) - [激活许可证](/guide/install/bt-panel.md#激活许可证) ## 使用 Helm 部署 ### [使用 Helm 部署](/guide/install/helm.md) - [先决条件](/guide/install/helm.md#先决条件) - [快速部署](/guide/install/helm.md#快速部署) - [卸载](/guide/install/helm.md#卸载) - [使用 MySQL 数据库](/guide/install/helm.md#使用-mysql-数据库) - [使用已有的数据库](/guide/install/helm.md#使用已有的数据库) - [创建 Ingress](/guide/install/helm.md#创建-ingress) - [其他参数](/guide/install/helm.md#其他参数) ## 使用 Podman 部署 ### [使用 Podman 部署](/guide/install/podman.md) - [前言](/guide/install/podman.md#前言) - [环境搭建](/guide/install/podman.md#环境搭建) - [部署 Halo](/guide/install/podman.md#部署-halo) - [升级 Halo](/guide/install/podman.md#升级-halo) - [使用 Podman Quadlet](/guide/install/podman.md#使用-podman-quadlet) ## 使用 JAR 文件部署 ### [使用 JAR 文件部署](/guide/install/jar-file.md) - [依赖检查](/guide/install/jar-file.md#依赖检查) - [安装](/guide/install/jar-file.md#安装) - [作为服务运行](/guide/install/jar-file.md#作为服务运行) - [版本升级](/guide/install/jar-file.md#版本升级) - [反向代理](/guide/install/jar-file.md#反向代理) ## 使用离线包部署 ### [使用离线包部署](/guide/install/offline.md) - [下载安装包](/guide/install/offline.md#下载安装包) - [安装部署](/guide/install/offline.md#安装部署) ## 配置说明 ### [配置说明](/guide/install/config.md) - [配置方式](/guide/install/config.md#配置方式) - [配置列表](/guide/install/config.md#配置列表) - [Redis 集成](/guide/install/config.md#redis-集成) ## 云平台 ### [阿里云计算巢部署](/guide/install/cloud/alibaba-cloud-computenest.md) - [部署流程](/guide/install/cloud/alibaba-cloud-computenest.md#部署流程) ### [阿里云云市场部署](/guide/install/cloud/alibaba-cloud-market.md) - [购买服务器](/guide/install/cloud/alibaba-cloud-market.md#购买服务器) - [访问 Halo](/guide/install/cloud/alibaba-cloud-market.md#访问-halo) - [管理 Halo](/guide/install/cloud/alibaba-cloud-market.md#管理-halo) ### [腾讯云轻量应用模板](/guide/install/cloud/tencent-cloud-lighthouse.md) - [购买轻量应用服务器](/guide/install/cloud/tencent-cloud-lighthouse.md#购买轻量应用服务器) - [应用管理](/guide/install/cloud/tencent-cloud-lighthouse.md#应用管理) - [访问 Halo](/guide/install/cloud/tencent-cloud-lighthouse.md#访问-halo) - [1Panel 管理](/guide/install/cloud/tencent-cloud-lighthouse.md#1panel-管理) - [查看预装应用](/guide/install/cloud/tencent-cloud-lighthouse.md#查看预装应用) - [升级 Halo](/guide/install/cloud/tencent-cloud-lighthouse.md#升级-halo) - [绑定域名](/guide/install/cloud/tencent-cloud-lighthouse.md#绑定域名) ## 其他指南 ### [Nginx Proxy Manager 反向代理](/guide/install/other/nginxproxymanager.md) - [Halo 部署](/guide/install/other/nginxproxymanager.md#halo-部署) - [简介](/guide/install/other/nginxproxymanager.md#简介) - [说明](/guide/install/other/nginxproxymanager.md#说明) - [安装 Nginx Proxy Manager](/guide/install/other/nginxproxymanager.md#安装-nginx-proxy-manager) - [配置 Halo 的反向代理](/guide/install/other/nginxproxymanager.md#配置-halo-的反向代理) - [进阶配置:性能与安全(可选)](/guide/install/other/nginxproxymanager.md#进阶配置性能与安全可选) ### [Traefik 反向代理](/guide/install/other/traefik.md) - [Halo 部署](/guide/install/other/traefik.md#halo-部署) - [简介](/guide/install/other/traefik.md#简介) - [创建 Traefik](/guide/install/other/traefik.md#创建-traefik) - [配置 Halo 的反向代理](/guide/install/other/traefik.md#配置-halo-的反向代理) --- url: https://docs.halo.run/guide/install/docker-compose.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 使用 Docker Compose 部署 :::info 先阅读《写在前面》 在继续操作之前,我们推荐您先阅读[《写在前面》](https://docs.halo.run/guide/prepare.md),这可以快速帮助你了解 Halo。 ::: ## 环境搭建 - Docker 安装文档:[https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/) - Docker Compose 安装文档:[https://docs.docker.com/compose/install/](https://docs.docker.com/compose/install/) ## 部署 Halo ### 镜像说明 Halo 主要区分为[社区版和付费版](https://docs.halo.run/guide/prepare.md#%E5%8F%91%E8%A1%8C%E7%89%88%E6%9C%AC),这两个版本使用不同的 Docker 镜像,以下是 Docker Hub 的官方镜像地址: - [Halo 付费版镜像](https://hub.docker.com/r/halohub/halo-pro/tags):包括 [Halo 专业版](https://www.lxware.cn/halo?code=mcYhwMkn) 和 [Halo 商城版](https://www.lxware.cn/halo?code=mcYhwMkn),包含社区版的所有功能,并提供额外的付费功能,部分付费功能需要使用许可证激活 - [Halo 社区版镜像](https://hub.docker.com/r/halohub/halo/tags):使用 Halo 的[开源仓库](https://github.com/halo-dev/halo)构建,不包含任何付费功能,也不支持激活许可证 镜像名称由以下组成: ```bash # 付费版 halohub/halo-pro: # 社区版 halohub/halo: ``` `` 表示 Halo 的具体版本号,比如 `2.27.0`,版本命名方式遵循 [SemVer](https://semver.org/lang/zh-CN/),即 `..` 除了具体版本号的标签之外,Halo 还提供了 `:` 和 `:.` 的标签,比如: - `halohub/halo-pro:2`:代表整个 Halo 2 的最新版本 - `halohub/halo-pro:2.27`:代表 Halo 2.27 的最新版本 以上是 Docker Hub 的官方镜像地址,如果你的服务器因为网络原因导致拉取速度缓慢,也可以使用我们自行搭建的镜像库: - 付费版:`registry.fit2cloud.com/halo/halo-pro` - 社区版:`registry.fit2cloud.com/halo/halo` 后续文档将使用 `registry.fit2cloud.com/halo/halo-pro` 为例,如果你需要安装社区版,需要将 `halo-pro` 替换为 `halo`。 ### 开始搭建 ### 创建目录 在系统任意位置创建一个文件夹,此文档以 `~/halo` 为例。 ```bash mkdir ~/halo && cd ~/halo ``` :::info 妥善保存数据目录 注意:后续操作中,Halo 产生的所有数据都会保存在这个目录,请妥善保存。 ::: ### 创建 `docker-compose.yaml` 此文档提供几种场景的 Docker Compose 配置文件,请根据你的需要**选择一种**。 **Halo + PostgreSQL(推荐)** ```yaml {25-31,45} title="~/halo/docker-compose.yaml" services: halo: image: registry.fit2cloud.com/halo/halo-pro:2.27 restart: on-failure:3 depends_on: halodb: condition: service_healthy networks: halo_network: volumes: - ./halo2:/root/.halo2 ports: - "8090:8090" healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8090/actuator/health/readiness"] interval: 30s timeout: 5s retries: 5 start_period: 30s environment: # JVM 参数,默认为 -Xmx256m -Xms256m,可以根据实际情况做调整,置空表示不添加 JVM 参数 - JVM_OPTS=-Xmx256m -Xms256m command: - --spring.r2dbc.url=r2dbc:pool:postgresql://halodb/halo - --spring.r2dbc.username=halo # PostgreSQL 的密码,请保证与下方 POSTGRES_PASSWORD 的变量值一致。 - --spring.r2dbc.password=openpostgresql - --spring.sql.init.platform=postgresql # 外部访问地址,请根据实际需要修改 - --halo.external-url=http://localhost:8090/ halodb: image: postgres:15.4 restart: on-failure:3 networks: halo_network: volumes: - ./db:/var/lib/postgresql/data healthcheck: test: ["CMD", "pg_isready"] interval: 10s timeout: 5s retries: 5 environment: - POSTGRES_PASSWORD=openpostgresql - POSTGRES_USER=halo - POSTGRES_DB=halo - PGUSER=halo networks: halo_network: ``` :::info PostgreSQL 容器端口 此示例的 PostgreSQL 数据库容器默认没有设置端口映射,如果需要在容器外部访问数据库,可以自行在 `halodb` 服务中添加端口映射,PostgreSQL 的端口为 `5432`。 ::: **Halo + MySQL** ```yaml {25-31,53} title="~/halo/docker-compose.yaml" services: halo: image: registry.fit2cloud.com/halo/halo-pro:2.27 restart: on-failure:3 depends_on: halodb: condition: service_healthy networks: halo_network: volumes: - ./halo2:/root/.halo2 ports: - "8090:8090" healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8090/actuator/health/readiness"] interval: 30s timeout: 5s retries: 5 start_period: 30s environment: # JVM 参数,默认为 -Xmx256m -Xms256m,可以根据实际情况做调整,置空表示不添加 JVM 参数 - JVM_OPTS=-Xmx256m -Xms256m command: - --spring.r2dbc.url=r2dbc:pool:mysql://halodb:3306/halo - --spring.r2dbc.username=root # MySQL 的密码,请保证与下方 MYSQL_ROOT_PASSWORD 的变量值一致。 - --spring.r2dbc.password=o#DwN&JSa56 - --spring.sql.init.platform=mysql # 外部访问地址,请根据实际需要修改 - --halo.external-url=http://localhost:8090/ halodb: image: mysql:8.1.0 restart: on-failure:3 networks: halo_network: command: - --default-authentication-plugin=caching_sha2_password - --character-set-server=utf8mb4 - --collation-server=utf8mb4_general_ci - --explicit_defaults_for_timestamp=true volumes: - ./mysql:/var/lib/mysql - ./mysqlBackup:/data/mysqlBackup healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "--silent"] interval: 3s retries: 5 start_period: 30s environment: # 请修改此密码,并对应修改上方 Halo 服务的 SPRING_R2DBC_PASSWORD 变量值 - MYSQL_ROOT_PASSWORD=o#DwN&JSa56 - MYSQL_DATABASE=halo networks: halo_network: ``` :::info MySQL 容器端口 此示例的 MySQL 数据库容器默认没有设置端口映射,如果需要在容器外部访问数据库,可以自行在 `halodb` 服务中添加端口映射,MySQL 的端口为 `3306`。 ::: **Halo + H2** :::warning 不建议在生产环境使用 H2 不推荐在生产环境使用默认的 H2 数据库,这可能因为操作不当导致数据文件损坏。如果因为某些原因(如内存不足以运行独立数据库)必须要使用,建议按时[备份数据](https://docs.halo.run/guide/use/backup.md)。 ::: ```yaml {21} title="~/halo/docker-compose.yaml" services: halo: image: registry.fit2cloud.com/halo/halo-pro:2.27 restart: on-failure:3 volumes: - ./halo2:/root/.halo2 ports: - "8090:8090" healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8090/actuator/health/readiness"] interval: 30s timeout: 5s retries: 5 start_period: 30s environment: # JVM 参数,默认为 -Xmx256m -Xms256m,可以根据实际情况做调整,置空表示不添加 JVM 参数 - JVM_OPTS=-Xmx256m -Xms256m command: # 外部访问地址,请根据实际需要修改 - --halo.external-url=http://localhost:8090/ ``` **使用外部数据库** ```yaml {5,13-20} title="~/halo/docker-compose.yaml" services: halo: image: registry.fit2cloud.com/halo/halo-pro:2.27 restart: on-failure:3 network_mode: "host" volumes: - ./halo2:/root/.halo2 environment: # JVM 参数,默认为 -Xmx256m -Xms256m,可以根据实际情况做调整,置空表示不添加 JVM 参数 - JVM_OPTS=-Xmx256m -Xms256m command: # 修改为自己已有的 MySQL 配置 - --spring.r2dbc.url=r2dbc:pool:mysql://localhost:3306/halo - --spring.r2dbc.username=root - --spring.r2dbc.password= - --spring.sql.init.platform=mysql # 外部访问地址,请根据实际需要修改 - --halo.external-url=http://localhost:8090/ # 端口号 默认8090 - --server.port=8090 ``` :::info 外部数据库需预先创建 使用外部数据库时,需要提前手动创建好数据库,以 MySQL 为例: ```sql create database halo character set utf8mb4 collate utf8mb4_bin; ``` ::: 运行参数详解: | 参数名 | 描述 | | -------------------------- | ---------------------------------------------- | | `spring.r2dbc.url` | 数据库连接地址,详细可查阅下方的 `数据库配置` | | `spring.r2dbc.username` | 数据库用户名 | | `spring.r2dbc.password` | 数据库密码 | | `spring.sql.init.platform` | 数据库平台名称,支持 `postgresql`、`mysql`、`mariadb`、`h2` | | `halo.external-url` | 外部访问链接,如果需要在公网访问,需要配置为实际访问地址 | 数据库配置: | 链接方式 | 链接地址格式 | `spring.sql.init.platform` | | -------------- | ---------------------------------------------------------------------------------- | -------------------------- | | PostgreSQL(推荐) | `r2dbc:pool:postgresql://{HOST}:{PORT}/{DATABASE}` | postgresql | | MySQL | `r2dbc:pool:mysql://{HOST}:{PORT}/{DATABASE}` | mysql | | MariaDB | `r2dbc:pool:mariadb://{HOST}:{PORT}/{DATABASE}` | mariadb | | H2 Database | `r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE` | h2 | :::info 查看完整配置 为了保持部署流程的简洁,此文档仅提供了必要的配置示例,完整的配置选项列表可查阅:[配置说明](https://docs.halo.run/guide/install/config.md) ::: ### 启动 Halo 服务 ```bash docker compose up -d ``` 实时查看日志: ```bash docker compose logs -f ``` ### 测试访问 用浏览器访问 /console 即可进入 Halo 管理页面,首次启动会进入初始化页面。 :::tip 配置域名访问 如果需要配置域名访问,建议先配置好反向代理以及域名解析再进行初始化。如果通过 `http://ip:端口号` 的形式无法访问,请到服务器厂商后台将运行的端口号添加到安全组,如果服务器使用了 Linux 面板,请检查此 Linux 面板是否有还有安全组配置,需要同样将端口号添加到安全组。 ::: ### 激活许可证 可以参考 [许可证激活](https://docs.halo.run/guide/use/activate.md) 进行激活,社区版无需此步骤。 ## 升级 Halo ### 备份数据 可以参考 [备份与恢复](https://docs.halo.run/guide/use/backup.md) 进行完整备份(可选,但推荐备份)。 ### 更新 Halo 服务 修改 `docker-compose.yaml` 中配置的镜像版本。 ```yaml {3} services: halo: image: registry.fit2cloud.com/halo/halo-pro:2.27 ``` ```bash docker compose up -d ``` ## 反向代理 你可以在下面的反向代理软件中任选一项,我们假设你已经安装好了其中一项,并对其的基本操作有一定了解。如果你对它们没有任何了解,可以参考我们更为详细的反向代理文档: 1. 使用 [Nginx Proxy Manager](https://docs.halo.run/guide/install/other/nginxproxymanager.md) 2. 使用 [Traefik](https://docs.halo.run/guide/install/other/traefik.md) ### Nginx ```nginx {2,7,10} upstream halo { server 127.0.0.1:8090; } server { listen 80; listen [::]:80; server_name www.yourdomain.com; client_max_body_size 1024m; location / { proxy_pass http://halo; proxy_set_header HOST $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } } ``` ### Caddy 2 ```txt {1,5} www.yourdomain.com encode gzip reverse_proxy 127.0.0.1:8090 ``` ### Traefik 更新 halo 容器组的配置 1. `networks` 中引入已存在的网络 `traefik`(此网络需要 [提前创建](https://docs.halo.run/guide/install/other/traefik.md#%E5%88%9B%E5%BB%BA-traefik)) 2. `services.halo.networks` 中添加网络 `traefik` 3. 修改外部地址为你的域名 4. 声明路由规则、开启 TLS ```yaml {2-3,14,18,23-29} networks: traefik: external: true halo: services: halo: image: registry.fit2cloud.com/halo/halo-pro:2.27 restart: on-failure:3 volumes: - ./halo2:/root/.halo2 networks: - traefik - halo command: # 外部访问地址,请根据实际需要修改 - --halo.external-url=https://yourdomain.com labels: traefik.enable: "true" traefik.docker.network: traefik traefik.http.routers.halo.rule: Host(`yourdomain.com`) traefik.http.routers.halo.tls: "true" traefik.http.routers.halo.tls.certresolver: myresolver traefik.http.services.halo.loadbalancer.server.port: 8090 ``` --- url: https://docs.halo.run/guide/install/docker.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 使用 Docker 部署 :::info 先阅读《写在前面》 在继续操作之前,我们推荐您先阅读[《写在前面》](https://docs.halo.run/guide/prepare.md),这可以快速帮助你了解 Halo。 ::: :::warning 仅适合体验和测试 此文档仅提供使用默认 H2 数据库的 Docker 运行方式,主要用于体验和测试,在生产环境我们不推荐使用 H2 数据库,这可能因为操作不当导致数据文件损坏。如果因为某些原因(如内存不足以运行独立数据库)必须要使用,建议按时[备份数据](https://docs.halo.run/guide/use/backup.md)。 如果需要使用其他数据库部署,我们推荐使用 Docker Compose 部署:[使用 Docker Compose 部署](https://docs.halo.run/guide/install/docker-compose.md) ::: ## 环境搭建 - Docker 安装文档:[https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/) ## 部署 Halo ### 镜像说明 Halo 主要区分为[社区版和付费版](https://docs.halo.run/guide/prepare.md#%E5%8F%91%E8%A1%8C%E7%89%88%E6%9C%AC),这两个版本使用不同的 Docker 镜像,以下是 Docker Hub 的官方镜像地址: - [Halo 付费版镜像](https://hub.docker.com/r/halohub/halo-pro/tags):包括 [Halo 专业版](https://www.lxware.cn/halo?code=mcYhwMkn) 和 [Halo 商城版](https://www.lxware.cn/halo?code=mcYhwMkn),包含社区版的所有功能,并提供额外的付费功能,部分付费功能需要使用许可证激活 - [Halo 社区版镜像](https://hub.docker.com/r/halohub/halo/tags):使用 Halo 的[开源仓库](https://github.com/halo-dev/halo)构建,不包含任何付费功能,也不支持激活许可证 镜像名称由以下组成: ```bash # 付费版 halohub/halo-pro: # 社区版 halohub/halo: ``` `` 表示 Halo 的具体版本号,比如 `2.27.0`,版本命名方式遵循 [SemVer](https://semver.org/lang/zh-CN/),即 `..` 除了具体版本号的标签之外,Halo 还提供了 `:` 和 `:.` 的标签,比如: - `halohub/halo-pro:2`:代表整个 Halo 2 的最新版本 - `halohub/halo-pro:2.27`:代表 Halo 2.27 的最新版本 以上是 Docker Hub 的官方镜像地址,如果你的服务器因为网络原因导致拉取速度缓慢,也可以使用我们自行搭建的镜像库: - 付费版:`registry.fit2cloud.com/halo/halo-pro` - 社区版:`registry.fit2cloud.com/halo/halo` 后续文档将使用 `registry.fit2cloud.com/halo/halo-pro` 为例,如果你需要安装社区版,需要将 `halo-pro` 替换为 `halo`。 ### 创建容器 ```bash docker run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2 -e JVM_OPTS="-Xmx256m -Xms256m" registry.fit2cloud.com/halo/halo-pro:2.27 ``` :::info 默认使用 H2 数据库 注意:此命令默认使用自带的 H2 Database 数据库。如需使用 PostgreSQL,请参考:[使用 Docker Compose 部署](https://docs.halo.run/guide/install/docker-compose.md) ::: - **-it**:开启输入功能并连接伪终端 - **-d**:后台运行容器 - **--name**:为容器指定一个名称 - **-p**:端口映射,格式为 `主机(宿主)端口:容器端口` ,可在 `application.yaml` 配置。 - **-v**:工作目录映射。形式为:`-v 宿主机路径:/root/.halo2`,后者不能修改。 运行参数详解: | 参数名 | 描述 | | -------------------------- | ---------------------------------------------- | | `spring.r2dbc.url` | 数据库连接地址,详细可查阅下方的 `数据库配置` | | `spring.r2dbc.username` | 数据库用户名 | | `spring.r2dbc.password` | 数据库密码 | | `spring.sql.init.platform` | 数据库平台名称,支持 `postgresql`、`mysql`、`mariadb`、`h2` | | `halo.external-url` | 外部访问链接,如果需要在公网访问,需要配置为实际访问地址 | 数据库配置: | 链接方式 | 链接地址格式 | `spring.sql.init.platform` | | -------------- | ---------------------------------------------------------------------------------- | -------------------------- | | PostgreSQL(推荐) | `r2dbc:pool:postgresql://{HOST}:{PORT}/{DATABASE}` | postgresql | | MySQL | `r2dbc:pool:mysql://{HOST}:{PORT}/{DATABASE}` | mysql | | MariaDB | `r2dbc:pool:mariadb://{HOST}:{PORT}/{DATABASE}` | mariadb | | H2 Database | `r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE` | h2 | :::info 查看完整配置 为了保持部署流程的简洁,此文档仅提供了必要的配置示例,完整的配置选项列表可查阅:[配置说明](https://docs.halo.run/guide/install/config.md) ::: ### 测试访问 用浏览器访问 `/console` 即可进入 Halo 管理页面,首次启动会进入初始化页面。 :::tip 初始化前配置访问地址 如果需要配置域名访问,建议先配置好反向代理以及域名解析再进行初始化。如果通过 `http://ip:端口号` 的形式无法访问,请到服务器厂商后台将运行的端口号添加到安全组,如果服务器使用了 Linux 面板,请检查此 Linux 面板是否有还有安全组配置,需要同样将端口号添加到安全组。 ::: ### 激活许可证 可以参考 [许可证激活](https://docs.halo.run/guide/use/activate.md) 进行激活,社区版无需此步骤。 ## 升级 Halo ### 备份数据 可以参考 [备份与恢复](https://docs.halo.run/guide/use/backup.md) 进行完整备份(可选,但推荐备份)。 ### 拉取新版本镜像 ```bash docker pull registry.fit2cloud.com/halo/halo-pro:2.27 ``` ### 停止运行中的容器 ```bash docker stop halo docker rm halo ``` ### 更新 Halo 修改版本号后,按照最初安装的方式,重新创建容器即可。 ```bash docker run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2 -e JVM_OPTS="-Xmx256m -Xms256m" registry.fit2cloud.com/halo/halo-pro:2.27 ``` --- url: https://docs.halo.run/guide/install/1panel.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 使用 1Panel 部署 :::info 先阅读《写在前面》 在继续操作之前,我们推荐您先阅读[《写在前面》](https://docs.halo.run/guide/prepare.md),这可以快速帮助你了解 Halo。 ::: ## 1Panel 简介 [1Panel](https://1panel.cn) 是一个现代化、开源的 Linux 服务器运维管理面板。 ![1Panel 截图](/img/install/1panel/1panel.png) ### 功能 - **快速建站**:深度集成 WordPress 和 Halo,域名绑定、SSL 证书配置等一键搞定。 - **高效管理**:通过 Web 端轻松管理 Linux 服务器,包括应用管理、主机监控、文件管理、数据库管理、容器管理等。 - **安全可靠**:最小漏洞暴露面,提供防火墙和安全审计等功能。 - **一键备份**:支持一键备份和恢复,备份数据云端存储,永不丢失。 ### 安装 关于 1Panel 的安装部署与基础功能介绍,请参考 [1Panel 官方文档](https://1panel.cn/docs/installation/online_installation/)。此处假设你已经完成了 1Panel 的安装部署,并对其功能有了基础了解。 ### 安装基础软件 在安装 Halo 之前,我们需要先在 1Panel 上安装好所需的软件,包括 OpenResty 和数据库(MySQL、PostgreSQL、MariaDB 都可以)。在接下来的文档中,我们会默认你已经安装好了这两个软件,并不再赘述。 ![OpenResty 和 MySQL](/img/install/1panel/openresty-mysql.png) ## 安装 Halo 应用 进入应用商店应用列表,选择其中的 Halo 应用进行安装。 ![选择 Halo 应用](/img/install/1panel/app-store-halo.png) 在应用详情页选择最新的 Halo 版本进行安装。 ![选择 Halo 版本](/img/install/1panel/install-halo.png) 参数说明: - **名称**:要创建的 Halo 应用的名称。 - **版本**:选择最新的版本即可。 - **数据库服务**:Halo 应用使用的数据库应用,支持下拉选择已安装的数据库应用,1Panel 会自动配置 Halo 使用该数据库。 - **数据库名**:Halo 应用使用的数据库名称,1Panel 会在选中的数据库中自动创建这个数据库。 - **数据库用户**:Halo 应用使用的数据库用户名,1Panel 会在选中的数据库中自动创建这个用户,并添加对应的数据库授权。 - **数据库用户密码**:Halo 应用使用的数据库用户密码,1Panel 会在选中的数据库中自动为上一步创建的用户配置该密码。 - **外部访问地址**:Halo 应用的最终访问地址,如果有为 Halo 规划域名,需要配置为域名格式,例如 `http://halo.example.com`。否则配置为 `http://服务器IP:PORT`,例如 `http://192.168.1.1:8090`。 - **端口**:Halo 应用的服务端口。 开始安装后页面自动跳转到已安装应用列表,等待刚刚安装的 Halo 应用变为已启动状态。 ![Halo 运行状态](/img/install/1panel/halo-status.png) ## 创建网站 完成 Halo 应用的安装后,此时并不会自动创建一个网站,我们需要手动创建一个网站,然后将 Halo 应用绑定到这个网站上才能使用域名访问。 点击 1Panel 菜单的 **网站**,进入网站列表页,点击 **创建网站** 按钮。 ![创建网站](/img/install/1panel/new-site.png) 1. 在已装应用中选择我们刚刚新建的 Halo 应用。 2. 正确填写主域名,需要注意的是需要提前解析好域名到服务器 IP。 最后,点击确认按钮,等待网站创建完成即可访问网站进行 [初始化](https://docs.halo.run/guide/setup.md)。 ![网站列表](/img/install/1panel/site.png) ## 升级 Halo :::info 新版本上架有延迟 当 Halo 发布新版本之后,并不会在 1Panel 的应用商店中实时查看到新版本,通常需要等待一段时间才会显示,这取决于 1Panel 的应用商店更新频率。 ::: :::warning 升级前查看更新日志 目前 1Panel 不支持在升级应用的时候查看应用的更新日志,所以建议在升级前前往 [Halo 版本发布](https://releases.halo.run/) 查看对应版本的更新日志,了解新版本的变化。 ::: 当 Halo 在 1Panel 的应用商店有更新时,可以在 **应用商店** 的 **可升级** 选项卡中看到 Halo 应用的升级按钮。 ![升级 Halo](/img/install/1panel/upgrade.png) 点击 **升级** 按钮后,可以在升级界面中选择最新的 Halo 版本,最后点击 **确认** 按钮即可完成升级。 ![升级 Halo](/img/install/1panel/upgrade-2.png) ## 激活许可证 可以参考 [许可证激活](https://docs.halo.run/guide/use/activate.md) 进行激活,社区版无需此步骤。 --- url: https://docs.halo.run/guide/install/bt-panel.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 使用宝塔面板部署 :::info 先阅读《写在前面》 在继续操作之前,我们推荐您先阅读[《写在前面》](https://docs.halo.run/guide/prepare.md),这可以快速帮助你了解 Halo。 ::: ## 宝塔面板简介 宝塔面板是一个常见的 Linux 服务器运维面板,提供网站、数据库、SSL、Docker 等可视化管理能力。通过宝塔面板的 Docker 模块和应用商店,可以比较方便地完成 Halo 的安装、运行和升级。 ![宝塔 Docker 模块](/img/install/bt-panel/docker.png) ### 准备工作 在开始之前,需要确保你已经完成以下准备: - 已安装并可以正常登录宝塔面板。 - 已在服务器上安装宝塔的 Docker 模块。 - 已放行服务器的 `80` 和 `443` 端口。 - 如果计划使用域名访问 Halo,需要提前将域名解析到当前服务器。 ## 安装 Halo 应用 进入宝塔面板左侧的 **Docker**,在 **应用商店** 中搜索 `Halo`,然后点击 **安装**。 ![选择 Halo 应用](/img/install/bt-panel/halo-app.png) 在安装配置页面中,按照实际情况填写参数: ![安装 Halo](/img/install/bt-panel/install-halo.png) 参数说明: - **名称**:当前 Halo 应用的名称。 - **版本选择**:建议优先选择最新的稳定版本。 - **域名**:Halo 对外访问使用的域名,建议填写已经完成解析的域名。 - **允许外部访问**:如果希望直接通过 `IP:端口` 访问,可以启用此选项;如果只打算通过域名访问,通常不需要开启。 - **端口**:Halo 容器暴露的服务端口。 - **外部访问地址**:Halo 的最终访问地址,建议与实际访问地址保持一致,例如 `https://www.example.com`。 - **CPU 核心数限制**、**内存限制**:按服务器资源情况选填,不限制可以保持默认值。 - **编辑模板**:默认模板通常即可满足使用需求;如果需要调整镜像、挂载目录或其他编排参数,可以切换到自定义模板。 宝塔提供的 Halo 应用模板会自动创建 Halo 运行所需的容器。确认参数无误后,点击 **确定** 开始安装。 如果需要查看或调整底层的 Docker Compose 配置,可以切换到 **自定义** 模板模式: :::info 选择合适的镜像版本 宝塔的 Docker 应用商店的 Halo 版本可能会滞后于官方最新版本,通常建议自定义镜像版本,查看最新版本请前往 [Halo 版本发布](https://releases.halo.run/)。 此外,宝塔的默认编排是 Halo 社区版本,如果你想安装 Halo 专业版或者商城版,将镜像修改为 `registry.fit2cloud.com/halo/halo-pro` 即可。 ::: ![自定义 Compose 模板](/img/install/bt-panel/custom-compose.png) 安装完成后,进入 **Docker** 的 **已安装** 列表,等待 Halo 应用变为运行中状态。 ![已安装的 Halo 应用](/img/install/bt-panel/installed.png) ## 配置网站和 SSL 如果你在安装 Halo 时填写了域名,宝塔通常会同步创建对应的网站配置。你可以在已安装应用卡片中点击 **管理网站**,或者直接进入左侧菜单的 **网站** 查看站点状态。 ![网站列表](/img/install/bt-panel/ssl-status.png) 如果站点的 **SSL 证书** 一栏显示未部署,可以进入站点管理页面,在 **SSL** 标签页中申请证书。 ![申请 SSL 证书](/img/install/bt-panel/request-ssl.png) 证书申请成功后,即可通过你配置的域名使用 `https` 访问 Halo。首次访问时,根据页面提示完成 Halo 的[初始化](https://docs.halo.run/guide/setup.md)即可。 :::info 证书申请失败时的检查项 如果证书申请失败,建议优先检查域名解析是否生效,以及服务器的 `80`、`443` 端口是否已经正确放行。 ::: ## 升级 Halo 当需要升级 Halo 时,可以进入 **Docker** 的 **容器编排**,找到当前的 Halo 项目,修改镜像版本为最新版本,然后点击 **确定** 按钮即可完成升级。 :::info 查看 Halo 最新版本 查看最新版本请前往 [Halo 版本发布](https://releases.halo.run/)。 ::: ![升级 Halo](/img/install/bt-panel/update.png) 更新完成后,宝塔会重新拉取镜像并重建相关容器。建议升级前先备份 Halo 数据目录和数据库,并前往 [Halo 版本发布](https://releases.halo.run/) 查看对应版本的更新说明。 ## 激活许可证 可以参考 [许可证激活](https://docs.halo.run/guide/use/activate.md) 进行激活,社区版无需此步骤。 --- url: https://docs.halo.run/guide/install/helm.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 使用 Helm 部署 :::info 先阅读《写在前面》 在继续操作之前,我们推荐您先阅读[《写在前面》](https://docs.halo.run/guide/prepare.md),这可以快速帮助你了解 Halo。 ::: ## 先决条件 1. 拥有可用的 1.19 或更高版本的 Kubernetes 集群 2. 安装有 Helm 客户端 3.2 或更高的版本 3. 指定 StorageClass 自动创建存储卷时需要底层存储驱动支持 4. 用户对 Kubernetes 及 Helm 相关概念及如何使用有基本了解 ## 快速部署 通过以下命令可以使用默认安装参数快速部署 Halo。默认参数下该 Chart 会自动部署 PostgreSQL 数据库给 Halo 使用,同时 Halo 工作目录及 PostgreSQL 数据目录通过指定 StorageClass 的方式自动创建存储卷进行持久化。 ```bash # 添加 Halo 项目的 Helm Charts 仓库 helm repo add halo https://halo-sigs.github.io/charts/ # 从 chart 仓库中更新本地可用chart的信息 helm repo update # 使用默认参数,在当前的 Kubernetes namespace 中安装 Halo helm install halo halo/halo ``` 命令执行成功后会返回类似下文中的提示,通过提示中的命令可以获取到 NodePort 方式的 Halo 访问地址及默认的控制台管理员用户名和密码。 ```text NAME: halo LAST DEPLOYED: Sun Jun 25 15:49:53 2023 NAMESPACE: halo STATUS: deployed REVISION: 1 TEST SUITE: None NOTES: CHART NAME: halo CHART VERSION: 1.1.0 APP VERSION: 2.6.1 ** Please be patient while the chart is being deployed ** Your Halo site can be accessed through the following DNS name from within your cluster: halo.halo.svc.cluster.local (port 80) To access your Halo site from outside the cluster follow the steps below: 1. Get the Halo URL by running these commands: export NODE_PORT=$(kubectl get --namespace halo -o jsonpath="{.spec.ports[0].nodePort}" services halo) export NODE_IP=$(kubectl get nodes --namespace halo -o jsonpath="{.items[0].status.addresses[0].address}") echo "Halo URL: http://$NODE_IP:$NODE_PORT/" echo "Halo Console URL: http://$NODE_IP:$NODE_PORT/console" 2. Open a browser and access Halo using the obtained URL. 3. Login with the following credentials below to see your site: echo Username: admin echo Password: $(kubectl get secret --namespace halo halo -o jsonpath="{.data.halo-password}" | base64 -d) ``` :::info 默认 PostgreSQL 参数 - 使用 Halo Helm Chart 仓库中 [values.yaml](https://github.com/halo-sigs/charts/blob/main/charts/halo/values.yaml) 文件中的默认参数进行安装; - 关于 PostgreSQL 数据库的更多参数说明,请参考 [Bitnami PostgreSQL Chart](https://github.com/bitnami/charts/tree/main/bitnami/postgresql#parameters),在原有参数格式上增加 `postgresql.` 前缀即可。 ::: ## 卸载 使用命令 `helm uninstall halo` 可卸载已安装的 Halo 应用,其中 `halo` 为安装时指定的 Halo 应用名称。 :::warning 卸载前备份数据 卸载应用前请确认数据库及 Halo 工作空间中的文件已进行备份或不再需要。 ::: ## 使用 MySQL 数据库 当用户希望使用 MySQL 数据库而非默认的 PostgreSQL 数据库时,可以参考以下命令进行部署。 ```bash helm install halo halo/halo --set mysql.enabled=true --set postgresql.enabled=false ``` :::info 自动安装 MySQL 参数 - `mysql.enabled=true`:自动安装 MySQL 数据库; - `postgresql.enabled=false`:不自动安装 PostgreSQL 数据库; - 关于 mysql 的更多参数说明,请参考 [Bitnami MySQL Chart](https://github.com/bitnami/charts/tree/main/bitnami/mysql#parameters),在原有参数格式上增加 `mysql.` 前缀即可。 ::: ## 使用已有的数据库 当用户希望使用已有的数据库而非自动安装新数据库时,可以参考以下命令进行部署。 ```bash helm install halo halo/halo \ --set mysql.enabled=false \ --set postgresql.enabled=false \ --set externalDatabase.platform=mysql \ --set externalDatabase.host=mysql \ --set externalDatabase.port=3306 \ --set externalDatabase.user=halo \ --set externalDatabase.password=0P0gJrCyzz \ --set externalDatabase.database=halo ``` :::info 外部数据库参数 - `mysql.enabled=false`:不自动安装 MySQL 数据库; - `postgresql.enabled=false`:不自动安装 PostgreSQL 数据库; - `externalDatabase.platform=mysql`:外部数据库类型,例如 `postgresql`、`mysql`; - `externalDatabase.host=mysql`:外部数据库连接地址; - `externalDatabase.port=3306`:外部数据库连接端口; - `externalDatabase.user=halo`:外部数据库用户名; - `externalDatabase.password=0P0gJrCyzz`:外部数据库密码; - `externalDatabase.database=halo`:外部数据库库名; ::: ## 创建 Ingress 当用户希望通过 Ingress 将 Halo 应用暴露到 Kubernetes 集群外进行访问时,可以参考以下安装参数。 ```bash helm install halo halo/halo --set ingress.enabled=true --set ingress.hostname=demo.halo.run ``` 对于已有的 Halo 应用,可以通过如下命令更新应用参数,为 Halo 应用创建 Ingress。 ```bash helm upgrade halo halo/halo --set ingress.enabled=true --set ingress.hostname=demo.halo.run ``` ## 其他参数 完整参数列表请参考 Halo 项目的 [Helm Chart 仓库](https://github.com/halo-sigs/charts#parameters)。 --- url: https://docs.halo.run/guide/install/podman.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 使用 Podman 部署 ## 前言 :::info 先阅读《写在前面》 在继续操作之前,我们推荐您先阅读[《写在前面》](https://docs.halo.run/guide/prepare.md),这可以快速帮助你了解 Halo。 ::: :::info Podman 简介与适用场景 什么是 Podman ? Podman(全称 POD 管理器)是一款用于在 Linux® 系统上开发、管理和运行容器的开源工具。Podman 最初由红帽® 工程师联合开源社区一同开发,它可利用 lipod 库来管理整个容器生态系统。 Podman 采用无守护进程的包容性架构,因此可以更安全、更简单地进行容器管理,再加上 Buildah 和 Skopeo 等与之配套的工具和功能,开发人员能够按照自身需求来量身定制容器环境。 为什么选择 Podman 而不是 Docker ? 这个需要视情况而定,如果您的主机配置不是很高,您使用 Docker 时,因为 Docker 自带的守护进程可能会雪上加霜,它会大量占用您的资源。 而 Podman 采用无守护进程架构,而且容器是无根模式,您可以在占用资源极小的情况下运行镜像,并且获得很高的安全性。 而且 Podman 与 Docker 高度兼容,您不需要做特别配置即可将 Docker 容器运行在 Podman 上。 [什么是 Podman?](https://www.redhat.com/zh/topics/containers/what-is-podman) [Podman ArchWiki](https://wiki.archlinux.org/title/Podman) [Podman 官网](https://podman.io/) ::: :::tip 不建议在生产环境使用 H2 此文档提供使用默认 H2 数据库和 Postgresql 数据库的 Podman 运行示例,在生产环境我们不推荐使用 H2 数据库。 ::: ## 环境搭建 - Podman 安装文档:[https://podman.io/docs/installation](https://podman.io/docs/installation) :::tip 先阅读 Podman 官方文档 我们推荐您先阅读 Podman 官方文档对 Podman 有了相关了解后,再考虑通过 Linux 包管理系统安装 Podman 或者使用文档中指定的方式安装。 ::: ## 部署 Halo :::tip Podman 可直接使用 Docker 镜像 为什么是 Docker 镜像? 通过[前言](#前言)我们已经了解了 Podman,其中提到 **_Podman 与 Docker 高度兼容_** ,正是因为 Podman 完全是为了替代 Docker 而诞生,所以原本的 Docker 生态中的镜像我们可以无需更改直接使用。 ::: ### 镜像说明 Halo 主要区分为[社区版和付费版](https://docs.halo.run/guide/prepare.md#%E5%8F%91%E8%A1%8C%E7%89%88%E6%9C%AC),这两个版本使用不同的 Docker 镜像,以下是 Docker Hub 的官方镜像地址: - [Halo 付费版镜像](https://hub.docker.com/r/halohub/halo-pro/tags):包括 [Halo 专业版](https://www.lxware.cn/halo?code=mcYhwMkn) 和 [Halo 商城版](https://www.lxware.cn/halo?code=mcYhwMkn),包含社区版的所有功能,并提供额外的付费功能,部分付费功能需要使用许可证激活 - [Halo 社区版镜像](https://hub.docker.com/r/halohub/halo/tags):使用 Halo 的[开源仓库](https://github.com/halo-dev/halo)构建,不包含任何付费功能,也不支持激活许可证 镜像名称由以下组成: ```bash # 付费版 halohub/halo-pro: # 社区版 halohub/halo: ``` `` 表示 Halo 的具体版本号,比如 `2.27.0`,版本命名方式遵循 [SemVer](https://semver.org/lang/zh-CN/),即 `..` 除了具体版本号的标签之外,Halo 还提供了 `:` 和 `:.` 的标签,比如: - `halohub/halo-pro:2`:代表整个 Halo 2 的最新版本 - `halohub/halo-pro:2.27`:代表 Halo 2.27 的最新版本 以上是 Docker Hub 的官方镜像地址,如果你的服务器因为网络原因导致拉取速度缓慢,也可以使用我们自行搭建的镜像库: - 付费版:`registry.fit2cloud.com/halo/halo-pro` - 社区版:`registry.fit2cloud.com/halo/halo` 后续文档将使用 `registry.fit2cloud.com/halo/halo-pro` 为例,如果你需要安装社区版,需要将 `halo-pro` 替换为 `halo`。 ### 创建容器 ```bash mkdir -p ~/.halo2 podman run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2:Z registry.fit2cloud.com/halo/halo-pro:2.27 ``` :::info 默认使用 H2 数据库 注意:此命令默认使用自带的 H2 Database 数据库。如需使用 PostgreSQL,请参考:[使用 Docker Compose 部署](https://docs.halo.run/guide/install/docker-compose.md) ::: - **-it**:开启输入功能并连接伪终端 - **-d**:后台运行容器 - **--name**:为容器指定一个名称 - **-p**:端口映射,格式为 `主机(宿主)端口:容器端口` ,可在 `application.yaml` 配置。 - **-v**:工作目录映射。形式为:`-v 宿主机路径:/root/.halo2`,后者不能修改。 运行参数详解: | 参数名 | 描述 | | -------------------------- | ---------------------------------------------- | | `spring.r2dbc.url` | 数据库连接地址,详细可查阅下方的 `数据库配置` | | `spring.r2dbc.username` | 数据库用户名 | | `spring.r2dbc.password` | 数据库密码 | | `spring.sql.init.platform` | 数据库平台名称,支持 `postgresql`、`mysql`、`mariadb`、`h2` | | `halo.external-url` | 外部访问链接,如果需要在公网访问,需要配置为实际访问地址 | 数据库配置: | 链接方式 | 链接地址格式 | `spring.sql.init.platform` | | -------------- | ---------------------------------------------------------------------------------- | -------------------------- | | PostgreSQL(推荐) | `r2dbc:pool:postgresql://{HOST}:{PORT}/{DATABASE}` | postgresql | | MySQL | `r2dbc:pool:mysql://{HOST}:{PORT}/{DATABASE}` | mysql | | MariaDB | `r2dbc:pool:mariadb://{HOST}:{PORT}/{DATABASE}` | mariadb | | H2 Database | `r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE` | h2 | :::info 查看完整配置 为了保持部署流程的简洁,此文档仅提供了必要的配置示例,完整的配置选项列表可查阅:[配置说明](https://docs.halo.run/guide/install/config.md) ::: ### 测试访问 用浏览器访问 `/console` 即可进入 Halo 管理页面,首次启动会进入初始化页面。 :::tip 初始化前配置访问地址 如果需要配置域名访问,建议先配置好反向代理以及域名解析再进行初始化。如果通过 `http://ip:端口号` 的形式无法访问,请到服务器厂商后台将运行的端口号添加到安全组,如果服务器使用了 Linux 面板,请检查此 Linux 面板是否有还有安全组配置,需要同样将端口号添加到安全组。 ::: ### 激活许可证 可以参考 [许可证激活](https://docs.halo.run/guide/use/activate.md) 进行激活,社区版无需此步骤。 ## 升级 Halo ### 备份数据 可以参考 [备份与恢复](https://docs.halo.run/guide/use/backup.md) 进行完整备份(可选,但推荐备份)。 ### 拉取新版本镜像 ```bash podman pull registry.fit2cloud.com/halo/halo-pro:2.27 ``` ### 停止运行中的容器 ```bash podman stop halo podman rm halo ``` ### 更新 Halo 修改版本号后,按照最初安装的方式,重新创建容器即可。 ```bash podman run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2:Z registry.fit2cloud.com/halo/halo-pro:2.27 ``` ## 使用 [Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) :::tip 使用 Quadlet 实现开机启动 Podman 没有和 Docker 类似的管理进程,在低配置的主机上更友好。 但是使用 Podman 想要开机后自动启动,官方推荐一种和 systemd 服务类似的语法文件,即 Podman Quadlet。 ::: 下面是一个使用 Podstgresql 数据库的示例: ```bash mkdir -p /opt/podman-data/halo mkdir -p /etc/containers/systemd vim /etc/containers/systemd/halo.container ``` ```ini [Unit] Description=The halo container Wants=network-online.target After=network-online.target [Container] AutoUpdate=registry ContainerName=halo User=60000 Group=60000 UserNS=keep-id:uid=60000,gid=60000 Environment=JVM_OPTS="-Xmx512m -Xms256m" Environment=HALO_WORK_DIR="/.halo" Environment=SPRING_CONFIG_LOCATION="optional:classpath:/;optional:file:/.halo/" Environment=TZ=Asia/Shanghai Volume=/opt/podman-data/halo:/.halo:Z PublishPort=127.0.0.1:8090:8090 Image=ghcr.io/halo-dev/halo:2.27 Exec=--halo.external-url=https://localhost:8090 --spring.sql.init.platform=postgresql --spring.r2dbc.url=r2dbc:pool:postgresql://host.containers.internal:5432/my-db --spring.r2dbc.username=my-user --spring.r2dbc.password=my-password [Service] Restart=always RestartSec=30s TimeoutStartSec=900 TimeoutStopSec=70 [Install] WantedBy=multi-user.target default.target ``` ```bash systemctl daemon-reload systemctl start halo # 只需要systemctl start halo. # 之后重启会自动启动不需要enable服务. ``` Podman Quadlet 解析: `[Unit]` 部分: - Wants 和 After 字段指定了 Halo 在什么服务后启动。 `[Container]` 部分: - `AutoUpdate=registry`指定了自动拉取容器。你需要`systemctl enable --now podman-auto-update.timer`以启用容器自动更新。本文示例`ghcr.io/halo-dev/halo:2.27`,将会自动更新到`2.27`系列的最新 patch 版本,例如您创建容器时是`2.27.0`,假设后续官方发布`2.27.1`版本,容器会自动更新到`2.27.1`。 - `ContainerName=`指定了 systemd 将生成的服务名称。 - `User=60000 Group=60000 UserNS=keep-id:uid=60000,gid=60000` 限制容器以 id 60000 的用户运行,提高安全性。注意这个 id 60000 请根据你实际想要运行的用户名来修改,可通过`id user`获得你的用户的 id. - `Environment=`字段指定了容器的环境变量,其中你需要注意的是`Environment=HALO_WORK_DIR="/.halo"` `Environment=SPRING_CONFIG_LOCATION="optional:classpath:/;optional:file:/.halo/"`这两个变量中的`/.halo`路径。 - `Volume=`字段指定挂载到容器储存 Halo 配置文件的路径,请仔细观察`/opt/podman-data/halo:/.halo:Z`其中的`/.halo`要与上面需要注意的环境变量路径要一致,`:Z` 用于为挂载目录设置 SELinux 标签。 - `PublishPort=`和 docker -p 命令一致,即需要映射的端口。 - `Image=ghcr.io/halo-dev/halo` 即 Docker 镜像的地址,注意要完整的。比如`ghcr.io`这个路径就不能少,如果你没有配置 Podman 的 registries 文件,此路径就必不可少,建议写全。 - `Exec=` 即附加到 Halo 容器的 Command,具体变量参考上方的 DockerArgs。多个变量以空格分开。示例中的 `host.containers.internal` 指向宿主机,如果数据库位于其他主机,请替换为实际地址。 `[Service]` 部分: 即原生 systemd 语法 - `Restart` 指定遇到错误后总是重启容器 - `RestartSec` 重启的间隔时间 - `TimeoutStartSec` 启动容器的超时时间,建议不要修改,因为每次开机后 Podman 将自动拉取容器,这时也许耗时会很长,这些时间是算在启动时间中的。如果定义太小的时间,可能将导致 Podman 无法拉取容器镜像。 - `TimeoutStopSec` 停止容器时的超时时间,`systemctl stop halo` 假设使用这个命令,如果停止时间超过了`TimeoutStopSec`定义的时间,将会被系统 Kill. `[Install]` 部分: 此部分请查看 systemd 文档,不建议修改。 使用默认的 root 用户运行时无需定义 `User=60000 Group=60000 UserNS=keep-id:uid=60000,gid=60000` 与 `Environment=HALO_WORK_DIR="/.halo"` `Environment=SPRING_CONFIG_LOCATION="optional:classpath:/;optional:file:/.halo/"`, 示例: ```bash mkdir -p /opt/podman-data/halo mkdir -p /etc/containers/systemd vim /etc/containers/systemd/halo.container ``` ```ini # /etc/containers/systemd/halo.container [Unit] Description=The halo container Wants=network-online.target After=network-online.target [Container] AutoUpdate=registry ContainerName=halo Volume=/opt/podman-data/halo:/root/.halo2:Z PublishPort=127.0.0.1:8090:8090 Image=ghcr.io/halo-dev/halo:2.27 Exec=--halo.external-url=https://localhost:8090 --spring.sql.init.platform=postgresql --spring.r2dbc.url=r2dbc:pool:postgresql://host.containers.internal:5432/my-db --spring.r2dbc.username=my-user --spring.r2dbc.password=my-password [Service] Restart=always RestartSec=30s TimeoutStartSec=900 TimeoutStopSec=70 [Install] WantedBy=multi-user.target default.target ``` --- url: https://docs.halo.run/guide/install/jar-file.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 使用 JAR 文件部署 :::info 先阅读《写在前面》 在继续操作之前,我们推荐您先阅读[《写在前面》](https://docs.halo.run/guide/prepare.md),这可以快速帮助你了解 Halo。 ::: ## 依赖检查 在开始之前,需要确保服务器已经满足以下条件: 1. [Java](https://openjdk.org) 环境,版本要求: - 2.21 以上版本:**JRE 21** - 2.20 及以下版本:**JRE 17** 2. 数据库(任一) - [MySQL 5.7+](https://www.mysql.com) - [MariaDB](https://mariadb.org) - [PostgreSQL](https://www.postgresql.org) 由于 Linux 发行版本的差异以及包管理器的不同,此文档不会涉及到如何安装 Java 环境以及数据库,建议查阅对应依赖的官方文档进行安装。 ## 安装 ### 创建新的系统用户 :::info 不建议使用 root 用户运行 我们不推荐直接使用系统 root 用户来运行 Halo。如果你需要直接使用 root 用户,请跳过这一步。 ::: 创建一个名为 halo 的用户(名字可以随意) ```bash useradd -m halo ``` 为 halo 用户创建密码 ```bash passwd halo ``` 登录到 halo 账户 ```bash su - halo ``` ### 创建存放运行包的目录 > 这里以 `~/app` 为例 ```bash mkdir ~/app && cd ~/app ``` ### 下载运行包 :::info 选择对应版本的 JAR 文件 Halo 主要区分为[社区版和付费版](https://docs.halo.run/guide/prepare.md#%E5%8F%91%E8%A1%8C%E7%89%88%E6%9C%AC),这两个版本使用不同的 JAR 文件,以下是 JAR 文件下载地址: 1. [https://dl.halo.run](https://dl.halo.run) 2. [GitHub Releases(社区版)](https://github.com/halo-dev/halo/releases) 后续文档将使用 `halo-pro-.jar` 为例,如果需要使用社区版,将 `halo-pro` 改为 `halo` 即可。 ::: ```bash wget https://dl.halo.run/release/halo-pro-2.27.2.jar -O halo.jar ``` ### 创建 [工作目录](https://docs.halo.run/guide/prepare.md#%E5%B7%A5%E4%BD%9C%E7%9B%AE%E5%BD%95) ```bash mkdir ~/.halo2 && cd ~/.halo2 ``` ### 创建 Halo 配置文件 ```bash vim application.yaml ``` 将以下内容复制到 `application.yaml` 中,根据下面的配置说明进行配置。 ```yaml title="application.yaml" server: # 运行端口 port: 8090 spring: # 数据库配置,支持 MySQL、MariaDB、PostgreSQL、H2 Database,具体配置方式可以参考下面的数据库配置 r2dbc: url: r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE username: admin password: 123456 sql: init: mode: always # 需要配合 r2dbc 的配置进行改动 platform: h2 halo: # 工作目录位置 work-dir: ${user.home}/.halo2 # 外部访问地址 external-url: http://localhost:8090 # 附件映射配置,通常用于迁移场景 attachment: resource-mappings: - pathPattern: /upload/** locations: - migrate-from-1.x ``` 数据库配置说明: | 参数名 | 描述 | | -------------------------- | ---------------------------------------------- | | `spring.r2dbc.url` | 数据库连接地址,详细可查阅下方的 `配置对应关系` | | `spring.r2dbc.username` | 数据库用户名 | | `spring.r2dbc.password` | 数据库密码 | | `spring.sql.init.platform` | 数据库平台名称,支持 `postgresql`、`mysql`、`mariadb`、`h2` | 配置对应关系: | 链接方式 | 链接地址格式 | `spring.sql.init.platform` | | -------------- | ---------------------------------------------------------------------------------- | -------------------------- | | PostgreSQL(推荐) | `r2dbc:pool:postgresql://{HOST}:{PORT}/{DATABASE}` | postgresql | | MySQL | `r2dbc:pool:mysql://{HOST}:{PORT}/{DATABASE}` | mysql | | MariaDB | `r2dbc:pool:mariadb://{HOST}:{PORT}/{DATABASE}` | mariadb | | H2 Database | `r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE` | h2 | :::info 数据库连接参数 - HOST:数据库服务地址,如 `localhost` - PORT:数据库服务端口,如 `3306` - DATABASE:数据库名称,如 `halo`,需要提前创建,以 MySQL 为例: ```sql create database halo character set utf8mb4 collate utf8mb4_bin; ``` ::: :::warning 不建议在生产环境使用 H2 不推荐在生产环境使用默认的 H2 数据库,这可能因为操作不当导致数据文件损坏。如果因为某些原因(如内存不足以运行独立数据库)必须要使用,建议按时[备份数据](https://docs.halo.run/guide/use/backup.md)。 ::: :::info 查看完整配置 为了保持部署流程的简洁,此文档仅提供了必要的配置示例,完整的配置选项列表可查阅:[配置说明](https://docs.halo.run/guide/install/config.md) ::: 配置完成之后,保存即可。 ### 测试运行 Halo ```bash cd ~/app && java -Dfile.encoding=UTF-8 -jar halo.jar --spring.config.additional-location=optional:file:$HOME/.halo2/ ``` :::tip 自定义工作目录 如果指定了其他工作目录,请将 `$HOME/.halo2/` 替换为相应的绝对路径,并确保路径末尾带有 `/`。 ::: ### 测试访问 如果没有观察到异常日志,即可尝试访问 Halo 打开 `http://ip:端口号` 即可跳转到初始化页面。 :::info 测试运行不会持续 如测试启动正常,请继续看[作为服务运行](#作为服务运行)部分,第 8 步仅仅作为测试。当你关闭 ssh 连接之后,服务会停止。你可使用 CTRL+C 停止运行测试进程。 ::: :::tip 初始化前配置访问地址 如果需要配置域名访问,建议先配置好反向代理以及域名解析再进行初始化。如果通过 `http://ip:端口号` 的形式无法访问,请到服务器厂商后台将运行的端口号添加到安全组,如果服务器使用了 Linux 面板,请检查此 Linux 面板是否有还有安全组配置,需要同样将端口号添加到安全组。 ::: ### 激活许可证 可以参考 [许可证激活](https://docs.halo.run/guide/use/activate.md) 进行激活,社区版无需此步骤。 ## 作为服务运行 下面将介绍如何将 Halo 作为服务运行,以实现在关闭 ssh 连接后,Halo 仍然可以正常运行。 此文档以 Systemd 为例,也可以参考:[Installing Spring Boot Applications](https://docs.spring.io/spring-boot/docs/current/reference/html/deployment.html#deployment.installing) ### 切换账户 退出 halo 账户,登录到 root 账户 > 如果当前就是 root 账户,请略过此步骤。 ```bash exit ``` ### 创建 halo.service 文件 ```bash vim /etc/systemd/system/halo.service ``` 将以下内容复制到 `halo.service` 中,根据下面的配置说明进行配置。 ```ini {9,10} title="/etc/systemd/system/halo.service" [Unit] Description=Halo Service Documentation=https://docs.halo.run After=network-online.target Wants=network-online.target [Service] Type=simple User=USER ExecStart=/usr/bin/java -Dfile.encoding=UTF-8 -server -Xms256m -Xmx256m -jar JAR_PATH --spring.config.additional-location=optional:file:/home/halo/.halo2/ ExecStop=/bin/kill -s QUIT $MAINPID Restart=always StandardOutput=syslog StandardError=inherit [Install] WantedBy=multi-user.target ``` - **JAR_PATH**:Halo 运行包的绝对路径,例如 `/home/halo/app/halo.jar`,注意:此路径不支持 `~` 符号。 - **USER**:运行 Halo 的系统用户,如果有按照上方教程创建新的用户来运行 Halo,修改为你创建的用户名称即可。反之请删除 `User=USER`。 :::tip 确认 Java 路径与启动命令 请确保 `/usr/bin/java` 是正确无误的。建议将 `ExecStart` 中的命令复制出来运行一下,保证命令有效。如果指定了其他工作目录,请像上面一样改动。 ::: 配置完成之后,保存即可。 ### 重新加载 systemd ```bash systemctl daemon-reload ``` ### 运行服务 ```bash systemctl start halo ``` ### 在系统启动时启动服务 ```bash systemctl enable halo ``` 最后,你可以通过下面的命令查看服务日志: ```bash journalctl -n 20 -u halo ``` ## 版本升级 ### 备份数据 可以参考 [备份与恢复](https://docs.halo.run/guide/use/backup.md) 进行完整备份(可选,但推荐备份)。 ### 停止 Halo 服务 ```bash service halo stop ``` ### 下载新版本 下载新版本的 Halo 运行包,覆盖原有的运行包 ```bash wget https://dl.halo.run/release/halo-pro-2.27.2.jar -O /home/halo/app/halo.jar ``` :::info Halo 运行包下载地址 以下是官方维护的下载地址: 1. [https://dl.halo.run](https://dl.halo.run) 2. [GitHub Releases(社区版)](https://github.com/halo-dev/halo/releases) ::: ### 启动 Halo 服务 ```bash service halo start ``` ## 反向代理 你可以在下面的反向代理软件中任选一项,我们假设你已经安装好了其中一项,并对其的基本操作有一定了解。如果你对它们没有任何了解,可以参考我们更为详细的反向代理文档: 1. 使用 [Nginx Proxy Manager](https://docs.halo.run/guide/install/other/nginxproxymanager.md) ### Nginx ```nginx {2,7,10} upstream halo { server 127.0.0.1:8090; } server { listen 80; listen [::]:80; server_name www.yourdomain.com; client_max_body_size 1024m; location / { proxy_pass http://halo; proxy_set_header HOST $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } } ``` ### Caddy 2 ```txt {1,5} www.yourdomain.com encode gzip reverse_proxy 127.0.0.1:8090 ``` --- url: https://docs.halo.run/guide/install/offline.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 使用离线包部署 :::info 先阅读《写在前面》 在继续操作之前,我们推荐您先阅读[《写在前面》](https://docs.halo.run/guide/prepare.md),这可以快速帮助你了解 Halo。 ::: Halo 离线安装包使用 Docker + Docker Compose 的方式部署 Halo 及其他服务,安装包中内置了 Docker 程序和容器镜像文件,可以帮助用户在无法访问互联网的服务器上,完成 Halo 的安装部署。 ## 下载安装包 请自行前往[飞致云开源社区](https://community.fit2cloud.com/#/products/halo/downloads)下载 Halo 最新版本的安装包,并复制到目标机器的 /tmp 目录下。 ## 安装部署 ### 解压安装包 以 root 用户 ssh 登录到目标机器,并执行如下命令: ```bash cd /tmp # 解压安装包(halo-offline-installer-v2.17.0-amd64.tar.gz 为示例安装包名称,操作时可根据实际安装包名称替换) tar zxvf halo-offline-installer-v2.17.0-amd64.tar.gz ``` :::info 离线安装包目录结构 安装包目录说明 ```tree ├── docker # 离线安装 Docker 使用到的文件 │   ├── bin │   │   ├── containerd │   │   ├── containerd-shim-runc-v2 │   │   ├── ctr │   │   ├── docker │   │   ├── docker-compose │   │   ├── dockerd │   │   ├── docker-init │   │   ├── docker-proxy │   │   └── runc │   └── service │   └── docker.service ├── docker-compose.yaml # 包含 Halo 及数据库服务的 Docker Compose 文件 ├── .env # Docker Compose 文件使用的变量声明文件,部分参数从该文件中读取 ├── images # Halo 及数据库的容器镜像文件 │   ├── halo.tar.gz │   ├── mysql.tar.gz │   └── postgres.tar.gz ├── install.sh # 安装脚本 ├── LICENSE └── README.md ``` ::: ### 执行安装脚本 ```bash # 进入安装包目录(halo-offline-installer-v2.17.0-amd64 为示例安装包目录名称,操作时可根据实际安装包名称替换) cd halo-offline-installer-v2.17.0-amd64 # 运行安装脚本 /bin/bash install.sh ``` 根据脚本给出的提示,输入安装目录、服务端口、数据库信息等相关配置信息,等待脚本执行完成。 :::info 默认安装目录结构 假设采用默认安装位置 /opt/halo 完成安装,安装目录的文件结构如下: ```tree ├── data # 数据存储目录 │   ├── db # 数据库数据存储目录,挂载至数据库容器 │   └── halo # Halo 数据存储目录,挂载至 Halo 容器 │   ├── indices │   ├── keys │   ├── logs │   ├── plugins │   └── themes ├── docker-compose.yaml # Docker Compose 文件 ├── .env # Docker Compose 文件使用的变量声明文件,部分参数从该文件中读取 ├── install.log # 安装脚本日志文件 ├── LICENSE └── README.md ``` 安装完成后,可以直接进入 /opt/halo 目录,使用 docker-compose 命令完成后续维护操作,也可以修改 docker-compose.yaml 中的相关配置满足不同需求。 运行参数详解: | 参数名 | 描述 | | -------------------------- | ---------------------------------------------- | | `spring.r2dbc.url` | 数据库连接地址,详细可查阅下方的 `数据库配置` | | `spring.r2dbc.username` | 数据库用户名 | | `spring.r2dbc.password` | 数据库密码 | | `spring.sql.init.platform` | 数据库平台名称,支持 `postgresql`、`mysql`、`mariadb`、`h2` | | `halo.external-url` | 外部访问链接,如果需要在公网访问,需要配置为实际访问地址 | 数据库配置: | 链接方式 | 链接地址格式 | `spring.sql.init.platform` | | -------------- | ---------------------------------------------------------------------------------- | -------------------------- | | PostgreSQL(推荐) | `r2dbc:pool:postgresql://{HOST}:{PORT}/{DATABASE}` | postgresql | | MySQL | `r2dbc:pool:mysql://{HOST}:{PORT}/{DATABASE}` | mysql | | MariaDB | `r2dbc:pool:mariadb://{HOST}:{PORT}/{DATABASE}` | mariadb | | H2 Database | `r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE` | h2 | ::: ### 登录访问 用浏览器访问 /console 即可进入 Halo 管理页面,首次启动会进入初始化页面。 --- url: https://docs.halo.run/guide/install/config.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 配置说明 在前面的部署文档中,为了保证部署流程的简洁,只说明了运行所必须的配置,但除了运行之外,Halo 还提供了不少其他的配置以及我们所使用的 Web 框架的配置,这个文档我们将详细介绍 Halo 的完整配置。 ## 配置方式 Halo 支持通过多种方式进行配置,目前 [Docker Compose 部署文档](https://docs.halo.run/guide/install/docker-compose.md) 的示例是通过运行参数配置,[JAR 文件部署方式](https://docs.halo.run/guide/install/jar-file.md) 是通过配置文件进行配置。 ### 通过运行参数 通常我们在使用 Docker Compose 部署的时候推荐使用这种方式进行配置,配置方式为在 Docker Compose 配置文件的 `command` 添加对应的配置条目即可,比如: ```yaml {5-10} services: halo: image: registry.fit2cloud.com/halo/halo-pro:2.27 ... command: - --spring.r2dbc.url=r2dbc:pool:postgresql://halodb/halo - --spring.r2dbc.username=halo - --spring.r2dbc.password=openpostgresql - --spring.sql.init.platform=postgresql - --halo.external-url=http://localhost:8090/ ``` ### 通过配置文件 通常我们在使用 JAR 文件部署的时候更推荐使用这种方式进行配置,配置文件名称为 `application.yaml`,并且需要在运行的时候通过 `--spring.config.additional-location` 参数指定配置文件存放的目录,运行示例: ```bash java -jar halo.jar --spring.config.additional-location=optional:file:$HOME/.halo2/ ``` 配置示例: ```yaml title="~/.halo2/application.yaml" spring: r2dbc: url: r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE username: admin password: 123456 sql: init: mode: always platform: h2 ``` :::info 查看 JAR 文件部署步骤 完整的 JAR 文件部署文档可查阅:[使用 JAR 文件部署](https://docs.halo.run/guide/install/jar-file.md) ::: 当然,使用 Docker Compose 部署同样支持通过这种方式配置,只需要将 `application.yaml` 放在工作目录的挂载目录即可,示例: ```tree ├── docker-compose.yaml └── halo2 └── application.yaml ``` 其中,`docker-compose.yaml` 的 Halo 服务的 `volumes` 应该包含 `./halo2:/root/.halo2`。 ## 配置列表 ### Halo 独有配置 通常用于生产环境的配置: | 配置路径 | 说明 | 生产环境默认值 | | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | `halo.work-dir` | Halo [工作目录](https://docs.halo.run/guide/prepare.md#%E5%B7%A5%E4%BD%9C%E7%9B%AE%E5%BD%95),通常不建议修改 | `${user.home}/.halo2` | | `halo.external-url` | 网站的实际访问地址,如:`https://www.halo.run`。未配置时,初始化页面会根据当前请求预填外部访问地址 | -- | | `halo.use-absolute-permalink` | 永久链接是否生成为绝对地址,设置为 `true` 时,请确保正确配置了 `halo.external-url` | `false` | | `halo.security.frame-options.disabled` | 是否禁用 `X-Frame-Options` 响应头。设为 `true` 后将不再通过该响应头限制 iframe 嵌入 | `false` | | `halo.security.frame-options.mode` | iframe 嵌入模式,默认为同源,可设置的值为 `DENY`、`SAMEORIGIN` | `SAMEORIGIN` | | `halo.security.referrer-options.policy` | Referrer-Policy 是一个 HTTP 头部字段,用于控制浏览器在发送请求时如何处理 Referer 信息,可设置的值请参考 [https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Referrer-Policy](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Referrer-Policy) | `strict-origin-when-cross-origin` | | `halo.security.remember-me.token-validity` | 保持登录会话的有效期,默认为 14 天(14d) | `14d` | | `halo.security.basic-auth.disabled` | 是否禁用 API 的 Basic Auth 认证 | `true` | | `halo.security.two-factor-auth.disabled` | 是否禁用系统全局的两步验证 | `false` | | `halo.attachment.resource-mappings[0].pathPattern` | 附件资源代理匹配规则,这个设置通常适用于从其他平台迁移的场景 | `/upload/**` | | `halo.attachment.resource-mappings[0].locations` | 附件资源代理目录,只能放置在[工作目录](https://docs.halo.run/guide/prepare.md#%E5%B7%A5%E4%BD%9C%E7%9B%AE%E5%BD%95)的 `attachments` 目录 | `migrate-from-1.x` | | `halo.attachment.thumbnail.disabled` | 是否禁用附件缩略图功能,如果不需要此功能,可以选择禁用 | false | | `halo.attachment.thumbnail.concurrent-threads` | 生成附件缩略图的并发数 | 1 | | `halo.attachment.thumbnail.quality` | 附件缩略图的生成质量,数值为 0-1 之间 | - | 通常用于开发环境的配置: | 配置路径 | 说明 | 默认值 | | -------------------------- | ------------- | --- | | `halo.ui.proxy.endpoint` | 开发环境的 UI 代理地址 | -- | | `halo.ui.proxy.enabled` | 是否启用 UI 代理地址 | -- | | `halo.plugin.runtime-mode` | 插件的运行模式 | -- | ### Web 框架本身的配置 Halo 使用了 [Spring Boot](https://docs.spring.io/spring-boot/) 和 [Spring WebFlux](https://docs.spring.io/spring-framework/reference/web/webflux.html),完整的配置可查阅:[Common Application Properties](https://docs.spring.io/spring-boot/appendix/application-properties/index.html#appendix.application-properties.core),以下将列出关于 Halo 常用的配置: Web 服务相关: | 配置路径 | 说明 | 默认值 | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------- | | `server.port` | Web 服务端口 | `8090` | | `server.compression.enabled` | 是否开启 gzip 压缩 | `true` | | `spring.web.resources.cache.cachecontrol.max-age` | 设置静态资源的缓存存储的最大周期,超过这个时间缓存被认为过期 | `365d` | | `spring.web.resources.cache.cachecontrol.no-cache` | 设置静态资源响应头的 `Cache-Control` 为 `no-cache`,在发布缓存副本之前,强制要求缓存把请求提交给原始服务器进行验证(协商缓存验证) | `false` | | `spring.web.resources.cache.cachecontrol.use-last-modified` | 是否为静态资源添加 Last-Modified 响应头,Last-Modified 表示服务器上资源的最后修改时间。当浏览器第一次请求资源时,服务器会在响应头中包含这个字段 | `true` | | `spring.thymeleaf.cache` | 是否开启模版引擎缓存 | `true` | 数据库相关: | 配置路径 | 说明 | 默认值 | | -------------------------- | ---------------------------------------------- | --- | | `spring.r2dbc.url` | 数据库连接地址,详细可查阅下方的 `数据库配置` | -- | | `spring.r2dbc.username` | 数据库用户名 | -- | | `spring.r2dbc.password` | 数据库密码 | -- | | `spring.sql.init.platform` | 数据库平台名称,支持 `postgresql`、`mysql`、`mariadb`、`h2` | -- | 数据库配置: | 链接方式 | 链接地址格式 | `spring.sql.init.platform` | | ----------- | ---------------------------------------------------------------------------------- | -------------------------- | | PostgreSQL | `r2dbc:pool:postgresql://{HOST}:{PORT}/{DATABASE}` | postgresql | | MySQL | `r2dbc:pool:mysql://{HOST}:{PORT}/{DATABASE}` | mysql | | MariaDB | `r2dbc:pool:mariadb://{HOST}:{PORT}/{DATABASE}` | mariadb | | H2 Database | `r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE` | h2 | ## Redis 集成 :::note 仅限 Halo 付费版 限 [Halo 付费版](https://docs.halo.run/guide/prepare.md#%E5%8F%91%E8%A1%8C%E7%89%88%E6%9C%AC) 可用。 ::: Halo 付费版在 2.16 中新增了集成 Redis 的功能,目前提供将用户登录 Session 存入 Redis 的支持。 ### 配置方式 如果使用 Docker 或者 Docker Compose 部署,需要添加以下启动参数: ```yaml - --spring.data.redis.host=localhost # Redis 服务地址 - --spring.data.redis.port=6379 # Redis 服务端口 - --spring.data.redis.database=0 # Redis 数据库 - --spring.data.redis.password= # Redis 密码 - --halo.session.store-type=redis # 声明 session 存储方式为 redis,默认不配置则为 in-memory - --halo.redis.enabled=true # 启用 Redis 服务 ``` :::info 确认 Redis 主机地址 请特别注意 `spring.data.redis.host` 的指向,在 Docker 容器中,可能并不是 localhost,需要确保 Halo 容器中能够正常访问到你的 Redis 服务。 ::: Docker Compose 配置片段如下: ```yaml {25-32} version: "3" services: halo: image: registry.fit2cloud.com/halo/halo-pro:2.27 restart: on-failure:3 depends_on: halodb: condition: service_healthy networks: halo_network: volumes: - ./halo2:/root/.halo2 ports: - "8090:8090" healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8090/actuator/health/readiness"] interval: 30s timeout: 5s retries: 5 start_period: 30s command: ... # Redis 相关配置开始 - --spring.data.redis.host=localhost # Redis 服务地址 - --spring.data.redis.port=6379 # Redis 服务端口 - --spring.data.redis.database=0 # Redis 数据库 - --spring.data.redis.password= # Redis 密码 - --halo.session.store-type=redis # 声明 session 存储方式为 redis,默认不配置则为 in-memory - --halo.redis.enabled=true # Redis 相关配置结束 networks: halo_network: ``` 如果你是使用的 Docker Compose 部署 Halo,并且希望将 Redis 服务编排在一起,以下是配置示例: ```yaml {26-33,37-44} version: "3" services: halo: image: registry.fit2cloud.com/halo/halo-pro:2.27 restart: on-failure:3 depends_on: halodb: condition: service_healthy networks: halo_network: volumes: - ./halo2:/root/.halo2 ports: - "8090:8090" healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8090/actuator/health/readiness"] interval: 30s timeout: 5s retries: 5 start_period: 30s command: # ... # Redis 相关配置开始 - --spring.data.redis.host=redis # Redis 服务地址 - --spring.data.redis.port=6379 # Redis 服务端口 - --spring.data.redis.database=0 # Redis 数据库 - --spring.data.redis.password= # Redis 密码 - --halo.session.store-type=redis # 声明 session 存储方式为 redis,默认不配置则为 in-memory - --halo.redis.enabled=true # Redis 相关配置结束 # ... # 新增的 Redis 编排 redis: image: redis:7.2.5 networks: halo_network: volumes: - ./redis-data:/data restart: always networks: halo_network: ``` --- url: https://docs.halo.run/guide/install/cloud/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 云平台 ## 云平台 ### [阿里云计算巢部署](/guide/install/cloud/alibaba-cloud-computenest.md) - [部署流程](/guide/install/cloud/alibaba-cloud-computenest.md#部署流程) ### [阿里云云市场部署](/guide/install/cloud/alibaba-cloud-market.md) - [购买服务器](/guide/install/cloud/alibaba-cloud-market.md#购买服务器) - [访问 Halo](/guide/install/cloud/alibaba-cloud-market.md#访问-halo) - [管理 Halo](/guide/install/cloud/alibaba-cloud-market.md#管理-halo) ### [腾讯云轻量应用模板](/guide/install/cloud/tencent-cloud-lighthouse.md) - [购买轻量应用服务器](/guide/install/cloud/tencent-cloud-lighthouse.md#购买轻量应用服务器) - [应用管理](/guide/install/cloud/tencent-cloud-lighthouse.md#应用管理) - [访问 Halo](/guide/install/cloud/tencent-cloud-lighthouse.md#访问-halo) - [1Panel 管理](/guide/install/cloud/tencent-cloud-lighthouse.md#1panel-管理) - [查看预装应用](/guide/install/cloud/tencent-cloud-lighthouse.md#查看预装应用) - [升级 Halo](/guide/install/cloud/tencent-cloud-lighthouse.md#升级-halo) - [绑定域名](/guide/install/cloud/tencent-cloud-lighthouse.md#绑定域名) --- url: https://docs.halo.run/guide/install/cloud/alibaba-cloud-computenest.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 阿里云计算巢部署 阿里云计算巢提供了软件与资源的一体化交付的完善基础能力,助力服务商、开发者的提升服务能力和降低运营成本。计算巢已经支持快速部署 Halo 社区版。 ## 部署流程 ### 填写部署参数 访问计算巢 Halo 社区版服务[部署链接](https://computenest.console.aliyun.com/service/instance/create/default?type=user\&ServiceId=service-71b471d79c224520bba3),按提示填写部署参数: ![image.png](/img/install/alibab-cloud-computenest/deploy_1.jpg) ### 确认订单 参数填写完成后可以看到对应询价明细,确认参数后点击**下一步:确认订单**。确认订单完成后同意服务协议并点击**立即创建**进入部署阶段。 ### 获取访问链接 等待部署完成后进入服务实例管理,在控制台找到 Halo 服务访问链接。 ![image.png](/img/install/alibab-cloud-computenest/deploy_2.jpg) ### 访问 Halo 单击链接访问 Halo 服务。 ![image.png](/img/install/alibab-cloud-computenest/halo-setup.jpg) --- url: https://docs.halo.run/guide/install/cloud/alibaba-cloud-market.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 阿里云云市场部署 阿里云云市场提供围绕云计算产品的软件应用及服务,包括数据与 API、专业服务、基础软件、建站小程序、企业应用、安全、AI 与大数据计算、开发与运维、解决方案以及 IoT 十大类目市场,商品数量达上万种。 Halo 目前已上架至阿里云云市场,助力用户打造高效便捷的建站体验!本指南将介绍如何通过阿里云云市场购买、部署和使用 **Halo** 镜像,并提供购买服务器的优惠链接。 阿里云的 Halo 镜像不仅包括了已经部署好的 Halo 服务,还集成了 [1Panel](https://1panel.cn/) Linux 管理面板,可以更加方便地升级 Halo 和配置网站。 ## 购买服务器 ### 通过优惠链接 目前阿里云针对 Halo 用户推出了 5.5 折优惠,您可以通过以下链接购买服务器:[专属阿里云特价链接 5.5 折优惠](https://market.aliyun.com/common/dashi/halo?userCode=kmemb8jp) ![阿里云活动](/img/install/alibaba-cloud-market/buy-1.png) ![阿里云 ECS](/img/install/alibaba-cloud-market/buy-2.png) ### 创建 ECS 时选择 Halo 镜像 您也可以自行购买[阿里云服务器](https://ecs-buy.aliyun.com/ecs?userCode=kmemb8jp),并在选择镜像时选择云市场镜像并搜索 **Halo**,即可快速选择镜像进行部署。 ![阿里云 ECS](/img/install/alibaba-cloud-market/buy-3.jpeg) ![阿里云 ECS](/img/install/alibaba-cloud-market/buy-4.jpeg) 服务器初始化完成之后,进入 ECS 控制台即可看到服务器信息,如下图所示: ![阿里云 ECS 控制台](/img/install/alibaba-cloud-market/instance.png) ## 访问 Halo 首先需要在服务器的安全组开放 80 端口,然后就可以通过服务器的公网 IP 访问 Halo 了。 ![安全组 HTTP](/img/install/alibaba-cloud-market/iptables-http.jpeg) 首次访问会进入 Halo 初始化页面,填写初始化信息即可完成 Halo 的安装。 :::info 完成 Halo 初始化 Halo 初始化文档可查阅:[初始化](https://docs.halo.run/guide/setup.md) ::: ## 管理 Halo 该镜像的 Halo 使用 Docker Compose 方式部署,相关文件位于 `/opt/halo` 目录中。 ### 查看服务状态 ```bash cd /opt/halo docker compose ps ``` ### 升级 Halo 修改 `/opt/halo/docker-compose.yml` 中 Halo 容器使用的镜像标签为对应版本后,执行 `docker compose up -d` 命令即可进行升级。 --- url: https://docs.halo.run/guide/install/cloud/tencent-cloud-lighthouse.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 腾讯云轻量应用模板 腾讯云目前已经在轻量应用服务器的应用模板中添加了 Halo 的模板镜像,选择应用模板购买服务器之后就预装了 Halo 和 [1Panel](https://1panel.cn/)。 ## 购买轻量应用服务器 购买地址:[轻量应用服务器](https://buy.cloud.tencent.com/lighthouse?blueprintType=APP_OS\&blueprintOfficialId=lhbp-pjoqcja2\®ionId=8\&zone=ap-beijing-3\&bundleId=bundle_starter_mc_med2_01\&loginSet=AUTO\&from=lh-console) 然后在应用模板中选择 Halo,然后选择所需地域、可用区、套餐等,点击立即购买即可。 ![购买](/img/install/tencent-cloud-lighthouse/buy.png) ## 应用管理 ![应用管理](/img/install/tencent-cloud-lighthouse/application.png) 服务器初始化完成之后,进入应用 **管理页面** 即可看到 Halo 和 1Panel 的相关信息。 ## 访问 Halo 在 **应用管理** 页面中点击 **管理员登录地址** 即可进入 Halo 初始化页面,填写初始化信息即可完成 Halo 的安装。 ![Halo 初始化](/img/install/tencent-cloud-lighthouse/halo-setup.png) ## 1Panel 管理 ### 开放 1Panel 端口 在 **应用管理** 页面中可以看到预装的 1Panel 信息,首先需要将 1Panel 的端口开放,进入防火墙页面添加默认端口 8090 即可: ![防火墙](/img/install/tencent-cloud-lighthouse/firewall.png) ### 获取 1Panel 登录信息 登录到实例获取 1Panel 初始用户名和密码: ![1Panel 信息](/img/install/tencent-cloud-lighthouse/1panel-info.png) ### 登录 1Panel 然后就可以通过 `http://ip:8090/tencentcloud` 进入 1Panel 的管理后台: ![1Panel 登录](/img/install/tencent-cloud-lighthouse/1panel-login.png) ![1Panel 概览](/img/install/tencent-cloud-lighthouse/1panel-overview.png) ## 查看预装应用 为了保证 Halo 的正常运行,1Panel 中预装了 Halo 所需的环境,可以在 **应用商店** 的 **已安装** 选项卡中查看: ![预装应用](/img/install/tencent-cloud-lighthouse/installed-apps.png) 关于应用商店,可查阅 [1Panel 文档](https://1panel.cn/docs/user_manual/appstore/appstore/)。 ## 升级 Halo 在 **应用商店** 的 **可升级** 选项卡中检查 Halo 是否有更新,如果有新的版本,点击应用卡片的 **升级** 按钮即可。 ![升级 Halo](/img/install/tencent-cloud-lighthouse/upgrade.png) ## 绑定域名 :::info 准备可用域名 该操作要求用户有一个可用的域名,并在 DNS 服务商处添加对应的解析记录。 ::: 在 **网站** 页面中,此镜像默认添加了一个关联 Halo 应用的网站,你可以点击配置按钮然后添加自己的域名。 ![网站](/img/install/tencent-cloud-lighthouse/websites.png) ![添加域名](/img/install/tencent-cloud-lighthouse/domain.png) 除此之外,在绑定域名之后,还需要修改一下 Halo 的 **外部访问地址** 参数为实际的网站访问地址(如:[https://demo.halo.run](https://demo.halo.run)),否则 Halo 的部分功能或者插件可能会出现使用问题,只需要按照下图所示修改应用的参数然后点击确认即可。 ![修改外部访问地址](/img/install/tencent-cloud-lighthouse/external-url.png) 关于网站管理,可查阅 [1Panel 文档](https://1panel.cn/docs/user_manual/websites/websites/)。 --- url: https://docs.halo.run/guide/install/other/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 其他指南 ## 其他指南 ### [Nginx Proxy Manager 反向代理](/guide/install/other/nginxproxymanager.md) - [Halo 部署](/guide/install/other/nginxproxymanager.md#halo-部署) - [简介](/guide/install/other/nginxproxymanager.md#简介) - [说明](/guide/install/other/nginxproxymanager.md#说明) - [安装 Nginx Proxy Manager](/guide/install/other/nginxproxymanager.md#安装-nginx-proxy-manager) - [配置 Halo 的反向代理](/guide/install/other/nginxproxymanager.md#配置-halo-的反向代理) - [进阶配置:性能与安全(可选)](/guide/install/other/nginxproxymanager.md#进阶配置性能与安全可选) ### [Traefik 反向代理](/guide/install/other/traefik.md) - [Halo 部署](/guide/install/other/traefik.md#halo-部署) - [简介](/guide/install/other/traefik.md#简介) - [创建 Traefik](/guide/install/other/traefik.md#创建-traefik) - [配置 Halo 的反向代理](/guide/install/other/traefik.md#配置-halo-的反向代理) --- url: https://docs.halo.run/guide/install/other/nginxproxymanager.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # Nginx Proxy Manager 反向代理 ## Halo 部署 参见 [使用 Docker Compose 部署](https://docs.halo.run/guide/install/docker-compose.md) :::info 跳过 Halo 反向代理配置 `「反向代理」` 部分不进行操作,保证 Halo 服务运行无误即可。 ::: ## 简介 Nginx Proxy Manager 是一个可视化的 Nginx 反向代理管理器,支持在 Web UI 上管理反向代理的网站,支持申请免费的 SSL 证书并自动续签。 接下来会介绍如何使用 Nginx Proxy Manager 来反向代理 Halo,以下的 Nginx 安装方式均来自于 [Nginx Proxy Manager 官方文档](https://nginxproxymanager.com/guide/)。在开始之前,建议先阅读一遍官方文档,需要对其有一定的了解。 ## 说明 - 此文档需要对 Docker 和 Docker Compose 有一定的熟悉程度,并且已经提前在服务器上安装 - 在安装 Nginx Proxy Manager 之前,需要确保服务器没有其他占用了 80 和 443 端口的服务 - 需要对 Vim 有一定的熟悉程度 - 下文使用 NPM 简称 Nginx Proxy Manager ## 安装 Nginx Proxy Manager ### 创建工作目录 创建一个文件夹来存放 NPM 的 `docker-compose.yml` 文件: ```bash mkdir npm && cd npm vim docker-compose.yml ``` ### 创建 `docker-compose.yml` 将下面的内容复制到 `docker-compose.yml` 文件: ```yaml services: npm: image: "jc21/nginx-proxy-manager:latest" networks: - npm restart: unless-stopped ports: - "80:80" # Nginx 的 80 端口 - "443:443" # Nginx 的 443 端口 - "81:81" # Nginx Proxy Manager 的管理端口 volumes: - ./data:/data - ./letsencrypt:/etc/letsencrypt # 定义网络以便 NPM 与其他容器通信 networks: npm: name: npm attachable: true ``` :::info 提前开放所需端口 配置中提到的 80、443、81 端口需要提前在服务器提供商开放端口。 ::: ### 启动 NPM ```bash docker compose up -d ``` ### 创建管理员账户 在服务正常启动的情况下,现在已经可以通过 `http://{服务器公网 IP}:81` 访问 NPM 的网页端了。 :::info 无法访问时检查 81 端口 如果无法通过端口访问到 NPM,可以检查是否在服务器提供商开放了 `81` 端口。 ::: ![Nginx Proxy Manager Welcome](/img/nginx-proxy-manager/npm-welcome.png) 首次进入页面会提示创建管理员账户,需要注意的是:**邮箱一定要是合法邮箱,后续涉及到 SSL 证书签发**。 至此,我们已经完成了 Nginx Proxy Manager 的搭建,之后就可以用它给我们的 Halo 或者其他 Web 应用做反向代理了。 ## 配置 Halo 的反向代理 ### 配置 Halo 的 Docker 编排 将 `npm` 的网络加入到 Halo 的容器,之后就可以使用 Halo 的服务名作为 `hostname` 在 NPM 的内部进行反向代理了。 ```yaml {3-5,16-17} # 省略 networks: # 加入 npm 网络 npm: external: true halo: services: halo: image: registry.fit2cloud.com/halo/halo-pro:2.27 container_name: halo restart: on-failure:3 volumes: - ./halo2:/root/.halo2 networks: # 加入 npm 网络 - npm - halo # 省略 ``` 配置完成之后,需要使用 `docker compose up -d` 命令重建 Halo 容器。 ### 进入代理服务配置页面 进入 NPM 仪表盘,点击代理服务进入代理服务配置页面。 ![Nginx Proxy Manager Dashboard](/img/nginx-proxy-manager/npm-dashboard.png) ### 添加代理配置 ![Nginx Proxy Manager Add Proxy](/img/nginx-proxy-manager/npm-add-proxy.png) 1. **域名**:配置想要代理到 Halo 的域名,需要提前在域名服务商解析到当前服务器 2. **协议**:选择 http 3. **转发主机名 / IP**:填写 Halo 容器的服务名,比如上方示例中的 `halo` 4. **转发端口**:8090 以上配置为必须修改,界面中的其他配置可以按需选择,但其中的**缓存资源**不建议打开,可能不会完全遵守 Halo 的缓存策略。 配置完成之后,就可以尝试访问域名。 ### 配置 SSL 点击 SSL 选项卡,勾选 **申请新证书** 之后保存即可,同时建议勾选 **强制 SSL**,这样在访问 http 协议的地址时会自动跳转到 https 协议的地址。 ![Nginx Proxy Manager SSL](/img/nginx-proxy-manager/npm-ssl.png) 至此,我们已经完成了在 Nginx Proxy Manager 配置 Halo 反向代理并添加 SSL 证书的全过程。 ## 进阶配置:性能与安全(可选) 前文已完成基础反向代理与 SSL,对大多数博客已经够用。本节介绍在 NPM 中追加性能优化与安全响应头配置,两个目标: - **性能**:让 JavaScript、字体、JSON 等静态资源也参与 gzip 压缩;调大 proxy buffer 避免响应落盘 - **安全**:补齐 [securityheaders.com](https://securityheaders.com) 认可的安全响应头,默认可拿到 A 评级 :::info 通用反向代理优化 本节所有配置均为反代层通用优化,与具体主题无关,适用于任何 Halo 实例。 ::: 在 NPM 中添加自定义配置: ### 编辑 Halo 的代理记录 进入 NPM 仪表盘,在 Hosts → Proxy Hosts 点开 Halo 的代理记录进行编辑。 ### 打开高级设置 切换到 **Advanced** 标签页。 ### 添加自定义配置 把下面的内容粘贴到 **Custom Nginx Configuration** 文本框。 ### 保存配置 保存后 NPM 会自动 reload nginx,无需重建容器。 ### 推荐的自定义配置 ```nginx # ---- gzip 压缩:补齐 NPM 默认未覆盖的 JS、字体、JSON 等 MIME 类型 ---- gzip on; gzip_vary on; gzip_proxied any; gzip_comp_level 6; gzip_min_length 1024; gzip_types text/css text/javascript application/javascript application/x-javascript application/json application/xml application/rss+xml application/atom+xml image/svg+xml font/ttf font/otf font/woff font/woff2; # 若目录下存在 .gz 预压缩文件则优先使用 gzip_static on; # ---- proxy buffer:避免较大响应被临时写入磁盘 ---- proxy_buffers 16 32k; proxy_buffer_size 64k; proxy_busy_buffers_size 128k; # ---- 安全响应头:加 always 确保错误页也会返回 ---- add_header X-Content-Type-Options "nosniff" always; add_header X-Frame-Options "SAMEORIGIN" always; add_header X-XSS-Protection "1; mode=block" always; add_header Referrer-Policy "strict-origin-when-cross-origin" always; add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always; # HSTS 请在确认 HTTPS 稳定运行后再启用,见下文说明 # add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always; # ---- RSS 路径别名:Halo 默认 RSS 为 /rss.xml ---- rewrite ^/rss$ /rss.xml permanent; rewrite ^/feed$ /rss.xml permanent; ``` :::tip 避免重复声明 text/html `gzip_types` 不要再列 `text/html`,nginx 默认已经对其启用 gzip,重复声明会产生 `duplicate MIME type` 警告。 ::: ### 关于 HSTS `Strict-Transport-Security` 会告诉浏览器未来只能通过 HTTPS 访问当前域名。一旦启用且 `max-age` 较长,浏览器会缓存该策略直到过期,期间无法回退到 HTTP。因此建议: - 在 HTTPS 证书可正常续签、基础设施稳定运行 1–2 周后再启用 - 先从 `max-age=300`(5 分钟)起步验证,确认无误再逐步调大到 `63072000`(2 年) - `preload` 表示提交到浏览器内置 HSTS 列表,**提交后撤销非常困难**,确有必要再加 ### 验证配置是否生效 ```bash # 查看安全响应头 curl -I https://your-halo-domain.example.com/ \ | grep -iE "x-content-type|x-frame|x-xss|referrer-policy|permissions-policy" # 检查 JavaScript 是否启用了 gzip curl -IH "Accept-Encoding: gzip" \ https://your-halo-domain.example.com/themes//source/main.js \ | grep -i content-encoding ``` 浏览器侧也可以在 DevTools → Network → Response Headers 中确认。 ### 常见问题 #### 能拿到 securityheaders.com A+ 吗? 上面的配置能稳定拿到 **A 评级**。追求 **A+** 的硬指标是配置 `Content-Security-Policy`(CSP),在博客场景下收益较低: - 多数 Halo 主题依赖若干第三方 CDN(字体、评论系统、统计、表情等),每个都需要加入 CSP 白名单 - 主题模板中常见内联脚本,需使用 `'unsafe-inline'`(会明显削弱 CSP 的价值)或改造为 nonce 模式 - 管理后台「代码注入」功能注入的脚本同样受 CSP 约束,白名单收敛难度较高 如确有 A+ 需求,建议按以下路径落地: 1. 先使用 `Content-Security-Policy-Report-Only`,不阻断页面,仅在浏览器控制台打印违规 2. 观察 1–2 周,根据 violation 报告收敛白名单 3. 白名单稳定后再转为生产 `Content-Security-Policy` 作为参考,GitHub 本身的 securityheaders.com 评级也是 A,对博客类站点而言 A 已足够。 #### NPM 界面中的「缓存资源」开关要开启吗? 建议保持关闭。Halo 自身已通过 `ETag`、`Last-Modified` 等机制对静态资源提供合理的缓存策略,NPM 层再叠一层缓存可能导致主题升级或资源替换后不能立即生效。性能提升主要来自本节的 gzip 与 proxy buffer 优化。 #### 为什么要调大 proxy buffer? NPM 默认的 proxy buffer 较小,当 Halo 返回的响应体超过 buffer 总量时,nginx 会把剩余数据临时写入磁盘后再转发。调大到 `16 32k`(共 512 KB)能覆盖绝大多数 HTML/JSON 响应,避免磁盘 I/O 成为瓶颈。 --- url: https://docs.halo.run/guide/install/other/traefik.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # Traefik 反向代理 ## Halo 部署 参见 [使用 Docker Compose 部署](https://docs.halo.run/guide/install/docker-compose.md) :::info 跳过 Halo 反向代理配置 `「反向代理」` 部分不进行操作,保证 Halo 服务运行无误即可。 ::: ## 简介 [Traefik](https://traefik.io/traefik/) 是一款开源的反向代理与负载均衡工具,它监听后端的变化并自动更新服务配置。 它与传统反向代理最大的区别,是支持声明式的动态路由规则,大大简化网关规则的配置。而且还有诸多实用特性,例如:健康检查、多实例负载均衡、能够实现 Let's Encrypt 证书的自动签发、验证与续期等等。 ## 创建 Traefik 下面的配置中,创建了 Traefik 实例。并且做了基础的几项配置: 1. 监听了宿主机的 80、443 端口,并自动将 80 端口的请求重定向到 443 端口。[文档](https://doc.traefik.io/traefik/routing/entrypoints/) 2. 开启 Docker 服务发现,监听检测 Docker 容器声明的服务关系。[文档](https://doc.traefik.io/traefik/providers/docker/#provider-configuration) 3. 开启 Traefik Dashboard,建议使用二级域名的形式(示例:`traefik.yourdomain.com`)。[文档](https://doc.traefik.io/traefik/operations/dashboard/#dashboard-router-rule) 4. 开启证书自动生成,通过 ACME 自动管理 TLS 证书的申请、校验与续期。[文档](https://doc.traefik.io/traefik/https/acme/) :::warning 持久化 ACME 证书 ACME 证书 (`/acme.json`) 一定要 [持久化](https://doc.traefik.io/traefik/https/acme/#storage),否则每次重启 Traefik 服务,都会去申请签发证书。可能会触发 Let's Encrypt 的 [速率限制](https://letsencrypt.org/zh-cn/docs/rate-limits/),导致签名的域名一段时间内无法签发新的证书。 ::: 创建工作目录、Compose 文件和 ACME 证书存储文件: ```bash mkdir -p ~/traefik && cd ~/traefik touch acme.json && chmod 600 acme.json vim docker-compose.yaml ``` ```yaml {17,28-30,34,40} showLineNumbers networks: traefik: name: traefik attachable: true services: traefik: image: traefik:v2.9 container_name: traefik networks: - traefik ports: - "80:80" - "443:443" volumes: - /var/run/docker.sock:/var/run/docker.sock - ./acme.json:/acme.json command: > --api.dashboard=true --entrypoints.web.address=:80 --entrypoints.websecure.address=:443 --entrypoints.web.http.redirections.entrypoint.to=websecure --entrypoints.web.http.redirections.entrypoint.scheme=https --providers.docker=true --providers.docker.endpoint=unix:///var/run/docker.sock --providers.docker.watch=true --providers.docker.exposedByDefault=false --certificatesResolvers.myresolver.acme.httpChallenge.entryPoint=web --certificatesresolvers.myresolver.acme.email=your-mail@mail.com --certificatesresolvers.myresolver.acme.storage=/acme.json labels: traefik.enable: "true" traefik.docker.network: traefik traefik.http.routers.dashboard.rule: Host(`traefik.yourdomain.com`) traefik.http.routers.dashboard.tls: "true" traefik.http.routers.dashboard.tls.certresolver: myresolver traefik.http.routers.dashboard.service: "api@internal" traefik.http.routers.dashboard.middlewares: auth # 账号密码 admin/P@88w0rd 生成 echo $(htpasswd -nb user password) | sed -e s/\\$/\\$\\$/g traefik.http.middlewares.auth.basicauth.users: "admin:$$apr1$$q8q0qpzT$$lvzMP7VYd9EUcG/wkIsAN." ``` 保存配置后启动 Traefik: ```bash docker compose up -d ``` ## 配置 Halo 的反向代理 这里以最简配置(h2 数据库)Halo 服务的 Docker 配置举例。只需做以下调整: 1. 顶层 `networks` 中添加了外部网络 `traefik` 2. `services.halo.networks` 中添加了 `traefik` 网络 3. `services.halo.labels` 中声明了 Traefik 配置 1. 路由规则为 `yourdomain.com` 2. 开启 TLS 3. 指定了服务端口为 8090 ```yaml {2-3,13-15,18,20-25} showLineNumbers networks: traefik: external: true halo: services: halo: image: registry.fit2cloud.com/halo/halo-pro:2.27 container_name: halo restart: on-failure:3 volumes: - ./halo2:/root/.halo2 networks: - traefik - halo command: # 外部访问地址,请根据实际需要修改 - --halo.external-url=https://yourdomain.com labels: traefik.enable: "true" traefik.docker.network: traefik traefik.http.routers.halo.rule: Host(`yourdomain.com`) traefik.http.routers.halo.tls: "true" traefik.http.routers.halo.tls.certresolver: myresolver traefik.http.services.halo.loadbalancer.server.port: 8090 ``` --- url: https://docs.halo.run/guide/setup.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 初始化 通过之前的安装文档,你已经成功安装了 Halo,在首次访问网站的时候会自动跳转到初始化页面,你需要完成这个步骤才能正常使用 Halo。 ![Setup](/img/setup/setup-2.26.png) 表单项说明: 1. **语言**:Halo Console、个人中心和系统页面默认使用的语言。 2. **外部访问地址**:站点对外提供访问的完整地址,例如 `https://www.example.com`。Halo 会根据当前请求自动填写,请确认协议、域名和端口正确。 3. **站点标题**:网站的名称,将会显示在浏览器标签页上。 4. **用户名**:初始管理员的用户名。 5. **电子邮箱**:初始管理员的邮箱地址。 6. **密码**:初始管理员的密码。 7. **确认密码**:重复输入密码以验证是否匹配。 输入完成之后点击**初始化**按钮即可完成初始化。初始化完成后将进入 Console;如果登录状态失效,可以使用刚才设置的用户名或已验证邮箱和密码重新登录。 --- url: https://docs.halo.run/guide/first-post.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 第一篇文章 ## 登录管理端 浏览器访问 `/console` 即可进入 Halo 管理端。 ## 新建文章 Halo 安装完成后,默认初始化了一篇 `Hello Halo` 文章,接下来我们将创建并发布一篇自己的文章。 ### 进入文章编辑页面 在 Halo 管理端,点击仪表盘页面中的 `创建文章` 快捷入口,即可进入到文章编辑页面。 ### 编辑文章内容 在文章编辑器中,你可以尽情写下你想展现的内容。 ### 设置文章信息 当内容编辑完成后,点击右上角的 `发布` 按钮,给文章设置一个合适的标题和别名,同时可以设置文章所属分类、标签及其他一些高级设置。 ### 发布文章 确认无误后,点击弹框下方的 `发布` 按钮,我们的第一篇文章就成功发布了。 :::info 查看文章使用指南 关于文章相关其他功能及文章各种设置项的说明,请参考《[用户指南 - 文章](https://docs.halo.run/guide/use/posts.md)》章节 ::: ## 查看文章 文章发布成功后,就可以在主题端查看到我们刚刚创建的文章了。 浏览器访问域名进入站点首页,站点展示的内容及样式由当前启用的主题所决定。 接下来,选一款喜欢的主题,尽情体验 Halo 吧! --- url: https://docs.halo.run/guide/use/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 常用模块 ## 常用模块 ### [概念说明](/guide/use/common.md) - [登录](/guide/use/common.md#登录) - [注册](/guide/use/common.md#注册) - [控制台](/guide/use/common.md#控制台) - [个人中心](/guide/use/common.md#个人中心) - [文章](/guide/use/common.md#文章) - [页面](/guide/use/common.md#页面) - [分类](/guide/use/common.md#分类) - [标签](/guide/use/common.md#标签) - [附件](/guide/use/common.md#附件) - [主题](/guide/use/common.md#主题) - [插件](/guide/use/common.md#插件) ### [仪表盘](/guide/use/dashboard.md) - [调整仪表盘](/guide/use/dashboard.md#调整仪表盘) - [配置不同设备的布局](/guide/use/dashboard.md#配置不同设备的布局) ### [许可证激活](/guide/use/activate.md) - [购买许可证](/guide/use/activate.md#购买许可证) - [部署 Halo 付费版](/guide/use/activate.md#部署-halo-付费版) - [查看产品版本信息](/guide/use/activate.md#查看产品版本信息) - [查看已购产品许可证](/guide/use/activate.md#查看已购产品许可证) - [下载许可证](/guide/use/activate.md#下载许可证) - [激活许可证](/guide/use/activate.md#激活许可证) - [取消激活许可证](/guide/use/activate.md#取消激活许可证) - [使用增值权益](/guide/use/activate.md#使用增值权益) ### [个人中心](/guide/use/user-center.md) - [进入个人中心](/guide/use/user-center.md#进入个人中心) - [个人资料](/guide/use/user-center.md#个人资料) - [通知配置](/guide/use/user-center.md#通知配置) - [个人令牌](/guide/use/user-center.md#个人令牌) - [认证方式](/guide/use/user-center.md#认证方式) - [两步验证](/guide/use/user-center.md#两步验证) - [登录设备](/guide/use/user-center.md#登录设备) - [消息](/guide/use/user-center.md#消息) - [我的文章](/guide/use/user-center.md#我的文章) - [商城](/guide/use/user-center.md#商城) ### [文章](/guide/use/posts.md) - [新建文章](/guide/use/posts.md#新建文章) - [文章设置](/guide/use/posts.md#文章设置) - [发布及取消发布](/guide/use/posts.md#发布及取消发布) - [删除文章](/guide/use/posts.md#删除文章) - [文章分类管理](/guide/use/posts.md#文章分类管理) - [文章标签管理](/guide/use/posts.md#文章标签管理) ### [页面](/guide/use/pages.md) - [页面设置](/guide/use/pages.md#页面设置) - [页面操作](/guide/use/pages.md#页面操作) ### [评论](/guide/use/comments.md) - [查找评论](/guide/use/comments.md#查找评论) - [审核评论](/guide/use/comments.md#审核评论) - [回复评论](/guide/use/comments.md#回复评论) - [删除评论](/guide/use/comments.md#删除评论) ### [附件](/guide/use/attachments.md) - [存储策略](/guide/use/attachments.md#存储策略) - [附件分组](/guide/use/attachments.md#附件分组) - [上传附件](/guide/use/attachments.md#上传附件) - [查看附件](/guide/use/attachments.md#查看附件) - [删除附件](/guide/use/attachments.md#删除附件) - [移动附件](/guide/use/attachments.md#移动附件) ### [菜单](/guide/use/menus.md) - [创建菜单](/guide/use/menus.md#创建菜单) - [创建菜单项](/guide/use/menus.md#创建菜单项) - [排序](/guide/use/menus.md#排序) ### [主题](/guide/use/themes.md) - [安装主题](/guide/use/themes.md#安装主题) - [切换主题](/guide/use/themes.md#切换主题) - [修改主题设置](/guide/use/themes.md#修改主题设置) - [预览主题](/guide/use/themes.md#预览主题) - [升级主题](/guide/use/themes.md#升级主题) - [重载主题配置](/guide/use/themes.md#重载主题配置) - [重置](/guide/use/themes.md#重置) - [卸载主题](/guide/use/themes.md#卸载主题) ### [插件](/guide/use/plugins.md) - [安装插件](/guide/use/plugins.md#安装插件) - [插件设置](/guide/use/plugins.md#插件设置) - [启用/禁用插件](/guide/use/plugins.md#启用禁用插件) - [升级插件](/guide/use/plugins.md#升级插件) - [重载插件](/guide/use/plugins.md#重载插件) - [重置](/guide/use/plugins.md#重置) - [卸载插件](/guide/use/plugins.md#卸载插件) - [扩展配置](/guide/use/plugins.md#扩展配置) ### [应用市场](/guide/use/app-store.md) - [应用市场页面](/guide/use/app-store.md#应用市场页面) - [绑定 Halo 官网账号](/guide/use/app-store.md#绑定-halo-官网账号) - [安装/更新插件](/guide/use/app-store.md#安装更新插件) - [安装/更新主题](/guide/use/app-store.md#安装更新主题) - [付费应用激活](/guide/use/app-store.md#付费应用激活) ### [用户与权限](/guide/use/users.md) - [概览](/guide/use/users.md#概览) - [用户](/guide/use/users.md#用户) - [角色](/guide/use/users.md#角色) - [身份认证](/guide/use/users.md#身份认证) ### [站点设置](/guide/use/settings.md) - [基本设置](/guide/use/settings.md#基本设置) - [文章设置](/guide/use/settings.md#文章设置) - [SEO 设置](/guide/use/settings.md#seo-设置) - [用户设置](/guide/use/settings.md#用户设置) - [附件设置](/guide/use/settings.md#附件设置) - [评论设置](/guide/use/settings.md#评论设置) - [主题路由设置](/guide/use/settings.md#主题路由设置) - [代码注入](/guide/use/settings.md#代码注入) - [品牌信息](/guide/use/settings.md#品牌信息) - [通知设置](/guide/use/settings.md#通知设置) ### [备份与恢复](/guide/use/backup.md) - [备份](/guide/use/backup.md#备份) - [自动备份与同步](/guide/use/backup.md#自动备份与同步) - [恢复](/guide/use/backup.md#恢复) ### [移动端 App](/guide/use/mobile-app.md) - [绑定设备](/guide/use/mobile-app.md#绑定设备) - [删除绑定](/guide/use/mobile-app.md#删除绑定) --- url: https://docs.halo.run/guide/use/common.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 概念说明 Halo 作为一款好用又强大的开源建站工具,配合上不同的模板与插件,可以很好地帮助你构建你心中的理想站点。它可以是你公司的官方网站,可以是你的个人博客,也可以是团队共享的知识库,甚至可以是一个论坛、一个商城。 为了更好地发挥出 Halo 的价值,这里有一些基本概念需要你进行了解。 ## 登录 Halo 的统一登录入口为 `/login`。 ![Login](/img/user-guide/common/login-2.26.png) Halo 支持使用用户名和密码登录。从 Halo 2.26 开始,也可以使用已验证的邮箱和密码登录;配置邮件通知并启用邮箱验证码认证后,还可以使用邮箱验证码登录。管理员也可以在用户管理的身份认证页面启用并排序其他认证方式。 ## 注册 Halo 的注册地址为 `/signup`,需要注意的是,Halo 默认不会开启注册功能,需要在设置页面的 [用户设置](https://docs.halo.run/guide/use/settings.md#%E7%94%A8%E6%88%B7%E8%AE%BE%E7%BD%AE) 中手动开启。 ![Signup](/img/user-guide/common/signup.png) 通过 OAuth2 等第三方认证方式首次登录时,可以根据页面提示绑定已有账号;站点开放注册时,也可以注册新账号并按要求补充资料、同意相关协议。 ## 控制台 Console 控制台是一个 Halo 站点的后台管理系统,只有具有权限的登录用户才可以正常使用控制台功能。你可以在控制台中管理站点中的文章、页面、附件等各种内容,调整站点使用的主题或各种设置,访问地址为 `/console`。 ![控制台界面说明](/img/user-guide/common/控制台界面说明.png) 1. **全局搜索框**:点击或通过快捷键 `Ctrl+K` 可以呼出全局搜索框,输入关键字可以在所有文章、页面、附件、用户及设置项等所有内容中进行全局搜索。 2. **侧边导航栏**:对控制台提供的功能进行导航,点击导航栏条目会在页面右侧显示对应功能页面。安装某些插件可能会扩展导航栏条目。 3. **用户信息展示及操作**:展示当前登录用户的头像、名称及角色等信息,`···` 中提供更多用户相关操作。 4. **功能页面标题**:当前所在的功能页面标题。 5. **功能页面操作区域**:当前所在功能页面提供的功能操作按钮。 6. **功能页面主体**:当前所在功能页面的主体显示区域,显示内容及形式视具体页面功能而定。 ## 个人中心 从 Halo 2.11 开始,除了 Console 管理控制台,我们新增加了个人中心,用于管理和用户相关的所有功能。有了个人中心之后,也可以让网站有更多的使用和开发场景,个人中心独立访问入口为 `/uc`。 ## 文章 文章是 Halo 中的核心概念之一。一篇文章主要由纯文本的文章标题和富文本的文章内容构成,除此之外你还可以为文章设置所属分类、添加标签、设置封面图等。 在不同的站点类型不同的应用场景中,文章的实际含义也会有所区别,它可以代表一则公司新闻、一篇博客或者产品文档中的某一章节。 ## 页面 页面与文章类似,同样包含页面标题和富文本形式的页面内容。与文章不同的是页面无法设置所属分类和标签信息,一般用于站点中单一展示功能的页面,例如常见的站点关于页面、联系我们页面等。 ## 分类 通过分类可以更好地组织管理文章。分类之间存在层级关系,一个父分类下可包含多个子分类。一篇文章可以同时属于多个分类。 ## 标签 标签可以用于为文章添加特定标记,与分类不同的是标签之间没有层级关系。一篇文章也可以同时添加多个标签。 ## 附件 由用户上传的,供文章、主题设置等各个地方引用的文件。多用于文章配图、主题配图、用户头像等场景。 ## 主题 包含了各种站点页面模板的资源包。用户访问 Halo 站点浏览到的内容及样式,由 Halo 管理端所配置使用的主题所决定。 ## 插件 用于扩展 Halo 功能的软件包。插件独立于 Halo 核心应用,可以单独安装、升级、卸载。 :::info 主题和插件获取渠道 目前有两个官方渠道可以获取主题和插件: - 应用市场:[https://www.halo.run/store/apps](https://www.halo.run/store/apps) - Awesome Halo:[https://github.com/halo-sigs/awesome-halo](https://github.com/halo-sigs/awesome-halo) ::: --- url: https://docs.halo.run/guide/use/dashboard.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 仪表盘 登录 Console 后,默认会进入仪表盘。仪表盘由多个组件组成,用于集中展示站点概况和常用信息;插件也可以提供新的仪表盘组件。 ![仪表盘](/img/user-guide/dashboard/dashboard-2.26.png) ## 调整仪表盘 点击仪表盘右上角的 `设置` 按钮进入设计模式。在设计模式中可以: - 添加 Halo 或插件提供的组件; - 拖拽组件以调整位置; - 拖动组件边缘以调整尺寸; - 修改支持配置的组件; - 删除不再需要的组件。 完成调整后,点击右上角的 `保存` 按钮使布局生效。 ![仪表盘设计模式](/img/user-guide/dashboard/dashboard-designer-2.26.png) ## 配置不同设备的布局 设计模式支持切换不同设备尺寸。你可以分别调整各尺寸下的组件位置和大小,使仪表盘适应不同宽度的屏幕。切换尺寸或离开页面前,请先保存当前修改。 --- url: https://docs.halo.run/guide/use/activate.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 许可证激活 :::note 仅适用于 Halo 付费版 此文档仅适用于 **[Halo 付费版](https://docs.halo.run/guide/prepare.md#%E5%8F%91%E8%A1%8C%E7%89%88%E6%9C%AC)**(专业版 / 商城版),在开始之前需要确保已经成功部署了 Halo 付费版。 社区版无需进行许可证激活。 ::: ## 购买许可证 你可以在[凌霞软件](https://www.lxware.cn/halo?code=mcYhwMkn)官网购买 Halo 付费版的许可证,目前分为 Halo 专业版和 Halo 商城版,支持按月/按年订阅或者版本买断。 在凌霞官网购买产品后,可以在 `个人中心` > `我的许可证` ,统一管理当前账户下的全部已购产品的许可证。 ![许可证列表.png](/img/user-guide/activate/lxware-licenses.png) ## 部署 Halo 付费版 可以查阅: - [使用 Docker Compose 部署](https://docs.halo.run/guide/install/docker-compose.md) - [使用 1Panel 部署](https://docs.halo.run/guide/install/1panel.md) - [使用 JAR 文件部署](https://docs.halo.run/guide/install/jar-file.md) ## 查看产品版本信息 部署成功后,访问 `控制台` > `概览`,可以查看 Halo 版本信息,目前还处于未激活状态,需要按照后续步骤进行激活。 ![未激活状态.png](/img/user-guide/activate/overview-activate.png) ## 查看已购产品许可证 登录到凌霞官网的 [订单列表](https://lxware.cn/uc/cloud/order),点击已完成订单条目右侧的更多按钮,点击「许可证列表」,即可跳转至 `我的许可证` 列表,可以查看该订单所购产品的许可证。 ![查看订单许可证.png](/img/user-guide/activate/lxware-licenses.png) ## 下载许可证 在 `我的许可证`列表,点击许可证条目右侧的更多按钮,点击「详情」; ![查看许可证详情.png](/img/user-guide/activate/lxware-licenses-operation-detail.png) 在详情页下载许可证文件,同时支持兑换包含在产品许可证内的免赠权益。 ![下载许可证.png](/img/user-guide/activate/lxware-license-detail.png) ## 激活许可证 进入 `控制台` > `概览`,导入下载的许可证文件。 ![导入许可证.png](/img/user-guide/activate/overview-import-license.png) 导入完成后,可以查看到更新的版本信息。许可证显示为「有效」即为激活成功,到此即可正常使用 Halo 付费版。 ![激活成功.png](/img/user-guide/activate/overview-activated.png) ## 取消激活许可证 你可以随时在当前应用中取消激活许可证,取消后付费版功能将会受限。在许可证有效期内,许可证可被重新激活至其他设备中。 ![取消激活.png](/img/user-guide/activate/overview-deactivate.png) ## 使用增值权益 > 随着 Halo 付费版订阅制的上线(2024-11-12),我们更新了获取增值权益即官方付费应用的方式。目前,用户可以直接通过 Halo 付费版许可证激活付费的插件和主题。 > 此外,从 2024-11-28 开始,通过付费版激活应用将开放给全部 Halo 付费版用户,你可以重新在凌霞官网下载许可证并激活,然后就可以通过付费版许可证激活所有官方付费应用。需要保证 Halo 付费版版本为 2.20.4 以上,应用市场插件的版本为 1.9.0 以上。相关阅读:[Halo 付费版永久授权增值权益的升级说明](https://www.lxware.cn/archives/benefits-upgrade) 在进行下面的步骤之前,请确保已经正常激活 Halo 付费版。 ### 查看和下载付费应用 使用 Halo 付费版许可证激活后,就可以在内置的应用市场中查看所有可下载的付费应用。 ![付费应用列表](/img/user-guide/activate/app-store.png) ### 激活付费应用 下载付费应用之后,即可在许可证管理中使用 Halo 付费版许可证进行激活。 ![激活付费应用](/img/user-guide/activate/app-activate.png) :::info 激活后重启插件 如果你在激活前就启动了插件,那么在激活后可能需要重启插件才会生效。 ::: ### Halo 付费版增值权益内容 所有付费版可以在许可证有效期内使用所有 Halo 官方发行的付费应用,包括在许可证有效期内新增的付费应用,[点击查看最新官方付费应用列表](https://www.halo.run/store/apps?price-mode=ONE_TIME\&sort=creationTimestamp%2Cdesc\&tag=official)。 查看当前许可证包含的付费应用可以在 `个人中心` > `我的许可证` 中进入具体 Halo 许可证的详情页面中查看,如下图: ![许可证包含的付费应用](/img/user-guide/activate/lxware-license-detail-apps.png) --- url: https://docs.halo.run/guide/use/user-center.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 个人中心 从 Halo 2.11 开始,除了 Console 管理控制台,我们新增加了个人中心,用于管理和用户相关的所有功能。有了个人中心之后,也可以让网站有更多的使用和开发场景。 ## 进入个人中心 你可以通过点击 Console 左下角的个人中心图标进入个人中心,也可以直接访问 `/uc` 进入个人中心。 :::info Console 入口显示条件 此外,如果用户拥有进入 Console 的权限,也会在个人中心的左侧导航栏中看到 Console 的入口。 详情可见:[创建角色](https://docs.halo.run/guide/use/users.md#%E5%88%9B%E5%BB%BA%E8%A7%92%E8%89%B2) ::: ![Uc entry](/img/uc/uc-entry.png) ## 个人资料 这个页面会显示和用户相关的信息,并支持修改头像、显示名称、简介等个人资料。用户还可以验证电子邮箱;付费版本在站点已配置短信服务时,还可以验证并绑定手机号。用户可以修改登录密码;通过免密认证注册且尚未设置密码的用户,可以在这里设置密码。 ![User profile](/img/uc/uc-profile-edit-2.26.png) ## 通知配置 这个页面可以配置用户的通知偏好,可以选择接收哪些类型的通知。 ![Notification preferences](/img/uc/uc-notification-preferences.png) ## 个人令牌 个人令牌是一种用于访问 Halo API 的凭证,可以通过个人令牌访问 Halo 的 RESTful API,而无需通过用户名和密码授权,使用方式可查阅:[RESTful API 介绍](https://docs.halo.run/developer-guide/restful-api/introduction.md) ![Personal access token](/img/uc/pat-list-2.26.png) 创建新的个人令牌: ![Create personal access token](/img/uc/pat-create-2.26.png) - **名称**:个人令牌的名称。 - **过期时间**:个人令牌的过期时间,不选择则表示永不过期。 - **描述**:个人令牌的描述信息,用于描述个人令牌的用途。 - **角色与权限模板**:决定个人令牌可以访问的 API 范围,可以选择多个角色或权限模板。 创建好的个人令牌: ![Personal access token string](/img/uc/pat-token-2.26.png) 令牌值只会在创建完成时完整显示,请立即复制并妥善保管。对于已有令牌,可以查看最后使用时间,并执行撤销、恢复或删除操作;删除后无法恢复。 ## 认证方式 认证方式页面会列出当前账号可以使用的第三方认证方式。对于支持账号绑定的认证方式,可以在这里绑定或解除绑定。 ![个人中心认证方式](/img/uc/authentication-methods-2.26.png) ## 两步验证 在这个选项卡中,我们可以配置登录之后两步验证方式,目前支持 TOTP 验证器。 ![Totp](/img/uc/totp.png) ![Totp Config](/img/uc/totp-config.png) ## 登录设备 在这里可以看到当前账号的所有登录设备,你也可以在更多按钮中撤销任意设备。 ![User devices](/img/uc/user-devices.png) ## 消息 此页面用于显示用户收到的站内消息。 ![Notifications](/img/uc/uc-notifications.png) ## 我的文章 Halo 默认为个人中心提供了管理个人文章的功能,每个用户都可以在个人中心创建、编辑自己的文章。当然,也可以通过配置角色权限,自行决定是否开放此功能,可查阅[创建角色](https://docs.halo.run/guide/use/users.md#%E5%88%9B%E5%BB%BA%E8%A7%92%E8%89%B2)。 ![My posts](/img/uc/uc-posts.png) ## 商城 Halo 商城版会在个人中心增加订单、收货地址、优惠券和订阅功能,使用方法参见[商城客户中心](https://docs.halo.run/guide/shop/customer-center.md)。 --- url: https://docs.halo.run/guide/use/posts.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 文章 ## 新建文章 目前你可以通过以下两种方式新建一篇文章: 1. 点击仪表盘快捷访问组件中的创建文章 2. 通过左侧导航栏进入文章页面,点击右上角的新建按钮 进入到如下页面后,你就可以开始编辑自己的文章内容了: ![文章编辑界面说明](/img/user-guide/posts/post-edit.png) 1. **编辑器切换**:如果安装了其他的编辑器插件,那么就可以在这个位置选择所需的编辑器。 2. **预览**:点击预览按钮可以在未发布的时候预览文章的渲染效果。 3. **保存**:仅保存文章内容,但是不发布。 4. **发布**:保存并发布文章内容。 :::info 获取其他文章编辑器 Halo 支持通过插件来拓展文章编辑器,目前除了 Halo 内置的编辑器,应用市场中还有其他的编辑器可用:[https://www.halo.run/store/apps?tag=editor](https://www.halo.run/store/apps?tag=editor) ::: ## 文章设置 当你想修改一篇文章的标题、所属分类等信息时,你可以通过以下方式进行操作: 1. 点击文章列表指定文章所在行的 `···` 更多操作按钮,选择设置。 2. 在文章列表点击指定文章的标题进入文章编辑页面,点击页面右上角的设置按钮。 ![文章编辑界面说明](/img/user-guide/posts/post-settings-publish-2.26.png) ### 设置说明 - **标题**:用于在主题端显示的文章标题。 - **别名**:通常用于生成文章访问地址,如:`/archives/{slug}`。 - **分类目录**:文章所属分类,方便用户区分文章类型进行针对性浏览,一篇文章可以属于多个分类。 - **标签**:文章添加的标签,方便用户更进一步标识文章信息,一篇文章可以添加多个标签。 - **自动生成摘要**:文章摘要是对文章内容的概括性描述。 - **是**:系统根据文章内容,自动生成一段摘要。 - **否**:用户自行输入文章摘要文本。 - **自定义摘要**:用户自行输入的文章摘要文本,仅当 `自动生成摘要` 为否时生效。 - **允许评论**:是否允许用户在主题端浏览文章时对该文章发起评论。 - **是否置顶**:文章是否排序在文章列表的最顶部。 - **可见性**:访问站点主题端时,哪些人可以看到这篇文章。 - **公开**:所有用户均可看到这篇文章,包括未登录用户。 - **私有**:仅文章作者可以看到这篇文章。 - **发表时间**:手动指定文章的发表时间,未指定时以实际发布时间为准。 - **自定义模板**:自定义文章的渲染模板,由主题提供支持。 - **封面图**:文章封面图设置,需要主题支持该功能。 - **元数据**:供主题、插件使用的额外数据信息。比如主题在文章页面提供了一个下载按钮,那么就可以通过元数据来指定下载地址。 ## 发布及取消发布 对于已发布的文章,默认可以通过站点地址进行公开访问,用户可以在文章高级设置中修改可见性。 你可以在上文介绍的文章设置对话框中,修改文章的发布状态。 在文章设置对话框中,若文章当前处于已发布状态,下方会显示取消发布按钮;若文章处于未发布状态,下方会显示发布或定时发布按钮。 ## 删除文章 当你不再需要一篇文章时,你可以通过以下方式删除该文章: 1. 点击文章列表指定文章所在行的 `···` 更多操作按钮,选择删除。 2. 勾选文章列表中的全选/多选框,选中一篇或多篇文章进行批量删除。 文章删除后会进入回收站中,点击右上角的回收站按钮进入回收站。在回收站中,你可以永久删除或恢复指定的文章。 :::warning 永久删除不可恢复 文章永久删除后将从数据库删除该记录,后续无法再恢复找回。 ::: ## 文章分类管理 通过分类可以更好地组织管理文章。分类之间存在层级关系,一个父分类下可包含多个子分类。一篇文章可以同时属于多个分类。 在文章管理页面,点击页面右上角的 `分类` 按钮即可进入分类管理页面。 ### 新建文章分类 点击分类管理页面右上角的 `新建` 按钮即可新建一个分类。 ![文章分类编辑界面说明](/img/user-guide/posts/category-create.png) ![文章分类编辑界面说明 2](/img/user-guide/posts/category-create-2.png) #### 设置说明 - **名称**:用于在主题端显示的分类名称。 - **别名**:通常用于生成分类归档页面的访问地址。默认路径规则为 `/categories/{slug}`,其中 `slug` 为分类别名,访问该地址即可浏览该分类下的所有文章。分类页路由前缀可[在设置中修改](https://docs.halo.run/guide/use/settings.md#%E4%B8%BB%E9%A2%98%E8%B7%AF%E7%94%B1%E8%AE%BE%E7%BD%AE)。 - **自定义模板**:自定义分类归档页面的渲染模板,由主题提供支持。 - **自定义文章模板**:自定义当前分类下所有文章的渲染模板,由主题提供支持。 - **封面图**:分类封面图设置,需要主题支持该功能。 - **在列表中隐藏**:开启此选项后,此分类和其下子分类,以及其下文章将不会显示在前台的列表中,需要主动访问分类归档页面,此功能仅对第一级目录生效。 - **阻止文章级联查询**:阻止父级分类在级联文章查询中包含此分类及其子分类。 - **描述**:关于该文章分类的更多描述信息。 - **元数据**:供主题、插件使用的额外数据信息。例如部分主题期望使用不同的颜色对分类进行区分,便可以使用该功能为分类增加颜色相关的元数据。 ### 调整分类层级 分类之间存在层级关系,一个父分类下可包含多个子分类。 你可以按住分类前的图标,通过拖拽来调整分类间的层级关系和顺序。 ![移动文章分类](/img/user-guide/posts/category-move.gif) ### 修改/删除分类 点击指定分类所在行后方的 `···` 更多操作按钮,可以对文章分类进行修改或删除。 :::warning 删除分类的影响 文章分类删除后,对应文章的关联将被解除,且该操作不可恢复,请谨慎进行该操作。 ::: ## 文章标签管理 标签可以用于为文章添加特定标记,与分类不同的是标签之间没有层级关系。一篇文章也可以同时添加多个标签。 ### 新建文章标签 点击文章标签页面右上角的 `新建` 按钮即可新建一个标签。 ![标签编辑界面说明](/img/user-guide/posts/tag-edit-2.26.png) #### 设置说明 - **名称**:用于在主题端显示的标签名称。 - **别名**:通常用于生成标签归档页面的访问地址。默认路径规则为 `/tags/{slug}`,其中 `slug` 为标签别名,访问该地址即可浏览具有该标签的所有文章。标签页路由前缀可[在设置中修改](https://docs.halo.run/guide/use/settings.md#%E4%B8%BB%E9%A2%98%E8%B7%AF%E7%94%B1%E8%AE%BE%E7%BD%AE)。 - **颜色**:用于在控制台及主题端显示的标签颜色,主题端显示颜色需要主题支持该功能。 - **封面图**:标签封面图设置,需要主题支持该功能。 - **描述**:标签的文字说明,主题可以在标签归档页等位置展示。 - **元数据**:供主题、插件使用的额外数据信息。 ### 修改/删除标签 在列表模式下,点击指定标签所在行后方的 `···` 更多操作按钮,可以对文章标签进行修改或删除。 :::warning 删除标签的影响 文章标签删除后,对应文章的关联将被解除,且该操作不可恢复,请谨慎进行该操作。 ::: --- url: https://docs.halo.run/guide/use/pages.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 页面 页面与文章类似,同样包含页面标题和富文本形式的页面内容。与文章不同的是页面无法设置所属分类和标签信息,一般用于站点中单一展示功能的页面,例如常见的站点关于页面、联系我们页面等。 自定义页面的访问链接为 `/{slug}` 其中 `slug` 为自定义页面的别名。 对于如下的关于页面,便可以通过 `/about` 地址进行访问。 ![页面列表](/img/user-guide/pages/pages-list-2.26.png) 点击页面标题可以进入编辑器,页面设置入口位于编辑器右上角。 ![页面编辑器](/img/user-guide/pages/page-editor-2.26.png) :::info 自定义页面模板 自定义页面默认使用主题端的 `page.html` 模板进行渲染,如果主题中提供了针对自定义页面的其他模板,用户可以通过修改自定义页面高级设置中的自定义模板设置进行使用。 ::: ## 页面设置 新建或编辑页面时,可以在页面设置中配置: - **标题和别名**:别名用于生成页面访问地址; - **摘要**:可以自动生成,也可以手动填写; - **封面图**:供支持该功能的主题展示; - **是否允许评论**:控制访客能否在页面下发表评论; - **置顶**:供支持页面置顶的主题使用; - **可见性**:可以设置为公开、仅自己可见或密码访问; - **发布时间**:可以立即发布或设置定时发布时间; - **自定义模板**:选择当前主题提供的页面模板; - **元数据**:供主题和插件保存额外信息。 ![页面设置](/img/user-guide/pages/page-settings-2.26.png) ## 页面操作 对于页面的新建、设置、发布及删除等操作,与文章操作基本一致,具体操作请参考[《用户指南 - 文章》](https://docs.halo.run/guide/use/posts.md)章节,此处不再赘述。 --- url: https://docs.halo.run/guide/use/comments.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 评论 点击 Console 左侧导航栏的 `评论` 进入评论管理页面。这里可以统一管理文章、页面以及插件扩展内容收到的评论。 ![评论列表](/img/user-guide/comments/comments-list-2.26.png) ## 查找评论 评论列表支持按关键词搜索,并按审核状态、评论者等条件筛选和排序。点击评论关联的内容,可以查看评论所在的文章、页面或其他内容。 ## 审核评论 对于待审核评论,可以在评论操作菜单中选择 `通过`;已经通过的评论也可以取消审核。选中多条评论后,可以批量通过审核。 待审核评论的操作菜单: ![审核待审核评论](/img/user-guide/comments/comment-review-pending-2.26.png) 已通过评论的操作菜单: ![取消通过评论](/img/user-guide/comments/comment-review-approved-2.26.png) ## 回复评论 点击评论的 `回复` 操作可以直接回复。评论回复也支持审核和删除,具体可用操作取决于当前评论状态和用户权限。 ![评论回复界面](/img/user-guide/comments/comment-reply-2.26.png) ## 删除评论 可以从单条评论的操作菜单删除评论,也可以选中多条评论后批量删除。 :::warning 删除评论不可恢复 评论删除后无法恢复,请在确认不再需要后操作。 ::: --- url: https://docs.halo.run/guide/use/attachments.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 附件 ## 存储策略 为了能够更加灵活地管理附件的存储位置,Halo 提供了存储策略的概念。 Halo 默认提供了本地的存储策略类型,你还可以通过安装插件的方式扩展其他的存储策略类型。一个存储策略包含了存储提供者,具体存储位置等使用该类型存储所必要的各种信息。 :::info 扩展存储方式 目前除了 Halo 内置的本地存储,在应用市场中也有三方的存储插件:[https://www.halo.run/store/apps?tag=storage](https://www.halo.run/store/apps?tag=storage) 此外,如果你期望对接类似于阿里云、腾讯云的对象存储,可以考虑使用 [对象存储(Amazon S3 协议)](https://www.halo.run/store/apps/app-Qxhpp) 插件,此插件兼容市面上所有支持 S3 协议的对象存储厂商。 ::: 你可以点击附件页面右上角的 `存储策略` 按钮对存储策略进行管理。 ### 新建存储策略 点击存储策略列表右上方的 `+` 添加按钮即可新建一个存储策略。 ![添加存储策略](/img/user-guide/attachments/attachment-policy-add.png) 添加时首先需要选择一种存储策略类型,系统内置的存储策略为本地存储,图中的 `S3 对象存储` 由[对象存储(Amazon S3 协议)](https://www.halo.run/store/apps/app-Qxhpp)提供,此文档以本地存储为例。 ![添加本地存储策略](/img/user-guide/attachments/attachment-policy-add-local.png) 添加一个本地存储时,你需要输入名称及存储位置信息。其中的存储位置决定了使用该存储策略的附件,在服务器上的实际存储路径,路径规则为 `{Halo 工作目录}/attachments/{存储位置}`,其中的 Halo 工作目录由安装时指定的参数决定,默认为 `~/.halo2`。 :::info Docker 附件存储位置 默认的 Docker 部署方式,实际存储位置由挂载到 Halo 容器工作目录的服务器目录所决定。 ::: ### 管理存储策略 点击存储策略列表指定存储所在行后方的 `···` 更多操作按钮即可对该存储策略进行编辑或删除。 ![存储策略操作](/img/user-guide/attachments/attachment-policy-operate.png) :::info 删除存储策略前先清空附件 为了保护附件安全避免用户误操作,当存储策略下存在附件时,该存储策略不允许删除。如果确定要删除某个存储策略及该存储策略中的所有附件,可以先按照存储策略对附件进行筛选,先批量删除存储策略下的所有附件,再删除存储策略。 ::: ## 附件分组 通过附件分组功能可以方便地将同一类型、同一用途的附件划分到一个分组中,方便后续附件的管理和插件。 附件所使用的存储策略决定了附件的实际存储位置和 URL 规则,而附件分组功能仅是逻辑上的归类划分,不会影响附件的存储位置及 URL。 ### 新建分组 点击附件列表上方的 `添加分组` 按钮即可新建一个分组。 ![添加分组](/img/user-guide/attachments/attachment-group-add.png) ### 删除分组 点击附件列表上方指定分组上的 `···` 更多按钮,可以对分组进行重命名或删除操作。 Halo 目前提供了两种分组删除策略: 1. **删除并将附件移动至未分组**:分组被删将被删除,分组下的附件移动到未分组中。 2. **删除并同时删除附件**:先删除下的所有附件后,再删除该分组。 :::warning 删除的附件不可恢复 当使用 `删除并同时删除附件` 方式时,分组下的所有附件会被同时删除且不可恢复、无法找回,请谨慎进行该操作。 ::: ## 上传附件 点击附件列表右上方的 `上传` 按钮即可上传新的附件到 Halo。 ![上传附件](/img/user-guide/attachments/attachment-upload-2.26.png) 1. **存储策略选择**:你可以选择需要使用的存储策略,为了方便,选择之后会在浏览器记住这个选项。 2. **分组选择**:你可以选择需要上传到的分组,为了方便,选择之后会在浏览器记住这个选项。 3. **上传区域**:同时支持拖拽文件、点击上传区域选择文件、粘贴文件。 切换到远程下载选项卡后,也可以输入一个或多个文件 URL,由 Halo 下载并保存到所选存储策略和分组中。 ## 查看附件 点击附件列表中的某一个附件即可查看该附件的详细信息。 ![附件详情](/img/user-guide/attachments/attachment-detail-2.26.png) 1. **预览区域**:目前支持图片、视频、音频的预览。 2. **名称**:可以修改附件在 Console 中显示的名称,不会改变附件的存储位置。 3. **链接**:目前可以显示并复制链接、HTML 格式代码、Markdown 格式代码。 ## 删除附件 目前有两种删除附件的方式,你可以选中一些附件进行批量删除或者点击指定附件所在行后方的 `···` 更多按钮,对单个附件进行删除操作。 ![批量操作附件](/img/user-guide/attachments/attachment-batch-operate.png) :::warning 删除附件不可恢复 附件删除后不可恢复、无法找回,请谨慎进行该操作。 ::: ## 移动附件 ![附件移动](/img/user-guide/attachments/attachment-move.png) 与批量删除操作类似,你可以选中多个附件后在上方的批量操作按钮中选择 `移动` 操作,将所选附件移动到指定的分组中。 :::info 仅支持移动附件分组 需要注意的是,目前移动附件只支持移动分组,不支持存储策略的移动。 ::: --- url: https://docs.halo.run/guide/use/menus.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 菜单 菜单功能用于管理网站上的导航菜单,目前 Halo 支持配置多个菜单组。 ![Menus](/img/user-guide/menus/menus-2.26.png) 说明: 1. 左边为菜单列表,右边为所选菜单的菜单项列表。 2. 点击左边的菜单可以切换菜单项列表。 ## 创建菜单 点击左边菜单列表底部的 **新建** 可以打开新建菜单的对话框,输入名称即可创建。 ![Create menu](/img/user-guide/menus/create-menu.png) ![Menu operation](/img/user-guide/menus/menu-operation-2.26.png) 点击菜单条目的操作按钮可以展开操作选项,包括: 1. **设置为主菜单**:设置当前菜单为主菜单,主菜单会在网站导航栏中显示(具体需要以主题的实现为准)。 2. **克隆**:复制当前菜单及其菜单项,用于快速创建结构相近的新菜单。此功能从 Halo 2.24 开始提供。 3. **编辑**:编辑当前菜单的名称。 4. **删除**:删除当前菜单,会同时删除菜单下的所有菜单项。 ## 创建菜单项 点击菜单项列表右上角的 **新建** 可以打开新建菜单的对话框。 ![Create menu item](/img/user-guide/menus/create-menu-item.png) 表单项说明: 1. **上级菜单项**:可以选择当前新建的菜单项归属的上级菜单项。 2. **类型**: 1. 自定义链接:可以输入任意的名称和链接地址,可以是外部的网址。 2. 文章:可以选择网站上已有的文章。 3. 自定义页面:可以选择网站上已有的页面。 4. 分类:可以选择网站上已有的分类。 5. 标签:可以选择网站上已有的标签。 3. **名称**:当类型为自定义链接时,可以输入任意的名称,当类型为文章、自定义页面、分类、标签时,会自动生成名称。 4. **链接地址**:当类型为自定义链接时,可以输入任意的链接地址,当类型为文章、自定义页面、分类、标签时,会自动生成链接地址。 5. **打开方式**:链接的打开方式。 ![Create menu item 2](/img/user-guide/menus/create-menu-item-2.png) 上图是类型选择 **分类** 时的表单,可以选择分类。 ![Menu item operation](/img/user-guide/menus/menu-item-operation-2.26.png) 点击菜单项条目的操作按钮可以展开操作选项,包括: 1. **编辑**:编辑当前菜单项的信息。 2. **新增子菜单项**:新增当前菜单项的子菜单项。 3. **删除**:删除当前菜单项,如果当前菜单项包含子菜单项,会同时删除。 ## 排序 你可以按住菜单项前的图标,通过拖拽来调整菜单项间的层级关系和顺序。 ![Sort](/img/user-guide/menus/sort.gif) --- url: https://docs.halo.run/guide/use/themes.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 主题 主题包含了各种站点页面模板的资源包。用户访问 Halo 站点浏览到的内容及样式,由 Halo 管理端所配置使用的主题所决定。 :::info 主题获取渠道 目前有两个官方渠道可以获取主题: - 应用市场:[https://www.halo.run/store/apps](https://www.halo.run/store/apps) - Awesome Halo:[https://github.com/halo-sigs/awesome-halo](https://github.com/halo-sigs/awesome-halo) ::: ## 安装主题 点击主题页面右上方的 `主题管理` 按钮即可弹出主题管理对话框。 在已安装主题列表中,可以按主题名称搜索。 ![已安装主题列表与批量操作](/img/user-guide/themes/themes-installed-2.26.png) ### 从内置应用市场安装(推荐) 从 Halo 2.10 开始,内置了应用市场插件,可以更加方便在 Console 直接安装应用市场的主题。 ![安装主题](/img/user-guide/app-store/app-store-themes.png) :::info 查看内置应用市场指南 更多关于内置应用市场的使用说明可查阅:[应用市场](https://docs.halo.run/guide/use/app-store.md) ::: ### 本地上传安装 你可以点击主题管理对话框下方的 `安装主题` 按钮,在弹出的安装主题对话框中上传主题压缩包。 ![安装主题](/img/user-guide/themes/theme-install.png) ### 远程下载安装 同样,在安装主题的对话框中,切换到远程下载选项卡,输入主题的下载地址,点击 `下载` 按钮即可开始下载主题。 ## 切换主题 同样点击主题页面右上方的 `主题管理` 按钮弹出主题管理对话框。 在弹框中点击选中要切换的目标主题,此时页面返回到主题详情页,点击右上角的 `启用` 按钮即可将当前主题切换为实际使用的主题。 :::info 选中主题不会自动启用 仅选中主题不点击右上角的 `启用` 按钮时,不会影响当前实际使用的主题。 ::: 你也可以在已安装主题列表中,通过后方 `···` 的更多操作中的启用选项直接启用指定的主题。 ## 修改主题设置 主题页面默认显示出了当前主题的详细信息,在详细信息标签页后方的标签页,即为主题提供的相关设置。不同的主题提供的设置项各不相同,设置项的详细说明请参考对应主题的文档。 ![主题设置](/img/user-guide/themes/theme-setting.png) 以 Halo 的默认主题 Earth 为例,该主题提供了布局、样式、侧边栏、页脚及备案设置共五组配置项。 :::info 重置主题设置 你可以点击主题列表指定主题所在行后方的 `···` 更多操作按钮,选择其中的 `重置` 选项将主题提供的设置项恢复为默认值。 ::: ## 预览主题 通过预览功能,你可以在不更改当前启用主题的情况下查看不同主题的效果。点击主题详情页面右上角的 `预览` 按钮预览当前主题,或者进入已安装主题列表,通过后方 `···` 的更多操作中的预览选项预览指定的主题。 在主题预览页面你可以切换不同分辨率的设备,模拟主题在不同终端下的显示效果。也可以通过右上角的功能菜单切换预览的主题,或者调整当前主题的设置,查看不同设置下主题所展现的区别。 演示视频: ## 升级主题 如果当前使用了内置的应用市场插件,在主题更新后会在主题列表中显示更新提示,点击 **立即更新** 按钮即可。 手动升级可以点击主题详情页右上角的 `···` 更多操作按钮,选择其中的 `升级` 选项即可打开升级主题的对话框。 ## 重载主题配置 如果当前主题提供的设置项发生变化,可以通过 `···` 更多操作中的 `重载主题配置` 选项对主题配置项进行更新。 ## 重置 如果你需要清空所有主题配置并重新配置主题,你可以通过 `···` 更多操作中的 `重置` 选项将主题提供的设置项恢复为默认值。 ## 卸载主题 进入已安装主题列表,点击指定主题所在行后方的 `···` 更多操作按钮,选择其中的 `卸载` 选项即可对当前主题进行卸载。 ![卸载主题](/img/user-guide/themes/theme-uninstall-2.26.png) :::info 卸载方式的区别 目前提供了 `卸载` 及 `卸载并删除配置` 两种卸载方式。 仅卸载主题时主题的配置信息会进行保留,当重新安装主题后还可以使用之前已保存的配置。 ::: 批量卸载时,只能选择当前未启用的主题。请在确认不再需要这些主题后操作。 --- url: https://docs.halo.run/guide/use/plugins.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 插件 插件是用于扩展 Halo 功能的软件包。插件独立于 Halo 核心应用,可以单独安装、升级、卸载。 本文档仅对插件的基本管理功能进行说明,关于插件的详细使用说明请参考对应插件的文档。 :::info 插件获取渠道 目前有两个官方渠道可以获取插件: - 应用市场:[https://www.halo.run/store/apps](https://www.halo.run/store/apps) - Awesome Halo:[https://github.com/halo-sigs/awesome-halo](https://github.com/halo-sigs/awesome-halo) ::: ## 安装插件 进入插件管理页面,点击右上角的 `安装` 按钮即可打开插件安装的对话框。 ### 从内置应用市场安装(推荐) 从 Halo 2.10 开始,内置了应用市场插件,可以更加方便在 Console 直接安装应用市场的插件。 ![安装插件](/img/user-guide/app-store/app-store-plugins.png) :::info 查看内置应用市场指南 更多关于内置应用市场的使用说明可查阅:[应用市场](https://docs.halo.run/guide/use/app-store.md) ::: ### 本地上传安装 ![安装插件](/img/user-guide/plugins/plugin-install.png) 插件安装成功后,便会出现在插件管理的列表中。 :::info 注意第三方插件安全 从非 Halo 官网应用市场安装插件时,请务必注意其安全性。 ::: ### 远程下载安装 同样,在安装插件的对话框中,切换到远程下载选项卡,输入插件的下载地址,点击 `下载` 按钮即可开始下载插件。 :::info 注意第三方插件安全 从非 Halo 官网应用市场安装插件时,请务必注意其安全性。 ::: ## 插件设置 点击插件列表中的某个插件进入插件详情页面。与主题设置类似,插件详情页面默认显示出了当前插件的详细信息,在详细信息标签页后方的标签页,即为插件提供的相关设置。不同的插件提供的设置项各不相同,设置项的详细说明请参考对应插件的文档。 ![插件设置](/img/user-guide/plugins/plugin-setting.png) 此处以 `Umami` 插件为例。 :::info 重置插件设置 你可以点击插件列表指定插件所在行后方的 `···` 更多操作按钮,选择其中的 `重置` 选项将插件提供的设置项恢复为默认值。 ::: ## 启用/禁用插件 点击插件列表或插件详情页中的启用/禁用开关,即可切换插件的启用禁用状态。 ![插件启用/禁用](/img/user-guide/plugins/plugins-bulk-actions-2.26.png) 选中多个插件后,可以批量启用或禁用。批量操作只会处理当前状态允许执行该操作的插件。 ## 升级插件 如果当前使用了内置的应用市场插件,在插件更新后会在插件列表中显示更新提示,点击 **立即更新** 按钮即可。 手动升级可以点击具体插件的 `···` 更多操作按钮,选择其中的 `升级` 选项即可打开升级插件的对话框。 ## 重载插件 从 Halo 2.24 开始,已启用的插件可以通过 `···` 更多操作中的 `重载` 选项重新加载。插件运行状态异常或更新了需要重新加载的资源时,可以先尝试重载,无需重启 Halo。 ## 重置 如果你需要清空所有插件配置并重新配置插件,你可以通过 `···` 更多操作中的 `重置` 选项将插件提供的设置项恢复为默认值。 ## 卸载插件 点击插件列表指定插件所在行后方的 `···` 更多操作按钮,选择其中的 `卸载` 选项即可对当前插件进行卸载。 ![卸载插件](/img/user-guide/plugins/plugin-uninstall-2.26.png) 选中多个插件后,也可以批量卸载。 :::info 卸载方式的区别 目前提供了 `卸载` 及 `卸载并删除配置` 两种卸载方式。 仅卸载插件时插件的配置信息会进行保留,当重新安装插件后还可以使用之前已保存的配置。 ::: ## 扩展配置 在 Halo 的插件机制中,我们使用扩展点来实现插件与 Halo 核心应用的交互,插件可以通过扩展点来扩展 Halo 的功能。这就意味着插件可能会实现和 Halo 或者其他插件相同的扩展点,这时候就需要对扩展点进行管理。 以搜索引擎为例,Halo 默认提供了 `Lucene` 搜索引擎和对应的扩展点,那么用户在安装了其他搜索引擎插件之后就需要在这里进行选择,否则 Halo 无法确定使用哪个搜索引擎。 ![Extension point settings entry](/img/user-guide/plugins/extension-point-settings-entry.png) 进入插件管理,点击右上角的 `扩展配置` 按钮即可进入扩展配置页面。 ![Extension point settings](/img/user-guide/plugins/extension-point-settings.png) 这里以搜索引擎为例,安装了 `Meilisearch` 插件之后就可以在这里选择启用这个插件的搜索引擎。 更多关于扩展点的说明可以查阅:[插件开发 / 扩展点和定制化 / 扩展点](https://docs.halo.run/developer-guide/plugin/extension-points/server/index.md) --- url: https://docs.halo.run/guide/use/app-store.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 应用市场 为了方便使用者安装应用市场的主题和插件,我们提供了一个内置到 Console 的应用市场插件,可以更加方便在 Console 直接安装主题和插件。并且此插件从 Halo 2.10 开始已经预设到 Halo 中,无需手动安装。 如果你使用了旧版本的 Halo,并且当前未安装应用市场插件,可以访问 [https://www.halo.run/store/apps/app-VYJbF](https://www.halo.run/store/apps/app-VYJbF) 手动下载并在 Console 的插件管理中安装。 :::info 可安全停用应用市场插件 这是目前唯一由 Halo 官方提供的服务,如果你当前的 Halo 网站处于无法访问公网的环境或者不需要此功能,你可以卸载或者停用此插件,不会影响网站的正常使用。 ::: ## 应用市场页面 这是一个为 Console 提供的独立的应用市场页面,此页面基本和 [https://www.halo.run/store/apps](https://www.halo.run/store/apps) 保持一致,但有所不同的是,你可以直接在这里查看所有的主题和插件并安装到你的 Halo 站点中。 ![应用市场](/img/user-guide/app-store/app-store-page.png) ## 绑定 Halo 官网账号 ![账号绑定](/img/user-guide/app-store/app-store-pat.png) 绑定方式: 1. 进入应用市场插件的设置页面,切换到 **账号绑定** 选项卡。 2. 根据提示访问 Halo 官网并注册账号,然后在 Halo 官网的[个人中心](https://www.halo.run/uc/profile?tab=pat)生成一个个人令牌并填写到下方的 **个人令牌** 输入框即可。 ## 安装/更新插件 此插件还扩展了插件安装的界面,可以在安装插件时直接从应用市场获取。 ![安装插件](/img/user-guide/app-store/app-store-plugins.png) 此外,如果插件是从应用市场安装的,后续插件更新之后也可以及时收到更新信息,并一键更新。 ![更新插件](/img/user-guide/app-store/app-store-upgrade-plugin.png) ## 安装/更新主题 与插件一样,在主题管理中也可以直接从应用市场中获取,以及接收主题更新提示。 ![安装主题](/img/user-guide/app-store/app-store-themes.png) ![更新主题](/img/user-guide/app-store/app-store-upgrade-theme.png) ## 付费应用激活 部分付费主题和插件需要许可证激活才能够正常使用,在购买付费应用之后就会自动为你的 Halo 官网账号中生成对应的应用许可证,目前支持在线激活和离线激活两种方式。 ### 在线激活 :::info 在线激活方式 目前在线激活支持两种方式: 1. 通过 [Halo 官网账户](https://www.halo.run/):如果你是在 Halo 官网购买的付费应用,需要通过这种方式,并提前[绑定 Halo 官网账号](#绑定-halo-官网账号) 2. 通过 [Halo 专业版/商城版许可证](https://docs.halo.run/guide/prepare.md#%E5%8F%91%E8%A1%8C%E7%89%88%E6%9C%AC):如果你购买了 [Halo 付费版](https://docs.halo.run/guide/prepare.md#%E5%8F%91%E8%A1%8C%E7%89%88%E6%9C%AC),可以选择这个选项来激活应用 关于 Halo 专业版/商城版许可证的更多信息可查阅:[许可证激活 / 查看和下载付费应用](https://docs.halo.run/guide/use/activate.md#%E6%9F%A5%E7%9C%8B%E5%92%8C%E4%B8%8B%E8%BD%BD%E4%BB%98%E8%B4%B9%E5%BA%94%E7%94%A8) ::: 在安装好需要许可证的付费插件或主题后,列表会显示一个许可证状态的图标,点击即可打开许可证激活的对话框,选择 **Halo 官网账户** 或 **Halo 专业版/商城版许可证** 并点击激活即可。 ![插件激活状态](/img/user-guide/app-store/app-store-license-status-2.22.png) ![插件许可证激活](/img/user-guide/app-store/app-store-plugin-license-2.22.png) 除此之外,你也可以在 **许可证管理** 页面查看所有应用的许可证,并管理它们的状态。 ![许可证列表](/img/user-guide/app-store/app-store-license-manage-2.22.png) ### 离线激活 如果你的 Halo 网站无法访问公网,你可以选择离线激活的方式。 ### 打开许可证激活对话框 同样点击许可证状态的图标,打开许可证激活的对话框。 ![插件激活状态](/img/user-guide/app-store/app-store-license-status.png) ### 选择激活方式 激活方式选择许可证。 ![离线激活选项](/img/user-guide/app-store/app-store-license-offline-option.png) ### 复制离线许可证凭证 点击 **复制离线许可证凭证** 按钮,然后点击 **去生成** 按钮,然后会跳转到 Halo 官网去生成离线激活码。 ### 生成离线许可证 找到对应的许可证,选择 **生成离线许可证**。 ![生成离线激活码](/img/user-guide/app-store/app-store-license-generate-license-1.png) ### 复制离线许可证 在 **生成离线许可证** 的对话框中,粘贴刚刚复制的离线许可证凭证,然后点击 **生成并复制** 按钮,然后会打开 **查看离线许可证** 对话框,你可以选择下载文件或者复制许可证。 ![生成离线激活码](/img/user-guide/app-store/app-store-license-generate-license-2.png) ![生成离线激活码](/img/user-guide/app-store/app-store-license-generate-license-3.png) ### 激活离线许可证 回到 Halo 网站,粘贴刚刚复制的离线许可证,然后点击 **激活** 按钮即可。 ![离线激活](/img/user-guide/app-store/app-store-license-offline.png) 其他注意事项: 1. 目前同一个账号的许可证在同一时间只能在一个站点中使用,使用 Halo 配置中的 **外部访问地址(halo.external-url)** 和设备 id 做判定。 2. 取消激活会删除许可证使用记录。 --- url: https://docs.halo.run/guide/use/users.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 用户与权限 ## 概览 Halo 2.0 版本采用了基于角色的权限控制(RBAC)体系。不同于之前 1.x 版本的单用户设计,现在你可以创建多个用户并且通过赋予不同用户不同角色的方式,为他们分配不同的权限。 ## 用户 点击左侧导航栏的 `用户` 条目进入用户管理页面。 ### 创建用户 在用户管理页面,点击右上角的 `添加用户` 按钮即可弹出新建用户对话框。 ![创建用户](/img/user-guide/users/user-setting-2.20+.png) 目前支持配置的用户属性有: - **用户名**:用户登录 Halo 控制台使用的用户名,不可与已有的用户名重复; - **显示名称**:用于显示文章作者等用户信息时使用的,更友好的用户名称; - **电子邮箱**:用户的电子邮箱; - **新密码**:用户的初始密码; - **角色**:用户的初始角色; - **描述**:可以用于为用户添加备注。 ### 其他操作 点击用户列表中的 `···` 更多操作按钮,可以对指定用户进行修改资料、修改密码等其他更多操作。 ![用户列表其他操作](/img/user-guide/users/user-operate.png) #### 修改用户资料 你可以修改除用户名以外的所有资料,具有用户管理相关权限的用户,也可对其他用户的资料进行修改。 #### 修改用户密码 对于已有的用户,你可以在 `···` 更多操作中修改指定用户的登录密码。 #### 分配角色 对于已有的用户,你可以在 `···` 更多操作中为该用户分配角色,分配角色后该用户具有角色所对应的权限。 :::info 修改角色会影响权限 修改用户分配的角色会影响用户所拥有的权限,可能影响用户使用。 ::: #### 删除用户 对于已有的用户,你可以在 `···` 更多操作中删除该用户。 :::warning 删除用户的影响 删除用户后,该用户之前创建的文章、页面等内容的作者信息将会丢失,可能影响站点内容浏览。此操作不可恢复。 ::: ## 角色 如下图所示,在用户管理页面,点击右上角红色区域的 `角色管理` 按钮,即可进入到角色管理页面。 ![角色管理](/img/user-guide/users/role-management.png) ### 创建角色 Halo 提供了全新创建和基于已有角色创建两种角色创建方式。 #### 全新创建 点击角色管理页面右上角的 `新建角色` 按钮即可弹出新建角色对话框,通过这种方式创建的角色默认未勾选任何权限,你需要在对话框中点击切换到权限标签页,为该角色勾选需要的权限。 #### 基于已有角色创建 ![基于已有角色创建角色](/img/user-guide/users/role-fork.png) 当系统中已经存在一些基础角色时,你可以点击某个角色所在行中的 `···` 更多操作按钮,选择 `基于此角色创建` 来创建一个新的角色。通过这种方式创建的角色默认继承了原有角色的权限,但你同样可以对新角色的权限进行进一步调整。 ![创建角色](/img/user-guide/users/role-creation.png) - **名称**:角色的名称。 - **禁止访问 Console**:勾选后,该角色的用户将无法进入 Console 管理控制台,只能访问个人中心(/uc)。 - **权限**:角色的权限,可以选择多个权限。 ### 修改角色信息 对于已有的角色,你可以在 `···` 更多操作中修改指定角色的名称和该角色所拥有的权限。 ### 其他操作 对于已有的角色,你可以在 `···` 更多操作中删除指定角色。 :::warning 删除角色的影响 删除角色后,分配了该角色的用户会丧失对应的权限,影响用户使用。此操作不可恢复。 ::: ## 身份认证 Halo 内置用户名或已验证邮箱加密码的本地认证。从 Halo 2.26 开始,Halo 还内置邮箱验证码认证;配置邮件通知后,可以在身份认证管理页面启用。其他第三方认证方式可以通过插件扩展。 :::info 官方身份认证插件 目前 Halo 官方提供的身份认证插件: - [OAuth2 认证](https://www.halo.run/store/apps/app-ESVDK) - [社交 IAM 认证(包含在 Halo 付费版)](https://www.halo.run/store/apps/app-IXZkJ) - [LDAP 认证(包含在 Halo 付费版)](https://www.halo.run/store/apps/app-vrSqF) ::: 你可以在用户管理界面的右上角点击 `身份认证` 按钮,进入身份认证管理页面。 ![身份认证](/img/user-guide/users/users-2.26.png) 进入身份认证管理页面之后,如果你已经安装了提供身份认证方式的插件,你就可以在列表中看到对应的身份认证方式,你可以对其进行设置并启用。 ![身份认证方式](/img/user-guide/users/auth-providers-2.26.png) ### 邮箱验证码登录 使用邮箱验证码登录前,需要先完成以下配置: 1. 在[通知设置](https://docs.halo.run/guide/use/settings.md#%E9%82%AE%E4%BB%B6%E9%80%9A%E7%9F%A5)中配置邮件服务器; 2. 在身份认证管理页面启用邮箱验证码认证; 3. 用户在个人中心验证自己的邮箱地址。 启用后,可以拖拽认证方式调整它在登录页面中的顺序。 ### 第三方认证首次登录 通过 OAuth2 等第三方认证方式首次登录时,用户可以绑定已有 Halo 账号。站点开放注册时,也可以创建新账号;如果站点设置了注册协议或必填资料,用户需要先完成相关步骤。 ### 手机验证码登录 :::note 仅限 Halo 付费版 限 [Halo 付费版](https://docs.halo.run/guide/prepare.md#%E5%8F%91%E8%A1%8C%E7%89%88%E6%9C%AC) 可用。 ::: 在 [短信通知](https://docs.halo.run/guide/use/settings.md#%E7%9F%AD%E4%BF%A1%E9%80%9A%E7%9F%A5) 中配置好短信通知后,就可以在身份认证管理页面中开启手机验证码登录,也可以通过拖拽的方式调整默认登录方式。 --- url: https://docs.halo.run/guide/use/settings.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 站点设置 ## 基本设置 Halo 提供了以下站点基本信息设置: - **站点标题** - **站点副标题** - **Logo** - **Favicon** - **首选语言** 在控制台设置完成后,主题端可以通过特定的表达式获取到这些信息并且在对应的位置进行展示。具体是否读取使用这些配置、在哪些位置显示这些信息由使用的不同主题而决定。 以 Halo 2.0 的[默认主题 Earth](https://github.com/halo-dev/theme-earth) 为例,这些设置信息将在如下位置进行展示。 ![默认主题基本设置说明](/img/user-guide/settings/setting-basic.png) ## 文章设置 针对主题端的文章展示,Halo 提供了以下设置项: - **文章列表显示条数**:首页的文章显示条数。 - **归档页文章显示条数**:归档页面(/archives)的文章显示条数。 - **分类页文章显示条数**:分类归档页面(/categories/\{slug})的文章显示条数。 - **标签页文章显示条数**:标签归档页面(/tags/\{slug})的文章显示条数。 - **作者页文章显示条数**:作者归档页面(/authors/\{name})的文章显示条数。 - **别名生成策略**: - 根据标题:自动根据文章标题生成,比如文章标题为 `Hello Halo`,那么别名将生成为 `hello-halo` - 时间戳:使用当前时间的时间戳作为标题 - Short UUID:生成类似于 `BT5kIgrb` 的别名 - UUID:生成类似于 `4f662408-ed90-470b-9ed1-7fdc0283631b` 的别名 - **附件存储策略**:在编辑器中上传图片时的附件存储策略 - 已经在 Halo 2.22 中标记为过时,后续请使用 [附件设置](#附件设置) 代替 - **附件存储组**:在编辑器中上传图片时的附件分组 - 已经在 Halo 2.22 中标记为过时,后续请使用 [附件设置](#附件设置) 代替 ![文章设置](/img/user-guide/settings/settings-post-2.26.png) ## SEO 设置 针对站点的 SEO(搜索引擎优化)需求,Halo 提供了以下设置项: - **屏蔽搜索引擎**:配置后会在所有页面 HTML 源码的 head 部分添加: ```html ``` :::info 提示 需要注意的是,并不是所有搜索引擎都会遵守这个规则。 ::: - **站点关键词**:格式为以 `,` 分隔的关键词列表,配置后会在所有页面 HTML 源码的 head 部分添加: ```html ``` :::warning 注意 目前主流的搜索引擎(如 Google、Bing、百度搜索等)已经不再使用该标签作为关键词的参考,因此该设置项的作用已经不大,未来我们也可能会移除该设置项。 ::: - **站点描述**:仅对首页生效,配置后会在首页 HTML 源码的 head 部分添加: ```html ``` 其他页面会根据页面类型和内容自动生成描述。 ## 用户设置 - **开放注册**:是否允许访客注册,勾选之后在登录页面会显示注册入口。 - **注册需验证邮箱**:开启之后,用户注册时必须要经过邮箱验证,需要配置好 [邮件通知](#通知设置)。 - **保留用户名与名称**:设置之后,这些用户名或显示名称将无法被其他用户注册或修改使用。多个值使用英文逗号 `,` 分隔。 - **默认角色**:新注册用户的默认角色。 - **注册时所需协议**:选择注册时需要用户阅读并同意的自定义页面,例如用户协议、隐私政策等。 - **头像存储位置**:用户上传头像的存储策略。 - 已经在 Halo 2.22 中标记为过时,后续请使用 [附件设置](#附件设置) 代替 - **个人中心附件存储位置**:用户在个人中心端上传附件时的默认存储策略,需要用户包含上传附件的权限。 - 已经在 Halo 2.22 中标记为过时,后续请使用 [附件设置](#附件设置) 代替 ![用户注册设置](/img/user-guide/settings/settings-user-registration-2.26.png) ### 注册协议页面 开启 **开放注册** 后,可以通过 **注册时所需协议** 选择一个或多个自定义页面作为注册协议。保存后,注册页面会显示 `我已阅读并同意` 勾选项,并将已选择的页面显示为可点击链接。用户必须勾选同意后才能提交注册。 从 Halo 2.25.0 开始,新安装站点会在初始化时自动创建 **用户协议** 和 **隐私政策** 两个自定义页面,并默认将它们配置为注册时所需协议。 :::warning 开放注册前替换协议内容 自动创建的协议页面只包含占位内容。正式开放注册前,请进入 [页面](https://docs.halo.run/guide/use/pages.md) 管理并替换为你站点实际使用的用户协议、隐私政策或其他合规说明。 ::: 如果不需要在注册时要求用户同意协议,可以清空 **注册时所需协议** 并保存设置。 ## 附件设置 - **管理端附件配置**:为管理端设置附件上传默认的存储策略和分组,通常用于直接上传附件的场景,比如在文章编辑器中粘贴上传。 - **个人中心附件配置**:为个人中心设置附件上传默认的存储策略和分组,如果你的网站允许部分用户在个人中心创建文章,**那么建议单独创建一个专门的存储策略,并限制文件格式和大小**。 - **头像附件配置**:用户上传头像的存储策略配置,**建议单独创建存储策略并限制仅允许上传图片**。 ## 评论设置 针对站点的评论功能,Halo 提供了以下设置项: - **启用评论**:全局评论功能开关配置,修改后影响所有文章、页面的评论功能。 - **新评论审核**:新增的评论是否需要在控制台进行审核,审核通过后其他访问者才能看到该条评论。 - **仅允许注册用户评论**:开启后只有登录用户才能添加评论,关闭后匿名(未登录)的访客也可以通过自行填写昵称、邮箱、网址等信息进行评论。 ## 主题路由设置 针对访问站点各种类型页面的 URL 生成规则,Halo 提供了以下主题路由设置项: - **关闭主题预览**:关闭后,未包含主题管理权限的用户无法通过参数预览未启用的主题。 - **分类页路由前缀**:定位到分类列表页面以及分类归档页面。 - 默认的分类列表页面 URL 规则前缀为 `/categories` - 默认的分类归档页面 URL 规则前缀为 `/categories/{slug}` - **标签页路由前缀**:定位到标签列表页面以及标签归档页面。 - 默认的标签列表页面 URL 规则前缀为 `/tags` - 默认的标签归档页面 URL 规则前缀为 `/tags/{slug}` - **归档页路由前缀**:定位到文章归档页面的 URL 规则前缀,默认为 `/archives`。 - **文章详情页访问规则**:定位到具体文章详情页面的 URL 规则前缀,默认为 `/archives/{slug}` ,用户可从以下路径规则进行选择: - `/archives/{slug}` - `/archives/{name}` - `/?p={name}` - `/?p={slug}` - `/{year}/{slug}` - `/{year}/{month}/{slug}` - `/{year}/{month}/{day}/{slug}` - `/categories/{categorySlug}/{slug}` :::info 变量说明 - `slug`:文章别名 - `name`:文章 `metadata.name` 字段值 - `year`:四位数格式的文章发布年份 - `month`:两位数格式的文章发布月份 - `day`:两位数格式的文章发布日 - `categorySlug`:文章所属分类的别名;文章没有分类时使用默认值 `uncategorized` ::: ![主题路由设置](/img/user-guide/settings/settings-routes-2.26.png) ## 代码注入 你可以使用代码注入功能,在特定类型的页面中注入额外的代码。你可以通过该功能覆盖或补充部分主题 CSS 样式,或者引入额外的 JavaScript 脚本扩展主题端功能。 - **全局 head 标签**:该代码将会被注入到所有页面的 head 标签中。 - **内容页 head 标签**:该代码将会被注入到文章、页面详情页的 head 标签中。 - **页脚**:该代码将会被注入到所有页面的页脚中。 ## 品牌信息 :::note 仅限 Halo 付费版 限 [Halo 付费版](https://docs.halo.run/guide/prepare.md#%E5%8F%91%E8%A1%8C%E7%89%88%E6%9C%AC) 可用。 :::

- **登录页 Logo**:登录、注册等页面的 Logo 设置,如果不填写将默认使用 Halo 的标志。 - **登录页 Logo 大小**:用于调整登录页面的 Logo 大小。 - **控制台 Logo**:Console 控制台、UC 个人中心的 Logo 设置,如果不填写将默认使用 Halo 的标志。 - **控制台 Logo 大小**:用于调整控制台的 Logo 大小。 - **显示控制台页脚信息**:是否显示 Console 控制台和 UC 个人中心底部的版权信息。 - **自定义页脚信息**:如果勾选了 **显示控制台页脚信息**,可以自定义底部的版权信息,支持 HTML,如果不填写将使用默认的 Halo 版权信息。 ## 通知设置 从 2.10.0 版本开始,Halo 提供了 **通知** 功能,当有新的评论、留言、回复等事件发生时,Halo 会通过配置的方式通知站长或者相关用户。同时,个人中心配置的电子邮箱也会作为通知的接收邮箱。 ### 邮件通知 - **启用邮件通知器**:开启后,当有新的评论、留言、回复等事件发生时,Halo 会通过 **邮件** 的方式通知站长或者相关用户。 - **用户名**:你需要在此处填写你的 **邮箱账号**。 - **密码**:你需要在此处填写你的 **邮箱密码** 或相关的 **授权码**,具体请参考你所使用邮箱的相关说明。 - **显示名称**:你需要在此处填写你的 **邮箱显示名称**,该名称将会作为邮件发送者的名称显示。 - **SMTP 服务器地址**:你需要在此处填写你的 **SMTP 服务器地址**,具体请参考你所使用邮箱的相关说明。 - **端口号**:你需要在此处填写你的 **SMTP 服务器端口号**,具体请参考你所使用邮箱的相关说明。 - **加密方式**:你需要在此处选择你的 **SMTP 服务器加密方式**,具体请参考你所使用邮箱的相关说明。 > 常见邮箱服务商的文档如下: > > - [QQ 邮箱](https://service.mail.qq.com/detail/0/310) > - [163 邮箱](https://help.mail.163.com/faqDetail.do?code=d7a5dc8471cd0c0e8b4b8f4f8e49998b374173cfe9171305fa1ce630d7f67ac2a5feb28b66796d3b) > - [Gmail](https://support.google.com/mail/answer/7104828?hl=zh-Hans) > - [阿里云企业邮箱](https://help.aliyun.com/document_detail/36687.html) > - [腾讯企业邮箱](https://open.work.weixin.qq.com/help2/pc/19870) ### 短信通知 :::note 仅限 Halo 付费版 限 [Halo 付费版](https://docs.halo.run/guide/prepare.md#%E5%8F%91%E8%A1%8C%E7%89%88%E6%9C%AC) 可用。 ::: 目前短信通知在 Halo 中基本只作为用户登录时发送验证码使用,以下是配置说明: - 提供商 (腾讯云/阿里云/UCloud):目前仅支持腾讯云、阿里云、UCloud 短信服务中的国内短信服务,即仅能向中国大陆手机号码发送短信 - 超时时间:短信在系统中记录的超时时间,超过当前时间后系统会判断已到期 - 验证码长度:发送验证码到手机商的长度,一般为 6 位 - 提供商具体配置:不同的提供商需要提供的参数不一致,具体提供商的具体参数说明请参考后续文档 - 测试短信:提供检测机制测试当前的配置是否有效。点击测试短信会发送短信给当前操作用户,所以当前的用户在个人信息中配置正确的手机号码 #### 腾讯云短信服务配置说明 在 Halo 中进行以下设置之前,需要先在腾讯云开通短信服务,并创建可用的签名、模板及应用等内容。 - [腾讯云短信服务控制台地址](https://console.cloud.tencent.com/smsv2) - [腾讯云短信服务文档地址](https://cloud.tencent.com/document/product/382/37745) 1. SecretId:用于调用腾讯云接口的 API 密钥的 SecretId,可以在腾讯云控制台 [API密钥管理页面](https://console.cloud.tencent.com/cam/capi) 创建 2. SecretKey:用于调用腾讯云接口的 API 密钥的 SecretKey,可以在腾讯云控制台 [API密钥管理页面](https://console.cloud.tencent.com/cam/capi) 创建 3. 地域:腾讯云接口要求的必传参数,可选的地域列表可以查看 [腾讯云文档](https://cloud.tencent.com/document/api/382/52071#.E5.9C.B0.E5.9F.9F.E5.88.97.E8.A1.A8) 4. 应用 ID:在腾讯云短信服务 [应用管理菜单](https://console.cloud.tencent.com/smsv2/app-manage) 中创建的应用的 `SDK AppID` 5. 签名内容:在腾讯云短信服务 [签名管理菜单](https://console.cloud.tencent.com/smsv2/csms-sign) 中创建的签名的 `签名内容` 6. 模板 ID:在腾讯云短信服务 [正文模板管理菜单](https://console.cloud.tencent.com/smsv2/csms-template) 中创建的正文模板的 `ID` #### 阿里云短信服务配置说明 在 Halo 中进行以下设置之前,需要先在阿里云开通短信服务,并创建可用的签名、模板等内容。 - [阿里云短信服务控制台地址](https://dysms.console.aliyun.com/overview) - [阿里云短信服务文档地址](https://help.aliyun.com/zh/sms/) 1. AccessKey ID:用于调用阿里云接口的 API 密钥的 AccessKey ID,可以在阿里云控制台 [AccessKey管理页面](https://ram.console.aliyun.com/manage/ak) 创建 2. AccessKey Secret:用于调用阿里云接口的 API 密钥的 AccessKey Secret,可以在阿里云控制台 [AccessKey管理页面](https://ram.console.aliyun.com/manage/ak) 创建 3. 地域:阿里云接口要求的必传参数,可选的地域列表可以查看 [阿里云文档](https://help.aliyun.com/zh/sms/developer-reference/api-dysmsapi-2017-05-25-endpoint?spm=a2c4g.11174283.0.0.13d64994r9G5rN) 4. 短信签名:在阿里云短信服务 [签名管理菜单](https://dysms.console.aliyun.com/domestic/text/sign) 中创建的签名的 `签名名称` 5. 短信模板:在阿里云短信服务 [模板管理菜单](https://dysms.console.aliyun.com/domestic/text/template) 中创建的模板的 `模板CODE` #### UCloud 短信服务配置说明 在 Halo 中进行以下设置之前,需要先在 UCloud 开通短信服务,并创建可用的签名、模板等内容。 - [UCloud 短信服务控制台地址](https://console.ucloud.cn/usms) - [UCloud 短信服务文档地址](https://docs.ucloud.cn/usms/README) > 目前仅支持国内短信且短信模版仅支持一个变量的验证码类型短信模版如:**你的验证码为\{1},该验证码5分钟内有效,如非本人操作,请忽略本短信!** 1. 公钥:用于调用 UCloud 接口的 API 密钥的 公钥,可以在 UCloud 控制台 [API密钥](https://console.ucloud.cn/uaccount/api_manage) 创建 2. 私钥:用于调用 UCloud 接口的 API 密钥的 私钥,可以在 UCloud 控制台 [API密钥](https://console.ucloud.cn/uaccount/api_manage) 创建 3. 项目 ID:UCloud 接口要求的必传参数,可选的项目列表可以查看 [项目管理](https://console.ucloud.cn/uaccount/iam/project_manage) 中的`项目ID` 4. 模版 ID:在 UCloud 短信服务 [短信模板](https://console.ucloud.cn/usms/domestic) 中创建的签名的 `模板ID` 5. 签名内容:在 UCloud 短信服务 [短信签名](https://console.ucloud.cn/usms/domestic) 中创建的签名的 `签名内容` 配置完成之后,可以在 [身份认证](https://docs.halo.run/guide/use/users.md#%E8%BA%AB%E4%BB%BD%E8%AE%A4%E8%AF%81) 中开启手机号登录。 --- url: https://docs.halo.run/guide/use/backup.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 备份与恢复 从 Halo 2.8 开始,Halo 内置了备份和恢复的功能,可以在 Console 中一键备份和恢复完整的数据。 ## 备份 :::warning 商城数据不包含在备份中 因为商城相关的功能数据存储结构不同,所以备份和恢复功能暂不支持商城相关的数据,建议直接备份数据库。 所以如果你使用了 Halo 商城版的商城功能,备份文件不会包含商城相关的数据。 ::: 在 Console 中,点击左侧菜单的 `备份`,进入备份页面。 点击右上角的 `创建备份` 按钮,即可创建一个新的备份请求,需要注意的是,创建备份请求并不会立即开始备份,而是会在后台异步执行,因此需要等待一段时间才能看到备份的结果。 ![Create a backup](/img/user-guide/backup/create-backup.png) 备份中: ![Backup running](/img/user-guide/backup/backup-running.png) 备份完成: ![Backup complete](/img/user-guide/backup/backup-complete.png) ## 自动备份与同步 为了保障数据的安全,Halo 提供了自动备份和同步的[备份增强插件](https://www.halo.run/store/apps/app-dHakX),可以定期将数据备份到本地并同步到云端。 :::note 仅限 Halo 付费版 此插件目前为 [Halo 付费版](https://docs.halo.run/guide/prepare.md#%E5%8F%91%E8%A1%8C%E7%89%88%E6%9C%AC) 专享插件。 ::: ![Auto backup and sync](/img/user-guide/backup/auto-backup.png) ## 恢复 :::info 恢复备份前须知 1. 恢复不限制部署方式,也不限制数据库,也就是说新站点的部署方式和数据库类型可以和备份的站点不同。 2. 恢复过程可能会持续较长时间,期间请勿刷新页面。 3. 在恢复的过程中,虽然已有的数据不会被清理掉,但如果有冲突的数据将被覆盖。 4. 恢复完成之后会提示停止运行 Halo,停止之后可能需要手动运行。 ::: 在 Console 中,点击左侧菜单的 `备份`,进入备份页面,然后点击 `恢复` 选项卡即可进入恢复界面,阅读完注意事项之后点击 `开始恢复` 按钮即可显示备份文件上传界面。 ![Before restore](/img/user-guide/backup/before-restore.png) ![Restore](/img/user-guide/backup/restore.png) Halo 支持三种恢复方式: 1. 上传备份文件:上传已有的备份文件进行恢复。 2. 远程恢复:从远程 URL 下载备份文件进行恢复。 3. 从备份文件恢复:支持从 [工作目录](https://docs.halo.run/guide/prepare.md#%E5%B7%A5%E4%BD%9C%E7%9B%AE%E5%BD%95) 的 backups 目录扫描备份文件,并选择文件进行恢复。 :::info 大文件建议从服务器恢复 如果你的备份文件较大,推荐提前将备份文件上传到服务器,然后选择 `从备份文件恢复` 方式进行恢复,避免因为网络原因导致上传失败。 ::: 使用 `上传备份文件` 方式进行恢复的操作示例: 选择备份文件后,点击 `上传` 按钮即可开始上传备份文件,上传完成后会自动开始恢复。 ![Restore upload](/img/user-guide/backup/restore-upload.png) 恢复完成,会提示重启 Halo,点击 `确定` 按钮即可重启 Halo。 ![Restore complete](/img/user-guide/backup/restore-complete.png) ![Waiting restart](/img/user-guide/backup/waiting-restart.png) 最后,建议去服务器检查 Halo 的运行状态,如果没有设置自动重启,需要手动重启。 --- url: https://docs.halo.run/guide/use/mobile-app.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 移动端 App :::note 仅限 Halo 付费版本 移动端 App 绑定要求站点已激活付费版本,并由超级管理员操作。 ::: Halo 付费版本支持将站点绑定到移动端 App,以便从移动设备管理站点。 ## 绑定设备 ### 安装 App 从[移动端 App 下载页面](https://www.lxware.cn/halo-app)安装 App。 ### 进入移动端 App 页面 使用超级管理员登录 Halo 控制台,进入 **工具 -> 移动端 App**。 ### 开始绑定设备 点击 **绑定设备**。 ### 显示二维码 阅读安全提示后点击 **显示二维码**。 ### 扫描二维码 使用 App 扫描二维码,等待控制台提示绑定成功。 绑定成功后,控制台会显示设备名称、IP 地址、绑定时间和状态。 :::warning 二维码等同于超级管理员凭证 绑定过程会为 App 颁发具有超级管理员权限的个人令牌。不要分享或保存绑定二维码,并妥善保管已绑定设备。 ::: ## 删除绑定 在设备列表中打开操作菜单并选择 **删除**。删除后,该 App 将无法继续连接此站点,与绑定关联的个人令牌也会被撤销。 设备遗失、转交他人或不再使用时,应立即删除对应绑定。 --- url: https://docs.halo.run/guide/shop/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 商城模块 ## 商城模块 ### [写在前面](/guide/shop/prepare.md) - [前提条件](/guide/shop/prepare.md#前提条件) - [前台路由](/guide/shop/prepare.md#前台路由) ### [控制台首页](/guide/shop/console-home.md) ### [商店设置](/guide/shop/settings.md) - [店铺](/guide/shop/settings.md#店铺) - [小程序](/guide/shop/settings.md#小程序) - [订单号](/guide/shop/settings.md#订单号) ### [支付方式](/guide/shop/payments.md) - [支付宝](/guide/shop/payments.md#支付宝) - [微信支付](/guide/shop/payments.md#微信支付) - [易支付](/guide/shop/payments.md#易支付) - [Stripe](/guide/shop/payments.md#stripe) - [银行转账](/guide/shop/payments.md#银行转账) - [收款码支付](/guide/shop/payments.md#收款码支付) ### [销售渠道](/guide/shop/sales-channels.md) - [创建销售渠道](/guide/shop/sales-channels.md#创建销售渠道) ### [产品管理](/guide/shop/products.md) - [查找和管理产品](/guide/shop/products.md#查找和管理产品) - [创建产品](/guide/shop/products.md#创建产品) - [管理分类](/guide/shop/products.md#管理分类) - [管理属性模板](/guide/shop/products.md#管理属性模板) - [发布产品](/guide/shop/products.md#发布产品) ### [订阅管理](/guide/shop/subscriptions.md) - [创建订阅产品](/guide/shop/subscriptions.md#创建订阅产品) - [订阅档次](/guide/shop/subscriptions.md#订阅档次) - [订阅计划](/guide/shop/subscriptions.md#订阅计划) - [变更规则](/guide/shop/subscriptions.md#变更规则) - [订阅策略](/guide/shop/subscriptions.md#订阅策略) - [管理订阅](/guide/shop/subscriptions.md#管理订阅) - [客户自助管理](/guide/shop/subscriptions.md#客户自助管理) - [续费提醒邮件](/guide/shop/subscriptions.md#续费提醒邮件) - [相关设置](/guide/shop/subscriptions.md#相关设置) - [限制](/guide/shop/subscriptions.md#限制) - [相关文档](/guide/shop/subscriptions.md#相关文档) ### [营销](/guide/shop/marketing.md) - [折扣](/guide/shop/marketing.md#折扣) - [优惠券](/guide/shop/marketing.md#优惠券) ### [订单管理](/guide/shop/orders.md) - [查找订单](/guide/shop/orders.md#查找订单) - [手动创建订单](/guide/shop/orders.md#手动创建订单) - [查看订单详情](/guide/shop/orders.md#查看订单详情) - [发货](/guide/shop/orders.md#发货) ### [虚拟交付](/guide/shop/virtual-delivery.md) - [创建产品](/guide/shop/virtual-delivery.md#创建产品) - [设置文件资源下载](/guide/shop/virtual-delivery.md#设置文件资源下载) - [设置卡密发货](/guide/shop/virtual-delivery.md#设置卡密发货) - [订单相关](/guide/shop/virtual-delivery.md#订单相关) - [API 规范](/guide/shop/virtual-delivery.md#api-规范) ### [商城客户中心](/guide/shop/customer-center.md) - [收货地址](/guide/shop/customer-center.md#收货地址) - [优惠券](/guide/shop/customer-center.md#优惠券) - [订单](/guide/shop/customer-center.md#订单) - [订阅](/guide/shop/customer-center.md#订阅) ### [Webhook](/guide/shop/webhooks.md) - [创建 Webhook](/guide/shop/webhooks.md#创建-webhook) - [请求格式](/guide/shop/webhooks.md#请求格式) - [验证签名](/guide/shop/webhooks.md#验证签名) - [返回状态与重试](/guide/shop/webhooks.md#返回状态与重试) - [防止重复处理](/guide/shop/webhooks.md#防止重复处理) - [查看投递记录](/guide/shop/webhooks.md#查看投递记录) ### [小程序](/guide/shop/mp.md) - [获取方式](/guide/shop/mp.md#获取方式) - [使用流程](/guide/shop/mp.md#使用流程) - [在 Halo 中配置](/guide/shop/mp.md#在-halo-中配置) - [配置支付渠道](/guide/shop/mp.md#配置支付渠道) ### [商城主题开发](/guide/shop/theme-dev.md) --- url: https://docs.halo.run/guide/shop/prepare.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 写在前面 ## 前提条件 在开始使用商城功能之前,需要先确定以下条件是否已满足: - 正常安装 [Halo 商城版](https://docs.halo.run/guide/install/index.md) - 激活 [Halo 商城版许可证](https://docs.halo.run/guide/use/activate.md) - 根据当地法律法规,满足开设网络商店的资质与要求 - 开通支付平台账户,目前支持: - [支付宝官方接口](https://open.alipay.com/) - [微信支付官方接口](https://pay.weixin.qq.com/) ## 前台路由 Halo 商城版 2.27 的常用前台路由如下: - `/shop`:商城首页,目前会重定向到商品列表页面 - `/shop/products`:商品列表页面 - `/shop/products/{handle}`:商品详情页面,`handle` 为商品永久链接标识 - `/shop/subscription/{handle}`:订阅商品详情页面 - `/shop/cart`:购物车页面 - `/shop/checkout/{contextId}`:结算页面,由购买流程生成当前会话的结算地址 - `/shop/order/{orderCode}/payments`:订单支付页面 - `/shop/order/{orderCode}`:订单详情页面,需具备该订单的访问权限 旧数字 ID 入口为 `/shop/product/{id}`;商品设置了永久链接标识时,会重定向到对应的商品详情地址。分享商品时,优先使用实际商品页面的链接。 :::note 系统内置页面模板 这些页面无需主题提供对应的模板文件即可访问,使用的是系统内置的模板文件。如果当前激活的主题提供了对应的模板文件,则会优先使用主题提供的模板文件。 ::: 可以把商品列表或购物车等入口添加到[网站菜单](https://docs.halo.run/guide/use/menus.md)中;结算、支付和订单详情地址由交易流程生成。需要定制这些页面时,参见[商城主题开发](https://docs.halo.run/developer-guide/shop/theme/overview.md)。 --- url: https://docs.halo.run/guide/shop/console-home.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 控制台首页 控制台的商店首页主要用于查看运营数据、指引、商店数据等信息。 ![](/img/user-guide/shop/preview-console-home-1.png) ![](/img/user-guide/shop/preview-console-home-2.png) ![](/img/user-guide/shop/preview-console-home-3.png) --- url: https://docs.halo.run/guide/shop/settings.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 商店设置 :::note 仅限 Halo 商城版 限 [Halo 商城版](https://docs.halo.run/guide/prepare.md#%E5%8F%91%E8%A1%8C%E7%89%88%E6%9C%AC) 可用。 ::: 登录 Halo 控制台,进入 **商店 -> 设置**。支付方式和销售渠道分别参见[支付方式](https://docs.halo.run/guide/shop/payments.md)与[销售渠道](https://docs.halo.run/guide/shop/sales-channels.md),本页介绍其余设置。 ## 店铺 ### 允许匿名购买 开启后,访客无需登录即可在商城前台结账,订单绑定结账时填写的邮箱。 :::note 订阅产品仍需登录 即使开启匿名购买,订阅产品的购买仍要求客户登录。订阅功能参见[订阅管理](https://docs.halo.run/guide/shop/subscriptions.md)。 ::: ### 订阅菜单 **显示个人中心订阅菜单**:开启后(默认),客户可以在个人中心看到 **订阅** 菜单并管理自己的订阅;关闭后隐藏该菜单并限制订阅列表页访问,不影响已有订阅。 ### 联系方式 联系方式会展示在商城前台需要联系商家的位置。可以添加多项联系方式,并设置: - 名称和图标 - 类型:链接或图片 - 链接类型的显示文字与跳转地址 - 图片类型的图片,以及可选的图片跳转地址 - 帮助说明 例如,可以配置客服邮箱、在线客服链接或客服二维码。修改后应到商城前台确认链接和图片均可正常访问。 ### 询价跳转地址 当产品使用“询价”定价时,前台会显示 **联系销售** 按钮: - 已设置询价跳转地址:点击后跳转到该地址。 - 未设置询价跳转地址:前台展示已配置的联系方式。 ## 小程序 小程序设置包括微信登录、轮播图和快捷入口。完整配置方法参见[小程序](https://docs.halo.run/guide/shop/mp.md)。 ## 订单号 订单号支持以下生成策略: - UUID:使用随机的唯一标识。 - Snowflake:生成有序的唯一编号。 还可以为订单号设置前缀,并在前缀中使用时间占位符: | 占位符 | 含义 | | ------------------------ | --------- | | `{yyyy}` / `{yy}` | 四位 / 两位年份 | | `{MM}` / `{dd}` | 月 / 日 | | `{HH}` / `{mm}` / `{ss}` | 时 / 分 / 秒 | 设置页面会实时预览订单号。保存前请确认格式符合内部对账或客服检索习惯。 --- url: https://docs.halo.run/guide/shop/payments.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 支付方式 在正式运营商城之前,我们需要配置至少一个可用的支付方式,目前商城支持的支付方式包括: - 支付宝 - 微信支付 - 易支付 - Stripe - 银行转账(手动) - 收款码支付(手动) 支付场景用于区分支付终端。当前销售渠道可以使用 PC 网页和小程序,实际可选场景由支付提供商决定;为小程序配置支付时,应选择提供商支持的小程序场景,再把支付方式绑定到[小程序销售渠道](https://docs.halo.run/guide/shop/sales-channels.md)。下文的提供商配置以 PC 网页支付为例。 首先登录到 Halo 控制台,进入 **商店 -> 设置 -> 支付方式** 页面,点击右上角的新建按钮。 **1️⃣ 进入支付方式页面** ![](/img/user-guide/shop/settings-payments.png) **2️⃣ 新建支付方式** ![](/img/user-guide/shop/settings-payments-create-2.23.png) :::note 先创建测试产品 在配置支付方式之前,建议先创建一个测试产品,方便在配置完成后进行测试。 ::: ## 支付宝 ### 创建支付宝应用 支付宝支付使用官方接口,买家交易的资金将直接进入商家的支付宝账户,无第三方平台介入。 在创建支付宝支付方式之前,需要先在支付宝商家平台和支付宝开放平台完成注册。 - [支付宝商家平台](https://b.alipay.com/) - [支付宝开放平台](https://open.alipay.com/) 注册完成后,进入支付宝 [开放平台 -> 控制台](https://open.alipay.com/develop/manage),点击 **创建网页/移动应用** 按钮: ![](/img/user-guide/shop/settings-payments-alipay-create-app.png) 其中 **应用类型** 选择网页应用,其他参数按照实际情况填写即可。 ### 获取支付宝配置信息 创建应用后,进入应用详情页面: ![](/img/user-guide/shop/settings-payments-alipay-app-detail.png) - 1️⃣:应用 ID - 2️⃣:设置接口加签方式 - 加签方式选择 **密钥** - 其他流程按照支付宝的指引进行操作 - 最后下载 **支付宝公钥证书** 到本地,后续配置时需要 - 3️⃣:接口内容加密方式,点击 **生成加密方式** 并复制密文 ### 在 Halo 中配置 打开新建支付方式的界面,支付提供商选择 **支付宝支付**,并填写以下信息: - 启用:勾选 - 名称:给用户展示的支付方式名称 - 场景:选择 **PC 网页支付** - 网关地址:`https://openapi.alipay.com` - 支付宝账号 ID:进入支付宝开放平台的账户中心,复制 **账号 ID** - 应用 ID:上一步中获取的应用 ID - 商户私钥:上一步在工具中生成的密钥文件 - 支付宝公钥:上一步中下载的 `alipayCertPublicKey_RSA2.crt` 文件内容 - 加密密钥:上一步中生成的加密密钥 配置完成之后,还需要在 [销售渠道](https://docs.halo.run/guide/shop/sales-channels.md) 中绑定该支付方式。 支付预览: ![](/img/user-guide/shop/preview-payments-alipay.png) ### 沙箱环境 访问 [沙箱应用 - 开放平台](https://open.alipay.com/develop/sandbox/app),按照页面上的信息在 Halo 中配置即可。 ## 微信支付 ### 申请微信支付商户号 微信支付使用官方接口,买家交易的资金将直接进入商家的微信支付商户账户,无第三方平台介入。 在配置微信支付之前,需要先在微信支付商户平台申请商户号。 - [微信支付商户平台](https://pay.weixin.qq.com/) - [微信支付开发文档](https://pay.weixin.qq.com/doc/v3/merchant/4012791874) 注册并完成商户认证后,进入 [微信支付商户平台](https://pay.weixin.qq.com/),开通 **Native 支付**。 ### 获取微信支付配置信息 登录微信支付商户平台后,需要获取以下配置信息: #### 获取商户号 进入商户平台的 **账户中心 -> 商户信息**,查看您的微信支付商户号(Mch ID)。 #### 设置 API 密钥 1. 进入 **账户中心 -> API 安全 -> API v3 密钥** 2. 点击 **设置密钥** 按钮,按照提示设置 API v3 密钥(32 位字符串) 3. 请妥善保管该密钥,后续在 Halo 中配置时需要使用 #### 申请 API 证书 1. 进入 **账户中心 -> API 安全 -> 验证商户身份 -> 商户 API 证书** 2. 点击 **申请 API 证书** 或 **管理证书** 3. 按照页面指引完成操作后,下载证书文件(包含 `apiclient_cert.pem` 和 `apiclient_key.pem`) 4. 在证书管理页面可以查看到证书序列号,记录下来以便配置 #### 获取微信 AppID 1. 进入 **产品中心 -> AppID 账号管理** 2. 关联您的微信公众号、小程序或企业微信 3. 记录下对应的 AppID ### 在 Halo 中配置 打开新建支付方式的界面,支付提供商选择 **微信支付**,并填写以下信息: - 启用:勾选 - 名称:给用户展示的支付方式名称 - 场景:选择 **PC 网页支付** - 应用 ID:上一步获取的微信 AppID - 商户号:上一步获取的商户号(Mch ID) - 商户私钥:上一步下载的 `apiclient_key.pem` 文件内容 - 商户证书序列号:上一步获取的证书序列号 - API v3 密钥:上一步设置的 API v3 密钥 配置完成之后,还需要在 [销售渠道](https://docs.halo.run/guide/shop/sales-channels.md) 中绑定该支付方式。 支付预览: ![](/img/user-guide/shop/preview-payments-wechat.png) ## 易支付 ### 注册易支付 访问 [易支付官网](https://z-pay.cn),注册并登录账号。 ### 开通支付渠道 访问 [易支付 -> 我的支付渠道](https://member.z-pay.cn/member/channel.html),新增支付宝或者微信渠道,根据平台的要求填写相关信息。 开通成功之后,需要记录 **渠道 ID**,后续在 Halo 中配置时可能需要使用。 ![](/img/user-guide/shop/settings-payments-zpayz-channels.png) ### 获取 API 信息 访问 [易支付 -> API 安全](https://member.z-pay.cn/member/myapi.html),记录 **网关**、**商户 ID(PID)** 和 **商户密钥(KEY)**,后续在 Halo 中配置时需要使用。 ![](/img/user-guide/shop/settings-payments-zpayz-api.png) ### 在 Halo 中配置 打开新建支付方式的界面,支付提供商选择 **易支付**,并填写以下信息: - 启用:勾选 - 名称:给用户展示的支付方式名称 - 场景:选择 **PC 网页支付** - 自定义图标:由于易支付同时支持微信和支付宝,推荐自定义图标来区分 - 网关地址:上一步中记录的 **网关** - 商户号:上一步中记录的 **商户 ID(PID)** - 商户私钥:上一步中记录的 **商户密钥(KEY)** - 支付方式:选择 **微信** 或 **支付宝**,需要确保已经在易支付开通对应的渠道 - 支付渠道 ID:上一步中记录的 **渠道 ID**,支持填写多个,使用英文逗号, 隔开,如果不填则随机调用 配置完成之后,还需要在 [销售渠道](https://docs.halo.run/guide/shop/sales-channels.md) 中绑定该支付方式。 支付预览: ![](/img/user-guide/shop/preview-payments-zpayz.png) ## Stripe ### 登录或者注册 Stripe 访问 [Stripe 官网](https://stripe.com),登录或者注册账号,并且需要完成必要的信息填写,确保可以正常使用 Stripe 的支付功能。 ### 获取 API 信息 登录到 [Stripe 控制台](https://dashboard.stripe.com),进入设置 -> 开发人员 -> 管理 API 密钥,复制 **密钥** 即可,后续在 Halo 中配置时需要使用。 ### 创建 WebHook ### 打开工作台 ![](/img/user-guide/shop/settings-payments-stripe-1.png) ### 添加接收端 切换到 WebHook 选项卡,并点击 **添加接收端** ![](/img/user-guide/shop/settings-payments-stripe-2.png) ### 选择事件 在事件中选择 `checkout.session.completed` ![](/img/user-guide/shop/settings-payments-stripe-3.png) ### 选择接收端类型 接收端类型选择 **Webhook 端点** ![](/img/user-guide/shop/settings-payments-stripe-4.png) ### 填写端点 URL :::note 端点 URL 格式 端点 URL 的格式为: ```text https://your-domain.com/apis/api.ecommerce.halo.run/v1alpha1/payment-providers/stripe/callback ``` 其中 `your-domain.com` 需要替换为你的域名,并且需要确保该域名可以访问。 ::: ![](/img/user-guide/shop/settings-payments-stripe-5.png) 最后点击 **创建** 按钮即可。 ### 获取签名密钥 创建完成之后可以在页面的 **签名密钥** 部分复制 **签名密钥**,后续在 Halo 中配置时需要使用。 ![](/img/user-guide/shop/settings-payments-stripe-6.png) ### 在 Halo 中配置 打开新建支付方式的界面,支付提供商选择 **Stripe**,并填写以下信息: - 启用:勾选 - 名称:给用户展示的支付方式名称 - 场景:选择 **PC 网页支付** - API Key:上一步中获取的 **密钥** - WebHook Secret:上一步中获取的 **签名密钥** 配置完成之后,还需要在 [销售渠道](https://docs.halo.run/guide/shop/sales-channels.md) 中绑定该支付方式。 支付预览: ![](/img/user-guide/shop/preview-payments-stripe.png) ![](/img/user-guide/shop/preview-payments-stripe-2.png) ## 银行转账 银行转账支付方式不经过 Halo 的支付系统,仅仅是在支付的时候显示商家的银行收款信息,让买家转账到商家的银行账户,后续再通过人工审核的方式确认订单。 打开新建支付方式的界面,支付提供商选择 **银行转账**,并填写以下信息: - 启用:勾选 - 名称:给用户展示的支付方式名称 - 场景:选择 **PC 网页支付** - 收款银行:银行名称 - 银行支行地址:开户行地址 - 收款账户名:收款账户名称 - 收款账号:收款银行账号 - 付款说明:为用户说明转账时需要注意的事项 配置完成之后,还需要在 [销售渠道](https://docs.halo.run/guide/shop/sales-channels.md) 中绑定该支付方式。 支付预览: ![](/img/user-guide/shop/preview-payments-bank-transfer.png) ## 收款码支付 收款码支付方式不经过 Halo 的支付系统,仅仅是在支付的时候显示商家的收款码,让买家扫码支付,后续再通过人工审核的方式确认订单。 打开新建支付方式的界面,支付提供商选择 **收款码支付**,并填写以下信息: - 启用:勾选 - 名称:给用户展示的支付方式名称 - 场景:选择 **PC 网页支付** - 收款码二维码图片链接 - 付款说明:为用户说明扫码时需要注意的事项 配置完成之后,还需要在 [销售渠道](https://docs.halo.run/guide/shop/sales-channels.md) 中绑定该支付方式。 支付预览: ![](/img/user-guide/shop/preview-payments-qrcode.png) --- url: https://docs.halo.run/guide/shop/sales-channels.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 销售渠道 为了区分不同平台(PC 端、小程序等)的支付方式以及后续追踪订单来源,系统提供了销售渠道功能。 :::info 按实际终端创建销售渠道 当前控制台支持 **PC 端商城(MALL_PC)** 和 **小程序(MINI_PROGRAM)**。只使用网页商城时创建 PC 端渠道;启用小程序时,再创建小程序渠道并绑定对应的支付方式。 ::: ## 创建销售渠道 首先登录到 Halo 控制台,进入 **商店 -> 设置 -> 销售渠道** 页面,点击右上角的新建按钮。 **1️⃣ 进入销售渠道页面** ![](/img/user-guide/shop/settings-sales-channels.png) **2️⃣ 新建销售渠道** ![](/img/user-guide/shop/settings-sales-channels-create.png) - 是否启用:勾选 - 名称:可任意填写 - 编码:根据销售终端选择 **PC 端商城(MALL_PC)** 或 **小程序(MINI_PROGRAM)** - 支付方式:选择已创建的支付方式,创建方式可参考:[支付方式](https://docs.halo.run/guide/shop/payments.md) 同一销售渠道可以绑定多个可用支付方式。保存后,请分别从网页商城或小程序发起测试订单,确认前台能显示并完成对应支付。 --- url: https://docs.halo.run/guide/shop/products.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 产品管理 ![](/img/user-guide/shop/preview-console-products.png) ## 查找和管理产品 登录 Halo 控制台,进入 **商店 -> 产品**。产品列表支持关键词搜索,并可按状态、类型和分类筛选或调整排序。打开单个产品的操作菜单,可以编辑或删除产品。 ## 创建产品 首先登录到 Halo 控制台,进入 **商店 -> 产品** 页面,点击右上角的新建按钮。 ![](/img/user-guide/shop/products-create.png) ### 基本信息 - 名称:产品名称 - 简短描述:产品的简短描述 - 描述:产品的详细描述,使用富文本编辑器 - 图片:产品图片,可以直接上传或者从附件库中选择,第一张图片会作为封面图 ### 产品数据 这里主要配置产品的类型、属性、规格、价格等数据。 产品类型目前支持四种: 1. 实体:需要配送的产品类型 2. 虚拟:不需要实体配送,使用线上发货的产品类型 3. 链接:直接跳转到第三方链接的产品类型 4. 订阅:按周期售卖的产品类型,创建后不可修改类型,详见 [订阅管理](https://docs.halo.run/guide/shop/subscriptions.md) :::info 虚拟产品交付方式 虚拟产品支持文件资源下载、卡密发货,可参考 [虚拟交付](https://docs.halo.run/guide/shop/virtual-delivery.md) 进行发货配置。 ::: #### 属性配置 属性的作用是为产品添加一些额外的信息,比如颜色、尺寸、型号等,同时也可以用于生成产品规格。 ![](/img/user-guide/shop/products-spec-form.png) - 名称:属性名称,比如颜色、尺寸 - 属性值:支持多个属性值,比如颜色可以有红色、蓝色、绿色等,尺寸可以有小、中、大等,同时也可以为不同的属性值设置图片,用于展示给用户 - 用于生成产品规格:勾选后,支持在配置产品规格时根据多个属性生成不同的产品规格 #### 规格配置 规格即产品的具体规格,比如颜色为红色、尺寸为小,型号为1234567890,可以根据属性值生成不同的规格,并单独设置价格、库存等信息,最终用户购买时,可以选择属性值来确定购买的产品规格。 :::note 规格也称 SKU 这里的规格也可以称之为 **变体** 或者 **SKU**。 ::: ![](/img/user-guide/shop/products-variants-0.png) 当我们设置好 [属性](#属性配置) 之后,可以点击 **生成规格** 按钮来批量生成所有可能产生的规格。 ![](/img/user-guide/shop/products-variants.png) 然后可以点击具体的规格项,展开规格配置表单: ![](/img/user-guide/shop/products-variants-form.png) - 图片:为规格设置图片,用于在购物车,订单等页面展示,如果不设置,会使用属性值中配置的图片或者产品封面 - 状态:支持 **草稿**、**已发布**、**已归档** 三种状态 - SKU 编号:规格的唯一标识 - 条形码:产品规格的条形码,也可用于表示 GTIN、UPC、EAN 或 ISBN 等 - 定价类型 - 固定价格:填写实际价格和可选的划线价 - 询价:不填写价格,前台显示 **联系销售**;跳转行为由[商店设置](https://docs.halo.run/guide/shop/settings.md#%E8%AF%A2%E4%BB%B7%E8%B7%B3%E8%BD%AC%E5%9C%B0%E5%9D%80)决定 - 管理库存 - 否:不管理库存,用户可以无限购买 - 是:管理库存,用户购买时,库存会减少 - 库存:规格的库存数量,当库存为0时,用户无法购买 - 重量:规格的重量 - 长度:规格的长度 - 宽度:规格的宽度 - 高度:规格的高度 :::note 尺寸信息仅用于实物产品 重量、长度、宽度、高度用于后续发货相关的业务,如果产品类型为虚拟,则不需要配置。 ::: 除了为单个规格设置上述配置之外,也可以点击上方的批量设置按钮,用于为所有规格设置相同的配置。 ![](/img/user-guide/shop/products-variants-batch.png) ### 分类配置 分类配置用于将产品分类,比如手机、电脑、服装、数码等,支持多级分类。 ![](/img/user-guide/shop/products-category-selector.png) ## 管理分类 进入 **商店 -> 分类**,可以新建、编辑和删除分类。分类支持父分类、名称、别名、描述和图片;为分类选择父级即可建立多级结构。 产品编辑页面的分类选择器会使用这里维护的分类。 ## 管理属性模板 进入 **商店 -> 属性模板**,可以把常用的属性名称和值保存为模板,例如“颜色:红色、蓝色”和“尺寸:S、M、L”。创建产品时选择模板,可以直接带入这些属性值,再按当前产品调整。 ## 发布产品 配置完产品信息之后,就可以将产品状态改为 **发布**,并保存产品,最终就可以在商城前台中展示。 ![](/img/user-guide/shop/preview-product.png) --- url: https://docs.halo.run/guide/shop/subscriptions.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 订阅管理 :::note 适用范围 本页适用于 **Halo 商城版 2.27.0 及以上版本**,限 [Halo 商城版](https://docs.halo.run/guide/prepare.md#%E5%8F%91%E8%A1%8C%E7%89%88%E6%9C%AC) 可用。 ::: 订阅产品用于销售按周期提供的服务,例如 SaaS 套餐、会员服务或许可证。与一次性售卖的商品不同,订阅有自己的生命周期:试用、生效、续费、变更、取消与过期。 本页面向商家,介绍控制台配置和日常管理。接入方实现权益开通、订阅同步和交付回执时,请阅读[商城集成文档](https://docs.halo.run/developer-guide/shop/integration/overview.md)。 :::warning 手动续费模式 Halo **不保存客户的支付凭据,也不会自动扣款**。连续购买的订阅到期前会向客户发送提醒,客户需要在个人中心手动完成续费。 ::: ## 创建订阅产品 登录 Halo 控制台,进入 **商店 -> 产品**,点击右上角的新建按钮,将产品类型选择为 **订阅**。 - 订阅产品表示一条产品线,创建后**不可修改产品类型**。 - 订阅产品不配置规格价格,价格与周期在订阅计划中配置。 - 创建保存后,在产品编辑页面进入 **订阅设置**,按 **添加档次 -> 添加计划** 的顺序完成配置;上架前请至少添加一个可售计划。 ## 订阅档次 档次是产品线下的商业等级(例如基础版、专业版),是权益契约的归属单位。同一档次下的月付、年付、买断计划共享同一份权益。 每个档次可以配置: - **名称**:档次的显示名称。 - **标识**:接入方识别用的稳定键,同一产品线下不可重复,例如 `professional`。 - **排序**:数字越小越靠前。档次排序同时决定变更方向:目标档次排序值更大为升级,相同为平移;**降级不被支持**。 - **接入契约**:给接入方系统读取的键值数据,支持字符串、数字、布尔三种类型。契约不会展示给客户,键名需与接入方约定。 ## 订阅计划 计划是客户实际购买的套餐,由档次、计费模式和计费周期组成。 | 配置项 | 说明 | | ------- | --------------------------------------------------- | | 档次 | 计划所属的档次。 | | 计费模式 | 连续购买(到期前提醒,客户手动续费)、单期购买(到期自动停用,需要重新购买)、永久买断(一次性付费)。 | | 计费周期 | 控制台可选择按月或按年,周期数固定为 1,暂不支持配置季付等多周期组合。 | | 价格 / 原价 | 计划的实际价格与可选的划线价。 | | 状态 | 草稿、已发布、已归档;只有已发布的计划可以被购买。 | | 启用试用 | 开启后可配置试用天数和试用价格,客户可按试用价开通。 | | 数量上下限 | 单个订阅允许购买的最小与最大数量。 | | 宽限期(天) | 仅连续购买有效:到期未续费后,订阅进入逾期状态的容忍天数,宽限期结束后订阅过期。 | ## 变更规则 变更规则决定客户的现有订阅可以切换到哪些计划: - 只允许**同一计费周期内**的变更,且目标档次不得低于来源计划(升级或平移);跨周期(月付 ↔ 年付)与降级都无法配置。 - 每个允许的变更方向都需要单独配置一条规则并启用,未配置规则的方向一律拒绝变更。 - 费用模式: - **按剩余价值折算**(推荐):新一期全价减去当前计划未使用部分的价值。 - **固定费用(按数量)**:按设置的单价 × 订阅数量收取一期费用。 - **免费**:变更不收费。 - 变更支付完成后立即生效,并从生效时刻起开一期完整新周期;变更不修改订阅数量。 ## 订阅策略 - **每客户仅允许一个订阅**:开启后(默认),客户同时只能持有一个生效订阅,重复购买会被拦下并引导去变更或续费;关闭后每次购买都会新建独立订阅,适用于许可证类产品。 ## 管理订阅 进入 **商店 -> 订阅**(需要超级管理员权限),可以查看所有客户订阅: - 列表支持关键词搜索,并可按状态(试用中、生效中、逾期、已取消、已过期)和产品线筛选。 - 订阅详情展示摘要、当前计划、有效权益、订阅周期与变更记录(新购、续费、变更、转正、取消、过期)。 - 可以对未终止的订阅执行 **立即取消**:订阅立即变为已取消,不会退款。 ## 客户自助管理 客户登录后,可以在个人中心的 **订阅** 菜单中管理自己的订阅: - 查看订阅状态、周期与变更记录。 - **立即续费**:按当前价格创建续费订单,支付后周期顺延;续费订单 24 小时未支付会自动过期。 - **立即转正**:试用中的订阅通过续费入口创建转正订单,支付首期后进入正式计费周期。 - **变更**:在变更页面选择目标计划并查看报价,确认支付后立即生效。 - **取消**:默认可选择到期取消(当前周期结束后取消,周期内仍可使用);仅当订阅已逾期时才允许立即取消,立即取消不会退款。 ## 续费提醒邮件 连续购买的订阅在到期前会向客户发送一次提醒邮件(试用中的订阅则提醒转正),已设置到期取消的订阅不发送。 提醒邮件依赖系统邮件通知配置,请先在 **设置 -> 通知设置** 中配置好[邮件通知](https://docs.halo.run/guide/use/settings.md#%E9%82%AE%E4%BB%B6%E9%80%9A%E7%9F%A5),否则客户无法收到提醒。 :::info 单期购买不发提醒 只有连续购买的计划会发送到期提醒;单期购买的订阅到期后直接过期。 ::: ## 相关设置 在 **商店 -> 设置** 中可以配置 **显示个人中心订阅菜单**:关闭后隐藏个人中心的订阅菜单并限制订阅列表页访问,不影响已有订阅。参见[商店设置](https://docs.halo.run/guide/shop/settings.md#%E8%AE%A2%E9%98%85%E8%8F%9C%E5%8D%95)。 ## 限制 - 不支持自动扣款与自动续费,续费必须由客户手动发起。 - 不支持降级、跨计费周期变更与订阅暂停。 - 订阅产品要求客户登录后购买;即使开启[匿名购买](https://docs.halo.run/guide/shop/settings.md#%E5%85%81%E8%AE%B8%E5%8C%BF%E5%90%8D%E8%B4%AD%E4%B9%B0),订阅产品也不支持游客结账。 - 订阅订单行不会在控制台手动发货,也不会自动发放卡密或数字资源,需要接入方系统对接交付,详见[商城订阅对接](https://docs.halo.run/developer-guide/shop/integration/overview.md)。 ## 相关文档 - [商城订阅对接](https://docs.halo.run/developer-guide/shop/integration/overview.md):面向接入方的 Webhook 与履约上报对接说明。 - [订阅生命周期](https://docs.halo.run/developer-guide/shop/integration/subscription-lifecycle.md):订阅状态机与周期语义。 - [商城客户中心](https://docs.halo.run/guide/shop/customer-center.md):客户在个人中心的其他自助能力。 --- url: https://docs.halo.run/guide/shop/marketing.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 营销 :::note 仅限 Halo 商城版 限 [Halo 商城版](https://docs.halo.run/guide/prepare.md#%E5%8F%91%E8%A1%8C%E7%89%88%E6%9C%AC) 可用。 ::: 登录 Halo 控制台,进入 **商店 -> 营销**。商城提供 **折扣** 和 **优惠券** 两类营销工具。 ## 折扣 折扣可以在订单满足条件时自动生效,也可以要求顾客输入折扣码。 创建折扣时可以配置: - 触发方式:折扣码或自动折扣。 - 优惠方式:固定金额或百分比。 - 适用范围:全部产品或指定产品。 - 排除范围:指定产品、分类或特价产品。 - 使用条件:最低订单金额。 - 使用限制:总使用次数、每位顾客的使用次数。 - 生效时间:开始时间和可选的结束时间。 - 状态:是否启用。 保存后,建议使用测试账号和测试订单验证适用范围、最低金额及叠加结果。 ## 优惠券 优惠券同样支持固定金额和百分比优惠,并可配置适用产品、最低订单金额、总数量、每位顾客限领数量和有效期。 优惠券还可以控制是否允许与以下优惠叠加: - 订单折扣 - 其他优惠券 创建并启用优惠券后,可以从优惠券列表执行发放: - 自动发放:向全部顾客或选定的多个顾客发放。 - 手动发放:向指定的单个顾客发放。 顾客也可以在[商城客户中心](https://docs.halo.run/guide/shop/customer-center.md#%E4%BC%98%E6%83%A0%E5%88%B8)查看可领取的优惠券及自己已有的优惠券。 :::tip 上线前先限定范围 新活动建议先限制产品、顾客和使用次数,完成一次下单验证后再扩大范围。 ::: --- url: https://docs.halo.run/guide/shop/orders.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 订单管理 ![](/img/user-guide/shop/preview-console-orders.png) ## 查找订单 登录 Halo 控制台,进入 **商店 -> 订单**。订单列表支持按关键词、顾客、订单状态、支付状态和发货状态筛选,并可以调整排序。 ## 手动创建订单 点击 **创建订单**,可以为指定顾客手动创建订单。创建时需要: 1. 选择顾客。 2. 添加一个或多个产品规格,设置数量和成交价。 3. 按需填写顾客备注。 4. 根据实际情况决定是否跳过库存管理。 确认金额和库存处理方式后再提交。手动创建的订单随后与顾客正常下单的订单一样,在订单详情中处理付款和发货。 ## 查看订单详情 我们可以点击订单标题进入订单详情页面,或者点击订单标题右侧的图标按钮预览订单详情。 ![](/img/user-guide/shop/preview-console-order-modal.png) ![](/img/user-guide/shop/preview-console-order-detail.png) 订单详情会显示订单项目、顾客与收货信息、付款记录、发货记录及操作时间线。根据订单状态,可以执行以下操作: - 标记已付款:付款处于待处理或授权中时,可以人工确认收款。 - 取消订单:停止继续处理当前打开的订单。 - 删除订单:仅已取消或已归档的订单显示删除操作。删除会隐藏订单,但付款、发货、折扣和优惠券等关联记录仍会保留。 ## 发货 收到用户订单之后,可以在订单详情页面的 **发货信息** 区域点击 **发货** 按钮,打开发货界面: ![](/img/user-guide/shop/preview-console-order-request-fulfillment.png) 在这个界面需要选择本次发货的产品和数量,并按需填写物流公司、物流单号和物流查询地址,然后点击 **确认发货**。一个订单可以分多次发货;发货失败时,可以在发货记录中重试。 :::info 物流与虚拟产品发货 1. 目前仅支持填写物流信息,没有内置物流轨迹查询平台。建议填写物流查询地址,方便顾客自行查询。 2. 虚拟产品发货可参考:[虚拟交付](https://docs.halo.run/guide/shop/virtual-delivery.md) 3. 订阅产品的订单行不能在控制台手动发货:订单支付后需要接入方系统完成交付并上报履约结果,详见[订阅管理](https://docs.halo.run/guide/shop/subscriptions.md#%E9%99%90%E5%88%B6)。 ::: --- url: https://docs.halo.run/guide/shop/virtual-delivery.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 虚拟交付 在 Halo 2.23 中,我们完善了虚拟产品的发货功能,目前支持文件资源下载、卡密发货。 ## 创建产品 完整的创建产品流程可参考 [产品管理](https://docs.halo.run/guide/shop/products.md) 文档,需要注意的是,如果产品要支持虚拟交付,需要在产品类型中选择 **虚拟** 产品类型。 ![](/img/user-guide/shop/products-create-virtual.png) ## 设置文件资源下载 创建完产品之后,我们需要进入 **产品 -> 虚拟交付** 页面,然后选择刚刚创建的产品。 ![](/img/user-guide/shop/virtual-delivery-products.png) 进入设置页面之后,就可以看到 **资源下载** 的设置页面,我们可以点击右上方的 **添加** 按钮来添加文件。 ![](/img/user-guide/shop/virtual-delivery-resource-add.png) - 资源类型:支持附件和静态 URL - 资源名称:为客户显示的文件名称 - 资源描述:可以填写文件的描述信息 - 附件(当类型为附件时):可以点击 `+` 按钮选择已上传的附件或者上传新的附件 - 资源地址(当类型为静态 URL 时):可以填写文件的 URL 地址 填写完成之后,点击 **保存** 按钮即可。 当文件添加完成之后,我们还需要手动启用自动发货,点击右上角的 **发货配置** 按钮,勾选启用即可。 ![](/img/user-guide/shop/virtual-delivery-resource-config.png) ## 设置卡密发货 进入虚拟交付设置页面之后,选择 **卡密资产** 选项卡,就可以看到 **卡密资产** 的设置页面。 ![](/img/user-guide/shop/virtual-delivery-cdks.png) 我们可以点击右上方的 **添加** 按钮来添加卡密。 ![](/img/user-guide/shop/virtual-delivery-cdk-add.png) - 卡密:卡密内容,支持批量添加,一行一个 - 过期时间:卡密过期时间 - 备注:可以填写卡密的备注信息 填写完成之后点击 **添加** 按钮即可。 当卡密添加完成之后,我们还需要手动启用自动发货,点击右上角的 **发货配置** 按钮,勾选启用即可。 ![](/img/user-guide/shop/virtual-delivery-cdk-config.png) 此外,在卡密发货配置界面中,还支持配置 **远程调用配置**,支持通过三方 API 来补货或者动态生成卡密并发货。 定义: - 预获取:优先从卡密列表中选择并发货,在库存不足时才调用 API 进行补货 - 动态获取:每次发货时都调用 API 获取卡密并发货 配置说明: - 类型:支持 **预获取** 和 **动态获取** - 补货配置(当类型为预获取时) - API 地址:补货 API 地址 - 认证 Token:补货 API 认证 Token,用于对 API 请求进行认证 - 阈值:可用卡密数量低于此值时触发补货 - 每次获取的卡密数量:每次调用 API 获取的卡密数量 - 服务器配置(当类型为动态获取时) - API 地址:远程生成 API 地址 - 认证 Token:API 认证 Token,用于对 API 请求进行认证 需要注意的是,API 需要自行实现并适配 Halo 的接口标准,可以参考下方的 [API 规范](#api-规范)。 ## 订单相关 为产品配置好虚拟交付之后,当客户下单并支付时,系统会自动为订单进行发货流程,可以在控制台的订单详情中看到发货状态。 ![](/img/user-guide/shop/virtual-delivery-console-order.png) 客户也可以在订单页面看到已发货的虚拟物品。 ![](/img/user-guide/shop/virtual-delivery-uc-order-1.png) ![](/img/user-guide/shop/virtual-delivery-uc-order-2.png) ## API 规范 ### 卡密远程生成 API 规范 用户下单后,Halo 会向配置的远程地址发起请求,由你的服务实时生成或分配卡密。 #### 请求 ```http POST <你配置的远程生成地址> Content-Type: application/json Authorization: Bearer // 配置了 token 时附带 ``` **请求体** ```json { "orderItem": { "id": 10001, "orderId": 90001, "productId": 80001, "quantity": 2, "itemTitle": "年度会员兑换码", "productVariantSnapshot": { "id": 123, "name": "默认规格" } }, "dryRun": false } ``` | 字段 | 类型 | 必填 | 说明 | | ---------------------------------- | ------- | -- | -------------- | | `orderItem.id` | long | 是 | 订单项 ID(可用作幂等键) | | `orderItem.orderId` | long | 是 | 订单 ID | | `orderItem.productId` | long | 是 | 商品 ID | | `orderItem.quantity` | int | 是 | 需要发放的卡密数量 | | `orderItem.itemTitle` | string | 否 | 订单项标题 | | `orderItem.productVariantSnapshot` | object | 否 | 规格快照 | | `dryRun` | boolean | 是 | 当前固定为 `false` | #### 响应 返回卡密列表,所有卡密的 `capacity` 之和须不小于 `orderItem.quantity`。 ```json [ { "code": "ABCD-EFGH-IJKL", "secret": "S3cr3t-1", "expireAt": "2026-12-31T23:59:59Z", "capacity": 1 } ] ``` | 字段 | 类型 | 必填 | 说明 | | ---------- | ------ | -- | ------------------ | | `code` | string | 是 | 卡密(同一响应内唯一) | | `secret` | string | 否 | 附加验证信息 | | `expireAt` | string | 否 | 过期时间(UTC,ISO-8601) | | `capacity` | int | 否 | 可用次数,默认为 `1` | :::warning 发放响应必须非空且幂等 响应不可为空列表,否则触发卡密发放失败。建议以 `orderItem.id` 作为幂等键,避免重复请求导致重复发放。 ::: #### 错误码 建议使用非 `2xx` 状态码表达失败,并返回结构化错误: ```json { "code": "CDK_OUT_OF_STOCK", "message": "No enough CDKs available", "requestId": "f38db1c2-2f7a-4dc3-b5a8-2d0012345678" } ``` 推荐错误码: | HTTP 状态码 | 错误码 | 含义 | 是否可重试 | | -------- | --------------------- | ----------- | ----- | | `400` | `INVALID_REQUEST` | 请求字段不合法 | 否 | | `401` | `UNAUTHORIZED` | 鉴权失败 | 否 | | `403` | `FORBIDDEN` | 调用被拒绝 | 否 | | `404` | `NOT_FOUND` | 路由不存在 | 否 | | `409` | `IDEMPOTENT_CONFLICT` | 幂等键冲突且参数不一致 | 否 | | `422` | `CDK_OUT_OF_STOCK` | 库存不足 | 视业务而定 | | `429` | `RATE_LIMITED` | 触发限流 | 是 | | `500` | `INTERNAL_ERROR` | 远程服务内部错误 | 是 | | `503` | `SERVICE_UNAVAILABLE` | 服务不可用 | 是 | ### 卡密自动补货 API 规范 当密钥库存低于阈值时,Halo 会自动向配置的补货地址发起补货请求。 #### 请求 ```http POST <你配置的补货地址> Content-Type: application/json Authorization: Bearer // 配置了 token 时附带 ``` **请求体** ```json { "productVariantId": 123, "quantity": 50 } ``` | 字段 | 类型 | 必填 | 说明 | | ------------------ | ---- | -- | ------------ | | `productVariantId` | long | 是 | 需要补货的商品规格 ID | | `quantity` | int | 是 | 请求补充的卡密数量 | #### 响应 返回卡密列表,实际返回数量可与请求数量不一致。 ```json [ { "code": "ABCD-EFGH-IJKL", "secret": "S3cr3t-1", "expireAt": "2026-12-31T23:59:59Z", "capacity": 1 } ] ``` | 字段 | 类型 | 必填 | 说明 | | ---------- | ------ | -- | ------------------ | | `code` | string | 是 | 卡密(同一响应内唯一) | | `secret` | string | 否 | 附加验证信息 | | `expireAt` | string | 否 | 过期时间(UTC,ISO-8601) | | `capacity` | int | 否 | 可用次数,默认为 `1` | :::warning 补货响应不可为空 响应不可为空列表,否则视为补货失败。补货失败不影响当前订单的卡密发放。 ::: #### 错误码 建议使用非 `2xx` 状态码表达失败,并返回结构化错误: ```json { "code": "CDK_OUT_OF_STOCK", "message": "No enough CDKs available", "requestId": "f38db1c2-2f7a-4dc3-b5a8-2d0012345678" } ``` 推荐错误码: | HTTP 状态码 | 错误码 | 含义 | 是否可重试 | | -------- | --------------------- | ----------- | ----- | | `400` | `INVALID_REQUEST` | 请求字段不合法 | 否 | | `401` | `UNAUTHORIZED` | 鉴权失败 | 否 | | `403` | `FORBIDDEN` | 调用被拒绝 | 否 | | `404` | `NOT_FOUND` | 路由不存在 | 否 | | `409` | `IDEMPOTENT_CONFLICT` | 幂等键冲突且参数不一致 | 否 | | `422` | `CDK_OUT_OF_STOCK` | 库存不足 | 视业务而定 | | `429` | `RATE_LIMITED` | 触发限流 | 是 | | `500` | `INTERNAL_ERROR` | 远程服务内部错误 | 是 | | `503` | `SERVICE_UNAVAILABLE` | 服务不可用 | 是 | --- url: https://docs.halo.run/guide/shop/customer-center.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 商城客户中心 :::note 仅限 Halo 商城版 限 [Halo 商城版](https://docs.halo.run/guide/prepare.md#%E5%8F%91%E8%A1%8C%E7%89%88%E6%9C%AC) 可用。 ::: 顾客登录后,可以访问 `/uc`,从个人中心管理自己的收货地址、优惠券、订单和订阅。 ## 收货地址 进入 **收货地址**,可以新建、编辑、删除地址,并将常用地址设为默认地址。地址信息包括: - 姓名和手机号 - 省、市、区 - 街道地址 - 邮政编码 - 是否设为默认地址 下单前应确认地址和手机号准确;实体产品发货后,地址通常不能由顾客直接修改。 ## 优惠券 进入 **优惠券**,可以查看: - 可领取的优惠券,并在满足领取条件时领取。 - 已领取的优惠券及其可用、已使用或已过期状态。 优惠券的适用产品、最低订单金额、有效期和叠加规则由商家设置,参见[营销](https://docs.halo.run/guide/shop/marketing.md#%E4%BC%98%E6%83%A0%E5%88%B8)。 ## 订单 进入 **订单** 可以查看订单状态、商品、金额、付款、发货和收货信息。根据订单当前状态,顾客可以执行: - 支付:待支付订单会进入订单支付页面。 - 取消:订单仍为打开状态,且付款处于待处理或授权中时可取消。 - 确认收货:订单已付款、已发货且仍为打开状态时可确认。 虚拟产品订单还会显示可下载资源或卡密。相关交付方式参见[虚拟交付](https://docs.halo.run/guide/shop/virtual-delivery.md)。 ## 订阅 进入 **订阅** 可以查看自己购买的订阅产品及其状态、周期和变更记录。根据订阅当前状态,顾客可以执行: - 续费:创建续费订单并完成支付后,当前周期顺延。 - 转正:试用中的订阅支付首期后进入正式计费周期。 - 变更:切换到同计费周期的更高或平级套餐,支付差价后立即生效。 - 取消:默认到期取消,当前周期内仍可使用;仅订阅已逾期时可立即取消。 订阅的配置与限制由商家设置,参见[订阅管理](https://docs.halo.run/guide/shop/subscriptions.md)。如果顾客在个人中心看不到订阅菜单,请检查[商店设置](https://docs.halo.run/guide/shop/settings.md#%E8%AE%A2%E9%98%85%E8%8F%9C%E5%8D%95)中的订阅菜单开关。 需要联系商家时,订单页面会使用[商店设置](https://docs.halo.run/guide/shop/settings.md#%E8%81%94%E7%B3%BB%E6%96%B9%E5%BC%8F)中的联系方式。 --- url: https://docs.halo.run/guide/shop/webhooks.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # Webhook :::note 适用范围 本页适用于控制台已经显示 **Webhook** 菜单的 Halo 商城版。可选事件以当前安装版本的创建表单为准。 ::: Webhook 会把订单、支付、发货和订阅事件以 HTTP `POST` 请求发送到外部系统,可用于对接 ERP、物流、营销或订阅服务。 本页介绍控制台配置和投递排查。开发接收服务时,参见[商城集成](https://docs.halo.run/developer-guide/shop/integration/overview.md);订阅事件载荷与处理规则见[订阅 Webhook](https://docs.halo.run/developer-guide/shop/integration/subscription-webhook.md)。 ## 创建 Webhook 登录 Halo 控制台,进入 **Webhook**,点击新建并填写: - 名称:用于在控制台中辨认配置。 - URL:接收事件的 HTTPS 地址。 - 密钥:用于校验请求签名,应使用随机值并妥善保管。 - 事件:需要订阅的事件类型。 - 是否启用:停用后不会发送新的事件。 保存后,可以从列表发送测试事件。测试请求的事件类型是 `WEBHOOK_TEST`,测试订单号为 `TEST-ORDER`,金额为 `0`。 ## 请求格式 请求正文是 JSON,基本结构如下: ```json { "eventType": "ORDER_PAID", "timestamp": "2026-08-31T08:00:00Z", "webhookId": 1, "data": {} } ``` 常用请求头: | 请求头 | 说明 | | --------------------------- | -------------------- | | `X-Halo-Event` | 事件类型 | | `X-Halo-Signature-256` | `sha256=<十六进制 HMAC>` | | `X-Halo-Delivery-Timestamp` | 本次投递时间 | | `X-Halo-Webhook-Id` | 投递 ID;重试和手动重投时保持不变 | | `X-Halo-Delivery-Attempt` | 当前投递次数 | 当前可能出现的业务事件包括: - `ORDER_CREATED` - `ORDER_PAID` - `ORDER_CANCELLED` - `PAYMENT_FAILED` - `PAYMENT_CANCELLED` - `FULFILLMENT_REQUESTED` - `FULFILLMENT_SHIPPED` - `FULFILLMENT_COMPLETED` - `SUBSCRIPTION_*` 订阅事件 零元订单在创建时即视为已支付,会同时触发 `ORDER_CREATED` 和 `ORDER_PAID`。当前没有退款事件。订阅事件的含义、载荷与处理方式见[订阅 Webhook](https://docs.halo.run/developer-guide/shop/integration/subscription-webhook.md)。 ## 验证签名 使用 Webhook 密钥,对未经解析的原始请求正文计算 HMAC-SHA256,并使用常量时间比较校验签名: ```python import hashlib import hmac expected = "sha256=" + hmac.new( secret.encode(), raw_body, hashlib.sha256 ).hexdigest() if not hmac.compare_digest(received_signature, expected): raise ValueError("invalid webhook signature") ``` 不要先解析再重新序列化 JSON,否则字节变化会导致验签失败。 ## 返回状态与重试 - `2xx`:投递成功。 - `4xx`:接收端拒绝请求,不再自动重试。 - `5xx` 或网络错误:按约 1 分钟、5 分钟、30 分钟、2 小时、8 小时的间隔重试,共最多投递 6 次。 Halo 等待接收端响应的超时时间为 10 秒。接收端应先完成验签和持久化,再尽快返回 `2xx`;耗时处理应放到后台任务。 ## 防止重复处理 Webhook 采用至少一次投递,同一事件可能被重复发送。接收端应以 `X-Halo-Webhook-Id` 作为幂等键:已经处理过该 ID 时直接返回成功,不要重复扣库存、发货或记账。 不同订单中的事件通常按发布顺序发送,但失败重试可能造成交错,接收端仍需根据业务状态判断能否执行操作。 ## 查看投递记录 在 **Webhook -> 投递记录** 中可以按状态和事件类型筛选记录,查看请求头、请求正文及响应结果。失败记录修复后,可以手动重新投递。 :::warning 数据与密钥安全 Webhook 数据可能包含订单金额、姓名、地址和手机号。请只使用 HTTPS,不要把密钥放入前端代码或日志,并限制投递记录和接收端日志的访问权限。 ::: --- url: https://docs.halo.run/guide/shop/mp.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 小程序 自 Halo 2.24 起,Halo 商城支持以微信小程序作为销售终端。相较于 Web 端,小程序在国内拥有更高的用户渗透率,更适合承载移动端购物场景。 ![小程序预览](/img/user-guide/shop/mp-preview.png) ## 获取方式 Halo 官方目前以源码形式提供小程序模板,你需要自行编译,并通过微信开发者工具完成发布。 - 源码仓库:[lxware-dev/halo-shop-miniprogram](https://github.com/lxware-dev/halo-shop-miniprogram) - 在线文档:[小程序配置与发布文档](https://github.com/lxware-dev/halo-shop-miniprogram/tree/main/docs) ## 使用流程 :::info Fork 后再修改 为了便于后续同步官方更新,建议先将仓库 Fork 到自己的 GitHub 账户,再克隆到本地进行配置、编译和发布。 ::: ```bash git clone https://github.com/{your-github-username}/halo-shop-miniprogram.git ``` 克隆完成后,请阅读源码仓库中的 `docs` 目录,其中包含完整的小程序配置、编译与发布说明,可按文档完成后续操作。 ## 在 Halo 中配置 进入 **商店 -> 设置 -> 小程序**,完成以下配置: 1. 启用微信小程序登录,填写小程序 App ID,并在 Secret 字段中保存 App Secret。 2. 按需添加首页轮播图。每张轮播图可以设置标题、描述、图片、优先级,以及不跳转、跳转到产品或跳转到分类。 3. 按需添加快捷入口。每个入口可以设置标题、图片、优先级,以及不跳转、跳转到产品或跳转到分类。 4. 保存设置。 App ID 和 App Secret 必须与编译、发布小程序时使用的微信小程序一致。App Secret 属于敏感凭证,不要写入小程序源码或公开仓库。 ## 配置支付渠道 1. 在[支付方式](https://docs.halo.run/guide/shop/payments.md)中创建支持小程序场景的支付方式。 2. 在[销售渠道](https://docs.halo.run/guide/shop/sales-channels.md)中创建编码为 **小程序(MINI_PROGRAM)** 的渠道,并绑定该支付方式。 3. 从已发布的小程序创建测试订单,验证登录、下单和支付流程。 --- url: https://docs.halo.run/guide/shop/theme-dev.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 商城主题开发 默认情况下,我们已经在 Halo 本身内置了一套默认的商城模板,如果当前主题没有提供对应的模板文件,则会使用内置的模板文件。 如果你需要定制商城页面或者开发一套全新的商城主题,请阅读开发者指南中的[商城主题开发](https://docs.halo.run/developer-guide/shop/theme/overview.md)。 - [快速开始](https://docs.halo.run/developer-guide/shop/theme/quick-start.md):准备环境并适配第一个商城页面。 - [复用与覆盖模板](https://docs.halo.run/developer-guide/shop/theme/template-reuse.md):将内置商城页面融入现有主题。 - [源码二次开发](https://docs.halo.run/developer-guide/shop/theme/source-development.md):接管商城前端的布局和交互。 相关示例仓库: - [lxware-dev/shop-templates](https://github.com/lxware-dev/shop-templates):Halo 商城基础模板与主题适配文档 - [lxware-dev/theme-shop-starter](https://github.com/lxware-dev/theme-shop-starter):Halo 商城的基础示例主题 - [lxware-dev/theme-shop-advanced-starter](https://github.com/lxware-dev/theme-shop-advanced-starter):Halo 商城的二次开发示例主题 --- url: https://docs.halo.run/guide/faq.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 常见问题 ### Halo 是什么? **Halo** \[ˈheɪloʊ],是一款好用又强大的[开源建站工具](https://github.com/halo-dev/halo),配合上不同的模板与插件,可以很好地帮助你构建你心中的理想站点。它可以是你公司的官方网站,可以是你的个人博客,也可以是团队共享的知识库,甚至可以是一个论坛、一个商城。 ### 为什么 Halo 启动之后,数据库只有一张表? 从 Halo 2.0 开始,为了方便插件扩展,能够方便的持久化数据,我们设计了一种自定义模型的方案,详情可参考 RFC:[自定义模型设计 ](https://github.com/halo-dev/rfcs/tree/main/extension) ### 忘记密码怎么办? 1. 站点管理员已经配置好邮件通知,并且用户已完成电子邮箱验证时,可以点击登录页面的 `找回密码` 链接,填写邮箱后,系统将向该邮箱发送密码重置链接,用户可通过该链接重置密码; 2. 如果不满足上述条件,或者密码重置邮件不能发送成功,请直接联系具有用户管理权限的管理员进行密码重置操作,管理员可参考文档[修改用户密码](https://docs.halo.run/guide/use/users.md#%E4%BF%AE%E6%94%B9%E7%94%A8%E6%88%B7%E5%AF%86%E7%A0%81)部分修改指定用户的密码; 3. 如果系统没有任何一个能够正常登录控制台且具有用户管理权限的管理员账号,则用户需要通过更新数据库记录的方式重置指定用户的密码。 :::info 参考 SQL 语句 通过以下 SQL 语句,可以将 `admin` 用户的密码重置为 `password`,密码重置后请尽快修改为更加安全的密码。 **PostgreSQL** 数据库 ```sql UPDATE extensions SET data = convert_to( jsonb_set( convert_from(data, 'UTF-8') :: jsonb, '{spec,password}', '"{bcrypt}$2a$10$7tBEL1sNQSr/uWtLZHLmCeA9IGx0I9/Jz//3Uwo/anIm9xdxv.xrO"' ) :: text, 'UTF-8' ) WHERE name LIKE '/registry/users/admin'; ``` **MySQL** 数据库 ```sql UPDATE extensions SET data = JSON_SET( CONVERT(data USING utf8mb4), '$.spec.password', '{bcrypt}$2a$10$7tBEL1sNQSr/uWtLZHLmCeA9IGx0I9/Jz//3Uwo/anIm9xdxv.xrO' ) WHERE name LIKE '/registry/users/admin'; ``` ::: ### 附件上传提示 `413 Request Entity Too Large` 如何解决? 这可能是由于 Nginx 的上传大小限制所导致的。可以在 Nginx 的配置文件下的 server 节点加入 `client_max_body_size 1024m;` 即可解决,如果 1024m 还不够,请自行断定,详细配置参考如下: ```nginx {4} server { listen 80; server_name localhost; client_max_body_size 1024m; } ``` ### 网站加载速度慢,是什么问题导致的? 导致网站加载速度慢的原因有很多,建议打开浏览器的 Developer Tools 查看具体是哪个请求时间过长,然后进行针对性的优化。这里提供一些可能的原因: 1. 服务器带宽过小,很多厂商提供的最低带宽一般是 1M。 2. 服务器地区过远,这个需要自行取舍。 3. 网站上的图片过多或者体积过大,可以尝试压缩图片,或者参考 [优雅的让 Halo 支持 webp 图片输出](https://www.halo.run/archives/halo-and-webp) 的教程配置一个 Webp 图片的服务。 4. 部分主题的静态资源可能是由公共 CDN 提供的,当这个 CDN 不稳定的时候可能会导致加载变慢。 一些提升网站加载速度的建议: 1. 尽量不要选择 1M 带宽的服务器,可以根据自己的预算适当提升带宽。一般 3M 以上即可。 2. 尽量购买网络质量较好的服务器,或者较近区域的服务器。 3. 如果一定需要放大量的图片,建议先无损压缩一下再使用。 4. 如上所说,可以自行搭建一个 Webp 图片转换的服务,参考 [优雅的让 Halo 支持 webp 图片输出](https://www.halo.run/archives/halo-and-webp)。 5. 如果网站的静态资源加载慢是由三方 CDN 导致的,可以自行修改主题。 6. 可以使用全站 CDN 加速的方案。 ### 如何在一台服务器上部署多个站点? 使用 Docker 创建多个容器,因为使用 Docker 可以将内部的工作目录映射到宿主机的任何目录,可以参考以下创建容器的方式: ```bash # 第一个 Halo 容器 docker run \ -it -d \ --name halo-1 \ -p 8090:8090 \ -v ~/.halo2:/root/.halo2 \ registry.fit2cloud.com/halo/halo-pro:2.27 \ # 第二个 Halo 容器 docker run \ -it -d \ --name halo-2 \ -p 8091:8090 \ -v ~/.halo2_2:/root/.halo2 \ registry.fit2cloud.com/halo/halo-pro:2.27 \ ``` 更多 Docker 相关的教程请参考:[使用 Docker 部署 Halo](https://docs.halo.run/guide/install/docker.md) ### 如何查看运行日志? 1. 可以在 Console 端的概览页面下载最近的日志文件。 2. 使用 docker logs 命令进行查看。 ```bash # '-f' 滚动更新日志 # '-n 200' 从倒数第 200 行开始查看 # 更多帮助可以查看 'docker logs --help' docker logs -f halo -n 200 ``` ### 前台样式丢失,如何解决? 前台样式不正常或者丢失有很多种问题的可能,最快捷定位问题的方式就是打开浏览器控制台查看具体请求的错误,以下列出了部分导致出现该问题的常见原因: 1. `外部访问地址` 与实际访问地址不一致。也可能是开启了 https 之后,无法正常加载 http 资源,将 [外部访问地址](https://docs.halo.run/guide/install/config.md#halo-%E7%8B%AC%E6%9C%89%E9%85%8D%E7%BD%AE) 改为 https 协议即可。 2. Nginx 配置了静态资源缓存,但没有设置 `proxy_pass`,参考如下: ```nginx location ~ .*\.(gif|jpg|jpeg|png|bmp|swf|flv|mp4|ico)$ { proxy_pass http://halo; expires 30d; access_log off; } ``` --- url: https://docs.halo.run/guide/contribution/issue.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 问题反馈 :::info 提交问题前请阅读 如果您在使用过程中遇到了什么问题,您可以通过下面的方式反馈,但请尽量按照要求提出反馈。 ::: ## GitHub - [https://github.com/halo-dev/halo/issues](https://github.com/halo-dev/halo/issues):反馈 Halo 核心项目的 Bug 或提出功能建议,请提供复现步骤或清晰的需求描述。 - [https://github.com/halo-dev/halo/discussions](https://github.com/halo-dev/halo/discussions):交流使用、部署等问题。 - [https://github.com/orgs/lxware-dev/discussions](https://github.com/orgs/lxware-dev/discussions):Halo 付费版或者付费应用的问题可以在这里进行反馈。 如果你在使用过程中,遇到了一些 bug 或者需要添加某些新特性,请尽量在 GitHub 进行反馈,这非常有助于我们跟踪解决此问题,您也可以很方便的接收到处理状态。 建议步骤: 1. 在 GitHub 搜索相关问题,看看是否有其他人已经提到了此问题。 2. 如果当前还没有人遇到您类似的问题,可以创建新的 Issue 或者 Discussion。 3. 选择正确的反馈类型。 4. 请尽可能详细的按照模板填写内容。 5. 提交反馈。 ## Halo 官方社区 链接:[https://bbs.halo.run](https://bbs.halo.run) 此平台主要目的用于与其他 Halo 用户进行交流。但如果您对 GitHub 不是很熟悉或者没有账号,您也可以在此平台进行反馈。 --- url: https://docs.halo.run/guide/contribution/pr.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 贡献政策 ## 主仓库贡献政策 [Halo 主仓库](https://github.com/halo-dev/halo)目前仅接受项目维护者提交的 Pull Request,暂不接受外部贡献者的 Pull Request,包括代码、测试和文档修改。 欢迎通过 Issue 反馈 Bug、提出功能建议,或通过 Discussions 参与讨论。创建 Issue 或参与讨论不代表获得提交 Pull Request 的许可。 ## 反馈与讨论 - [GitHub Issues](https://github.com/halo-dev/halo/issues):反馈 Halo 核心项目的 Bug 或提出功能建议,请提供复现步骤或清晰的需求描述。 - [GitHub Discussions](https://github.com/halo-dev/halo/discussions):交流使用、部署等问题。 更多反馈渠道和提交建议,请参阅[问题反馈](https://docs.halo.run/guide/contribution/issue.md)。 ## 维护者开发流程 项目维护者请参阅主仓库的 [Contributing Guide](https://github.com/halo-dev/halo/blob/main/CONTRIBUTING.md),了解开发环境、提交前检查、Pull Request 流程以及 AI 辅助开发等要求。 ## 其他仓库 以上 Pull Request 限制适用于 `halo-dev/halo` 主仓库。文档、插件、主题及其他生态项目的贡献方式,请以各自仓库的贡献指南为准。 --- url: https://docs.halo.run/guide/migrate-from-1.x.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 从 Halo 1.x 迁移 因为 Halo 2.0 的底层架构变动,无法兼容 1.x 的数据,导致无法平滑升级,所以需要进行数据迁移。为此,我们提供了从 Halo 1.5 / 1.6 版本迁移的插件。在进行迁移之前,**有几点注意事项和要求,如果你目前无法满足,建议先暂缓迁移。** - Halo 版本必须为 1.5.x 或 1.6.x。如果不满足,需要先升级到 1.5.x 或 1.6.x 版本。 - Halo 2.0 不兼容 1.x 的主题,建议在升级前先查询你正在使用的主题是否已经支持 2.0。你可以访问 [halo-sigs/awesome-halo](https://github.com/halo-sigs/awesome-halo) 或 [应用市场](https://www.halo.run/store/apps?type=THEME) 查阅目前支持的主题。 - Halo 2.0 目前没有内置 Markdown 编辑器,如果需要重新编辑迁移后的文章,需要额外安装 Markdown 编辑器插件,可以在应用市场找到合适的 Markdown 插件:[https://www.halo.run/store/apps?tag=editor](https://www.halo.run/store/apps?tag=editor) - Halo 2.0 不再内置友情链接、日志、图库等模块,需要安装额外的插件,目前官方已提供: - 链接管理:[https://www.halo.run/store/apps/app-hfbQg](https://www.halo.run/store/apps/app-hfbQg) - 图库:[https://www.halo.run/store/apps/app-BmQJW](https://www.halo.run/store/apps/app-BmQJW) - 瞬间(原日志):[https://www.halo.run/store/apps/app-SnwWD](https://www.halo.run/store/apps/app-SnwWD) - Halo 2.0 不再内置外部云存储的支持。需要安装额外的插件,目前官方已提供: - S3(兼容国内主流的云存储):[https://www.halo.run/store/apps/app-Qxhpp](https://www.halo.run/store/apps/app-Qxhpp) - 在迁移过程中不会保留旧版本的用户数据,迁移完成之后,关于文章等数据的关联都将改为 Halo 2.0 的新用户。 - 为了防止直接升级 2.0 导致 1.x 的数据受到破坏,我们已经将工作目录由 `~/.halo` 变更为 `~/.halo2`。 - 可以考虑先在本地运行一个 Halo 2.0,模拟一下导入,检查导入后是否满足要求。 如果遇到了迁移过程中的问题,也可以向我们提交 Issue: [https://github.com/halo-dev/halo/issues/new/choose](https://github.com/halo-dev/halo/issues/new/choose),以上暂不支持的功能我们也会陆续完善。 ## 备份数据 在进行迁移操作之前,我们强烈建议先**完整备份所有数据**,可以参考 [备份迁移](https://v1.legacy-docs.halo.run/user-guide/backup-migration) 进行整站备份。 ## 导出数据文件 在 Halo 1.5.x / 1.6.x 后台的小工具中提供了数据导出的功能,将最新的数据进行备份,然后下载即可。这个数据文件包含了数据库所有的数据,后续我们在 2.0 的导入插件中就是通过这个文件进行数据导入。 ![Halo 1.6 export data](/img/migrate/halo1.6-export.png) ## 部署 Halo 2.0 可以参考以下文档进行部署: - [使用 Docker 部署](https://docs.halo.run/guide/install/docker.md) - [使用 Docker Compose 部署](https://docs.halo.run/guide/install/docker-compose.md) - [使用 JAR 文件部署](https://docs.halo.run/guide/install/jar-file.md) :::tip 保留旧版本时更换端口 可以考虑暂时保留旧版本的 Halo,等到迁移完成之后再移除。如果需要保留旧版本的 Halo,请注意在部署 Halo 2.0 的时候使用其他端口,然后在反向代理(Nginx)中修改为 Halo 2.0 的运行端口即可。 ::: ## 移动附件 - 本地存储的附件,只需要将 1.x 工作目录的 `upload` 目录里面的所有文件夹移动到 2.0 工作目录下的 `attachments/migrate-from-1.x` 文件夹即可。 - 云存储的附件迁移会在迁移插件中进行。 ## 安装插件 在迁移过程中,需要提前安装必要的插件: - 站点迁移:[https://www.halo.run/store/apps/app-TlUBt](https://www.halo.run/store/apps/app-TlUBt) - 链接管理:[https://www.halo.run/store/apps/app-hfbQg](https://www.halo.run/store/apps/app-hfbQg) - 图库:[https://www.halo.run/store/apps/app-BmQJW](https://www.halo.run/store/apps/app-BmQJW) - 瞬间(原日志):[https://www.halo.run/store/apps/app-SnwWD](https://www.halo.run/store/apps/app-SnwWD) - S3(如果需要迁移存在云存储的附件,需要安装):[https://www.halo.run/store/apps/app-Qxhpp](https://www.halo.run/store/apps/app-Qxhpp) ## 配置存储策略 > 如果在 Halo 1.x 中未使用云存储,可以跳过此步骤。 ### 安装 S3 插件 在 Halo 2.0 中安装 S3 插件,为迁移云存储附件准备对应的存储能力。 ### 进入附件管理页面 登录 Halo 2.0 控制台,打开附件管理页面。 ### 打开存储策略 点击页面右上角的 **存储策略** 按钮。 ### 创建存储策略 选择 **S3 对象存储**。 ### 保存配置 填写相关配置,点击 **保存** 即可。 ## 迁移 ![Migrate Plugin 1](/img/migrate/halo2.0-migrate-plugin-1.png) ![Migrate Plugin 2](/img/migrate/halo2.0-migrate-plugin-2.png) ![Migrate Plugin 3](/img/migrate/halo2.0-migrate-plugin-3.png) ### 进入迁移页面 点击左侧菜单的迁移进入迁移页面。 ### 选择迁移类型 选择 **Halo 1.5 / 1.6 数据迁移**。 ### 选择数据文件 点击 **选择文件** 按钮,选择在 Halo 1.5.x / 1.6.x 导出的数据文件(JSON 格式)。 ### 选择存储策略 如果在 1.x 中使用了云存储,会弹出选择云存储的对话框,选择之前创建的存储策略即可。 ### 执行导入 最后点击页面下方的 **执行导入** 即可。 --- url: https://docs.halo.run/guide/contribution/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 参与贡献 --- url: https://docs.halo.run/developer-guide/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 开发者指南 ## 系统开发 ### [准备工作](/developer-guide/core/prepare.md) - [环境要求](/developer-guide/core/prepare.md#环境要求) - [名词解释](/developer-guide/core/prepare.md#名词解释) ### [开发环境运行](/developer-guide/core/run.md) - [项目结构说明](/developer-guide/core/run.md#项目结构说明) - [克隆项目](/developer-guide/core/run.md#克隆项目) - [运行 UI 服务](/developer-guide/core/run.md#运行-ui-服务) - [运行 Halo](/developer-guide/core/run.md#运行-halo) ### [构建](/developer-guide/core/build.md) - [克隆项目](/developer-guide/core/build.md#克隆项目) - [构建 Fat Jar](/developer-guide/core/build.md#构建-fat-jar) - [构建 Docker 镜像](/developer-guide/core/build.md#构建-docker-镜像) ### [Halo 架构概览](/developer-guide/core/framework.md) - [Halo 核心概念和 Extension](/developer-guide/core/framework.md#halo-核心概念和-extension) ## 插件开发 ### [介绍](/developer-guide/plugin/introduction.md) ### [准备工作](/developer-guide/plugin/prepare.md) ### [AI 辅助](/developer-guide/plugin/ai.md) - [提供文档上下文](/developer-guide/plugin/ai.md#提供文档上下文) - [核对版本与源码](/developer-guide/plugin/ai.md#核对版本与源码) - [生成前检查清单](/developer-guide/plugin/ai.md#生成前检查清单) - [Agent Skill](/developer-guide/plugin/ai.md#agent-skill) ### [入门](/developer-guide/plugin/hello-world.md) - [创建插件项目](/developer-guide/plugin/hello-world.md#创建插件项目) - [按需扩展项目](/developer-guide/plugin/hello-world.md#按需扩展项目) - [运行插件](/developer-guide/plugin/hello-world.md#运行插件) - [下一步](/developer-guide/plugin/hello-world.md#下一步) ### [案例和最佳实践](/developer-guide/plugin/examples/index.md) ### [基础](/developer-guide/plugin/basics/index.md) ### [API 参考](/developer-guide/plugin/api-reference/index.md) ### [扩展点和定制化](/developer-guide/plugin/extension-points/index.md) ### [与其他插件交互](/developer-guide/plugin/interaction/index.md) ### [与主题集成](/developer-guide/plugin/theme-integration.md) - [选择集成方式](/developer-guide/plugin/theme-integration.md#选择集成方式) - [提供稳定的模板契约](/developer-guide/plugin/theme-integration.md#提供稳定的模板契约) - [提供浏览器 API 和资源](/developer-guide/plugin/theme-integration.md#提供浏览器-api-和资源) - [扩展最终页面输出](/developer-guide/plugin/theme-integration.md#扩展最终页面输出) - [验证集成状态](/developer-guide/plugin/theme-integration.md#验证集成状态) ### [安全和权限管理](/developer-guide/plugin/security/index.md) ### [测试插件](/developer-guide/plugin/testing.md) - [选择验证层级](/developer-guide/plugin/testing.md#选择验证层级) - [运行自动化检查](/developer-guide/plugin/testing.md#运行自动化检查) - [在本地 Halo 中联调](/developer-guide/plugin/testing.md#在本地-halo-中联调) - [验证兼容性和生命周期](/developer-guide/plugin/testing.md#验证兼容性和生命周期) - [记录可复核结果](/developer-guide/plugin/testing.md#记录可复核结果) ### [常见问题](/developer-guide/plugin/faq.md) - [插件启动失败](/developer-guide/plugin/faq.md#startup-failure) - [类加载与依赖冲突](/developer-guide/plugin/faq.md#dependency-conflict) - [UI 扩展不加载](/developer-guide/plugin/faq.md#ui-not-loading) - [权限配置不生效](/developer-guide/plugin/faq.md#permission-not-effective) - [开发期热重载不生效](/developer-guide/plugin/faq.md#hot-reload) ### [插件发布验收清单](/developer-guide/plugin/release-checklist.md) - [构建发布制品](/developer-guide/plugin/release-checklist.md#构建发布制品) - [检查 JAR 内容](/developer-guide/plugin/release-checklist.md#检查-jar-内容) - [验证安装和升级](/developer-guide/plugin/release-checklist.md#验证安装和升级) - [核对 CI/CD](/developer-guide/plugin/release-checklist.md#核对-cicd) - [记录发布证据](/developer-guide/plugin/release-checklist.md#记录发布证据) ### [API 变更日志](/developer-guide/plugin/api-changelog.md) - [2.27.0](/developer-guide/plugin/api-changelog.md#2270) - [2.26.0](/developer-guide/plugin/api-changelog.md#2260) - [2.25.0](/developer-guide/plugin/api-changelog.md#2250) - [2.23.0](/developer-guide/plugin/api-changelog.md#2230) - [2.22.8](/developer-guide/plugin/api-changelog.md#2228) - [2.22.5](/developer-guide/plugin/api-changelog.md#2225) - [2.22.1](/developer-guide/plugin/api-changelog.md#2221) - [2.22.0](/developer-guide/plugin/api-changelog.md#2220) ## 主题开发 ### [准备工作](/developer-guide/theme/prepare.md) - [搭建开发环境](/developer-guide/theme/prepare.md#搭建开发环境) - [新建一个主题](/developer-guide/theme/prepare.md#新建一个主题) - [通过模板创建](/developer-guide/theme/prepare.md#通过模板创建) - [创建第一个页面模板](/developer-guide/theme/prepare.md#创建第一个页面模板) - [安装主题](/developer-guide/theme/prepare.md#安装主题) ### [AI 辅助](/developer-guide/theme/ai.md) - [提供文档上下文](/developer-guide/theme/ai.md#提供文档上下文) - [核对版本与源码](/developer-guide/theme/ai.md#核对版本与源码) - [生成前检查清单](/developer-guide/theme/ai.md#生成前检查清单) - [Agent Skill](/developer-guide/theme/ai.md#agent-skill) ### [目录结构](/developer-guide/theme/structure.md) ### [配置文件](/developer-guide/theme/config.md) - [格式示例](/developer-guide/theme/config.md#格式示例) - [字段详解](/developer-guide/theme/config.md#字段详解) - [更新配置](/developer-guide/theme/config.md#更新配置) - [从 1.x 迁移](/developer-guide/theme/config.md#从-1x-迁移) ### [Thymeleaf 模板语法](/developer-guide/theme/thymeleaf.md) - [确认运行环境](/developer-guide/theme/thymeleaf.md#确认运行环境) - [认识常用表达式](/developer-guide/theme/thymeleaf.md#认识常用表达式) - [输出文本和 HTML](/developer-guide/theme/thymeleaf.md#输出文本和-html) - [组合文本和处理空值](/developer-guide/theme/thymeleaf.md#组合文本和处理空值) - [遍历和条件渲染](/developer-guide/theme/thymeleaf.md#遍历和条件渲染) - [定义局部变量](/developer-guide/theme/thymeleaf.md#定义局部变量) - [复用模板片段](/developer-guide/theme/thymeleaf.md#复用模板片段) - [使用表达式工具](/developer-guide/theme/thymeleaf.md#使用表达式工具) - [向 JavaScript 输出数据](/developer-guide/theme/thymeleaf.md#向-javascript-输出数据) - [常见错误](/developer-guide/theme/thymeleaf.md#常见错误) - [排查模板错误](/developer-guide/theme/thymeleaf.md#排查模板错误) ### [静态资源](/developer-guide/theme/static-resources.md) - [模板标签引用](/developer-guide/theme/static-resources.md#模板标签引用) - [API 引用](/developer-guide/theme/static-resources.md#api-引用) - [#theme.route(path)](/developer-guide/theme/static-resources.md#themeroutepath) ### [设置选项](/developer-guide/theme/settings.md) - [区分系统设置与主题设置](/developer-guide/theme/settings.md#区分系统设置与主题设置) - [定义表单](/developer-guide/theme/settings.md#定义表单) - [更新配置](/developer-guide/theme/settings.md#更新配置) - [从 1.x 迁移](/developer-guide/theme/settings.md#从-1x-迁移) ### [主题附带资源](/developer-guide/theme/extension-resources.md) - [提供资源](/developer-guide/theme/extension-resources.md#提供资源) - [允许的资源](/developer-guide/theme/extension-resources.md#允许的资源) - [加载和更新](/developer-guide/theme/extension-resources.md#加载和更新) - [卸载边界](/developer-guide/theme/extension-resources.md#卸载边界) - [源码参考](/developer-guide/theme/extension-resources.md#源码参考) ### [国际化](/developer-guide/theme/i18n.md) - [定义消息](/developer-guide/theme/i18n.md#定义消息) - [在模板中使用](/developer-guide/theme/i18n.md#在模板中使用) - [页面级消息](/developer-guide/theme/i18n.md#页面级消息) - [在 JavaScript 中使用](/developer-guide/theme/i18n.md#在-javascript-中使用) - [切换和测试语言](/developer-guide/theme/i18n.md#切换和测试语言) ### [模板路由](/developer-guide/theme/template-route-mapping.md) - [主要模板](/developer-guide/theme/template-route-mapping.md#主要模板) - [自定义模板](/developer-guide/theme/template-route-mapping.md#custom-templates) ### [全局变量](/developer-guide/theme/global-variables.md) - [site](/developer-guide/theme/global-variables.md#site) - [#halo.matchVersion(constraint)](/developer-guide/theme/global-variables.md#halomatchversionconstraint) - [theme](/developer-guide/theme/global-variables.md#theme) - [按登录状态条件渲染](/developer-guide/theme/global-variables.md#按登录状态条件渲染) - [访问量统计脚本](/developer-guide/theme/global-variables.md#访问量统计脚本) ### [页面模板与变量](/developer-guide/theme/template-variables/index.md) ### [Finder API](/developer-guide/theme/finder-apis/index.md) ### [自定义标签](/developer-guide/theme/template-tag.md) - [halo:comment](/developer-guide/theme/template-tag.md#halocomment) - [halo:footer](/developer-guide/theme/template-tag.md#halofooter) ### [模型元数据](/developer-guide/theme/annotations.md) - [#annotations.get(extension,key)](/developer-guide/theme/annotations.md#annotationsgetextensionkey) - [#annotations.getOrDefault(extension,key,defaultValue)](/developer-guide/theme/annotations.md#annotationsgetordefaultextensionkeydefaultvalue) - [#annotations.contains(extension,key)](/developer-guide/theme/annotations.md#annotationscontainsextensionkey) ### [使用 Vite 开发主题](/developer-guide/theme/vite.md) - [区分源码和构建产物](/developer-guide/theme/vite.md#区分源码和构建产物) - [配置插件](/developer-guide/theme/vite.md#配置插件) - [复用模板片段](/developer-guide/theme/vite.md#复用模板片段) - [开发和构建](/developer-guide/theme/vite.md#开发和构建) ### [与插件集成](/developer-guide/theme/plugin-integration.md) - [检查插件是否可用](/developer-guide/theme/plugin-integration.md#检查插件是否可用) - [保留主题扩展点](/developer-guide/theme/plugin-integration.md#保留主题扩展点) - [兼容插件前台页面](/developer-guide/theme/plugin-integration.md#兼容插件前台页面) - [适配插件组件配色](/developer-guide/theme/plugin-integration.md#适配插件组件配色) - [覆盖插件前台模板](/developer-guide/theme/plugin-integration.md#覆盖插件前台模板) - [验证兼容性](/developer-guide/theme/plugin-integration.md#验证兼容性) ### [页面布局契约](/developer-guide/theme/page-layout.md) - [适配主题布局](/developer-guide/theme/page-layout.md#适配主题布局) - [在主题页面中复用布局](/developer-guide/theme/page-layout.md#在主题页面中复用布局) - [插件页面调用布局](/developer-guide/theme/page-layout.md#插件页面调用布局) - [兼容状态](/developer-guide/theme/page-layout.md#兼容状态) - [版本演进](/developer-guide/theme/page-layout.md#版本演进) ### [UI 扩展](/developer-guide/theme/ui-plugin.md) - [目录结构](/developer-guide/theme/ui-plugin.md#目录结构) - [入口文件](/developer-guide/theme/ui-plugin.md#入口文件) - [使用 Vite 构建](/developer-guide/theme/ui-plugin.md#使用-vite-构建) - [使用 Rsbuild 构建](/developer-guide/theme/ui-plugin.md#使用-rsbuild-构建) - [输出格式和共享依赖](/developer-guide/theme/ui-plugin.md#输出格式和共享依赖) ### [主题调试与测试](/developer-guide/theme/testing.md) - [建立开发反馈循环](/developer-guide/theme/testing.md#建立开发反馈循环) - [定位常见问题](/developer-guide/theme/testing.md#定位常见问题) - [覆盖页面和状态](/developer-guide/theme/testing.md#覆盖页面和状态) - [记录可复核结果](/developer-guide/theme/testing.md#记录可复核结果) ### [图片优化](/developer-guide/theme/image-optimization.md) - [为什么使用响应式图片?](/developer-guide/theme/image-optimization.md#为什么使用响应式图片) - [Finder API](/developer-guide/theme/image-optimization.md#finder-api) - [HTTP API](/developer-guide/theme/image-optimization.md#http-api) ### [性能最佳实践](/developer-guide/theme/performance.md) - [静态资源加载](/developer-guide/theme/performance.md#静态资源加载) - [控制 Finder 调用](/developer-guide/theme/performance.md#控制-finder-调用) - [图片优化](/developer-guide/theme/performance.md#图片优化) - [验证](/developer-guide/theme/performance.md#验证) ### [主题 SEO](/developer-guide/theme/seo.md) - [设置页面标题](/developer-guide/theme/seo.md#设置页面标题) - [使用 Halo 注入的元数据](/developer-guide/theme/seo.md#使用-halo-注入的元数据) - [通过主题设置控制扩展标签](/developer-guide/theme/seo.md#通过主题设置控制扩展标签) - [可选的结构化数据](/developer-guide/theme/seo.md#可选的结构化数据) - [验证最终结果](/developer-guide/theme/seo.md#验证最终结果) ### [构建与打包](/developer-guide/theme/packaging.md) - [配置打包命令](/developer-guide/theme/packaging.md#配置打包命令) - [默认打包内容](/developer-guide/theme/packaging.md#默认打包内容) - [谨慎使用 --all](/developer-guide/theme/packaging.md#谨慎使用---all) - [发布前检查](/developer-guide/theme/packaging.md#发布前检查) ### [主题发布验收清单](/developer-guide/theme/release-checklist.md) - [构建并确认制品](/developer-guide/theme/release-checklist.md#构建并确认制品) - [验证安装和升级](/developer-guide/theme/release-checklist.md#验证安装和升级) - [覆盖页面和内容状态](/developer-guide/theme/release-checklist.md#覆盖页面和内容状态) - [验证集成和浏览器表现](/developer-guide/theme/release-checklist.md#验证集成和浏览器表现) - [配置持续发布(可选)](/developer-guide/theme/release-checklist.md#配置持续发布可选) - [记录发布证据](/developer-guide/theme/release-checklist.md#记录发布证据) ### [API 变更日志](/developer-guide/theme/api-changelog.md) - [2.27.0](/developer-guide/theme/api-changelog.md#2270) - [2.26.0](/developer-guide/theme/api-changelog.md#2260) - [2.25.0](/developer-guide/theme/api-changelog.md#2250) - [2.24.1](/developer-guide/theme/api-changelog.md#2241) - [2.23.0](/developer-guide/theme/api-changelog.md#2230) - [2.22.8](/developer-guide/theme/api-changelog.md#2228) - [2.22.1](/developer-guide/theme/api-changelog.md#2221) - [2.22.0](/developer-guide/theme/api-changelog.md#2220) ## 商城开发 ### [内容导航](/developer-guide/shop/index.md) ### [主题开发](/developer-guide/shop/theme/index.md) ### [集成](/developer-guide/shop/integration/index.md) ## RESTful API ### [介绍](/developer-guide/restful-api/introduction.md) - [API 在线文档](/developer-guide/restful-api/introduction.md#api-在线文档) - [认证方式](/developer-guide/restful-api/introduction.md#认证方式) - [示例项目](/developer-guide/restful-api/introduction.md#示例项目) ### [API Client 请求库](/developer-guide/restful-api/api-client.md) - [安装](/developer-guide/restful-api/api-client.md#安装) - [模块介绍](/developer-guide/restful-api/api-client.md#模块介绍) - [使用](/developer-guide/restful-api/api-client.md#使用) ## 应用市场 ### [发布应用](/developer-guide/app-store/publish-app.md) - [发布流程概览](/developer-guide/app-store/publish-app.md#发布流程概览) - [发布前准备](/developer-guide/app-store/publish-app.md#发布前准备) - [申请成为开发者](/developer-guide/app-store/publish-app.md#申请成为开发者) - [创建应用和首个版本](/developer-guide/app-store/publish-app.md#创建应用和首个版本) - [提交首次审核](/developer-guide/app-store/publish-app.md#提交首次审核) - [审核期间和审核结果](/developer-guide/app-store/publish-app.md#审核期间和审核结果) - [发布后维护](/developer-guide/app-store/publish-app.md#发布后维护) ### [应用市场审核指南](/developer-guide/app-store/app-review-guidelines.md) - [提交前检查](/developer-guide/app-store/app-review-guidelines.md#提交前检查) - [1. 安全](/developer-guide/app-store/app-review-guidelines.md#1-安全) - [2. 性能](/developer-guide/app-store/app-review-guidelines.md#2-性能) - [3. 商业](/developer-guide/app-store/app-review-guidelines.md#3-商业) - [4. 设计](/developer-guide/app-store/app-review-guidelines.md#4-设计) - [5. 法律](/developer-guide/app-store/app-review-guidelines.md#5-法律) - [重新提交与申诉](/developer-guide/app-store/app-review-guidelines.md#重新提交与申诉) - [指南更新](/developer-guide/app-store/app-review-guidelines.md#指南更新) - [联系方式](/developer-guide/app-store/app-review-guidelines.md#联系方式) ## 表单定义与组件速查 ### [表单定义与组件速查](/developer-guide/form-schema.md) - [选择正确的使用场景](/developer-guide/form-schema.md#选择正确的使用场景) - [常用 FormKit 原生输入](/developer-guide/form-schema.md#常用-formkit-原生输入) - [Setting 资源定义方式](/developer-guide/form-schema.md#setting-资源定义方式) - [Halo 扩展组件速查](/developer-guide/form-schema.md#halo-扩展组件速查) - [组件类型](/developer-guide/form-schema.md#组件类型) ## 元数据表单定义 ### [元数据表单定义](/developer-guide/annotations-form.md) - [AnnotationSetting 资源定义方式](/developer-guide/annotations-form.md#annotationsetting-资源定义方式) - [为多个模型定义表单](/developer-guide/annotations-form.md#为多个模型定义表单) --- url: https://docs.halo.run/developer-guide/core/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 系统开发 ## 系统开发 ### [准备工作](/developer-guide/core/prepare.md) - [环境要求](/developer-guide/core/prepare.md#环境要求) - [名词解释](/developer-guide/core/prepare.md#名词解释) ### [开发环境运行](/developer-guide/core/run.md) - [项目结构说明](/developer-guide/core/run.md#项目结构说明) - [克隆项目](/developer-guide/core/run.md#克隆项目) - [运行 UI 服务](/developer-guide/core/run.md#运行-ui-服务) - [运行 Halo](/developer-guide/core/run.md#运行-halo) ### [构建](/developer-guide/core/build.md) - [克隆项目](/developer-guide/core/build.md#克隆项目) - [构建 Fat Jar](/developer-guide/core/build.md#构建-fat-jar) - [构建 Docker 镜像](/developer-guide/core/build.md#构建-docker-镜像) ### [Halo 架构概览](/developer-guide/core/framework.md) - [Halo 核心概念和 Extension](/developer-guide/core/framework.md#halo-核心概念和-extension) --- url: https://docs.halo.run/developer-guide/core/prepare.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 准备工作 ## 环境要求 - [OpenJDK 21 LTS](https://github.com/openjdk/jdk) - [Node.js 20 LTS](https://nodejs.org) - [pnpm 10](https://pnpm.io/) - [IntelliJ IDEA](https://www.jetbrains.com/idea/) - [Git](https://git-scm.com/) - [Docker](https://www.docker.com/)(可选) ## 名词解释 ### 工作目录 指 Halo 所依赖的工作目录,在 Halo 运行的时候会在系统当前用户目录下产生一个 halo-next 的文件夹,绝对路径为 \~/halo-next。里面通常包含下列目录或文件: 1. `db`:存放 H2 Database 的物理文件,如果你使用其他数据库,那么不会存在这个目录。 2. `themes`:里面包含用户所安装的主题。 3. `plugins`:里面包含用户所安装的插件。 4. `attachments`:附件目录。 5. `logs`:运行日志目录。 --- url: https://docs.halo.run/developer-guide/core/run.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 开发环境运行 :::info 运行前准备 在此之前,我们推荐你先阅读[《准备工作》](https://docs.halo.run/developer-guide/core/prepare.md),检查本地环境是否满足要求。 ::: ## 项目结构说明 目前如果需要完整的运行 Halo,总共需要三个部分: 1. Halo 主项目([halo-dev/halo](https://github.com/halo-dev/halo)) 2. UI,包括 Console 控制台和 UC 个人中心(托管在 Halo 主项目) 3. 主题(Halo 主项目内已包含默认主题) :::info UI 需要单独运行 从 Halo 2.11 开始,Halo 项目的 `ui` 目录同时包含了 Console(管理控制台)和 UC(个人中心),以下统称为 UI。 当前 Halo 主项目并不会将 UI 的构建资源托管到 Git 版本控制,所以在开发环境是需要同时运行 UI 项目的。当然,在我们的最终发布版本的时候会在 CI 中自动构建 UI 到 Halo 主项目。 ::: ## 克隆项目 如果你已经 Fork 了相关仓库,请将以下命令中的 `halo-dev` 替换为你的 GitHub 用户名。 ```bash git clone https://github.com/halo-dev/halo # 或者使用 ssh 的方式 clone(推荐) # git clone git@github.com:halo-dev/halo.git # 或者使用 GitHub CLI 克隆(推荐) # gh repo clone halo-dev/halo # 或者使用 GitHub CLI Fork(推荐) # gh repo fork halo-dev/halo ``` ## 运行 UI 服务 ```bash cd path/to/halo/ui pnpm install pnpm build:packages pnpm dev ``` 最终控制台打印了如下信息即代表运行正常: ```text VITE v8.0.0 ready in 805 ms ➜ Local: http://localhost:3000/ ➜ Network: http://192.168.1.7:3000/ ``` :::info 通过 Halo 代理访问 UI 请不要直接使用 UI 的运行端口 3000 访问,会因为跨域问题导致无法正常登录,建议按照后续的步骤以 dev 的配置文件运行 Halo,在 dev 的配置文件中,我们默认代理了 UI 页面的访问地址,所以后续访问 UI 页面使用 `http://localhost:8090/console` 和 `http://localhost:8090/uc` 访问即可,代理的相关配置: ```yaml halo: ui: proxy: endpoint: http://localhost:3000/ enabled: true ``` ::: ## 运行 Halo 使用 IntelliJ IDEA 运行 使用 Gradle 运行 ### 使用 IntelliJ IDEA 打开项目 在 IntelliJ IDEA 中打开 Halo 项目,等待 Gradle 初始化和依赖下载完成。 ### 下载预设插件(可选) **macOS / Linux** ```bash ./gradlew downloadPluginPresets ``` **Windows** ```bash ./gradlew.bat downloadPluginPresets ``` ### 修改 IntelliJ IDEA 的运行配置 **macOS / Linux** 将 Active Profiles 改为 `dev`,如图所示: ![IntelliJ IDEA Profiles](/img/developer-run/IntelliJ-IDEA-Profiles-macOS.png) **Windows** 将 Active Profiles 改为 `dev,win`,如图所示: ![IntelliJ IDEA Profiles](/img/developer-run/IntelliJ-IDEA-Profiles-Win.png) ### 运行 点击 IntelliJ IDEA 的运行按钮,等待项目启动完成。 **macOS / Linux** ```bash ./gradlew bootRun --args="--spring.profiles.active=dev" ``` **Windows** ```bash gradlew.bat bootRun --args="--spring.profiles.active=dev,win" ``` 最终提供以下访问地址: 1. 网站首页:[http://localhost:8090](http://localhost:8090) 2. Console 控制台:[http://localhost:8090/console](http://localhost:8090/console) 3. UC 个人中心:[http://localhost:8090/uc](http://localhost:8090/uc) --- url: https://docs.halo.run/developer-guide/core/build.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 构建 :::info 构建前准备 在此之前,我们推荐你先阅读[《准备工作》](https://docs.halo.run/developer-guide/core/prepare.md),检查本地环境是否满足要求。 ::: 一般情况下,为了保证版本一致性和可维护性,我们并不推荐自行构建和二次开发。 ## 克隆项目 如果你已经 Fork 了相关仓库,请将以下命令中的 `halo-dev` 替换为你的 GitHub 用户名。 ```bash git clone https://github.com/halo-dev/halo # 或者使用 ssh 的方式 clone(推荐) # git clone git@github.com:halo-dev/halo.git # 或者使用 GitHub CLI 克隆(推荐) # gh repo clone halo-dev/halo # 或者使用 GitHub CLI Fork(推荐) # gh repo fork halo-dev/halo cd halo # 切换到特定的分支或标签,请替换 ${branch_name} git checkout ${branch_name} ``` ## 构建 Fat Jar 构建之前需要修改 `gradle.properties` 中的 `version` 属性(推荐遵循 [SemVer 规范](https://semver.org/)),例如:`version=2.25.0` ```bash cd path/to/halo ``` 下载预设插件(可选): ```bash # Windows ./gradlew.bat downloadPluginPresets # macOS / Linux ./gradlew downloadPluginPresets ``` 构建: ```bash # Windows ./gradlew.bat clean build -x check # macOS / Linux ./gradlew clean build -x check ``` 构建完成之后,在 Halo 项目下产生的 `application/build/libs/halo-${version}.jar` 即为构建完成的文件。 最终部署文档可参考:[使用 JAR 文件部署](https://docs.halo.run/guide/install/jar-file.md)。 ## 构建 Docker 镜像 在此之前,请确认已经构建好了 Fat Jar。 ```bash cd path/to/halo ``` ```bash # 请替换 ${tag_name} docker build -t halo-dev/halo:${tag_name} . ``` ```bash # 插件构建完成的版本 docker images | grep halo ``` 最终部署文档可参考:[使用 Docker Compose 部署](https://docs.halo.run/guide/install/docker-compose.md)。 --- url: https://docs.halo.run/developer-guide/core/framework.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # Halo 架构概览 Halo 是一个基于 Spring Boot 的 Java Web 应用,Web 层不再使用 Servlet 技术,而是充分向异步和非阻塞的反应式编程靠拢,使用 Netty 作为 Web 服务器,使用 [Reactor](https://projectreactor.io/) 作为异步编程框架,使用 R2DBC 作为数据库访问框架,使用 WebFlux 作为 Web 层框架。 Halo 由以下几个核心模块组成: - 安全模块:提供用户认证、授权、用户管理等功能。 - 插件模块:提供插件管理、插件加载、插件通信、扩展点等功能。 - 主题模块:提供主题管理、模板渲染、主题配置等功能。 - 内置内容管理模块:提供文章、分类、标签、评论、附件、页面、菜单、设置等功能。 ## Halo 核心概念和 Extension ### 自定义模型 \{#extension} Extension 自定义模型提供了一种声明和管理数据模型的方法,它是 Halo 的核心概念之一。Halo 中的所有数据模型都是通过 Extension 来定义的,包括文章、分类、标签、评论、附件、页面、菜单、设置等,这便于插件系统可以灵活的进行数据模型的扩展,设计文档参考:[自定义模型设计](https://github.com/halo-dev/rfcs/tree/main/extension)。 每个自定义模型都有三大类属性:metadata、spec、和 status。 1. metadata 用于标识自定义模型,每个自定义模型都至少有三个 metadata 属性:name、creationTimestamp、version,除此之外还有 labels 用于标识自定义模型的标签,annotations 用于存放扩展信息,deletionTimestamp 用于标识自定义模型是否被删除,finalizers 用于标识自定义模型的是否可回收。 2. spec 描述用户期望达到的理想状态(Desired State),比如用户可以配置插件的 `spec.enable` 属性为 `true` 来启用插件或者为 `false` 来停用插件,这就是用户期望达到的理想状态,然后插件控制器会根据用户的期望状态来实现插件的启用或停用,它是声明式的,用户只需要声明期望状态,实际状态由具体的控制器来维护,最终达到用户期望的状态。 3. status 描述当前实际状态(Actual State),比如用户可以通过 `status.phase` 属性来查看插件启用进行到了哪一步,中间过程可能包含多个步骤,比如插件解析、加载、资源准备等,这些步骤都是由插件控制器来实现的,它是实际状态,只要插件控制器还在运行,它就会一直更新状态,最终达到用户期望的状态。 每个自定义模型注册后都会默认生成 CRUD APIs,通过这些 APIs 就可以对自定义模型对象进行增删改查的操作,然后只需要编写控制器来实现自定义模型的业务逻辑即可,这就是 Halo 的异步编程模型。 ### 控制器 \{#controller} 在 Halo 中,用户通过自定义模型定义资源的期望状态,Controller 负责监视资源的实际状态,当资源的实际状态和“期望状态”不一致时,Controller 则对系统进行必要的更改,以确保两者一致,这个过程被称之为调谐(Reconcile),而实现调谐的逻辑被称之为 Reconciler。Reconciler 获取对象的名称并返回是否需要重试(例如发生一些错误),如果需要重试,则 Controller 会在稍后再次调用 Reconciler,而这个过程会一直重复,直到 Reconciler 返回成功为止,这个过程被称之为调谐循环(Reconciliation Loop)。 ### 自定义模型生命周期 \{#extension-lifecycle} 所有 Halo 的自定义模型对象都遵循一个共同的生命周期,可以将其视为状态机,尽管某些特定的自定义模型扩展了这一点并提供了更多状态。要编写正确的控制器,了解公共对象生命周期非常重要。 所有自定义模型对象都存在以下状态之一: - `DOES_NOT_EXIST`:Halo 不知道该对象。该状态不区分“尚未创建”和“已删除”。 - `ACTIVE`:Halo 知道该对象并且该对象尚未被删除(未设置 `metadata.deletionTimestamp`)。在此状态下,任何更新操作(PUT、PATCH、服务器端处理等)都将导致相同的状态。 - `DELETING`:Halo 知道该对象,该对象已被删除,但尚未完全删除。这可能是因为对象有一个或多个终结器(在 `metadata.finilizers` 中),客户端仍然可以访问该对象,并且可以看到它正在删除,因为设置了 `metadata.deleteTimestamp` 字段。当最后一个终结器被删除时,该对象将从存储中删除,并真正不存在。 下图描述了上述状态: ```text +---- object | updated v | +----------+ | | +----+ object --------->| ACTIVE | created | +-----------+ | +---+------+ | | | | | | | +------------+---+ | | | | object deleted | | |<--- without finalizers | | | object deleted | DOES_NOT_EXIST | with finalizers | | | | |<--- finalizers removed | | | | | +----------------+ | | | | | | +---+------+ | | | | | DELETING |<----------+ | | +----------+ ``` 总结:自定义模型对象的删除并不是立即生效的,而是需要经过两个步骤,第一步是将对象的 `metadata.deletionTimestamp` 字段设置为当前时间,第二步是将对象的 `metadata.finalizers` 字段设置为空,这样对象才会真正被删除,第一步是由用户发起的,第二步是由 Halo 控制器发起的。 ### Secret \{#secret} Secret 用于解决密码、token、密钥等敏感数据的配置问题,而不需要把这些敏感数据暴露到自定义模型的 Spec 中,或 API 响应中。 ### ConfigMap \{#configmap} ConfigMap 自定义模型用来保存 key-value pair 配置数据,这个数据可以在 Reconciler 里使用,或者被用来为插件或者主题存储配置数据。 虽然 ConfigMap 跟 Secret 类似,但是 ConfigMap 更方便的处理不含敏感信息的字符串。 ### Setting \{#setting} Setting 自定义模型用于提供用户配置声明,用户可以通过 Setting 来声明一些模板需要的配置,比如主题设置、插件设置、系统设置等都可以通过 Setting 来声明,就能在 UI 层面提供配置入口,用户可以通过 UI 来配置这些设置,而不需要修改配置文件。 ### 基于角色的访问控制(RBAC)\{#rbac} Halo 使用基于角色的访问控制(Role-based Access Control,RBAC)来控制用户对资源的访问权限,RBAC 通过将角色分配给用户来实现访问控制,用户可以通过角色来访问资源,角色可以通过权限来访问资源。 RBAC 主要引入了角色(Role)和角色绑定(RoleBinding)的抽象概念,插件可以通过定义角色来提供用户对资源的分配入口,用户可以通过角色绑定来获取角色,从而获取资源的访问权限。 而对于底层角色,用户分配起来比较麻烦,因此 Halo 提供了**角色模板**的概念,通过将角色标记为模板来使用一组功能相关的角色,如文章查看的角色可能必须包含标签和分类的查看才算是一组完整的功能,因此可以将文章查看的角色标记为模板,并依赖标签和分类的查看角色,这样用户就可以通过角色模板来获取一组功能相关的角色,而不需要一个一个的分配角色。 --- url: https://docs.halo.run/developer-guide/plugin/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 插件开发 ## 介绍 ### [介绍](/developer-guide/plugin/introduction.md) ## 准备工作 ### [准备工作](/developer-guide/plugin/prepare.md) ## AI 辅助 ### [AI 辅助](/developer-guide/plugin/ai.md) - [提供文档上下文](/developer-guide/plugin/ai.md#提供文档上下文) - [核对版本与源码](/developer-guide/plugin/ai.md#核对版本与源码) - [生成前检查清单](/developer-guide/plugin/ai.md#生成前检查清单) - [Agent Skill](/developer-guide/plugin/ai.md#agent-skill) ## 入门 ### [入门](/developer-guide/plugin/hello-world.md) - [创建插件项目](/developer-guide/plugin/hello-world.md#创建插件项目) - [按需扩展项目](/developer-guide/plugin/hello-world.md#按需扩展项目) - [运行插件](/developer-guide/plugin/hello-world.md#运行插件) - [下一步](/developer-guide/plugin/hello-world.md#下一步) ## 案例和最佳实践 ### [Todo List](/developer-guide/plugin/examples/todolist.md) - [准备项目](/developer-guide/plugin/examples/todolist.md#准备项目) - [定义 Todo 模型](/developer-guide/plugin/examples/todolist.md#定义-todo-模型) - [注册模型](/developer-guide/plugin/examples/todolist.md#注册模型) - [生成 API Client](/developer-guide/plugin/examples/todolist.md#生成-api-client) - [添加 Console 菜单](/developer-guide/plugin/examples/todolist.md#添加-console-菜单) - [实现 Todo 页面](/developer-guide/plugin/examples/todolist.md#实现-todo-页面) - [运行并验证](/developer-guide/plugin/examples/todolist.md#运行并验证) ## 基础 ### [插件项目结构](/developer-guide/plugin/basics/structure.md) ### [插件注册和配置](/developer-guide/plugin/basics/manifest.md) - [字段详解](/developer-guide/plugin/basics/manifest.md#字段详解) - [插件运行模式](/developer-guide/plugin/basics/manifest.md#插件运行模式) ### [DevTools](/developer-guide/plugin/basics/devtools.md) - [安装](/developer-guide/plugin/basics/devtools.md#安装) - [使用说明](/developer-guide/plugin/basics/devtools.md#使用说明) - [配置](/developer-guide/plugin/basics/devtools.md#配置) - [任务](/developer-guide/plugin/basics/devtools.md#任务) - [调试后端代码](/developer-guide/plugin/basics/devtools.md#调试后端代码) - [迁移](/developer-guide/plugin/basics/devtools.md#迁移) ### [服务端](/developer-guide/plugin/basics/server/index.md) ### [UI](/developer-guide/plugin/basics/ui/index.md) ## API 参考 ### [服务端](/developer-guide/plugin/api-reference/server/index.md) ### [UI](/developer-guide/plugin/api-reference/ui/index.md) ## 扩展点和定制化 ### [服务端](/developer-guide/plugin/extension-points/server/index.md) ### [UI](/developer-guide/plugin/extension-points/ui/index.md) ## 与其他插件交互 ### [依赖其他插件](/developer-guide/plugin/interaction/dependency.md) - [依赖声明方式](/developer-guide/plugin/interaction/dependency.md#依赖声明方式) - [依赖检查和加载](/developer-guide/plugin/interaction/dependency.md#依赖检查和加载) - [提供依赖的插件项目结构](/developer-guide/plugin/interaction/dependency.md#提供依赖的插件项目结构) - [版本管理](/developer-guide/plugin/interaction/dependency.md#版本管理) - [源码参考](/developer-guide/plugin/interaction/dependency.md#源码参考) ### [发布共享 Java API](/developer-guide/plugin/interaction/shared-java-api.md) - [创建 API 模块](/developer-guide/plugin/interaction/shared-java-api.md#创建-api-模块) - [项目结构](/developer-guide/plugin/interaction/shared-java-api.md#项目结构) - [编写 API](/developer-guide/plugin/interaction/shared-java-api.md#编写-api) - [配置实现和使用方](/developer-guide/plugin/interaction/shared-java-api.md#配置实现和使用方) - [发布](/developer-guide/plugin/interaction/shared-java-api.md#发布) ### [事件共享](/developer-guide/plugin/interaction/shared-events.md) - [监听 Halo 提供的共享事件](/developer-guide/plugin/interaction/shared-events.md#监听-halo-提供的共享事件) - [发布自定义共享事件](/developer-guide/plugin/interaction/shared-events.md#发布自定义共享事件) - [最佳实践](/developer-guide/plugin/interaction/shared-events.md#最佳实践) ### [插件如何被扩展](/developer-guide/plugin/interaction/making-plugin-extensible.md) - [定义扩展点](/developer-guide/plugin/interaction/making-plugin-extensible.md#定义扩展点) - [查找扩展](/developer-guide/plugin/interaction/making-plugin-extensible.md#查找扩展) ## 与主题集成 ### [与主题集成](/developer-guide/plugin/theme-integration.md) - [选择集成方式](/developer-guide/plugin/theme-integration.md#选择集成方式) - [提供稳定的模板契约](/developer-guide/plugin/theme-integration.md#提供稳定的模板契约) - [提供浏览器 API 和资源](/developer-guide/plugin/theme-integration.md#提供浏览器-api-和资源) - [扩展最终页面输出](/developer-guide/plugin/theme-integration.md#扩展最终页面输出) - [验证集成状态](/developer-guide/plugin/theme-integration.md#验证集成状态) ## 安全和权限管理 ### [基于角色的权限控制](/developer-guide/plugin/security/rbac.md) - [RBAC 的基本概念](/developer-guide/plugin/security/rbac.md#rbac-的基本概念) - [什么是基于角色的权限控制](/developer-guide/plugin/security/rbac.md#什么是基于角色的权限控制) - [Role 和 RoleBinding](/developer-guide/plugin/security/rbac.md#role-和-rolebinding) - [RoleBinding 与角色的关联](/developer-guide/plugin/security/rbac.md#rolebinding-与角色的关联) - [角色模板](/developer-guide/plugin/security/rbac.md#角色模板) - [继承角色/角色模板](/developer-guide/plugin/security/rbac.md#继承角色角色模板) - [聚合角色](/developer-guide/plugin/security/rbac.md#聚合角色) - [隐藏角色模板](/developer-guide/plugin/security/rbac.md#隐藏角色模板) - [Halo 中的特殊角色](/developer-guide/plugin/security/rbac.md#halo-中的特殊角色) - [Halo 中的内置角色](/developer-guide/plugin/security/rbac.md#halo-中的内置角色) - [参考](/developer-guide/plugin/security/rbac.md#参考) ### [API 权限控制](/developer-guide/plugin/security/role-template.md) - [角色模板定义](/developer-guide/plugin/security/role-template.md#角色模板定义) - [角色绑定](/developer-guide/plugin/security/role-template.md#角色绑定) ### [UI 权限控制](/developer-guide/plugin/security/ui-permission.md) - [什么是 UI 权限控制](/developer-guide/plugin/security/ui-permission.md#什么是-ui-权限控制) - [UI 权限控制的核心概念](/developer-guide/plugin/security/ui-permission.md#ui-权限控制的核心概念) - [Halo 的 UI 权限控制](/developer-guide/plugin/security/ui-permission.md#halo-的-ui-权限控制) ### [敏感数据与出站请求](/developer-guide/plugin/security/outbound-http.md) - [使用 Secret 保存敏感数据](/developer-guide/plugin/security/outbound-http.md#使用-secret-保存敏感数据) - [限制出站目标](/developer-guide/plugin/security/outbound-http.md#限制出站目标) - [对安全开关采用 fail closed](/developer-guide/plugin/security/outbound-http.md#对安全开关采用-fail-closed) - [发布前检查](/developer-guide/plugin/security/outbound-http.md#发布前检查) ## 测试插件 ### [测试插件](/developer-guide/plugin/testing.md) - [选择验证层级](/developer-guide/plugin/testing.md#选择验证层级) - [运行自动化检查](/developer-guide/plugin/testing.md#运行自动化检查) - [在本地 Halo 中联调](/developer-guide/plugin/testing.md#在本地-halo-中联调) - [验证兼容性和生命周期](/developer-guide/plugin/testing.md#验证兼容性和生命周期) - [记录可复核结果](/developer-guide/plugin/testing.md#记录可复核结果) ## 常见问题 ### [常见问题](/developer-guide/plugin/faq.md) - [插件启动失败](/developer-guide/plugin/faq.md#startup-failure) - [类加载与依赖冲突](/developer-guide/plugin/faq.md#dependency-conflict) - [UI 扩展不加载](/developer-guide/plugin/faq.md#ui-not-loading) - [权限配置不生效](/developer-guide/plugin/faq.md#permission-not-effective) - [开发期热重载不生效](/developer-guide/plugin/faq.md#hot-reload) ## 插件发布验收清单 ### [插件发布验收清单](/developer-guide/plugin/release-checklist.md) - [构建发布制品](/developer-guide/plugin/release-checklist.md#构建发布制品) - [检查 JAR 内容](/developer-guide/plugin/release-checklist.md#检查-jar-内容) - [验证安装和升级](/developer-guide/plugin/release-checklist.md#验证安装和升级) - [核对 CI/CD](/developer-guide/plugin/release-checklist.md#核对-cicd) - [记录发布证据](/developer-guide/plugin/release-checklist.md#记录发布证据) ## API 变更日志 ### [API 变更日志](/developer-guide/plugin/api-changelog.md) - [2.27.0](/developer-guide/plugin/api-changelog.md#2270) - [2.26.0](/developer-guide/plugin/api-changelog.md#2260) - [2.25.0](/developer-guide/plugin/api-changelog.md#2250) - [2.23.0](/developer-guide/plugin/api-changelog.md#2230) - [2.22.8](/developer-guide/plugin/api-changelog.md#2228) - [2.22.5](/developer-guide/plugin/api-changelog.md#2225) - [2.22.1](/developer-guide/plugin/api-changelog.md#2221) - [2.22.0](/developer-guide/plugin/api-changelog.md#2220) --- url: https://docs.halo.run/developer-guide/plugin/introduction.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 介绍 Halo 采用可插拔架构,功能模块之间耦合度低、灵活性提高,支持用户按需安装、卸载插件,操作便捷。同时提供插件开发接口以确保较高扩展性和可维护性,这个系列的文档将帮助你了解如何开发 Halo 插件。 --- url: https://docs.halo.run/developer-guide/plugin/prepare.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 准备工作 在 Halo 中,插件是使用 Java 和 JavaScript / TypeScript 编写的,UI 使用 [Vuejs](https://vuejs.org) 编写。 在创建你的第一个插件之前,请确保你具备以下条件: - 你能通过 [Docker 运行 Halo](https://docs.halo.run/guide/install/docker.md) 或在[开发环境运行 Halo](https://docs.halo.run/developer-guide/core/run.md)。 - 你需要安装 Java 21 或更高版本。 - 你熟悉 Java Web 开发并掌握 [Spring Boot](https://spring.io/projects/spring-boot/) 框架。 - 你需要安装 Node.js `>=22.0.0` 来运行插件创建工具;如果插件包含 UI,则至少需要 Node.js `>=22.12.0`。可以从 [Node.js 官网](https://nodejs.org/)下载安装。 - 你熟悉 Vue 和 TypeScript。 - 你应该熟悉使用 pnpm,并以脚手架生成的 `ui/package.json` 中 `packageManager` 声明的版本为准。 - Git 是一个版本控制系统,用于跟踪代码的更改,您需要 Git 来下载示例插件并发布插件。 同时需要先阅读 [Halo 架构概览](https://docs.halo.run/developer-guide/core/framework.md) 以了解 Halo 的核心概念和技术栈。 --- url: https://docs.halo.run/developer-guide/plugin/ai.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # AI 辅助 为了帮助 AI 更全面地了解 Halo 插件的结构、开发流程与最佳实践,从而在插件开发和问题排查过程中提供更准确的帮助,可以向 AI 提供 Halo 开发文档,或安装面向插件开发的 Agent Skill。 ## 提供文档上下文 如果 AI 工具支持读取网页,应根据所需上下文范围选择地址: ```text title='文档索引:先查找与任务相关的页面' https://docs.halo.run/llms.txt ``` ```text title='完整文档:仅在需要全站上下文时使用' https://docs.halo.run/llms-full.txt ``` `llms.txt` 只包含页面标题、描述和链接,不包含每一页的正文。根据索引找到所需页面后,可以把页面地址的后缀改为 `.md`,向 AI 提供该页面的 Markdown 内容,例如: ```text https://docs.halo.run/developer-guide/plugin/basics/manifest.md ``` `/developer-guide/plugin/index.md` 是插件文档的入口页,不是全部插件开发文档的聚合内容。 :::tip 以线上页面为准 如果让 AI 直接阅读文档仓库源码,需要注意仓库中 `_` 前缀的 Markdown 文件(如 `vo/_ThemeVo.md`、`interface/_OperationItem.md`)是被其他页面引用的片段,单独阅读会缺少上下文。应以上述线上 `.md` 页面为准,它们已包含拼接后的完整内容。 ::: ## 核对版本与源码 Halo 插件 API 会随版本演进。使用 AI 生成或修改代码前,应依次确认: 1. 插件 `spec.requires`、Halo BOM 或现有依赖所对应的目标版本。 2. [插件 API 变更](https://docs.halo.run/developer-guide/plugin/api-changelog.md)以及与任务直接相关的文档页面。 3. 文档没有覆盖的签名和行为,以目标版本的 Halo 源码及插件实际依赖类型为准。 向 AI 描述重要契约时,应同时给出引入版本或最低 `spec.requires`、权限、输入与返回值、阻塞或响应式要求、失败语义、生命周期行为及固定提交的源码链接。不要只复制类型名称或方法签名。 ## 生成前检查清单 让 AI 编写插件前,至少要求它遵守以下规则: 1. 新插件从官方 `pnpm create halo-plugin` 脚手架开始,现有插件保留自身包管理器、Gradle 和 UI 构建方式。 2. 自定义模型和使用 `SpringdocRouteBuilder` 描述的接口通过 `generateApiClient` 生成 TypeScript 类型与请求方法;不手写可生成的资源类型、参数和 API 路径,具体参考 [API 请求](https://docs.halo.run/developer-guide/plugin/api-reference/ui/api-request.md)。 3. 普通插件设置使用 Setting YAML;页面和弹窗表单使用 Halo 已注册的 FormKit,列表与交互复用 `@halo-dev/components`,具体参考[插件设置与表单组件](https://docs.halo.run/developer-guide/plugin/basics/ui/forms.md)。 4. 密码、Token、API Key 和私钥使用 Halo `Secret`,不存入 ConfigMap 或自定义模型;用户可配置的出站地址必须防范 SSRF 和凭据泄漏,具体参考[敏感数据与出站请求](https://docs.halo.run/developer-guide/plugin/security/outbound-http.md)。 5. UI 路由、操作权限、RoleTemplate 和后端鉴权保持一致;公开 API 和安全开关在配置缺失或读取失败时采用 fail closed。 6. WebFlux 请求链路使用响应式 API,不调用阻塞客户端;修改 API 契约后运行生成任务,不手动修改生成结果。 :::warning 不要手动修改生成文件 不要让 AI 手动修改 OpenAPI 生成的 `api-client`、`api-docs`、构建目录或锁文件。应修改源文件,再运行项目已有的生成器、构建命令或包管理器更新这些文件。 ::: ## Agent Skill Agent Skill 是可安装到 AI 开发工具中的领域知识包,能够让 AI 在特定场景下更准确地给出建议或执行操作。 [halo-dev/dev-skills](https://github.com/halo-dev/dev-skills) 仓库提供了 `halo-plugin-dev` Skill,包含以下内容: - 插件目录结构与 `plugin.yaml` 配置 - Java 后端、扩展点与自定义 API 开发 - RBAC 权限管理 - Vue 3 前端与 Console、用户中心路由开发 - DevTools 开发流程与 OpenAPI 客户端生成 ### 安装 在 Cursor、Claude Code、Codex 等支持 Agent Skills 的 AI 开发工具中,可以通过 [Skills CLI](https://skills.sh/) 安装: ```bash # 全局安装,可在所有项目中使用 npx skills add halo-dev/dev-skills@halo-plugin-dev -g # 或仅安装到当前项目 npx skills add halo-dev/dev-skills@halo-plugin-dev ``` ### 使用 安装完成后,通常在开发 Halo 插件时,Agent 会根据当前项目和任务自动识别并调用 `halo-plugin-dev` Skill,无需在提示词中显式指定。如果 Agent 未自动调用,可以在提示词中明确要求使用该 Skill。 AI 生成的代码仍需经过代码审查,并按照[插件测试](https://docs.halo.run/developer-guide/plugin/testing.md)和[插件发布验收清单](https://docs.halo.run/developer-guide/plugin/release-checklist.md)完成自动化检查、构建及安装/启停验证后再用于生产环境。 --- url: https://docs.halo.run/developer-guide/plugin/hello-world.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 入门 此文档将帮助你了解如何构建你的第一个插件并在 Halo 中安装和启用。 ## 创建插件项目 我们为插件开发者提供了一个插件创建工具,可以帮助你快速创建一个插件项目。 ```bash pnpm create halo-plugin ``` ```text 🚀 Welcome to Halo Plugin Creator! ✔ Plugin name: › hello-world ✔ Domain (for group and package name): › com.example ✔ Author name: › Halo ✔ Include UI project? › yes ✔ Choose UI build tool: › Vite 📋 Project Configuration: Name: hello-world Domain: com.example Package: com.example.helloworld Author: Halo Include UI: Yes UI Tool: vite Output Directory: /path/to/hello-world ✔ Create project? › yes ``` - **Plugin name**: 插件的名称,用于插件的标识,此字段必须由小写字母、数字和连字符组成 - **Domain**: 插件的包名 - **Author name**: 插件的作者 - **Include UI project**: 是否创建 Console 和 UC 的 UI 子项目;纯服务端插件可以选择不创建 - **Choose UI build tool**: 插件的 UI 构建工具,目前支持 `Vite`(推荐)和 `Rsbuild` 更多关于插件创建工具的信息可查阅:[halo-dev/create-halo-plugin](https://github.com/halo-dev/create-halo-plugin) ## 按需扩展项目 从 `create-halo-plugin` 1.6.0 开始,可以在已有插件项目的根目录中按需添加 UI 项目或 Java 模块,无需重新创建插件或手动复制模板。 ### 添加 UI 项目 ```bash pnpm dlx create-halo-plugin@latest add ui --tool vite # 或 pnpm dlx create-halo-plugin@latest add ui --tool rsbuild ``` 命令会先展示将要创建或更新的文件;重复执行相同命令不会产生变化,已有的 `ui/` 目录或无法识别的 Gradle 配置也不会被覆盖。UI 项目的构建方式可查阅:[UI 构建](https://docs.halo.run/developer-guide/plugin/basics/ui/build.md)。 ### 添加 Java 模块 ```bash pnpm dlx create-halo-plugin@latest add module api ``` 可以将 `api` 替换为实际模块名。命令会创建 Java 源码与测试目录、Maven Central 发布配置、模块 README 和 `.github/workflows/publish.yml`,并自动配置模块依赖。发布工作流从 `main` 分支发布 SNAPSHOT 版本,从 `v*` 标签发布正式版本;运行前需要配置工作流中列出的 Maven Central 和签名密钥。 如果模块用于向其他插件提供 Java API,可继续阅读:[发布共享 Java API](https://docs.halo.run/developer-guide/plugin/interaction/shared-java-api.md)。 ## 运行插件 现在有了一个空项目,我们需要让插件以最小配置运行起来,这里提供两种运行方式。 使用 DevTools 运行(推荐) 传统方式运行 Halo 提供了一个用于插件开发的 DevTools,它可以帮助你快速的运行和调试插件,在模板插件项目中已经集成了 DevTools,可查阅 [DevTools 使用说明](https://docs.halo.run/developer-guide/plugin/basics/devtools.md)。 使用 DevTools 运行插件的前提是需要你的电脑上已经安装了 Docker 环境,这是我们推荐的用户开发时运行插件的方式,只需要执行以下命令即可。 ### 运行插件 ```shell # macOS / Linux ./gradlew haloServer # Windows ./gradlew.bat haloServer ``` 执行此命令后,会自动创建一个 Halo 的 Docker 容器并加载当前的插件。 ### 确认插件启动成功 ```text Halo 初始化成功,访问:http://localhost:8090/console 用户名:admin 密码:admin ``` 然后访问 `http://localhost:8090/console` 在插件列表将能看到插件已经被正确启动,并且在左侧菜单添加了一个 `示例分组`,其下有一个名 `示例页面` 的菜单。 ![hello-world-in-plugin-list](/img/plugin-hello-world.png) 如果你的设备上无法安装 Docker 或你对 Docker 不熟悉,可以使用传统方式运行并开发插件。 但由于此方式需要先使用源码运行 Halo 才能启动插件,请确保已经在开发环境运行了 Halo,可以参考 [Halo 开发环境运行](https://docs.halo.run/developer-guide/core/run.md) ### 编译插件 ```shell # macOS / Linux ./gradlew build # Windows ./gradlew.bat build ``` ### 修改 Halo 配置文件 ```shell # 进入 Halo 项目根目录后,使用 cd 命令进入配置文件目录 cd application/src/main/resources # 创建 application-local.yaml 文件 touch application-local.yaml ``` 根据你的操作系统,将以下内容添加到 `application-local.yaml` 文件中。 ```yaml # macOS / Linux halo: plugin: runtime-mode: development fixed-plugin-path: # 配置为插件项目目录绝对路径 - /path/to/halo-plugin-hello-world # Windows halo: plugin: runtime-mode: development fixed-plugin-path: # 配置为插件项目目录绝对路径 - C:\path\to\halo-plugin-hello-world ``` ### 启动 Halo ```shell # macOS / Linux ./gradlew bootRun --args="--spring.profiles.active=dev,local" # Windows gradlew.bat bootRun --args="--spring.profiles.active=dev,win,local" ``` 然后访问 `http://localhost:8090/console` 在插件列表将能看到插件已经被正确启动,并且在左侧菜单添加了一个 `示例分组`,其下有一个名 `示例页面` 的菜单。 ![hello-world-in-plugin-list](/img/plugin-hello-world.png) ## 下一步 - 了解插件项目的完整组成:[目录结构](https://docs.halo.run/developer-guide/plugin/basics/structure.md) - 跟随完整案例开发一个具有前后端的插件:[Todo List 插件](https://docs.halo.run/developer-guide/plugin/examples/todolist.md) - 查阅可用的扩展能力:[扩展点和定制化](https://docs.halo.run/developer-guide/plugin/extension-points/index.md) --- url: https://docs.halo.run/developer-guide/plugin/examples/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 案例和最佳实践 ## 案例和最佳实践 ### [Todo List](/developer-guide/plugin/examples/todolist.md) - [准备项目](/developer-guide/plugin/examples/todolist.md#准备项目) - [定义 Todo 模型](/developer-guide/plugin/examples/todolist.md#定义-todo-模型) - [注册模型](/developer-guide/plugin/examples/todolist.md#注册模型) - [生成 API Client](/developer-guide/plugin/examples/todolist.md#生成-api-client) - [添加 Console 菜单](/developer-guide/plugin/examples/todolist.md#添加-console-菜单) - [实现 Todo 页面](/developer-guide/plugin/examples/todolist.md#实现-todo-页面) - [运行并验证](/developer-guide/plugin/examples/todolist.md#运行并验证) --- url: https://docs.halo.run/developer-guide/plugin/examples/todolist.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # Todo List 本案例从一个带 UI 的插件模板开始,最终实现一个可持久化的 Todo List。你将完成以下功能: - 创建、完成和删除 Todo。 - 按全部、未完成和已完成筛选 Todo。 - 将数据保存为 Halo 自定义模型,重启后不会丢失。 - 在 Console 中通过自动生成的 API Client 访问数据。 案例基于 Halo 2.26 和当前 `create-halo-plugin` 模板编写。自定义模型和 CRUD API 从 Halo 2.0 起可用;本案例使用的脚手架、Java 21 和 ESM UI 构建要求以 Halo 2.26 为准。 ## 准备项目 先按照[创建插件项目](https://docs.halo.run/developer-guide/plugin/hello-world.md#%E5%88%9B%E5%BB%BA%E6%8F%92%E4%BB%B6%E9%A1%B9%E7%9B%AE)生成一个包含 UI 的插件。本文使用以下名称: | 项目 | 值 | | --------- | ---------------------- | | 项目名 | `plugin-todolist` | | Java 包名 | `com.example.tutorial` | | 插件主类 | `TodoListPlugin` | | API group | `todo.plugin.halo.run` | 如果你的项目使用了其他名称,请同步替换后续示例中的包名和主类名。 本案例只修改以下源码和配置: ```tree plugin-todolist/ ├── build.gradle ├── src/main/java/com/example/tutorial/ │ ├── Todo.java │ └── TodoListPlugin.java ├── src/test/java/com/example/tutorial/TodoListPluginTest.java └── ui/src/ ├── api/index.ts ├── index.ts └── views/HomeView.vue ``` `ui/src/api/generated/` 由 Gradle 任务维护,不要手动创建或修改其中的文件。 ## 定义 Todo 模型 创建 `src/main/java/com/example/tutorial/Todo.java`: ```java title="src/main/java/com/example/tutorial/Todo.java" package com.example.tutorial; import io.swagger.v3.oas.annotations.media.Schema; import lombok.Data; import lombok.EqualsAndHashCode; import run.halo.app.extension.AbstractExtension; import run.halo.app.extension.GVK; @Data @EqualsAndHashCode(callSuper = true) @GVK( group = "todo.plugin.halo.run", version = "v1alpha1", kind = "Todo", plural = "todos", singular = "todo" ) public class Todo extends AbstractExtension { @Schema(requiredMode = Schema.RequiredMode.REQUIRED) private TodoSpec spec; @Data @Schema(name = "TodoSpec") public static class TodoSpec { @Schema(requiredMode = Schema.RequiredMode.REQUIRED, minLength = 1) private String title; @Schema(defaultValue = "false") private Boolean done; } } ``` `@GVK` 决定资源类型和 API 路径。注册后,Todo 的接口前缀为: ```text /apis/todo.plugin.halo.run/v1alpha1/todos ``` `@Schema` 同时用于生成 OpenAPI Schema 和校验写入的数据。本例要求 `spec` 和 `title` 存在,并且标题不能为空字符串。 ## 注册模型 用以下内容替换插件主类: ```java title="src/main/java/com/example/tutorial/TodoListPlugin.java" package com.example.tutorial; import org.springframework.stereotype.Component; import run.halo.app.extension.Scheme; import run.halo.app.extension.SchemeManager; import run.halo.app.plugin.BasePlugin; import run.halo.app.plugin.PluginContext; @Component public class TodoListPlugin extends BasePlugin { private final SchemeManager schemeManager; public TodoListPlugin(PluginContext pluginContext, SchemeManager schemeManager) { super(pluginContext); this.schemeManager = schemeManager; } @Override public void start() { schemeManager.register(Todo.class); } @Override public void stop() { schemeManager.unregister(Scheme.buildFromType(Todo.class)); } } ``` 插件启动时注册模型,停止时注销对应的 Scheme。注销 Scheme 不会删除已经保存的 Todo;再次启用插件并注册模型后仍可读取这些数据。 脚手架自带的测试只适用于没有额外依赖的主类。加入 `SchemeManager` 后,将测试更新为: ```java title="src/test/java/com/example/tutorial/TodoListPluginTest.java" package com.example.tutorial; import static org.mockito.ArgumentMatchers.any; import static org.mockito.Mockito.verify; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.ExtendWith; import org.mockito.InjectMocks; import org.mockito.Mock; import org.mockito.junit.jupiter.MockitoExtension; import run.halo.app.extension.Scheme; import run.halo.app.extension.SchemeManager; import run.halo.app.plugin.PluginContext; @ExtendWith(MockitoExtension.class) class TodoListPluginTest { @Mock PluginContext context; @Mock SchemeManager schemeManager; @InjectMocks TodoListPlugin plugin; @Test void registersAndUnregistersTodoScheme() { plugin.start(); plugin.stop(); verify(schemeManager).register(Todo.class); verify(schemeManager).unregister(any(Scheme.class)); } } ``` 先确认服务端代码可以编译并通过测试: ```shell ./gradlew test ``` ## 生成 API Client Halo 会为已注册的自定义模型提供 CRUD API。UI 不需要手写请求路径和资源类型,而是从 OpenAPI 文档生成 TypeScript Client。 在根项目 `build.gradle` 末尾添加: ```groovy title="build.gradle" haloPlugin { openApi { groupingRules { todoApi { displayName = 'Extension API for Todo List' pathsToMatch = ['/apis/todo.plugin.halo.run/v1alpha1/**'] } } groupedApiMappings = [ '/v3/api-docs/todoApi': 'todoApi.json' ] generator { outputDir = file("${projectDir}/ui/src/api/generated") } } } ``` 保持 UI 仍为脚手架初始代码,然后执行: ```shell ./gradlew generateApiClient ``` 该任务会启动开发用 Halo、加载插件、读取 OpenAPI 文档,再生成 `Todo`、`TodoList` 和 `TodoV1alpha1Api` 等 TypeScript 代码。首次生成应在 UI 引用这些文件之前完成,否则 UI 构建会因为生成目录尚不存在而失败。 :::tip 使用已有的 Halo 服务 如果不希望任务启动临时容器,可以按照 [DevTools 文档](https://docs.halo.run/developer-guide/plugin/basics/devtools.md#how-to-generate-api-client)配置 `openApi.useExistingServer`。无论使用哪种方式,生成目录都必须是专用目录。 ::: 创建 `ui/src/api/index.ts`,让生成的 Client 复用 Halo Console 已配置认证和错误处理的 Axios 实例: ```ts title="ui/src/api/index.ts" import { axiosInstance } from "@halo-dev/api-client"; import { TodoV1alpha1Api } from "./generated"; const todoApiClient = new TodoV1alpha1Api(undefined, "", axiosInstance); export { todoApiClient }; ``` 模型发生变化时,修改 Java 源码后重新运行 `./gradlew generateApiClient`,不要直接修补生成的 TypeScript 文件。 ## 添加 Console 菜单 用以下内容替换 `ui/src/index.ts`: ```ts title="ui/src/index.ts" import { IconPlug } from "@halo-dev/components"; import { definePlugin } from "@halo-dev/ui-shared"; import { markRaw } from "vue"; export default definePlugin({ components: {}, routes: [ { parentName: "Root", route: { path: "/todos", name: "TodoList", component: () => import("./views/HomeView.vue"), meta: { title: "Todo List", searchable: true, menu: { name: "Todo List", group: "工具", icon: markRaw(IconPlug), priority: 0, }, }, }, }, ], extensionPoints: {}, }); ``` 这里保留了脚手架的 `Root` 父路由,只替换页面路径、名称和菜单信息。页面组件继续使用异步导入,避免增加 Console 的初始加载体积。 ## 实现 Todo 页面 用以下内容替换 `ui/src/views/HomeView.vue`: ```vue title="ui/src/views/HomeView.vue" ``` 页面只使用 Vue 的 `ref`、`computed` 和原生表单控件,不需要安装 TodoMVC 或额外样式依赖。筛选在已加载的数据上计算;创建、更新和删除成功后统一重新获取列表,确保页面与服务端状态一致。 本案例用 `page: 0, size: 0` 读取全部 Todo,适合少量示例数据。真实插件的数据量可能持续增长时,应改为分页列表。 ## 运行并验证 启动开发环境: ```shell ./gradlew haloServer ``` 使用任务输出的管理员账号登录 Console,然后按顺序验证: 1. 左侧“工具”分组中出现“Todo List”。 2. 创建一个 Todo 后,刷新页面仍能看到它。 3. 勾选 Todo 后,可在“已完成”和“未完成”之间正确筛选。 4. 删除 Todo 后,刷新页面不会再次出现。 5. 停止并重新执行 `haloServer`,已有 Todo 仍然存在。 开发过程中修改服务端代码后,可以运行 `./gradlew reloadPlugin` 重新加载插件。修改 UI 后按照脚手架提供的 UI 开发任务重新构建;提交前至少执行: ```shell ./gradlew test ./gradlew build ``` 至此,数据流只有一条:`HomeView.vue` 调用生成的 `TodoV1alpha1Api`,Halo 的自定义模型 API 负责校验和持久化 `Todo`。后续如果要增加截止时间、优先级或分页,应先修改 `TodoSpec`,重新生成 API Client,再调整页面。 --- url: https://docs.halo.run/developer-guide/plugin/basics/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 基础 ## 插件项目结构 ### [插件项目结构](/developer-guide/plugin/basics/structure.md) ## 插件注册和配置 ### [插件注册和配置](/developer-guide/plugin/basics/manifest.md) - [字段详解](/developer-guide/plugin/basics/manifest.md#字段详解) - [插件运行模式](/developer-guide/plugin/basics/manifest.md#插件运行模式) ## DevTools ### [DevTools](/developer-guide/plugin/basics/devtools.md) - [安装](/developer-guide/plugin/basics/devtools.md#安装) - [使用说明](/developer-guide/plugin/basics/devtools.md#使用说明) - [配置](/developer-guide/plugin/basics/devtools.md#配置) - [任务](/developer-guide/plugin/basics/devtools.md#任务) - [调试后端代码](/developer-guide/plugin/basics/devtools.md#调试后端代码) - [迁移](/developer-guide/plugin/basics/devtools.md#迁移) ## 服务端 ### [生命周期](/developer-guide/plugin/basics/server/lifecycle.md) - [生命周期与数据边界](/developer-guide/plugin/basics/server/lifecycle.md#生命周期与数据边界) - [插件启动](/developer-guide/plugin/basics/server/lifecycle.md#插件启动) - [插件停止](/developer-guide/plugin/basics/server/lifecycle.md#插件停止) - [插件删除](/developer-guide/plugin/basics/server/lifecycle.md#插件删除) ### [插件中的对象管理](/developer-guide/plugin/basics/server/object-management.md) - [PluginContext](/developer-guide/plugin/basics/server/object-management.md#plugincontext) - [依赖注入 Halo 共享的 Bean](/developer-guide/plugin/basics/server/object-management.md#依赖注入-halo-共享的-bean) ### [响应式服务端开发](/developer-guide/plugin/basics/server/reactive-development.md) - [保持调用链非阻塞](/developer-guide/plugin/basics/server/reactive-development.md#保持调用链非阻塞) - [隔离无法替换的阻塞调用](/developer-guide/plugin/basics/server/reactive-development.md#隔离无法替换的阻塞调用) - [处理外部请求和错误](/developer-guide/plugin/basics/server/reactive-development.md#处理外部请求和错误) - [管理后台任务](/developer-guide/plugin/basics/server/reactive-development.md#管理后台任务) - [测试响应式行为](/developer-guide/plugin/basics/server/reactive-development.md#测试响应式行为) ### [数据存储](/developer-guide/plugin/basics/server/data-storage.md) - [选择存储方式](/developer-guide/plugin/basics/server/data-storage.md#选择存储方式) - [使用本地文件](/developer-guide/plugin/basics/server/data-storage.md#使用本地文件) - [运行和部署边界](/developer-guide/plugin/basics/server/data-storage.md#运行和部署边界) - [备份和升级](/developer-guide/plugin/basics/server/data-storage.md#备份和升级) ### [定时任务](/developer-guide/plugin/basics/server/scheduled-tasks.md) - [启用调度](/developer-guide/plugin/basics/server/scheduled-tasks.md#启用调度) - [生命周期](/developer-guide/plugin/basics/server/scheduled-tasks.md#生命周期) - [注意事项](/developer-guide/plugin/basics/server/scheduled-tasks.md#注意事项) ### [日志](/developer-guide/plugin/basics/server/logging.md) - [使用 SLF4J](/developer-guide/plugin/basics/server/logging.md#使用-slf4j) - [日志级别约定](/developer-guide/plugin/basics/server/logging.md#日志级别约定) - [调整插件日志级别](/developer-guide/plugin/basics/server/logging.md#调整插件日志级别) ## UI ### [介绍](/developer-guide/plugin/basics/ui/intro.md) - [Console 与 UC](/developer-guide/plugin/basics/ui/intro.md#console-与-uc) ### [入口文件](/developer-guide/plugin/basics/ui/entry.md) - [定义入口文件](/developer-guide/plugin/basics/ui/entry.md#定义入口文件) - [PluginModule 字段](/developer-guide/plugin/basics/ui/entry.md#pluginmodule-字段) ### [插件设置与表单组件](/developer-guide/plugin/basics/ui/forms.md) - [先选择正确的表单入口](/developer-guide/plugin/basics/ui/forms.md#先选择正确的表单入口) - [定义插件设置](/developer-guide/plugin/basics/ui/forms.md#定义插件设置) - [在 Vue 页面中使用 FormKit](/developer-guide/plugin/basics/ui/forms.md#在-vue-页面中使用-formkit) - [复用页面和列表组件](/developer-guide/plugin/basics/ui/forms.md#复用页面和列表组件) - [权限和验证](/developer-guide/plugin/basics/ui/forms.md#权限和验证) ### [构建](/developer-guide/plugin/basics/ui/build.md) - [原理](/developer-guide/plugin/basics/ui/build.md#原理) - [@halo-dev/ui-plugin-bundler-kit](/developer-guide/plugin/basics/ui/build.md#bundler-kit) - [输出格式与 Halo 目标](/developer-guide/plugin/basics/ui/build.md#output-format) - [共享运行时依赖](/developer-guide/plugin/basics/ui/build.md#shared-runtime-dependencies) - [加载和生命周期](/developer-guide/plugin/basics/ui/build.md#加载和生命周期) - [迁移旧版构建插件](/developer-guide/plugin/basics/ui/build.md#legacy-bundler-kit) - [构建输出](/developer-guide/plugin/basics/ui/build.md#构建输出) - [迁移](/developer-guide/plugin/basics/ui/build.md#migration) --- url: https://docs.halo.run/developer-guide/plugin/basics/structure.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 插件项目结构 使用 `pnpm create halo-plugin` 创建包含 UI 的插件时,核心目录结构如下所示。示例省略了编辑器、代码检查和 CI 等辅助文件: ```tree ├── ui │ ├── src │ │ ├── assets │ │ │ └── logo.svg │ │ ├── views │ │ │ └── HomeView.vue │ │ └── index.ts │ ├── build.gradle │ ├── env.d.ts │ ├── package.json │ ├── tsconfig.app.json │ ├── tsconfig.json │ ├── tsconfig.node.json │ ├── tsconfig.vitest.json │ ├── vite.config.ts 或 rsbuild.config.ts │ └── vitest.config.ts ├── gradle ├── src │ ├── main │ │ ├── java │ │ │ └── com/example/helloworld/HelloWorldPlugin.java │ │ └── resources │ │ ├── logo.png │ │ └── plugin.yaml │ └── test │ └── java │ └── com/example/helloworld/HelloWorldPluginTest.java ├── LICENSE ├── README.md ├── build.gradle ├── gradle.properties ├── gradlew ├── gradlew.bat └── settings.gradle ``` 此目录结构划分为前端和后端两部分,下面我们将分别进行详细说明。 ### 后端部分 `src` 目录中存放的是后端代码,这部分遵循标准的 Java 项目结构。以下是各个文件和文件夹的说明: - `HelloWorldPlugin.java`:以 `hello-world` 为项目名时生成的插件后端入口。脚手架会根据项目名生成类名和包路径,该类需要继承 `run.halo.app.plugin.BasePlugin`。 - `plugin.yaml`:这是插件的描述文件,位于 `src/main/resources` 目录下。该文件是必须的,包含插件的基本信息,如插件名称、版本、作者、描述以及依赖等内容。 - `resources/ui`:插件 JAR 中的推荐 UI 资源目录。Gradle 会将 `ui/build/dist` 的完整构建产物复制到 `build/resources/main/ui` 后打包,其中可能包含 `ui-plugin.json`、入口、样式、异步分块和其他静态资源。如果插件不包含 UI 部分,此目录可以忽略。 :::warning 优先使用 resources/ui 从 2.11 开始,Halo 支持了 UC 个人中心,且个人中心和 Console 的插件机制共享,因此推荐使用 `resources/ui`。Halo 2.x 仍兼容旧项目使用的 `resources/console`,并优先读取 `ui`。 ::: ### 前端部分 `ui` 目录下存放插件的前端代码和相关资源,前端部分通常采用 Vue 作为开发框架,并推荐使用 TypeScript 作为主要语言,这有助于在编译阶段捕获潜在错误。 以下是前端部分各文件夹和文件的说明: - `src/index.ts`:作为前端部分的插件的入口文件。 - `views`:用于存放 Vue 组件的页面视图文件。 - `styles`:用于存放全局样式和自定义 CSS 文件。 - `components`:推荐创建该目录以放置可复用的公共组件,便于插件项目的模块化和维护。 - `assets`:存放静态资源文件,如图片、图标等。 --- url: https://docs.halo.run/developer-guide/plugin/basics/manifest.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 插件注册和配置 在 Halo 插件开发中,`plugin.yaml` 是用于定义插件基本信息和配置的核心文件。 一个典型的 `plugin.yaml` 文件如下所示: ```yaml apiVersion: plugin.halo.run/v1alpha1 kind: Plugin metadata: name: hello-world spec: requires: ">=2.0.0" author: name: Halo website: https://www.halo.run logo: https://www.halo.run/logo # settingName: hello-world-settings # configMapName: hello-world-configmap homepage: https://github.com/halo-dev/plugin-starter#readme repo: https://github.com/halo-dev/plugin-starter issues: https://github.com/halo-dev/plugin-starter/issues displayName: "插件 Hello world" description: "插件开发的 hello world,用于学习如何开发一个简单的 Halo 插件" license: - name: "GPL-3.0" url: "https://github.com/halo-dev/plugin-starter/blob/main/LICENSE" ``` ## 字段详解 | 字段 | 说明 | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `apiVersion` 和 `kind` | 固定写法,定义插件的 API 版本和类型,不可更改。 | | `metadata.name` | 插件的唯一标识名,长度不超过 253 个字符,仅包含小写字母、数字或 `-`,以字母或数字开头和结尾。 | | `spec.enabled` | Halo 运行时记录的期望启用状态。普通上传安装会将其设为 `false`,不能通过源清单让插件在安装后自动启用,通常无需在源文件中声明。 | | `spec.version` | 插件版本,必须为完整的 SemVer 版本号。使用官方 Gradle 插件构建时,最终产物中的值会自动取自 Gradle 项目版本。 | | `spec.requires` | 插件支持的 Halo 版本范围,遵循 [SemVer Range Expressions](https://github.com/zafarkhaja/jsemver#range-expressions)。参考:[常用 SemVer Range Expressions](#common-range-expressions) | | `spec.pluginDependencies` | 插件依赖及其版本范围,支持必需依赖和可选依赖。参考:[依赖其他插件](https://docs.halo.run/developer-guide/plugin/interaction/dependency.md)。 | | `spec.author` | 插件作者的信息,包括名称和支持网址。 | | `spec.logo` | 插件的 logo,支持 URL 链接或相对于项目 `src/main/resources` 目录的文件路径。 | | `spec.settingName`(可选) | 插件配置表单的名称,用于提供用户可视化配置的表单,名称建议为 "插件名-settings"。参考:[插件设置与表单组件](https://docs.halo.run/developer-guide/plugin/basics/ui/forms.md)、[表单定义与组件速查](https://docs.halo.run/developer-guide/form-schema.md)和[获取插件配置](https://docs.halo.run/developer-guide/plugin/api-reference/server/setting-fetcher.md)。 | | `spec.configMapName`(可选) | 插件配置存储的 ConfigMap 名称,通常建议命名为 "插件名-configmap"。没有配置 `settingName` 则不需要配置此项。 | | `spec.homepage` | 插件的主页链接,通常指向插件的官方文档或帮助页面。 | | `spec.repo` | 插件源码的仓库地址。 | | `spec.issues` | 插件的反馈问题地址,可以是 GitHub Issues。 | | `spec.displayName` | 插件的显示名称,它通常是以少数几个字来概括插件的用途。 | | `spec.description` | 插件的简短描述,用于说明插件的用途。 | | `spec.license` | 插件的许可协议,包含协议名称和链接。参考:[Software License](https://en.wikipedia.org/wiki/Software_license)。 | :::info spec.version 由构建过程写入 Halo 的 Plugin Schema 要求最终安装包中的 `spec.version` 为完整的 SemVer 版本号。使用官方 Halo Gradle 插件时,源文件可以省略此字段;构建过程会读取 Gradle 项目版本,并将其写入构建产物中的 `plugin.yaml`。请不要手动修改构建目录里的副本。 ::: :::tip settingName 需要对应资源 如果在 `plugin.yaml` 中配置了 `settingName`,但没有提供对应的 Setting 资源文件,插件将因为找不到 `metadata.name` 与 `settingName` 一致的 Setting 而无法启动。 ::: 从 `@halo-dev/ui-plugin-bundler-kit@2.26.0` 开始,`spec.requires` 也用于自动选择 UI 构建格式。支持的推导写法和回退行为请参考 [UI 构建 > 输出格式与 Halo 目标](https://docs.halo.run/developer-guide/plugin/basics/ui/build.md#output-format)。 ## 插件运行模式 Halo 插件可以在两种模式下运行:`deployment`(默认)模式和 `development` 开发模式。 - `deployment` **模式**:标准的插件发布流程,插件打包成 JAR 文件后部署到 Halo。这是插件的生产运行模式。 - `development` **模式**:适用于插件开发阶段,开发者可以在无需打包和部署的情况下直接运行和调试插件,极大地提升了开发效率。 ### 配置运行模式 要配置插件的运行模式,可以在 Halo 的配置文件中进行以下设置: #### 以 `deployment` 模式运行插件 默认情况下,Halo 以 `deployment` 模式运行插件,无需特别配置。如果需要明确指定,可以参考以下配置: ```yaml halo: plugin: runtime-mode: deployment ``` 参考 [传统方式运行](https://docs.halo.run/developer-guide/plugin/hello-world.md#%E8%BF%90%E8%A1%8C%E6%8F%92%E4%BB%B6) #### 以 `development` 模式运行插件 在开发过程中,可以将 `runtime-mode` 修改为 `development`,并通过 `fixed-plugin-path` 指定插件的绝对路径,支持多个路径配置: ```yaml # macOS / Linux halo: plugin: runtime-mode: development fixed-plugin-path: # 配置为插件绝对路径 - /path/to/halo-plugin-hello-world # Windows halo: plugin: runtime-mode: development fixed-plugin-path: # 配置为插件绝对路径 - C:\path\to\halo-plugin-hello-world ``` :::tip development 模式的插件加载方式 1. `development` 开发模式下,既可以运行 `fixed-plugin-path` 下的插件,也可以运行通过 `Console` 管理端安装的 JAR 格式的插件。 2. 如果使用 [DevTools 运行方式](https://docs.halo.run/developer-guide/plugin/hello-world.md#%E8%BF%90%E8%A1%8C%E6%8F%92%E4%BB%B6) 来开发插件,则不需要配置 `runtime-mode` 和 `fixed-plugin-path`。 ::: ### 常用的 SemVer Range Expressions \{#common-range-expressions} - 常规符号:`>`、`>=`、`<`、`<=`、`=`、`!=` - 通配符范围 ( `*` | `X`| `x`):`1.*` 解释为 `>=1.0.0 && <2.0.0` - 波形符范围 ( `~` ):`~1.5` 解释为 `>=1.5.0 && <1.6.0` - 连字符范围 ( `-` ):`1.0-2.0` 解释为 `>=1.0.0 && <=2.0.0` - 插入符范围 ( `^` ):`^0.2.3`解释为 `>=0.2.3 && <0.3.0` - 部分版本范围:`1` 解释为 `1.x` 或 `>=1.0.0 && <2.0.0` - 否定运算符:`!(1.x)` 解释为 `<1.0.0 && >=2.0.0` - 带括号的表达式:`~1.3 || (1.4.* && !=1.4.5) || ~2` 更多详细信息请参考[SemVer Range Expressions](https://github.com/zafarkhaja/jsemver#range-expressions) --- url: https://docs.halo.run/developer-guide/plugin/basics/devtools.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # DevTools DevTools 插件开发工具提供了一些 Task,用于辅助 Halo 插件的运行、调试和代码生成。`haloServer`、`watch` 以及默认的 OpenAPI 文档生成流程需要本地具有 [Docker](https://docs.docker.com/get-docker/) 环境;从 DevTools 0.8.0 开始,OpenAPI 文档生成也可以直接复用已有的 Halo 服务,此时不需要 Docker。 DevTools 还提供了一些其他的构建任务,如插件打包、插件检查等。 DevTools 适合开发期运行和联调;自动化检查、兼容性验证及最终 JAR 安装测试参考[测试插件](https://docs.halo.run/developer-guide/plugin/testing.md)。 ## 安装 DevTools 是使用 Java 开发的一个 [Gradle](https://gradle.org/) 插件,如果你使用的 [halo-dev/create-halo-plugin](https://github.com/halo-dev/create-halo-plugin) 创建的插件项目,那么你无需任何操作,它已经默认集成了 DevTools 插件。 你可以在项目的 `build.gradle` 中找到它: ```groovy plugins { // ... id "run.halo.plugin.devtools" version "0.9.0" } ``` Release 版本和版本说明可以在 [GitHub Releases](https://github.com/halo-sigs/halo-gradle-plugin/releases) 上查看;插件开发依赖的 platform BOM(`run.halo.tools.platform:plugin`)最新版本可以在 [Maven Central](https://central.sonatype.com/artifact/run.halo.tools.platform/plugin) 上查看,建议与目标 Halo 版本保持一致。 ## 使用说明 当在项目中引入了 `devtools` 之后,就可以使用一些额外的构建任务来辅助插件的开发,参考 [构建任务详解](#任务)。 例如,正在开发 `plugin-starter` 插件时,可以通过 `haloServer` 任务启动 Halo 服务,来测试插件功能: ```shell ./gradlew haloServer ``` 看到如下日志时表示 Halo 服务已经启动成功: ```text ======================================================================= > Halo 启动成功! 访问地址:http://localhost:8090/console?language=zh-CN 用户名:admin 密码:admin API 文档:http://localhost:8090/swagger-ui.html 插件开发文档:https://docs.halo.run/developer-guide/plugin/introduction ======================================================================= ``` 修改代码后,无需停止服务,只需执行: ```shell ./gradlew reloadPlugin ``` 即可应用改动。如果使用 watch 任务启动插件,则不需要执行 `reloadPlugin`,它会自动监听并重载插件。 :::tip 关于任务名 `reloadPlugin` 是规范任务名;得益于 Gradle 的任务名缩写特性,`./gradlew reload` 在没有歧义时也可以工作,但建议使用完整任务名。 ::: ### 同时运行多个插件项目 从 DevTools 0.9.0 开始,可以通过 `-Pport` 在启动时指定端口,无需修改 `build.gradle`。例如,分别在两个插件项目的目录中执行: ```shell # 插件项目 A ./gradlew haloServer -Pport=8091 # 插件项目 B ./gradlew haloServer -Pport=8092 ``` `watch` 也支持同样的参数: ```shell ./gradlew watch -Pport=8091 ``` 使用 `haloServer` 启动后,在另一个终端进入同一插件项目目录,直接执行 `./gradlew reloadPlugin` 即可重载,无需重复传入端口。DevTools 会通过 Docker 查找该项目已记录的运行实例,并读取其访问地址。使用 `watch` 时,自动重载也会沿用启动时的地址。 端口取值范围为 `1` 到 `65535`,优先级为 `-Pport` > `halo.port` > 默认值 `8090`。未显式配置的 `externalUrl` 会自动跟随端口;如果配置了固定的 `externalUrl`,需要同步调整,或移除该配置以恢复自动推导。调试端口默认自动分配;如果固定了 `debugPort`,多个项目也需要使用不同的调试端口。 ## 配置 可通过 `build.gradle` 文件中的 `halo {}` 块自定义 DevTools 启动 Halo 服务必要配置,示例如下: ```groovy halo { version = '2.27' superAdminUsername = 'admin' superAdminPassword = 'admin' port = 8090 // 默认根据 port 推导为 http://localhost:8090 // externalUrl = 'http://localhost:8090' // 默认根据项目名称、根目录和 Gradle project path 自动生成 // containerName = 'halo-for-plugin-development' debug = true // 默认自动分配可用端口 // debugPort = 5005 // 通常不需要配置。未配置时使用 Docker 的默认配置和环境变量 // docker { // url = 'unix:///var/run/docker.sock' // apiVersion = '1.42' // } } ``` - `version`:表示要使用的 Halo 版本,随着插件 API 的更新你可能需要更高的 Halo 版本来运行插件,可自行更改。 - `superAdminUsername`:Halo 的超级管理员用户名,当你启动插件时会自动根据此配置和 `superAdminPassword` 为你初始化 Halo 的超级管理员账户。 - `superAdminPassword`:Halo 的超级管理员用户密码。 - `externalUrl`:Halo 的外部访问地址。未配置时会根据 `port` 推导为 `http://localhost:${port}`。 - `containerName`:开发用 Halo 容器的名称。未配置时会根据项目名称、根目录和 Gradle project path 自动生成,通常不需要手动设置。 - `docker.url`:用于配置连接 Docker 的 URL。未配置时使用 Docker Client 的默认配置和 `DOCKER_HOST`、`DOCKER_TLS_VERIFY`、`DOCKER_CERT_PATH` 等环境变量。 - `docker.apiVersion`:Docker 的 API 版本。大多数情况下无需配置;如需固定版本,可以使用 `docker version` 命令查看,例如: ```shellsession ➤ docker version Client: Version: 24.0.7 API version: 1.43 ``` - `port`:Halo 服务的端口号,默认为 `8090`。可以修改此配置;从 DevTools 0.9.0 开始,也可以通过 `-Pport` 覆盖,参考[同时运行多个插件项目](#同时运行多个插件项目)。 - `debug`:是否开启调试模式,开启后会在启动 Halo 服务时会自动开启调试模式,此时你可以使用 IDE 连接到 Halo 服务进行调试。 - `debugPort`:调试模式下的调试端口号,默认是自动分配端口号,你可以修改此配置来固定调试端口号。 - `suspend`:是否在启动时挂起,如果开启则会在启动时挂起直到有调试器连接到 Halo 服务。 :::warning Halo 2.20 版本兼容性 由于 Halo 2.20.0 版本更改了初始化和登录流程,如果 `halo.version` 指定 `2.20.x` 版本需要将 `run.halo.plugin.devtools` 版本升级到 `0.2.0` 及以上。 ::: ## 任务 本插件提供运行、热重载、OpenAPI 文档生成、API Client 生成和角色模板生成等任务。其中,`haloServer` 和 `watch` 需要在本地配置 Docker 环境。 ### 环境要求 - **Windows 和 Mac 用户**:可以直接安装 [Docker Desktop](https://www.docker.com/products/docker-desktop)。 - **Linux 用户**:请参考 [Docker 官方文档](https://docs.docker.com/engine/install/) 安装 Docker。 确保 Docker 服务已启动后,即可运行 `haloServer` 和 `watch` 任务。 ### 工作目录 这两个任务会将 Halo 的工作目录挂载到插件项目的 `workplace` 目录下,以确保在重启任务时数据不会丢失。 ### 自定义配置 如果需要修改 Halo 的配置,您可以在 `workplace` 目录下创建一个 `config` 目录,并添加一个 `application.yaml` 文件。在该文件中,您可以覆盖 Halo 的默认配置。例如: ```yaml # workplace/config/application.yaml logging: level: run.halo.app: DEBUG ``` 更多配置项请参考 [Halo 配置列表](https://docs.halo.run/guide/install/config.md#%E9%85%8D%E7%BD%AE%E5%88%97%E8%A1%A8)。 ### haloServer 任务 使用方式: ```shell ./gradlew haloServer ``` 此任务用于启动 Halo 服务并自动将使用此 Gradle 插件的 Halo 插件项目以开发模式加载到 Halo 服务中,当你修改了插件的代码后,可以通过 `reloadPlugin` 任务使更改生效。 #### haloServer 任务默认配置 使用 `create-halo-plugin` 创建的项目会显式配置目标 Halo 版本,例如: ```groovy halo { version = '2.27' } ``` 这不是 DevTools 自身的默认 Halo 版本。DevTools 0.9.0 源码中的默认值为 `2.9.1`,但实际项目应当显式指定与插件 API 依赖和目标 Halo 环境一致的版本。其他配置项及默认行为参见[配置](#配置)。 ### reloadPlugin 任务 使用方式: ```shell ./gradlew reloadPlugin ``` 此任务用于重新加载当前正在开发的插件,修改代码后执行此任务以应用更改。 从 DevTools 0.9.0 开始,不传 `-Pport` 时,该任务会通过 Docker 查询当前项目记录的容器,并使用运行实例的访问地址。因此,即使启动时使用了 `./gradlew haloServer -Pport=8091`,重载时也无需重复指定端口。 如果记录中的容器已停止、不存在,或无法查询其访问地址,任务会报错,不会回退连接默认端口。请重新启动 `haloServer`,或显式指定目标: ```shell ./gradlew reloadPlugin -Pport=8091 ``` 没有容器记录,或显式传入 `-Pport` 时,任务会按本次构建的 `halo` 配置连接,无需查询 Docker。显式配置的 `externalUrl` 仍优先于根据端口推导的地址。 无论使用哪种方式选择地址,调用 Halo API 时都使用以下配置中的管理员凭据: ```groovy halo { // ... superAdminUsername = 'admin' superAdminPassword = 'admin' // 可选,仅在需要固定访问地址时配置 // externalUrl = 'http://localhost:8090' } ``` ### watch 任务 使用方式: ```shell ./gradlew watch ``` 此任务用于监视 Halo 插件项目的变化并自动重新加载到 Halo 服务中。 默认监听整个 `src/main/` 目录,并排除 Console 构建产物等无需触发重载的内容。如果需要监听其他目录,可以在项目的 `build.gradle` 中添加如下配置: ```groovy haloPlugin { watchDomains { // consoleSource 为自定义的名称,可以随意取 consoleSource { // 监听 console/src/ 目录下的文件变化 files files('console/src/') // exclude '**/node_modules/**' // exclude '**/.idea/**' // exclude '**/.git/**' // exclude '**/.gradle/**' // exclude 'src/main/resources/ui/**' // exclude 'src/main/resources/console/**' // exclude 'build/**' // exclude 'gradle/**' // exclude 'dist/**' // exclude 'test/java/**' // exclude 'test/resources/**' } // ... 可以添加多个 } } ``` `exclude` 接收字符串用于排除不需要监听的文件或目录,可以使用 `**` 通配符。注释掉的是每个 `watchDomains` 都会默认排除的规则。 ### 生成 API client API Client 根据 OpenAPI 文档生成请求方法和 TypeScript 类型,用于减少手写请求代码并在编译期检查请求参数和响应类型。自动重试、错误日志等策略不由生成器提供,需要通过 Axios 实例自行配置。 #### 如何生成 API client \{#how-to-generate-api-client} 本插件提供了一个 `generateApiClient` 任务,用于为插件项目生成 API client,生成规则基于 OpenAPI 规范来自动生成客户端代码。 能生成 API 客户端代码的前提是插件项目中需要对自定义的 API 进行文档声明如: ```java final var tag = "CommentV1alpha1Console"; return SpringdocRouteBuilder.route() .GET("comments", this::listComments, builder -> { builder.operationId("ListComments") .description("List comments.") .tag(tag) .response(responseBuilder() .implementation(ListResult.generateGenericClass(ListedComment.class)) ); CommentQuery.buildParameters(builder); }) .build(); ``` 或者是在插件中定义了自定义模型,自定义模型自动生成的 CRUD APIs 是已经支持的。 以下是如何配置和使用 `generateApiClient` 的详细步骤: ##### 配置 `generateApiClient` 在 build.gradle 文件中,使用 haloPlugin 块来配置 OpenAPI 文档生成和 API 客户端生成的相关设置: ```groovy haloPlugin { openApi { // outputDir = file("$rootDir/api-docs/openapi/v3_0") // 指定 OpenAPI 文档的输出目录默认输出到 build 目录下,不建议修改,除非需要提交到代码仓库 // DevTools 0.8.0 起支持复用已有 Halo 服务。启用后不启动临时容器,默认读取 halo.externalUrl // useExistingServer = true // 仅在需要读取其他 Halo 服务时覆盖 // apiDocsUrl = 'http://localhost:8090' groupingRules { // 定义 API 分组规则,用于为插件项目中的 APIs 分组然后只对此分组生成 API 客户端代码 // 定义了一个名为 extensionApis 的分组,task 会通过 /v3/api-docs/extensionApis 访问到 api docs 然后生成 API 客户端代码 // extensionApis 名称可以替换为其他名称,但需要与 groupedApiMappings 中的名称一致 extensionApis { // 分组显示名称,避免与其他分组重名建议替换 {your-plugin-name} 为插件名称 displayName = 'Extension API for {your-plugin-name}' // 分组的 API 规则用于匹配插件项目中的 API 将其划分到此分组,它是一个 Ant 风格的路径匹配规则可以写多个 pathsToMatch = ['/apis/staticpage.halo.run/v1alpha1/**'] } } groupedApiMappings = [ // 这里为固定写法,照搬即可,除非是 groupingRules 中 extensionApis 的名字修改了 '/v3/api-docs/extensionApis': 'extensionApis.json' ] generator { // 指定 API 客户端代码的输出目录如 console 或 ui outputDir = file("${projectDir}/console/src/api/generated") // 定制生成,以下是默认配置可以不需要添加到 build.gradle 中 additionalProperties = [ useES6: true, useSingleRequestParameter: true, withSeparateModelsAndApi: true, apiPackage: "api", modelPackage: "models" ] // 类型映射,用于将 OpenAPI 中的类型映射到 TypeScript 中的类型,以下是默认配置可以不需要添加到 build.gradle 中 typeMappings = [ set: "Array" ] } } } ``` 当配置了 `openApi` 规则之后,`haloServer` 或 `watch` 启动可以通过 `http://localhost:8090/swagger-ui.html` 访问 API 文档, 并通过选择你配置的 `displayName` 分组来**检查你的规则是否正确**。 这一步检查有助于避免生成 API Client 为空或者生成 `roleTemplates.yaml` 为空的情况。 ##### 执行 `generateApiClient` 在项目目录中执行以下命令即可生成 API 客户端代码到指定目录: ```shell ./gradlew generateApiClient ``` 然后在 `openApi.generator.outputDir` 目录创建一个 `index.ts` 文件并创建实例,以瞬间插件为例 ```typescript // console/src/api/index.ts // 先引入 axiosInstance 用于请求 import { axiosInstance } from "@halo-dev/api-client"; // 这里导入的是声明 API doc 时指定的 tag 名称,如上文中定义的 CommentV1alpha1Console import { ConsoleApiMomentHaloRunV1alpha1MomentApi, MomentV1alpha1Api, UcApiMomentHaloRunV1alpha1MomentApi, } from "./generated"; // MomentV1alpha1Api 是自定义模型生成的 API tag 这里创建了一个 momentsCoreApiClient 实例 const momentsCoreApiClient = { moment: new MomentV1alpha1Api(undefined, "", axiosInstance), }; // ConsoleApiMomentHaloRunV1alpha1MomentApi 是用于在 console 端调用的 APIs 的 tag,这里创建了一个 momentsConsoleApiClient 实例用于在 console 端调用 const momentsConsoleApiClient = { moment: new ConsoleApiMomentHaloRunV1alpha1MomentApi( undefined, "", axiosInstance, ), }; // 用于在个人中心调用的 APIs,单独创建一个 momentsUcApiClient 实例 const momentsUcApiClient = { moment: new UcApiMomentHaloRunV1alpha1MomentApi(undefined, "", axiosInstance), }; // 导出实例 export { momentsConsoleApiClient, momentsCoreApiClient, momentsUcApiClient }; ``` 使用定义的实例: ```typescript import { momentsConsoleApiClient } from "@/api"; // 查询瞬间的标签 const { data } = await momentsConsoleApiClient.moment.listTags({ name: props.keyword?.value, }); ``` :::tip API 客户端生成流程 它会先执行 `generateOpenApiDocs` 任务根据配置访问 `/v3/api-docs/extensionApis` 获取 OpenAPI 文档, 并将 OpenAPI 的 Schema 文件保存到 `openApi.outputDir` 目录下,然后再由 `generateApiClient` 任务根据 Schema 文件生成 API 客户端代码到 `openApi.generator.outputDir` 目录下。 如果 OpenAPI 文档依赖其他已安装插件,请先启动并准备好对应的 Halo 服务,然后设置 `openApi.useExistingServer = true`。此模式默认从 `halo.externalUrl` 读取文档并跳过临时容器;只有读取其他 Halo 服务时才需要设置 `openApi.apiDocsUrl`。连接需要自定义请求头或信任库时,还可以配置 `requestHeaders`、`trustStore` 和 `trustStorePassword`。 ::: :::warning 避免误删生成目录 `generateOpenApiDocs` 会先删除 `openApi.outputDir`,`generateApiClient` 会先删除 `openApi.generator.outputDir`。这两个配置都必须指向专用目录,不能与源码目录或其他文件共用,以免误删文件。 `generateOpenApiDocs` 依赖项目的 `build` 任务。如果前端构建又依赖尚未生成的 API Client,需要调整任务依赖关系,避免形成循环依赖。 ::: ### generateRoleTemplates 任务 在 Halo 插件开发中,权限管理是一个关键问题,尤其是配置[角色模板](https://docs.halo.run/developer-guide/plugin/security/rbac#%E8%A7%92%E8%89%B2%E6%A8%A1%E6%9D%BF)时,角色的 `rules` 部分往往让开发者感到困惑。具体来说,如何区分资源、apiGroup、verb 等概念是许多开发者的痛点。 `generateRoleTemplates` Task 的出现正是为了简化这一过程,该任务能够根据 [配置 Generate Api Client](#配置-generateapiclient) 中的配置获取到 OpenAPI docs 的 JSON 文件,并自动生成 Halo 的 Role YAML 文件,让开发者可以专注于自己的业务逻辑,而不是纠结于复杂的角色 `rules` 配置。 在生成的 `roleTemplates.yaml` 文件中,rules 部分是基于 OpenAPI docs 中 API 资源和请求方式自动生成的,覆盖了可能的操作。 然而,在实际的生产环境中,Role 通常会根据具体的需求被划分为不同的权限级别,例如: - 查看权限的角色模板:通常只包含对资源的读取权限,如 get、list、watch 等。 - 管理权限的角色模板:则可能包含创建、修改、删除等权限,如 create、update、delete。 > watch verb 是对于 WebSocket API,不会在 roleTemplates.yaml 中体现为 watch,而是体现为 list,因此需要开发者根据实际情况进行调整。 因此,生成的 YAML 文件只是一个基础模板,涵盖了所有可用的操作。开发者需要根据自己的实际需求,对这些 rules 进行调整。比如,针对只需要查看资源的场景,开发者可以从生成的 YAML 中删除`修改`和`删除`相关的操作,保留读取权限。 而对于需要管理资源的场景,可以保留`创建`、`更新`和`删除`权限,对于角色模板的依赖关系和聚合关系,开发者也可以根据实际情况进行调整。 通过这种方式,开发者可以使用生成的 YAML 文件作为基础,快速定制出符合不同场景的权限配置,而不必从头开始编写复杂的规则以减少出错的可能性。 #### 如何使用 在 build.gradle 文件中,使用 haloPlugin 块来配置 OpenAPI 文档生成和 Role 模板生成的相关设置: ```groovy haloPlugin { openApi { // 参考配置 generateApiClient 中的配置 } } ``` 在项目目录中执行以下命令即可生成 `roleTemplates.yaml` 文件到 `workplace` 目录: ```shell ./gradlew generateRoleTemplates ``` ## 调试后端代码 如果你想调试后端代码,可以在 `build.gradle` 中配置 ```groovy halo { debug = true } ``` 然后通过 IDEA 运行 `haloServer` 以便于配合 `IDEA` 进行调试。 ![Use-Devtools](/img/developer-guide/plugin/use-devtools.png) 首先点击上图中 `1` 处的 `haloServer` 运行插件,然后点击 `2` 处的 `Attach debugger` 让 IDEA 连接到 Halo 服务,此时会打开一个调试窗口就可以开始打断点调试了。 可能会因为日志太快而点击不到 `Attach debugger`,那么你可以配置 ```groovy halo { debug = true suspend = true } ``` 这样,在点击 `haloServer` 启动插件时会挂起等待在 `Attach debugger` 处,直到你点击 `Attach debugger` 连接调试器后才会继续执行。 ## 迁移 ### 从旧版本升级到 0.2.x 及以上版本 如果 `run.halo.plugin.devtools` 从旧版本升级到 `0.2.0` 版本,需要先将 Gradle 版本升级到 `8.3` 以上,你可以通过以下命令升级 Gradle 版本: 在插件项目根目录下执行: ```shell # 如将 Gradle 版本升级至 8.9 ./gradlew wrapper --gradle-version=8.9 ``` --- url: https://docs.halo.run/developer-guide/plugin/basics/server/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 服务端基础 ## 服务端 ### [生命周期](/developer-guide/plugin/basics/server/lifecycle.md) - [生命周期与数据边界](/developer-guide/plugin/basics/server/lifecycle.md#生命周期与数据边界) - [插件启动](/developer-guide/plugin/basics/server/lifecycle.md#插件启动) - [插件停止](/developer-guide/plugin/basics/server/lifecycle.md#插件停止) - [插件删除](/developer-guide/plugin/basics/server/lifecycle.md#插件删除) ### [插件中的对象管理](/developer-guide/plugin/basics/server/object-management.md) - [PluginContext](/developer-guide/plugin/basics/server/object-management.md#plugincontext) - [依赖注入 Halo 共享的 Bean](/developer-guide/plugin/basics/server/object-management.md#依赖注入-halo-共享的-bean) ### [响应式服务端开发](/developer-guide/plugin/basics/server/reactive-development.md) - [保持调用链非阻塞](/developer-guide/plugin/basics/server/reactive-development.md#保持调用链非阻塞) - [隔离无法替换的阻塞调用](/developer-guide/plugin/basics/server/reactive-development.md#隔离无法替换的阻塞调用) - [处理外部请求和错误](/developer-guide/plugin/basics/server/reactive-development.md#处理外部请求和错误) - [管理后台任务](/developer-guide/plugin/basics/server/reactive-development.md#管理后台任务) - [测试响应式行为](/developer-guide/plugin/basics/server/reactive-development.md#测试响应式行为) ### [数据存储](/developer-guide/plugin/basics/server/data-storage.md) - [选择存储方式](/developer-guide/plugin/basics/server/data-storage.md#选择存储方式) - [使用本地文件](/developer-guide/plugin/basics/server/data-storage.md#使用本地文件) - [运行和部署边界](/developer-guide/plugin/basics/server/data-storage.md#运行和部署边界) - [备份和升级](/developer-guide/plugin/basics/server/data-storage.md#备份和升级) ### [定时任务](/developer-guide/plugin/basics/server/scheduled-tasks.md) - [启用调度](/developer-guide/plugin/basics/server/scheduled-tasks.md#启用调度) - [生命周期](/developer-guide/plugin/basics/server/scheduled-tasks.md#生命周期) - [注意事项](/developer-guide/plugin/basics/server/scheduled-tasks.md#注意事项) ### [日志](/developer-guide/plugin/basics/server/logging.md) - [使用 SLF4J](/developer-guide/plugin/basics/server/logging.md#使用-slf4j) - [日志级别约定](/developer-guide/plugin/basics/server/logging.md#日志级别约定) - [调整插件日志级别](/developer-guide/plugin/basics/server/logging.md#调整插件日志级别) --- url: https://docs.halo.run/developer-guide/plugin/basics/server/lifecycle.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 生命周期 插件入口类继承的 `BasePlugin` 提供以下生命周期方法。脚手架默认重写 `start()` 和 `stop()`;只有需要处理卸载行为时才重写 `delete()`: ```java @Override public void start() { System.out.println("插件启动成功!"); } @Override public void stop() { System.out.println("插件停止!"); } @Override public void delete() { System.out.println("插件被删除!"); } ``` 它们就是插件的生命周期方法,分别对应插件的启动、停止和删除。 1. 继承 `run.halo.app.plugin.BasePlugin` 类后,你可以重写这些方法来干预插件的生命周期,例如在插件启动时初始化一些资源,在插件停止时清理掉这些资源。 2. 一个插件项目只允许有一个类继承 `BasePlugin` 类且标记为 Bean,此时这个类将被作为插件的后端入口,如果有多个类继承了 `BasePlugin` 会导致插件无法启动或生命周期方法无法被调用。 :::tip 将 BasePlugin 注册为 Bean 如果一个类继承了 `BasePlugin` 类但没有标记为 Bean,那么它将不会被 Halo 识别到,其中的生命周期方法也不会被调用。 ::: ## 生命周期与数据边界 | 方法 | 调用时机 | 适合执行的操作 | | ---------- | ------- | ----------------------------------- | | `start()` | 插件启动时 | 注册自定义模型 Scheme、初始化缓存、注册监听器等运行时资源 | | `stop()` | 插件停止或禁用 | 注销 Scheme、关闭监听器和连接、释放缓存等可重新创建的运行时资源 | | `delete()` | 插件被卸载时 | 按插件的卸载约定清理外部资源或持久化数据 | :::warning 不要在 stop() 中删除持久化业务数据 `stop()` 也会在插件禁用、重载等场景中调用。插件重新启动后仍需使用的自定义模型数据不应在此删除。 只有在插件的卸载约定明确要求删除数据时,才应在 `delete()` 中执行持久化数据清理,并提前考虑数据备份和不可恢复风险。 ::: 存储方式参考[数据存储](https://docs.halo.run/developer-guide/plugin/basics/server/data-storage.md)。 ## 插件启动 插件被安装后,只加载了插件的 `plugin.yaml`,类及其他资源文件的加载均在启动时进行。 当插件加载完类文件并准备好启动插件后就会调用插件的 `start()` 方法。自定义模型需要在此注册 Scheme,并在 `stop()` 中对称地注销: ```java @Override public void start() { schemeManager.register(MyExtension.class); } @Override public void stop() { schemeManager.unregister(Scheme.buildFromType(MyExtension.class)); } ``` ## 插件停止 插件停止时,应释放由 `start()` 创建且能够在下次启动时重建的运行时资源,例如 Scheme、监听器、连接和缓存。 Halo 还会清理由插件 `src/main/resources/extensions/*.yaml` 加载并记录的预置资源,但以下资源不属于这项停止清理: - `spec.settingName` 指向的 `Setting`,它由 Halo 单独管理。 - 带有 `halo.run/do-not-overwrite` 标签的预置资源。 - 插件在运行期间创建的持久化业务数据。 因此,不要把“注销自定义模型的 Scheme”和“删除该模型的所有数据”混为一谈。 ## 插件删除 `delete()` 在插件被卸载时调用,适合执行仅在卸载时需要的最终清理。Halo 会在插件清理流程中移除插件文件、反向代理以及 `spec.settingName` 指向的 `Setting`;插件自行管理的外部资源或业务数据是否删除,应由插件的卸载约定决定。 --- url: https://docs.halo.run/developer-guide/plugin/basics/server/object-management.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 插件中的对象管理 在插件中你可以使用 [Spring Framework](https://spring.io/projects/spring-framework/) 提供的常用 Bean 注解来标注一个类,然后就能使用依赖注入功能注入其他类的对象。这省去了使用工厂创建类和维护的过程,你可以像开发一个常规的 Spring 项目一样来开发插件,目前支持以下 Spring Framework 的特性: 1. [Core Technologies](https://docs.spring.io/spring-framework/reference/core.html) 2. [Web on Reactive](https://docs.spring.io/spring-framework/reference/web-reactive.html) 3. [Testing](https://docs.spring.io/spring-framework/reference/testing.html) 通过脚手架创建的项目中,插件入口类会标注 `@Component`: ```java @Component public class HelloWorldPlugin extends BasePlugin { public HelloWorldPlugin(PluginContext pluginContext) { super(pluginContext); } } ``` 假设项目中有一个 `FruitService`,并将其声明了为了 Bean: ```java @Service public class FruitService { } ``` 你可以在任何同样声明为 Bean 的类中使用[依赖注入](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-dependencies)来使用它: ```java @Component public class Demo { private final FruitService fruitService; public Demo(FruitService fruitService) { this.fruitService = fruitService; } // use it... } ``` ## PluginContext Halo 会向插件入口的构造函数提供 `PluginContext`,可以安全保留并在插件生命周期内使用: | 属性 | 含义 | | --------------- | ----------------------------------------- | | `name` | 插件的 `metadata.name`,可用于日志和本地数据目录命名空间 | | `configMapName` | `plugin.yaml` 声明的配置 ConfigMap 名称;未配置时可能为空 | | `version` | 当前加载的插件版本 | | `runtimeMode` | 当前为开发模式还是部署模式 | 不要使用显示名称、Java 包名或硬编码常量代替插件 `name` 来标识运行中的插件。 ## 依赖注入 Halo 共享的 Bean Halo 提供了一些共享的 Bean,任何插件都可以直接依赖注入这些 Bean。 ### ReactiveExtensionClient `ReactiveExtensionClient` 是一个用于管理自定义模型对象的增删改查的 Bean,它是反应式的。 参考 [与自定义模型交互](https://docs.halo.run/developer-guide/plugin/api-reference/server/extension-client.md) 了解更多。 ### ExtensionClient `ExtensionClient` 作用和方法与 ReactiveExtensionClient 一样,但它是阻塞的,只能用在非 NIO 线程中,如后台任务。 ### ReactiveSettingFetcher 和 SettingFetcher 用于读取 `plugin.yaml` 中 `settingName` 和 `configMapName` 对应的插件配置,并在配置更新后自动读取新值。响应式调用链使用 `ReactiveSettingFetcher`;具体方法参考[获取插件配置](https://docs.halo.run/developer-guide/plugin/api-reference/server/setting-fetcher.md)。 ### SchemeManager `SchemeManager` 是一个用于管理自定义模型定义的注册和销毁的 Bean。 API 参考:[SchemeManager](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/extension/SchemeManager.java) ### UserService 用于操作 Halo 用户的 Bean,包括获取用户信息、更新密码、创建用户等函数。 API 参考 [UserService](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/core/user/service/UserService.java) ### ReactiveUserDetailsService 用于获取用户信息的 Bean,它只有一个方法 `Mono findByUsername(String username)`。 ### RoleService 用于操作 Halo 角色的 Bean,包括查询角色绑定、角色及依赖等函数。 API 参考 [RoleService](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/core/user/service/RoleService.java) ### AttachmentService 用于操作 Halo 附件的 Bean,包括上传、删除附件以及获取附件访问链接等函数。 API 参考 [AttachmentService](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/core/extension/service/AttachmentService.java)。 ### PostContentService 在 Halo 中,文章内容具有版本管理的概念。第一个版本是完整的文章内容,称为 `baseSnapshot`。从第二个版本开始,每个版本都是基于 `baseSnapshot` 的增量内容。因此,要查询完整的文章内容,需要获取 `baseSnapshot` 以及对应的版本增量内容并合并。 ![文章内容版本模型](/img/developer-guide/plugin/basic/server/post-content-version-generation.png) 为了方便插件开发者获取文章内容,Halo 提供了 `PostContentService`,以简化这一过程的复杂性。 - getHeadContent:获取文章的最新版本内容(包括正在编辑的草稿)。 - getReleaseContent:获取最新发布的文章内容。 - getSpecifiedContent:获取指定 snapshotName 对应的文章内容。 - listSnapshots:获取指定文章的所有版本的 Snapshot 对象的名称列表。 API 参考:[PostContentService](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/content/PostContentService.java) 文章自定义模型定义参考 [Post](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/core/extension/content/Post.java) ### NotificationReasonEmitter 用于发送通知事件的 Bean。 使用示例参考 [通知事件触发示例](https://docs.halo.run/developer-guide/plugin/api-reference/server/notification.md#reason-emitter-example) API 参考:[NotificationReasonEmitter](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/notification/NotificationReasonEmitter.java) ### NotificationCenter 用于管理通知的订阅和取消订阅。 使用示例参考 [通知订阅示例](https://docs.halo.run/developer-guide/plugin/api-reference/server/notification.md#subscribe-example) API 参考:[NotificationCenter](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/notification/NotificationCenter.java) ### ExternalLinkProcessor 用于将一个站内相对链接转换为绝对链接。 如配置了外部访问地址为 `https://example.com`,那么将 `/post/1` 转换为 `https://example.com/post/1`。 API 参考:[ExternalLinkProcessor](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/infra/ExternalLinkProcessor.java)。 ### LoginHandlerEnhancer Halo 提供了登录增强机制,插件可以在登录成功或失败时调用登录增强器,使 Halo 可以执行额外的处理逻辑。 参考 [登录增强器](https://docs.halo.run/developer-guide/plugin/api-reference/server/login-handler-enhancer.md) 了解更多。 使用示例参考用户名密码登录的[成功处理](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/application/src/main/java/run/halo/app/security/authentication/LoginSuccessHandler.java)和[失败处理](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/application/src/main/java/run/halo/app/security/authentication/LoginFailureHandler.java)。 ### BackupRootGetter 用于获取 Halo 备份文件的根目录。它是 `Supplier` 的子类。 ### PluginsRootGetter 用于获取 Halo 共享的插件根目录。它是 `Supplier` 的子类,其中还会存放插件 JAR;插件写入数据时必须创建以 `PluginContext.name` 命名的子目录,不能直接向根目录写业务文件或修改其他插件的数据。存储方式参考[数据存储](https://docs.halo.run/developer-guide/plugin/basics/server/data-storage.md)。 ### ExtensionGetter 用于获取扩展点实例(扩展)的 Bean。 例如,Halo 定义了 `AttachmentHandler` 这个扩展点,你可以通过 `ExtensionGetter` 获取到所有实现了 `AttachmentHandler` 接口的扩展。 有了它,插件中便可以定义自己的扩展点,然后由其他插件实现以达到插件扩展插件的目的。 API 参考 [ExtensionGetter](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/plugin/extensionpoint/ExtensionGetter.java) ### ServerSecurityContextRepository 用于获取操作用户的认证上下文信息,如登录成功后保存认证信息。 ServerSecurityContextRepository 被 [ReactorContextWebFilter](https://github.com/spring-projects/spring-security/blob/9d2ca3da6a285f31ebd2da5f019127e1527e5042/web/src/main/java/org/springframework/security/web/server/context/ReactorContextWebFilter.java) 使用来获取操作用户的认证上下文信息并填充到 ReactiveSecurityContextHolder 中。 此过滤器的执行顺序在 [SecurityWebFiltersOrder](https://github.com/spring-projects/spring-security/blob/9d2ca3da6a285f31ebd2da5f019127e1527e5042/config/src/main/java/org/springframework/security/config/web/server/SecurityWebFiltersOrder.java#L47) 中定义。因此如果你的过滤器在此过滤器之前执行,那么你将无法从 ReactiveSecurityContextHolder 中获取到操作用户的认证上下文信息只能通过注入 ServerSecurityContextRepository 来获取。 API 参考:[ServerSecurityContextRepository](https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/web/server/context/ServerSecurityContextRepository.html) ### CryptoService Halo 根据用户名密码登录时,会先使用 CryptoService 的 `readPublicKey` 方法读取公钥,然后使用公钥加密密码,再发送给服务器。 当插件需要添加一些拦截器处理登录请求时可能需要获取原始密码,此时可以使用 CryptoService 的 `decrypt` 方法解密密码。 也可以复用它的公钥来作为一些加密算法的密钥。 API 参考 [CryptoService](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/security/authentication/CryptoService.java) ### ExternalUrlSupplier `ExternalUrlSupplier` 是一个用于获取用户配置的 Halo 外部访问地址的 Bean。 API 参考:[ExternalUrlSupplier](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/infra/ExternalUrlSupplier.java) ### RateLimiterRegistry `RateLimiterRegistry` 是一个用于管理限流器的 Bean。 如果插件定义的某些 API 需要限流,可以使用 `RateLimiterRegistry` 来创建一个限流器,但是需要注意的是,**必须要在插件停止的生命周期方法里销毁你所创建的限流器**,否则会导致内存泄漏。 #### 使用示例 以下示例展示了如何使用 `RateLimiterRegistry` 创建一个限流器: ```java final Set limiterNames = new HashSet<>(); Mono sendEmailVerificationCode(String username, String email) { return buildSendEmailRateLimiter(username, email) // step 1: 构建一个限流器 .transformDeferred(rateLimiter -> rateLimiter.map(RateLimiterOperator::of)) // step 2: 返回一个经过变换的新 Mono // step 3: 从这里开始的操作符都会受到限流的影响 .flatMap(rateLimiter -> emailVerificationService.sendVerificationCode(username, email)) // 转换 RequestNotPermitted 为 RateLimitExceededException 以使全局异常处理器能够处理 .onErrorMap(RequestNotPermitted.class, RateLimitExceededException::new); } RateLimiter buildSendEmailRateLimiter(String username, String email) { var rateLimiterKey = "send-email-verification-code-" + username + ":" + email; var rateLimiter = rateLimiterRegistry.rateLimiter(rateLimiterKey, new RateLimiterConfig.Builder() // 频次限制为 1 次 .limitForPeriod(1) // 限制刷新周期为 60 秒,即 60 秒内只能执行 1 次 .limitRefreshPeriod(Duration.ofSeconds(60)) .build()); // 添加 limiter 到自己实现的 Registry 中保存起来以便在插件停止时清理 limiters.add(rateLimiterKey); return limiter; } ``` 在插件停止的生命周期方法里销毁你所创建的限流器: ```java @Override public void stop() { limiters.forEach(rateLimiterRegistry::remove); } ``` `transformDeferred` 的作用是将 Mono 传入你提供的变换器中,返回一个经过变换的新 Mono。由于 RateLimiterOperator 是基于 Publisher 的装饰器(decorator),它会监视这个 Mono 的订阅和执行情况,从而对整个 Mono 的操作链进行限流。 换句话说,因为 `RateLimiterOperator` 装饰了这个 Mono,所以任何接在 `transformDeferred()` 之后的操作符都会受到限流的影响,直到整个流结束。 ### SystemInfoGetter 用于获取站点基本信息的 Bean,它是 `Supplier>` 的子类,仅有一个 `get` 方法。 > 此为 `2.20.11` 版本新增的 Bean 因此需要 Halo 2.20.11 及以上版本才可使用。 可以获取到的数据示例如下: ```json { "title": "guqing's blog", "subtitle": "副标题", "logo": "/upload/myavatar.png", "favicon": "/upload/myavatar.png", "url": "http://localhost:8090", "version": { "majorVersion": 2, "minorVersion": 20, "normalVersion": "2.20.10", "preRelease": true, "publicApiStable": true, "patchVersion": 10, "preReleaseVersion": "SNAPSHOT", "buildMetadata": "", "stable": false }, "seo": { "blockSpiders": false, "keywords": "keyword1,keyword2", "description": "站点描述" }, "locale": "zh_CN_#Hans", "timeZone": "Asia/Shanghai", "activatedThemeName": "theme-earth" } ``` --- url: https://docs.halo.run/developer-guide/plugin/basics/server/reactive-development.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 响应式服务端开发 Halo 服务端基于 Spring WebFlux。请求通常由少量事件循环线程处理,因此插件的 Controller、WebFilter、Finder 和其他响应式扩展不应阻塞当前线程。 ## 保持调用链非阻塞 在响应式入口中直接返回 `Mono` 或 `Flux`,并使用 `ReactiveExtensionClient`、`ReactiveSettingFetcher`、`WebClient` 等响应式 API: ```java public Mono getProfile(String name) { return client.fetch(Profile.class, name) .switchIfEmpty(Mono.error(new NotFoundException("Profile not found"))); } ``` 不要在 WebFlux Controller、WebFilter 或响应式扩展点中调用 `.block()`,也不要直接调用 `ExtensionClient`、JDBC、阻塞式 HTTP 客户端或文件 I/O。WebFlux 默认假设请求线程不会阻塞,具体线程模型参考 [Spring WebFlux 并发模型](https://docs.spring.io/spring-framework/reference/web/webflux/new-framework.html#webflux-concurrency-model)。 返回 Publisher 后由 Halo 负责订阅。不要为了“让代码执行”而在请求处理方法内部调用 `.subscribe()`,否则错误、取消和请求上下文会脱离原调用链。 ## 隔离无法替换的阻塞调用 只有依赖库没有响应式 API 时,才把单个阻塞操作包装到 `boundedElastic`: ```java public Mono execute() { return Mono.fromCallable(blockingClient::execute) .subscribeOn(Schedulers.boundedElastic()) .timeout(Duration.ofSeconds(5)); } ``` - 使用 `Mono.fromCallable` 延迟执行阻塞操作。 - 将 `subscribeOn(Schedulers.boundedElastic())` 紧邻阻塞源放置,使订阅和调用在受限的工作线程池执行。 - `timeout` 只限制响应式调用链等待时间,不保证底层阻塞库立即中断;仍应配置 HTTP、数据库或文件库自身的连接和读取超时。 - 不要把整条响应式链无差别切换到 `boundedElastic`,只隔离无法替换的阻塞边界。 该模式参考 [Reactor:包装同步阻塞调用](https://projectreactor.io/docs/core/release/reference/faq.html#faq.wrap-blocking)。 ## 处理外部请求和错误 使用 `WebClient` 时返回响应式结果,并为外部依赖设置明确的超时和错误语义: ```java public Mono fetchRemote() { return webClient.get() .uri("/results") .retrieve() .bodyToMono(RemoteResult.class) .timeout(Duration.ofSeconds(5)) .onErrorMap(WebClientResponseException.class, error -> new RemoteServiceException("Remote request failed", error)); } ``` 不要用 `onErrorResume` 静默吞掉所有异常。只有业务允许降级时才返回缓存或默认值,并保留足够的日志和状态让使用者识别依赖失败。 ## 管理后台任务 定时任务、异步事件或插件启动时创建的长期订阅不属于 HTTP 请求生命周期。插件需要保存它创建的 `Disposable`、线程池、连接或客户端,并在 [`stop()`](https://docs.halo.run/developer-guide/plugin/basics/server/lifecycle.md#%E6%8F%92%E4%BB%B6%E5%81%9C%E6%AD%A2) 中释放;重载后必须能够重新创建。 ## 测试响应式行为 - 使用 `StepVerifier` 验证正常结果、空结果和错误类型,并为验证设置超时,避免测试无限等待。 - 对阻塞边界验证调用确实在工作线程执行,同时验证超时和依赖不可用时的结果。 - 对外部服务验证非 2xx、慢响应、连接失败和取消场景。 - 使用 `haloServer` 联调时同时检查 Halo 日志,确认没有阻塞线程警告和未处理错误。 完整验证流程参考[测试插件](https://docs.halo.run/developer-guide/plugin/testing.md)。 --- url: https://docs.halo.run/developer-guide/plugin/basics/server/data-storage.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 数据存储 插件应根据数据用途、查询方式和生命周期选择存储方式。不要为少量配置自行维护数据库,也不要把不可恢复的业务数据当作缓存。 ## 选择存储方式 | 数据类型 | 建议方式 | | -------------------------------- | ------------------------------------------------ | | 需要通过 Halo API 查询、授权或与其他插件交互的业务数据 | 自定义模型和 `ReactiveExtensionClient` | | 由用户在插件设置页面维护的少量配置 | `Setting`、`ConfigMap` 和 `ReactiveSettingFetcher` | | 密码、Token、API Key 和私钥 | `Secret`,其他资源只保存 Secret 名称 | | 插件专用数据库、索引或无法表示为自定义模型的文件 | `PluginsRootGetter` 下的插件专属目录 | | 可以重新生成的临时结果 | 明确标识的缓存目录,并允许安全删除和重建 | 配置读取参考[获取插件配置](https://docs.halo.run/developer-guide/plugin/api-reference/server/setting-fetcher.md),自定义模型参考[自定义模型](https://docs.halo.run/developer-guide/plugin/api-reference/server/extension.md),密钥存储和第三方请求参考[敏感数据与出站请求](https://docs.halo.run/developer-guide/plugin/security/outbound-http.md)。 ## 使用本地文件 `PluginsRootGetter` 从 Halo 2.18.0 开始提供插件根目录。插件应在该根目录下使用稳定且唯一的专属子目录,通常采用自身 `metadata.name` 或不会与其他插件冲突的固定名称。不能读写其他插件目录,也不能把路径暴露为任意用户输入。 本地文件不会自动获得自定义模型的查询、权限和版本能力。写入关键文件时,应先写入同目录临时文件,确认内容完整后再替换目标文件,避免进程中断留下半写状态。 ## 运行和部署边界 - **多副本**:本地目录通常不是跨副本共享存储。需要多副本一致读写的数据应使用自定义模型或明确配置的外部存储。 - **生命周期**:禁用或重载插件时不要删除持久化数据;仅在明确的卸载约定和用户知情情况下清理。 - **并发**:SQLite 等单文件数据库需要处理锁、超时和并发写入,不能假设每次调度或请求都串行执行。 - **敏感数据**:不要在日志、ConfigMap、自定义模型或未保护的缓存中存储密钥和个人敏感信息。密码、Token、API Key 和私钥应使用 Halo `Secret`;确需存储其他敏感文件时,应限制文件权限并说明数据用途。 ## 备份和升级 Halo 不会自动理解插件私有文件或数据库的 schema。选择本地存储后,插件需要自行定义: 1. 哪些文件属于持久化数据,哪些可以重建。 2. Halo 备份是否包含这些数据,以及用户如何单独备份和恢复。 3. schema 版本、升级顺序和失败后的恢复方式。 4. 新版本能否安全地重复执行升级步骤。 不要把未经验证的迁移过程描述为 Halo 的通用迁移方案。发布前应在数据副本上验证升级、降级限制、损坏恢复和插件卸载行为。 --- url: https://docs.halo.run/developer-guide/plugin/basics/server/scheduled-tasks.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 定时任务 Halo 插件运行在独立的 Spring 应用上下文中,因此可以直接使用 Spring 的调度能力执行周期性任务,例如定时同步外部数据、生成站点地图、清理过期记录等。 ## 启用调度 在插件启动类上添加 `@EnableScheduling`,然后在任意 Spring Bean 的方法上使用 `@Scheduled`: ```java @EnableScheduling public class MyPlugin extends BasePlugin { // ... } ``` ```java @Component public class SitemapScheduler { // 每小时执行一次 @Scheduled(fixedDelay = 60 * 60 * 1000L, initialDelay = 60 * 1000L) public void regenerate() { // do something } // 或使用 cron 表达式,每天凌晨 3:30 执行 @Scheduled(cron = "0 30 3 * * *") public void dailyCleanup() { // do something } } ``` `@Scheduled` 支持 `fixedRate`、`fixedDelay`、`initialDelay` 和 `cron` 等方式,完整说明参考 [Spring 调度文档](https://docs.spring.io/spring-framework/reference/integration/scheduling.html)。 ## 生命周期 定时任务注册在插件自己的应用上下文中,因此: - 插件启动后任务才开始调度,插件停止或卸载时上下文关闭,任务随之取消,无需手动清理。 - Halo 不保证根应用的 `/actuator/scheduledtasks` 能发现插件子应用上下文中的任务。插件应自行记录任务的开始、结束和失败信息。 ## 注意事项 - **避免阻塞调度线程**:Spring 默认使用单线程调度器,长时间运行的任务会拖延同插件内其他任务的执行;耗时操作应切换到弹性线程执行(参考[响应式服务端开发](https://docs.halo.run/developer-guide/plugin/basics/server/reactive-development.md)中的阻塞隔离方式)。 - **任务应是幂等的**:Halo 可能运行在多个副本或被重启,任务逻辑应能安全地重复执行,不要依赖上一次运行的内存状态。 - **明确时区**:使用 cron 时通过 `zone` 显式声明业务时区,避免部署环境的系统时区改变执行时间。 - **避免任务重叠**:执行时间可能超过调度间隔时,应使用互斥或状态检查防止同一实例重复执行;多副本部署还需要分布式协调。 - **记录并处理异常**:任务异常不能只依赖调度器日志。记录可定位的上下文,并让下次执行能够安全重试。 - **返回响应式链**:Spring Framework 6.1 起会自动订阅 `@Scheduled` 方法返回的 `Mono`、`Flux` 或其他 `Publisher`,并在插件应用上下文关闭时取消后续调度和活动订阅。优先直接返回响应式链,不要在方法中再次手动订阅;只有未作为返回值交给调度器的后台订阅才需要按[后台任务生命周期](https://docs.halo.run/developer-guide/plugin/basics/server/reactive-development.md#%E7%AE%A1%E7%90%86%E5%90%8E%E5%8F%B0%E4%BB%BB%E5%8A%A1)自行释放。 - **与 Reconciler 的分工**:如果是「让资源持续符合期望状态」的场景(如资源变更后重建索引),优先使用 [Reconciler](https://docs.halo.run/developer-guide/plugin/api-reference/server/reconciler.md) 的事件驱动调谐,而不是定时轮询;定时任务适合与资源变更无关的周期性工作,例如按时间触发的数据同步或清理。 --- url: https://docs.halo.run/developer-guide/plugin/basics/server/logging.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 日志 ## 使用 SLF4J 插件应通过 SLF4J 门面记录日志,不要引入自己的日志实现(如 Logback、Log4j2 的实现包),日志输出由 Halo 主程序统一管理: ```java import lombok.extern.slf4j.Slf4j; import org.springframework.stereotype.Component; @Slf4j @Component public class LinkService { public void sync() { log.info("Start syncing links"); try { // do something } catch (Exception e) { log.error("Failed to sync links", e); } } } ``` 不使用 Lombok 时可以手动创建: ```java private static final Logger log = LoggerFactory.getLogger(LinkService.class); ``` ## 日志级别约定 - `error`:功能执行失败,需要用户或管理员关注。 - `warn`:可恢复的异常或不符合预期的状态。 - `info`:关键业务节点(如任务开始/完成),不要在高频路径上使用。 - `debug`/`trace`:排查用的详细信息,默认级别下不输出。 ## 调整插件日志级别 Halo 使用 Spring Boot 的日志配置,插件的 logger 名称即类的全限定名,因此可以通过 Halo 的配置调整插件包的日志级别: ```yaml # Halo 的 application.yaml logging: level: com.example.myplugin: DEBUG ``` 使用 [DevTools](https://docs.halo.run/developer-guide/plugin/basics/devtools.md) 开发时,可以在 `workplace/config/application.yaml` 中做同样的配置,重启 `haloServer` 后生效。 生产环境中,日志随 Halo 进程输出:Docker 部署通过 `docker logs` 查看,1Panel 等面板部署可在面板的日志页面查看。 --- url: https://docs.halo.run/developer-guide/plugin/basics/ui/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # UI 基础 ## UI ### [介绍](/developer-guide/plugin/basics/ui/intro.md) - [Console 与 UC](/developer-guide/plugin/basics/ui/intro.md#console-与-uc) ### [入口文件](/developer-guide/plugin/basics/ui/entry.md) - [定义入口文件](/developer-guide/plugin/basics/ui/entry.md#定义入口文件) - [PluginModule 字段](/developer-guide/plugin/basics/ui/entry.md#pluginmodule-字段) ### [插件设置与表单组件](/developer-guide/plugin/basics/ui/forms.md) - [先选择正确的表单入口](/developer-guide/plugin/basics/ui/forms.md#先选择正确的表单入口) - [定义插件设置](/developer-guide/plugin/basics/ui/forms.md#定义插件设置) - [在 Vue 页面中使用 FormKit](/developer-guide/plugin/basics/ui/forms.md#在-vue-页面中使用-formkit) - [复用页面和列表组件](/developer-guide/plugin/basics/ui/forms.md#复用页面和列表组件) - [权限和验证](/developer-guide/plugin/basics/ui/forms.md#权限和验证) ### [构建](/developer-guide/plugin/basics/ui/build.md) - [原理](/developer-guide/plugin/basics/ui/build.md#原理) - [@halo-dev/ui-plugin-bundler-kit](/developer-guide/plugin/basics/ui/build.md#bundler-kit) - [输出格式与 Halo 目标](/developer-guide/plugin/basics/ui/build.md#output-format) - [共享运行时依赖](/developer-guide/plugin/basics/ui/build.md#shared-runtime-dependencies) - [加载和生命周期](/developer-guide/plugin/basics/ui/build.md#加载和生命周期) - [迁移旧版构建插件](/developer-guide/plugin/basics/ui/build.md#legacy-bundler-kit) - [构建输出](/developer-guide/plugin/basics/ui/build.md#构建输出) - [迁移](/developer-guide/plugin/basics/ui/build.md#migration) --- url: https://docs.halo.run/developer-guide/plugin/basics/ui/intro.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 介绍 Halo 插件体系的 UI 部分可以让开发者在 Console 控制台和 UC 个人中心添加新的页面或者扩展已有的功能。 ## Console 与 UC Halo 有两个可扩展的前端入口,两者的定位和可用扩展点不同: - **Console(控制台)**:面向站点管理员和贡献者的管理后台(`/console`),承担内容和系统管理工作。大多数插件 UI 属于这里,例如文章管理、插件自身的管理页面、仪表盘小部件等。 - **UC(个人中心)**:面向普通登录用户的自助空间(`/uc`),承载与用户本人相关的功能,例如个人资料、通知、以及内容投稿类插件的用户侧页面。 选择依据是功能的受众:管理性功能放 Console,与当前登录用户相关的自助功能放 UC。在入口文件中,`routes` 注册 Console 路由,`ucRoutes` 注册 UC 路由(详见[入口文件](https://docs.halo.run/developer-guide/plugin/basics/ui/entry.md));扩展点同理,名称中通常可以区分归属(如 `user:detail:tabs:create` 属于 Console,`uc:user:profile:tabs:create` 属于 UC)。 开始前应熟悉 Vue 3,并按照[准备工作](https://docs.halo.run/developer-guide/plugin/prepare.md)安装 Node.js 和 pnpm。具体版本以当前插件 `ui/package.json` 的 `engines` 和 `packageManager` 为准,不要在多个页面分别维护版本号。 --- url: https://docs.halo.run/developer-guide/plugin/basics/ui/entry.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 入口文件 入口文件用于定义 Halo 核心需要加载的 `PluginModule`,每个插件有且只有一个源码入口。使用 `@halo-dev/ui-plugin-bundler-kit` 构建时,IIFE 和 ESM 都会生成一个主入口;ESM 还可以包含异步 JavaScript、CSS 和其他静态资源分块。构建和打包方式请参考 [构建](https://docs.halo.run/developer-guide/plugin/basics/ui/build.md)。 为了方便开发者,我们已经在 [halo-dev/create-halo-plugin](https://github.com/halo-dev/create-halo-plugin) 配置好了基础项目结构,包括构建配置,后续文档也会以此为准。 ## 定义入口文件 ```ts title="ui/src/index.ts" import { definePlugin } from "@halo-dev/ui-shared"; export default definePlugin({ formkit: {}, components: {}, routes: [], ucRoutes: [], extensionPoints: {}, }); ``` ## PluginModule 字段 `definePlugin` 接收并返回一个 `PluginModule`。请直接使用 `@halo-dev/ui-shared` 提供的类型和 IDE 提示,不要把包内的完整类型定义复制到插件项目中;扩展点会随 Halo 版本演进,当前列表和参数类型请参考[扩展点和定制化](https://docs.halo.run/developer-guide/plugin/extension-points/ui/index.md)。 - `formkit`:FormKit 相关扩展定义。 - `inputs`:自定义 FormKit 输入组件定义,key 为在 FormKit Schema 中使用的 `$formkit` 类型名称,value 为 FormKit input definition。详细文档可参考 [FormKit 扩展](https://docs.halo.run/developer-guide/plugin/api-reference/ui/formkit.md)。 - `components`:组件列表,key 为组件名称,value 为组件对象,在此定义之后,加载插件时会自动注册到 Vue App 全局。 - `routes`:Console 控制台路由定义,详细文档可参考 [路由定义](https://docs.halo.run/developer-guide/plugin/api-reference/ui/route.md) - `ucRoutes`:UC 个人中心路由定义,详细文档可参考 [路由定义](https://docs.halo.run/developer-guide/plugin/api-reference/ui/route.md) - `extensionPoints`:扩展点定义,详细文档可参考 [扩展点](https://docs.halo.run/developer-guide/plugin/extension-points/ui/index.md) --- url: https://docs.halo.run/developer-guide/plugin/basics/ui/forms.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 插件设置与表单组件 Halo 已经在 Console 和用户中心注册了 FormKit,并通过 `@halo-dev/components` 提供页面、列表、弹窗和反馈组件。插件应复用宿主能力,使交互、校验、权限和视觉样式与 Halo 保持一致。 Setting Schema 的字段、默认值、敏感数据边界以及 Halo 扩展输入组件统一参考[表单定义与组件速查](https://docs.halo.run/developer-guide/form-schema.md)。本页只说明如何在插件中关联设置,以及何时使用 Setting 或自定义 Vue 表单。 ## 先选择正确的表单入口 | 场景 | 推荐方式 | | ---------------- | --------------------------------------------------------------- | | 插件详情中的普通设置 | 在 Setting YAML 中定义 FormKit Schema,由 Halo 自动渲染 | | 创建、编辑资源的页面或弹窗 | 在 Vue SFC 中使用 `` 和 FormKit 输入组件 | | 搜索、筛选、列表和分页 | 使用 `SearchInput`、`FilterDropdown`、`VEntity`、`VPagination` 等宿主组件 | | 单个列表选择、文件控件等轻量交互 | 邻近 Halo 页面采用原生控件时可以保持一致 | 插件通过 `plugin.yaml` 的 `spec.settingName` 和 `spec.configMapName` 关联 Setting 后,Halo 会在插件详情页自动渲染设置表单。插件 UI 不需要再注册普通设置路由,也不需要自行读取或更新 ConfigMap。只有 Setting Schema 无法表达的独立业务流程,才应创建自定义设置页面。 ## 定义插件设置 在 `src/main/resources/plugin.yaml` 中声明 Setting 名称和用于保存配置的 ConfigMap 名称: ```yaml title="src/main/resources/plugin.yaml" apiVersion: plugin.halo.run/v1alpha1 kind: Plugin metadata: name: project-sync spec: displayName: 项目同步 settingName: project-sync-settings configMapName: project-sync-config ``` 然后在 `src/main/resources/extensions/settings.yaml` 中提供对应的 Setting 资源: ```yaml title="src/main/resources/extensions/settings.yaml" apiVersion: v1alpha1 kind: Setting metadata: name: project-sync-settings spec: forms: - group: sync label: 同步设置 formSchema: - $formkit: switch name: enabled label: 启用自动同步 value: false - $formkit: number name: interval label: 同步间隔(分钟) value: 30 validation: required|min:5 ``` `spec.settingName` 必须与 Setting 的 `metadata.name` 一致。`spec.configMapName` 应使用插件专属的稳定名称,并在后续版本中保持不变。插件安装或启动后,Halo 会加载 Setting,在插件详情页渲染表单,并将每个 `group` 的值保存到对应 ConfigMap。 服务端应通过 [`ReactiveSettingFetcher`](https://docs.halo.run/developer-guide/plugin/api-reference/server/setting-fetcher.md) 读取配置,不要直接操作配置 ConfigMap。密码、Token、API Key 等敏感信息必须使用 [`secret`](https://docs.halo.run/developer-guide/form-schema.md#secret) 组件和 Halo Secret,不能直接保存在 Setting 中。 ## 在 Vue 页面中使用 FormKit FormKit 由 Halo 全局注册,插件不需要再次安装、初始化或自定义一套基础输入样式。页面和弹窗表单使用 Vue 3、` ``` 表单数据只在确实与 API 模型不同的情况下定义单独类型。插件 API 的资源模型、列表结果和请求参数应使用[生成的 API Client](https://docs.halo.run/developer-guide/plugin/basics/devtools.md#how-to-generate-api-client),不要再手写一份同名类型。 Halo 还提供附件、文章、单页面、分类、标签、菜单、图标和 Secret 等 FormKit 输入组件。可用类型及引入版本参考[表单定义与组件速查](https://docs.halo.run/developer-guide/form-schema.md)。需要注册插件自定义输入时,再参考 [FormKit 扩展](https://docs.halo.run/developer-guide/plugin/api-reference/ui/formkit.md)。 ## 复用页面和列表组件 插件 UI 应先在目标版本的 Halo Core 或当前官方插件中查找相同页面类型,再选择组件: - 普通管理页使用 `VPageHeader` 和 `VCard`。 - 资源列表使用 `VEntityContainer`、`VEntity`、`VEntityField`、`VEmpty` 和 `VLoading`。 - 关键词搜索使用 [`SearchInput`](https://docs.halo.run/developer-guide/plugin/api-reference/ui/components/search-input.md)。 - 确认和删除操作使用 `Dialog`,操作结果使用 `Toast`。 - 创建和编辑弹窗使用 `VModal` 与 FormKit。 组件需要从 `@halo-dev/components` 导入时,应使用包的公开导出,不要复制 Halo 内部组件源码或重新实现按钮、输入框、弹窗、提示和颜色体系。 ## 权限和验证 - 路由、菜单和按钮的权限应与后端 API 和 RoleTemplate 保持一致,UI 隐藏不能代替后端鉴权。 - 使用 FormKit 的 `required`、`url`、`min`、`max` 等规则提供即时校验,服务端仍必须验证所有不可信输入。 - 保存期间禁用重复提交,并使用宿主的 loading、Toast 和错误处理模式。 - 变更完成后检查桌面端和窄屏布局,以及 loading、空数据、错误和无权限状态。 --- url: https://docs.halo.run/developer-guide/plugin/basics/ui/build.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 构建 通过 [halo-dev/create-halo-plugin](https://github.com/halo-dev/create-halo-plugin) 创建的项目已经包含可用构建配置。没有特殊需求时沿用脚手架配置,不要重新实现 Halo 的输出协议。 | 任务 | 阅读位置 | | ---------------------------- | --------------------------------------- | | 在 Vite 或 Rsbuild 间选择 | [ui-plugin-bundler-kit](#bundler-kit) | | 配置图标组件 | [使用图标组件](#使用图标组件) | | 确认 ESM、IIFE 与最低 Halo 版本 | [输出格式与 Halo 目标](#output-format) | | 使用 Halo 提供的 Vue、Axios 和 UI 包 | [共享运行时依赖](#shared-runtime-dependencies) | | 从旧版 plugin-starter 迁移 | [迁移旧版构建插件](#legacy-bundler-kit) | ## 原理 Halo 插件的 UI 部分(Console / UC)以 `index.ts` 为源码入口,默认导出一个包含组件、路由和扩展点等内容的 `PluginModule`。Halo 2.x 支持两种构建和加载格式: - **ESM**:从 Halo 2.26.0 开始支持。每个插件独立加载入口、样式和异步分块,可以使用标准的动态 `import()` 和独立缓存。 - **IIFE**:旧版兼容格式。Halo 会将插件和当前主题的 `main.js`、`style.css` 汇总后加载,现有产物在 Halo 2.x 中无需重新构建。 在 [halo-dev/create-halo-plugin](https://github.com/halo-dev/create-halo-plugin) 创建的项目中,`@halo-dev/ui-plugin-bundler-kit` 提供了 [Vite](https://vite.dev/) 和 [Rsbuild](https://rsbuild.dev/) 的预配置。它会根据插件清单选择输出格式、生成 Halo 所需的元数据,并将共享依赖和资源路径配置为与 Halo 运行时兼容的形式,因此不建议自行实现这部分构建协议。 ## @halo-dev/ui-plugin-bundler-kit \{#bundler-kit} 这个库提供两个构建工具预配置: 1. `viteConfig`: Vite 的预配置 2. `rsbuildConfig`: Rsbuild 的预配置 从 2.26.0 开始,`viteConfig` 和 `rsbuildConfig` 分别通过 `/vite` 和 `/rsbuild` 专用入口导出。2.27.0 移除了包根入口及 `HaloUIPluginBundlerKit`,已有项目请参考[迁移说明](#migration)。 从 2.27.0 开始,Vite、Rsbuild 及各自的 Vue 插件均为可选 peer 依赖。只需显式安装所选构建工具及其 Vue 插件,无需安装另一套工具链。以下安装示例使用 2.27.0。 ### viteConfig #### 使用 如果你在通过 [halo-dev/create-halo-plugin](https://github.com/halo-dev/create-halo-plugin) 创建项目时没有选择使用 Vite 作为 UI 的构建工具,那么可以通过以下方式改为使用 Vite。 安装依赖: ```bash pnpm install @halo-dev/ui-plugin-bundler-kit@2.27.0 vite @vitejs/plugin-vue -D ``` 创建 vite.config.ts: ```ts import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit/vite"; export default viteConfig(); ``` 更新 package.json: ```json { "type": "module", "scripts": { "dev": "vite build --watch --mode=development", "build": "vite build" } } ``` #### 配置 ```ts import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit/vite"; export default viteConfig({ vite: { // 自定义 Vite 配置 plugins: [ // 额外的插件(Vue 插件已预配置) ], // 其他配置... }, }); ``` 示例: 1. 添加路径别名 ```ts import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit/vite"; import path from "path"; export default viteConfig({ vite: { resolve: { alias: { "@": path.resolve(__dirname, "src"), "@components": path.resolve(__dirname, "src/components"), }, }, }, }); ``` 2. 添加额外的 Vite 插件 ```ts import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit/vite"; import { defineConfig } from "vite"; import UnoCSS from "unocss/vite"; export default viteConfig({ vite: { plugins: [ UnoCSS(), // 添加 UnoCSS 插件 ], }, }); ``` ### rsbuildConfig Rsbuild 是基于 Rspack 开发的上层构建工具,其优势在于兼容 Webpack 生态并且性能优异。 #### 使用 如果你在通过 [halo-dev/create-halo-plugin](https://github.com/halo-dev/create-halo-plugin) 创建项目时没有选择使用 Rsbuild 作为 UI 的构建工具,那么可以通过以下方式改为使用 Rsbuild。 安装依赖: ```bash pnpm install @halo-dev/ui-plugin-bundler-kit@2.27.0 @rsbuild/core @rsbuild/plugin-vue -D ``` 创建 rsbuild.config.ts: ```ts import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit/rsbuild"; export default rsbuildConfig(); ``` 更新 package.json: ```json { "type": "module", "scripts": { "dev": "rsbuild build --env-mode development --watch", "build": "rsbuild build" } } ``` #### 配置 ```ts import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit/rsbuild"; export default rsbuildConfig({ rsbuild: { // 自定义 Rsbuild 配置 plugins: [ // 额外的插件(Vue 插件已预配置) ], // 其他配置... }, }); ``` 示例: 1. 添加路径别名 ```ts import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit/rsbuild"; export default rsbuildConfig({ rsbuild: { source: { alias: { "@": "./src", "@components": "./src/components", }, }, }, }); ``` 2. 添加额外的 Rsbuild 插件 ```ts import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit/rsbuild"; import { pluginSass } from "@rsbuild/plugin-sass"; export default rsbuildConfig({ rsbuild: { plugins: [ pluginSass(), // 添加 Sass 插件 ], }, }); ``` ### 配置内置的 Vue 编译器 `viteConfig` 和 `rsbuildConfig` 已经分别创建了一个 Vue 插件实例。需要修改 Vue 模板编译选项时,应使用顶层的 `vue` 字段,不要在内部的 `plugins` 数组中再次添加 `@vitejs/plugin-vue` 或 `@rsbuild/plugin-vue`。 Vite: ```ts export default viteConfig({ vue: { template: { compilerOptions: { isCustomElement: (tag) => tag === "halo-app-card", }, }, }, vite: {}, }); ``` Rsbuild: ```ts export default rsbuildConfig({ vue: { vueLoaderOptions: { compilerOptions: { isCustomElement: (tag) => tag === "halo-app-card", }, }, }, rsbuild: {}, }); ``` ### 使用图标组件 官方脚手架使用 `unplugin-icons`,现有项目应继续把它挂载到 `viteConfig` 或 `rsbuildConfig` 的扩展配置中,不要改用原始的 `defineConfig` 绕过 Halo preset。 Vite: ```ts import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit/vite"; import Icons from "unplugin-icons/vite"; export default viteConfig({ vite: { plugins: [Icons({ compiler: "vue3" })], }, }); ``` Rsbuild: ```ts import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit/rsbuild"; import Icons from "unplugin-icons/rspack"; export default rsbuildConfig({ rsbuild: { tools: { rspack: { plugins: [Icons({ compiler: "vue3" })], }, }, }, }); ``` 未安装时添加 `unplugin-icons` 开发依赖,并在 `env.d.ts` 中声明 Vue 类型: ```ts /// ``` 之后可以通过虚拟模块导入图标组件: ```ts import RiBookReadLine from "~icons/ri/book-read-line"; ``` ## 输出格式与 Halo 目标\{#output-format} `viteConfig` 和 `rsbuildConfig` 使用相同的格式选项: ```ts export default viteConfig({ format: "auto", // "auto" | "iife" | "esm" vite: {}, }); ``` `auto` 是默认值。构建工具只会从以下两种 `spec.requires` 写法推导 ESM 目标: - 稳定版本,例如 `2.26.0`。 - 简单的最低版本,例如 `>=2.26.0`。 推导出的最低版本为 2.26.0 或更高版本时输出 ESM,低于 2.26.0 时输出 IIFE。通配符、组合范围或其他无法直接推导最低稳定版本的写法会产生警告并回退到 IIFE,例如 `^2.26.0`、`>=2.26.0 <3.0.0`。这些写法仍可能是有效的 Halo 版本范围,只是不能用于自动选择 ESM。 如果需要暂时保留旧格式,可以显式设置: ```ts export default viteConfig({ format: "iife", vite: {}, }); ``` 只有在无法从 `spec.requires` 推导目标且确实需要 ESM 时,才设置 `targetHaloVersion`: ```ts export default viteConfig({ format: "esm", targetHaloVersion: "2.26.0", vite: {}, }); ``` `targetHaloVersion` 只用于选择构建时的 Halo 共享运行时快照,不会改变插件的安装兼容范围。发布 ESM 产物时,仍应确保 `plugin.yaml` 的 `spec.requires` 不允许安装到不支持 ESM 的 Halo 版本。 ### ESM 构建产物 成功的 ESM 构建会额外生成保留文件 `ui-plugin.json`,并可能包含异步 JavaScript、CSS 和其他静态资源。以下目录仅作示意,实际入口和启动样式路径以 `ui-plugin.json` 为准: ```tree build/dist/ ├── ui-plugin.json ├── main..js # 默认 ESM 入口 ├── style..css # 可选,路径由构建工具决定 ├── chunks/ # 可选的异步 JavaScript / CSS 分块 └── assets/ # 可选的图片、字体等资源 ``` `ui-plugin.json` 由 bundler kit 生成,请勿手动创建、复制或覆盖。打包插件时需要保留完整输出目录,不能只复制清单中记录的入口和启动样式。没有该文件的产物会继续按旧版 IIFE 格式加载,即使 `spec.requires` 已经包含 Halo 2.26.0。 默认的 ESM preset 会配置模块输出、共享依赖、相对资源路径,并为入口、启动样式和异步资源使用内容哈希文件名。原生 Vite / Rsbuild 配置会在这些默认值之后合并,bundler kit 不会检查、拒绝或重写冲突的覆盖项。如果自定义配置修改了输出格式、入口、资源路径、externals 或文件名,开发者需要自行保证清单一致性、Import Map 兼容性、共享依赖身份、资源迁移和缓存安全。旧项目暂时无法满足这些要求时,可以显式选择 `format: "iife"`。 ## 共享运行时依赖\{#shared-runtime-dependencies} ESM 插件可以从 Halo 运行时导入以下包根路径: - `vue` - `vue-router` - `pinia` - `axios` - `@formkit/vue` - `@formkit/core` - `@halo-dev/ui-shared` - `@halo-dev/components` - `@halo-dev/api-client` - `@halo-dev/richtext-editor` bundler kit 会发现对共享包根路径的导入,并在能够读取包元数据时,对比插件安装的版本与目标 Halo 快照中的版本。插件版本更新或主版本不同时会产生尽力而为的兼容性提示,但版本差异不会导致构建失败。bundler kit 不检查静态导出、别名、fork 或构建工具最终解析到的包;从共享包进行深层导入仍会失败,因为 Halo 的 Import Map 只公开上述包根路径。默认 preset 会将未列出的依赖打入插件产物;如果通过自定义配置修改 externals 或依赖解析,开发者需要自行保证浏览器能够解析最终产物。 `axios` 是 Halo 提供的标准共享模块,请勿修改它的全局 defaults 或 interceptors;需要隔离配置时使用 `axios.create()`。`@halo-dev/api-client` 导出的 `axiosInstance` 是另一个带 Halo 认证和错误处理的实例,详细说明请参考 [API 请求](https://docs.halo.run/developer-guide/plugin/api-reference/ui/api-request.md)。 ## 加载和生命周期 ESM 入口仍需默认导出已有的 `PluginModule`,不应通过顶层副作用自行注册路由或组件。Halo 会并行加载各 provider 的启动样式、ESM 入口和旧版 IIFE bundle,再按照稳定的 provider 顺序注册成功加载的模块。插件不能依赖其他 provider 的求值或注册顺序,也不支持直接导入其他 provider 的实现。 单个 provider 的入口、样式或注册失败时,Halo 会跳过该 provider,并继续启动核心 UI 和其他 provider。入口求值产生的定时器、事件监听器等任意副作用无法保证回滚,因此插件安装、升级、启用、禁用或重新加载后,完整刷新 Console 或 UC 页面是受支持的模块替换和恢复边界。 ## 迁移旧版构建插件 \{#legacy-bundler-kit} 旧版本 [plugin-starter](https://github.com/halo-dev/plugin-starter) 使用的 `HaloUIPluginBundlerKit` 已在 2.27.0 中移除。升级前请按[迁移步骤](#migration)改用 `viteConfig` 或 `rsbuildConfig`。此变更不影响已有 IIFE 产物在 Halo 2.x 中的兼容性。 ## 构建输出 在 `viteConfig` 和 `rsbuildConfig` 中,已经配置好了开发环境和生产构建的输出目录,分别是: - **开发环境**:目标 Halo 为 2.25.0 或更高版本时输出到 `build/resources/main/ui`;旧目标继续输出到 `build/resources/main/console`。在开发 UI 的过程中,可以使用 `pnpm dev` 实时构建 - **生产环境**:`ui/build/dist` > 生产目录是临时构建产物。使用 Gradle 构建插件时,应将完整目录复制到 `build/resources/main/ui`,并随插件 JAR 一起打包。`console` 目录仍作为旧项目的兼容回退。发布前应按[插件发布验收清单](https://docs.halo.run/developer-guide/plugin/release-checklist.md#%E6%A3%80%E6%9F%A5-jar-%E5%86%85%E5%AE%B9)检查最终 JAR。 ## 迁移\{#migration} ### 从包根入口迁移 如果已经使用 `viteConfig` 或 `rsbuildConfig`,只需修改导入路径,并按上文安装所选构建工具及其 Vue 插件。现有配置参数和 Gradle 打包配置无需因此修改。 ```ts // Vite 项目 import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit/vite"; ``` ```ts // Rsbuild 项目 import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit/rsbuild"; ``` ### 从 HaloUIPluginBundlerKit 迁移 如果当前插件使用旧版本 [plugin-starter](https://github.com/halo-dev/plugin-starter) 中的 `HaloUIPluginBundlerKit`,可以参考以下步骤迁移到 Vite 预配置: ### 更新 `@halo-dev/ui-plugin-bundler-kit` 更新至 `2.27.0` 或更高版本: ```bash pnpm install @halo-dev/ui-plugin-bundler-kit@2.27.0 vite @vitejs/plugin-vue -D ``` ### 更新 `vite.config.ts` ```typescript import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit/vite"; export default viteConfig({ vite: { // Vite 配置需要按照原有的配置进行修改,但需要移除 Vue 插件,因为已经内置 plugins: [], }, }); ``` ### 更新项目根目录的 `build.gradle` ```groovy plugins { id 'java' id "io.freefair.lombok" version "8.13" id "run.halo.plugin.devtools" version "0.9.0" } group 'com.example.starter' repositories { mavenCentral() } dependencies { implementation platform('run.halo.tools.platform:plugin:2.26.0') compileOnly 'run.halo.app:api' testImplementation 'run.halo.app:api' testImplementation 'org.springframework.boot:spring-boot-starter-test' testRuntimeOnly 'org.junit.platform:junit-platform-launcher' } test { useJUnitPlatform() } java { toolchain { languageVersion = JavaLanguageVersion.of(21) } } tasks.withType(JavaCompile).configureEach { options.encoding = "UTF-8" options.release = 21 } tasks.register('processUiResources', Copy) { from project(':ui').layout.buildDirectory.dir('dist') into layout.buildDirectory.dir('resources/main/ui') dependsOn project(':ui').tasks.named('assemble') shouldRunAfter tasks.named('processResources') } tasks.named('classes') { dependsOn tasks.named('processUiResources') } halo { version = '2.26' } ``` ### 新建 UI 构建配置 在 ui 或者 console 目录新建 `build.gradle` 文件,内容如下: ```groovy plugins { id 'base' id "com.github.node-gradle.node" version "7.1.0" } group 'com.example.starter.ui' tasks.register('buildFrontend', PnpmTask) { group = 'build' description = 'Builds the UI project using pnpm.' args = ['build'] dependsOn tasks.named('pnpmInstall') inputs.dir(layout.projectDirectory.dir('src')) inputs.files(fileTree( dir: layout.projectDirectory, includes: ['*.cjs', '*.ts', '*.js', '*.json', '*.yaml'])) outputs.dir(layout.buildDirectory.dir('dist')) } tasks.register('pnpmCheck', PnpmTask) { group = 'verification' description = 'Runs unit tests using pnpm.' args = ['test:unit'] dependsOn tasks.named('pnpmInstall') } tasks.named('check') { dependsOn tasks.named('pnpmCheck') } tasks.named('assemble') { dependsOn tasks.named('buildFrontend') } ``` 进行此变更的主要目的是保证 UI 构建产物不直接输出到源码目录,而是通过 Gradle 复制到 `build/resources/main/ui` 并打包到插件 JAR 中。 如果你不想使用新的 Gradle 构建配置,也可以让 viteConfig 或 rsbuildConfig 直接输出到源码资源目录: viteConfig: ```ts import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit/vite"; const OUT_DIR_PROD = "../src/main/resources/ui"; const OUT_DIR_DEV = "../build/resources/main/ui"; export default viteConfig({ vite: ({ mode }) => { const isProduction = mode === "production"; const outDir = isProduction ? OUT_DIR_PROD : OUT_DIR_DEV; return { build: { outDir, }, }; }, }); ``` rsbuildConfig: ```ts import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit/rsbuild"; const OUT_DIR_PROD = "../src/main/resources/ui"; const OUT_DIR_DEV = "../build/resources/main/ui"; export default rsbuildConfig({ rsbuild: ({ envMode }) => { const isProduction = envMode === "production"; const outDir = isProduction ? OUT_DIR_PROD : OUT_DIR_DEV; return { output: { distPath: { root: outDir, }, }, }; }, }); ``` --- url: https://docs.halo.run/developer-guide/plugin/api-reference/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # API 参考 ## 服务端 ### [自定义模型](/developer-guide/plugin/api-reference/server/extension.md) - [定义模型](/developer-guide/plugin/api-reference/server/extension.md#person-extension-example) - [注册模型](/developer-guide/plugin/api-reference/server/extension.md#create-extension) - [声明预置对象](/developer-guide/plugin/api-reference/server/extension.md#declare-extension-object) - [校验对象](/developer-guide/plugin/api-reference/server/extension.md#validate-extension-object) - [配置索引](/developer-guide/plugin/api-reference/server/extension.md#using-indexes) - [元数据命名](/developer-guide/plugin/api-reference/server/extension.md#元数据命名) - [使用自动生成的 API](/developer-guide/plugin/api-reference/server/extension.md#extension-apis) - [自定义 API](/developer-guide/plugin/api-reference/server/extension.md#custom-api-group-spec) - [源码参考](/developer-guide/plugin/api-reference/server/extension.md#源码参考) ### [自定义 API](/developer-guide/plugin/api-reference/server/custom-endpoints.md) - [选择 API Group](/developer-guide/plugin/api-reference/server/custom-endpoints.md#custom-api-group-spec) - [使用 CustomEndpoint](/developer-guide/plugin/api-reference/server/custom-endpoints.md#使用-customendpoint) - [使用带注解的控制器](/developer-guide/plugin/api-reference/server/custom-endpoints.md#使用带注解的控制器) - [处理列表参数](/developer-guide/plugin/api-reference/server/custom-endpoints.md#处理列表参数) - [校验请求体](/developer-guide/plugin/api-reference/server/custom-endpoints.md#using-java-bean-validation) - [生成 OpenAPI 文档](/developer-guide/plugin/api-reference/server/custom-endpoints.md#生成-openapi-文档) - [源码参考](/developer-guide/plugin/api-reference/server/custom-endpoints.md#源码参考) ### [编写控制器](/developer-guide/plugin/api-reference/server/reconciler.md) - [编写 Reconciler](/developer-guide/plugin/api-reference/server/reconciler.md#编写-reconciler) - [控制器示例](/developer-guide/plugin/api-reference/server/reconciler.md#控制器示例) ### [与自定义模型交互](/developer-guide/plugin/api-reference/server/extension-client.md) ### [获取插件配置](/developer-guide/plugin/api-reference/server/setting-fetcher.md) - [概述](/developer-guide/plugin/api-reference/server/setting-fetcher.md#概述) - [监听配置变更](/developer-guide/plugin/api-reference/server/setting-fetcher.md#监听配置变更) - [使用示例](/developer-guide/plugin/api-reference/server/setting-fetcher.md#使用示例) ### [静态资源代理](/developer-guide/plugin/api-reference/server/reverseproxy.md) ### [发送和订阅通知](/developer-guide/plugin/api-reference/server/notification.md) - [通知系统工作流程](/developer-guide/plugin/api-reference/server/notification.md#通知系统工作流程) - [通知事件](/developer-guide/plugin/api-reference/server/notification.md#通知事件) - [通知模板](/developer-guide/plugin/api-reference/server/notification.md#通知模板) - [触发通知事件](/developer-guide/plugin/api-reference/server/notification.md#触发通知事件) - [订阅通知](/developer-guide/plugin/api-reference/server/notification.md#订阅通知) - [通知器](/developer-guide/plugin/api-reference/server/notification.md#通知器) ### [为主题提供数据](/developer-guide/plugin/api-reference/server/finder-for-theme.md) - [创建一个 Finder](/developer-guide/plugin/api-reference/server/finder-for-theme.md#创建一个-finder) - [Finder 命名](/developer-guide/plugin/api-reference/server/finder-for-theme.md#finder-命名) - [使用 Finder](/developer-guide/plugin/api-reference/server/finder-for-theme.md#使用-finder) ### [在插件中提供主题模板](/developer-guide/plugin/api-reference/server/template-for-theme.md) - [创建一个模板](/developer-guide/plugin/api-reference/server/template-for-theme.md#创建一个模板) - [复用当前主题页面布局](/developer-guide/plugin/api-reference/server/template-for-theme.md#复用当前主题页面布局) - [模板片段](/developer-guide/plugin/api-reference/server/template-for-theme.md#模板片段) ### [实现 WebSocket](/developer-guide/plugin/api-reference/server/websocket.md) ### [登录增强](/developer-guide/plugin/api-reference/server/login-handler-enhancer.md) - [背景](/developer-guide/plugin/api-reference/server/login-handler-enhancer.md#背景) ### [获取扩展](/developer-guide/plugin/api-reference/server/extension-getter.md) ## UI ### [路由定义](/developer-guide/plugin/api-reference/ui/route.md) - [定义方式](/developer-guide/plugin/api-reference/ui/route.md#定义方式) - [类型定义](/developer-guide/plugin/api-reference/ui/route.md#类型定义) ### [API 请求](/developer-guide/plugin/api-reference/ui/api-request.md) - [选择客户端](/developer-guide/plugin/api-reference/ui/api-request.md#选择客户端) - [使用插件生成的 API Client](/developer-guide/plugin/api-reference/ui/api-request.md#使用插件生成的-api-client) - [使用 Halo API Client](/developer-guide/plugin/api-reference/ui/api-request.md#使用-halo-api-client) - [直接使用 axiosInstance](/developer-guide/plugin/api-reference/ui/api-request.md#直接使用-axiosinstance) ### [FormKit 扩展](/developer-guide/plugin/api-reference/ui/formkit.md) - [注册输入组件](/developer-guide/plugin/api-reference/ui/formkit.md#注册输入组件) - [在 FormKit Schema 中使用](/developer-guide/plugin/api-reference/ui/formkit.md#在-formkit-schema-中使用) - [注意事项](/developer-guide/plugin/api-reference/ui/formkit.md#注意事项) ### [共享工具库](/developer-guide/plugin/api-reference/ui/shared.md) - [stores](/developer-guide/plugin/api-reference/ui/shared.md#stores) - [utils](/developer-guide/plugin/api-reference/ui/shared.md#utils) - [events](/developer-guide/plugin/api-reference/ui/shared.md#events) ### [组件](/developer-guide/plugin/api-reference/ui/components/index.md) - [基础组件库](/developer-guide/plugin/api-reference/ui/components/index.md#基础组件库) - [业务组件和指令](/developer-guide/plugin/api-reference/ui/components/index.md#业务组件和指令) --- url: https://docs.halo.run/developer-guide/plugin/api-reference/server/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 服务端 API 参考 ## 服务端 ### [自定义模型](/developer-guide/plugin/api-reference/server/extension.md) - [定义模型](/developer-guide/plugin/api-reference/server/extension.md#person-extension-example) - [注册模型](/developer-guide/plugin/api-reference/server/extension.md#create-extension) - [声明预置对象](/developer-guide/plugin/api-reference/server/extension.md#declare-extension-object) - [校验对象](/developer-guide/plugin/api-reference/server/extension.md#validate-extension-object) - [配置索引](/developer-guide/plugin/api-reference/server/extension.md#using-indexes) - [元数据命名](/developer-guide/plugin/api-reference/server/extension.md#元数据命名) - [使用自动生成的 API](/developer-guide/plugin/api-reference/server/extension.md#extension-apis) - [自定义 API](/developer-guide/plugin/api-reference/server/extension.md#custom-api-group-spec) - [源码参考](/developer-guide/plugin/api-reference/server/extension.md#源码参考) ### [自定义 API](/developer-guide/plugin/api-reference/server/custom-endpoints.md) - [选择 API Group](/developer-guide/plugin/api-reference/server/custom-endpoints.md#custom-api-group-spec) - [使用 CustomEndpoint](/developer-guide/plugin/api-reference/server/custom-endpoints.md#使用-customendpoint) - [使用带注解的控制器](/developer-guide/plugin/api-reference/server/custom-endpoints.md#使用带注解的控制器) - [处理列表参数](/developer-guide/plugin/api-reference/server/custom-endpoints.md#处理列表参数) - [校验请求体](/developer-guide/plugin/api-reference/server/custom-endpoints.md#using-java-bean-validation) - [生成 OpenAPI 文档](/developer-guide/plugin/api-reference/server/custom-endpoints.md#生成-openapi-文档) - [源码参考](/developer-guide/plugin/api-reference/server/custom-endpoints.md#源码参考) ### [编写控制器](/developer-guide/plugin/api-reference/server/reconciler.md) - [编写 Reconciler](/developer-guide/plugin/api-reference/server/reconciler.md#编写-reconciler) - [控制器示例](/developer-guide/plugin/api-reference/server/reconciler.md#控制器示例) ### [与自定义模型交互](/developer-guide/plugin/api-reference/server/extension-client.md) ### [获取插件配置](/developer-guide/plugin/api-reference/server/setting-fetcher.md) - [概述](/developer-guide/plugin/api-reference/server/setting-fetcher.md#概述) - [监听配置变更](/developer-guide/plugin/api-reference/server/setting-fetcher.md#监听配置变更) - [使用示例](/developer-guide/plugin/api-reference/server/setting-fetcher.md#使用示例) ### [静态资源代理](/developer-guide/plugin/api-reference/server/reverseproxy.md) ### [发送和订阅通知](/developer-guide/plugin/api-reference/server/notification.md) - [通知系统工作流程](/developer-guide/plugin/api-reference/server/notification.md#通知系统工作流程) - [通知事件](/developer-guide/plugin/api-reference/server/notification.md#通知事件) - [通知模板](/developer-guide/plugin/api-reference/server/notification.md#通知模板) - [触发通知事件](/developer-guide/plugin/api-reference/server/notification.md#触发通知事件) - [订阅通知](/developer-guide/plugin/api-reference/server/notification.md#订阅通知) - [通知器](/developer-guide/plugin/api-reference/server/notification.md#通知器) ### [为主题提供数据](/developer-guide/plugin/api-reference/server/finder-for-theme.md) - [创建一个 Finder](/developer-guide/plugin/api-reference/server/finder-for-theme.md#创建一个-finder) - [Finder 命名](/developer-guide/plugin/api-reference/server/finder-for-theme.md#finder-命名) - [使用 Finder](/developer-guide/plugin/api-reference/server/finder-for-theme.md#使用-finder) ### [在插件中提供主题模板](/developer-guide/plugin/api-reference/server/template-for-theme.md) - [创建一个模板](/developer-guide/plugin/api-reference/server/template-for-theme.md#创建一个模板) - [复用当前主题页面布局](/developer-guide/plugin/api-reference/server/template-for-theme.md#复用当前主题页面布局) - [模板片段](/developer-guide/plugin/api-reference/server/template-for-theme.md#模板片段) ### [实现 WebSocket](/developer-guide/plugin/api-reference/server/websocket.md) ### [登录增强](/developer-guide/plugin/api-reference/server/login-handler-enhancer.md) - [背景](/developer-guide/plugin/api-reference/server/login-handler-enhancer.md#背景) ### [获取扩展](/developer-guide/plugin/api-reference/server/extension-getter.md) --- url: https://docs.halo.run/developer-guide/plugin/api-reference/server/extension.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 自定义模型 Halo 自定义模型参考 Kubernetes 自定义资源设计,用于存储插件业务数据,并自动获得 CRUD API、权限和查询能力。本文描述模型本身;需要编写额外业务接口时参考[自定义 API](https://docs.halo.run/developer-guide/plugin/api-reference/server/custom-endpoints.md)。 ## 定义模型 \{#person-extension-example} 自定义模型继承 `AbstractExtension`,并通过 `@GVK` 声明 API group、version、kind 和资源名称: ```java import io.swagger.v3.oas.annotations.media.Schema; import lombok.Data; import lombok.EqualsAndHashCode; import run.halo.app.extension.AbstractExtension; import run.halo.app.extension.GVK; @Data @EqualsAndHashCode(callSuper = true) @GVK(group = "my-plugin.halo.run", version = "v1alpha1", kind = "Person", plural = "persons", singular = "person") public class Person extends AbstractExtension { @Schema(requiredMode = Schema.RequiredMode.REQUIRED) private Spec spec; @Data @Schema(name = "PersonSpec") public static class Spec { @Schema(maxLength = 100) private String name; @Schema(minimum = "0", maximum = "150") private Integer age; } } ``` - `group` 应使用插件或组织控制的域名形式,避免与其他插件冲突。 - `version` 与 group 组成 `apiVersion`。 - `kind` 是资源类型名。 - `plural` 和 `singular` 必须小写,并用于 API 路径。 `apiVersion`、`kind` 和 `metadata` 已由 `AbstractExtension` 提供。插件通常定义 `spec` 表示期望状态,并在需要时定义 `status` 表示控制器维护的实际状态。 ## 注册模型 \{#create-extension} 在插件启动时注册 Scheme,并在停止时对称注销: ```java @Override public void start() { schemeManager.register(Person.class); } @Override public void stop() { schemeManager.unregister(Scheme.buildFromType(Person.class)); } ``` 注册 Scheme 不会自动实现业务状态维护。需要响应资源变化时,另行注册[自定义模型控制器](https://docs.halo.run/developer-guide/core/framework.md#controller)。 ## 声明预置对象 \{#declare-extension-object} 插件可以在 `src/main/resources/extensions` 中提供 YAML 对象。插件启动后,Halo 会按 `apiVersion`、`kind` 和 `metadata.name` 创建或更新资源: ```yaml apiVersion: my-plugin.halo.run/v1alpha1 kind: Person metadata: name: halo spec: name: Halo age: 18 ``` 文件名可以自定义,也可以使用 `---` 在同一文件中声明多个对象。 默认情况下,同名对象会在插件再次启动时更新。需要保留用户修改时,可以添加: ```yaml metadata: labels: halo.run/do-not-overwrite: "true" ``` 带该标签的预置资源不会被启动流程覆盖,也不会在插件停止时按普通预置资源清理。完整边界见[插件生命周期](https://docs.halo.run/developer-guide/plugin/basics/server/lifecycle.md#%E6%8F%92%E4%BB%B6%E5%81%9C%E6%AD%A2)。 ## 校验对象 \{#validate-extension-object} Halo 根据模型生成 OpenAPI Schema,并在写入对象时校验结构和约束。使用 `@Schema` 声明必填、长度和数值范围等约束: ```java @Schema(requiredMode = Schema.RequiredMode.REQUIRED, maxLength = 100) private String name; @Schema(minimum = "0", maximum = "150") private Integer age; ``` `description` 和 `example` 主要用于 API 文档;是否形成运行时约束取决于对应 OpenAPI Schema 关键字。 ## 配置索引 \{#using-indexes} 查询或排序的字段必须注册为索引。Halo 2.22.0 起应使用 `IndexSpecs.single()` 或 `IndexSpecs.multi()`: ```java @Override public void start() { schemeManager.register(Person.class, indexSpecs -> indexSpecs.add(IndexSpecs .single("spec.name", String.class) .indexFunc(person -> person.getSpec().getName())) ); } ``` - 单值索引可以返回 `null`。 - 多值索引返回 `Set`。 - `keyType` 必须实现 `Comparable`。 - 同一模型中的索引名称必须唯一。 Halo 已为以下字段建立索引,不要重复声明: - `metadata.name`,唯一索引 - `metadata.labels` - `metadata.creationTimestamp` - `metadata.deletionTimestamp` 索引会增加写入和存储成本,只为实际查询或排序的字段创建。 ## 元数据命名 ### metadata.name \{#naming-spec-for-metadata-name} `metadata.name` 是同一资源类型中的唯一标识: - 不超过 253 个字符。 - 只能包含小写字母、数字和 `-`。 - 以字母或数字开头和结尾。 ### labels \{#naming-spec-for-labels} labels 用于标识和查询对象,因此会自动建立索引。插件应使用自己控制的 DNS 子域名前缀,例如 `example.com/category`,不能使用 Halo 保留的 `halo.run` 等前缀。 名称部分最多 63 个字符,可包含字母、数字、`-`、`.` 和 `_`,并以字母或数字开头和结尾。不要在 labels 中存放凭据或个人敏感信息;不需要查询的数据应放在 annotations 中。 ### annotations \{#naming-spec-for-annotations} annotations 与 labels 使用相同的 `/` 键格式,但不会自动建立索引。它适合保存不参与查询的附加信息;仍然不能用于存放凭据或个人敏感信息。 ## 使用自动生成的 API \{#extension-apis} 注册模型后,Halo 自动提供以下资源 API: ```text GET /apis/// GET /apis////{name} POST /apis/// PUT /apis////{name} DELETE /apis////{name} ``` 列表 API 支持 `page`、`size`、`sort`、`labelSelector` 和 `fieldSelector`。排序与字段选择器只能使用已建立索引的字段: ```http GET /apis/my-plugin.halo.run/v1alpha1/persons?page=1&size=10&sort=metadata.name,desc&labelSelector=type=staff&fieldSelector=metadata.name=halo ``` 该请求查询 label `type=staff` 且名称为 `halo` 的对象,并按 `metadata.name` 降序返回第一页。 ### 标签选择器 \{#label-selector-query-params} - `labelSelector=type=staff`:值等于 `staff` - `labelSelector=type!=staff`:值不等于 `staff` - `labelSelector=!type`:不存在 `type` - `labelSelector=type`:存在 `type` ### 字段选择器 \{#field-selector-query-params} - `fieldSelector=metadata.name=halo`:值等于 `halo` - `fieldSelector=metadata.name!=halo`:值不等于 `halo` - `fieldSelector=metadata.name=(halo,halo2)`:值在集合中 服务端代码中的响应式查询方式见 [ReactiveExtensionClient](https://docs.halo.run/developer-guide/plugin/api-reference/server/extension-client.md#query)。 ## 自定义 API \{#custom-api-group-spec} 自动生成的 CRUD API 不能覆盖聚合查询或业务动作时,使用[自定义 API](https://docs.halo.run/developer-guide/plugin/api-reference/server/custom-endpoints.md#custom-api-group-spec)。原有 `custom-api-group-spec` 锚点保留在本节,已有链接无需修改。 ### 自定义 API 请求校验 \{#using-java-bean-validation} 自定义 API 的 Bean Validation 内容已移至[校验请求体](https://docs.halo.run/developer-guide/plugin/api-reference/server/custom-endpoints.md#using-java-bean-validation)。本节保留原有锚点,已有链接无需修改。 ## 源码参考 - [AbstractExtension](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/extension/AbstractExtension.java) - [GVK](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/extension/GVK.java) - [IndexSpecs](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/extension/index/IndexSpecs.java) --- url: https://docs.halo.run/developer-guide/plugin/api-reference/server/custom-endpoints.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 自定义 API 自动生成的自定义模型 CRUD API 不能满足聚合查询或业务动作时,可以定义响应式自定义 API。简单资源读写仍应优先使用[自定义模型 API](https://docs.halo.run/developer-guide/plugin/api-reference/server/extension.md#extension-apis)。 ## 选择 API Group \{#custom-api-group-spec} 自定义 API 的 group 决定主要使用范围和 OpenAPI 分组: | 使用范围 | group 示例 | | ---------- | -------------------------------- | | Console | `console.api.my-plugin.halo.run` | | UC 个人中心 | `uc.api.my-plugin.halo.run` | | 主题或其他公开调用方 | `api.my-plugin.halo.run` | 自定义 API 仍需配置最小权限。使用公开 group 不会自动允许匿名访问,权限规则见[角色模板](https://docs.halo.run/developer-guide/plugin/security/role-template.md)。 ## 使用 CustomEndpoint `CustomEndpoint` 从 Halo 2.0.0 开始提供,为 `RouterFunction` 自动添加 group 和 version 前缀: ```java import static org.springframework.http.MediaType.APPLICATION_JSON; import java.util.Map; import org.springframework.stereotype.Component; import org.springframework.web.reactive.function.server.RouterFunction; import org.springframework.web.reactive.function.server.RouterFunctions; import org.springframework.web.reactive.function.server.ServerRequest; import org.springframework.web.reactive.function.server.ServerResponse; import reactor.core.publisher.Mono; import run.halo.app.core.extension.endpoint.CustomEndpoint; import run.halo.app.extension.GroupVersion; @Component public class PersonEndpoint implements CustomEndpoint { @Override public RouterFunction endpoint() { return RouterFunctions.route() .GET("/persons/{name}", this::getPerson) .build(); } private Mono getPerson(ServerRequest request) { return ServerResponse.ok() .contentType(APPLICATION_JSON) .bodyValue(Map.of("name", request.pathVariable("name"))); } @Override public GroupVersion groupVersion() { return new GroupVersion("console.api.my-plugin.halo.run", "v1alpha1"); } } ``` 最终路径为 `/apis/console.api.my-plugin.halo.run/v1alpha1/persons/{name}`。保持资源型 API 路径不超过角色模板支持的层级;复杂筛选使用查询参数。 ## 使用带注解的控制器 `ApiVersion` 从 Halo 2.0.0 开始提供。需要注解风格时,可以使用 `@RestController`,并通过 `@ApiVersion` 添加 Halo API group 和 version 前缀。缺少该注解时,控制器仍可能按原始 `@RequestMapping` 路径注册,因此不能用省略注解的方式禁用 API: ```java @ApiVersion("console.api.my-plugin.halo.run/v1alpha1") @RequestMapping("/persons") @RestController public class PersonController { @GetMapping("/{name}") public Mono> get(@PathVariable String name) { return Mono.just(Map.of("name", name)); } } ``` Halo 基于 WebFlux;控制器不能返回阻塞调用。无法替换的阻塞工作应按[响应式服务端开发](https://docs.halo.run/developer-guide/plugin/basics/server/reactive-development.md)隔离。 ## 处理列表参数 需要支持分页、排序和选择器时,可以在 Halo 2.5.0 及以上版本继承 `SortableRequest`,复用 Halo 的查询参数解析: ```java public class PersonQuery extends SortableRequest { public PersonQuery(ServerWebExchange exchange) { super(exchange); } public String getKeyword() { return queryParams.getFirst("keyword"); } @Override public ListOptions toListOptions() { var builder = ListOptions.builder(super.toListOptions()); if (StringUtils.isNotBlank(getKeyword())) { builder.andQuery(contains("spec.name", getKeyword())); } return builder.build(); } } ``` `spec.name` 必须已经注册索引。查询与分页调用见 [ReactiveExtensionClient](https://docs.halo.run/developer-guide/plugin/api-reference/server/extension-client.md#query)。 ## 校验请求体 \{#using-java-bean-validation} 自定义 API 的输入属于信任边界。使用 Jakarta Bean Validation 或等价的显式校验,不要只依赖 OpenAPI 描述: ```java public class PersonParam { @NotBlank @Size(max = 100) private String name; @Min(0) @Max(150) private int age; } ``` WebFlux Functional Endpoint 不会仅凭字段上的约束注解自动执行校验。先在插件应用上下文中提供 Validator: ```java @Configuration public class PluginConfig { @Bean public LocalValidatorFactoryBean validator() { return new LocalValidatorFactoryBean(); } } ``` 然后在读取请求体后显式调用: ```java private final Validator validator; private Mono createPerson(ServerRequest request) { return request.bodyToMono(PersonParam.class) .doOnNext(this::validate) .flatMap(param -> ServerResponse.ok().bodyValue(param)); } private void validate(PersonParam param) { var errors = new BeanPropertyBindingResult(param, "person"); validator.validate(param, errors); if (errors.hasErrors()) { throw new ServerWebInputException(errors.toString()); } } ``` 这里的 `Validator` 为 `org.springframework.validation.Validator`。校验失败时返回可定位的 4xx 错误,不能把无效输入写入自定义模型。涉及当前用户语言时,在请求范围内设置 Locale,并在结束后恢复。 ## 生成 OpenAPI 文档 需要让 Functional Endpoint 出现在 Swagger 和生成的 API Client 中时,使用 `SpringdocRouteBuilder` 描述 operationId、tag、参数和响应。operationId 应稳定且唯一,tag 建议包含资源 Kind、版本和作用域。 OpenAPI 分组与 API group 对应。生成客户端的步骤见 [DevTools](https://docs.halo.run/developer-guide/plugin/basics/devtools.md#how-to-generate-api-client)。不要手动修改生成的 `api-client` 或 `api-docs`。 ## 源码参考 - [CustomEndpoint](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/core/extension/endpoint/CustomEndpoint.java) - [ApiVersion](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/plugin/ApiVersion.java) - [SortableRequest](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/extension/router/SortableRequest.java) --- url: https://docs.halo.run/developer-guide/plugin/api-reference/server/reconciler.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 编写控制器 控制器是 Halo 的关键组件,它们负责对每个自定义模型对象进行操作,协调所需状态和当前状态,参考: [控制器概述](https://docs.halo.run/developer-guide/core/framework.md#controller)。 控制器通常在具有一般事件序列的控制循环中运行: 1. 观察:每个控制器将被设计为观察一组自定义模型对象,例如文章的控制器会观察文章对象,插件的控制器会观察插件自定义模型对象等。 2. 比较:控制器将对象配置的期望状态与其当前状态进行比较,以确定是否需要更改,例如插件的 `spec.enabled` 为 `true`,而插件的当前状态是未启动,则插件控制器会处理启动插件的逻辑。 3. 操作:控制器将根据比较的结果执行相应的操作,以确保对象的实际状态与其期望状态一致,例如插件期望启动,插件控制器会处理启动插件的逻辑。 4. 重复:上述所有步骤都由控制器重复执行直到与期望状态一致。 这是一个描述控制器作用的例子:房间里的温度自动调节器。 当你设置了温度,告诉了温度自动调节器你的期望状态(Desired State)。 房间的实际温度是当前状态(Current State)。通过对设备的开关控制,温度自动调节器让其当前状态接近期望状态,未到达期望状态则继续调节,直到达到期望状态。 在 Halo 中控制器的运行部分已经有一个默认实现,你只需要编写控制器的调谐的逻辑也就是 [控制器概述](https://docs.halo.run/developer-guide/core/framework.md#controller) 中的所说的 Reconciler 即可。 ## 编写 Reconciler Reconciler 是控制器的核心,它是一个接口,你需要实现它的 `reconcile()` 方法,该方法接收一个 `Reconciler.Request` 对象,它包含了当前自定义模型对象的名称,你可以通过它来获取自定义模型对象的当前状态和期望状态,然后编写调谐的逻辑。 ```java @Component public class PostReconciler implements Reconciler { @Override public Result reconcile(Request request) { } @Override public Controller setupWith(ControllerBuilder builder) { return builder .extension(new Post()) .build(); } } ``` 以上是一个简单的 Reconciler 实现,它实现了 `reconcile()` 方法,然后在 `setupWith()` 方法中将其通过 `ControllerBuilder` 构建为一个控制器并指定了 它要观察的自定义模型对象为`Post`,当文章自定义模型对象发生变化时,`reconcile()` 方法就会被调用,从 `Request request` 参数中你可以获得当前发生变化的文章自定义模型对象的名称,然后你就可以通过名称来查询到自定义模型对象进行调谐了。 ### 构建控制器 `setupWith()` 方法用于根据当前类的 `reconcile` 方法构建控制器,你可以通过 `ControllerBuilder` 提供的方法来构建并定制控制器: ```java public class ControllerBuilder { private final String name; private Duration minDelay; private Duration maxDelay; private final Reconciler reconciler; private Supplier nowSupplier; private Extension extension; private ExtensionMatcher onAddMatcher; private ExtensionMatcher onDeleteMatcher; private ExtensionMatcher onUpdateMatcher; private ListOptions syncAllListOptions; private boolean syncAllOnStart = true; private int workerCount = 1; } ``` - `name`:控制器的名称,用于标识控制器。 - `minDelay`:控制器的最小延迟,用于控制控制器的最小调谐间隔,默认为 5 毫秒。 - `maxDelay`:控制器的最大延迟,用于控制控制器的最大调谐间隔,默认为 1000 秒。 - `reconciler`:控制器的调谐器,用于执行调谐逻辑,你需要实现 `Reconciler` 接口。 - `nowSupplier`:用于获取当前时间的供应商,用于控制器的时间戳,默认使用 `Instant.now()` 获取当前时间。 - `extension`:控制器要观察的自定义模型对象。 - `onAddMatcher`:用于匹配添加事件的匹配器,当自定义模型对象被创建时会触发。 - `onDeleteMatcher`:用于匹配删除事件的匹配器,当自定义模型对象被删除时会触发。 - `onUpdateMatcher`:用于匹配更新事件的匹配器,当自定义模型对象被更新时会触发。 - `syncAllListOptions`:用于同步所有自定义模型对象的查询条件,仅当 `syncAllOnStart` 为 `true` 时生效。 - `syncAllOnStart`:是否在控制器启动时同步所有自定义模型对象,默认为 `true`,可以配合 `syncAllListOptions` 使用以缩小需要同步的对象范围避免不必要的同步,例如只同步某个用户创建的文章或者某个固定名称的 ConfigMap 对象。如果你的控制器不需要同步所有对象,可以将其设置为 `false`。 - `workerCount`:控制器的工作线程数,用于控制控制器的并发度,如果你的控制器需要处理大量的对象,可以将其设置为大于 1 的值,以提高控制器的处理能力,但需要注意的是并发度越高,系统的负载也会越高。这里的并发度是指控制器的并发度,但是每个控制器还是单线程执行的。 #### ExtensionMatcher `onAddMatcher/onUpdateMatcher/onDeleteMatcher` 都是 `ExtensionMatcher` 类型,用于决定当自定义模型对象发生变化时是否触发控制器: ```java public interface ExtensionMatcher { boolean match(Extension extension); } ``` 这里`match` 方法的 `Extension` 参数类型与 `ControllerBuilder` 中的 `extension` 类型始终是一致的,因此可以直接通过强制类型转换来得到需要的类型。 比如我们想要观察文章对象,但是只想观察文章对象中 `visible` 字段为 `PUBLIC` 的文章,可以这样 ```java import static run.halo.app.extension.index.query.Queries.equal; public class PostReconciler implements Reconciler { @Override public Result reconcile(Request request) { return Result.doNotRetry(); } @Override public Controller setupWith(ControllerBuilder builder) { // 只想观察 VisibleEnum.PUBLIC 的文章 ExtensionMatcher extensionMatcher = extension -> { var post = (Post) extension; return VisibleEnum.PUBLIC.equals(post.getSpec().getVisible()); }; return builder .extension(new Post()) .onAddMatcher(extensionMatcher) .onUpdateMatcher(extensionMatcher) .onDeleteMatcher(extensionMatcher) .build(); } } ``` #### 控制启动时同步的范围 如果想要在控制器启动时控制同步对象的范围,可以通过 `syncAllListOptions` 和 `syncAllOnStart` 来实现,例如只同步某个用户创建的文章: ```java public class PostReconciler implements Reconciler { @Override public Result reconcile(Request request) { return Result.doNotRetry(); } @Override public Controller setupWith(ControllerBuilder builder) { return builder .extension(new Post()) .syncAllListOptions(ListOptions.builder() .fieldQuery(equal("spec.owner", "guqing")) .build() ) .syncAllOnStart(true) .build(); } } ``` ### Reconciler 的返回值 `reconcile()` 方法的返回值是一个 `Result` 对象,它包含了调谐的结果,你可以通过它来告诉控制器是否需要重试,如果需要重试则控制器会在稍后再次调用 `reconcile()` 方法,而这个过程会一直重复,直到 `reconcile()` 方法返回成功为止,这个过程被称之为调谐循环(Reconciliation Loop)。 ```java record Result(boolean reEnqueue, Duration retryAfter) {} ``` `Result` 对象包含了两个属性:reEnqueue 和 retryAfter,reEnqueue 用于标识是否需要重试,retryAfter 用于标识重试的时间间隔,如果 reEnqueue 为 true 则会在 retryAfter 指定的时间间隔后再次调用 `reconcile()` 方法,如果 reEnqueue 为 false 则不会再次调用 `reconcile()` 方法。 在没有特殊需要时,`retryAfter` 可以不指定,控制器会有一套默认的重试策略。 如果直接返回 `null` 则会被视为成功,效果等同于返回 `new Result(false, null)`。 ### Reconciler 的异常处理 当 `reconcile()` 方法抛出异常时,控制器会将异常记录到日志中,然后会将 `Request request` 对象重新放入队列中,等待下次调用 `reconcile()` 方法,这个过程会一直重复,直到 `reconcile()` 成功,对于默认重试策略,每次重试间隔会越来越长,直到达到最长间隔后不再增加。 ## 控制器示例 本章节将通过一个简单的示例来演示如何编写控制器。 ### 场景:事件管理系统 创建一个名为”EventTracker“的自定义模型,用于管理和追踪组织内的各种事件。这些事件可以是会议、研讨会、社交聚会或任何其他类型的组织活动。 “EventTracker“自定义模型将提供一个框架,用于记录事件的详细信息,如时间、地点、参与者和状态。 由于这里的重点是控制器,因此我们将忽略自定义模型的详细信息,只关注控制器的实现,一个可能的“EventTracker”数据结构如下: ```yaml apiVersion: tracker.halo.run/v1alpha1 kind: EventTracker metadata: name: event-tracker-1 spec: eventName: "Halo Meetup" eventDate: "2024-01-20T12:00:00Z" location: "Chengdu" participants: ["@sig-doc", "@sig-console", "@sig-halo"] description: "Halo Meetup in Chengdu" status: phase: "Planned" # Planned, Ongoing, Completed participants: [] conditions: - type: "Invalid" status: "True" reason: "InvalidEventDate" message: "Event date is invalid" ``` 业务逻辑处理: 1. 事件创建: - 当新的 EventTracker 资源被创建时,控制器需验证所有必要字段的存在和格式正确性。 - 初始化事件状态为 Planned。 2. 事件更新: - 检查 eventDate、location 和 participants 字段的变更。 - 如果接近事件日期,自动更新状态为 Ongoing。 3. 状态管理: - 根据当前日期和事件日期自动管理 phase 字段。 - 当事件日期过去时,将状态更新为 Completed。 4. 数据验证和完整性: - 确保所有输入数据的格式正确且合理。 - 如有不一致或缺失的重要信息,记录警告或错误。 5. 事件提醒和通知: - 在事件状态改变或临近事件日期时发送通知。 6. 清理和维护: - 对于已完成的事件,提供自动清理机制,例如在事件结束后一定时间内删除资源。 首先实现 EventTracker 控制器的协调循环主体,通过依赖注入 `ExtensionClient` 可以用于获取当前变更的对象: ```java @Component @RequiredArgsConstructor public class EventTrackerReconciler implements Reconciler { private final ExtensionClient client; @Override public Result reconcile(Request request) { // ... } @Override public Controller setupWith(ControllerBuilder builder) { return builder .extension(new EventTracker()) .build(); } } ``` 然后在 `reconcile()` 方法中根据 `EventTracker` 对象的状态来执行响应的操作,确保执行逻辑是是幂等的,这意味着即使多次执行相同操作,结果也应该是一致的。 ```java public Result reconcile(Request request) { client.fetch(EventTracker.class, request.name()).ifPresent(eventTracker -> { // 获取到当前变更的 EventTracker 对象 // 1. 检查必要字段的存在和格式正确性 // 2. 初始化事件状态为 Planned if (eventTracker.getStatus() == null) { eventTracker.setStatus(new EventTracker.Status()); } var status = eventTracker.getStatus(); if (status.getPhase() == null) { status.setPhase(EventTracker.Phase.PLANNED); } var eventName = eventTracker.getSpec().getEventName(); if (StringUtils.isBlank(eventName)) { Condition condition = Condition.builder() .type("Invalid") .reason("InvalidEventName") .message("Event name is invalid") .status(ConditionStatus.FALSE) .lastTransitionTime(Instant.now()) .build(); status.getConditions().addAndEvictFIFO(condition); } client.update(eventTracker); }); return new Result(false, null); } ``` 上述,我们通过 `client.fetch()` 方法获取到了当前变更的 `EventTracker` 对象,然后根据 `EventTracker` 对象的状态来执行响应的操作,例如初始化事件状态为 Planned,检查必要字段的存在和格式正确性等,但需要注意控制器的执行是异步的,如果我们通过 `EventTracker` 的 API 来创建或更改了一个 `EventTracker` 对象,那么 API 会在控制器执行之前返回结果,这意味着在用户界面看到的结果可能不是最新的,并且可能会在稍后更新。 对于上述校验 `eventName` 的逻辑只是保证后续的执行是可靠的,如果有些字段是必须的,那么我们可以通过 `@Schema` 注解来标注,为了让控制器中校验字段失败的信息能够呈现到用户界面,我们通过向 `status.conditions` 中添加了一条 Condition 记录来用于记录这个事件,再用户界面可以展示这个 Condition 记录的信息以让用户知晓。 最后,我们通过 `client.update()` 方法来更新 `EventTracker` 对象,这个过程就是将实际状态回写到 `EventTracker` 对象并应用到数据库中,这样就完成了一次调谐。 当 `EventTracker` 对象发生变更时,控制器也会被执行,这时我们可以根据 `EventTracker` 对象的状态来执行响应的操作,例如检查和更新 `eventDate`、`location` 和 `participants` 字段的变更,如果接近事件日期,自动更新状态为 Ongoing。 ```java public Result reconcile(Request request) { client.fetch(EventTracker.class, request.name()).ifPresent(eventTracker -> { // ...此处省略之前的逻辑 if (isApproach(eventTracker.getSpec().getEventDate())) { status.setPhase(EventTracker.Phase.ONGOING); sendNotification(eventTracker, "Event is ongoing"); } }); return new Result(false, null); } ``` 这里我们通过 `isApproach()` 方法来表示判断是否接近事件日期,如果接近则更新状态为 Ongoing,并使用 `sendNotification` 来发送发送通知。 > 为了简化示例,我们省略了 `isApproach()` 和 `sendNotification` 方法的实现。 还可以根据 `spec.participants` 字段来解析参与者信息,然后将其添加到 `status.participants` 中,这样就可以在用户界面看到参与者信息了。 ```java public Result reconcile(Request request) { client.fetch(EventTracker.class, request.name()).ifPresent(eventTracker -> { // ...此处省略之前的逻辑 var participants = eventTracker.getSpec().getParticipants(); resolveParticipants(participants).forEach(status::addParticipant); }); return new Result(false, null); } ``` ### 使用 Finalizers `Finalizers` 允许控制器实现异步预删除钩子。假设您为正在实现的 API 类型的每个对象创建了一个外部资源,例如存储桶,并且您希望在从 Halo 中删除相应对象 时清理外部资源,您可以使用终结器来删除外部资源资源。 比如 `EventTracker` 对象被删除时,我们需要删除 `EventTracker` 对象记录的日志,这时我们可以通过 `Finalizers` 来实现。 首先我们需要在 `reconcile()` 的开头判断 `EventTracker` 对象的 `metadata.deletionTimestamp` 是否存在,如果存在则表示 `EventTracker` 对象被删除了, 这时我们就可以执行清理操作。 ```java public Result reconcile(Request request) { client.fetch(EventTracker.class, request.name()).ifPresent(eventTracker -> { if (ExtensionOperator.isDeleted(eventTracker)) { // 1. 判断是否被删除 // 2. 调用 removeFinalizers 方法移除终结器(稍后会说明) ExtensionUtil.removeFinalizers(eventTracker.getMetadata(), Set.of(FINALIZER_NAME)); // 3. 执行清理操作 cleanUpLogsForTracker(eventTracker); // 4. 更新 EventTracker 对象将变更应用到数据库中 client.update(eventTracker); // 5. return 避免执行后续逻辑 return; } // ...此处省略之前的逻辑 }); return new Result(false, null); } ``` 1. `ExtensionOperator.isDeleted` 方法是 Halo 提供的工具方法,用于判断对象是否被删除,它会判断 `metadata.deletionTimestamp` 是否存在,如果存在则表示对象被标记删除了。 关于自定义模型对象的删除可以参考:[自定义模型对象生命周期](https://docs.halo.run/developer-guide/core/framework.md#extension-lifecycle) 2. `ExtensionUtil.removeFinalizers` 方法是 Halo 提供的工具方法,用于移除对象的终结器,它接收两个参数,第一个参数是对象的元数据,第二个参数是要移除的终结器名称集合,它来自 `run.halo.app.extension.ExtensionUtil`。 3. `cleanUpLogsForTracker` 方法是我们自己实现的,这里的示例是用于清理 `EventTracker` 对象记录的日志,你可以根据自己的业务需求来实现,如清理外部资源等。 经过上述步骤,我们只是写了移除终结器但是发现没有添加终结器的逻辑,添加终结器的逻辑需要在判断删除之后,`metadata.finalizers` 是一个字符串集合,用于标识对象是否可回收,如果 `metadata.finalizers` 不为空则表示对象不可回收,否则表示对象可回收,我们可以通过 `ExtensionUtil.addFinalizers` 方法来添加终结器。 最佳实践是,一个控制器最多添加一个终结器,名称为了防止冲突可以使用当前业务的 `group/终结器名称` 来命名,例如 `tracker.halo.run/finalizer`,例如在 Halo 中文章的控制器使用了一个终结器,但可能插件也会定义一个文章控制器来扩展文章的业务,那么根据最佳实践命名终结器可以避免冲突。 ```java private static final String FINALIZER_NAME = "tracker.halo.run/finalizer"; public Result reconcile(Request request) { client.fetch(EventTracker.class, request.name()).ifPresent(eventTracker -> { if (ExtensionOperator.isDeleted(eventTracker)) { // ... 省略删除逻辑 } // 添加终结器 ExtensionUtil.addFinalizers(post.getMetadata(), Set.of(FINALIZER_NAME)); // ...此处省略之前的逻辑 // 会在更新时将终结器的变更写入到数据库中 client.update(eventTracker); }); } ``` --- url: https://docs.halo.run/developer-guide/plugin/api-reference/server/extension-client.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 与自定义模型交互 Halo 提供了两个类用于与自定义模型对象交互 `ExtensionClient` 和 `ReactiveExtensionClient`。 它们提供了对自定义模型对象的增删改查操作。`ExtensionClient` 是阻塞式的,只能用于非响应式环境,例如已经切换到工作线程的后台任务;WebFlux 控制器、WebFilter 等响应式调用链应使用 `ReactiveExtensionClient`。后者返回 Reactor 提供的 `Mono` 或 `Flux`。 ```java public interface ReactiveExtensionClient { Flux list(Class type, Predicate predicate, Comparator comparator); // 已经过时,建议使用 listBy 或 listAll 代替 @Deprecated Mono> list(Class type, Predicate predicate, Comparator comparator, int page, int size); Flux listAll(Class type, ListOptions options, Sort sort); Mono> listBy(Class type, ListOptions options, PageRequest pageable); /** * Fetches Extension by its type and name. * * @param type is Extension type. * @param name is Extension name. * @param is Extension type. * @return an optional Extension. */ Mono fetch(Class type, String name); Mono fetch(GroupVersionKind gvk, String name); Mono get(Class type, String name); /** * Creates an Extension. * * @param extension is fresh Extension to be created. Please make sure the Extension name does * not exist. * @param is Extension type. */ Mono create(E extension); /** * Updates an Extension. * * @param extension is an Extension to be updated. Please make sure the resource version is * latest. * @param is Extension type. */ Mono update(E extension); /** * Deletes an Extension. * * @param extension is an Extension to be deleted. Please make sure the resource version is * latest. * @param is Extension type. */ Mono delete(E extension); /** * Watches the changes of all extensions. */ void watch(Watcher watcher); } ``` - `fetch(GroupVersionKind, name)`:以 `Unstructured` 形式按 GVK 和名称获取自定义模型,适用于不确定具体 Java 类型的场景。 - `watch`:注册一个 `Watcher` 监听所有自定义模型的变更事件。两个 API 均自 Halo 2.4.0 起可用。 :::warning 已废弃的方法 `getJsonExtension(GroupVersionKind, name)` 自 Halo 2.23.0 起被标记为 `@Deprecated(forRemoval = true)`,请迁移到 `fetch(GroupVersionKind, name)`。 ::: ### 示例 如果你想在插件中根据 name 参数查询获取到 Person 自定义模型的数据,则可以这样写: ```java @Service @RequiredArgsConstructor public PersonService { private final ReactiveExtensionClient client; Mono getPerson(String name) { return client.fetch(Person.class, name); } } ``` 或者使用阻塞式 Client ```java @Service @RequiredArgsConstructor public PersonService { private final ExtensionClient client; Optional getPerson(String name) { return client.fetch(Person.class, name); } } ``` 注意:非阻塞线程中不能调用阻塞式方法。 我们建议你更多的使用响应式的 `ReactiveExtensionClient` 去替代 `ExtensionClient`。 ### 监听模型变更 \{#watch} 如果只需要在自定义模型发生变更时执行一些逻辑(而不是持续调谐到期望状态),可以通过 `watch` 方法注册一个 `Watcher`: ```java import jakarta.annotation.PreDestroy; import java.util.concurrent.atomic.AtomicBoolean; @Component public class PersonWatcher implements Watcher { private final AtomicBoolean disposed = new AtomicBoolean(); private Runnable disposeHook = () -> {}; public PersonWatcher(ReactiveExtensionClient client) { client.watch(this); } @Override public void onAdd(Extension extension) { if (extension instanceof Person person) { // do something } } @Override public void onUpdate(Extension oldExtension, Extension newExtension) { // do something } @Override public void onDelete(Extension extension) { // do something } @Override public void registerDisposeHook(Runnable dispose) { this.disposeHook = dispose; } @PreDestroy @Override public void dispose() { if (disposed.compareAndSet(false, true)) { disposeHook.run(); } } @Override public boolean isDisposed() { return disposed.get(); } } ``` `Watcher` 的 `onAdd`、`onUpdate`、`onDelete` 分别对应模型的创建、更新和删除事件。需要注意的是 `watch` 会接收**所有**自定义模型的变更,需要在回调中自行过滤类型,并在插件上下文关闭时调用 `dispose()` 取消注册;如果需要声明式地将资源持续调谐到期望状态,应优先使用 [Reconciler](https://docs.halo.run/developer-guide/plugin/api-reference/server/reconciler.md)。 ### 查询 \{#query} `ReactiveExtensionClient` 提供了以下方法用于查询数据: - `listBy`:分页查询数据。 - `listNamesBy`:分页查询对象名称。 - `listAll`:查询所有数据。 - `listAllNames`:查询所有对象名称。 - `listTopNames`:查询指定数量的对象名称。 - `countBy`:统计符合条件的数据数量。 这些方法都需要一个 `ListOptions` 参数,用于传递查询条件: ```java public class ListOptions { private LabelSelector labelSelector; private FieldSelector fieldSelector; } ``` 其中 `LabelSelector` 用于传递标签查询条件,`FieldSelector` 用于传递字段查询条件。 `FieldSelector` 支持比自动生成的 APIs 中更多的查询条件,可以通过 `run.halo.app.extension.index.query.Queries` 来构建。 ```java import static run.halo.app.extension.index.query.Queries.and; import static run.halo.app.extension.index.query.Queries.equal; ListOptions.builder() .fieldQuery(and( equal("name", "test"), equal("age", 18) )) .build(); ``` 支持的查询条件如下: | 方法 | 说明 | 示例 | | ------------- | ------------------- | ------------------------------------------------------- | | `equal` | 等于 | `equal("name", "test")` | | `notEqual` | 不等于 | `notEqual("name", "test")` | | `greaterThan` | 大于,可通过第三个参数控制是否包含边界 | `greaterThan("age", 18)`、`greaterThan("age", 18, true)` | | `lessThan` | 小于,可通过第三个参数控制是否包含边界 | `lessThan("age", 18)`、`lessThan("age", 18, true)` | | `between` | 在范围内,可分别控制上下边界是否包含 | `between("age", 18, true, 20, false)` | | `in` | 在给定值范围内 | `in("age", 18, 19, 20)` | | `isNull` | 值为空 | `isNull("deletedAt")` | | `all` | 指定字段的所有值 | `all("age")` | | `startsWith` | 以指定字符串开头 | `startsWith("name", "test")` | | `endsWith` | 以指定字符串结尾 | `endsWith("name", "test")` | | `contains` | 包含指定字符串 | `contains("name", "test")` | | `and` | 且 | `and(equal("name", "test"), equal("age", 18))` | | `or` | 或 | `or(equal("name", "test"), equal("age", 18))` | | `not` | 取反 | `not(equal("name", "test"))` | | `labelExists` | 标签存在 | `labelExists("halo.run/hidden")` | | `labelEqual` | 标签等于 | `labelEqual("env", "production")` | | `labelIn` | 标签值在给定范围内 | `labelIn("env", Set.of("production", "staging"))` | 在 `FieldSelector` 中使用的所有字段都必须添加为索引,否则会抛出异常表示不支持该字段。关于如何使用索引请参考 [自定义模型使用索引](https://docs.halo.run/developer-guide/plugin/api-reference/server/extension.md#using-indexes)。 :::note 使用 Queries 构建查询 从 2.22.0 开始,`QueryFactory` 已过时,请使用 `Queries` 创建查询条件。取反查询可以通过 `Queries.not(condition)` 或 `condition.not()` 构建。 ::: 可以通过 `and` 和 `or` 方法组合和嵌套查询条件: ```java import run.halo.app.extension.index.query.Condition; import static run.halo.app.extension.index.query.Queries.and; import static run.halo.app.extension.index.query.Queries.equal; import static run.halo.app.extension.index.query.Queries.or; Condition query = and( or(equal("dept", "A"), equal("dept", "B")), or(equal("age", 19), equal("age", 18)) ); ListOptions.builder() .fieldQuery(query) .build(); ``` ### 构建 ListOptions ListOptions 提供了 `builder` 方法用于构建查询条件,`fieldQuery` 方法用于传递字段查询条件,`labelSelector` 方法用于传递标签查询条件。 ```java import static run.halo.app.extension.index.query.Queries.equal; ListOptions.builder() .labelSelector() .eq("key-1", "value-1") .end() .fieldQuery(equal("key-2", "value-2")) .build(); ``` - `labelSelector` 之后使用 `end` 方法结束标签查询条件的构建。 - `andQuery` 和 `orQuery` 用于组合多个 `FieldSelector` 查询条件。 ### 排序 `listBy`、`listNamesBy`、`listAll`、`listAllNames` 和 `listTopNames` 方法都支持传递 `Sort` 参数,用于传递排序条件。 ```java import org.springframework.data.domain.Sort; Sort.by(Sort.Order.asc("metadata.name")) ``` 通过 `Sort.by` 方法可以构建排序条件,`Sort.Order` 用于指定排序字段和排序方式,`asc` 表示升序,`desc` 表示降序。 排序中使用的字段必须是添加为索引的字段,否则会抛出异常表示不支持该字段。关于如何使用索引请参考 [自定义模型使用索引](https://docs.halo.run/developer-guide/plugin/api-reference/server/extension.md#using-indexes)。 ### 分页 `listBy` 方法支持传递 `PageRequest` 参数,用于传递分页条件。 ```java import run.halo.app.extension.PageRequestImpl; PageRequestImpl.of(1, 10); PageRequestImpl.of(1, 10, Sort.by(Sort.Order.asc("metadata.name")); PageRequestImpl.ofSize(10); ``` 通过 `PageRequestImpl.of` 方法可以构建分页条件,具有两个参数的方法用于指定页码和每页数量,具有三个参数的方法用于指定页码、每页数量和排序条件。 `ofSize` 方法用于指定每页数量,页码默认为 1。 --- url: https://docs.halo.run/developer-guide/plugin/api-reference/server/setting-fetcher.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 获取插件配置 插件的 `plugin.yaml` 中允许配置 `settingName` 和 `configMapName` 字段,用于定义插件的个性化设置。 本文介绍如何获取插件定义的设置表单对应的配置数据,以及如何在插件中使用配置数据。 如何关联 `plugin.yaml` 与 Setting、选择 FormKit 输入组件,请先参考[插件设置与表单组件](https://docs.halo.run/developer-guide/plugin/basics/ui/forms.md)和[表单定义与组件速查](https://docs.halo.run/developer-guide/form-schema.md)。 ## 概述 Halo 提供了两个 Bean 用于获取插件配置数据:`SettingFetcher` 和 `ReactiveSettingFetcher`,分别用于同步和异步获取配置数据。 以 `ReactiveSettingFetcher` 为例,提供了以下方法: ```java public interface ReactiveSettingFetcher { Mono fetch(String group, Class clazz); @NonNull Mono getSettingValue(String group); @NonNull Mono> getSettingValues(); } ``` - `fetch` 方法用于获取指定分组的配置数据,并将其转换为指定的 Java 类型。 - `getSettingValue` 方法用于获取指定分组的配置数据,返回 `JsonNode` 类型。 - `getSettingValues` 方法用于获取所有配置数据,返回 `Map` 类型,其中键为分组名称,值为配置对象。 :::warning 已废弃的方法 `get(group)` 和 `getValues()` 自 Halo 2.23.0 起被标记为 `@Deprecated(forRemoval = true)`,将在后续版本移除,请迁移到 `getSettingValue(group)` 和 `getSettingValues()`。注意新方法的返回类型为 Jackson 3 的 `tools.jackson.databind.JsonNode`,而废弃方法返回 Jackson 2 的 `com.fasterxml.jackson.databind.JsonNode`,迁移时需要同步调整 import。 ::: `ReactiveSettingFetcher` 和 `SettingFetcher` 底层都对配置数据进行了缓存,以提高性能,并且在配置变更时会自动刷新缓存,所以直接调用这些方法即可获取最新的配置数据。 ## 监听配置变更 当用户修改插件配置时,可以通过监听 `PluginConfigUpdatedEvent` 事件,执行相应的操作。`PluginConfigUpdatedEvent` 包含了配置变更前后的数据,使插件能够对变化做出响应。 ```java public class PluginConfigUpdatedEvent extends ApplicationEvent { private final Map oldConfig; private final Map newConfig; // ... } ``` ## 使用示例 ### 定义设置表单 假设项目同步插件定义了一个名为 `project-sync-settings` 的设置表单,其中包含自动同步开关和同步间隔: ```yaml title="src/main/resources/extensions/settings.yaml" apiVersion: v1alpha1 kind: Setting metadata: name: project-sync-settings spec: forms: - group: sync label: 同步设置 formSchema: - $formkit: switch name: enabled label: 启用自动同步 value: false - $formkit: number name: interval label: 同步间隔(分钟) value: 30 validation: required|min:5 ``` ### 配置 plugin.yaml 在 `plugin.yaml` 中配置 `settingName` 和 `configMapName` 字段: ```yaml apiVersion: plugin.halo.run/v1alpha1 kind: Plugin metadata: name: project-sync spec: displayName: 项目同步 # ... configMapName: project-sync-config settingName: project-sync-settings ``` ### 定义值类 为了方便使用,定义一个值类存储配置数据: ```java public record SyncSetting(boolean enabled, int interval) { public static final String GROUP = "sync"; } ``` ### 获取配置数据 通过依赖注入 `ReactiveSettingFetcher` 并使用 `fetch(group, type)` 方法查询配置: ```java @Service @RequiredArgsConstructor public class SyncService { private final ReactiveSettingFetcher settingFetcher; public Mono syncProjects() { return settingFetcher.fetch(SyncSetting.GROUP, SyncSetting.class) .doOnNext(syncSetting -> { if (syncSetting.enabled()) { // 使用 syncSetting.interval() 安排下一次同步 } }) .then(); } } ``` ### 监听配置变更 通过监听 `PluginConfigUpdatedEvent` 事件来处理配置变更: ```java @Component public class SyncConfigListener { @EventListener public void onConfigUpdated(PluginConfigUpdatedEvent event) { if (event.getNewConfig().containsKey(SyncSetting.GROUP)) { // 重新安排同步任务 } } } ``` 通过以上示例,可以看到如何使用 `ReactiveSettingFetcher` 获取配置数据,并通过监听 `PluginConfigUpdatedEvent` 来处理配置变更事件,确保系统能及时响应配置的变化。 --- url: https://docs.halo.run/developer-guide/plugin/api-reference/server/reverseproxy.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 静态资源代理 插件中的静态资源如图片等如果想被外部访问到,需要放到 `src/main/resources` 目录下,并通过创建 `ReverseProxy` 自定义模型对象来进行静态资源代理访问。 例如 `src/main/resources` 下的 `static` 目录下有一张 `halo.jpg`: 1. 首先需要在 `src/main/resources/extensions` 下创建一个 `yaml`,文件名可以任意。 2. 声明 `ReverseProxy` 对象如下: ```yaml apiVersion: plugin.halo.run/v1alpha1 kind: ReverseProxy metadata: # 为了避免与其他插件冲突,推荐带上插件名称前缀 name: my-plugin-fake-reverse-proxy rules: - path: /res/** file: directory: static # 如果想代理 static 下所有静态资源则省略 filename 配置 filename: halo.jpg ``` 插件启动后会根据 `/plugins/{plugin-name}/assets/**` 规则生成访问路径, 因此该 `ReverseProxy` 的访问路径为:`/plugins/my-plugin/assets/res/halo.jpg`。 - `rules` 下可以添加多组规则。 - `path` 为路径前缀。 - `file` 表示访问文件系统,目前暂时仅支持这一种。 - `directory` 表示要代理的目标文件目录,它相对于 `src/main/resources/` 目录。 - `filename` 表示要代理的目标文件名。 `directory` 和 `filename` 都是可选的,但必须至少有一个被配置。 --- url: https://docs.halo.run/developer-guide/plugin/api-reference/server/notification.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 发送和订阅通知 Halo 的通知功能提供了事件驱动的消息提醒机制,让用户能够及时获取系统内的关键事件。 开发者可以根据需求定义事件类型和通知方式(如站内消息、邮件等),并支持个性化的推送策略,提升用户体验和系统可扩展性。 通知系统通过事件机制将关键消息推送给用户。开发者可以自定义通知类型、消息格式和推送方式,主要应用于以下场景: - 用户互动:如文章评论、点赞等; - 订单和流程提醒:如订单创建、处理完成等; - 内容更新:如文章发布、系统公告等。 ## 通知系统工作流程 下图展示了 Halo 通知功能的工作流程,包括事件声明、订阅查找、通知发送等关键步骤。 ```mermaid graph TD A[开发者声明 ReasonType] --> B[业务代码创建 Reason] B --> C[查找匹配的 Subscription] C --> D{用户订阅了事件吗?} D -- 是 --> E[获取用户通知偏好] E --> F[查找通知模板] F --> G[查找对应的 Notifier] G --> H[发送通知] D -- 否 --> I[结束,无需通知] H --> J[用户接收通知] J --> K[用户查看/处理通知] Z[用户订阅事件] --> D ``` 1. 声明事件类型:开发者首先需要声明通知事件的类型 (ReasonType),指定事件的名称、描述和事件所需的属性。 2. 插件触发事件:当插件中的某个业务操作发生时,插件需要触发相应的事件。 3. 创建 Reason 实例:Halo 根据发送的事件创建一个 Reason 实例,表示具体的事件信息,步骤 2 和 3 可以合并为`业务代码创建 Reason`。 4. 订阅查找:Halo 通知中心会根据事件的类型和属性查找匹配的订阅。 5. 通知发送:如果找到匹配的订阅,系统根据用户的偏好设置通过不同的通知器(如站内消息、邮件等)发送通知。 6. 用户接收和处理通知:用户通过预设的通知渠道接收事件通知,并可以在系统中查看或处理这些通知。 ## 通知事件 在 Halo 通知系统中,`ReasonType` 和 `Reason` 是两个核心自定义模型,用于定义通知事件的类别和具体的事件实例。 理解它们的字段对于开发者扩展通知功能至关重要。 下面将详细说明这两个模型的字段及其作用。 ### ReasonType 模型 `ReasonType` 是用于定义通知事件类别的模型。每个 `ReasonType` 都代表一类特定的事件,例如文章评论、新文章发布等。通过 `ReasonType`,系统可以了解该事件的特定属性和数据结构。 用户个人中心的通知设置页面会根据 `ReasonType` 的名称和描述展示事件类型和通知方式。 #### ReasonType 字段说明 | 字段名 | 类型 | 是否必填 | 说明 | | ------------------ | -------- | ---- | -------------------------------------------- | | `apiVersion` | `string` | 是 | API 版本号,定义为 `notification.halo.run/v1alpha1` | | `kind` | `string` | 是 | 自定义资源类型,必须为 `ReasonType` | | `metadata.name` | `string` | 是 | 事件类别的唯一标识名称,例如 `comment` | | `spec.displayName` | `string` | 是 | 事件类别的展示名称,用户界面中显示的事件名称 | | `spec.description` | `string` | 否 | 事件类别的描述,说明此事件的用途和含义 | | `spec.properties` | `array` | 是 | 此事件包含的属性字段,用于定义该类事件应携带的数据 | #### spec.properties 字段 `properties` 字段用于定义该通知事件需要传递的参数或属性。每个属性都是一个对象,通常包含以下字段: | 字段名 | 类型 | 是否必填 | 说明 | | ------------- | --------- | ---- | ------------------------------------- | | `name` | `string` | 是 | 属性的名称,表示事件数据中的某个字段 | | `type` | `string` | 是 | 属性的数据类型,例如 `string`、`boolean` 等,仅用于描述 | | `description` | `string` | 否 | 对该属性的描述,说明其在事件中的作用 | | `optional` | `boolean` | 否 | 该属性是否为可选字段,默认值为 `false`,`false` 表示必填 | `properties.type` 字段仅用于文档性目的,不会在运行时进行数据类型检查。有了此描述,便于编写通知模板时使用正确的数据类型。 **示例:** 声明评论事件的 ReasonType ```yaml apiVersion: notification.halo.run/v1alpha1 kind: ReasonType metadata: name: comment spec: displayName: "评论事件" description: "用户在文章上收到评论时触发。" properties: - name: postName type: string description: "文章的名称。" - name: commenter type: string description: "评论者用户名。" - name: content type: string description: "评论内容。" ``` 在这个示例中,`ReasonType` 定义了一个评论事件,该事件包括三种属性:`postName`(文章名)、`commenter`(评论者)和 `content`(评论内容),这些属性在触发事件时将传递给通知系统。 这一类型的资源声明非常适合放在插件的 `resources` 目录下,以便插件安装时自动创建。参考 [声明自定义模型对象](https://docs.halo.run/developer-guide/plugin/api-reference/server/extension.md#declare-extension-object) ### Reason 模型 `Reason` 模型用于描述具体的事件实例,它是 `ReasonType` 的一个实例化,包含触发该事件时的具体数据。 `Reason` 通常在某个事件发生时创建,例如某篇文章收到评论时生成一个 `Reason`,记录具体的评论信息。 #### Reason 字段说明 | 字段名 | 类型 | 是否必填 | 说明 | | ----------------- | -------- | ---- | -------------------------------------------- | | `apiVersion` | `string` | 是 | API 版本号,定义为 `notification.halo.run/v1alpha1` | | `kind` | `string` | 是 | 自定义资源类型,必须为 `Reason` | | `metadata.name` | `string` | 是 | 该事件实例的唯一标识名称,通常自动生成 | | `spec.reasonType` | `string` | 是 | 引用的 `ReasonType` 名称,表示该事件实例属于哪个事件类型 | | `spec.author` | `string` | 是 | 事件的触发者或创建者,通常为用户或系统的标识符 | | `spec.subject` | `object` | 是 | 事件的主题,指向该事件所涉及的具体对象(如文章、评论等) | | `spec.attributes` | `object` | 是 | 包含事件具体数据的键值对,内容与 `ReasonType` 中定义的属性一致 | #### spec.subject 字段 `subject` 字段描述了与该事件相关的主体对象,例如,评论事件中的文章对象。`subject` 通常包含以下字段: | 字段名 | 类型 | 是否必填 | 说明 | | ------------ | -------- | ---- | -------------------------------------------- | | `apiVersion` | `string` | 是 | 主题对象的 API 版本号,例如 `content.halo.run/v1alpha1` | | `kind` | `string` | 是 | 主题对象的类型,例如 `Post` 表示文章 | | `name` | `string` | 是 | 主题对象的唯一标识,通常是对象的名称或 ID | | `title` | `string` | 是 | 主题对象的标题,通常是人类可读的名称 | | `url` | `string` | 否 | 主题对象的访问链接或详情页面的 URL | 参考 [Reason 自定义模型](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/core/extension/notification/Reason.java) #### spec.attributes 字段 `attributes` 字段用于存储该事件实例的具体数据。每个键值对表示一个 `ReasonType` 中定义的属性和其对应的值。 **示例:** 创建评论事件的 Reason ```yaml apiVersion: notification.halo.run/v1alpha1 kind: Reason metadata: name: comment-123 spec: reasonType: comment author: "访客" subject: apiVersion: "content.halo.run/v1alpha1" kind: Post name: "post-456" title: "Halo 系统介绍" url: "https://example.com/archives/456" attributes: postName: "Halo 系统介绍" commenter: "访客" content: "这是一篇非常有帮助的文章!" ``` 在这个示例中,`Reason` 表示具体的评论事件。 它关联了 `comment` 这一 `ReasonType`,并提供了详细的事件信息,包括文章(subject)的标识信息以及评论的内容(attributes)。 通过 ReasonType 和 Reason,开发者可以定义和管理各种事件,并在事件发生时触发相应的通知逻辑。 ## 通知模板 在 Halo 系统中,通知模板用于定义每种通知类型的展示格式和内容结构。每当触发某个通知事件时,系统会根据事件的类型选择相应的通知模板,并将事件的属性嵌入到模板中生成最终的通知内容。如果未定义通知模板,则系统无法确定通知的具体格式和内容,这可能导致通知发送失败。因此,定义通知模板是实现通知功能的关键步骤。 ### 通知模板的基本结构 通知模板是通过 `NotificationTemplate` 自定义模型定义的。 每个模板指定了与某个事件类型 (ReasonType) 关联的内容格式,包括通知的标题、正文内容等。 模板内容可以使用属性占位符,以便在通知生成时自动填充事件属性。Halo 支持使用 [Thymeleaf](https://www.thymeleaf.org/) 模板引擎进行内容渲染。 #### 通知模板字段说明 | 字段名 | 类型 | 是否必填 | 说明 | | -------------------------------- | -------- | ---- | -------------------------------------------- | | `apiVersion` | `string` | 是 | API 版本号,定义为 `notification.halo.run/v1alpha1` | | `kind` | `string` | 是 | 自定义资源类型,必须为 `NotificationTemplate` | | `metadata.name` | `string` | 是 | 模板的唯一标识名称 | | `spec.reasonSelector.reasonType` | `string` | 是 | 关联的事件类型 (`ReasonType`) 名称 | | `spec.reasonSelector.language` | `string` | 是 | 模板语言,固定写为 `default` | | `spec.template.title` | `string` | 是 | 通知的标题模板,支持占位符 | | `spec.template.rawBody` | `string` | 是 | 通知的正文模板,应当是纯文本,支持占位符 | | `spec.template.htmlBody` | `string` | 是 | 通知的正文模板,格式为 HTML 的模板,支持占位符 | #### 定义通知模板 定义通知模板时,开发者需要指定模板的 `reasonSelector`,用于与事件类型关联,并在 `template` 中定义通知标题和内容的格式。 `spec.reasonSelector.language` 字段用于指定模板的语言,设计支持多语言,但目前 Halo 没有提供保存用户语言偏好的入口,因此只能使用 `default`。 模板内容支持纯文本和 HTML 格式,建议开发者两种内容都提供,以适应不同的通知渠道。比如邮件通知需要 HTML 格式,而短信通知则仅支持纯文本。 **示例:** 定义评论事件的通知模板 假设我们需要为“新评论”事件定义一个通知模板,该模板包括事件的标题和正文内容: ```yaml apiVersion: notification.halo.run/v1alpha1 kind: NotificationTemplate metadata: name: template-new-comment-on-post spec: reasonSelector: reasonType: new-comment-on-post language: default template: title: "你的文章 [(${subject.title})] 收到了一条新评论" rawBody: | 评论者 [(${author.name})] 评论了您的文章 [(${subject.title})],内容如下: [(${props.comment})] htmlBody: |

评论者 [(${author.name})] 评论了您的文章 [(${subject.title})],内容如下:

[(${props.comment})]

``` 参考 [Halo 默认通知模板 YAML](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/application/src/main/resources/extensions/notification-templates.yaml) #### 通知模板设计小技巧与最佳实践 ##### 合理使用占位符 在通知模板中,使用占位符来动态插入事件数据是提高模板灵活性的关键。占位符的设计应遵循以下规则: - 使用清晰的命名:占位符应具有明确的含义,例如 `[(${quoteReplyName})]` 表示引用回复的名称,让代码更具可读性,建议使用 `CamelCase` 命名规范,不要使用嵌套对象作为变量如 `subject.title`。 - 避免嵌套复杂表达式:为了避免通知生成的内容过于复杂,建议在模板中尽量使用简单的占位符。复杂逻辑应在事件触发时处理,尽量保持模板的简洁。 - 确保属性完整性:占位符应与 ReasonType 中定义的属性一致,避免由于属性缺失导致的通知发送错误。 ##### 提供多种格式的内容 在 Halo 中,不同的通知渠道可能支持不同格式的内容,建议模板中同时提供纯文本和 HTML 格式,以便适应各类通知渠道需求。 - 纯文本格式:适合即时通讯类应用消息和短信通知,尽量简洁明了,关注重点信息。 - HTML 格式:适合富文本展示渠道,如邮件通知。HTML 模板可使用简单的样式和链接,帮助用户更好地理解通知内容。 - 适配不同渠道的内容:对于可能发送到多渠道的通知,可以在不同格式中包含适合该渠道的具体内容,如 HTML 中使用 `` 标签提供链接,而纯文本只展示简洁的链接地址。 - 如果在模板中需要用到日期,建议提前将其格式化为带时区的日期字符串,避免在模板中使用复杂的日期格式化。 ##### 模板语法 Halo 使用 Thymeleaf 模板引擎来渲染通知模板,开发者可以在模板中使用 Thymeleaf 的语法来处理模板中的逻辑和数据。 - 对于纯文本如标题和 `rawBody`,使用 Thymeleaf 的 [Textual syntax](https://www.thymeleaf.org/doc/tutorials/3.1/usingthymeleaf.html#textual-syntax) 语法来引用变量和表达式。 其取值格式为:`[(${expression})]`,例如 `[(${title})]`。 - 对于 HTML 内容如 `htmlBody`,使用 Thymeleaf 的 [Standard syntax](https://www.thymeleaf.org/doc/tutorials/3.1/usingthymeleaf.html#standard-syntax) 语法。 其取值格式为:`${expression}`,例如 `${title}`。 #### 模板渲染与发送 在通知事件触发时,Halo 通知中心会查找与该事件 `ReasonType` 匹配的 `NotificationTemplate`,并将事件数据填充到模板中生成最终通知内容。 没有定义模板的事件将无法发送通知,因此为每个 `ReasonType` 定义模板是保证通知发送成功的前提。 可以有多个相同的 `reasonSelector` 绑定到同一个事件类型,比如 `reasonType=new-comment-on-post`且 `language=default` 的模板存在多个,Halo 会**选择最近创建的模板**。 根据这个特点,**插件或主题开发者可以提供自己的通知模板以覆盖默认的通知模板**。 在生成通知内容时,系统还会提供一些额外的全局属性(如 `site.title` 等),这些属性可以在模板中直接使用: | 字段名 | 类型 | 说明 | | ------------------------ | -------- | -------------- | | `site.title` | `string` | 站点标题 | | `site.subtitle` | `string` | 站点副标题 | | `site.logo` | `string` | 站点 Logo URL | | `site.url` | `string` | 站点外部访问地址 | | `subscriber.displayName` | `string` | 订阅者显示名称 | | `subscriber.id` | `string` | 订阅者唯一标识符 | | `unsubscribeUrl` | `string` | 退订地址,用于取消订阅的链接 | ## 触发通知事件 在 Halo 系统中,通知功能的核心是通过触发特定的事件,生成相应的 Reason 实例,然后通过系统的通知机制将该事件通知给订阅者。 Halo 提供了 `NotificationReasonEmitter` 接口,开发者可以通过它轻松触发通知事件,将业务逻辑与通知机制结合起来。 ### 工作机制 `NotificationReasonEmitter` 的作用是简化事件触发和通知的处理流程,它的主要职责是: - 接收业务事件的参数,生成 `Reason` 实例。 - 将 `Reason` 实例与 `ReasonType` 进行匹配,触发事件。 - 通过 Halo 的通知系统,将事件推送给订阅了该事件的用户。 定义参考 [NotificationReasonEmitter](https://docs.halo.run/developer-guide/plugin/basics/server/object-management.md#notificationreasonemitter) - `reasonType`:事件类型的名称,对应于 `ReasonType` 的 `metadata.name` 字段。 - `reasonData`:事件数据的构建器,用于构建 `Reason` 实例的属性。 Reason 数据的构建器有以下属性: ```java public class ReasonPayloadBuilder { private Reason.Subject subject; private UserIdentity author; private Map attributes; } ``` - `subject`:事件的主体对象,参考 `Reason` 中的 `spec.subject` 字段。 - `author`:事件的触发者,通常是用户或系统的标识符,这是一个 `UserIdentity` 对象,如果作者是匿名的则需要传递邮箱地址来构造,比如评论者可能没有关联具体用户而仅仅是邮箱地址。 - `attributes`:事件的具体数据,包含了 `ReasonType` 中定义的属性和对应的值,如果必填字段没有传递则会抛出异常。 使用场景举例: - 当用户在博客上发表文章时,触发“新文章发布”事件,通知订阅了该事件的用户。 - 当用户在文章上发表评论时,触发“评论回复”事件,通知文章作者或订阅了评论的用户。 - 当管理员处理插件订单时,触发“订单创建”事件,通知管理员新订单的详情。 ### 示例 \{#reason-emitter-example} 假设我们需要在用户发布的文章时有新评论时,向订阅了“文章有新评论”事件的用户发送通知。可以通过 `NotificationReasonEmitter` 实现如下逻辑。 第一步:在你的插件代码中注入 `NotificationReasonEmitter`。 ```java import run.halo.app.notification.NotificationReasonEmitter; @Service @RequiredArgsConstructor public class CommentEventListener { private final NotificationReasonEmitter notificationReasonEmitter; } ``` 第二步:有新评论被创建时触发 ```java import run.halo.app.core.extension.content.Comment; import run.halo.app.core.extension.content.Post; @Async @EventListener(CommentCreatedEvent.class) public void onNewComment(CommentCreatedEvent event) { Comment comment = event.getComment(); Ref subjectRef = comment.getSpec().getSubjectRef(); Post post = client.fetch(Post.class, subjectRef.getName()).orElseThrow(); // 评论的主体是文章,因此构建文章的主体对象 var reasonSubject = Reason.Subject.builder() .apiVersion(post.getApiVersion()) .kind(post.getKind()) .name(subjectRef.getName()) .title(post.getSpec().getTitle()) .url(postUrl) .build(); // new-comment-on-post 用于表示 ReasonType 的 metadata.name notificationReasonEmitter.emit("new-comment-on-post", builder -> { // 定义了一个类型用于保存评论事件的数据,避免 map 的 key 写错 var attributes = CommentOnPostReasonData.builder() .postName(subjectRef.getName()) .postOwner(post.getSpec().getOwner()) .postTitle(post.getSpec().getTitle()) .postUrl(postUrl) .commenter(owner.getDisplayName()) .content(comment.getSpec().getContent()) .commentName(comment.getMetadata().getName()) .build(); // 将 CommentOnPostReasonData 转换为事件所需的 Map 类型数据 builder.attributes(toAttributeMap(attributes)) .author(identityFrom(owner)) .subject(reasonSubject); }).block(); } public static Map toAttributeMap(T data) { Assert.notNull(data, "Reason attributes must not be null"); return JsonUtils.mapper().convertValue(data, new TypeReference<>() { }); } ``` 参考 [Halo 评论事件触发](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/application/src/main/java/run/halo/app/content/comment/CommentNotificationReasonPublisher.java) ## 订阅通知 在 Halo 系统中,用户可以通过订阅通知来接收感兴趣的事件,并且可以使用表达式对事件进行过滤,确保只接收到符合条件的通知。 通过这种方式,用户可以精确订阅某些事件,并避免被无关的事件打扰。 订阅机制支持根据事件属性、主体对象和事件发起人来过滤事件,并使用 SpEL(Spring Expression Language)编写过滤表达式。 ### 订阅通知的工作机制 通知订阅机制允许用户订阅各种类型的事件(如文章发布、评论回复等),并且支持通过表达式过滤事件。 订阅系统可以通过以下三种根对象来筛选感兴趣的事件: - props:事件属性的根对象,表示事件携带的具体数据。例如,在评论回复事件中,属性可以是 `{repliedOwner: 'guqing'}`,可以通过 `props.repliedOwner` 来访问 `repliedOwner` 属性。 - subject:事件的主体对象,表示事件所关联的核心对象,字段同 `Reason` 中的 `spec.subject` 字段。例如,在“新评论”事件中,subject 是评论所属的文章。 - author:事件的发起人,表示触发事件的用户标识符,字符串类型。例如,在评论事件中,发起人是评论者。 通过这些对象,订阅者可以编写表达式来对事件进行过滤。 表达式的结果必须为布尔值,用于判断当前事件是否符合订阅者的条件。 ### 表达式过滤规则 使用 [SpEL](https://docs.spring.io/spring-framework/reference/core/expressions.html) 规范,开发者可以通过以下方式过滤事件: - props:访问事件的属性。例如,`props.repliedOwner == 'guqing'` 用于筛选事件属性中 repliedOwner 为 guqing 的事件。 - subject:访问事件主体的属性。例如,`subject.kind == 'Post'` 用于筛选主体为 Post 的事件。 - author:访问事件的发起人。例如,`author == 'guqing'` 用于筛选 guqing 发起的评事件。 ### 订阅方式 目前 Halo 没有提供用户界面来订阅通知,订阅均是通过事件发起前由开发者为用户创建的订阅对象来实现的。 因此,开发者需要在插件中实现订阅逻辑,为用户创建订阅对象,需要注意以下几点: 1. 订阅对象的创建需要在用户订阅事件前完成,否则用户无法接收到通知。 2. 哪些用户能够接收到通知需要开发者谨慎考虑,确保用户订阅的事件是符合其需求的,避免将无关的事件推送给用户。 3. 在创建订阅时,同样的逻辑反复执行不会重复创建订阅,因此可以在每次事件触发前订阅。 Halo 提供 `NotificationCenter` Bean 来帮助开发者创建订阅对象和取消订阅对象。 参考 [NotificationCenter Bean](https://docs.halo.run/developer-guide/plugin/basics/server/object-management.md#notificationcenter) `subscribe` 方法用于订阅事件,`unsubscribe` 方法用于取消订阅事件,第一个参数是订阅者,第二个参数是感兴趣的事件。 #### Subscription.Subscriber `Subscription.Subscriber` 具有以下属性: | 字段名 | 类型 | 是否必填 | 说明 | | ------ | -------- | ---- | ------------------------------------ | | `name` | `string` | 是 | 订阅者的用户名,或通过 `UserIdentity` 构建的匿名订阅标识 | #### Subscription.InterestReason `Subscription.InterestReason` 具有以下属性: | 字段名 | 类型 | 是否必填 | 说明 | | ------------ | -------- | ---- | ------------------------------------------------- | | `reasonType` | `string` | 是 | 感兴趣的事件类型的名称,对应于 `ReasonType` 的 `metadata.name` 字段 | | `expression` | `string` | 是 | 订阅事件的过滤表达式,用于过滤感兴趣的事件避免用户接收到不相关的通知 | 参考 [Subscription 自定义模型](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/core/extension/notification/Subscription.java) ### 示例 \{#subscribe-example} 以下是一个通过 Java 代码实现订阅文章“新评论”通知的示例。该示例展示了如何使用表达式来筛选事件,只接收特定文章下的评论通知。 ```java // step 0: 依赖注入 NotificationCenter private final NotificationCenter notificationCenter; Mono subscribeNewCommentOnPostNotification(String username) { // step1: 创建订阅者对象 var subscriber = new Subscription.Subscriber(); subscriber.setName(username); // 设置订阅者的用户名 // step2: 创建感兴趣的事件类型对象 var interestReason = new Subscription.InterestReason(); // 设置订阅的事件类型为“新评论” interestReason.setReasonType(NEW_COMMENT_ON_POST); // step3: 使用表达式过滤事件,props 是事件属性的根对象 // 只接收由指定用户创建的文章下的评论事件 interestReason.setExpression("props.repliedOwner == '%s'".formatted(username)); // step4: 订阅事件 return notificationCenter.subscribe(subscriber, interestReason); } ``` 在这个示例中,我们通过以下步骤实现了订阅: 1. 创建订阅者对象:通过 `Subscription.Subscriber()` 实例化一个订阅者对象,并为其设置订阅者的用户名。 2. 定义感兴趣的事件类型:使用 `Subscription.InterestReason()` 定义感兴趣的事件类型,这里使用 `NEW_COMMENT_ON_POST` 表示订阅“新评论”事件。 3. 使用表达式过滤事件:通过表达式 `props.repliedOwner == '%s'`,订阅者只会接收到`被评论者/回复者`是他们自己的评论通知。 4. 执行订阅操作:调用 `notificationCenter.subscribe(subscriber, interestReason)` 方法完成订阅操作。 参考 [Halo 评论订阅](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/application/src/main/java/run/halo/app/core/reconciler/CommentReconciler.java) ## 通知器 开发者可以通过 Halo 的通知器机制扩展通知的发送方式。 参考 [通知器扩展点](https://docs.halo.run/developer-guide/plugin/extension-points/server/notifier.md) --- url: https://docs.halo.run/developer-guide/plugin/api-reference/server/finder-for-theme.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 为主题提供数据 当你在插件中创建了自己的自定义模型时,你可能需要在主题模板中使用这些数据。或者,你提供一些额外的数据,以便主题可以使用它们,你可以通过创建一个自定义的 `finder` 来实现这一点。 在开始定义 Finder 前,可以先参考[与主题集成](https://docs.halo.run/developer-guide/plugin/theme-integration.md#%E9%80%89%E6%8B%A9%E9%9B%86%E6%88%90%E6%96%B9%E5%BC%8F),确认场景需要服务端模板数据而不是浏览器公开 API。 ## 创建一个 Finder 首先,你需要创建一个 `interface`,并在其中定义你需要提供给主题获取数据的方法,方法的返回值可以是 `Mono` 或 `Flux` 类型,例如: ```java public interface LinkFinder { Mono get(String linkName); Flux listAll(); } ``` 然后写一个实现类,实现这个 `interface`,并在类上添加 `@Finder` 注解,例如: ```java import run.halo.app.theme.finders.Finder; @Finder("myPluginLinkFinder") public class LinkFinderImpl implements LinkFinder { @Override public Mono get(String linkName) { // ... } @Override public Flux listAll() { // ... } } ``` `@Finder` 注解的值是你在主题中使用的名称,例如,你可以在主题中使用 `myPluginLinkFinder.get('a-link-name')` 来获取数据,`myPluginLinkFinder` 就是你在 `@Finder` 注解中定义的名称。 ## Finder 命名 为了避免与其他插件的 `finder` 名称冲突,建议在 `@Finder` 注解中添加一个你插件名称的前缀作为 `finder` 名称且名称需要是驼峰式的,不能包含除了 `_` 之外的其他特殊字符。 例如,你的插件名称是 `my_plugin`,你需要为主题提供一个获取链接的 `finder`,那么你可以这样定义 `@Finder` 注解: ```java @Finder("myPluginLinkFinder") ``` ## 使用 Finder 在主题中,你可以通过 `finder` 名称和方法名及对应的参数来获取数据,例如: ```html
``` 模板语法参考:[Thymeleaf](https://www.thymeleaf.org/doc/tutorials/3.1/usingthymeleaf.html#standard-expression-syntax)。 --- url: https://docs.halo.run/developer-guide/plugin/api-reference/server/template-for-theme.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 在插件中提供主题模板 当你在插件中创建了自己的自定义模型后,你可能需要在主题端提供一个模板来展示这些数据,这一般有两种方式: 1. 插件规定模板名称,由主题选择性适配,如瞬间插件提供了 `/moments` 的路由渲染 `moments.html` 模板,主题可以选择性地提供 `moments.html` 模板来展示瞬间数据。 2. 插件提供默认模板,当主题没有提供对应的模板时,使用默认模板,主题提供了对应的模板时,使用主题提供的模板。 ## 创建一个模板 首先,你需要在插件的 `resources` 目录下创建一个 `templates` 目录,然后在 `templates` 目录下提供你的模板,例如: ```tree ├── templates │ ├── moments.html ``` 然后提供一个路由用于渲染这个模板,例如: ```java import run.halo.app.theme.TemplateNameResolver; import run.halo.app.theme.router.ModelConst; @RequiredArgsConstructor @Configuration(proxyBeanMethods = false) public class MomentRouter { private final TemplateNameResolver templateNameResolver; @Bean RouterFunction momentRouterFunction() { return route(GET("/moments"), this::renderMomentPage).build(); } Mono renderMomentPage(ServerRequest request) { // 或许你需要准备你需要提供给模板的默认数据,非必须 var model = new HashMap(); model.put("moments", List.of()); model.put(ModelConst.TEMPLATE_ID, "plugin:plugin-moment:moments"); return templateNameResolver.resolveTemplateNameOrDefault(request.exchange(), "moments") .flatMap(templateName -> ServerResponse.ok().render(templateName, model)); } } ``` 使用 `TemplateNameResolver` 来解析模板名称,如果主题提供了对应的模板,那么就使用主题提供的模板,否则使用插件提供的模板,如果直接返回模板名称,那么只会使用主题提供的模板,如果主题没有提供对应的模板,那么会抛出异常。 `ModelConst.TEMPLATE_ID` 对应模板变量 `_templateId`。建议使用 `plugin::` 形式的稳定值,便于 Head 处理器、SEO 插件和其他渲染扩展识别插件页面。模板名称、模型字段和 `_templateId` 都属于主题集成契约,不应在兼容版本中随意修改。 ## 复用当前主题页面布局 从 Halo 2.26.0 开始,如果插件提供的前台页面希望复用当前主题的页头、页脚和整体页面外壳,可以在插件模板中调用 `layout :: html(...)`: ```html title="src/main/resources/templates/moments.html" 瞬间 - [[${site.title}]]
``` `layout` 是 Halo 保留的集成模板名。当当前主题提供符合契约的 `templates/layout.html` 时,插件页面会使用主题布局;否则会使用 Halo 内置的 fallback 布局。完整契约可参考[页面布局契约](https://docs.halo.run/developer-guide/theme/page-layout.md)。 ## 模板片段 如果你的默认模板不止一个,你可能需要通过模板片段来抽取一些公共的部分,例如,你的插件提供了一个 `moments.html` 模板,你可能需要抽取一些公共的部分,例如头部、尾部等,你可以这样做: ```tree ├── templates │ ├── moments.html │ ├── fragments │ │ ├── layout.html ``` 然后定义一个 `layout.html` 模板,例如: ```html Moment
``` 那么使用 `layout.html` 模板中提供的 `fragment` 时,你需要这样做: ```html
Hello World
``` `plugin:plugin-moment:fragments/layout` 即为使用 `layout.html` 模板的路径,必须以 `plugin::`前缀作为开头,`fragments/layout` 为模板相对于 `resources/templates` 的路径,`` 即为你的插件名称。 **总结:** 1. 定义模板片段时与主题端定义模板片段时一样 2. 使用模板片段时,必须以 `plugin::` 前缀作为开头,后跟模板相对于 `resources/templates` 的路径,例如 `plugin:plugin-moment:fragments/layout`,`plugin-moment` 即为你的插件名称,`fragments/layout` 为模板相对于 `resources/templates` 的路径。 参考:[Thymeleaf 模板片段](https://www.thymeleaf.org/doc/tutorials/3.1/usingthymeleaf.html#including-template-fragments) --- url: https://docs.halo.run/developer-guide/plugin/api-reference/server/websocket.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 实现 WebSocket 从 Halo 2.15.0 版本开始,核心提供了 WebSocketEndpoint 接口,其主要目的是为了方便插件实现 WebSocket 功能。 插件只需要实现这个接口,并添加 `@Component` 注解,WebSocket 实现将会在插件启动后生效,插件卸载后,该实现也会随之删除。 在插件中实现 WebSocket 的代码样例如下: ```java @Component public class MyWebSocketEndpoint implements WebSocketEndpoint { @Override public GroupVersion groupVersion() { return GroupVersion.parseApiVersion("my-plugin.halowrite.com/v1alpha1"); } @Override public String urlPath() { return "/resources"; } @Override public WebSocketHandler handler() { return session -> { var messages = session.receive() .map(message -> { var payload = message.getPayloadAsText(); return session.textMessage(payload.toUpperCase()); }); return session.send(messages); }; } } ``` 当插件安装成功后,可以通过路径 `/apis/my-plugin.halowrite.com/v1alpha1/resources` 访问。示例如下: ```bash websocat --basic-auth admin:admin ws://127.0.0.1:8090/apis/my-plugin.halowrite.com/v1alpha1/resources ``` 需要注意的是,插件中实现的 WebSocket 相关的 API 仍然受当前权限系统约束。 --- url: https://docs.halo.run/developer-guide/plugin/api-reference/server/login-handler-enhancer.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 登录增强 ## 背景 在 Halo 中,插件可以实现多种登录方式,例如 LDAP、第三方登录等。然而,灵活的登录方式也带来了以下问题: 1. 登录逻辑难以统一:例如登录成功后需要进行额外处理,这需要插件自行实现。 2. Halo 或其他插件无法知晓登录状态:无法记录登录日志等额外处理。 3. 新增安全特性适配:Halo 增加了新安全特性,插件需要适配才能使用,如在记住我机制中需要在登录成功后设置 remember-me cookie。 为了解决这些问题,Halo 提供了登录增强机制,插件可以在登录成功或失败时调用登录增强器,使 Halo 可以执行额外的处理逻辑。随着 Halo 的版本更新,这些逻辑也会更新,而插件无需做任何修改。 ### 登录增强器 Halo 提供了一个 LoginHandlerEnhancer 的 Bean,插件可以通过依赖注入的方式在合适的位置调用该 Bean 的方法,以便 Halo 可以在登录成功或失败后执行逻辑切入。 ```java public interface LoginHandlerEnhancer { /** * Invoked when login success. * * @param exchange The exchange. * @param successfulAuthentication The successful authentication. */ Mono onLoginSuccess(ServerWebExchange exchange, Authentication successfulAuthentication); /** * Invoked when login fails. * * @param exchange The exchange. * @param exception the reason authentication failed */ Mono onLoginFailure(ServerWebExchange exchange, AuthenticationException exception); } ``` 如果插件自定义了认证过滤器或登录端点,可以先调用登录增强器,再委托给自己的成功或失败处理器: ```java @RequiredArgsConstructor public class PluginAuthenticationHandler implements ServerAuthenticationSuccessHandler, ServerAuthenticationFailureHandler { private final LoginHandlerEnhancer loginHandlerEnhancer; private final ServerAuthenticationSuccessHandler delegateSuccessHandler; private final ServerAuthenticationFailureHandler delegateFailureHandler; @Override public Mono onAuthenticationFailure( WebFilterExchange webFilterExchange, AuthenticationException exception ) { var exchange = webFilterExchange.getExchange(); return loginHandlerEnhancer.onLoginFailure(exchange, exception) .then(delegateFailureHandler.onAuthenticationFailure( webFilterExchange, exception )); } @Override public Mono onAuthenticationSuccess( WebFilterExchange webFilterExchange, Authentication authentication ) { var exchange = webFilterExchange.getExchange(); return loginHandlerEnhancer.onLoginSuccess(exchange, authentication) .then(delegateSuccessHandler.onAuthenticationSuccess( webFilterExchange, authentication )); } } ``` 设备管理、记住我等机制都依赖登录增强器。每次认证结果只应调用一次:仅实现 `UsernamePasswordAuthenticationManager` 时,Halo 内置的成功和失败处理器已经负责调用,无需在认证管理器中重复调用;自行处理完整登录流程时才需要显式调用。 源码参考:[登录成功处理器](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/application/src/main/java/run/halo/app/security/authentication/LoginSuccessHandler.java)、[登录失败处理器](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/application/src/main/java/run/halo/app/security/authentication/LoginFailureHandler.java)。 --- url: https://docs.halo.run/developer-guide/plugin/api-reference/server/extension-getter.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 获取扩展 `ExtensionGetter` 用于获取和管理 Halo 或其他插件提供的扩展。它提供了多种方法来根据扩展点获取扩展,确保插件能够灵活地集成和使用各种扩展功能。 `ExtensionGetter` 接口的定义如下: ```java public interface ExtensionGetter { /** * Get only one enabled extension from system configuration. * * @param extensionPoint is extension point class. * @return implementation of the corresponding extension point. If no configuration is found, * we will use the default implementation from application context instead. */ Mono getEnabledExtension(Class extensionPoint); /** * Get the extension(s) according to the {@link ExtensionPointDefinition} queried * by incoming extension point class. * * @param extensionPoint extension point class * @return implementations of the corresponding extension point. * @throws IllegalArgumentException if the incoming extension point class does not have * the {@link ExtensionPointDefinition}. */ Flux getEnabledExtensions(Class extensionPoint); /** * Get all extensions according to extension point class. * * @param extensionPointClass extension point class * @param type of extension point * @return a bunch of extension points. */ Flux getExtensions(Class extensionPointClass); } ``` 包含以下方法: 1. `getEnabledExtension(Class extensionPoint)`: 获取一个在扩展设置中已启用的扩展。如果没有找到对应配置,将使用 Halo 中的默认扩展,如果 Halo 没有提供默认实现则找到一个由**已启用插件**提供的可用扩展。 2. `getEnabledExtensions(Class extensionPoint)`: 根据传入的扩展点类获取所有已启用扩展。如果没有在扩展设置页面配置过则会返回所有可用的扩展。 3. `getExtensions(Class extensionPointClass)`: 获取所有与扩展点类相关的扩展,无论是否在扩展设置中启用它。 :::tip 根据扩展点类型选择方法 使用 `getEnabledExtension` 方法或者 `getEnabledExtensions` 方法取决于扩展点声明的 `type` 是 `SINGLETON` 还是 `MULTI_INSTANCE`。 通过使用 `ExtensionGetter`,开发者可以轻松地在插件中访问和管理各种扩展点,提升插件的功能和灵活性。 如果想了解 Halo 提供的扩展点请参考:[扩展点](https://docs.halo.run/developer-guide/plugin/extension-points/server/index.md)。 ::: ### 示例 如果你想在插件中获取已启用的搜索引擎扩展,可以使用 `ExtensionGetter` 来获取: ```java @Service @RequiredArgsConstructor public class SearchService { private final ExtensionGetter extensionGetter; Mono getSearchEngine() { return extensionGetter.getEnabledExtension(SearchEngine.class) } } ``` --- url: https://docs.halo.run/developer-guide/plugin/api-reference/ui/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # UI API 参考 ## 路由定义 ### [路由定义](/developer-guide/plugin/api-reference/ui/route.md) - [定义方式](/developer-guide/plugin/api-reference/ui/route.md#定义方式) - [类型定义](/developer-guide/plugin/api-reference/ui/route.md#类型定义) ## API 请求 ### [API 请求](/developer-guide/plugin/api-reference/ui/api-request.md) - [选择客户端](/developer-guide/plugin/api-reference/ui/api-request.md#选择客户端) - [使用插件生成的 API Client](/developer-guide/plugin/api-reference/ui/api-request.md#使用插件生成的-api-client) - [使用 Halo API Client](/developer-guide/plugin/api-reference/ui/api-request.md#使用-halo-api-client) - [直接使用 axiosInstance](/developer-guide/plugin/api-reference/ui/api-request.md#直接使用-axiosinstance) ## FormKit 扩展 ### [FormKit 扩展](/developer-guide/plugin/api-reference/ui/formkit.md) - [注册输入组件](/developer-guide/plugin/api-reference/ui/formkit.md#注册输入组件) - [在 FormKit Schema 中使用](/developer-guide/plugin/api-reference/ui/formkit.md#在-formkit-schema-中使用) - [注意事项](/developer-guide/plugin/api-reference/ui/formkit.md#注意事项) ## 共享工具库 ### [共享工具库](/developer-guide/plugin/api-reference/ui/shared.md) - [stores](/developer-guide/plugin/api-reference/ui/shared.md#stores) - [utils](/developer-guide/plugin/api-reference/ui/shared.md#utils) - [events](/developer-guide/plugin/api-reference/ui/shared.md#events) ## 组件 ### [UppyUpload](/developer-guide/plugin/api-reference/ui/components/uppy-upload.md) - [使用方式](/developer-guide/plugin/api-reference/ui/components/uppy-upload.md#使用方式) - [Props](/developer-guide/plugin/api-reference/ui/components/uppy-upload.md#props) - [Emits](/developer-guide/plugin/api-reference/ui/components/uppy-upload.md#emits) ### [FilterDropdown](/developer-guide/plugin/api-reference/ui/components/filter-dropdown.md) - [使用示例](/developer-guide/plugin/api-reference/ui/components/filter-dropdown.md#使用示例) - [Props](/developer-guide/plugin/api-reference/ui/components/filter-dropdown.md#props) - [Emits](/developer-guide/plugin/api-reference/ui/components/filter-dropdown.md#emits) ### [FilterCleanButton](/developer-guide/plugin/api-reference/ui/components/filter-clean-button.md) - [使用示例](/developer-guide/plugin/api-reference/ui/components/filter-clean-button.md#使用示例) ### [AnnotationsForm](/developer-guide/plugin/api-reference/ui/components/annotations-form.md) - [使用示例](/developer-guide/plugin/api-reference/ui/components/annotations-form.md#使用示例) - [Props](/developer-guide/plugin/api-reference/ui/components/annotations-form.md#props) ### [AttachmentFileTypeIcon](/developer-guide/plugin/api-reference/ui/components/attachment-file-type-icon.md) - [使用示例](/developer-guide/plugin/api-reference/ui/components/attachment-file-type-icon.md#使用示例) - [Props](/developer-guide/plugin/api-reference/ui/components/attachment-file-type-icon.md#props) ### [AttachmentSelectorModal](/developer-guide/plugin/api-reference/ui/components/attachment-selector-modal.md) - [使用示例](/developer-guide/plugin/api-reference/ui/components/attachment-selector-modal.md#使用示例) - [Props](/developer-guide/plugin/api-reference/ui/components/attachment-selector-modal.md#props) - [Emits](/developer-guide/plugin/api-reference/ui/components/attachment-selector-modal.md#emits) ### [HasPermission](/developer-guide/plugin/api-reference/ui/components/has-permission.md) - [使用方式](/developer-guide/plugin/api-reference/ui/components/has-permission.md#使用方式) - [Props](/developer-guide/plugin/api-reference/ui/components/has-permission.md#props) ### [SearchInput](/developer-guide/plugin/api-reference/ui/components/search-input.md) - [使用方式](/developer-guide/plugin/api-reference/ui/components/search-input.md#使用方式) - [Props](/developer-guide/plugin/api-reference/ui/components/search-input.md#props) - [Emits](/developer-guide/plugin/api-reference/ui/components/search-input.md#emits) ### [PluginDetailModal](/developer-guide/plugin/api-reference/ui/components/plugin-detail-modal.md) - [使用方式](/developer-guide/plugin/api-reference/ui/components/plugin-detail-modal.md#使用方式) - [Props](/developer-guide/plugin/api-reference/ui/components/plugin-detail-modal.md#props) ### [VCodemirror](/developer-guide/plugin/api-reference/ui/components/v-codemirror.md) - [使用方式](/developer-guide/plugin/api-reference/ui/components/v-codemirror.md#使用方式) - [Props](/developer-guide/plugin/api-reference/ui/components/v-codemirror.md#props) - [Emits](/developer-guide/plugin/api-reference/ui/components/v-codemirror.md#emits) ### [v-tooltip](/developer-guide/plugin/api-reference/ui/components/v-tooltip.md) - [使用方式](/developer-guide/plugin/api-reference/ui/components/v-tooltip.md#使用方式) ### [v-permission](/developer-guide/plugin/api-reference/ui/components/v-permission.md) - [使用方式](/developer-guide/plugin/api-reference/ui/components/v-permission.md#使用方式) --- url: https://docs.halo.run/developer-guide/plugin/api-reference/ui/route.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 路由定义 Halo 为插件提供了为 Console 控制台和 UC 个人中心添加新路由的入口,可以用于为插件单独提供一个页面。 此文档将介绍如何定义路由以及侧边菜单项。 ## 定义方式 Console 控制台和 UC 个人中心的路由定义基本和 Vue Router 官方的保持一致,为了区分 Console 控制台和 UC 个人中心的路由,Halo 为插件提供了两个不同的路由定义入口。 - `routes`:Console 控制台路由定义 - `ucRoutes`:UC 个人中心路由定义 ```ts import HomeView from "./views/HomeView.vue"; import { IconComputer } from "@halo-dev/components"; export default definePlugin({ routes: [ // Console 控制台路由定义 { parentName: "Root", route: { path: "/foo", name: "Foo", component: HomeView, meta: { permissions: [""], menu: { name: "Foo", group: "content", icon: markRaw(IconComputer), priority: 40, }, }, }, }, ], ucRoutes: [ // UC 个人中心路由定义 { parentName: "Root", route: { path: "/uc-foo", name: "FooUC", component: HomeView, meta: { permissions: [""], menu: { name: "FooUC", group: "content", icon: markRaw(IconComputer), priority: 40, }, }, }, }, ], }); ``` ## 类型定义 ```ts { routes?: RouteRecordRaw[] | RouteRecordAppend[]; ucRoutes?: RouteRecordRaw[] | RouteRecordAppend[]; } ``` ```ts export interface RouteRecordAppend { parentName: RouteRecordName; route: RouteRecordRaw; } ``` - `parentName`:父路由名称,主要用于确认页面 Layout,如果想要添加到顶级路由,可以设置为 `Root`。如果不需要设置父路由,可以完全使用 `RouteRecordRaw` 定义。此外,如果同时设置了 `parentName` 以及其下路由设置了 `meta.menu`,那么此路由的菜单项将成为父菜单的子菜单项,可支持的父路由名称如下: - Console: - `AttachmentsRoot`(附件) - `CommentsRoot`(评论) - `SinglePagesRoot`(页面) - `PostsRoot`(文章) - `MenusRoot`(菜单) - `ThemeRoot`(主题) - `OverviewRoot`(概览) - `BackupRoot`(备份) - `PluginsRoot`(插件) - `SettingsRoot`(设置) - `UsersRoot`(用户) - `ToolsRoot`(工具) - UC: - `PostsRoot`(文章) - `NotificationsRoot`(消息) :::info RouteRecordRaw 类型来源 `RouteRecordRaw` 来自 Vue Router,详见 [API 文档 | Vue Router](https://router.vuejs.org/zh/api/#Type-Aliases-RouteRecordRaw) ::: 此外,为了方便插件在 Console 控制台和 UC 个人中心添加菜单项等操作,Halo 为 `RouteRecordRaw` 添加了 `meta` 属性,该属性为 `RouteMeta` 类型,定义如下: ```ts interface RouteMeta { title?: string; // 浏览器标题 searchable?: boolean; // 是否可以在 Console 的全局搜索中搜索到 permissions?: string[]; // UI 权限 menu?: { // 侧边菜单配置 name: string; // 菜单名称 group?: CoreMenuGroupId; // 内置菜单分组 ID,如果不使用内置的分组,也可以直接填写分组名称 icon?: Component; // 菜单图标,类型为 Vue 组件,推荐使用 https://github.com/unplugin/unplugin-icons priority: number; // 菜单项排序,数字越小越靠前 mobile?: boolean; // 是否在移动端显示 }; } ``` ```ts export type CoreMenuGroupId = "dashboard" | "content" | "interface" | "system" | "tool"; ``` --- url: https://docs.halo.run/developer-guide/plugin/api-reference/ui/api-request.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # API 请求 Halo 插件 UI 通常需要调用插件自己的接口和 Halo Core 接口。先根据接口归属选择客户端,不要为 Halo 请求自行创建 Axios 实例或手写可生成的资源类型和路径。 ## 选择客户端 | 接口 | 推荐方式 | | ------------------------------------- | -------------------------------------------- | | 插件自定义模型的 CRUD API | 使用 `generateApiClient` 生成的模型和 API 类 | | 插件通过 `SpringdocRouteBuilder` 描述的自定义端点 | 使用 `generateApiClient` 生成的 API 类 | | Halo Core、Console、用户中心或公开 API | 使用 `@halo-dev/api-client` 已提供的客户端 | | 暂时没有 OpenAPI 描述的一次性插件接口 | 最后才直接使用 `axiosInstance` | | 与 Halo 无关的独立外部服务 | 根据该服务要求创建独立客户端,不复用或修改 Halo 的 `axiosInstance` | ## 使用插件生成的 API Client 插件的 Java 模型是 API 类型的来源。自定义模型会生成 CRUD API;自定义端点需要使用 `SpringdocRouteBuilder` 定义稳定的 `operationId`、参数和响应,才能进入 OpenAPI 文档。 在 `build.gradle` 中配置 `haloPlugin.openApi` 后运行: ```shell ./gradlew generateApiClient ``` 完整的分组、生成目录和任务说明参考[开发工具 > 生成 API client](https://docs.halo.run/developer-guide/plugin/basics/devtools.md#how-to-generate-api-client)。生成目录必须专用于 API Client,不要手动编辑其中的类型或请求代码。 为生成的类复用 Halo 已配置认证和统一错误处理的 `axiosInstance`: ```ts title="ui/src/api/index.ts" import { axiosInstance } from "@halo-dev/api-client"; import { TodoV1alpha1Api } from "./generated"; const todoCoreApiClient = { todo: new TodoV1alpha1Api(undefined, "", axiosInstance), }; export { todoCoreApiClient }; ``` 调用方法时使用生成的请求参数和响应类型: ```ts import { todoCoreApiClient } from "@/api"; const { data } = await todoCoreApiClient.todo.listTodo({ page: 1, size: 20 }); ``` 当接口或模型变化时,修改 Java 源码或 OpenAPI 描述并重新运行生成任务。不要在 UI 中复制 `Metadata`、资源模型、列表结果或接口参数来绕过生成器。 ## 使用 Halo API Client 从 Halo 2.17.0 开始,`@halo-dev/api-client` 提供以下客户端: ```ts import { axiosInstance, consoleApiClient, coreApiClient, publicApiClient, ucApiClient, } from "@halo-dev/api-client"; ``` - `coreApiClient`:Halo 自定义模型 CRUD API。 - `consoleApiClient`:Halo Console API。 - `ucApiClient`:Halo 用户中心 API。 - `publicApiClient`:Halo 公开 API。 - `axiosInstance`:带有 Halo 认证和统一错误处理的 Axios 实例。 调用 Halo 已提供的接口无需配置基础地址: ```ts import { coreApiClient } from "@halo-dev/api-client"; const { data } = await coreApiClient.content.post.listPost({ page: 1, size: 20, }); ``` ## 直接使用 axiosInstance 只有接口暂时无法进入 OpenAPI 且调用点很少时,才直接使用路径: ```ts import { axiosInstance } from "@halo-dev/api-client"; const { data } = await axiosInstance.get("/apis/foo.halo.run/v1alpha1/bar"); ``` 当该接口需要复用、拥有稳定模型或包含多个参数时,应补充 OpenAPI 描述并改用生成客户端。 不要为 `/api` 或 `/apis` 下的 Halo 请求调用 `axios.create()`。从 `axios` 直接创建的实例不包含 Halo 登录状态、权限失败和统一错误处理配置;也不要修改 `axiosInstance` 的全局 defaults 或 interceptors。 `@halo-dev/ui-plugin-bundler-kit` 会让插件复用 Halo 提供的 `@halo-dev/api-client` 和 Axios。旧版 IIFE 通过兼容全局对象提供依赖,Halo 2.26.0 开始支持的 ESM 通过共享运行时模块提供,插件代码都应继续使用标准包导入。 :::info 同步提高 Halo 版本要求 如果插件使用 `@halo-dev/api-client@2.17.0` 或更高版本,需要让 `plugin.yaml` 的 `spec.requires` 覆盖对应 Halo 版本。新项目应以脚手架生成的依赖和版本要求为准。 ::: --- url: https://docs.halo.run/developer-guide/plugin/api-reference/ui/formkit.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # FormKit 扩展 从 Halo 2.25.0 开始,插件可以通过 UI 入口文件的 `formkit.inputs` 注册自定义 FormKit 输入组件。注册后,插件提供的 FormKit Schema 可以通过 `$formkit` 使用对应类型。 关于如何创建 FormKit 自定义输入组件,可参考 FormKit 官方文档:[Create a custom input](https://formkit.com/guides/create-a-custom-input)。 ## 注册输入组件 ```ts title="ui/src/index.ts" import { createInput } from "@formkit/vue"; import { definePlugin } from "@halo-dev/ui-shared"; import { defineAsyncComponent } from "vue"; export default definePlugin({ formkit: { inputs: { myPluginInput: createInput( defineAsyncComponent(() => import("./components/MyPluginInput.vue")), ), }, }, }); ``` ## 在 FormKit Schema 中使用 ```yaml - $formkit: myPluginInput name: customField label: 自定义字段 ``` ## 注意事项 `formkit.inputs` 仅支持同步对象。如果输入组件需要懒加载,可以在 input definition 内部使用 `defineAsyncComponent`。 当插件注册的输入类型名称与 Halo 内置类型或更早加载的插件类型重复时,Halo 会保留已有类型,跳过冲突的插件类型并在控制台输出警告。建议使用带插件标识的类型名称,例如 `myPluginInput`。 --- url: https://docs.halo.run/developer-guide/plugin/api-reference/ui/shared.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 共享工具库 从 Halo 2.22 开始,Halo 为插件的 UI 部分提供了共享的工具库并放置在了 `@halo-dev/ui-shared` 中,利用这些工具,可以减少部分开发工作量。 使用这些工具需要将插件项目的 `@halo-dev/ui-shared`(前 [@halo-dev/console-shared](https://docs.halo.run/developer-guide/plugin/api-changelog.md#halo-devconsole-shared-%E6%94%B9%E5%90%8D))依赖升级到 2.22.0。并在发布新版本插件时,将 [plugin.yaml#spec.requires](https://docs.halo.run/developer-guide/plugin/basics/manifest.md#%E5%AD%97%E6%AE%B5%E8%AF%A6%E8%A7%A3) 提升到 `>=2.22.0`。 ## stores 用于共享常用的全局状态,使用此工具,需要先安装 Pinia 依赖: ```bash pnpm install pinia ``` ### uiPlugins 从 Halo 2.26.0 开始,可以通过 `stores.uiPlugins()` 查询当前页面发现的插件和已激活主题的 UI provider 状态。使用此 API 时,需要将 `@halo-dev/ui-shared` 和 `@halo-dev/ui-plugin-bundler-kit` 升级到 2.26.0 或更高版本,并将插件的 `spec.requires` 设置为不低于 Halo 2.26.0。 ```ts import { stores } from "@halo-dev/ui-shared"; import { computed } from "vue"; const uiPlugins = stores.uiPlugins(); // 是否在当前 provider 列表中 uiPlugins.isEnabled("plugin-search"); // 当前页面中是否已经成功注册 const searchRegistered = computed(() => uiPlugins.isRegistered("plugin-search"), ); // 读取 Halo 提供的只读状态 uiPlugins.get("plugin-search"); ``` 主题 provider 使用 `theme:{metadata.name}` 作为名称,例如 `theme:theme-earth`。 #### 属性 - `registrations`:只读的 provider 注册记录列表。 每条记录包含: ```ts interface UiPluginRegistration { name: string; type: "plugin" | "theme"; version: string; status: "pending" | "registered" | "failed"; } ``` #### 方法 - `get(name)`:返回指定 provider 的只读注册记录,不存在时返回 `undefined`。 - `isEnabled(name)`:是否在当前页面的 provider 描述中被发现,不代表其 UI 已经注册成功。 - `isRegistered(name)`:当前页面中是否已经成功完成 UI 注册。 该 store 由 Halo 管理,插件不应尝试修改注册记录,也不应依赖 provider 的加载或注册顺序。需要检测其他插件是否启用时,应使用 `isEnabled` 代替 `window.PluginName` 或 `window.enabledUiPlugins`;不支持通过该 store 获取、调用或导入其他 provider 的 `PluginModule`。 ### currentUser 用于获取当前登录用户的信息,示例: ```vue title="ui/src/MyComponent.vue" ``` #### 属性 - `currentUser`: 当前登录用户的详细信息,类型为 `DetailedUser | undefined` - `isAnonymous`: 是否为匿名用户,类型为 `boolean` #### 方法 - `fetchCurrentUser()`: 从服务器获取当前用户信息,返回 `Promise` ### globalInfo 用于获取当前网站的全局配置信息,示例: ```vue title="ui/src/MyComponent.vue" ``` #### 属性 - `globalInfo`: 全局配置信息,类型为 `GlobalInfo | undefined`,包含以下字段: - `externalUrl`: 外部访问地址 - `siteTitle`: 站点标题 - `timeZone`: 时区 - `locale`: 语言区域 - `allowComments`: 是否允许评论 - `allowAnonymousComments`: 是否允许匿名评论 - `allowRegistration`: 是否允许注册 - `useAbsolutePermalink`: 是否使用绝对路径 - `userInitialized`: 用户是否已初始化 - `dataInitialized`: 数据是否已初始化 - `favicon`: 网站图标 - `postSlugGenerationStrategy`: 文章 Slug 生成策略 - `mustVerifyEmailOnRegistration`: 注册时是否必须验证邮箱 - `socialAuthProviders`: 社交认证提供商列表 #### 方法 - `fetchGlobalInfo()`: 从服务器获取全局配置信息,返回 `Promise` ## utils 提供了一些常用的工具方法,包括时间日期格式化、权限判断、附件处理、ID 生成等。 ### date 日期时间处理工具,基于 [dayjs](https://day.js.org/) 实现。 #### format(date, format?) 格式化日期为字符串。 **参数:** - `date`: 要格式化的日期(string | Date | undefined | null) - `format`: 格式化字符串,默认为 `"YYYY-MM-DD HH:mm"` **返回值:** 格式化后的日期字符串,如果日期为空则返回空字符串 **示例:** ```ts import { utils } from "@halo-dev/ui-shared"; utils.date.format(new Date()); // "2025-11-05 14:30" utils.date.format("2025-10-22", "YYYY/MM/DD"); // "2025/10/22" utils.date.format(null); // "" ``` #### toISOString(date) 将日期转换为 ISO 8601 格式字符串。 **参数:** - `date`: 要转换的日期(string | Date | undefined | null) **返回值:** ISO 8601 格式的日期字符串 **示例:** ```ts import { utils } from "@halo-dev/ui-shared"; utils.date.toISOString(new Date("2025-10-22")); // "2025-10-22T00:00:00.000Z" ``` #### toDatetimeLocal(date) 将日期转换为 HTML5 datetime-local 输入框格式。 **参数:** - `date`: 要转换的日期(string | Date | undefined | null) **返回值:** datetime-local 格式的字符串(YYYY-MM-DDTHH:mm) **示例:** ```ts import { utils } from "@halo-dev/ui-shared"; utils.date.toDatetimeLocal(new Date("2025-10-22 14:30")); // "2025-10-22T14:30" ``` #### timeAgo(date) 获取从当前时间到指定日期的相对时间描述。 **参数:** - `date`: 目标日期(string | Date | undefined | null) **返回值:** 人类可读的相对时间字符串(如 "2 小时后"、"3 天前") **示例:** ```ts import { utils } from "@halo-dev/ui-shared"; // 假设当前时间是 2025-10-22 utils.date.timeAgo("2025-10-23"); // "1 天后" utils.date.timeAgo("2025-10-21"); // "1 天前" utils.date.timeAgo("2025-11-22"); // "1 个月后" ``` #### dayjs() 原始的 dayjs 实例,如果上述方法不能满足需求,可以手动调用 dayjs 方法,具体使用文档可查阅:[Day.js](https://day.js.org/zh-CN/)。 ### permission 权限判断工具,用于检查当前用户是否具有指定的权限。 #### has(permissions, any?) 检查用户是否具有指定的权限。 **参数:** - `permissions`: 要检查的权限数组(Array\) - `any`: 是否满足任意一个权限即可,默认为 `true` - `true`: 只要有任意一个权限匹配即返回 true - `false`: 必须所有权限都匹配才返回 true **返回值:** boolean **特殊情况:** - 如果用户拥有通配符权限 `*`,则始终返回 true - 如果不需要检查任何权限(空数组),则返回 true - 如果用户没有任何权限,则返回 false **示例:** ```ts import { utils } from "@halo-dev/ui-shared"; // 检查是否拥有任意一个权限 utils.permission.has(["core:posts:manage"], true); // true utils.permission.has(["core:posts:delete"], true); // false // 检查是否拥有所有权限 utils.permission.has(["core:posts:manage", "core:attachments:view"], false); // true utils.permission.has(["core:posts:manage", "core:posts:delete"], false); // false ``` #### getUserPermissions() 获取当前设置的用户权限列表。 **返回值:** Array\ | undefined **示例:** ```ts import { utils } from "@halo-dev/ui-shared"; const permissions = utils.permission.getUserPermissions(); console.log(permissions); // ["core:posts:manage", "core:attachments:view"] ``` ### attachment 附件处理工具,提供附件 URL 获取、缩略图获取、数据格式转换等功能。 #### getThumbnailUrl(url, size) 为指定的图片 URL 生成缩略图 URL。 **参数:** - `url`: 原始图片 URL(string) - `size`: 缩略图尺寸("XL" | "L" | "M" | "S") - `"XL"`: 1600px - `"L"`: 1200px - `"M"`: 800px - `"S"`: 400px **返回值:** 缩略图 URL(string) **处理逻辑:** 1. 如果 URL 是当前域名或相对路径:添加 `?width={尺寸}` 查询参数 2. 如果 URL 是外部链接:通过 Halo 的缩略图 API 代理 **示例:** ```ts import { utils } from "@halo-dev/ui-shared"; // 本地图片 utils.attachment.getThumbnailUrl("/uploads/image.jpg", "M"); // 返回: "/uploads/image.jpg?width=800" // 当前域名图片 utils.attachment.getThumbnailUrl("https://example.com/image.jpg", "S"); // 返回: "https://example.com/image.jpg?width=400" (如果当前域名是 example.com) ``` #### getUrl(attachment) 从附件对象中提取 URL。 **参数:** - `attachment`: 附件对象(string | Attachment | AttachmentSimple) **返回值:** URL 字符串(string | undefined) **示例:** ```ts import { utils } from "@halo-dev/ui-shared"; // 字符串 URL utils.attachment.getUrl("https://example.com/image.jpg"); // 返回: "https://example.com/image.jpg" // Attachment 对象 utils.attachment.getUrl(attachmentObject); // 返回: attachmentObject.status?.permalink // AttachmentSimple 对象 utils.attachment.getUrl({ url: "https://example.com/image.jpg" }); // 返回: "https://example.com/image.jpg" ``` #### convertToSimple(attachment) 将附件对象转换为简化格式。 **参数:** - `attachment`: 附件对象(string | Attachment | AttachmentSimple) **返回值:** AttachmentSimple | undefined **AttachmentSimple 类型:** ```ts interface AttachmentSimple { url: string; alt?: string; mediaType?: string; } ``` **示例:** ```ts import { utils } from "@halo-dev/ui-shared"; // 字符串 URL utils.attachment.convertToSimple("https://example.com/image.jpg"); // 返回: { url: "https://example.com/image.jpg" } // Attachment 对象 utils.attachment.convertToSimple(attachmentObject); // 返回: { // url: attachmentObject.status?.permalink || "", // alt: attachmentObject.spec.displayName, // mediaType: attachmentObject.spec.mediaType // } // AttachmentSimple 对象 utils.attachment.convertToSimple({ url: "https://example.com/image.jpg", alt: "Image", }); // 返回: { url: "https://example.com/image.jpg", alt: "Image" } ``` ### id ID 生成工具,用于生成唯一且可排序的标识符。基于 [uuid](https://github.com/uuidjs/uuid) 包实现。 #### uuid() 生成一个 RFC 4122 版本 7 的 UUID 字符串。 **返回值:** UUID v7 字符串(string) **特点:** - UUID v7 保持创建顺序与时间顺序大致一致 - 适合用于需要按时间排序的场景(如数据库记录、日志条目等) - 符合 RFC 4122 标准 **示例:** ```ts import { utils } from "@halo-dev/ui-shared"; const id = utils.id.uuid(); console.log(id); // "018f1c2e-4fcb-7d04-9f21-1a2b3c4d5e6f" // 可以用于生成唯一的资源标识 const resourceId = utils.id.uuid(); ``` ## events 全局的事件总线,目前仅提供插件配置更新的事件,用于在插件中及时知晓用户修改了插件配置,然后重新获取插件配置数据。 ### 使用示例 ```vue title="ui/src/MyComponent.vue" ``` ### 可用事件 - `core:plugin:configMap:updated`: 当插件的配置映射更新时触发 - `pluginName`: 插件名称(string) - `group`: 配置组名称(string) --- url: https://docs.halo.run/developer-guide/plugin/api-reference/ui/components/index.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # 组件 ## 组件 ### [UppyUpload](/developer-guide/plugin/api-reference/ui/components/uppy-upload.md) - [使用方式](/developer-guide/plugin/api-reference/ui/components/uppy-upload.md#使用方式) - [Props](/developer-guide/plugin/api-reference/ui/components/uppy-upload.md#props) - [Emits](/developer-guide/plugin/api-reference/ui/components/uppy-upload.md#emits) ### [FilterDropdown](/developer-guide/plugin/api-reference/ui/components/filter-dropdown.md) - [使用示例](/developer-guide/plugin/api-reference/ui/components/filter-dropdown.md#使用示例) - [Props](/developer-guide/plugin/api-reference/ui/components/filter-dropdown.md#props) - [Emits](/developer-guide/plugin/api-reference/ui/components/filter-dropdown.md#emits) ### [FilterCleanButton](/developer-guide/plugin/api-reference/ui/components/filter-clean-button.md) - [使用示例](/developer-guide/plugin/api-reference/ui/components/filter-clean-button.md#使用示例) ### [AnnotationsForm](/developer-guide/plugin/api-reference/ui/components/annotations-form.md) - [使用示例](/developer-guide/plugin/api-reference/ui/components/annotations-form.md#使用示例) - [Props](/developer-guide/plugin/api-reference/ui/components/annotations-form.md#props) ### [AttachmentFileTypeIcon](/developer-guide/plugin/api-reference/ui/components/attachment-file-type-icon.md) - [使用示例](/developer-guide/plugin/api-reference/ui/components/attachment-file-type-icon.md#使用示例) - [Props](/developer-guide/plugin/api-reference/ui/components/attachment-file-type-icon.md#props) ### [AttachmentSelectorModal](/developer-guide/plugin/api-reference/ui/components/attachment-selector-modal.md) - [使用示例](/developer-guide/plugin/api-reference/ui/components/attachment-selector-modal.md#使用示例) - [Props](/developer-guide/plugin/api-reference/ui/components/attachment-selector-modal.md#props) - [Emits](/developer-guide/plugin/api-reference/ui/components/attachment-selector-modal.md#emits) ### [HasPermission](/developer-guide/plugin/api-reference/ui/components/has-permission.md) - [使用方式](/developer-guide/plugin/api-reference/ui/components/has-permission.md#使用方式) - [Props](/developer-guide/plugin/api-reference/ui/components/has-permission.md#props) ### [SearchInput](/developer-guide/plugin/api-reference/ui/components/search-input.md) - [使用方式](/developer-guide/plugin/api-reference/ui/components/search-input.md#使用方式) - [Props](/developer-guide/plugin/api-reference/ui/components/search-input.md#props) - [Emits](/developer-guide/plugin/api-reference/ui/components/search-input.md#emits) ### [PluginDetailModal](/developer-guide/plugin/api-reference/ui/components/plugin-detail-modal.md) - [使用方式](/developer-guide/plugin/api-reference/ui/components/plugin-detail-modal.md#使用方式) - [Props](/developer-guide/plugin/api-reference/ui/components/plugin-detail-modal.md#props) ### [VCodemirror](/developer-guide/plugin/api-reference/ui/components/v-codemirror.md) - [使用方式](/developer-guide/plugin/api-reference/ui/components/v-codemirror.md#使用方式) - [Props](/developer-guide/plugin/api-reference/ui/components/v-codemirror.md#props) - [Emits](/developer-guide/plugin/api-reference/ui/components/v-codemirror.md#emits) ### [v-tooltip](/developer-guide/plugin/api-reference/ui/components/v-tooltip.md) - [使用方式](/developer-guide/plugin/api-reference/ui/components/v-tooltip.md#使用方式) ### [v-permission](/developer-guide/plugin/api-reference/ui/components/v-permission.md) - [使用方式](/developer-guide/plugin/api-reference/ui/components/v-permission.md#使用方式) --- url: https://docs.halo.run/developer-guide/plugin/api-reference/ui/components/uppy-upload.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # UppyUpload ## 使用方式 ```vue ``` ## Props | 属性名 | 类型 | 默认值 | 描述 | | ------------------- | -------------------------------------------------------------- | --------- | ----------------- | | `restrictions` | Restrictions | undefined | 可选,指定任何限制。 | | `meta` | Record\ | undefined | 可选,要发送的额外元数据。 | | `autoProceed` | boolean | false | 可选,在某些操作后自动继续。 | | `allowedMetaFields` | string\[] | undefined | 可选,指定允许的元数据字段。 | | `endpoint` | string | 无,必填 | 数据发送到的端点 URL。 | | `name` | string | file | 可选,用于上传的表单字段的名称。 | | `note` | string | undefined | 可选,任何备注或描述。 | | `method` | "GET" \| "POST" \| "PUT" \| "HEAD" \| "get" \| "post" \| "put" | post | 可选,用于请求的 HTTP 方法。 | | `disabled` | boolean | false | 可选,如果为真,则禁用组件。 | | `width` | string | 750px | 可选,组件的宽度。 | | `height` | string | 550px | 可选,组件的高度。 | | `doneButtonHandler` | () => void | undefined | 可选,完成时调用的处理函数。 | ## Emits | 事件名称 | 参数 | 描述 | | -------- | ----------------------------------------- | ----------- | | uploaded | `response`: SuccessResponse 类型,表示上传成功的响应。 | 当文件上传成功时触发。 | | error | `file`: 出错的文件。
`response`: 出错时的响应数据。 | 当文件上传出错时触发。 | --- url: https://docs.halo.run/developer-guide/plugin/api-reference/ui/components/filter-dropdown.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # FilterDropdown 此组件为通用的下拉筛选组件,可以接收一个对象数组作为选项,并使用 `v-model` 绑定选择的值。 ## 使用示例 ```vue ``` ## Props | 属性名 | 类型 | 默认值 | 描述 | | ------------ | ----------------------------------------------------------- | --------- | ----------------------------- | | `items` | \{ label: string; value?: string \| boolean \| number; }\[] | 无,必填 | 包含 `label` 和可选 `value` 的对象数组。 | | `label` | string | 无,必填 | 组件的标签文本。 | | `modelValue` | string \| boolean \| number | undefined | 可选,用于绑定到组件的值,可以是字符串、布尔值或数字。 | ## Emits | 事件名称 | 参数 | 描述 | | ----------------- | ------------------------------------------------------ | ---------- | | update:modelValue | `modelValue`: string \| boolean \| number \| undefined | 当模型值更新时触发。 | --- url: https://docs.halo.run/developer-guide/plugin/api-reference/ui/components/filter-clean-button.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # FilterCleanButton ## 使用示例 ```vue ``` --- url: https://docs.halo.run/developer-guide/plugin/api-reference/ui/components/annotations-form.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # AnnotationsForm 此组件用于提供统一的 [Annotations 表单](https://docs.halo.run/developer-guide/annotations-form.md),可以根据 `group` 和 `kind` 属性自动渲染对应的表单项。 ## 使用示例 ```vue ``` ## Props | 属性名 | 类型 | 默认值 | 描述 | | ------- | -------------------------------------------- | ---------------------- | ---------- | | `group` | string | 无,必填 | 定义组件所属的分组。 | | `kind` | string | 无,必填 | 定义组件的种类。 | | `value` | \{ \[key: string]: string; } \| null \| null | 可选,包含键值对的对象或空值,用于存储数据。 | | --- url: https://docs.halo.run/developer-guide/plugin/api-reference/ui/components/attachment-file-type-icon.md --- > For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt. # AttachmentFileTypeIcon 此组件用于根据文件名显示文件类型图标。 ## 使用示例 ```vue