Halo 2.27.1 介绍与选型指南

目标：用一篇文章讲清 Halo 是什么、能做什么、架构如何组织、与常见建站方案怎么选，并在 Ubuntu 22.04 + Temurin JDK 21 上完成一次真实的最小可用启动（含初始化回显）。文中全部命令与输出均于 2026-10-27 在实测环境逐条执行。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
JDK：Eclipse Temurin 21.0.13+9 LTS
Halo：2.27.1（社区版 JAR 单体包，halo-2.27.1.jar，134,790,347 字节）
数据库：H2（文件模式，随包默认），生产环境建议 PostgreSQL / MySQL
站点端口：8090
工作目录：/root/.halo2
实测日期：2026-10-27

Halo 官方在 2026-10-23 发布 2.27.1，属于带安全更新的补丁版本（修复登录/注册页面静态资源缓存、标签查询接口响应类型、表单内嵌编辑器误提交、HTTP/1.1 keep-alive 读请求中断等问题，并升级 Spring Boot 至 4.1.2）。选型时应以 2.27.x 为当前稳定线。

二、软件概述

2.1 定位

Halo 是面向个人与团队的开源建站与内容管理系统（CMS），由凌霞软件维护，主打「可插拔架构 + 主题/插件生态 + 对非技术用户友好的后台」。它不是一个纯静态博客生成器，也不是重型企业门户，而是介于两者之间：单进程即可提供完整站点（前台主题渲染 + 后台内容管理 + REST API + 插件运行时），既能让个人写博客，也能承载团队的多用户内容站点。

Halo 分为社区版与付费版（专业版/商城版）。本文所有内容基于社区版，付费版额外提供商城、Redis 会话等能力，社区版不包含。

2.2 版本与技术栈

项目	实测/核实结果	核实方式
最新稳定版	2.27.1	GitHub Releases `halo-dev/halo`
发布日期	2026-10-23T16:03:38Z	Releases API `published_at`
许可证	GPL-3.0	仓库 LICENSE（API `license.spdx_id`）
服务端语言	Java，编译目标 21	`application/build.gradle` 中 `options.release = 21`、toolchain 21
Web 框架	Spring Boot 4.1.2 + Spring WebFlux	`gradle/libs.versions.toml`、2.27.1 发布说明
前端	Vue 3（Console/UC 控制台为独立 SPA）	控制台构建产物与官方文档
构建工具	Gradle	仓库 `build.gradle`、`gradlew`
数据库	H2（默认）、PostgreSQL、MySQL、MariaDB	官方配置文档 `spring.sql.init.platform`
扩展机制	主题 + 插件（JAR 形式热插拔）	官方开发者文档
运行形态	单个可执行 JAR / 容器镜像	Releases 资产仅 `halo-2.27.1.jar`

⚠️ 注意：不少第三方教程仍写「Halo 2.x 基于 Spring Boot 3 + Java 17」。以 2.27.1 源码为准，编译目标是 Java 21，Spring Boot 已升级到 4.1.2（2.27.1 的发布说明中明确写了「升级 Spring Boot 至 4.1.2」）。按 Java 17 准备运行环境会在启动阶段直接失败，这一点在选型和部署时必须以实测版本为准。

三、核心架构

3.1 整体分层

Halo 2.x 的运行时可以概括为四层，单进程内完成：

