Halo

Halo 是一款诞生于国内开源社区、采用 Java/Spring Boot 生态打造的现代化开源博客与建站系统。随着 Halo 2.0 架构的全面推倒重构，系统由原有的单体架构演进为类似于 WordPress 插件机制、但在底层更加现代化的高度可扩展体系。凭借极致优雅的默认界面、所见即所得的块编辑器以及强大的 API 与容器化支持，Halo 成为了追求高颜值与灵活性创作者的理想之选。掌握其容器编排、持久化配置与版本迭代机制，是构建高可用博客的核心技能。

Halo 2.x 架构演进与核心设计理念

Halo 从 1.x 演进到 2.x，并非单纯的功能升级，而是一次底层核心治理理念与开发范式的彻底重塑。

模块化插件机制与系统内核解耦

在 Halo 1.x 时代，许多个性化功能（如特定的评论过滤、统计分析或第三方存储）必须硬编码到核心程序中，导致核心膨胀且维护困难。Halo 2.x 引入了基于 Spring PF4J 的插件体系，将主题、附件存储器、第三方登录、搜索引擎乃至后台菜单完全下放到插件层。核心系统专注于提供底层的安全审计、数据持久化抽象与响应式 RESTful API，极大地提升了二次开发与生态演进的自由度。

数据库抽象与底层运行环境要求

Halo 2.x 官方原生推荐使用 PostgreSQL 或 MySQL 8.0 作为生产级持久化数据库，彻底淘汰了以往简易但并发脆弱的嵌入式 H2 引擎。由于底层运行于 OpenJDK 环境，其对内存的占用基线天然高于轻量级 PHP 或 Go 编写的博客程序（通常需要分配至少 1GB 以上的空闲内存以应对 JVM 垃圾回收）。因此，合理规划容器内存配额是避免遭遇 OOM 杀进程的关键。

Halo 与传统开源博客系统横向对比选型

在立项选择内容管理系统时，需客观对比 Halo 与其他主流建站方案的技术优劣：

基于 Docker Compose 的生产部署标准流程

采用容器化技术部署 Halo 能够保证运行环境与宿主机环境的完全隔离，便于未来整站无缝平迁：

1. 规划目录层级与文件系统权限： 在宿主机规划专用的挂载目录（如 /opt/halo），下设 data 与 db 子目录。由于容器内默认以特定非 root 用户运行应用，必须执行 chown -R 1001:1001 /opt/halo/data 赋予正确的用户读写权限，避免出现日志或附件无法持久化的问题。
2. 编写 docker-compose.yaml 编排清单： 在部署目录中定义 Halo 核心应用与 PostgreSQL 15 数据库服务。配置互联专用 bridge 网桥，确保数据库仅对 Halo 容器暴露内部端口，禁止将 PostgreSQL 的 5432 端口映射到宿主机公网。
3. 反向代理配置与 WebSocket 协议透传： 使用 Nginx 或 Caddy 代理宿主机映射的 Halo 端口（如 8090）。在 Nginx 配置中必须添加 proxy_set_header Upgrade $http_upgrade; 以及 proxy_set_header Connection "upgrade"; 指令，否则后台实时通知与部分插件的 WebSocket 长连接将无法正常握手。
4. 初始化控制台与全站冷备脚本部署： 访问前台地址完成超级管理员初始化配置。随后在宿主机配置定时任务，使用 pg_dump 对数据库进行逻辑备份，结合 tar 归档 data 目录，实现数据与附件的双重异地备份。

插件兼容与版本升级避坑排障清单

在长期的博客运维与版本迭代过程中，需建立严谨的变更操作纪律：

• 跨大版本升级前的数据冷备要求： Halo 2.x 各次要版本之间若涉及数据库表结构变更，升级前务必先执行数据库整库备份。绝对不可直接修改 docker-compose.yaml 中的镜像标签直接 docker compose pull 盲目重启。
• 插件与核心版本的兼容性约束： 安装第三方插件时，需在 Halo 应用市场仔细审查该插件支持的最低与最高核心版本号。安装未经充分测试的过时插件可能导致后台白屏或应用启动陷入崩溃循环。
• 反代场景下外部访问链接与 HTTPS 异常： 若在反代后发现后台资源加载出现 Mixed Content（混合内容警告）或重定向至 HTTP，需在 Halo 的 halo.external-url 参数中显式配置完整的 HTTPS 外部访问域名。
• 容器时区不匹配与日志时间偏差： 默认镜像可能采用 UTC 时区，导致发布的文章时间戳或系统日志时间与本地存在 8 小时时差。需在容器环境变量中显式挂载宿主机 /etc/localtime:/etc/localtime:ro 或声明 TZ=Asia/Shanghai。