---
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 是什么?
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)。
## 项目状态

---
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 服务器运维管理面板。

### 功能
- **快速建站**:深度集成 WordPress 和 Halo,域名绑定、SSL 证书配置等一键搞定。
- **高效管理**:通过 Web 端轻松管理 Linux 服务器,包括应用管理、主机监控、文件管理、数据库管理、容器管理等。
- **安全可靠**:最小漏洞暴露面,提供防火墙和安全审计等功能。
- **一键备份**:支持一键备份和恢复,备份数据云端存储,永不丢失。
### 安装
关于 1Panel 的安装部署与基础功能介绍,请参考 [1Panel 官方文档](https://1panel.cn/docs/installation/online_installation/)。此处假设你已经完成了 1Panel 的安装部署,并对其功能有了基础了解。
### 安装基础软件
在安装 Halo 之前,我们需要先在 1Panel 上安装好所需的软件,包括 OpenResty 和数据库(MySQL、PostgreSQL、MariaDB 都可以)。在接下来的文档中,我们会默认你已经安装好了这两个软件,并不再赘述。

## 安装 Halo 应用
进入应用商店应用列表,选择其中的 Halo 应用进行安装。

在应用详情页选择最新的 Halo 版本进行安装。

参数说明:
- **名称**:要创建的 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 应用的安装后,此时并不会自动创建一个网站,我们需要手动创建一个网站,然后将 Halo 应用绑定到这个网站上才能使用域名访问。
点击 1Panel 菜单的 **网站**,进入网站列表页,点击 **创建网站** 按钮。

1. 在已装应用中选择我们刚刚新建的 Halo 应用。
2. 正确填写主域名,需要注意的是需要提前解析好域名到服务器 IP。
最后,点击确认按钮,等待网站创建完成即可访问网站进行 [初始化](https://docs.halo.run/guide/setup.md)。

## 升级 Halo
:::info 新版本上架有延迟
当 Halo 发布新版本之后,并不会在 1Panel 的应用商店中实时查看到新版本,通常需要等待一段时间才会显示,这取决于 1Panel 的应用商店更新频率。
:::
:::warning 升级前查看更新日志
目前 1Panel 不支持在升级应用的时候查看应用的更新日志,所以建议在升级前前往 [Halo 版本发布](https://releases.halo.run/) 查看对应版本的更新日志,了解新版本的变化。
:::
当 Halo 在 1Panel 的应用商店有更新时,可以在 **应用商店** 的 **可升级** 选项卡中看到 Halo 应用的升级按钮。

点击 **升级** 按钮后,可以在升级界面中选择最新的 Halo 版本,最后点击 **确认** 按钮即可完成升级。

## 激活许可证
可以参考 [许可证激活](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 模块。
- 已放行服务器的 `80` 和 `443` 端口。
- 如果计划使用域名访问 Halo,需要提前将域名解析到当前服务器。
## 安装 Halo 应用
进入宝塔面板左侧的 **Docker**,在 **应用商店** 中搜索 `Halo`,然后点击 **安装**。

在安装配置页面中,按照实际情况填写参数:

参数说明:
- **名称**:当前 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` 即可。
:::

安装完成后,进入 **Docker** 的 **已安装** 列表,等待 Halo 应用变为运行中状态。

## 配置网站和 SSL
如果你在安装 Halo 时填写了域名,宝塔通常会同步创建对应的网站配置。你可以在已安装应用卡片中点击 **管理网站**,或者直接进入左侧菜单的 **网站** 查看站点状态。

如果站点的 **SSL 证书** 一栏显示未部署,可以进入站点管理页面,在 **SSL** 标签页中申请证书。

证书申请成功后,即可通过你配置的域名使用 `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 数据目录和数据库,并前往 [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),按提示填写部署参数:

### 确认订单
参数填写完成后可以看到对应询价明细,确认参数后点击**下一步:确认订单**。确认订单完成后同意服务协议并点击**立即创建**进入部署阶段。
### 获取访问链接
等待部署完成后进入服务实例管理,在控制台找到 Halo 服务访问链接。

### 访问 Halo
单击链接访问 Halo 服务。

---
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)


### 创建 ECS 时选择 Halo 镜像
您也可以自行购买[阿里云服务器](https://ecs-buy.aliyun.com/ecs?userCode=kmemb8jp),并在选择镜像时选择云市场镜像并搜索 **Halo**,即可快速选择镜像进行部署。


服务器初始化完成之后,进入 ECS 控制台即可看到服务器信息,如下图所示:

## 访问 Halo
首先需要在服务器的安全组开放 80 端口,然后就可以通过服务器的公网 IP 访问 Halo 了。

首次访问会进入 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,然后选择所需地域、可用区、套餐等,点击立即购买即可。

## 应用管理

服务器初始化完成之后,进入应用 **管理页面** 即可看到 Halo 和 1Panel 的相关信息。
## 访问 Halo
在 **应用管理** 页面中点击 **管理员登录地址** 即可进入 Halo 初始化页面,填写初始化信息即可完成 Halo 的安装。

## 1Panel 管理
### 开放 1Panel 端口
在 **应用管理** 页面中可以看到预装的 1Panel 信息,首先需要将 1Panel 的端口开放,进入防火墙页面添加默认端口 8090 即可:

### 获取 1Panel 登录信息
登录到实例获取 1Panel 初始用户名和密码:

### 登录 1Panel
然后就可以通过 `http://ip:8090/tencentcloud` 进入 1Panel 的管理后台:


## 查看预装应用
为了保证 Halo 的正常运行,1Panel 中预装了 Halo 所需的环境,可以在 **应用商店** 的 **已安装** 选项卡中查看:

关于应用商店,可查阅 [1Panel 文档](https://1panel.cn/docs/user_manual/appstore/appstore/)。
## 升级 Halo
在 **应用商店** 的 **可升级** 选项卡中检查 Halo 是否有更新,如果有新的版本,点击应用卡片的 **升级** 按钮即可。

## 绑定域名
:::info 准备可用域名
该操作要求用户有一个可用的域名,并在 DNS 服务商处添加对应的解析记录。
:::
在 **网站** 页面中,此镜像默认添加了一个关联 Halo 应用的网站,你可以点击配置按钮然后添加自己的域名。


除此之外,在绑定域名之后,还需要修改一下 Halo 的 **外部访问地址** 参数为实际的网站访问地址(如:[https://demo.halo.run](https://demo.halo.run)),否则 Halo 的部分功能或者插件可能会出现使用问题,只需要按照下图所示修改应用的参数然后点击确认即可。

关于网站管理,可查阅 [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` 端口。
:::

首次进入页面会提示创建管理员账户,需要注意的是:**邮箱一定要是合法邮箱,后续涉及到 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 仪表盘,点击代理服务进入代理服务配置页面。

### 添加代理配置

1. **域名**:配置想要代理到 Halo 的域名,需要提前在域名服务商解析到当前服务器
2. **协议**:选择 http
3. **转发主机名 / IP**:填写 Halo 容器的服务名,比如上方示例中的 `halo`
4. **转发端口**:8090
以上配置为必须修改,界面中的其他配置可以按需选择,但其中的**缓存资源**不建议打开,可能不会完全遵守 Halo 的缓存策略。
配置完成之后,就可以尝试访问域名。
### 配置 SSL
点击 SSL 选项卡,勾选 **申请新证书** 之后保存即可,同时建议勾选 **强制 SSL**,这样在访问 http 协议的地址时会自动跳转到 https 协议的地址。

至此,我们已经完成了在 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。

表单项说明:
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`。

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) 中手动开启。

通过 OAuth2 等第三方认证方式首次登录时,可以根据页面提示绑定已有账号;站点开放注册时,也可以注册新账号并按要求补充资料、同意相关协议。
## 控制台
Console 控制台是一个 Halo 站点的后台管理系统,只有具有权限的登录用户才可以正常使用控制台功能。你可以在控制台中管理站点中的文章、页面、附件等各种内容,调整站点使用的主题或各种设置,访问地址为 `/console`。

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 后,默认会进入仪表盘。仪表盘由多个组件组成,用于集中展示站点概况和常用信息;插件也可以提供新的仪表盘组件。

## 调整仪表盘
点击仪表盘右上角的 `设置` 按钮进入设计模式。在设计模式中可以:
- 添加 Halo 或插件提供的组件;
- 拖拽组件以调整位置;
- 拖动组件边缘以调整尺寸;
- 修改支持配置的组件;
- 删除不再需要的组件。
完成调整后,点击右上角的 `保存` 按钮使布局生效。

## 配置不同设备的布局
设计模式支持切换不同设备尺寸。你可以分别调整各尺寸下的组件位置和大小,使仪表盘适应不同宽度的屏幕。切换尺寸或离开页面前,请先保存当前修改。
---
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 商城版,支持按月/按年订阅或者版本买断。
在凌霞官网购买产品后,可以在 `个人中心` > `我的许可证` ,统一管理当前账户下的全部已购产品的许可证。

## 部署 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 版本信息,目前还处于未激活状态,需要按照后续步骤进行激活。

## 查看已购产品许可证
登录到凌霞官网的 [订单列表](https://lxware.cn/uc/cloud/order),点击已完成订单条目右侧的更多按钮,点击「许可证列表」,即可跳转至 `我的许可证` 列表,可以查看该订单所购产品的许可证。

## 下载许可证
在 `我的许可证`列表,点击许可证条目右侧的更多按钮,点击「详情」;

在详情页下载许可证文件,同时支持兑换包含在产品许可证内的免赠权益。

## 激活许可证
进入 `控制台` > `概览`,导入下载的许可证文件。

导入完成后,可以查看到更新的版本信息。许可证显示为「有效」即为激活成功,到此即可正常使用 Halo 付费版。

## 取消激活许可证
你可以随时在当前应用中取消激活许可证,取消后付费版功能将会受限。在许可证有效期内,许可证可被重新激活至其他设备中。

## 使用增值权益
> 随着 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 付费版许可证激活后,就可以在内置的应用市场中查看所有可下载的付费应用。

### 激活付费应用
下载付费应用之后,即可在许可证管理中使用 Halo 付费版许可证进行激活。

:::info 激活后重启插件
如果你在激活前就启动了插件,那么在激活后可能需要重启插件才会生效。
:::
### Halo 付费版增值权益内容
所有付费版可以在许可证有效期内使用所有 Halo 官方发行的付费应用,包括在许可证有效期内新增的付费应用,[点击查看最新官方付费应用列表](https://www.halo.run/store/apps?price-mode=ONE_TIME\&sort=creationTimestamp%2Cdesc\&tag=official)。
查看当前许可证包含的付费应用可以在 `个人中心` > `我的许可证` 中进入具体 Halo 许可证的详情页面中查看,如下图:

---
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)
:::

## 个人资料
这个页面会显示和用户相关的信息,并支持修改头像、显示名称、简介等个人资料。用户还可以验证电子邮箱;付费版本在站点已配置短信服务时,还可以验证并绑定手机号。用户可以修改登录密码;通过免密认证注册且尚未设置密码的用户,可以在这里设置密码。

## 通知配置
这个页面可以配置用户的通知偏好,可以选择接收哪些类型的通知。

## 个人令牌
个人令牌是一种用于访问 Halo API 的凭证,可以通过个人令牌访问 Halo 的 RESTful API,而无需通过用户名和密码授权,使用方式可查阅:[RESTful API 介绍](https://docs.halo.run/developer-guide/restful-api/introduction.md)

创建新的个人令牌:

- **名称**:个人令牌的名称。
- **过期时间**:个人令牌的过期时间,不选择则表示永不过期。
- **描述**:个人令牌的描述信息,用于描述个人令牌的用途。
- **角色与权限模板**:决定个人令牌可以访问的 API 范围,可以选择多个角色或权限模板。
创建好的个人令牌:

令牌值只会在创建完成时完整显示,请立即复制并妥善保管。对于已有令牌,可以查看最后使用时间,并执行撤销、恢复或删除操作;删除后无法恢复。
## 认证方式
认证方式页面会列出当前账号可以使用的第三方认证方式。对于支持账号绑定的认证方式,可以在这里绑定或解除绑定。

## 两步验证
在这个选项卡中,我们可以配置登录之后两步验证方式,目前支持 TOTP 验证器。


## 登录设备
在这里可以看到当前账号的所有登录设备,你也可以在更多按钮中撤销任意设备。

## 消息
此页面用于显示用户收到的站内消息。

## 我的文章
Halo 默认为个人中心提供了管理个人文章的功能,每个用户都可以在个人中心创建、编辑自己的文章。当然,也可以通过配置角色权限,自行决定是否开放此功能,可查阅[创建角色](https://docs.halo.run/guide/use/users.md#%E5%88%9B%E5%BB%BA%E8%A7%92%E8%89%B2)。

## 商城
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. 通过左侧导航栏进入文章页面,点击右上角的新建按钮
进入到如下页面后,你就可以开始编辑自己的文章内容了:

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. 在文章列表点击指定文章的标题进入文章编辑页面,点击页面右上角的设置按钮。

### 设置说明
- **标题**:用于在主题端显示的文章标题。
- **别名**:通常用于生成文章访问地址,如:`/archives/{slug}`。
- **分类目录**:文章所属分类,方便用户区分文章类型进行针对性浏览,一篇文章可以属于多个分类。
- **标签**:文章添加的标签,方便用户更进一步标识文章信息,一篇文章可以添加多个标签。
- **自动生成摘要**:文章摘要是对文章内容的概括性描述。
- **是**:系统根据文章内容,自动生成一段摘要。
- **否**:用户自行输入文章摘要文本。
- **自定义摘要**:用户自行输入的文章摘要文本,仅当 `自动生成摘要` 为否时生效。
- **允许评论**:是否允许用户在主题端浏览文章时对该文章发起评论。
- **是否置顶**:文章是否排序在文章列表的最顶部。
- **可见性**:访问站点主题端时,哪些人可以看到这篇文章。
- **公开**:所有用户均可看到这篇文章,包括未登录用户。
- **私有**:仅文章作者可以看到这篇文章。
- **发表时间**:手动指定文章的发表时间,未指定时以实际发布时间为准。
- **自定义模板**:自定义文章的渲染模板,由主题提供支持。
- **封面图**:文章封面图设置,需要主题支持该功能。
- **元数据**:供主题、插件使用的额外数据信息。比如主题在文章页面提供了一个下载按钮,那么就可以通过元数据来指定下载地址。
## 发布及取消发布
对于已发布的文章,默认可以通过站点地址进行公开访问,用户可以在文章高级设置中修改可见性。
你可以在上文介绍的文章设置对话框中,修改文章的发布状态。
在文章设置对话框中,若文章当前处于已发布状态,下方会显示取消发布按钮;若文章处于未发布状态,下方会显示发布或定时发布按钮。
## 删除文章
当你不再需要一篇文章时,你可以通过以下方式删除该文章:
1. 点击文章列表指定文章所在行的 `···` 更多操作按钮,选择删除。
2. 勾选文章列表中的全选/多选框,选中一篇或多篇文章进行批量删除。
文章删除后会进入回收站中,点击右上角的回收站按钮进入回收站。在回收站中,你可以永久删除或恢复指定的文章。
:::warning 永久删除不可恢复
文章永久删除后将从数据库删除该记录,后续无法再恢复找回。
:::
## 文章分类管理
通过分类可以更好地组织管理文章。分类之间存在层级关系,一个父分类下可包含多个子分类。一篇文章可以同时属于多个分类。
在文章管理页面,点击页面右上角的 `分类` 按钮即可进入分类管理页面。
### 新建文章分类
点击分类管理页面右上角的 `新建` 按钮即可新建一个分类。


#### 设置说明
- **名称**:用于在主题端显示的分类名称。
- **别名**:通常用于生成分类归档页面的访问地址。默认路径规则为 `/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)。
- **自定义模板**:自定义分类归档页面的渲染模板,由主题提供支持。
- **自定义文章模板**:自定义当前分类下所有文章的渲染模板,由主题提供支持。
- **封面图**:分类封面图设置,需要主题支持该功能。
- **在列表中隐藏**:开启此选项后,此分类和其下子分类,以及其下文章将不会显示在前台的列表中,需要主动访问分类归档页面,此功能仅对第一级目录生效。
- **阻止文章级联查询**:阻止父级分类在级联文章查询中包含此分类及其子分类。
- **描述**:关于该文章分类的更多描述信息。
- **元数据**:供主题、插件使用的额外数据信息。例如部分主题期望使用不同的颜色对分类进行区分,便可以使用该功能为分类增加颜色相关的元数据。
### 调整分类层级
分类之间存在层级关系,一个父分类下可包含多个子分类。
你可以按住分类前的图标,通过拖拽来调整分类间的层级关系和顺序。

### 修改/删除分类
点击指定分类所在行后方的 `···` 更多操作按钮,可以对文章分类进行修改或删除。
:::warning 删除分类的影响
文章分类删除后,对应文章的关联将被解除,且该操作不可恢复,请谨慎进行该操作。
:::
## 文章标签管理
标签可以用于为文章添加特定标记,与分类不同的是标签之间没有层级关系。一篇文章也可以同时添加多个标签。
### 新建文章标签
点击文章标签页面右上角的 `新建` 按钮即可新建一个标签。

#### 设置说明
- **名称**:用于在主题端显示的标签名称。
- **别名**:通常用于生成标签归档页面的访问地址。默认路径规则为 `/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` 地址进行访问。

点击页面标题可以进入编辑器,页面设置入口位于编辑器右上角。

:::info 自定义页面模板
自定义页面默认使用主题端的 `page.html` 模板进行渲染,如果主题中提供了针对自定义页面的其他模板,用户可以通过修改自定义页面高级设置中的自定义模板设置进行使用。
:::
## 页面设置
新建或编辑页面时,可以在页面设置中配置:
- **标题和别名**:别名用于生成页面访问地址;
- **摘要**:可以自动生成,也可以手动填写;
- **封面图**:供支持该功能的主题展示;
- **是否允许评论**:控制访客能否在页面下发表评论;
- **置顶**:供支持页面置顶的主题使用;
- **可见性**:可以设置为公开、仅自己可见或密码访问;
- **发布时间**:可以立即发布或设置定时发布时间;
- **自定义模板**:选择当前主题提供的页面模板;
- **元数据**:供主题和插件保存额外信息。

## 页面操作
对于页面的新建、设置、发布及删除等操作,与文章操作基本一致,具体操作请参考[《用户指南 - 文章》](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 左侧导航栏的 `评论` 进入评论管理页面。这里可以统一管理文章、页面以及插件扩展内容收到的评论。

## 查找评论
评论列表支持按关键词搜索,并按审核状态、评论者等条件筛选和排序。点击评论关联的内容,可以查看评论所在的文章、页面或其他内容。
## 审核评论
对于待审核评论,可以在评论操作菜单中选择 `通过`;已经通过的评论也可以取消审核。选中多条评论后,可以批量通过审核。
待审核评论的操作菜单:

已通过评论的操作菜单:

## 回复评论
点击评论的 `回复` 操作可以直接回复。评论回复也支持审核和删除,具体可用操作取决于当前评论状态和用户权限。

## 删除评论
可以从单条评论的操作菜单删除评论,也可以选中多条评论后批量删除。
:::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 协议的对象存储厂商。
:::
你可以点击附件页面右上角的 `存储策略` 按钮对存储策略进行管理。
### 新建存储策略
点击存储策略列表右上方的 `+` 添加按钮即可新建一个存储策略。

添加时首先需要选择一种存储策略类型,系统内置的存储策略为本地存储,图中的 `S3 对象存储` 由[对象存储(Amazon S3 协议)](https://www.halo.run/store/apps/app-Qxhpp)提供,此文档以本地存储为例。

添加一个本地存储时,你需要输入名称及存储位置信息。其中的存储位置决定了使用该存储策略的附件,在服务器上的实际存储路径,路径规则为 `{Halo 工作目录}/attachments/{存储位置}`,其中的 Halo 工作目录由安装时指定的参数决定,默认为 `~/.halo2`。
:::info Docker 附件存储位置
默认的 Docker 部署方式,实际存储位置由挂载到 Halo 容器工作目录的服务器目录所决定。
:::
### 管理存储策略
点击存储策略列表指定存储所在行后方的 `···` 更多操作按钮即可对该存储策略进行编辑或删除。

:::info 删除存储策略前先清空附件
为了保护附件安全避免用户误操作,当存储策略下存在附件时,该存储策略不允许删除。如果确定要删除某个存储策略及该存储策略中的所有附件,可以先按照存储策略对附件进行筛选,先批量删除存储策略下的所有附件,再删除存储策略。
:::
## 附件分组
通过附件分组功能可以方便地将同一类型、同一用途的附件划分到一个分组中,方便后续附件的管理和插件。
附件所使用的存储策略决定了附件的实际存储位置和 URL 规则,而附件分组功能仅是逻辑上的归类划分,不会影响附件的存储位置及 URL。
### 新建分组
点击附件列表上方的 `添加分组` 按钮即可新建一个分组。

### 删除分组
点击附件列表上方指定分组上的 `···` 更多按钮,可以对分组进行重命名或删除操作。
Halo 目前提供了两种分组删除策略:
1. **删除并将附件移动至未分组**:分组被删将被删除,分组下的附件移动到未分组中。
2. **删除并同时删除附件**:先删除下的所有附件后,再删除该分组。
:::warning 删除的附件不可恢复
当使用 `删除并同时删除附件` 方式时,分组下的所有附件会被同时删除且不可恢复、无法找回,请谨慎进行该操作。
:::
## 上传附件
点击附件列表右上方的 `上传` 按钮即可上传新的附件到 Halo。

1. **存储策略选择**:你可以选择需要使用的存储策略,为了方便,选择之后会在浏览器记住这个选项。
2. **分组选择**:你可以选择需要上传到的分组,为了方便,选择之后会在浏览器记住这个选项。
3. **上传区域**:同时支持拖拽文件、点击上传区域选择文件、粘贴文件。
切换到远程下载选项卡后,也可以输入一个或多个文件 URL,由 Halo 下载并保存到所选存储策略和分组中。
## 查看附件
点击附件列表中的某一个附件即可查看该附件的详细信息。

1. **预览区域**:目前支持图片、视频、音频的预览。
2. **名称**:可以修改附件在 Console 中显示的名称,不会改变附件的存储位置。
3. **链接**:目前可以显示并复制链接、HTML 格式代码、Markdown 格式代码。
## 删除附件
目前有两种删除附件的方式,你可以选中一些附件进行批量删除或者点击指定附件所在行后方的 `···` 更多按钮,对单个附件进行删除操作。

:::warning 删除附件不可恢复
附件删除后不可恢复、无法找回,请谨慎进行该操作。
:::
## 移动附件

与批量删除操作类似,你可以选中多个附件后在上方的批量操作按钮中选择 `移动` 操作,将所选附件移动到指定的分组中。
:::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 支持配置多个菜单组。

说明:
1. 左边为菜单列表,右边为所选菜单的菜单项列表。
2. 点击左边的菜单可以切换菜单项列表。
## 创建菜单
点击左边菜单列表底部的 **新建** 可以打开新建菜单的对话框,输入名称即可创建。


点击菜单条目的操作按钮可以展开操作选项,包括:
1. **设置为主菜单**:设置当前菜单为主菜单,主菜单会在网站导航栏中显示(具体需要以主题的实现为准)。
2. **克隆**:复制当前菜单及其菜单项,用于快速创建结构相近的新菜单。此功能从 Halo 2.24 开始提供。
3. **编辑**:编辑当前菜单的名称。
4. **删除**:删除当前菜单,会同时删除菜单下的所有菜单项。
## 创建菜单项
点击菜单项列表右上角的 **新建** 可以打开新建菜单的对话框。

表单项说明:
1. **上级菜单项**:可以选择当前新建的菜单项归属的上级菜单项。
2. **类型**:
1. 自定义链接:可以输入任意的名称和链接地址,可以是外部的网址。
2. 文章:可以选择网站上已有的文章。
3. 自定义页面:可以选择网站上已有的页面。
4. 分类:可以选择网站上已有的分类。
5. 标签:可以选择网站上已有的标签。
3. **名称**:当类型为自定义链接时,可以输入任意的名称,当类型为文章、自定义页面、分类、标签时,会自动生成名称。
4. **链接地址**:当类型为自定义链接时,可以输入任意的链接地址,当类型为文章、自定义页面、分类、标签时,会自动生成链接地址。
5. **打开方式**:链接的打开方式。

上图是类型选择 **分类** 时的表单,可以选择分类。

点击菜单项条目的操作按钮可以展开操作选项,包括:
1. **编辑**:编辑当前菜单项的信息。
2. **新增子菜单项**:新增当前菜单项的子菜单项。
3. **删除**:删除当前菜单项,如果当前菜单项包含子菜单项,会同时删除。
## 排序
你可以按住菜单项前的图标,通过拖拽来调整菜单项间的层级关系和顺序。

---
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)
:::
## 安装主题
点击主题页面右上方的 `主题管理` 按钮即可弹出主题管理对话框。
在已安装主题列表中,可以按主题名称搜索。

### 从内置应用市场安装(推荐)
从 Halo 2.10 开始,内置了应用市场插件,可以更加方便在 Console 直接安装应用市场的主题。

:::info 查看内置应用市场指南
更多关于内置应用市场的使用说明可查阅:[应用市场](https://docs.halo.run/guide/use/app-store.md)
:::
### 本地上传安装
你可以点击主题管理对话框下方的 `安装主题` 按钮,在弹出的安装主题对话框中上传主题压缩包。

### 远程下载安装
同样,在安装主题的对话框中,切换到远程下载选项卡,输入主题的下载地址,点击 `下载` 按钮即可开始下载主题。
## 切换主题
同样点击主题页面右上方的 `主题管理` 按钮弹出主题管理对话框。
在弹框中点击选中要切换的目标主题,此时页面返回到主题详情页,点击右上角的 `启用` 按钮即可将当前主题切换为实际使用的主题。
:::info 选中主题不会自动启用
仅选中主题不点击右上角的 `启用` 按钮时,不会影响当前实际使用的主题。
:::
你也可以在已安装主题列表中,通过后方 `···` 的更多操作中的启用选项直接启用指定的主题。
## 修改主题设置
主题页面默认显示出了当前主题的详细信息,在详细信息标签页后方的标签页,即为主题提供的相关设置。不同的主题提供的设置项各不相同,设置项的详细说明请参考对应主题的文档。

以 Halo 的默认主题 Earth 为例,该主题提供了布局、样式、侧边栏、页脚及备案设置共五组配置项。
:::info 重置主题设置
你可以点击主题列表指定主题所在行后方的 `···` 更多操作按钮,选择其中的 `重置` 选项将主题提供的设置项恢复为默认值。
:::
## 预览主题
通过预览功能,你可以在不更改当前启用主题的情况下查看不同主题的效果。点击主题详情页面右上角的 `预览` 按钮预览当前主题,或者进入已安装主题列表,通过后方 `···` 的更多操作中的预览选项预览指定的主题。
在主题预览页面你可以切换不同分辨率的设备,模拟主题在不同终端下的显示效果。也可以通过右上角的功能菜单切换预览的主题,或者调整当前主题的设置,查看不同设置下主题所展现的区别。
演示视频:
## 升级主题
如果当前使用了内置的应用市场插件,在主题更新后会在主题列表中显示更新提示,点击 **立即更新** 按钮即可。
手动升级可以点击主题详情页右上角的 `···` 更多操作按钮,选择其中的 `升级` 选项即可打开升级主题的对话框。
## 重载主题配置
如果当前主题提供的设置项发生变化,可以通过 `···` 更多操作中的 `重载主题配置` 选项对主题配置项进行更新。
## 重置
如果你需要清空所有主题配置并重新配置主题,你可以通过 `···` 更多操作中的 `重置` 选项将主题提供的设置项恢复为默认值。
## 卸载主题
进入已安装主题列表,点击指定主题所在行后方的 `···` 更多操作按钮,选择其中的 `卸载` 选项即可对当前主题进行卸载。

:::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 直接安装应用市场的插件。

:::info 查看内置应用市场指南
更多关于内置应用市场的使用说明可查阅:[应用市场](https://docs.halo.run/guide/use/app-store.md)
:::
### 本地上传安装

插件安装成功后,便会出现在插件管理的列表中。
:::info 注意第三方插件安全
从非 Halo 官网应用市场安装插件时,请务必注意其安全性。
:::
### 远程下载安装
同样,在安装插件的对话框中,切换到远程下载选项卡,输入插件的下载地址,点击 `下载` 按钮即可开始下载插件。
:::info 注意第三方插件安全
从非 Halo 官网应用市场安装插件时,请务必注意其安全性。
:::
## 插件设置
点击插件列表中的某个插件进入插件详情页面。与主题设置类似,插件详情页面默认显示出了当前插件的详细信息,在详细信息标签页后方的标签页,即为插件提供的相关设置。不同的插件提供的设置项各不相同,设置项的详细说明请参考对应插件的文档。

此处以 `Umami` 插件为例。
:::info 重置插件设置
你可以点击插件列表指定插件所在行后方的 `···` 更多操作按钮,选择其中的 `重置` 选项将插件提供的设置项恢复为默认值。
:::
## 启用/禁用插件
点击插件列表或插件详情页中的启用/禁用开关,即可切换插件的启用禁用状态。

选中多个插件后,可以批量启用或禁用。批量操作只会处理当前状态允许执行该操作的插件。
## 升级插件
如果当前使用了内置的应用市场插件,在插件更新后会在插件列表中显示更新提示,点击 **立即更新** 按钮即可。
手动升级可以点击具体插件的 `···` 更多操作按钮,选择其中的 `升级` 选项即可打开升级插件的对话框。
## 重载插件
从 Halo 2.24 开始,已启用的插件可以通过 `···` 更多操作中的 `重载` 选项重新加载。插件运行状态异常或更新了需要重新加载的资源时,可以先尝试重载,无需重启 Halo。
## 重置
如果你需要清空所有插件配置并重新配置插件,你可以通过 `···` 更多操作中的 `重置` 选项将插件提供的设置项恢复为默认值。
## 卸载插件
点击插件列表指定插件所在行后方的 `···` 更多操作按钮,选择其中的 `卸载` 选项即可对当前插件进行卸载。

选中多个插件后,也可以批量卸载。
:::info 卸载方式的区别
目前提供了 `卸载` 及 `卸载并删除配置` 两种卸载方式。
仅卸载插件时插件的配置信息会进行保留,当重新安装插件后还可以使用之前已保存的配置。
:::
## 扩展配置
在 Halo 的插件机制中,我们使用扩展点来实现插件与 Halo 核心应用的交互,插件可以通过扩展点来扩展 Halo 的功能。这就意味着插件可能会实现和 Halo 或者其他插件相同的扩展点,这时候就需要对扩展点进行管理。
以搜索引擎为例,Halo 默认提供了 `Lucene` 搜索引擎和对应的扩展点,那么用户在安装了其他搜索引擎插件之后就需要在这里进行选择,否则 Halo 无法确定使用哪个搜索引擎。

进入插件管理,点击右上角的 `扩展配置` 按钮即可进入扩展配置页面。

这里以搜索引擎为例,安装了 `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 站点中。

## 绑定 Halo 官网账号

绑定方式:
1. 进入应用市场插件的设置页面,切换到 **账号绑定** 选项卡。
2. 根据提示访问 Halo 官网并注册账号,然后在 Halo 官网的[个人中心](https://www.halo.run/uc/profile?tab=pat)生成一个个人令牌并填写到下方的 **个人令牌** 输入框即可。
## 安装/更新插件
此插件还扩展了插件安装的界面,可以在安装插件时直接从应用市场获取。

此外,如果插件是从应用市场安装的,后续插件更新之后也可以及时收到更新信息,并一键更新。

## 安装/更新主题
与插件一样,在主题管理中也可以直接从应用市场中获取,以及接收主题更新提示。


## 付费应用激活
部分付费主题和插件需要许可证激活才能够正常使用,在购买付费应用之后就会自动为你的 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 专业版/商城版许可证** 并点击激活即可。


除此之外,你也可以在 **许可证管理** 页面查看所有应用的许可证,并管理它们的状态。

### 离线激活
如果你的 Halo 网站无法访问公网,你可以选择离线激活的方式。
### 打开许可证激活对话框
同样点击许可证状态的图标,打开许可证激活的对话框。

### 选择激活方式
激活方式选择许可证。

### 复制离线许可证凭证
点击 **复制离线许可证凭证** 按钮,然后点击 **去生成** 按钮,然后会跳转到 Halo 官网去生成离线激活码。
### 生成离线许可证
找到对应的许可证,选择 **生成离线许可证**。

### 复制离线许可证
在 **生成离线许可证** 的对话框中,粘贴刚刚复制的离线许可证凭证,然后点击 **生成并复制** 按钮,然后会打开 **查看离线许可证** 对话框,你可以选择下载文件或者复制许可证。


### 激活离线许可证
回到 Halo 网站,粘贴刚刚复制的离线许可证,然后点击 **激活** 按钮即可。

其他注意事项:
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 版本的单用户设计,现在你可以创建多个用户并且通过赋予不同用户不同角色的方式,为他们分配不同的权限。
## 用户
点击左侧导航栏的 `用户` 条目进入用户管理页面。
### 创建用户
在用户管理页面,点击右上角的 `添加用户` 按钮即可弹出新建用户对话框。

目前支持配置的用户属性有:
- **用户名**:用户登录 Halo 控制台使用的用户名,不可与已有的用户名重复;
- **显示名称**:用于显示文章作者等用户信息时使用的,更友好的用户名称;
- **电子邮箱**:用户的电子邮箱;
- **新密码**:用户的初始密码;
- **角色**:用户的初始角色;
- **描述**:可以用于为用户添加备注。
### 其他操作
点击用户列表中的 `···` 更多操作按钮,可以对指定用户进行修改资料、修改密码等其他更多操作。

#### 修改用户资料
你可以修改除用户名以外的所有资料,具有用户管理相关权限的用户,也可对其他用户的资料进行修改。
#### 修改用户密码
对于已有的用户,你可以在 `···` 更多操作中修改指定用户的登录密码。
#### 分配角色
对于已有的用户,你可以在 `···` 更多操作中为该用户分配角色,分配角色后该用户具有角色所对应的权限。
:::info 修改角色会影响权限
修改用户分配的角色会影响用户所拥有的权限,可能影响用户使用。
:::
#### 删除用户
对于已有的用户,你可以在 `···` 更多操作中删除该用户。
:::warning 删除用户的影响
删除用户后,该用户之前创建的文章、页面等内容的作者信息将会丢失,可能影响站点内容浏览。此操作不可恢复。
:::
## 角色
如下图所示,在用户管理页面,点击右上角红色区域的 `角色管理` 按钮,即可进入到角色管理页面。

### 创建角色
Halo 提供了全新创建和基于已有角色创建两种角色创建方式。
#### 全新创建
点击角色管理页面右上角的 `新建角色` 按钮即可弹出新建角色对话框,通过这种方式创建的角色默认未勾选任何权限,你需要在对话框中点击切换到权限标签页,为该角色勾选需要的权限。
#### 基于已有角色创建

当系统中已经存在一些基础角色时,你可以点击某个角色所在行中的 `···` 更多操作按钮,选择 `基于此角色创建` 来创建一个新的角色。通过这种方式创建的角色默认继承了原有角色的权限,但你同样可以对新角色的权限进行进一步调整。

- **名称**:角色的名称。
- **禁止访问 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)
:::
你可以在用户管理界面的右上角点击 `身份认证` 按钮,进入身份认证管理页面。

进入身份认证管理页面之后,如果你已经安装了提供身份认证方式的插件,你就可以在列表中看到对应的身份认证方式,你可以对其进行设置并启用。

### 邮箱验证码登录
使用邮箱验证码登录前,需要先完成以下配置:
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) 为例,这些设置信息将在如下位置进行展示。

## 文章设置
针对主题端的文章展示,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 中标记为过时,后续请使用 [附件设置](#附件设置) 代替

## SEO 设置
针对站点的 SEO(搜索引擎优化)需求,Halo 提供了以下设置项:
- **屏蔽搜索引擎**:配置后会在所有页面 HTML 源码的 head 部分添加:
```html
```
:::info 提示
需要注意的是,并不是所有搜索引擎都会遵守这个规则。
:::
- **站点关键词**:格式为以 `,` 分隔的关键词列表,配置后会在所有页面 HTML 源码的 head 部分添加:
```html
```
:::warning 注意
目前主流的搜索引擎(如 Google、Bing、百度搜索等)已经不再使用该标签作为关键词的参考,因此该设置项的作用已经不大,未来我们也可能会移除该设置项。
:::
- **站点描述**:仅对首页生效,配置后会在首页 HTML 源码的 head 部分添加:
```html
```
其他页面会根据页面类型和内容自动生成描述。
## 用户设置
- **开放注册**:是否允许访客注册,勾选之后在登录页面会显示注册入口。
- **注册需验证邮箱**:开启之后,用户注册时必须要经过邮箱验证,需要配置好 [邮件通知](#通知设置)。
- **保留用户名与名称**:设置之后,这些用户名或显示名称将无法被其他用户注册或修改使用。多个值使用英文逗号 `,` 分隔。
- **默认角色**:新注册用户的默认角色。
- **注册时所需协议**:选择注册时需要用户阅读并同意的自定义页面,例如用户协议、隐私政策等。
- **头像存储位置**:用户上传头像的存储策略。
- 已经在 Halo 2.22 中标记为过时,后续请使用 [附件设置](#附件设置) 代替
- **个人中心附件存储位置**:用户在个人中心端上传附件时的默认存储策略,需要用户包含上传附件的权限。
- 已经在 Halo 2.22 中标记为过时,后续请使用 [附件设置](#附件设置) 代替

### 注册协议页面
开启 **开放注册** 后,可以通过 **注册时所需协议** 选择一个或多个自定义页面作为注册协议。保存后,注册页面会显示 `我已阅读并同意` 勾选项,并将已选择的页面显示为可点击链接。用户必须勾选同意后才能提交注册。
从 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`
:::

## 代码注入
你可以使用代码注入功能,在特定类型的页面中注入额外的代码。你可以通过该功能覆盖或补充部分主题 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 中,点击左侧菜单的 `备份`,进入备份页面。
点击右上角的 `创建备份` 按钮,即可创建一个新的备份请求,需要注意的是,创建备份请求并不会立即开始备份,而是会在后台异步执行,因此需要等待一段时间才能看到备份的结果。

备份中:

备份完成:

## 自动备份与同步
为了保障数据的安全,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) 专享插件。
:::

## 恢复
:::info 恢复备份前须知
1. 恢复不限制部署方式,也不限制数据库,也就是说新站点的部署方式和数据库类型可以和备份的站点不同。
2. 恢复过程可能会持续较长时间,期间请勿刷新页面。
3. 在恢复的过程中,虽然已有的数据不会被清理掉,但如果有冲突的数据将被覆盖。
4. 恢复完成之后会提示停止运行 Halo,停止之后可能需要手动运行。
:::
在 Console 中,点击左侧菜单的 `备份`,进入备份页面,然后点击 `恢复` 选项卡即可进入恢复界面,阅读完注意事项之后点击 `开始恢复` 按钮即可显示备份文件上传界面。


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 大文件建议从服务器恢复
如果你的备份文件较大,推荐提前将备份文件上传到服务器,然后选择 `从备份文件恢复` 方式进行恢复,避免因为网络原因导致上传失败。
:::
使用 `上传备份文件` 方式进行恢复的操作示例:
选择备份文件后,点击 `上传` 按钮即可开始上传备份文件,上传完成后会自动开始恢复。

恢复完成,会提示重启 Halo,点击 `确定` 按钮即可重启 Halo。


最后,建议去服务器检查 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.
# 控制台首页
控制台的商店首页主要用于查看运营数据、指引、商店数据等信息。



---
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️⃣ 进入支付方式页面**

**2️⃣ 新建支付方式**

:::note 先创建测试产品
在配置支付方式之前,建议先创建一个测试产品,方便在配置完成后进行测试。
:::
## 支付宝
### 创建支付宝应用
支付宝支付使用官方接口,买家交易的资金将直接进入商家的支付宝账户,无第三方平台介入。
在创建支付宝支付方式之前,需要先在支付宝商家平台和支付宝开放平台完成注册。
- [支付宝商家平台](https://b.alipay.com/)
- [支付宝开放平台](https://open.alipay.com/)
注册完成后,进入支付宝 [开放平台 -> 控制台](https://open.alipay.com/develop/manage),点击 **创建网页/移动应用** 按钮:

其中 **应用类型** 选择网页应用,其他参数按照实际情况填写即可。
### 获取支付宝配置信息
创建应用后,进入应用详情页面:

- 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) 中绑定该支付方式。
支付预览:

### 沙箱环境
访问 [沙箱应用 - 开放平台](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) 中绑定该支付方式。
支付预览:

## 易支付
### 注册易支付
访问 [易支付官网](https://z-pay.cn),注册并登录账号。
### 开通支付渠道
访问 [易支付 -> 我的支付渠道](https://member.z-pay.cn/member/channel.html),新增支付宝或者微信渠道,根据平台的要求填写相关信息。
开通成功之后,需要记录 **渠道 ID**,后续在 Halo 中配置时可能需要使用。

### 获取 API 信息
访问 [易支付 -> API 安全](https://member.z-pay.cn/member/myapi.html),记录 **网关**、**商户 ID(PID)** 和 **商户密钥(KEY)**,后续在 Halo 中配置时需要使用。

### 在 Halo 中配置
打开新建支付方式的界面,支付提供商选择 **易支付**,并填写以下信息:
- 启用:勾选
- 名称:给用户展示的支付方式名称
- 场景:选择 **PC 网页支付**
- 自定义图标:由于易支付同时支持微信和支付宝,推荐自定义图标来区分
- 网关地址:上一步中记录的 **网关**
- 商户号:上一步中记录的 **商户 ID(PID)**
- 商户私钥:上一步中记录的 **商户密钥(KEY)**
- 支付方式:选择 **微信** 或 **支付宝**,需要确保已经在易支付开通对应的渠道
- 支付渠道 ID:上一步中记录的 **渠道 ID**,支持填写多个,使用英文逗号, 隔开,如果不填则随机调用
配置完成之后,还需要在 [销售渠道](https://docs.halo.run/guide/shop/sales-channels.md) 中绑定该支付方式。
支付预览:

## Stripe
### 登录或者注册 Stripe
访问 [Stripe 官网](https://stripe.com),登录或者注册账号,并且需要完成必要的信息填写,确保可以正常使用 Stripe 的支付功能。
### 获取 API 信息
登录到 [Stripe 控制台](https://dashboard.stripe.com),进入设置 -> 开发人员 -> 管理 API 密钥,复制 **密钥** 即可,后续在 Halo 中配置时需要使用。
### 创建 WebHook
### 打开工作台

### 添加接收端
切换到 WebHook 选项卡,并点击 **添加接收端**

### 选择事件
在事件中选择 `checkout.session.completed`

### 选择接收端类型
接收端类型选择 **Webhook 端点**

### 填写端点 URL
:::note 端点 URL 格式
端点 URL 的格式为:
```text
https://your-domain.com/apis/api.ecommerce.halo.run/v1alpha1/payment-providers/stripe/callback
```
其中 `your-domain.com` 需要替换为你的域名,并且需要确保该域名可以访问。
:::

最后点击 **创建** 按钮即可。
### 获取签名密钥
创建完成之后可以在页面的 **签名密钥** 部分复制 **签名密钥**,后续在 Halo 中配置时需要使用。

### 在 Halo 中配置
打开新建支付方式的界面,支付提供商选择 **Stripe**,并填写以下信息:
- 启用:勾选
- 名称:给用户展示的支付方式名称
- 场景:选择 **PC 网页支付**
- API Key:上一步中获取的 **密钥**
- WebHook Secret:上一步中获取的 **签名密钥**
配置完成之后,还需要在 [销售渠道](https://docs.halo.run/guide/shop/sales-channels.md) 中绑定该支付方式。
支付预览:


## 银行转账
银行转账支付方式不经过 Halo 的支付系统,仅仅是在支付的时候显示商家的银行收款信息,让买家转账到商家的银行账户,后续再通过人工审核的方式确认订单。
打开新建支付方式的界面,支付提供商选择 **银行转账**,并填写以下信息:
- 启用:勾选
- 名称:给用户展示的支付方式名称
- 场景:选择 **PC 网页支付**
- 收款银行:银行名称
- 银行支行地址:开户行地址
- 收款账户名:收款账户名称
- 收款账号:收款银行账号
- 付款说明:为用户说明转账时需要注意的事项
配置完成之后,还需要在 [销售渠道](https://docs.halo.run/guide/shop/sales-channels.md) 中绑定该支付方式。
支付预览:

## 收款码支付
收款码支付方式不经过 Halo 的支付系统,仅仅是在支付的时候显示商家的收款码,让买家扫码支付,后续再通过人工审核的方式确认订单。
打开新建支付方式的界面,支付提供商选择 **收款码支付**,并填写以下信息:
- 启用:勾选
- 名称:给用户展示的支付方式名称
- 场景:选择 **PC 网页支付**
- 收款码二维码图片链接
- 付款说明:为用户说明扫码时需要注意的事项
配置完成之后,还需要在 [销售渠道](https://docs.halo.run/guide/shop/sales-channels.md) 中绑定该支付方式。
支付预览:

---
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️⃣ 进入销售渠道页面**

**2️⃣ 新建销售渠道**

- 是否启用:勾选
- 名称:可任意填写
- 编码:根据销售终端选择 **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.
# 产品管理

## 查找和管理产品
登录 Halo 控制台,进入 **商店 -> 产品**。产品列表支持关键词搜索,并可按状态、类型和分类筛选或调整排序。打开单个产品的操作菜单,可以编辑或删除产品。
## 创建产品
首先登录到 Halo 控制台,进入 **商店 -> 产品** 页面,点击右上角的新建按钮。

### 基本信息
- 名称:产品名称
- 简短描述:产品的简短描述
- 描述:产品的详细描述,使用富文本编辑器
- 图片:产品图片,可以直接上传或者从附件库中选择,第一张图片会作为封面图
### 产品数据
这里主要配置产品的类型、属性、规格、价格等数据。
产品类型目前支持四种:
1. 实体:需要配送的产品类型
2. 虚拟:不需要实体配送,使用线上发货的产品类型
3. 链接:直接跳转到第三方链接的产品类型
4. 订阅:按周期售卖的产品类型,创建后不可修改类型,详见 [订阅管理](https://docs.halo.run/guide/shop/subscriptions.md)
:::info 虚拟产品交付方式
虚拟产品支持文件资源下载、卡密发货,可参考 [虚拟交付](https://docs.halo.run/guide/shop/virtual-delivery.md) 进行发货配置。
:::
#### 属性配置
属性的作用是为产品添加一些额外的信息,比如颜色、尺寸、型号等,同时也可以用于生成产品规格。

- 名称:属性名称,比如颜色、尺寸
- 属性值:支持多个属性值,比如颜色可以有红色、蓝色、绿色等,尺寸可以有小、中、大等,同时也可以为不同的属性值设置图片,用于展示给用户
- 用于生成产品规格:勾选后,支持在配置产品规格时根据多个属性生成不同的产品规格
#### 规格配置
规格即产品的具体规格,比如颜色为红色、尺寸为小,型号为1234567890,可以根据属性值生成不同的规格,并单独设置价格、库存等信息,最终用户购买时,可以选择属性值来确定购买的产品规格。
:::note 规格也称 SKU
这里的规格也可以称之为 **变体** 或者 **SKU**。
:::

当我们设置好 [属性](#属性配置) 之后,可以点击 **生成规格** 按钮来批量生成所有可能产生的规格。

然后可以点击具体的规格项,展开规格配置表单:

- 图片:为规格设置图片,用于在购物车,订单等页面展示,如果不设置,会使用属性值中配置的图片或者产品封面
- 状态:支持 **草稿**、**已发布**、**已归档** 三种状态
- 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 尺寸信息仅用于实物产品
重量、长度、宽度、高度用于后续发货相关的业务,如果产品类型为虚拟,则不需要配置。
:::
除了为单个规格设置上述配置之外,也可以点击上方的批量设置按钮,用于为所有规格设置相同的配置。

### 分类配置
分类配置用于将产品分类,比如手机、电脑、服装、数码等,支持多级分类。

## 管理分类
进入 **商店 -> 分类**,可以新建、编辑和删除分类。分类支持父分类、名称、别名、描述和图片;为分类选择父级即可建立多级结构。
产品编辑页面的分类选择器会使用这里维护的分类。
## 管理属性模板
进入 **商店 -> 属性模板**,可以把常用的属性名称和值保存为模板,例如“颜色:红色、蓝色”和“尺寸:S、M、L”。创建产品时选择模板,可以直接带入这些属性值,再按当前产品调整。
## 发布产品
配置完产品信息之后,就可以将产品状态改为 **发布**,并保存产品,最终就可以在商城前台中展示。

---
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.
# 订单管理

## 查找订单
登录 Halo 控制台,进入 **商店 -> 订单**。订单列表支持按关键词、顾客、订单状态、支付状态和发货状态筛选,并可以调整排序。
## 手动创建订单
点击 **创建订单**,可以为指定顾客手动创建订单。创建时需要:
1. 选择顾客。
2. 添加一个或多个产品规格,设置数量和成交价。
3. 按需填写顾客备注。
4. 根据实际情况决定是否跳过库存管理。
确认金额和库存处理方式后再提交。手动创建的订单随后与顾客正常下单的订单一样,在订单详情中处理付款和发货。
## 查看订单详情
我们可以点击订单标题进入订单详情页面,或者点击订单标题右侧的图标按钮预览订单详情。


订单详情会显示订单项目、顾客与收货信息、付款记录、发货记录及操作时间线。根据订单状态,可以执行以下操作:
- 标记已付款:付款处于待处理或授权中时,可以人工确认收款。
- 取消订单:停止继续处理当前打开的订单。
- 删除订单:仅已取消或已归档的订单显示删除操作。删除会隐藏订单,但付款、发货、折扣和优惠券等关联记录仍会保留。
## 发货
收到用户订单之后,可以在订单详情页面的 **发货信息** 区域点击 **发货** 按钮,打开发货界面:

在这个界面需要选择本次发货的产品和数量,并按需填写物流公司、物流单号和物流查询地址,然后点击 **确认发货**。一个订单可以分多次发货;发货失败时,可以在发货记录中重试。
:::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) 文档,需要注意的是,如果产品要支持虚拟交付,需要在产品类型中选择 **虚拟** 产品类型。

## 设置文件资源下载
创建完产品之后,我们需要进入 **产品 -> 虚拟交付** 页面,然后选择刚刚创建的产品。

进入设置页面之后,就可以看到 **资源下载** 的设置页面,我们可以点击右上方的 **添加** 按钮来添加文件。

- 资源类型:支持附件和静态 URL
- 资源名称:为客户显示的文件名称
- 资源描述:可以填写文件的描述信息
- 附件(当类型为附件时):可以点击 `+` 按钮选择已上传的附件或者上传新的附件
- 资源地址(当类型为静态 URL 时):可以填写文件的 URL 地址
填写完成之后,点击 **保存** 按钮即可。
当文件添加完成之后,我们还需要手动启用自动发货,点击右上角的 **发货配置** 按钮,勾选启用即可。

## 设置卡密发货
进入虚拟交付设置页面之后,选择 **卡密资产** 选项卡,就可以看到 **卡密资产** 的设置页面。

我们可以点击右上方的 **添加** 按钮来添加卡密。

- 卡密:卡密内容,支持批量添加,一行一个
- 过期时间:卡密过期时间
- 备注:可以填写卡密的备注信息
填写完成之后点击 **添加** 按钮即可。
当卡密添加完成之后,我们还需要手动启用自动发货,点击右上角的 **发货配置** 按钮,勾选启用即可。

此外,在卡密发货配置界面中,还支持配置 **远程调用配置**,支持通过三方 API 来补货或者动态生成卡密并发货。
定义:
- 预获取:优先从卡密列表中选择并发货,在库存不足时才调用 API 进行补货
- 动态获取:每次发货时都调用 API 获取卡密并发货
配置说明:
- 类型:支持 **预获取** 和 **动态获取**
- 补货配置(当类型为预获取时)
- API 地址:补货 API 地址
- 认证 Token:补货 API 认证 Token,用于对 API 请求进行认证
- 阈值:可用卡密数量低于此值时触发补货
- 每次获取的卡密数量:每次调用 API 获取的卡密数量
- 服务器配置(当类型为动态获取时)
- API 地址:远程生成 API 地址
- 认证 Token:API 认证 Token,用于对 API 请求进行认证
需要注意的是,API 需要自行实现并适配 Halo 的接口标准,可以参考下方的 [API 规范](#api-规范)。
## 订单相关
为产品配置好虚拟交付之后,当客户下单并支付时,系统会自动为订单进行发货流程,可以在控制台的订单详情中看到发货状态。

客户也可以在订单页面看到已发货的虚拟物品。


## 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 端,小程序在国内拥有更高的用户渗透率,更适合承载移动端购物场景。

## 获取方式
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 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 对象存储**。
### 保存配置
填写相关配置,点击 **保存** 即可。
## 迁移



### 进入迁移页面
点击左侧菜单的迁移进入迁移页面。
### 选择迁移类型
选择 **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`,如图所示:

**Windows**
将 Active Profiles 改为 `dev,win`,如图所示:

### 运行
点击 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`
在插件列表将能看到插件已经被正确启动,并且在左侧菜单添加了一个 `示例分组`,其下有一个名 `示例页面` 的菜单。

如果你的设备上无法安装 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`
在插件列表将能看到插件已经被正确启动,并且在左侧菜单添加了一个 `示例分组`,其下有一个名 `示例页面` 的菜单。

## 下一步
- 了解插件项目的完整组成:[目录结构](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"
正在加载…
当前筛选条件下没有 Todo。
```
页面只使用 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` 进行调试。

首先点击上图中 `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` 以及对应的版本增量内容并合并。

为了方便插件开发者获取文章内容,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