接入层：Spring WebFlux（Reactor Netty）提供 HTTP 服务，同时暴露前台主题页面、/console 管理台、/uc 用户中心与 /apis/* REST API。
应用层：内容（文章/页面/分类/标签）、评论、附件、用户与权限、主题、插件等模块，以「自定义模型 + 控制器（Controller/Reconciler）」的方式组织。
扩展层：主题包（前端模板资源）与插件包（JAR，运行在同一 JVM 内的独立插件运行时）构成了 Halo 的生态基础。
存储层：元数据与内容写入关系型数据库（H2/PostgreSQL/MySQL），附件与主题包落工作目录或对象存储。

Halo 2 的一个显著设计是把扩展资源也当成数据：主题、插件、文章、附件都以统一的扩展模型存库，由后台的控制器持续「调谐」到期望状态。这使插件装卸、主题切换都不需要重启主进程。

💡 技术拓展：内容站点按「页面如何产生」可分为三类——静态生成（Hexo/Hugo，构建期产出 HTML）、动态渲染（WordPress/Halo，请求时查库渲染）、混合增量（Next.js ISR 等）。静态生成资源占用最低、抗压最强，但改内容要重新构建；动态渲染编辑即生效、支持评论与多用户，但需要常驻进程与数据库。Halo 属于动态渲染路线，并用主题缓存与静态资源长缓存降低渲染开销。

3.2 数据与存储

数据库：默认 H2 文件库位于 ${halo.work-dir}/db/halo-next，开箱即用；生产环境官方明确不推荐 H2（易因操作不当损坏数据文件），推荐 PostgreSQL 或 MySQL/MariaDB。
工作目录：默认 ~/.halo2，保存数据库文件、附件（attachments/）、主题与插件包、日志等；升级时只需替换 JAR，工作目录不动。
附件：默认本地存储，另有 S3 兼容对象存储、阿里云 OSS、腾讯云 COS 等策略，可在后台「附件 -> 存储策略」中配置。

3.3 扩展机制

主题：一个包含模板、静态资源与 theme.yaml 的压缩包，后台上传即可切换。Halo 2 主题使用 Thymeleaf 模板语法，前后台共用一套内容模型。
插件：标准 JAR 包，声明 plugin.yaml 后上传安装，可注册路由、扩展点、自定义模型、后台菜单与设置项。插件与主程序同 JVM 运行，安装/启用/停用无需重启。

四、功能特性

4.1 内容创作与管理

Markdown 编辑器（Console 内置），支持粘贴上传图片、代码块高亮、实时预览。
文章支持草稿/已发布状态、定时发布、置顶、加密、允许评论等属性。
分类与标签体系，支持层级分类、标签检索。
页面（独立页面）与自定义页面模板，可用于「关于」「友链」等。

4.2 主题与插件生态

官方应用市场（halo.run/store）提供主题与插件；社区版即可安装任意兼容主题与插件。主题决定前台外观，插件补齐评论、统计、搜索、图床、Markdown 增强等能力。

4.3 多用户与权限

内置角色体系（超级管理员、管理员、作者、投稿者等），支持多用户协作、作者主页、用户中心（/uc）。可开启注册、邮箱验证、两步验证（2FA）。

4.4 附件存储

💡 技术拓展：附件存储常见有四类方案——

方案特点适用场景
本地磁盘零依赖、最快，但扩容与多机共享困难单机小站
S3 兼容对象存储（MinIO/AWS S3/R2）标准协议、易扩容、可 CDN 大多数生产站点
云厂商 OSS/COS 与 CDN、图片处理集成好，有厂商绑定国内公网站点
数据库存二进制备份简单，但库体积膨胀、性能差极小型场景

Halo 后台的「存储策略」同时支持本地、S3 兼容、阿里云 OSS、腾讯云 COS 等，本文实测采用默认本地存储，生产建议切换到对象存储。

方案	特点	适用场景
本地磁盘	零依赖、最快，但扩容与多机共享困难	单机小站
S3 兼容对象存储（MinIO/AWS S3/R2）	标准协议、易扩容、可 CDN	大多数生产站点
云厂商 OSS/COS	与 CDN、图片处理集成好，有厂商绑定	国内公网站点
数据库存二进制	备份简单，但库体积膨胀、性能差	极小型场景

4.5 SEO 与评论

内置 SEO 设置：站点标题/描述/关键词、文章摘要、站点地图（/sitemap.xml）、robots、永久链接格式。
评论系统内置（支持审核、回复、表情），也可通过插件对接第三方评论。

五、快速开始（最小可用）

本节用最短路径把 Halo 跑起来：装 JDK 21、下载官方 JAR、启动、访问并完成初始化。所有命令均在本机实测。

5.1 安装 JDK 21

Halo 2.27.1 的字节码目标为 Java 21，先准备 Temurin 21：

sudo mkdir -p /usr/local /opt/halo
curl -L -o /tmp/jdk21.tar.gz "https://api.adoptium.net/v3/binary/latest/21/ga/linux/x64/jdk/hotspot/normal/eclipse"
sudo tar -xzf /tmp/jdk21.tar.gz -C /usr/local/
sudo mv /usr/local/jdk-21.0.13+9 /usr/local/jdk-21.0.13
sudo ln -sfn /usr/local/jdk-21.0.13 /usr/local/java
/usr/local/java/bin/java -version

实测输出：

openjdk version "21.0.13" 2026-10-20 LTS
OpenJDK Runtime Environment Temurin-21.0.13+9 (build 21.0.13+9-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.13+9 (build 21.0.13+9-LTS, mixed mode, sharing)

⚠️ 网络说明：实测时官方 GitHub Release 直连不可用（curl 返回 000、无响应），改用代理 192.168.1.62:7897 后 200 成功。若你的服务器直连正常，可去掉代理参数；若在国内，也可用清华/阿里云镜像的 Temurin 包。

5.2 下载并启动 JAR

sudo curl -L -o /opt/halo/halo-2.27.1.jar \
  https://github.com/halo-dev/halo/releases/download/v2.27.1/halo-2.27.1.jar
sudo ln -sfn /opt/halo/halo-2.27.1.jar /opt/halo/halo.jar
sudo /usr/local/java/bin/java -Dfile.encoding=UTF-8 -Xms256m -Xmx512m \
  -jar /opt/halo/halo.jar --server.port=8090 --halo.external-url=http://127.0.0.1:8090

首次启动会自动在 ~/.halo2 初始化 H2 数据库。实测启动日志（节选）：

2026-10-27T12:58:35.458Z  INFO 197 --- [           main] o.s.boot.reactor.netty.NettyWebServer    : Netty started on port 8090 (http)
2026-10-27T12:58:35.544Z  INFO 197 --- [           main] run.halo.app.Application                 : Started Application in 7.196 seconds (process running for 7.677)

从进程启动到监听 8090 完成约 7.2 秒。验证端口与首页：

curl -s -o /dev/null -w "root=%{http_code}\n" http://127.0.0.1:8090/
curl -s -o /dev/null -w "console=%{http_code}\n" http://127.0.0.1:8090/console

实测输出：

root=404
console=302

此时首页 404 属正常现象——站点尚未初始化、未启用主题；/console 302 指向登录/初始化页。用浏览器访问 http://<服务器IP>:8090/console 会进入初始化表单，填写站点标题、管理员账号（示例：root / q1w2e3r4）、邮箱与外部访问地址即可。初始化成功后实测：

HTTP/1.1 204 No Content        # 提交初始化表单
root=200                       # 站点首页
<title>Halo 技术文档站</title>  # 首页标题已生效

⚠️ 注意：初始化表单的 language 字段只接受 zh-CN|zh-TW|en|es。传 zh 会返回 400：{"detail":"Validation failure","errors":["must match \"^(zh-CN|zh-TW|en|es)$\""]}。用 curl 走表单初始化时务必带对语言码，并携带页面下发的 _csrf 与 Cookie。

完整的分步部署（systemd 托管、PostgreSQL 外接、Docker Compose）见后续安装与 Compose 篇。

六、适用场景与限制

6.1 适合的场景

个人博客 / 技术专栏：写作体验好，Markdown 原生，主题可直接套用。
团队内容站：多用户、角色权限、投稿审核流程完整。
企业官网 / 产品文档站：动态渲染、可插件扩展、支持对象存储与 CDN。
需要 REST API 的二次开发：2.x 提供 Console API 与 UC API，可用个人访问令牌调用（详见 API 篇）。

6.2 不适合的场景

只需要极简静态博客、追求零运维与极致抗压：Hexo/Hugo 更合适。
超大流量门户：单进程动态渲染需靠缓存/反代扩展，超出 Halo 的设计目标。
强依赖复杂电商/会员体系：社区版不含商城，需要付费版或另选方案。
完全不想维护 JVM 与数据库：需接受定期升级和备份成本。

6.3 资源占用实测

本次最小站点（H2、无插件、默认主题）启动后进程常驻，JVM 堆按 -Xms256m -Xmx512m 限定。实测进程参数：

ps -ef | grep [j]ava

root         197       1 21 12:58 ?        00:00:34 /usr/local/java/bin/java -Dfile.encoding=UTF-8 -Xms256m -Xmx512m -jar /opt/halo/halo.jar --spring.config.additional-location=optional:file:/root/.halo2/

💡 说明：Halo 默认不限制堆大小，生产部署建议按 -Xms256m -Xmx512m 起步，再根据插件数量与访问量调整；只写 java -jar 而不加参数会让 JVM 按物理内存的 1/4 取上限，在小内存机器上有 OOM 风险。

七、同类选型对比

维度	Halo 2.27.1	WordPress	Ghost	Hexo	Halo 1.x
技术栈	Java 21 / Spring Boot 4 / Vue 3	PHP / MySQL	Node.js / MySQL	Node.js 静态生成	Java / Spring Boot 2
运行形态	单 JAR 常驻	PHP-FPM + Web 服务器	Node 常驻	构建期生成静态文件	单 JAR 常驻
数据库	H2 / PostgreSQL / MySQL / MariaDB	MySQL/MariaDB	MySQL（SQLite 需付费）	无	MySQL
许可证	GPL-3.0	GPL-2.0+	MIT（核心）	MIT	GPL-3.0
编辑体验	内置 Markdown 编辑器	块编辑器（Gutenberg）	Markdown 编辑器	本地 Markdown 文件	内置 Markdown 编辑器
主题/插件	主题 + JAR 插件，后台热插拔	生态最大，主题插件极多	主题与集成较少	主题较多，无运行时插件	主题 + 插件（1.x 体系）
多用户/权限	内置角色体系	完善	有限（作者/管理员）	无	有
资源占用	中（JVM 常驻）	中	低	极低（无进程）	中
二次开发	REST API + 插件扩展点	REST API + PHP 插件	Content API	无服务端	REST API
升级方式	替换 JAR + 保留工作目录	后台/命令行升级	替换版本	重新构建	已停止主线，需迁移 2.x

选型建议：

想要「WordPress 的完整后台 + 更轻的运行时 + 现代 Java 技术栈」→ Halo。
团队以 PHP 为主、需要海量现成主题插件 → WordPress。
纯博客、愿意用 Node 且不需要多用户 → Ghost。
追求零服务器成本、内容不频繁变动 → Hexo（或 Hugo）。
仍在使用 Halo 1.x → 1.x 已停止主线维护，官方提供迁移工具，建议尽早迁到 2.x（数据模型与插件体系均已换代）。

💡 技术拓展：CMS 的扩展模型大致有「钩子/事件（WordPress）」「插件包 + 扩展点（Halo、Ghost）」「无运行时、仅构建插件（Hexo）」三种。前两者可在不重启站点的情况下增删功能，后者把扩展固化在构建流程里、部署最简单但灵活性最低。Halo 属于第二种，插件与主程序同 JVM，装卸即时生效。

八、延伸阅读（本站系列）

《Ubuntu 22.04 安装 Halo 2.27.1 指南》：Temurin JDK 21 + JAR + systemd，H2 起步与 PostgreSQL 切换。
《Halo 2.27.1 Docker Compose 部署指南》：Halo + PostgreSQL + Nginx 三服务编排、固定网段与持久化验证。
《Halo 2.27.1 配置参数详解》：application.yaml 逐项默认值与实测效果。
《Halo 2.27.1 REST API 与个人访问令牌详解》：Console/Content API、PAT 创建吊销、文章与附件操作。

九、参考链接

Halo 官网：https://www.halo.run
Halo 文档：https://docs.halo.run
GitHub 仓库：https://github.com/halo-dev/halo
2.27.1 发布说明：https://github.com/halo-dev/halo/releases/tag/v2.27.1
应用市场：https://www.halo.run/store